API¶

YouTube Object¶

class pytubefix.YouTube(url: str, client: str = 'ANDROID_VR', on_progress_callback: Callable[[Any, bytes, int], None] | None = None, on_complete_callback: Callable[[Any, str | None], None] | None = None, proxies: Dict[str, str] | None = None, use_oauth: bool = False, allow_oauth_cache: bool = True, token_file: str | None = None, oauth_verifier: Callable[[str, str], None] | None = None, use_po_token: bool | None = False, po_token_verifier: Callable[[None], Tuple[str, str]] | None = None)[source]¶

Core developer interface for pytubefix.

age_check()[source]¶

If the video has any age restrictions, you must confirm that you wish to continue.

Originally the WEB client was used, but with the implementation of PoToken we switched to MWEB.

property author: str¶: Get the video author. :rtype: str

property caption_tracks: List[Caption]¶

Get a list of Caption.

Return type:: List[Caption]

property captions: CaptionQuery¶

Interface to query caption tracks.

Return type:: CaptionQuery.

property channel_id: str¶

Get the video poster’s channel id.

Return type:: str

property channel_url: str¶

Construct the channel url for the video’s poster from the channel id.

Return type:: str

property chapters: List[Chapter]¶

Get a list of Chapter.

Return type:: List[Chapter]

check_availability()[source]¶

Check whether the video is available.

Raises different exceptions based on why the video is unavailable, otherwise does nothing.

property description: str¶

Get the video description.

Return type:: str

property fmt_streams¶

Returns a list of streams if they have been initialized.

If the streams have not been initialized, finds all relevant streams and initializes them.

static from_id(video_id: str) → YouTube[source]¶

Construct a YouTube object from a video id.

Parameters:: video_id (str) – The video id of the YouTube video.
Return type:: YouTube

property key_moments: List[KeyMoment]¶

Get a list of KeyMoment.

Return type:: List[KeyMoment]

property keywords: List[str]¶

Get the video keywords.

Return type:: List[str]

property length: int¶

Get the video length in seconds.

Return type:: int

property likes¶

Get the video likes

Return type:: str

property metadata: YouTubeMetadata | None¶

Get the metadata for the video.

Return type:: YouTubeMetadata

property pot: str¶

Retrieves the poToken generated by botGuard.

This poToken only works for WEB-based clients.

property publish_date¶

Get the publish date.

Return type:: datetime

property rating: float¶

Get the video average rating.

Return type:: float

register_on_complete_callback(func: Callable[[Any, str | None], None])[source]¶

Register a download complete callback function post initialization.

Parameters:: func (callable) – A callback function that takes stream and file_path.
Return type:: None

register_on_progress_callback(func: Callable[[Any, bytes, int], None])[source]¶

Register a download progress callback function post initialization.

Parameters:

func (callable) –

A callback function that takes stream, chunk,: and bytes_remaining as parameters.

Return type:

None

property replayed_heatmap: List[Dict[str, float]]¶

Get a list of : Dict<str, float>.

Return type:: List[Dict[str, float]]

property signature_timestamp: dict¶

WEB clients need to be signed with a signature timestamp.

The signature is found inside the player’s base.js.

Return type:: Dict

property streaming_data¶: Return streamingData from video info.

property streams: StreamQuery¶

Interface to query both adaptive (DASH) and progressive streams.

Return type:: StreamQuery.

property thumbnail_url: str¶

Get the thumbnail url image.

Return type:: str

property title: str¶

Get the video title.

Return type:: str

property vid_details¶

Parse the raw vid details and return the parsed result.

The official player sends a request to the next endpoint to obtain some details of the video.

Return type:: Dict[Any, Any]

property vid_info¶

Parse the raw vid info and return the parsed result.

Return type:: Dict[Any, Any]

property views: int¶

Get the number of the times the video has been viewed.

Return type:: int

property visitor_data: str¶: Retrieves the visitorData from the WEB client.

KeyMomentsThumbnail Object¶

KeyMoments Object¶

Playlist Object¶

class pytubefix.contrib.playlist.Playlist(url: str, client: str = 'ANDROID_VR', proxies: Dict[str, str] | None = None, use_oauth: bool = False, allow_oauth_cache: bool = True, token_file: str | None = None, oauth_verifier: Callable[[str, str], None] | None = None, use_po_token: bool | None = False, po_token_verifier: Callable[[None], Tuple[str, str]] | None = None)[source]¶

Load a YouTube playlist with URL

count(value) → integer -- return number of occurrences of value¶

property html¶

Get the playlist page html.

Return type:: str

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

property initial_data¶

Extract the initial data from the playlist page html.

Return type:: dict

property last_updated: date | None¶

Extract the date that the playlist was last updated.

For some playlists, this will be a specific date, which is returned as a datetime object. For other playlists, this is an estimate such as “1 week ago”. Due to the fact that this value is returned as a string, pytube does a best-effort parsing where possible, and returns the raw string where it is not possible.

Returns:: Date of last playlist update where possible, else the string provided
Return type:: datetime.date

property length¶

Extract the number of videos in the playlist.

Returns:: Playlist video count
Return type:: int

property owner¶

Extract the owner of the playlist.

Returns:: Playlist owner name.
Return type:: str

property owner_id¶

Extract the channel_id of the owner of the playlist.

Returns:: Playlist owner’s channel ID.
Return type:: str

property owner_url¶

Create the channel url of the owner of the playlist.

Returns:: Playlist owner’s channel url.
Return type:: str

property playlist_id¶

Get the playlist id.

Return type:: str

property playlist_url¶

Get the base playlist url.

Return type:: str

property sidebar_info¶

Extract the sidebar info from the playlist page html.

Return type:: dict

property title: str | None¶

Extract playlist title

Returns:: playlist title (name)
Return type:: Optional[str]

trimmed(video_id: str) → Iterable[str][source]¶

Retrieve a list of YouTube video URLs trimmed at the given video ID

i.e. if the playlist has video IDs 1,2,3,4 calling trimmed(3) returns [1,2] :type video_id: str

video ID to trim the returned list of playlist URLs at

Return type:: List[str]
Returns:: List of video URLs from the playlist trimmed at the given ID

url_generator()[source]¶

Generator that yields video URLs.

Yields:: Video URLs

property video_urls: DeferredGeneratorList¶

Complete links of all the videos in playlist

Return type:: List[str]
Returns:: List of video URLs

property videos: Iterable[YouTube]¶

Yields YouTube objects of videos in this playlist

Return type:: List[YouTube]
Returns:: List of YouTube

property views¶

Extract view count for playlist.

Returns:: Playlist view count
Return type:: int

property yt_api_key¶

Extract the INNERTUBE_API_KEY from the playlist ytcfg.

Return type:: str

property ytcfg¶

Extract the ytcfg from the playlist page html.

Return type:: dict

Channel Object¶

class pytubefix.contrib.channel.Channel(url: str, client: str = 'ANDROID_VR', proxies: Dict[str, str] | None = None, use_oauth: bool = False, allow_oauth_cache: bool = True, token_file: str | None = None, oauth_verifier: Callable[[str, str], None] | None = None, use_po_token: bool | None = False, po_token_verifier: Callable[[None], Tuple[str, str]] | None = None)[source]¶

property about_html¶

Get the html for the /about page.

Currently unused for any functionality.

Return type:: str

property channel_id¶

Get the ID of the YouTube channel.

This will return the underlying ID, not the vanity URL.

Return type:: str

property channel_name¶

Get the name of the YouTube channel.

Return type:: str

property community_html¶

Get the html for the /community page.

Currently unused for any functionality.

Return type:: str

count(value) → integer -- return number of occurrences of value¶

property description: str¶

Extract the channel description.

Returns:: Channel description
Return type:: str

property featured_channels_html¶

Get the html for the /channels page.

Currently unused for any functionality.

Return type:: str

find_videos_info(data)[source]¶: Recursively search for ‘videos’ in the text content of the JSON.

property home: list¶

Yields YouTube, Playlist and Channel objects from the channel home page.

Returns:: List of YouTube, Playlist and Channel objects.

property html¶

Get the html for the /videos, /shorts or /streams page.

Return type:: str

property html_url¶

Get the html url.

Return type:: str

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

property initial_data¶

Extract the initial data from the playlist page html.

Return type:: dict

property last_updated: str¶

Extract the date of the last uploaded video.

Returns:: Last video uploaded
Return type:: str

property length¶: Extracts the approximate amount of videos from the channel.

property live: Iterable[YouTube]¶

Yields YouTube objects of live in this channel

Return type:: List[YouTube]
Returns:: List of YouTube

property owner¶

Extract the owner of the playlist.

Returns:: Playlist owner name.
Return type:: str

property owner_id¶

Extract the channel_id of the owner of the playlist.

Returns:: Playlist owner’s channel ID.
Return type:: str

property owner_url¶

Create the channel url of the owner of the playlist.

Returns:: Playlist owner’s channel url.
Return type:: str

property playlist_id¶

Get the playlist id.

Return type:: str

property playlist_url¶

Get the base playlist url.

Return type:: str

property playlists: Iterable[Playlist]¶

Yields Playlist objects in this channel

Return type:: List[Playlist]
Returns:: List of Playlist

property playlists_html¶

Get the html for the /playlists page.

Currently unused for any functionality.

Return type:: str

property releases: Iterable[Playlist]¶

Yields Playlist objects in this channel

Return type:: List[Playlist]
Returns:: List of YouTube

property shorts: Iterable[YouTube]¶

Yields YouTube objects of short videos in this channel

Return type:: List[YouTube]
Returns:: List of YouTube

property sidebar_info¶

Extract the sidebar info from the playlist page html.

Return type:: dict

property thumbnail_url: str¶

extract the profile image from the json of the channel home page

Return type:: str
Returns:: a string with the url of the channel’s profile image

property title: str | None¶

Extract playlist title

Returns:: playlist title (name)
Return type:: Optional[str]

trimmed(video_id: str) → Iterable[str]¶

Retrieve a list of YouTube video URLs trimmed at the given video ID

i.e. if the playlist has video IDs 1,2,3,4 calling trimmed(3) returns [1,2] :type video_id: str

video ID to trim the returned list of playlist URLs at

Return type:: List[str]
Returns:: List of video URLs from the playlist trimmed at the given ID

url_generator()[source]¶

Generator that yields video URLs.

Yields:: Video URLs

property vanity_url¶

Get the vanity URL of the YouTube channel.

Returns None if it doesn’t exist.

Return type:: str

property video_urls: DeferredGeneratorList¶

Complete links of all the videos in playlist

Return type:: List[str]
Returns:: List of video URLs

property videos: Iterable[YouTube]¶

Yields YouTube objects of videos in this channel

Return type:: List[YouTube]
Returns:: List of YouTube

property views: int¶

Extract view count for channel.

Returns:: Channel view count
Return type:: int

property yt_api_key¶

Extract the INNERTUBE_API_KEY from the playlist ytcfg.

Return type:: str

property ytcfg¶

Extract the ytcfg from the playlist page html.

Return type:: dict

Stream Object¶

class pytubefix.Stream(stream: Dict, monostate: Monostate)[source]¶

Container for stream manifest data.

property default_filename: str¶

Generate filename based on the video title.

Return type:: str
Returns:: An os file system compatible filename.

Downloads a file from the URL provided by self.url and saves it locally with optional configurations.

Args:

output_path (Optional[str]): Directory path where the downloaded file will be saved. Defaults to the current directory if not specified. filename (Optional[str]): Custom name for the downloaded file. If not provided, a default name is used. filename_prefix (Optional[str]): Prefix to be added to the filename (if provided). skip_existing (bool): Whether to skip the download if the file already exists at the target location. Defaults to True. timeout (Optional[int]): Maximum time, in seconds, to wait for the download request. Defaults to None for no timeout. max_retries (int): The number of times to retry the download if it fails. Defaults to 0 (no retries). interrupt_checker (Optional[Callable[[], bool]]): A callable function that is checked periodically during the download. If it returns True, the download will stop without errors.

Returns:

Optional[str]: The full file path of the downloaded file, or None if the download was skipped or failed.

Raises:

HTTPError: Raised if there is an error with the HTTP request during the download process.

Note:

The skip_existing flag avoids redownloading if the file already exists in the target location.
The interrupt_checker allows for the download to be halted cleanly if certain conditions are met during the download process.
Download progress can be monitored using the on_progress callback, and the on_complete callback is triggered once the download is finished.

property filesize: int¶

File size of the media stream in bytes.

Return type:: int
Returns:: Filesize (in bytes) of the stream.

property filesize_approx: int¶

Get approximate filesize of the video

Falls back to HTTP call if there is not sufficient information to approximate

Return type:: int
Returns:: size of video in bytes

property filesize_gb: float¶

File size of the media stream in gigabytes.

Return type:: float
Returns:: Rounded filesize (in gigabytes) of the stream.

property filesize_kb: float¶

File size of the media stream in kilobytes.

Return type:: float
Returns:: Rounded filesize (in kilobytes) of the stream.

property filesize_mb: float¶

File size of the media stream in megabytes.

Return type:: float
Returns:: Rounded filesize (in megabytes) of the stream.

property height: int¶

Video height. Returns None if it does not have the value.

Return type:: int
Returns:: Returns an int of the video height

property includes_audio_track: bool¶

Whether the stream only contains audio.

Return type:: bool

property includes_video_track: bool¶

Whether the stream only contains video.

Return type:: bool

property is_adaptive: bool¶

Whether the stream is DASH.

Return type:: bool

property is_progressive: bool¶

Whether the stream is progressive.

Return type:: bool

iter_chunks(chunk_size: int | None = None) → Iterator[bytes][source]¶

Get the chunks directly

Example: # Write the chunk by yourself with open(“somefile.mp4”) as out_file:

out_file.writelines(stream.iter_chunks(512))

# Another way # for chunk in stream.iter_chunks(512): # out_file.write(chunk)

# Or give it external api external_api.write_media(stream.iter_chunks(512))

Parameters:: size (int chunk)

The size in the bytes :rtype: Iterator[bytes]

on_complete(file_path: str | None)[source]¶

On download complete handler function.

Parameters:: file_path (str) – The file handle where the media is being written to.
Return type:: None

on_progress(chunk: bytes, file_handler: BinaryIO, bytes_remaining: int)[source]¶

On progress callback function.

This function writes the binary data to the file, then checks if an additional callback is defined in the monostate. This is exposed to allow things like displaying a progress bar.

Parameters:

chunk (bytes) – Segment of media file binary data, not yet written to disk.
file_handler (io.BufferedWriter) – The file handle where the media is being written to.
bytes_remaining (int) – The delta between the total file size in bytes and amount already downloaded.

Return type:

None

on_progress_for_chunks(chunk: bytes, bytes_remaining: int)[source]¶

On progress callback function.

This function checks if an additional callback is defined in the monostate. This is exposed to allow things like displaying a progress bar.

Parameters:: chunk (bytes)

Segment of media file binary data, not yet written to disk. io.BufferedWriter :param int bytes_remaining: The delta between the total file size in bytes and amount already downloaded.

Return type:: None

parse_codecs() → Tuple[str | None, str | None][source]¶

Get the video/audio codecs from list of codecs.

Parse a variable length sized list of codecs and returns a constant two element tuple, with the video codec as the first element and audio as the second. Returns None if one is not available (adaptive only).

Return type:: tuple
Returns:: A two element tuple with audio and video codecs.

stream_to_buffer(buffer: BinaryIO) → None[source]¶

Write the media stream to buffer

Return type:: io.BytesIO buffer

property title: str¶

Get title of video

Return type:: str
Returns:: Youtube video title

property width: int¶

Video width. Returns None if it does not have the value.

Return type:: int
Returns:: Returns an int of the video width

StreamQuery Object¶

class pytubefix.query.StreamQuery(fmt_streams)[source]¶

Interface for querying the available media streams.

all() → List[Stream][source]¶

Get all the results represented by this query as a list.

Return type:: list

asc() → StreamQuery[source]¶

Sort streams in ascending order.

Return type:: StreamQuery

count(value: str | None = None) → int[source]¶

Get the count of items in the list.

Return type:: int

desc() → StreamQuery[source]¶

Sort streams in descending order.

Return type:: StreamQuery

filter(fps=None, res=None, resolution=None, mime_type=None, type=None, subtype=None, file_extension=None, abr=None, bitrate=None, video_codec=None, audio_codec=None, only_audio=None, only_video=None, progressive=None, adaptive=None, is_dash=None, audio_track_name=None, custom_filter_functions=None)[source]¶

Apply the given filtering criterion.

Parameters:

fps (int or None) – (optional) The frames per second.
resolution (str or None) – (optional) Alias to res.
res (str or None) – (optional) The video resolution.
mime_type (str or None) – (optional) Two-part identifier for file formats and format contents composed of a “type”, a “subtype”.
type (str or None) – (optional) Type part of the mime_type (e.g.: audio, video).
subtype (str or None) – (optional) Sub-type part of the mime_type (e.g.: mp4, mov).
file_extension (str or None) – (optional) Alias to sub_type.
abr (str or None) – (optional) Average bitrate (ABR) refers to the average amount of data transferred per unit of time (e.g.: 64kbps, 192kbps).
bitrate (str or None) – (optional) Alias to abr.
video_codec (str or None) – (optional) Video compression format.
audio_codec (str or None) – (optional) Audio compression format.
progressive (bool) – Excludes adaptive streams (one file contains both audio and video tracks).
adaptive (bool) – Excludes progressive streams (audio and video are on separate tracks).
is_dash (bool) – Include/exclude dash streams.
only_audio (bool) – Excludes streams with video tracks.
only_video (bool) – Excludes streams with audio tracks.
audio_track_name – Name of the dubbed audio track
custom_filter_functions (list or None) – (optional) Interface for defining complex filters without subclassing.

first() → Stream | None[source]¶

Get the first Stream in the results.

Return type:: Stream or None
Returns:: the first result of this query or None if the result doesn’t contain any streams.

get_audio_only(subtype: str = 'mp4') → Stream | None[source]¶

Get highest bitrate audio stream for given codec (defaults to mp4)

Parameters:: subtype (str) – Audio subtype, defaults to mp4
Return type:: Stream or None
Returns:: The Stream matching the given itag or None if not found.

get_by_itag(itag: int | str) → Stream | None[source]¶

Get the corresponding Stream for a given itag.

Parameters:: itag (int) – YouTube format identifier code.
Return type:: Stream or None
Returns:: The Stream matching the given itag or None if not found.

get_by_resolution(resolution: str) → Stream | None[source]¶

Get the corresponding Stream for a given resolution.

Stream must be a progressive mp4.

Parameters:: resolution (str) – Video resolution i.e. “720p”, “480p”, “360p”, “240p”, “144p”
Return type:: Stream or None
Returns:: The Stream matching the given itag or None if not found.

get_default_audio_track() → StreamQuery[source]¶

Takes the standard audio tracks, will return all audio tracks if there is no dubbing.

Return type:: StreamQuery
Returns:: A StreamQuery object with filtered default dubbing streams.

get_extra_audio_track() → StreamQuery | None[source]¶

Get only dubbed audio tracks.

Return type:: StreamQuery or None
Returns:: A StreamQuery object with filtering only the dubbing streams.

get_extra_audio_track_by_name(name) → StreamQuery | None[source]¶

Filter dubbed audio streams by name

Return type:: StreamQuery or None
Returns:: A StreamQuery object filtering dubbed audio streams by name.

get_highest_resolution(progressive=True, mime_type=None) → Stream | None[source]¶

Get highest resolution stream that is a progressive video.

Parameters:

progressive (bool) – Filter only progressive streams (video and audio in the same file), default is True. Set False to get the adaptive stream (separate video and audio) at the highest resolution
mime_type (str) – Filter by mime_type. Leave as None to accept any mime_type.

Return type:

Stream or None

Returns:

The Stream matching the given itag or None if not found.

get_lowest_resolution(progressive=True) → Stream | None[source]¶

Get lowest resolution stream that is a progressive mp4.

Parameters:: progressive (bool) – Filter only progressive streams (video and audio in the same file), default is True. Set False to get the adaptive stream (separate video and audio) at the lowest resolution
Return type:: Stream or None
Returns:: The Stream matching the given itag or None if not found.

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

last()[source]¶

Get the last Stream in the results.

Return type:: Stream or None
Returns:: Return the last result of this query or None if the result doesn’t contain any streams.

order_by(attribute_name: str) → StreamQuery[source]¶

Apply a sort order. Filters out stream the do not have the attribute.

Parameters:: attribute_name (str) – The name of the attribute to sort by.

otf(is_otf: bool = False) → StreamQuery[source]¶

Filter stream by OTF, useful if some streams have 404 URLs

Parameters:: is_otf (bool) – Set to False to retrieve only non-OTF streams
Return type:: StreamQuery
Returns:: A StreamQuery object with otf filtered streams

Caption Object¶

class pytubefix.Caption(caption_track: Dict)[source]¶

Container for caption tracks.

download(title: str, srt: bool = True, output_path: str | None = None, filename_prefix: str | None = None) → str[source]¶

Write the media stream to disk.

Parameters:

title (str) – Output filename (stem only) for writing media file. If one is not specified, the default filename is used.
srt – Set to True to download srt, false to download xml. Defaults to True.

:type srt bool :param output_path:

(optional) Output path for writing media file. If one is not specified, defaults to the current working directory.

Parameters:: filename_prefix (str or None) – (optional) A string that will be prepended to the filename. For example a number in a playlist or the name of a series. If one is not specified, nothing will be prepended This is separate from filename so you can use the default filename but still add a prefix.
Return type:: str

static float_to_srt_time_format(d: float) → str[source]¶

Convert decimal durations into proper srt format.

Return type:: str
Returns:: SubRip Subtitle (str) formatted time duration.

float_to_srt_time_format(3.89) -> ‘00:00:03,890’

generate_srt_captions() → str[source]¶

Generate “SubRip Subtitle” captions.

Takes the xml captions from xml_captions() and recompiles them into the “SubRip Subtitle” format.

generate_txt_captions() → str[source]¶

Generate Text captions.

Takes the “SubRip Subtitle” format captions and converts them into text

property json_captions: dict¶: Download and parse the json caption tracks.

save_captions(filename: str)[source]¶

Generate and save “SubRip Subtitle” captions to a text file.

Takes the xml captions from xml_captions() and recompiles them into the “SubRip Subtitle” format and saves it to a text file.

Parameters:: filename – The name of the file to save the captions.

xml_caption_to_srt(xml_captions: str) → str[source]¶

Convert xml caption tracks to “SubRip Subtitle (srt)”.

Parameters:: xml_captions (str) – XML formatted caption tracks.

property xml_captions: str¶: Download the xml caption tracks.

CaptionQuery Object¶

class pytubefix.query.CaptionQuery(captions: List[Caption])[source]¶

Interface for querying the available captions.

all() → List[Caption][source]¶

Get all the results represented by this query as a list.

Return type:: list

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

get_by_language_code(lang_code: str) → Caption | None[source]¶

Get the Caption for a given lang_code.

Parameters:: lang_code (str) – The code that identifies the caption language.
Return type:: Caption or None
Returns:: The Caption matching the given lang_code or None if it does not exist.

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

values() → an object providing a view on D's values¶

Search Object¶

class pytubefix.contrib.search.Search(query: str, client: str = 'ANDROID_VR', proxies: Dict[str, str] | None = None, use_oauth: bool = False, allow_oauth_cache: bool = True, token_file: str | None = None, oauth_verifier: Callable[[str, str], None] | None = None, use_po_token: bool | None = False, po_token_verifier: Callable[[None], Tuple[str, str]] | None = None, filters: dict | None = None)[source]¶

property all: list¶: Return all objects found in the search

property channel: List[Channel]¶

Returns the search result channel.

On first call, will generate and return the first set of results. Additional results can be generated using .get_next_results().

Return type:: list[Channel]
Returns:: A list of Channel objects.

property completion_suggestions¶

Return query autocompletion suggestions for the query.

Return type:: list
Returns:: A list of autocomplete suggestions provided by YouTube for the query.

fetch_and_parse(continuation=None)[source]¶

Fetch from the innertube API and parse the results.

Parameters:: continuation (str) – Continuation string for fetching results.
Return type:: tuple
Returns:: A tuple of a list of YouTube objects and a continuation string.

fetch_query(continuation: str = None, filters: dict = None)[source]¶

Fetch raw results from the innertube API.

Parameters:

continuation (str) – Continuation string for fetching results.
filters (dict) – Parameter encoded in protobuf that contains the search filters.

Return type:

dict

Returns:

The raw json object returned by the innertube API.

get_next_results()[source]¶

Use the stored continuation string to fetch the next set of results.

This method does not return the results, but instead updates the results property.

property playlist: List[Playlist]¶

Returns the search result playlist.

On first call, will generate and return the first set of results. Additional results can be generated using .get_next_results().

Return type:: list[Playlist]
Returns:: A list of Playlist objects.

property results: list¶

returns a list with videos, shorts, playlist and channels.

On first call, will generate and return the first set of results. Additional results can be generated using .get_next_results().

Return type:: list
Returns:: A list of YouTube, Playlist and Channel objects.

property shorts: List[YouTube]¶

Returns the search result shorts.

On first call, will generate and return the first set of results. Additional results can be generated using .get_next_results().

Return type:: list[YouTube]
Returns:: A list of YouTube objects.

property videos: List[YouTube]¶

Returns the search result videos.

On first call, will generate and return the first set of results. Additional results can be generated using .get_next_results().

Return type:: list[YouTube]
Returns:: A list of YouTube objects.

ChapterThumbnail Object¶

class pytubefix.chapters.ChapterThumbnail(width: int, height: int, url: str)[source]¶: Container for chapter thumbnails.

Chapter Object¶

class pytubefix.chapters.Chapter(chapter_data: dict, duration: int)[source]¶: Container for chapters tracks.

Extract¶

This module contains all non-cipher related data extraction logic.

pytubefix.extract.apply_descrambler(stream_data: Dict) → List[Dict] | None[source]¶

Apply various in-place transforms to YouTube’s media stream data.

Creates a list of dictionaries by string splitting on commas, then taking each list item, parsing it as a query string, converting it to a dict and unquoting the value.

Parameters:: stream_data (dict) – Dictionary containing query string encoded values.

Example:

>>> d = {'foo': 'bar=1&var=test,em=5&t=url%20encoded'}
>>> apply_descrambler(d, 'foo')
>>> print(d)
{'foo': [{'bar': '1', 'var': 'test'}, {'em': '5', 't': 'url encoded'}]}

pytubefix.extract.apply_po_token(stream_manifest: Dict, vid_info: Dict, po_token: str) → None[source]¶

Apply the proof of origin token to the stream manifest

Parameters:

stream_manifest (dict) – Details of the media streams available.
po_token (str) – Proof of Origin Token.

pytubefix.extract.apply_signature(stream_manifest: Dict, vid_info: Dict, js: str, url_js: str) → None[source]¶

Apply the decrypted signature to the stream manifest.

Parameters:

stream_manifest (dict) – Details of the media streams available.
js (str) – The contents of the base.js asset file.
url_js (str) – Full base.js url

pytubefix.extract.channel_name(url: str) → str[source]¶

Extract the channel_name or channel_id from a YouTube url.

This function supports the following patterns:

https://youtube.com/c/channel_name/*
:samp:`https://youtube.com/channel/{channel_id}/*
https://youtube.com/u/channel_name/*
:samp:`https://youtube.com/user/{channel_id}/*
:samp:`https://youtube.com /@{channel_id}/*

Parameters:: url (str) – A YouTube url containing a channel name.
Return type:: str
Returns:: YouTube channel name.

pytubefix.extract.get_ytcfg(html: str) → str[source]¶

Get the entirety of the ytcfg object.

This is built over multiple pieces, so we have to find all matches and combine the dicts together.

Parameters:: html (str) – The html contents of the watch page.
Return type:: str
Returns:: Substring of the html containing the encoded manifest data.

pytubefix.extract.get_ytplayer_config(html: str) → Any[source]¶

Get the YouTube player configuration data from the watch html.

Extract the ytplayer_config, which is json data embedded within the watch html and serves as the primary source of obtaining the stream manifest data.

Parameters:: html (str) – The html contents of the watch page.
Return type:: str
Returns:: Substring of the html containing the encoded manifest data.

pytubefix.extract.get_ytplayer_js(html: str) → Any[source]¶

Get the YouTube player base JavaScript path.

:param str html: The html contents of the watch page.

Return type:: str
Returns:: Path to YouTube’s base.js file.

pytubefix.extract.initial_data(watch_html: str) → dict[source]¶

Extract the ytInitialData json from the watch_html page.

This mostly contains metadata necessary for rendering the page on-load, such as video information, copyright notices, etc.

@param watch_html: Html of the watch page @return:

pytubefix.extract.initial_player_response(watch_html: str) → str[source]¶

Extract the ytInitialPlayerResponse json from the watch_html page.

This mostly contains metadata necessary for rendering the page on-load, such as video information, copyright notices, etc.

@param watch_html: Html of the watch page @return:

pytubefix.extract.is_age_restricted(watch_html: str) → bool[source]¶

Check if content is age restricted.

Parameters:: watch_html (str) – The html contents of the watch page.
Return type:: bool
Returns:: Whether or not the content is age restricted.

pytubefix.extract.is_private(watch_html)[source]¶

Check if content is private.

Parameters:: watch_html (str) – The html contents of the watch page.
Return type:: bool
Returns:: Whether or not the content is private.

pytubefix.extract.js_url(html: str) → str[source]¶

Get the base JavaScript url.

Construct the base JavaScript url, which contains the decipher “transforms”.

Parameters:: html (str) – The html contents of the watch page.

pytubefix.extract.metadata(initial_data) → YouTubeMetadata | None[source]¶

Get the informational metadata for the video.

e.g.: [

{
‘Song’: ‘강남스타일(Gangnam Style)’, ‘Artist’: ‘PSY’, ‘Album’: ‘PSY SIX RULES Pt.1’, ‘Licensed to YouTube by’: ‘YG Entertainment Inc. […]’

}

]

Return type:: YouTubeMetadata

pytubefix.extract.mime_type_codec(mime_type_codec: str) → Tuple[str, List[str]][source]¶

Parse the type data.

Breaks up the data in the type key of the manifest, which contains the mime type and codecs serialized together, and splits them into separate elements.

Example:

mime_type_codec(‘audio/webm; codecs=”opus”’) -> (‘audio/webm’, [‘opus’])

Parameters:: mime_type_codec (str) – String containing mime type and codecs.
Return type:: tuple
Returns:: The mime type and a list of codecs.

pytubefix.extract.playability_status(player_response: dict) → Tuple[Any, Any][source]¶

Return the playability status and status explanation of a video.

For example, a video may have a status of LOGIN_REQUIRED, and an explanation of “This is a private video. Please sign in to verify that you may see it.”

This explanation is what gets incorporated into the media player overlay.

Parameters:: player_response (str) – Content of the player’s response.
Return type:: bool
Returns:: Playability status and reason of the video.

pytubefix.extract.playlist_id(url: str) → str[source]¶

Extract the playlist_id from a YouTube url.

This function supports the following patterns:

https://youtube.com/playlist?list=playlist_id
https://youtube.com/watch?v=video_id&list=playlist_id

Parameters:: url (str) – A YouTube url containing a playlist id.
Return type:: str
Returns:: YouTube playlist id.

pytubefix.extract.publish_date(watch_html: str)[source]¶

Extract publish date and return it as a datetime object :param str watch_html:

The html contents of the watch page.

Return type:: datetime
Returns:: Publish date of the video as a datetime object with timezone.

pytubefix.extract.recording_available(watch_html)[source]¶

Check if live stream recording is available.

Parameters:: watch_html (str) – The html contents of the watch page.
Return type:: bool
Returns:: Whether or not the content is private.

pytubefix.extract.video_id(url: str) → str[source]¶

Extract the video_id from a YouTube url.

This function supports the following patterns:

https://youtube.com/watch?v=video_id
https://youtube.com/embed/video_id
https://youtu.be/video_id

Parameters:: url (str) – A YouTube url containing a video id.
Return type:: str
Returns:: YouTube video id.

pytubefix.extract.video_info_url(video_id: str, watch_url: str) → str[source]¶

Construct the video_info url.

Parameters:

video_id (str) – A YouTube video identifier.
watch_url (str) – A YouTube watch url.

Return type:

str

Returns:

https://youtube.com/get_video_info with necessary GET parameters.

pytubefix.extract.video_info_url_age_restricted(video_id: str, embed_html: str) → str[source]¶

Construct the video_info url.

Parameters:

video_id (str) – A YouTube video identifier.
embed_html (str) – The html contents of the embed page (for age restricted videos).

Return type:

str

Returns:

https://youtube.com/get_video_info with necessary GET parameters.

Cipher¶

This module contains all the logic needed to find the signature functions.

YouTube’s strategy to restrict downloading videos is to send a ciphered version of the signature to the client, along with the decryption algorithm obfuscated in JavaScript. For the clients to play the videos, JavaScript must take the ciphered version, cycle it through a series of “transform functions,” and then signs the media URL with the output.

This module is responsible for (1) finding these “transformations functions” (2) sends them to be interpreted by jsinterp.py

pytubefix.cipher.get_initial_function_name(js: str, js_url: str) → str[source]¶

Extract the name of the function responsible for computing the signature. :param str js:

The contents of the base.js asset file.

Parameters:: js_url (str) – Full base.js url
Return type:: str
Returns:: Function name from regex match

pytubefix.cipher.get_throttling_function_name(js: str, js_url: str) → str[source]¶

Extract the name of the function that computes the throttling parameter.

Parameters:

js (str) – The contents of the base.js asset file.
js_url (str) – Full base.js url

Return type:

str

Returns:

The name of the function used to compute the throttling parameter.

Exceptions¶

Library specific exception definitions.

exception pytubefix.exceptions.AgeCheckRequiredAccountError(video_id: str)[source]¶

exception pytubefix.exceptions.AgeCheckRequiredError(video_id: str)[source]¶

exception pytubefix.exceptions.AgeRestrictedError(video_id: str)[source]¶: Video is age restricted, and cannot be accessed without OAuth.

exception pytubefix.exceptions.BotDetection(video_id: str)[source]¶

exception pytubefix.exceptions.ExtractError[source]¶: Data extraction based exception.

exception pytubefix.exceptions.HTMLParseError[source]¶: HTML could not be parsed

exception pytubefix.exceptions.InnerTubeResponseError(video_id: str, client: str)[source]¶

exception pytubefix.exceptions.LiveStreamError(video_id: str)[source]¶: Video is a live stream.

exception pytubefix.exceptions.LiveStreamOffline(video_id: str, reason: str)[source]¶: The live will start soon

exception pytubefix.exceptions.LoginRequired(video_id: str, reason: str)[source]¶

exception pytubefix.exceptions.MaxRetriesExceeded[source]¶: Maximum number of retries exceeded.

exception pytubefix.exceptions.MembersOnly(video_id: str)[source]¶

Video is members-only.

YouTube has special videos that are only viewable to users who have subscribed to a content creator. ref: https://support.google.com/youtube/answer/7544492?hl=en

exception pytubefix.exceptions.PoTokenRequired(video_id: str, client_name: str)[source]¶

exception pytubefix.exceptions.PytubeFixError[source]¶

Base pytubefix exception that all others inherit.

This is done to not pollute the built-in exceptions, which could result in unintended errors being unexpectedly and incorrectly handled within implementers code.

exception pytubefix.exceptions.RecordingUnavailable(video_id: str)[source]¶

exception pytubefix.exceptions.RegexMatchError(caller: str, pattern: str | Pattern)[source]¶: Regex pattern did not return any matches.

exception pytubefix.exceptions.UnknownVideoError(video_id: str, status: str = None, reason: str = None, developer_message: str = None)[source]¶: Unknown video error.

exception pytubefix.exceptions.VideoPrivate(video_id: str)[source]¶

exception pytubefix.exceptions.VideoRegionBlocked(video_id: str)[source]¶

exception pytubefix.exceptions.VideoUnavailable(video_id: str)[source]¶

Base video error.

This is the base error type for all video errors.

Call this if you can’t group the error by known error type and it is not important to the developer.

Helpers¶

Various helper functions implemented by pytube.

class pytubefix.helpers.DeferredGeneratorList(generator)[source]¶

A wrapper class for deferring list generation.

Pytubefix has some continuation generators that create web calls, which means that any time a full list is requested, all of those web calls must be made at once, which could lead to slowdowns. This will allow individual elements to be queried, so that slowdowns only happen as necessary. For example, you can iterate over elements in the list without accessing them all simultaneously. This should allow for speed improvements for playlist and channel interactions.

generate_all()[source]¶: Generate all items.

pytubefix.helpers.cache(func: Callable[[...], GenericType]) → GenericType[source]¶: mypy compatible annotation wrapper for lru_cache

pytubefix.helpers.create_mock_html_json(vid_id) → Dict[str, Any][source]¶

Generate a json.gz file with sample html responses.

:param str vid_id: YouTube video id
:return dict data: Dict used to generate the json.gz file

pytubefix.helpers.deprecated(reason: str) → Callable[source]¶: This is a decorator which can be used to mark functions as deprecated. It will result in a warning being emitted when the function is used.

pytubefix.helpers.generate_all_html_json_mocks()[source]¶

Regenerate the video mock json files for all current test videos.

This should automatically output to the test/mocks directory.

pytubefix.helpers.regex_search(pattern: str, string: str, group: int) → str[source]¶

Shortcut method to search a string for a given pattern.

Parameters:

pattern (str) – A regular expression pattern.
string (str) – A target string to search.
group (int) – Index of group to return.

Return type:

str or tuple

Returns:

Substring pattern matches.

pytubefix.helpers.reset_cache(verbose: bool = False)[source]¶

Deletes the __cache__ directory to reset the cache.

This function checks if the __cache__ directory exists in the same directory as the script. If it exists and is a directory, it deletes it along with its contents. If the directory does not exist, it logs a message indicating that the cache directory is not present.

Parameters:

verbose (bool): If True, sets up logging at the DEBUG level. Default is False.

Behavior:

When verbose is True, debug messages are logged, providing information about the existence and status of the cache directory.
If verbose is False, no logging configuration is modified, and debug messages may not be shown unless logging is already configured externally.

Example:

>>> reset_cache(verbose=True)
# Logs detailed information about the cache reset process.

Raises:

None

pytubefix.helpers.safe_filename(s: str, max_length: int = 255) → str[source]¶

Sanitize a string making it safe to use as a filename.

This function was based off the limitations outlined here: https://en.wikipedia.org/wiki/Filename.

Parameters:

s (str) – A string to make safe for use as a file name.
max_length (int) – The maximum filename character length.

Return type:

str

Returns:

A sanitized string.

pytubefix.helpers.setup_logger(level: int = 40, log_filename: str | None = None) → None[source]¶

Create a configured instance of logger.

Parameters:: level (int) – Describe the severity level of the logs to handle.

pytubefix.helpers.strip_color_codes(input_str)[source]¶: Remove ANSI color codes from a colored string

pytubefix.helpers.target_directory(output_path: str | None = None) → str[source]¶

Function for determining target directory of a download. Returns an absolute path (if relative one given) or the current path (if none given). Makes directory if it does not exist.

Returns:: An absolute directory path as a string.

pytubefix.helpers.uniqueify(duped_list: List) → List[source]¶

Remove duplicate items from a list, while maintaining list order.

:param List duped_list: List to remove duplicates from
:return List result: De-duplicated list

Request¶

Implements a simple wrapper around urlopen.

pytubefix.request.filesize(url)[source]¶

Fetch size in bytes of file at given URL

Parameters:: url (str) – The URL to get the size of
Returns:: int: size in bytes of remote file

pytubefix.request.get(url, extra_headers=None, timeout=<object object>)[source]¶

Send an http GET request.

Parameters:

url (str) – The URL to perform the GET request for.
extra_headers (dict) – Extra headers to add to the request

Return type:

str

Returns:

UTF-8 encoded string of response

pytubefix.request.head(url)[source]¶

Fetch headers returned http GET request.

Parameters:: url (str) – The URL to perform the GET request for.
Return type:: dict
Returns:: dictionary of lowercase headers

pytubefix.request.post(url, extra_headers=None, data=None, timeout=<object object>)[source]¶

Send an http POST request.

Parameters:

url (str) – The URL to perform the POST request for.
extra_headers (dict) – Extra headers to add to the request
data (dict) – The data to send on the POST request

Return type:

str

Returns:

UTF-8 encoded string of response

pytubefix.request.seq_filesize(url)[source]¶

Fetch size in bytes of file at given URL from sequential requests

Parameters:: url (str) – The URL to get the size of
Returns:: int: size in bytes of remote file

pytubefix.request.seq_stream(url, timeout=<object object>, max_retries=0)[source]¶: Read the response in sequence. :param str url: The URL to perform the GET request for. :rtype: Iterable[bytes]

pytubefix.request.stream(url, timeout=<object object>, max_retries=0)[source]¶: Read the response in chunks. :param str url: The URL to perform the GET request for. :rtype: Iterable[bytes]