Reference¶
Reference for the YTMusic class.
-
class
ytmusicapi.
YTMusic
(auth: str = None, user: str = 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: str = None, user: str = 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. - user – Optional. Specify a user ID string to use in requests. This is needed if you want to send requests on behalf of a brand account. Otherwise the default account is used. You can retrieve the user ID by going to https://myaccount.google.com and selecting your brand account. The user ID will be in the URL: https://myaccount.google.com/b/user_id/
- 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¶
See also the Setup page
-
classmethod
YTMusic.
setup
(filepath: str = None, headers_raw: str = 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.
- headers_raw – Optional request headers copied from browser. Otherwise requested from terminal
Returns: configuration headers string
Search¶
-
YTMusic.
search
(query: str, filter: str = None) → List[Dict[KT, VT]]¶ Search YouTube music Returns up to 20 results within the provided category.
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", "title": "Wonderwall (Remastered)", "artists": [ { "name": "Oasis", "id": "UCmMUZbaYdNH0bEd1PAlAqsA" } ], "album": { "name": "(What's The Story) Morning Glory? (Remastered)", "id": "MPREb_9nqEki4ZDpp" }, "duration": "4:19", "thumbnails": [...], "resultType": "song" } ]
Browsing¶
-
YTMusic.
get_artist
(channelId: str) → Dict[KT, VT]¶ 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()
. 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": "1838795605", "thumbnails": [...], "songs": { "browseId": "VLPLMpM3Z0118S42R1npOhcjoakLIv1aqnS1", "results": [ { "videoId": "ZrOKjDZOtkA", "title": "Wonderwall (Remastered)", "thumbnails": [...], "artist": "Oasis", "album": "(What's The Story) Morning Glory? (Remastered)" } ] }, "albums": { "results": [ { "title": "Familiar To Millions", "thumbnails": [...], "year": "2018", "browseId": "MPREb_AYetWMZunqA" } ], "browseId": "UCmMUZbaYdNH0bEd1PAlAqsA", "params": "6gPTAUNwc0JDbndLYlFBQV..." }, "singles": { "results": [ { "title": "Stand By Me (Mustique Demo)", "thumbnails": [...], "year": "2016", "browseId": "MPREb_7MPKLhibN5G" } ], "browseId": "UCmMUZbaYdNH0bEd1PAlAqsA", "params": "6gPTAUNwc0JDbndLYlFBQV..." }, "videos": { "results": [ { "title": "Wonderwall", "thumbnails": [...], "views": "358M", "videoId": "bx1Bh8ZvH84", "playlistId": "PLMpM3Z0118S5xuNckw1HUcj1D021AnMEB" } ], "browseId": "VLPLMpM3Z0118S5xuNckw1HUcj1D021AnMEB" } }
-
YTMusic.
get_artist_albums
(channelId: str, params: str) → List[Dict[KT, VT]]¶ 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)", "thumbnails": [...], "type": "EP", "year": "2020" }
-
YTMusic.
get_album
(browseId: str) → Dict[KT, VT]¶ 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:
{ "title": "Seven", "trackCount": "7", "durationMs": "1439579", "playlistId": "OLAK5uy_kGnhwT08mQMGw8fArBowdtlew3DpgUt9c", "releaseDate": { "year": 2016, "month": 10, "day": 28 }, "description": "Seven is ...", "thumbnails": [...], "artist": [ { "name": "Martin Garrix", "id": "UCqJnSdHjKtfsrHi9aI-9d3g" } ], "tracks": [ { "index": "1", "title": "WIEE (feat. Mesto)", "artists": "Martin Garrix", "videoId": "8xMNeXI9wxI", "lengthMs": "203406", "likeStatus": "INDIFFERENT" } ] }
Library¶
-
YTMusic.
get_library_playlists
(limit: int = 25) → List[Dict[KT, VT]]¶ Retrieves the playlists in the user’s library.
Parameters: limit – Number of playlists to retrieve Returns: List of owned playlists. Each item is in the following format:
{ 'playlistId': 'PLQwVIlKxHM6rz0fDJVv_0UlXGEWf-bFys', 'title': 'Playlist title', 'thumbnails: [...], 'count': 5 }
-
YTMusic.
get_library_songs
(limit: int = 25) → List[Dict[KT, VT]]¶ Gets the songs in the user’s library (liked videos are not included). To get liked songs and videos, use
get_liked_songs()
Parameters: limit – Number of songs to retrieve Returns: List of songs. . Same format as get_playlist()
-
YTMusic.
get_library_artists
(limit: int = 25) → List[Dict[KT, VT]]¶ Gets the artists of the songs in the user’s library.
Parameters: limit – Number of artists to return Returns: List of artists. Each item is in the following format:
{ "browseId": "UCxEqaQWosMHaTih-tgzDqug", "artist": "WildVibes", "subscribers": "2.91K", "thumbnails": [...] }
-
YTMusic.
get_library_albums
(limit: int = 25) → List[Dict[KT, VT]]¶ Gets the albums in the user’s library.
Parameters: limit – Number of albums to return Returns: List of albums
-
YTMusic.
get_liked_songs
(limit: int = 100) → Dict[KT, VT]¶ Gets playlist items for the ‘Liked Songs’ playlist
Parameters: limit – How many items to return. Default: 100 Returns: List of playlistItem dictionaries. See get_playlist()
-
YTMusic.
get_history
() → List[Dict[KT, VT]]¶ Gets your play history in reverse chronological order
Returns: List of playlistItems, see get_playlist()
The additional property ‘played’ indicates when the playlistItem was played
-
YTMusic.
rate_song
(videoId: str, rating: str = 'INDIFFERENT') → Dict[KT, VT]¶ 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
Returns: Full response
-
YTMusic.
rate_playlist
(playlistId: str, rating: str = 'INDIFFERENT') → Dict[KT, VT]¶ Rates a playlist/album (“Add to library”/”Remove from library” interactions on YouTube Music) You can also dislike a playlist/album, which has an effect on your recommendations
Parameters: - playlistId – Playlist id
- rating –
One of ‘LIKE’, ‘DISLIKE’, ‘INDIFFERENT’
’INDIFFERENT’ removes the playlist/album from the library
Returns: Full response
-
YTMusic.
subscribe_artists
(channelIds: List[str]) → Dict[KT, VT]¶ Subscribe to artists. Adds the artists to your library
Parameters: channelIds – Artist channel ids Returns: Full response
-
YTMusic.
unsubscribe_artists
(channelIds: List[str]) → Dict[KT, VT]¶ Unsubscribe from artists. Removes the artists from your library
Parameters: channelIds – Artist channel ids Returns: Full response
Playlists¶
-
YTMusic.
get_playlist
(playlistId: str, limit: int = 100) → Dict[KT, VT]¶ Returns a list of playlist items
Parameters: - playlistId – Playlist id
- limit – How many songs to return. Default: 100
Returns: List of playlistItem dictionaries
Each item is in the following format:
{ "id": "PLQwVIlKxHM6qv-o99iX9R85og7IzF9YS_", "privacy": "PUBLIC", "title": "New EDM This Week 03/13/2020", "thumbnails": [...] "description": "Weekly r/EDM new release roundup. Created with github.com/sigma67/spotifyplaylist_to_gmusic", "author": "sigmatics", "year": "2020", "duration": "6+ hours", "trackCount": 237, "tracks": [ { "videoId": "bjGppZKiuFE", "title": "Lost", "artists": [ { "name": "Guest Who", "id": "UCkgCRdnnqWnUeIH7EIc3dBg" }, { "name": "Kate Wild", "id": "UCwR2l3JfJbvB6aq0RnnJfWg" } ], "album": { "name": "Lost", "id": "MPREb_PxmzvDuqOnC" }, "duration": "2:58", "likeStatus": "INDIFFERENT", "thumbnails": [...] } ] }
The setVideoId is the unique id of this playlist item and needed for moving/removing playlist items
-
YTMusic.
create_playlist
(title: str, description: str, privacy_status: str = 'PRIVATE', video_ids: List[T] = None, source_playlist: str = None) → Union[str, Dict[KT, VT]]¶ 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’
- video_ids – IDs of songs to create the playlist with
- source_playlist – Another playlist whose songs should be added to the new playlist
Returns: ID of the YouTube playlist or full response if there was an error
-
YTMusic.
edit_playlist
(playlistId: str, title: str = None, description: str = None, privacyStatus: str = None, moveItem: Tuple[str, str] = None, addPlaylistId: str = None) → Union[str, Dict[KT, VT]]¶ Edit title, description or privacyStatus of a playlist. You may also move an item within a playlist or append another playlist to this 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
- moveItem – Optional. Move one item before another. Items are specified by setVideoId, see
get_playlist()
- addPlaylistId – Optional. Id of another playlist to add to this playlist
Returns: Status String or full response
-
YTMusic.
delete_playlist
(playlistId: str) → Union[str, Dict[KT, VT]]¶ Delete a playlist.
Parameters: playlistId – Playlist id Returns: Status String or full response
-
YTMusic.
add_playlist_items
(playlistId: str, videoIds: List[str]) → Union[str, Dict[KT, VT]]¶ 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: str, videos: List[Dict[KT, VT]]) → Union[str, Dict[KT, VT]]¶ Remove songs from an existing playlist
Parameters: - playlistId – Playlist id
- videos – List of PlaylistItems, see
get_playlist()
. Must contain videoId and setVideoId
Returns: Status String or full response
Uploads¶
-
YTMusic.
get_library_upload_songs
(limit: int = 25) → List[Dict[KT, VT]]¶ 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", "likeStatus": "LIKE", "thumbnails": [...] }
-
YTMusic.
get_library_upload_artists
(limit: int = 25) → List[Dict[KT, VT]]¶ Gets the artists of uploaded songs in the user’s library.
Parameters: limit – Number of artists to return. Default: 25 Returns: List of artists as returned by get_library_artists()
-
YTMusic.
get_library_upload_albums
(limit: int = 25) → List[Dict[KT, VT]]¶ Gets the albums of uploaded songs in the user’s library.
Parameters: limit – Number of albums to return. Default: 25 Returns: List of albums as returned by get_library_albums()
-
YTMusic.
get_library_upload_artist
(browseId: str) → List[Dict[KT, VT]]¶ Returns a list of uploaded tracks for the artist.
Parameters: browseId – Browse id of the upload artist, i.e. from get_library_upload_songs()
Returns: List of uploaded songs. Example List:
[ { "entityId": "t_po_CICr2crg7OWpchDKwoakAQ", "videoId": "Dtffhy8WJgw", "title": "Hold Me (Original Mix)", "artist": [ { "name": "Jakko", "id": "FEmusic_library_privately_owned_artist_detaila_po_CICr2crg7OWpchIFamFra28" } ], "album": null, "likeStatus": "LIKE", "thumbnails": [...] } ]
-
YTMusic.
get_library_upload_album
(browseId: str) → Dict[KT, VT]¶ Get information and tracks of an album associated with uploaded tracks
Parameters: browseId – Browse id of the upload album, i.e. from i.e. from get_library_upload_songs()
Returns: Dictionary with title, description, artist and tracks. Example album:
{ "title": "Hard To Stop - Single", "thumbnails": [...] "year": "2013", "trackCount": 1, "duration": "4 minutes, 2 seconds", "tracks": [ { "entityId": "t_po_CICr2crg7OWpchDN6tnYBw", "videoId": "VBQVcjJM7ak", "title": "Hard To Stop (Vicetone x Ne-Yo x Daft Punk)", "likeStatus": "LIKE" } ] }
-
YTMusic.
upload_song
(filepath: str) → Union[str, requests.models.Response]¶ 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_upload_entity
(entityId: str) → Union[str, Dict[KT, VT]]¶ Deletes a previously uploaded song or album
Parameters: entityId – The entity id of the uploaded song or album, e.g. retrieved from get_library_upload_songs()
Returns: Status String or error