~.youtube

YouTube Audio Source

YouTubeAudioSource

YouTubeAudioSource(
    url: str,
    *,
    bitrate: str | None = None,
    channels: int | None = None,
    name: str | None = None,
    volume: float | str | None = None
)

Bases: AudioSource

YouTube audio source implementation.

Create a YouTube audio source.

PARAMETER	DESCRIPTION
url	The YouTube URL of the audio source. TYPE: str
bitrate	If provided, the bitrate in which to play this source back at. TYPE: str | None DEFAULT: None
channels	If provided, the amount of channels this source plays with. TYPE: int | None DEFAULT: None
name	If provided, an internal name used for display purposes. TYPE: str | None DEFAULT: None
volume	If provided, overrides the player's set/default volume. Can be scaled (0.5, 1.0, 2.0, etc.) or dB-based (-3dB, etc.). TYPE: float | str | None DEFAULT: None

Important

This source depends on YouTube's undocumented internal APIs via yt-dlp. As a result, it is best-effort and may break without notice if YouTube changes its internal behavior. Functionality may require updating the pinned yt-dlp version to restore compatibility.

Basic video metadata is extracted on construction of this source. Using resolve_metadata will ensure this metadata is retrieved before using the metadata property. Enhanced video metadata, like media URLs, is extracted on request internally by the player (to ensure non-expired timestamps and nonces). Using resolve_media does this as well.

RAISES	DESCRIPTION
TypeError	If url is not str. If bitrate is provided and not str. If channels is provided and not int. If name is provided and not str. If volume is provided and not float or str.
ValueError	If url is empty. If bitrate is provided, and is not between 6k and 510k. If channels is provided and not 1 or 2. If name is provided and is empty. If volume is provided and is either a float and is not positive or a str and does not end with dB, contain a number, or (if provided) doesn't begin with - or +.

duration property

duration: float | None

The duration of the media source URL, if discovered - Use resolve_metadata or resolve_media to attain if not discovered.

metadata property

metadata: dict[str, Any]

The metadata of the YouTube media provided, if discovered - Use resolve_metadata or resolve_media to attain if not discovered.

url_media property

url_media: str | None

The media source URL that the YouTube URL points to, if discovered - Use resolve_media to attain if not discovered.

url_youtube property

url_youtube: str

The URL to the audio source.

bitrate property

bitrate: str | None

If provided, the bitrate in which this source is played back at.

channels property

channels: int | None

If provided, the amount of channels this source plays with.

name property

name: str | None

If provided, the name assigned to this source for display purposes.

volume property

volume: float | str | None

If provided, the overriding volume for this source.

resolve_media async

resolve_media(force: bool = False) -> str

Resolve the video's media URL and enhanced metadata.

PARAMETER	DESCRIPTION
force	If already previously resolved, re-resolve and overwrite the metadata. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
str	The internal video media URL used for playback.

resolve_metadata async

resolve_metadata() -> dict[str, Any]

Resolve the video's basic metadata.

RETURNS	DESCRIPTION
dict[str, Any]	The metadata of this video, once discovered.