Reference

Reference for the YTMusic class.

class ytmusicapi.YTMusic(auth='')

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='')

Create a new instance to interact with YouTube Music.

Parameters:auth – Optional. Provide authentication credentials to manage your library. Should be an adjusted version of headers_auth.json.example in the project root. Default: A default header is used without authentication.

Setup

See also the Setup page

classmethod YTMusic.setup()

Requests browser headers from the user and stores a configuration JSON file in the correct format in the current directory

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'
    }
]

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',
    '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 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