Pytubefix

https://pytubefix.readthedocs.io/en/latest/
Admin
Pytubefix is a lightweight, Pythonic, dependency-free library and command-line utility for...
Tokens:70,694
Snippets:481
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install from source

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/install.rst.txt

Install the package locally after navigating to the source directory.

```bash
$ cd pytubefix
$ python -m pip install .
```

--------------------------------

### Install proxy

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/helpers.html

Configures a global proxy for network requests.

```python
def install_proxy(proxy_handler: Dict[str, str]) -> None:
    proxy_support = request.ProxyHandler(proxy_handler)
    opener = request.build_opener(proxy_support)
    request.install_opener(opener)
```

--------------------------------

### Install pytubefix via pip

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/install.rst.txt

Standard command to install the package using the Python package manager.

```bash
$ pip install pytubefix
```

--------------------------------

### Terminal piping examples

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/buffer.rst.txt

Various command-line examples for piping script output to external tools like ffplay, ffmpeg, less, nc, and hexdump.

```bash
$ python3 main.py | ffplay -i -
```

```bash
$ python3 main.py | ffmpeg -i - -acodec libmp3lame output.mp3
```

```bash
$ python3 main.py | less
```

```bash
$ python3 main.py > output.webm
```

```bash
$ python3 main.py | nc 192.168.1.100 5000
```

```bash
$ python3 main.py | ffmpeg -i - -f wav - | audacity
```

```bash
$ python3 playlist.py | ffplay -i -
```

```bash
$ python3 main.py | hexdump -C
```

--------------------------------

### Access chapter start label

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/chapters.rst.txt

Retrieve the start timestamp label of a specific chapter.

```python
>>> print(yt.chapters[0].start_label)
```

--------------------------------

### Get video metadata properties

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/__main__.html

Simple property accessors for rating and length.

```python
@property
def rating(self) -> float:
    """Get the video average rating.

    :rtype: float

    """
    return self.vid_info.get("videoDetails", {}).get("averageRating")

@property
def length(self) -> int:
    """Get the video length in seconds.

    :rtype: int
    """
    self.check_availability()
    return int(self.vid_info.get('videoDetails', {}).get('lengthSeconds'))
```

--------------------------------

### Display help information

Source: https://pytubefix.readthedocs.io/en/latest/user/cli.html

Lists all available command-line options.

```bash
$ pytubefix --help
```

--------------------------------

### Display help and version

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/cli.rst.txt

Commands to view CLI options or the current version.

```bash
$ pytubefix --help
```

```bash
$ pytubefix -V
```

--------------------------------

### Send HTTP GET Request

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/request.html

Performs a GET request and returns the response as a UTF-8 decoded string.

```python
def get(url, extra_headers=None, timeout=socket._GLOBAL_DEFAULT_TIMEOUT):
    """Send an http GET request.

    :param str url:
        The URL to perform the GET request for.
    :param dict extra_headers:
        Extra headers to add to the request
    :rtype: str
    :returns:
        UTF-8 encoded string of response
    """
    if extra_headers is None:
        extra_headers = {}
    response = _execute_request(url, headers=extra_headers, timeout=timeout)
    return response.read().decode("utf-8")
```

--------------------------------

### get(url, extra_headers=None, timeout=socket._GLOBAL_DEFAULT_TIMEOUT)

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/request.html

Sends an HTTP GET request to the specified URL and returns the response as a UTF-8 encoded string.

```APIDOC
## get(url, extra_headers=None, timeout=socket._GLOBAL_DEFAULT_TIMEOUT)

### Description
Sends an HTTP GET request to the specified URL and returns the response as a UTF-8 encoded string.

### Parameters
- **url** (str) - Required - The URL to perform the GET request for.
- **extra_headers** (dict) - Optional - Extra headers to add to the request.
- **timeout** (int) - Optional - Timeout in seconds for the request.

### Returns
- **str** - UTF-8 encoded string of the response.
```

--------------------------------

### Initialize a Channel object

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/channel.rst.txt

Create a Channel instance using either the featured page URL or the videos page URL.

```python
>>> from pytubefix import Channel
```

```python
>>> c = Channel('https://www.youtube.com/@ProgrammingKnowledge/featured')
```

```python
>>> c = Channel('https://www.youtube.com/@ProgrammingKnowledge/videos')
```

--------------------------------

### Initializing a Playlist object

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/playlist.rst.txt

Create a playlist object using either a direct playlist URL or a video URL that belongs to a playlist.

```python
>>> p = Playlist('https://www.youtube.com/playlist?list=PLS1QulWo1RIaJECMeUT4LFwJ-ghgoSH6n')
```

```python
>>> p = Playlist('https://www.youtube.com/watch?v=41qgdwd3zAg&list=PLS1QulWo1RIaJECMeUT4LFwJ-ghgoSH6n')
```

--------------------------------

### YouTube.__init__

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/__main__.html

Constructs a new YouTube instance to interact with a specific video URL.

```APIDOC
## Constructor: YouTube(url, client, on_progress_callback, on_complete_callback, proxies, use_oauth, allow_oauth_cache, token_file, oauth_verifier, use_po_token, po_token_verifier)

### Description
Initializes the core developer interface for interacting with a YouTube video. This class handles the setup for fetching video information and managing stream downloads.

### Parameters
- **url** (str) - Required - A valid YouTube watch URL.
- **client** (str) - Optional - The YouTube client type (e.g., WEB, ANDROID, IOS).
- **on_progress_callback** (Callable) - Optional - Callback function for stream download progress events.
- **on_complete_callback** (Callable) - Optional - Callback function for stream download complete events.
- **proxies** (dict) - Optional - Mapping of protocol to proxy address.
- **use_oauth** (bool) - Optional - Whether to prompt the user to authenticate to YouTube.
- **allow_oauth_cache** (bool) - Optional - Whether to cache OAuth and Po tokens locally.
- **token_file** (str) - Optional - Path to the file where tokens are stored.
- **oauth_verifier** (Callable) - Optional - Custom verifier for OAuth tokens.
```

--------------------------------

### Request.get()

Source: https://pytubefix.readthedocs.io/en/latest/api.html

Performs a GET request to a specified URL.

```APIDOC
## Request.get()

### Description
Performs a standard HTTP GET request.

### Parameters
- **url** (str) - Required - The URL to fetch.
```

--------------------------------

### Initializing a YouTube object

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/quickstart.rst.txt

Create a YouTube object by providing the video URL.

```python
>>> yt = YouTube('http://youtube.com/watch?v=2lAe1cqCOXo')
```

--------------------------------

### pytubefix.request.head(url)

Source: https://pytubefix.readthedocs.io/en/latest/api.html

Fetches headers returned by an HTTP GET request.

```APIDOC
## pytubefix.request.head(url)

### Description
Fetch headers returned by an http GET request.

### Parameters
- **url** (str) - Required - The URL to perform the GET request for.

### Returns
- **dict** - Dictionary of lowercase headers.
```

--------------------------------

### head(url)

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/request.html

Fetches the headers returned by an HTTP GET request.

```APIDOC
## head(url)

### Description
Fetches headers returned by an HTTP GET request.

### Parameters
- **url** (str) - Required - The URL to perform the GET request for.

### Returns
- **dict** - Dictionary of lowercase headers.
```

--------------------------------

### Access specific environment details

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/info.rst.txt

Demonstrates how to extract individual keys like OS or Pytubefix version from the info dictionary.

```python
>>> from pytubefix import info
>>> 
>>> system_info = info()
>>> 
>>> print(f"Operational System: {system_info['OS']}")
Operational System: linux
>>> 
>>>
```

```python
>>> from pytubefix import info
>>> 
>>> system_info = info()
>>> 
>>> print(f"Pytubefix Version: {system_info['Pytubefix']}")
Pytubefix Version: 7.3.1
>>>
```

--------------------------------

### Initialize Format Streams

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/__main__.html

Initializes and returns a list of available streams, applying descramblers, PoTokens, and signature extraction as needed.

```python
    @property
    def fmt_streams(self):
        """Returns a list of streams if they have been initialized.

        If the streams have not been initialized, finds all relevant
        streams and initializes them.
        """
        self.check_availability()
        if self._fmt_streams:
            return self._fmt_streams

        self._fmt_streams = []

        stream_manifest = extract.apply_descrambler(self.streaming_data)
        inner_tube = InnerTube(self.client)
        if self.po_token:
            extract.apply_po_token(stream_manifest, self.vid_info, self.po_token)

        if inner_tube.require_js_player:
            # If the cached js doesn't work, try fetching a new js file
            # https://github.com/pytube/pytube/issues/1054
            try:
                extract.apply_signature(stream_manifest, self.vid_info, self.js, self.js_url)
            except exceptions.ExtractError:
                # To force an update to the js file, we clear the cache and retry
                self._js = None
                self._js_url = None
                pytubefix.__js__ = None
                pytubefix.__js_url__ = None
                extract.apply_signature(stream_manifest, self.vid_info, self.js, self.js_url)

        # build instances of :class:`Stream <Stream>`
        # Initialize stream objects
        for stream in stream_manifest:
            video = Stream(
                stream=stream,
                monostate=self.stream_monostate,
                po_token=self.po_token,
                video_playback_ustreamer_config=self.video_playback_ustreamer_config
            )
            self._fmt_streams.append(video)

        self.stream_monostate.title = self.title
        self.stream_monostate.duration = self.length

        return self._fmt_streams
```

--------------------------------

### Get playability status

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/extract.html

Extracts the playability status and explanation from the player response dictionary.

```python
def playability_status(player_response: dict) -> Tuple[Any, Any]:
    """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.

    :param str player_response:
        Content of the player's response.
    :rtype: bool
    :returns:
        Playability status and reason of the video.
    """
    status_dict = player_response.get('playabilityStatus', {})
    # if 'liveStreamability' in status_dict:
    # We used liveStreamability to know if the video was live,
    # however some clients still return this parameter even if the video is already available
    if 'videoDetails' in player_response:  # Private videos do not contain videoDetails
        if 'isLive' in player_response['videoDetails']:
            return 'LIVE_STREAM', 'Video is a live stream.'

    if 'status' in status_dict:
        if 'reason' in status_dict:
            return status_dict['status'], [status_dict['reason']]
        if 'messages' in status_dict:
            return status_dict['status'], status_dict['messages']
    return None, [None]
```

--------------------------------

### Integrate environment info into logging

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/info.rst.txt

Shows how to include environment metadata in application logs during a download process.

```python
>>> import logging
>>> from pytubefix import YouTube, info
>>> from pytubefix.cli import on_progress
>>> 
>>> logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
>>> 
>>> system_info = info()
>>> 
>>> def on_progress_with_logging(stream, chunk, bytes_remaining):
...     progress = 100 - (bytes_remaining / stream.filesize * 100)
...     logging.info(f"Download progress: {progress:.2f}%")
... 
>>> url = "https://www.youtube.com/watch?v=9bZkp7q19f0"
>>> 
>>> yt = YouTube(url, on_progress_callback=on_progress_with_logging)
>>> 
>>> ys = yt.streams.get_highest_resolution()
>>> ys.download()
'/home/PSY - GANGNAM STYLE(강남스타일) MV.mp4'
>>> 
>>> logging.info(f"System Information: Pytubefix v{system_info['Pytubefix']}, Python{system_info['Python']}, OS {system_info['OS']}")
2024-11-14 23:00:10,876 - INFO - System Information: Pytubefix v8.3.2, Python3.11.6 (main, Apr 10 2024, 17:26:07) [GCC 13.2.0], OS linux
>>> logging.info(f"Video title: {yt.title}")
2024-11-14 23:00:10,877 - INFO - Video title: PSY - GANGNAM STYLE(강남스타일) M/V
>>> 
>>> 
```

--------------------------------

### get(lang_code)

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/query.html

Retrieves a specific Caption object based on the provided language code.

```APIDOC
## get(lang_code)

### Description
Retrieves the Caption object matching the given language code. Returns None if the caption does not exist.

### Parameters
- **lang_code** (str) - Required - The code that identifies the caption language.

### Returns
- **Caption** (object) - The matching Caption object or None.
```

--------------------------------

### Initialize the YouTube class

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/__main__.html

Constructs the main interface for interacting with a YouTube video, supporting various clients, proxy configurations, and OAuth authentication.

```python
class YouTube:
    """Core developer interface for pytubefix."""

    def __init__(
            self,
            url: str,
            client: str = InnerTube().client_name,
            on_progress_callback: Optional[Callable[[Any, bytes, int], None]] = None,
            on_complete_callback: Optional[Callable[[Any, Optional[str]], None]] = None,
            proxies: Optional[Dict[str, str]] = None,
            use_oauth: bool = False,
            allow_oauth_cache: bool = True,
            token_file: Optional[str] = None,
            oauth_verifier: Optional[Callable[[str, str], None]] = None,
            use_po_token: Optional[bool] = False,
            po_token_verifier: Optional[Callable[[None], Tuple[str, str]]] = None,
    ):
```

--------------------------------

### Get video description

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/__main__.html

Retrieves the video description, optionally using OAuth engagement items.

```python
@property
def description(self) -> str:
    """Get the video description.

    :rtype: str
    """
    description = self.vid_info.get("videoDetails", {}).get("shortDescription")

    if self.use_oauth == True:
        description = self.vid_engagement_items()
        if description != None:
            description = description[2]['expandableVideoDescriptionBodyRenderer']['descriptionBodyText']['runs'][0]['text']

    if description is None:
        # TV client structure
        results = self.vid_details_content()
        for c in results:
            if 'videoSecondaryInfoRenderer' in c:
                description = c['videoSecondaryInfoRenderer']['attributedDescription']['content']
                break
    return description
```

--------------------------------

### Download audio as M4A using pytubefix

Source: https://pytubefix.readthedocs.io/en/latest/user/m4a.html

Initializes a YouTube object with a progress callback and downloads the best available audio-only stream.

```python
from pytubefix import YouTube
from pytubefix.cli import on_progress

url = input("url >")

yt = YouTube(url, on_progress_callback = on_progress)
print(yt.title)

ys = yt.streams.get_audio_only()
ys.download()
```

--------------------------------

### Get video thumbnail URL

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/__main__.html

Retrieves the highest resolution thumbnail URL available for the video.

```python
@property
def thumbnail_url(self) -> str:
    """Get the thumbnail url image.

    :rtype: str
    """
    thumbnail_details = (
        self.vid_info.get("videoDetails", {})
        .get("thumbnail", {})
        .get("thumbnails")
    )
    if thumbnail_details:
        thumbnail_details = thumbnail_details[-1]  # last item has max size
        return thumbnail_details["url"]

    return f"https://img.youtube.com/vi/{self.video_id}/maxresdefault.jpg"
```

--------------------------------

### Get Base JavaScript URL

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/extract.html

Retrieves the base JavaScript URL from the provided HTML content.

```python
    try:
        base_js = get_ytplayer_config(html)['assets']['js']
    except (KeyError, RegexMatchError):
        base_js = get_ytplayer_js(html)
    return f"https://youtube.com{base_js}"
```

--------------------------------

### Configure logger

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/helpers.html

Sets up a configured logger instance for the pytubefix package with optional file output.

```python
def setup_logger(level: int = logging.ERROR, log_filename: Optional[str] = None) -> None:
    """Create a configured instance of logger.

    :param int level:
        Describe the severity level of the logs to handle.
    """
    fmt = "[%(asctime)s] %(levelname)s in %(module)s: %(message)s"
    date_fmt = "%H:%M:%S"
    formatter = logging.Formatter(fmt, datefmt=date_fmt)

    # https://github.com/pytube/pytube/issues/163
    logger = logging.getLogger("pytubefix")
    logger.setLevel(level)

    stream_handler = logging.StreamHandler()
    stream_handler.setFormatter(formatter)
    logger.addHandler(stream_handler)

    if log_filename is not None:
        file_handler = logging.FileHandler(log_filename)
        file_handler.setFormatter(formatter)
        logger.addHandler(file_handler)
```

--------------------------------

### Search.__init__

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/contrib/search.html

Initializes a new Search object to perform queries on YouTube with optional authentication and filtering.

```APIDOC
## Search.__init__

### Description
Initializes the Search object with a query string and optional configuration for proxies, OAuth, and search filters.

### Parameters
- **query** (str) - Required - The search term to query.
- **client** (str) - Optional - The client name for the request.
- **proxies** (Dict[str, str]) - Optional - Proxy configuration.
- **use_oauth** (bool) - Optional - Whether to use OAuth authentication.
- **allow_oauth_cache** (bool) - Optional - Whether to cache OAuth tokens.
- **token_file** (str) - Optional - Path to the OAuth token file.
- **oauth_verifier** (Callable) - Optional - Callback for OAuth verification.
- **use_po_token** (bool) - Optional - Whether to use a PO token.
- **po_token_verifier** (Callable) - Optional - Callback for PO token verification.
- **filters** (Filter) - Optional - Search filter object.
```

--------------------------------

### index(value, start, stop)

Source: https://pytubefix.readthedocs.io/en/latest/api.html

Returns the first index of the specified value within the query results.

```APIDOC
## index(value, start, stop)

### Description
Return the first index of a value. Raises ValueError if the value is not present.

### Parameters
- **value** (any) - Required - The value to search for.
- **start** (int) - Optional - The starting index for the search.
- **stop** (int) - Optional - The stopping index for the search.

### Returns
- **integer** - The index of the value.
```

--------------------------------

### Search(query, ...)

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/contrib/search.html

Initializes a new search instance to query YouTube.

```APIDOC
## Search(query, proxies=None, use_oauth=False, allow_oauth_cache=True, token_file=None, oauth_verifier=None, use_po_token=False, po_token_verifier=None, filters=None)

### Description
Initializes a search object to perform queries on YouTube. This class handles the setup of the InnerTube client, authentication, and optional filtering.

### Parameters
- **query** (str) - Required - The search query string.
- **proxies** (dict) - Optional - Mapping of protocol to proxy address.
- **use_oauth** (bool) - Optional - Whether to prompt for OAuth authentication.
- **allow_oauth_cache** (bool) - Optional - Whether to cache OAuth tokens locally.
- **token_file** (str) - Optional - Path to store OAuth tokens.
- **oauth_verifier** (Callable) - Optional - Custom verifier for OAuth tokens.
- **use_po_token** (bool) - Optional - Whether to use proof of origin token.
- **po_token_verifier** (Callable) - Optional - Custom verifier for visitorData and po_token.
- **filters** (Filter) - Optional - Search filters (e.g., upload_date, type, duration).
```

--------------------------------

### Retrieve YouTube Shorts

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/search.rst.txt

Access the shorts attribute of a Search object to get a list of YouTube video objects.

```python
>>> from pytubefix import Search
>>> 
>>> s = Search('YouTube Rewind')
>>> 
>>> print(s.shorts)
```

--------------------------------

### Retrieve environment information

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/info.rst.txt

Fetches a dictionary containing the current OS, Python version, and Pytubefix version.

```python
>>> from pytubefix import info
>>> 
>>> print(info())
{'OS': {'linux'}, 'Python': {'3.11.6 (main, Apr 10 2024, 17:26:07) [GCC 13.2.0]'}, 'Pytubefix': {'7.3.1'}}
>>> 
```

--------------------------------

### pytubefix.request.get(url, extra_headers=None, timeout=<object object>)

Source: https://pytubefix.readthedocs.io/en/latest/api.html

Sends an HTTP GET request and returns the response as a UTF-8 encoded string.

```APIDOC
## pytubefix.request.get(url, extra_headers=None, timeout=<object object>)

### Description
Send an http GET request.

### Parameters
- **url** (str) - Required - The URL to perform the GET request for.
- **extra_headers** (dict) - Optional - Extra headers to add to the request.

### Returns
- **str** - UTF-8 encoded string of response.
```

--------------------------------

### download(title, srt=True, output_path=None, filename_prefix=None)

Source: https://pytubefix.readthedocs.io/en/latest/api.html

Writes the media stream to disk.

```APIDOC
## download(title, srt=True, output_path=None, filename_prefix=None)

### Description
Write the media stream to disk.

### Parameters
- **title** (str) - Required - Output filename (stem only) for writing media file.
- **srt** (bool) - Optional - Set to True to download srt, false to download xml. Defaults to True.
- **output_path** (str | None) - Optional - Output path for writing media file. Defaults to current working directory.
- **filename_prefix** (str | None) - Optional - A string that will be prepended to the filename.

### Returns
- **str** - The path to the saved file.
```

--------------------------------

### Get video title

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/__main__.html

Retrieves the video title, attempting to fetch it from engagement items if OAuth is enabled or falling back to standard metadata endpoints.

```python
@property
def title(self) -> str:
    """Get the video title.

    :rtype: str
    """
    self._author = self.vid_info.get("videoDetails", {}).get(
        "author", "unknown"
    )

    if self._title:
        return self._title

    if self.use_oauth == True:
        self._title = self.vid_engagement_items()
        if self._title != None:
            self._title = self._title[0]['videoDescriptionHeaderRenderer']['title']['runs'][0]['text']

    try:
        # Some clients may not return the title in the `player` endpoint,
        # so if it is not found we will look for it in the `next` endpoint
        if 'title' in self.vid_info['videoDetails']:
            self._title = self.vid_info['videoDetails']['title']
            logger.debug('Found title in vid_info')
        else:
            if 'singleColumnWatchNextResults' in self.vid_details['contents']:
                contents = self.vid_details['contents'][
                    'singleColumnWatchNextResults'][
                    'results'][
                    'results'][
                    'contents'][0][
                    'itemSectionRenderer'][
                    'contents'][0]

                if 'videoMetadataRenderer' in contents:
                    self._title = contents['videoMetadataRenderer']['title']['runs'][0]['text']
                else:
                    # JSON tree for titles in videos available on YouTube music
                    self._title = contents['musicWatchMetadataRenderer']['title']['simpleText']
```

--------------------------------

### Advanced YouTube object instantiation

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/quickstart.rst.txt

Configure advanced features like progress callbacks, completion callbacks, proxies, and OAuth settings.

```python
>>> yt = YouTube(
        'http://youtube.com/watch?v=2lAe1cqCOXo',
        on_progress_callback=progress_func,
        on_complete_callback=complete_func,
        proxies=my_proxies,
        use_oauth=False,
        allow_oauth_cache=True
    )
```

--------------------------------

### Log environment information during download

Source: https://pytubefix.readthedocs.io/en/latest/user/info.html

Integrates system information into standard logging during a video download process.

```python
>>> import logging
>>> from pytubefix import YouTube, info
>>> from pytubefix.cli import on_progress
>>>
>>> logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
>>>
>>> system_info = info()
>>>
>>> def on_progress_with_logging(stream, chunk, bytes_remaining):
...     progress = 100 - (bytes_remaining / stream.filesize * 100)
...     logging.info(f"Download progress: {progress:.2f}%")
...
>>> url = "https://www.youtube.com/watch?v=9bZkp7q19f0"
>>>
>>> yt = YouTube(url, on_progress_callback=on_progress_with_logging)
>>>
>>> ys = yt.streams.get_highest_resolution()
>>> ys.download()
'/home/PSY - GANGNAM STYLE(강남스타일) MV.mp4'
>>>
>>> logging.info(f"System Information: Pytubefix v{system_info['Pytubefix']}, Python{system_info['Python']}, OS {system_info['OS']}")
2024-11-14 23:00:10,876 - INFO - System Information: Pytubefix v8.3.2, Python3.11.6 (main, Apr 10 2024, 17:26:07) [GCC 13.2.0], OS linux
>>> logging.info(f"Video title: {yt.title}")
2024-11-14 23:00:10,877 - INFO - Video title: PSY - GANGNAM STYLE(강남스타일) M/V
>>>
>>>
```

--------------------------------

### Initialize Channel object

Source: https://pytubefix.readthedocs.io/en/latest/user/channel.html

Create a channel object using different types of YouTube channel URLs.

```python
>>> c = Channel('https://www.youtube.com/@ProgrammingKnowledge/featured')
```

```python
>>> c = Channel('https://www.youtube.com/@ProgrammingKnowledge/videos')
```

--------------------------------

### Download a YouTube video with progress tracking

Source: https://pytubefix.readthedocs.io/en/latest/_sources/index.rst.txt

Initializes a YouTube object with a progress callback and downloads the highest resolution stream available.

```python
from pytubefix import YouTube
from pytubefix.cli import on_progress
 
url = input("URL >")
 
yt = YouTube(url, on_progress_callback = on_progress)
print(yt.title)
 
ys = yt.streams.get_highest_resolution()
ys.download()
```

--------------------------------

### Configure and use a proxy with YouTube

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/proxy.rst.txt

Pass a dictionary containing proxy URLs to the YouTube constructor to route requests through a proxy server.

```python
from pytubefix import YouTube

proxy = {
    "http": "socks5://proxy_address",
    "https": "socks5://proxy_address"
    }

url = "url"

yt = YouTube(url, proxies=proxy)
print(yt.title)

ys = yt.streams.get_highest_resolution()
ys.download()
```

--------------------------------

### Playlist Class Initialization

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/contrib/playlist.html

Initializes a new Playlist instance to interact with a YouTube playlist.

```APIDOC
## Class: Playlist

### Description
Initializes a new instance of the Playlist class to load a YouTube playlist from a given URL.

### Constructor
`Playlist(url, client=InnerTube().client_name, proxies=None, use_oauth=False, allow_oauth_cache=True, token_file=None, oauth_verifier=None, use_po_token=False, po_token_verifier=None)`

### Parameters
- **url** (str) - Required - The URL of the YouTube playlist.
- **proxies** (dict) - Optional - A dict mapping protocol to proxy address.
- **use_oauth** (bool) - Optional - Whether to prompt the user to authenticate to YouTube.
- **allow_oauth_cache** (bool) - Optional - Whether to cache OAuth tokens locally.
- **token_file** (str) - Optional - Path to the file where OAuth tokens are stored.
- **oauth_verifier** (Callable) - Optional - Verifier to be used for getting OAuth tokens.
- **use_po_token** (bool) - Optional - Whether to use the proof of origin token.
- **po_token_verifier** (Callable) - Optional - Verifier used to obtain visitorData and po_token.
```

--------------------------------

### Create mock JSON

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/helpers.html

Generates a compressed JSON file containing sample HTML responses for a specific video ID.

```python
def create_mock_html_json(vid_id) -> Dict[str, Any]:
    """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
    """
    from pytubefix import YouTube
    gzip_filename = f'yt-video-{vid_id}-html.json.gz'
```

--------------------------------

### Retrieve channel playlists with pytubefix

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/channel_playlists.rst.txt

Initializes a Channel object with a URL and prints the list of associated playlist objects.

```python
from pytubefix import Channel

ch = Channel('https://www.youtube.com/@Alanwalkermusic')

print(ch.playlists)
```

--------------------------------

### Handle VideoUnavailable exceptions in a playlist

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/exceptions.rst.txt

Demonstrates how to iterate through a playlist and skip videos that trigger a VideoUnavailable exception.

```python
>>> from pytubefix import Playlist, YouTube
>>> from pytubefix.exceptions import VideoUnavailable
>>> playlist_url = 'https://youtube.com/playlist?list=special_playlist_id'
>>> p = Playlist(playlist_url)
>>> for url in p.video_urls:
...     try:
...         yt = YouTube(url)
...     except VideoUnavailable:
...         print(f'Video {url} is unavaialable, skipping.')
...     else:
...         print(f'Downloading video: {url}')
...         yt.streams.first().download()
```

--------------------------------

### YouTube Class Constructor

Source: https://pytubefix.readthedocs.io/en/latest/api.html

Initializes a new YouTube object to interact with a specific video URL.

```APIDOC
## class pytubefix.YouTube(url, client='ANDROID_VR', ...)

### Description
Initializes the core developer interface for interacting with a YouTube video.

### Parameters
- **url** (str) - Required - The URL of the YouTube video.
- **client** (str) - Optional - The client type (default: 'ANDROID_VR').
- **on_progress_callback** (Callable) - Optional - Callback for download progress.
- **on_complete_callback** (Callable) - Optional - Callback for download completion.
- **proxies** (Dict) - Optional - Proxy settings.
- **use_oauth** (bool) - Optional - Whether to use OAuth.
- **allow_oauth_cache** (bool) - Optional - Whether to cache OAuth tokens.
- **token_file** (str) - Optional - Path to token file.
- **oauth_verifier** (Callable) - Optional - OAuth verification callback.
- **use_po_token** (bool) - Optional - Whether to use PoToken.
- **po_token_verifier** (Callable) - Optional - PoToken verification callback.
```

--------------------------------

### Initialize Search object

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/contrib/search.html

Constructor for the Search class, accepting query parameters and optional authentication or filter configurations.

```python
class Search:
    def __init__(
            self, query: str,
            client: str = InnerTube().client_name,
            proxies: Optional[Dict[str, str]] = None,
            use_oauth: bool = False,
            allow_oauth_cache: bool = True,
            token_file: Optional[str] = None,
            oauth_verifier: Optional[Callable[[str, str], None]] = None,
            use_po_token: Optional[bool] = False,
            po_token_verifier: Optional[Callable[[None], Tuple[str, str]]] = None,
            filters: Optional[Filter] = None
    ):
        """Initialize Search object."""
```

--------------------------------

### Real-time preview with hexdump

Source: https://pytubefix.readthedocs.io/en/latest/user/buffer.html

Inspects the buffer stream in real-time using hexdump.

```bash
$ python3 main.py | hexdump -C
```

--------------------------------

### List available streams

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/cli.rst.txt

Displays all available streams for the specified video URL.

```bash
$ pytubefix https://www.youtube.com/watch?v=2lAe1cqCOXo --list
```

--------------------------------

### metadata(initial_data) -> Optional[YouTubeMetadata]

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/extract.html

Parses the informational metadata for a video from the initial data structure.

```APIDOC
## metadata(initial_data)

### Description
Extracts video metadata (such as Song, Artist, Album) from the provided initial data dictionary.

### Parameters
- **initial_data** (dict) - The parsed `ytInitialData` dictionary from the YouTube watch page.

### Returns
- **YouTubeMetadata** - An object containing the filtered metadata rows from the video secondary info renderer.
```

--------------------------------

### Legacy filter implementation methods

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/contrib/search.html

Methods for building filter configurations using a fluent interface.

```python
@classmethod
def create(cls):
    return cls()

def type(self, t: Type):
    self._type = t
    return self

def upload_date(self, u: UploadDate):
    self._upload_date = u
    return self

def duration(self, d: Duration):
    self._duration = d
    return self

def sort_by(self, s: SortBy):
    self._sort_by = s
    return self

def feature(self, features: List[Features]):
    if isinstance(features, list):
        self._features.update(features)
    else:
        self._features.update([features])
    return self

def merge(self):
    result = {}
    group_2 = {}

    if self._sort_by is not None:
        sort_dict = self._sort_by.value
        if len(sort_dict) != 1 or 1 not in sort_dict:
            raise ValueError("SortBy must have exactly {1: <value>}")
        result[1] = sort_dict[1]

    for val in [self._type, self._upload_date, self._duration]:
        if val is not None:
            for k, v in val.value.items():
                group_2[k] = v

    for f in self._features:
        for k, v in f.value.items():
            group_2[k] = v

    if group_2:
        result[2] = group_2

    logger.debug(f"Combined filters: {result}")

    return str(result)

def __repr__(self):
    return (f"Filter(type={self._type}, upload_date={self._upload_date}, "
            f"duration={self._duration}, sort_by={self._sort_by}, "
            f"features={[f.name for f in self._features]})")
```

--------------------------------

### Initialize InnerTube and Verify Video Access

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/__main__.html

Configures the InnerTube client and performs an age verification check on the video. Raises exceptions if the video is unplayable or requires account verification.

```python
        self.client = 'TV'
        innertube = InnerTube(
            client=self.client,
            use_oauth=self.use_oauth,
            allow_cache=self.allow_oauth_cache,
            token_file=self.token_file,
            oauth_verifier=self.oauth_verifier,
            use_po_token=self.use_po_token,
            po_token_verifier=self.po_token_verifier
        )

        if innertube.require_js_player:
            innertube.innertube_context.update(self.signature_timestamp)

        innertube.verify_age(self.video_id)

        innertube_response = innertube.player(self.video_id)

        playability_status = innertube_response['playabilityStatus'].get('status', None)

        # If we still can't access the video, raise an exception
        if playability_status != 'OK':
            if playability_status == 'UNPLAYABLE':
                raise exceptions.AgeCheckRequiredAccountError(self.video_id)
            else:
                raise exceptions.AgeCheckRequiredError(self.video_id)

        self._vid_info = innertube_response
```

--------------------------------

### Stream to Buffer Implementation

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/streams.html

Writes the media stream directly to a provided binary buffer. Requires an open BinaryIO object.

```python
    def stream_to_buffer(self, buffer: BinaryIO) -> None:
        """Write the media stream to buffer

        :rtype: io.BytesIO buffer
        """
        bytes_remaining = self.filesize
        logger.info(
            "downloading (%s total bytes) file to buffer", self.filesize,
        )

        for chunk in request.stream(self.url):
            # reduce the (bytes) remainder by the length of the chunk.
            bytes_remaining -= len(chunk)
            # send to the on_progress callback.
            self.on_progress(chunk, buffer, bytes_remaining)
        self.on_complete(None)
```

--------------------------------

### Construct Video Info URL

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/extract.html

Builds the get_video_info URL with required parameters for standard and age-restricted videos.

```python
    params = OrderedDict(
        [
            ("video_id", video_id),
            ("ps", "default"),
            ("eurl", quote(watch_url)),
            ("hl", "en_US"),
            ("html5", "1"),
            ("c", "TVHTML5"),
            ("cver", "7.20201028"),
        ]
    )
    return _video_info_url(params)
```

```python
    try:
        sts = regex_search(r'"sts"\s*:\s*(\d+)', embed_html, group=1)
    except RegexMatchError:
        sts = ""
    # Here we use ``OrderedDict`` so that the output is consistent between
    # Python 2.7+.
    eurl = f"https://youtube.googleapis.com/v/{video_id}"
    params = OrderedDict(
        [
            ("video_id", video_id),
            ("eurl", eurl),
            ("sts", sts),
            ("html5", "1"),
            ("c", "TVHTML5"),
            ("cver", "7.20201028"),
        ]
    )
    return _video_info_url(params)
```

--------------------------------

### Importing the YouTube class

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/quickstart.rst.txt

Initial step to access the core functionality of the library.

```python
>>> from pytubefix import YouTube
```

--------------------------------

### Initialize Search and inspect results

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/search.rst.txt

Basic initialization of the Search object and inspection of the initial result set.

```python
>>> from pytubefix import Search
>>> s = Search('YouTube Rewind')
>>> len(s.results)
17
>>> s.results
[\
    <pytubefix.__main__.YouTube object: videoId=YbJOTdZBX1g>, \
    <pytubefix.__main__.YouTube object: videoId=PKtnafFtfEo>, \
    ...\
]
```

--------------------------------

### Importing the Playlist class

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/playlist.rst.txt

Initial import required to access playlist functionality.

```python
>>> from pytubefix import Playlist
```

--------------------------------

### Retrieve video chapters

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/chapters.rst.txt

Initialize a YouTube object and access the chapters attribute to list all available video chapters.

```python
>>> from pytubefix import YouTube
>>> url = 'https://www.youtube.com/watch?v=kRzgCylePjk'
>>> yt = YouTube(url)
>>> print(yt.chapters)
```

--------------------------------

### download(title, srt=True, output_path=None, filename_prefix=None)

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/captions.html

Writes the caption media stream to disk. Supports saving as SRT or XML files.

```APIDOC
## download(title, srt=True, output_path=None, filename_prefix=None)

### Description
Writes the media stream to disk. This method handles the file naming, path resolution, and format conversion for caption files.

### Parameters
- **title** (str) - Required - Output filename (stem only) for writing media file.
- **srt** (bool) - Optional - Set to True to download srt, false to download xml. Defaults to True.
- **output_path** (str or None) - Optional - Output path for writing media file. Defaults to the current working directory.
- **filename_prefix** (str or None) - Optional - A string that will be prepended to the filename.

### Returns
- **str** - The full file path where the caption file was saved.
```

--------------------------------

### Iterate over stream chunks

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/streams.html

Demonstrates how to retrieve media stream data in chunks for custom processing or writing to a file.

```python
# 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))
```

--------------------------------

### Check version

Source: https://pytubefix.readthedocs.io/en/latest/user/cli.html

Displays the current version of the pytubefix CLI.

```bash
$ pytubefix -V
```

--------------------------------

### Initialize CaptionQuery

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/query.html

Constructs a CaptionQuery object by indexing a list of caption instances by their language code.

```python
self.lang_code_index = {c.code: c for c in captions}
```

--------------------------------

### Clone the pytubefix repository

Source: https://pytubefix.readthedocs.io/en/latest/_sources/user/install.rst.txt

Use git to clone the source code directly from the GitHub repository.

```bash
$ git clone git://github.com/JuanBindez/pytubefix.git
```

--------------------------------

### Register Download Callbacks

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/__main__.html

Methods to register custom callback functions for download progress and completion events.

```python
    def register_on_progress_callback(self, func: Callable[[Any, bytes, int], None]):
        """Register a download progress callback function post initialization.

        :param callable func:
            A callback function that takes ``stream``, ``chunk``,
             and ``bytes_remaining`` as parameters.

        :rtype: None

        """
        self.stream_monostate.on_progress = func

    def register_on_complete_callback(self, func: Callable[[Any, Optional[str]], None]):
        """Register a download complete callback function post initialization.
```

--------------------------------

### apply_po_token(stream_manifest: Dict, vid_info: Dict, po_token: str)

Source: https://pytubefix.readthedocs.io/en/latest/_modules/pytubefix/extract.html

Applies the proof of origin (poToken) to the URLs within the provided stream manifest.

```APIDOC
## apply_po_token(stream_manifest: Dict, vid_info: Dict, po_token: str)

### Description
Applies the proof of origin token to the stream manifest by updating the URL query parameters.

### Parameters
- **stream_manifest** (Dict) - Required - Details of the media streams available.
- **vid_info** (Dict) - Required - Video information dictionary.
- **po_token** (str) - Required - Proof of Origin Token.
```
Tokens:
Raw