Reference¶
Reference for the YTMusic class.
-
class
ytmusicapi.
YTMusic
(auth=None)¶ Allows automated interactions with YouTube Music by emulating the YouTube web client’s requests. Permits both authenticated and non-authenticated requests. Authentication header data must be provided on initialization.
-
YTMusic.
__init__
(auth=None)¶ Create a new instance to interact with YouTube Music.
Parameters: auth – Optional. Provide a string or path to file. Authentication credentials are needed to manage your library. Should be an adjusted version of headers_auth.json.example in the project root. See setup()
for how to fill in the correct credentials. Default: A default header is used without authentication.
Setup¶
See also the Setup page
-
classmethod
YTMusic.
setup
(filepath=None)¶ Requests browser headers from the user via command line and returns a string that can be passed to YTMusic()
Parameters: filepath – Optional filepath to store headers to. Returns: configuration headers string
Search¶
-
YTMusic.
search
(query, filter=None)¶ Search YouTube music Returns up to 20 results within the provided category. By default only songs (audio-only) are returned
Parameters: - query – Query string, i.e. ‘Oasis Wonderwall’
- filter – Filter for item types. Allowed values: ‘songs’, ‘videos’, ‘albums’, ‘artists’, ‘playlists’. Default: Default search, including all types of items.
Returns: List of results depending on filter. resultType specifies the type of item (important for default search). albums, artists and playlists additionally contain a browseId, corresponding to albumId, channelId and playlistId (browseId=’VL’+playlistId)
Example list:
[ { 'videoId': 'ZrOKjDZOtkA', 'artist': 'Oasis', 'title': 'Wonderwall (Remastered)', 'resultType': 'song' }, { 'videoId': 'Gvfgut8nAgw', 'artist': 'Oasis', 'title': 'Wonderwall', 'resultType': 'song' } ]
Browsing¶
-
YTMusic.
get_artist
(channelId)¶ Get information about an artist and their top releases (songs, albums, singles and videos). The top lists contain pointers for getting the full list of releases. For songs/videos, pass the browseId to
get_playlist_items()
. For albums/singles, pass browseId and params toget_artist_albums()
.Parameters: channelId – channel id of the artist Returns: Dictionary with requested information. Example: {
”name”: “Oasis”, “description”: “Oasis were …”, “views”: “1,838,795,605”, “songs”: {”browseId”: “VLPLMpM3Z0118S42R1npOhcjoakLIv1aqnS1”, “results”: [- {
- “videoId”: “ZrOKjDZOtkA”, “title”: “Wonderwall (Remastered)”, “artist”: “Oasis”, “album”: “(What’s The Story) Morning Glory? (Remastered)”
}
]
}, “albums”: {
- ”results”: [
- {
- “title”: “Familiar To Millions”, “year”: “2018”, “browseId”: “MPREb_AYetWMZunqA”
}
], “browseId”: “UCmMUZbaYdNH0bEd1PAlAqsA”
}, “singles”: {
- ”results”: [
- {
- “title”: “Stand By Me (Mustique Demo)”, “year”: “2016”, “browseId”: “MPREb_7MPKLhibN5G”
}
], “browseId”: “UCmMUZbaYdNH0bEd1PAlAqsA”
}, “videos”: {
- ”results”: [
- {
- “title”: “Wonderwall”, “views”: “358M”, “videoId”: “bx1Bh8ZvH84”, “playlistId”: “PLMpM3Z0118S5xuNckw1HUcj1D021AnMEB”
}
], “browseId”: “VLPLMpM3Z0118S5xuNckw1HUcj1D021AnMEB”
}
}
-
YTMusic.
get_artist_albums
(channelId, params)¶ Get the full list of an artist’s albums or singles
Parameters: - channelId – channel Id of the artist
- params – params obtained by
get_artist()
Returns: List of albums or singles
Example:
{
”browseId”: “MPREb_0rtvKhqeCY0”, “artist”: “Armin van Buuren”, “title”: “This I Vow (feat. Mila Josef)”, “type”: “EP”, “year”: “2020”
}
-
YTMusic.
get_album
(browseId)¶ Get information and tracks of an album
Parameters: browseId – browseId of the album, for example returned by search()
Returns: Dictionary with title, description, artist and tracks. Each track is in the following format:
{ "index": "1", "title": "WIEE (feat. Mesto)", "artists": "Martin Garrix", "videoId": "8xMNeXI9wxI", "lengthMs": "203406" }
Library¶
-
YTMusic.
get_liked_songs
(limit=1000)¶ Gets playlist items for the ‘Liked Songs’ playlist
Parameters: limit – How many items to return. Default: 1000 Returns: List of playlistItem dictionaries. See get_playlist_items()
-
YTMusic.
get_history
()¶ Gets your play history in reverse chronological order
Returns: List of playlistItems, see get_playlist_items()
The additional property ‘played’ indicates when the playlistItem was played
-
YTMusic.
rate_song
(videoId, rating='INDIFFERENT')¶ Rates a song (“thumbs up”/”thumbs down” interactions on YouTube Music)
Parameters: - videoId – Video id
- rating –
One of ‘LIKE’, ‘DISLIKE’, ‘INDIFFERENT’
’INDIFFERENT’ removes the previous rating and assigns no rating
Playlists¶
-
YTMusic.
get_playlists
()¶ Retrieves the content of the ‘Library’ page
Returns: List of owned playlists. Each item is in the following format:
{ 'playlistId': 'PLQwVIlKxHM6rz0fDJVv_0UlXGEWf-bFys', 'title': 'Playlist title' }
-
YTMusic.
get_playlist_items
(playlistId, limit=1000)¶ Returns a list of playlist items
Parameters: - playlistId – Playlist id
- limit – How many songs to return. Default: 1000
Returns: List of playlistItem dictionaries
Each item is in the following format:
{ 'videoId': 'PLQwVIlKxHM6rz0fDJVv_0UlXGEWf-bFys', 'artist': 'Artist', 'title': 'Song Title', 'album': None, 'setVideoId': '56B44F6D10557CC6' }
The setVideoId is the unique id of this playlist item and needed for moving/removing playlist items
-
YTMusic.
create_playlist
(title, description, privacy_status='PRIVATE')¶ Creates a new empty playlist and returns its id.
Parameters: - title – Playlist title
- description – Playlist description
- privacy_status – Playlists can be ‘PUBLIC’, ‘PRIVATE’, or ‘UNLISTED’. Default: ‘PRIVATE’
Returns: ID of the YouTube playlist
-
YTMusic.
edit_playlist
(playlistId, title=None, description=None, privacyStatus=None)¶ Edit title, description or privacyStatus of a playlist.
Parameters: - playlistId – Playlist id
- title – Optional. New title for the playlist
- description – Optional. New description for the playlist
- privacyStatus – Optional. New privacy status for the playlist
Returns: Status String or full response
-
YTMusic.
delete_playlist
(playlistId)¶ Delete a playlist.
Parameters: playlistId – Playlist id Returns: Status String or full response
-
YTMusic.
add_playlist_items
(playlistId, videoIds)¶ Add songs to an existing playlist
Parameters: - playlistId – Playlist id
- videoIds – List of Video ids
Returns: Status String or full response
-
YTMusic.
remove_playlist_items
(playlistId, videos)¶ Remove songs from an existing playlist
Parameters: - playlistId – Playlist id
- videos – List of PlaylistItems, see
get_playlist_items()
. Must contain videoId and setVideoId
Returns: Status String or full response
Uploads¶
-
YTMusic.
get_uploaded_songs
(limit=25)¶ Returns a list of uploaded songs
Parameters: limit – How many songs to return. Default: 25 Returns: List of uploaded songs. Each item is in the following format:
{ "entityId": "t_po_CICr2crg7OWpchDpjPjrBA", "videoId": "Uise6RPKoek", "artist": "Coldplay", "title": "A Sky Full Of Stars", "album": "Ghost Stories" }
-
YTMusic.
upload_song
(filepath)¶ Uploads a song to YouTube Music
Parameters: filepath – Path to the music file (mp3, m4a, wma, flac or ogg) Returns: Status String or full response
-
YTMusic.
delete_uploaded_song
(uploaded_song)¶ Deletes a previously uploaded song
Parameters: uploaded_song – The uploaded song to delete, e.g. retrieved from get_uploaded_songs()
Returns: Status String or error