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¶

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 to get_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",
        "params": "6gPTAUNwc0JDbndLYlFBQV..."
    },
    "singles": {
        "results": [
            {
                "title": "Stand By Me (Mustique Demo)",
                "year": "2016",
                "browseId": "MPREb_7MPKLhibN5G"
            }
        ],
        "browseId": "UCmMUZbaYdNH0bEd1PAlAqsA",
        "params": "6gPTAUNwc0JDbndLYlFBQV..."
    },
    "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',
    'count': 5
}

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

Parameters:	filepath – Optional filepath to store headers to.
Returns:	configuration headers string