ytmusicapi package

Subpackages

Submodules

ytmusicapi.constants module

ytmusicapi.continuations module

ytmusicapi.continuations.get_continuation_contents(continuation: dict[str, Any], parse_func: collections.abc.Callable[[list[dict[str, Any]]], list[dict[str, Any]]]) → list[dict[str, Any]]
Return type:

list[dict[str, Any]]

ytmusicapi.continuations.get_continuation_params(results: dict[str, Any], ctoken_path: str = '') → str
Return type:

str

ytmusicapi.continuations.get_continuation_string(ctoken: str) → str

Returns the continuation string used in the continuation request

Parameters:

ctoken (str) – the unique continuation token

Return type:

str

ytmusicapi.continuations.get_continuation_token(results: list[dict[str, Any]]) → str | None
Return type:

Optional[str]

ytmusicapi.continuations.get_continuations(results: dict[str, Any], continuation_type: str, limit: int | None, request_func: collections.abc.Callable[[str], dict[str, Any]], parse_func: collections.abc.Callable[[list[dict[str, Any]]], list[dict[str, Any]]], ctoken_path: str = '', additionalParams: str | None = None) → list[dict[str, Any]]
Parameters:

  • results (dict[str, Any]) – result list from request data

  • continuation_type (str) – type of continuation, determines which subkey will be used to navigate the continuation return data

  • limit (Optional[int]) – determines minimum of how many items to retrieve in total. None to retrieve all items until no more continuations are returned

  • request_func (Callable[[str], dict[str, Any]]) – the request func to use to get the continuations

  • parse_func (Callable[[list[dict[str, Any]]], list[dict[str, Any]]]) – the parse func to apply on the returned continuations

  • ctoken_path (str) – rarely used specifier applied to retrieve the ctoken (“next<ctoken_path>ContinuationData”). Default empty string

  • additionalParams (Optional[str]) – Optional additional params to pass to the request func. Default: use get_continuation_params

Return type:

list[dict[str, Any]]

Returns:

list of parsed continuation results

ytmusicapi.continuations.get_continuations_2025(results: dict[str, Any], limit: int | None, request_func: collections.abc.Callable[[dict[str, Any]], dict[str, Any]], parse_func: collections.abc.Callable[[list[dict[str, Any]]], list[dict[str, Any]]]) → list[dict[str, Any]]
Return type:

list[dict[str, Any]]

ytmusicapi.continuations.get_parsed_continuation_items(response: dict[str, Any], parse_func: collections.abc.Callable[[list[dict[str, Any]]], list[dict[str, Any]]], continuation_type: str) → dict[str, Any]
Return type:

dict[str, Any]

ytmusicapi.continuations.get_reloadable_continuation_params(results: dict[str, Any]) → str
Return type:

str

ytmusicapi.continuations.get_reloadable_continuations(results: dict[str, Any], continuation_type: str, limit: int | None, request_func: collections.abc.Callable[[str], dict[str, Any]], parse_func: collections.abc.Callable[[list[dict[str, Any]]], list[dict[str, Any]]]) → list[dict[str, Any]]

Reloadable continuations are a special case that only exists on the playlists page (suggestions).

Return type:

list[dict[str, Any]]

ytmusicapi.continuations.get_validated_continuations(results: dict[str, Any], continuation_type: str, limit: int, per_page: int, request_func: collections.abc.Callable[[str], dict[str, Any]], parse_func: collections.abc.Callable[[list[dict[str, Any]]], list[dict[str, Any]]], ctoken_path: str = '') → list[dict[str, Any]]
Return type:

list[dict[str, Any]]

ytmusicapi.continuations.resend_request_until_parsed_response_is_valid(request_func: collections.abc.Callable[[str], dict[str, Any]], request_additional_params: str, parse_func: collections.abc.Callable[[dict[str, Any]], dict[str, Any]], validate_func: collections.abc.Callable[[dict[str, Any]], bool], max_retries: int) → dict[str, Any]
Return type:

dict[str, Any]

ytmusicapi.continuations.validate_response(response: dict[str, Any], per_page: int, limit: int, current_count: int) → bool
Return type:

bool

ytmusicapi.enums module

class ytmusicapi.enums.ResponseStatus(value)

Bases: str, Enum

An enumeration.

SUCCEEDED = 'STATUS_SUCCEEDED'

ytmusicapi.exceptions module

custom exception classes for ytmusicapi

exception ytmusicapi.exceptions.YTMusicError

Bases: Exception

base error class

shall only be raised if none of the subclasses below are fitting

exception ytmusicapi.exceptions.YTMusicServerError

Bases: YTMusicError

error caused by the YouTube Music backend

exception ytmusicapi.exceptions.YTMusicUserError

Bases: YTMusicError

error caused by invalid usage of ytmusicapi

ytmusicapi.helpers module

ytmusicapi.helpers.get_authorization(auth: str) → str

Returns SAPISIDHASH value based on headers and current time

Parameters:

auth (str) – SAPISID and Origin value from headers concatenated with space

Return type:

str

ytmusicapi.helpers.get_visitor_id(request_func: collections.abc.Callable[[str], requests.models.Response]) → dict[str, str]
Return type:

dict[str, str]

ytmusicapi.helpers.initialize_context() → dict[str, Any]
Return type:

dict[str, Any]

ytmusicapi.helpers.initialize_headers() → requests.structures.CaseInsensitiveDict[str]
Return type:

CaseInsensitiveDict[str]

Return type:

str

ytmusicapi.helpers.sum_total_duration(item: dict[str, Any]) → int
Return type:

int

ytmusicapi.helpers.to_int(string: str) → int

Attempts to cast a string to an integer using locale or Python int cast

Parameters:

string (str) – string that can be cast to an integer

Return type:

int

:return Integer if string is a valid integer

:raise ValueError if string is not a valid integer

ytmusicapi.navigation module

commonly used navigation paths

ytmusicapi.navigation.find_object_by_key(object_list: list[dict[str, Any]], key: str, nested: str | None = None, is_key: bool = False) → dict[str, Any] | None
Return type:

Optional[dict[str, Any]]

ytmusicapi.navigation.find_objects_by_key(object_list: list[dict[str, Any]], key: str, nested: str | None = None) → list[dict[str, Any]]
Return type:

list[dict[str, Any]]

ytmusicapi.navigation.nav(root: dict[str, Any] | None, items: list[Any], none_if_absent: bool = False) → Any | None

Access a nested object in root by item sequence.

Return type:

Optional[Any]

ytmusicapi.setup module

ytmusicapi.setup.main() → ytmusicapi.auth.oauth.token.RefreshingToken | str
Return type:

RefreshingToken | str

ytmusicapi.setup.parse_args(args: list[str]) → argparse.Namespace
Return type:

Namespace

ytmusicapi.setup.setup(filepath: str | None = None, headers_raw: str | None = None) → str

Requests browser headers from the user via command line and returns a string that can be passed to YTMusic()

Parameters:

  • filepath (Optional[str]) – Optional filepath to store headers to.

  • headers_raw (Optional[str]) – Optional request headers copied from browser. Otherwise requested from terminal

Return type:

str

Returns:

configuration headers string

ytmusicapi.setup.setup_oauth(client_id: str, client_secret: str, filepath: str | None = None, session: requests.sessions.Session | None = None, proxies: dict[str, str] | None = None, open_browser: bool = False) → ytmusicapi.auth.oauth.token.RefreshingToken

Starts oauth flow from the terminal and returns a string that can be passed to YTMusic()

Parameters:

  • client_id (str) – Optional. Used to specify the client_id oauth should use for authentication flow. If provided, client_secret MUST also be passed or both will be ignored.

  • client_secret (str) – Optional. Same as client_id but for the oauth client secret.

  • session (Optional[Session]) – Session to use for authentication

  • proxies (Optional[dict[str, str]]) – Proxies to use for authentication

  • filepath (Optional[str]) – Optional filepath to store headers to.

  • open_browser (bool) – If True, open the default browser with the setup link

Return type:

RefreshingToken

Returns:

configuration headers string

ytmusicapi.type_alias module

ytmusicapi.ytmusic module

class ytmusicapi.ytmusic.YTMusic(auth: str | dict[str, Any] | None = None, user: str | None = None, requests_session: requests.sessions.Session | None = None, proxies: dict[str, str] | None = None, language: str = 'en', location: str = '', oauth_credentials: ytmusicapi.auth.oauth.credentials.OAuthCredentials | None = None)

Bases: YTMusicBase, BrowsingMixin, SearchMixin, WatchMixin, ChartsMixin, ExploreMixin, LibraryMixin, PlaylistsMixin, PodcastsMixin, UploadsMixin

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.

class ytmusicapi.ytmusic.YTMusicBase(auth: str | dict[str, Any] | None = None, user: str | None = None, requests_session: requests.sessions.Session | None = None, proxies: dict[str, str] | None = None, language: str = 'en', location: str = '', oauth_credentials: ytmusicapi.auth.oauth.credentials.OAuthCredentials | None = None)

Bases: object

as_mobile() → collections.abc.Iterator[None]
Return type:

Iterator[None]

Not thread-safe!

Temporarily changes the context to enable different results from the API, meant for the Android mobile-app. All calls inside the with-statement with emulate mobile behavior.

This context-manager has no enter_result, as it operates in-place and only temporarily alters the underlying YTMusic-object.

Example:

with yt.as_mobile():
    yt._send_request(...)  # results as mobile-app

yt._send_request(...)  # back to normal, like web-app
property base_headers: CaseInsensitiveDict[str]
property headers: CaseInsensitiveDict[str]
proxies: Optional[dict[str, str]]

params for session modification

Module contents

class ytmusicapi.LikeStatus(value)

Bases: str, Enum

An enumeration.

DISLIKE = 'DISLIKE'
INDIFFERENT = 'INDIFFERENT'
LIKE = 'LIKE'
class ytmusicapi.OAuthCredentials(client_id: str, client_secret: str, session: requests.sessions.Session | None = None, proxies: dict[str, str] | None = None)

Bases: Credentials

Class for handling OAuth credential retrieval and refreshing.

client_id: str
client_secret: str
get_code() → ytmusicapi.auth.oauth.models.AuthCodeDict

Method for obtaining a new user auth code. First step of token creation.

Return type:

AuthCodeDict

refresh_token(refresh_token: str) → ytmusicapi.auth.oauth.models.BaseTokenDict

Method for requesting a new access token for a given refresh_token. Token must have been created by the same OAuth client.

Parameters:

refresh_token (str) – Corresponding refresh_token for a matching access_token. Obtained via

Return type:

BaseTokenDict

token_from_code(device_code: str) → ytmusicapi.auth.oauth.models.RefreshableTokenDict

Method for verifying user auth code and conversion into a FullTokenDict.

Return type:

RefreshableTokenDict

class ytmusicapi.YTMusic(auth: str | dict[str, Any] | None = None, user: str | None = None, requests_session: requests.sessions.Session | None = None, proxies: dict[str, str] | None = None, language: str = 'en', location: str = '', oauth_credentials: ytmusicapi.auth.oauth.credentials.OAuthCredentials | None = None)

Bases: YTMusicBase, BrowsingMixin, SearchMixin, WatchMixin, ChartsMixin, ExploreMixin, LibraryMixin, PlaylistsMixin, PodcastsMixin, UploadsMixin

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.

ytmusicapi.setup(filepath: str | None = None, headers_raw: str | None = None) → str

Requests browser headers from the user via command line and returns a string that can be passed to YTMusic()

Parameters:

  • filepath (Optional[str]) – Optional filepath to store headers to.

  • headers_raw (Optional[str]) – Optional request headers copied from browser. Otherwise requested from terminal

Return type:

str

Returns:

configuration headers string

ytmusicapi.setup_oauth(client_id: str, client_secret: str, filepath: str | None = None, session: requests.sessions.Session | None = None, proxies: dict[str, str] | None = None, open_browser: bool = False) → ytmusicapi.auth.oauth.token.RefreshingToken

Starts oauth flow from the terminal and returns a string that can be passed to YTMusic()

Parameters:

  • client_id (str) – Optional. Used to specify the client_id oauth should use for authentication flow. If provided, client_secret MUST also be passed or both will be ignored.

  • client_secret (str) – Optional. Same as client_id but for the oauth client secret.

  • session (Optional[Session]) – Session to use for authentication

  • proxies (Optional[dict[str, str]]) – Proxies to use for authentication

  • filepath (Optional[str]) – Optional filepath to store headers to.

  • open_browser (bool) – If True, open the default browser with the setup link

Return type:

RefreshingToken

Returns:

configuration headers string