### youtube-dl Configuration File Example

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

This snippet shows an example of a youtube-dl configuration file. It demonstrates how to specify options like extracting audio, disabling mtime copying, setting a proxy, and defining output file naming conventions. Lines starting with '#' are treated as comments.

```text
# Lines starting with # are comments

# Always extract audio
-x

# Do not copy the mtime
--no-mtime

# Use this proxy
--proxy 127.0.0.1:3128

# Save all videos under Movies directory in your home directory
-o ~/Movies/%(title)s.%(ext)s
```

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

### Install youtube-dl with wget

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Installs youtube-dl for all UNIX users using wget. Requires sudo privileges and write access to /usr/local/bin.

```bash
sudo wget https://yt-dl.org/downloads/latest/youtube-dl -O /usr/local/bin/youtube-dl
sudo chmod a+rx /usr/local/bin/youtube-dl
```

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

### Example URL for Site Support

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Site support requests must include a specific example URL of a video you wish to download. Generic URLs like the main page of a service are not sufficient.

```url
https://www.youtube.com/watch?v=BaW_jenozKc
```

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

### Initialize YoutubeDL Instance

Source: https://github.com/ytdl-org/youtube-dl/blob/master/docs/module_guide.rst

Demonstrates the initial setup for using the youtube_dl library. It involves importing the YoutubeDL class and creating an instance, followed by adding default extractors to enable functionality for various video sites.

```python
from youtube_dl import YoutubeDL
ydl = YoutubeDL()
ydl.add_default_info_extractors()
```

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

### youtube-dl Verbose Output Example

Source: https://github.com/ytdl-org/youtube-dl/blob/master/CONTRIBUTING.md

Demonstrates the expected verbose output when running youtube-dl with the -v flag, crucial for debugging issues. Includes system configuration, command-line arguments, and version information.

```shell
$ youtube-dl -v <your command line>
[debug] System config: []
[debug] User config: []
[debug] Command-line args: [u'-v', u'https://www.youtube.com/watch?v=BaW_jenozKcj']
[debug] Encodings: locale cp1251, fs mbcs, out cp866, pref cp1251
[debug] youtube-dl version 2015.12.06
[debug] Git HEAD: 135392e
[debug] Python version 2.6.6 - Windows-2003Server-5.2.3790-SP2
[debug] exe versions: ffmpeg N-75573-g1d0487f, ffprobe N-75573-g1d0487f, rtmpdump 2.4
[debug] Proxy map: {}
```

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

### Install youtube-dl with curl

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Installs youtube-dl for all UNIX users using curl. Requires sudo privileges and write access to /usr/local/bin.

```bash
sudo curl -L https://yt-dl.org/downloads/latest/youtube-dl -o /usr/local/bin/youtube-dl
sudo chmod a+rx /usr/local/bin/youtube-dl
```

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

### youtube-dl Format Selection Examples

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Demonstrates various ways to select video and audio formats for download using youtube-dl, including merging, filtering by extension, resolution, file size, and protocol.

```bash
# Download best mp4 format available or any other best if no mp4 available
$ youtube-dl -f 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best'
```

```bash
# Download best format available but no better than 480p
$ youtube-dl -f 'bestvideo[height<=480]+bestaudio/best[height<=480]'
```

```bash
# Download best video only format but no bigger than 50 MB
$ youtube-dl -f 'best[filesize<50M]'
```

```bash
# Download best format available via direct link over HTTP/HTTPS protocol
$ youtube-dl -f '(bestvideo+bestaudio/best)[protocol^=http]'
```

```bash
# Download the best video format and the best audio format without merging them
$ youtube-dl -f 'bestvideo,bestaudio' -o '%(title)s.f%(format_id)s.%(ext)s'
```

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

### Print Program Version (--version)

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Prints the current version of the youtube-dl program and exits. This is helpful for troubleshooting or verifying the installed version.

```shell
--version
```

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

### Install youtube-dl with Homebrew

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Installs youtube-dl on macOS using the Homebrew package manager.

```bash
brew install youtube-dl
```

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

### Install youtube-dl with MacPorts

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Installs youtube-dl on macOS using the MacPorts package manager.

```bash
sudo port install youtube-dl
```

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

### Install youtube-dl with pip

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Installs or upgrades youtube-dl using pip. This method requires Python and pip to be installed.

```bash
sudo -H pip install --upgrade youtube-dl
```

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

### Manual Installation/Update Script

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Install or update youtube-dl manually by downloading the latest executable. This method is recommended for users who prefer direct control or when package managers are outdated.

```shell
sudo wget https://yt-dl.org/downloads/latest/youtube-dl -O /usr/local/bin/youtube-dl
sudo chmod a+rx /usr/local/bin/youtube-dl
hash -r
```

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

### Run youtube-dl as Developer

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

To execute youtube-dl directly from a development setup without building, use the Python module execution. This is the recommended way to run the tool when working on its source code.

```python
python -m youtube_dl
```

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

### Handle youtube-dl IDs/Filenames Starting with Hyphen

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

To download videos whose IDs or filenames begin with a hyphen, prepend the full URL or use the '--' separator. This distinguishes the argument from command-line options.

```shell
youtube-dl -- -wNyEUrxzFU
```

```shell
youtube-dl "https://www.youtube.com/watch?v=-wNyEUrxzFU"
```

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

### youtube-dl Date Filtering Examples

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Shows how to filter video downloads based on their upload date using absolute dates (YYYYMMDD) or relative date expressions.

```bash
# Download only the videos uploaded in the last 6 months
$ youtube-dl --dateafter now-6months
```

```bash
# Download only the videos uploaded on January 1, 1970
$ youtube-dl --date 19700101
```

```bash
# Download only the videos uploaded in the 200x decade
$ youtube-dl --dateafter 20000101 --datebefore 20091231
```

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

### Update youtube-dl (Manual/Script)

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Update youtube-dl using the built-in update command. This method is applicable if you installed youtube-dl manually or via a script.

```shell
youtube-dl -U
```

```shell
sudo youtube-dl -U
```

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

### Embed youtube-dl Advanced Configuration

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Provides an advanced example of embedding youtube-dl in Python, showcasing custom logger and progress hooks, and configuring post-processors to convert downloaded audio to MP3 format.

```python
from __future__ import unicode_literals
import youtube_dl


class MyLogger(object):
    def debug(self, msg):
        pass

    def warning(self, msg):
        pass

    def error(self, msg):
        print(msg)


def my_hook(d):
    if d['status'] == 'finished':
        print('Done downloading, now converting ...')


ydl_opts = {
    'format': 'bestaudio/best',
    'postprocessors': [{
        'key': 'FFmpegExtractAudio',
        'preferredcodec': 'mp3',
        'preferredquality': '192',
    }],
    'logger': MyLogger(),
    'progress_hooks': [my_hook],
}
with youtube_dl.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=BaW_jenozKc'])
```

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

### Embed youtube-dl Basic Usage

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Demonstrates how to embed the youtube-dl library in a Python program to download a video. It shows the basic setup using `youtube_dl.YoutubeDL` and the `download` method.

```python
from __future__ import unicode_literals
import youtube_dl

ydl_opts = {}
with youtube_dl.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=BaW_jenozKc'])
```

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

### Default Search Prefix (--default-search)

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Specifies a prefix for unqualified URLs, guiding youtube-dl's search behavior. Options include 'auto' for guessing, 'auto_warning' for guessing with a warning, 'error' to throw an error, and 'fixup_error' to repair broken URLs.

```shell
--default-search PREFIX
```

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

### Python Regex: Flexible HTML Attribute Matching

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Shows how to write flexible regular expressions for parsing HTML attributes. This example tolerates variations in attribute quoting (single vs. double) and skips over potentially changing attributes like 'style'.

```python
title = self._search_regex(
    r'<span[^>]+class="title"[^>]*>([^<]+)', webpage, 'title')
```

```python
title = self._search_regex(
    r'<span[^>]+class=(["\'])title\1[^>]*>(?P<title>[^<]+)',
    webpage, 'title', group='title')
```

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

### Update youtube-dl (pip)

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Update youtube-dl if it was installed using pip. This command ensures you get the latest version from the Python Package Index.

```bash
sudo pip install -U youtube-dl
```

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

### Print Help Text (--help)

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Prints the help text for the youtube-dl program and exits. This is useful for understanding available commands and options.

```shell
-h, --help
```

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

### Setting up .netrc for Authentication

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

This section provides instructions for setting up the .netrc file to store authentication credentials for youtube-dl extractors. It includes commands to create the file, restrict permissions, and the format for adding extractor-specific login and password details.

```bash
touch $HOME/.netrc
chmod a-rwx,u+rw $HOME/.netrc
```

```text
machine <extractor>
login <login>
password <password>
```

```text
machine youtube
login myaccount@gmail.com
password my_youtube_password
```

```text
machine twitch
login my_twitch_account_name
password my_twitch_password
```

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

### Referencing Supported Options

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Review the list of supported options in the project's README before requesting new features. Many requested features may already exist.

```url
https://github.com/ytdl-org/youtube-dl/blob/master/README.md#options
```

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

### Run youtube-dl Tests

Source: https://github.com/ytdl-org/youtube-dl/blob/master/CONTRIBUTING.md

Instructions for running the project's test suite using different Python test runners or directly executing test files.

```shell
python -m unittest discover
```

```shell
python test/test_download.py
```

```shell
nosetests
```

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

### youtube-dl Playlist and Directory Structure

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Shows how to organize downloaded playlist videos into directories based on playlist and video order, and how to structure downloads for channels and series.

```bash
# Download YouTube playlist videos in separate directory indexed by video order
$ youtube-dl -o '%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s' https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re

# Download all playlists of YouTube channel/user keeping each playlist in separate directory
$ youtube-dl -o '%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s' https://www.youtube.com/user/TheLinuxFoundation/playlists

# Download Udemy course keeping each chapter in separate directory
$ youtube-dl -u user -p password -o '~/MyVideos/%(playlist)s/%(chapter_number)s - %(chapter)s/%(title)s.%(ext)s' https://www.udemy.com/java-tutorial/

# Download entire series season keeping each series and each season in separate directory
$ youtube-dl -o "C:/MyVideos/%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s" https://videomore.ru/kino_v_detalayah/5_sezon/367617
```

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

### Playlist Navigation Options

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Control which videos are downloaded from a playlist by specifying start, end, or specific item indices. These options are crucial for targeted playlist downloads.

```APIDOC
--playlist-start NUMBER
    Playlist video to start at (default is 1)

--playlist-end NUMBER
    Playlist video to end at (default is last)

--playlist-items ITEM_SPEC
    Playlist video items to download. Specify indices of the videos in the playlist separated by commas like: "--playlist-items 1,2,5,8" if you want to download videos indexed 1, 2, 5, 8 in the playlist. You can specify range: "--playlist-items 1-3,7,10-13", it will download the videos at index 1, 2, 3, 7, 10, 11, 12 and 13.
```

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

### Run youtube-dl as Developer

Source: https://github.com/ytdl-org/youtube-dl/blob/master/CONTRIBUTING.md

Execute youtube-dl directly from the source code without building. This is the recommended method for development.

```shell
python -m youtube_dl
```

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

### Configuration Location (--config-location)

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Specifies the path to the configuration file or its containing directory. This allows users to manage custom settings for youtube-dl.

```shell
--config-location PATH
```

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

### Python: Inline Variable Extraction Example

Source: https://github.com/ytdl-org/youtube-dl/blob/master/CONTRIBUTING.md

Advises against extracting variables that are used only once and moving them far from their usage. This promotes linear code flow and improves readability by keeping related logic together.

```python
title = self._html_search_regex(r'<title>([^<]+)</title>', webpage, 'title')
```

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

### Git Commands for Contributing

Source: https://github.com/ytdl-org/youtube-dl/blob/master/CONTRIBUTING.md

Essential Git commands for cloning the repository, creating a new branch for development, and staging/committing changes.

```Shell
git clone git@github.com:YOUR_GITHUB_USERNAME/youtube-dl.git
```

```Shell
cd youtube-dl
git checkout -b yourextractor
```

```Shell
git add youtube_dl/extractor/extractors.py
git add youtube_dl/extractor/yourextractor.py
git commit -m "[yourextractor] Add new extractor"
git push origin yourextractor
```

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

### Extractor Descriptions (--extractor-descriptions)

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Provides detailed descriptions for all supported extractors. This offers insight into the capabilities and specific behaviors of each extractor.

```shell
--extractor-descriptions
```

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

### Setting HOME Environment Variable on Windows

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

This snippet shows how to manually set the HOME environment variable on Windows systems, which may be necessary for the .netrc file to be recognized correctly by youtube-dl.

```bash
set HOME=%USERPROFILE%
```

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

### Run youtube-dl from Source

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Explains how to execute the youtube-dl script directly from the source code, typically after cloning the repository or unzipping the archive.

```python
__main__.py
```

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

### Netscape Cookie File Structure

Source: https://github.com/ytdl-org/youtube-dl/blob/master/test/testdata/cookies/session_cookies.txt

The Netscape HTTP Cookie File format is a plain text file that stores HTTP cookies. Each line represents a single cookie, with fields separated by tabs. Comments start with a '#'.

```CookieFile
# Netscape HTTP Cookie File
# http://curl.haxx.se/rfc/cookie_spec.html
# This is a generated file!  Do not edit.

www.foobar.foobar	FALSE	/	TRUE		YoutubeDLExpiresEmpty	YoutubeDLExpiresEmptyValue
www.foobar.foobar	FALSE	/	TRUE	0	YoutubeDLExpires0	YoutubeDLExpires0Value
```

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

### Testing and Linting Commands

Source: https://github.com/ytdl-org/youtube-dl/blob/master/CONTRIBUTING.md

Commands to run tests for the new extractor and to check code quality using flake8.

```Shell
python test/test_download.py TestDownload.test_YourExtractor
```

```Shell
$ flake8 youtube_dl/extractor/yourextractor.py
```

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

### Python: Long Lines Policy Example

Source: https://github.com/ytdl-org/youtube-dl/blob/master/CONTRIBUTING.md

Highlights the policy of keeping lines under 80 characters where possible without sacrificing readability. It specifically advises against splitting long string literals like URLs, prioritizing the integrity of such data.

```python
'https://www.youtube.com/watch?v=FqZTN594JQw&list=PLMYEtVRpaqY00V9W81Cwmzp6N6vZqfUKD4'
```

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

### Python: Collapsing Multiple Fallbacks

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Demonstrates how to consolidate multiple fallback data extraction calls into a single, more readable expression by using methods that accept a list of patterns or keys.

```python
description = self._html_search_meta(
    ['og:description', 'description', 'twitter:description'],
    webpage, 'description', default=None)
```

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

### Netscape HTTP Cookie File Format Specification

Source: https://github.com/ytdl-org/youtube-dl/blob/master/test/testdata/cookies/malformed_cookies.txt

Defines the structure of Netscape HTTP Cookie Files, used for storing HTTP cookies. It specifies the fields required for each cookie entry and provides examples of valid and invalid formats.

```APIDOC
Netscape HTTP Cookie File Format
Reference: http://curl.haxx.se/rfc/cookie_spec.html

Format:
Each line represents a cookie entry and follows a specific field structure.

Fields:
1. Domain: The domain name that the cookie belongs to.
2. Domain_Is_AD: A boolean indicating if the Domain field is a domain-is-a-wildcard.
3. Path: The path on the server where the cookie is valid.
4. Secure: A boolean indicating if the cookie should only be sent over secure (HTTPS) connections.
5. Expires: The expiration date and time of the cookie (Unix timestamp).
6. Name: The name of the cookie.
7. Value: The value of the cookie.

Example Entries:

# Cookie file entry with invalid number of fields - 6 instead of 7
www.foobar.foobar	FALSE	/	FALSE	0	COOKIE

# Cookie file entry with invalid expires at
www.foobar.foobar	FALSE	/	FALSE	1.7976931348623157e+308	COOKIE	VALUE

```

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

### youtube-dl Verbose Output for Bug Reports

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Illustrates the expected output format when running youtube-dl with the `-v` flag, which is crucial for debugging and reporting issues effectively. This output includes system configuration, command-line arguments, and version information.

```shell
$ youtube-dl -v <your command line>
[debug] System config: []
[debug] User config: []
[debug] Command-line args: [u'-v', u'https://www.youtube.com/watch?v=BaW_jenozKcj']
[debug] Encodings: locale cp1251, fs mbcs, out cp866, pref cp1251
[debug] youtube-dl version 2015.12.06
[debug] Git HEAD: 135392e
[debug] Python version 2.6.6 - Windows-2003Server-5.2.3790-SP2
[debug] exe versions: ffmpeg N-75573-g1d0487f, ffprobe N-75573-g1d0487f, rtmpdump 2.4
[debug] Proxy map: {}
...
```

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

### Python: Fallback Field Extraction

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Illustrates a fallback mechanism for extracting data. It first attempts to get a value from a primary source (e.g., a dictionary) and, if that fails or returns a falsy value, it tries an alternative extraction method.

```python
title = meta.get('title') or self._og_search_title(webpage)
```

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

### youtube-dl Filesystem Options

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Provides details on youtube-dl's command-line arguments for managing downloaded files, including batch processing, output templating, overwrite behavior, resuming downloads, metadata extraction, and cache management.

```APIDOC
-a, --batch-file FILE
  File containing URLs to download ('-' for stdin), one URL per line. Lines starting with '#', ';' or ']' are considered as comments and ignored.

--id
  Use only video ID in file name.

-o, --output TEMPLATE
  Output filename template. See the "OUTPUT TEMPLATE" for all the info.

--output-na-placeholder PLACEHOLDER
  Placeholder value for unavailable meta fields in output filename template (default is "NA").

--autonumber-start NUMBER
  Specify the start value for %(autonumber)s (default is 1).

--restrict-filenames
  Restrict filenames to only ASCII characters, and avoid "&" and spaces in filenames.

-w, --no-overwrites
  Do not overwrite files.

-c, --continue
  Force resume of partially downloaded files. By default, youtube-dl will resume downloads if possible.

--no-continue
  Do not resume partially downloaded files (restart from beginning).

--no-part
  Do not use .part files - write directly into output file.

--no-mtime
  Do not use the Last-modified header to set the file modification time.

--write-description
  Write video description to a .description file.

--write-info-json
  Write video metadata to a .info.json file.

--write-annotations
  Write video annotations to a .annotations.xml file.

--load-info-json FILE
  JSON file containing the video information (created with the "--write-info-json" option).

--cookies FILE
  File to read cookies from and dump cookie jar in.

--cache-dir DIR
  Location in the filesystem where youtube-dl can store some downloaded information permanently. By default $XDG_CACHE_HOME/youtube-dl or ~/.cache/youtube-dl. At the moment, only YouTube player files (for videos with obfuscated signatures) are cached, but that may change.

--no-cache-dir
  Disable filesystem caching.

--rm-cache-dir
  Delete all filesystem cache files.
```

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

### youtube-dl Basic Usage

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

The fundamental command-line syntax for youtube-dl to download videos from specified URLs. It accepts various options to customize the download process.

```bash
youtube-dl [OPTIONS] URL [URL...]
```

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

### Update Program (--update)

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Updates the youtube-dl program to the latest available version. It's recommended to run this with sufficient permissions, such as using 'sudo'.

```shell
-U, --update
```

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

### Testing and Linting a New Extractor

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Commands to run tests for the new extractor and to check code quality using flake8, ensuring compliance with youtube-dl's coding conventions.

```shell
# Run tests for the new extractor
python test/test_download.py TestDownload.test_YourExtractor

# Check code quality with flake8
flake8 youtube_dl/extractor/yourextractor.py
```

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

### Specify Output Folder with youtube-dl

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Use the -o option to specify an output template for downloads. This allows customization of filenames and directory structures using placeholders like %(title)s, %(id)s, and %(ext)s. For persistent settings, place the option in the configuration file.

```shell
youtube-dl -o "/home/user/videos/%(title)s-%(id)s.%(ext)s"
```

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

### Proxy Configuration (--proxy)

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Specifies a URL for an HTTP, HTTPS, or SOCKS proxy. For SOCKS proxies, a proper scheme like 'socks5://' must be provided. An empty string ('--proxy ""') forces a direct connection.

```shell
--proxy URL
```

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

### Python: Collapsing Fallback Values

Source: https://github.com/ytdl-org/youtube-dl/blob/master/CONTRIBUTING.md

Demonstrates how to consolidate multiple fallback extraction methods into a single, more manageable call by passing a list of patterns or keys to supported helper functions.

```python
description = self._html_search_meta(
    ['og:description', 'description', 'twitter:description'],
    webpage, 'description', default=None)
```

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

### List Extractors (--list-extractors)

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Outputs a list of all supported video extractors. This helps users identify which websites or services youtube-dl can download from.

```shell
--list-extractors
```

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

### Collecting Diagnostics with --call-home

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

If your server has multiple IPs or you suspect censorship, using the `--call-home` flag can provide additional diagnostics. This helps in identifying network-related issues or censorship effects.

```shell
--call-home
```

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

### Recompile youtube-dl Executable

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Instructions on how to recompile the youtube-dl executable from its source code. This is useful if you have modified the code or need to build a fresh executable.

```shell
make youtube-dl
```

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

### Test URL Support via CLI

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

To determine if a URL is supported by youtube-dl, execute the command with the verbose flag. If the URL is unsupported or does not refer to a video, youtube-dl will indicate this in its output.

```shell
youtube-dl -v "YOUR_URL_HERE"
```

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

### Searching Existing GitHub Issues

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Before opening a new issue, search the project's GitHub Issues page. Use terms like `-label:duplicate` to filter out already addressed or duplicate reports.

```url
https://github.com/ytdl-org/youtube-dl/search?type=Issues
```

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

### Execute Command

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Option to execute a custom command on the file after download and post-processing.

```APIDOC
--exec CMD
    Execute a command on the file after downloading and post-processing, similar to find's -exec syntax.
    Example: --exec 'adb push {} /sdcard/Music/ && rm {}'
```

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

### youtube-dl Debugging Flags

Source: https://github.com/ytdl-org/youtube-dl/blob/master/CONTRIBUTING.md

Optional flags for enhanced debugging. `--call-home` can provide more diagnostics, while `--dump-pages` and `--write-pages` capture page content for analysis, especially for extraction errors.

```shell
--call-home
```

```shell
--dump-pages >log.txt 2>&1
```

```shell
--write-pages
```

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

### youtube-dl Output Template Escaping and stdout

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Explains how to escape percent characters for use within Windows batch files and how to direct output to stdout.

```bash
# Escaping percent literals in Windows batch files
# Original: -o "% (title)s-%(id)s.%(ext)s"
# Escaped: -o "%%(title)s-%%(id)s.%%(ext)s"
# Environment variables remain untouched: -o "C:\%HOMEPATH%\Desktop\%%(title)s.%%(ext)s"

# Stream the video being downloaded to stdout
$ youtube-dl -o - BaW_jenozKc
```

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

### Run youtube-dl Tests

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

youtube-dl provides several methods for running its test suite. You can use Python's built-in unittest module, execute specific test files, or use the nosetests runner.

```shell
python -m unittest discover
```

```shell
python test/test_download.py
```

```shell
nosetests
```

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

### youtube-dl Thumbnail Options

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Details the command-line options available in youtube-dl for downloading and listing video thumbnail images in various formats.

```APIDOC
--write-thumbnail
  Write thumbnail image to disk.

--write-all-thumbnails
  Write all thumbnail image formats to disk.

--list-thumbnails
  Simulate and list all available thumbnail formats.
```

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

### Verbosity and Simulation Options

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Controls the verbosity of youtube-dl's output and enables simulation modes to preview actions without downloading. Includes options to print URLs, titles, JSON data, and manage progress display.

```APIDOC
-q, --quiet
    Activate quiet mode.

--no-warnings
    Ignore warnings.

-s, --simulate
    Do not download the video and do not write anything to disk.

--skip-download
    Do not download the video.

-g, --get-url
    Simulate, quiet but print URL.

-e, --get-title
    Simulate, quiet but print title.

--get-id
    Simulate, quiet but print id.

--get-thumbnail
    Simulate, quiet but print thumbnail URL.

--get-description
    Simulate, quiet but print video description.

--get-duration
    Simulate, quiet but print video length.

--get-filename
    Simulate, quiet but print output filename.

--get-format
    Simulate, quiet but print output format.

-j, --dump-json
    Simulate, quiet but print JSON information. See the "OUTPUT TEMPLATE" for a description of available keys.

-J, --dump-single-json
    Simulate, quiet but print JSON information for each command-line argument. If the URL refers to a playlist, dump the whole playlist information in a single line.

--print-json
    Be quiet and print the video information as JSON (video is still being downloaded).

--newline
    Output progress bar as new lines.

--no-progress
    Do not print progress bar.

--console-title
    Display progress in console titlebar.

-v, --verbose
    Print various debugging information.

--dump-pages
    Print downloaded pages encoded using base64 to debug problems (very verbose).

--write-pages
    Write downloaded intermediary pages to files in the current directory to debug problems.

--print-traffic
    Display sent and read HTTP traffic.

-C, --call-home
    Contact the youtube-dl server for debugging.

--no-call-home
    Do NOT contact the youtube-dl server for debugging.
```

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

### Handle Regex Extraction Failures Gracefully with default

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Illustrates using `_search_regex` with a `default` value to provide a fallback when a pattern is not found. This allows extraction to continue silently with the specified default.

```python
description = self._search_regex(
    r'<span[^>]+id="title"[^>]*>([^<]+)<',
    webpage, 'description', default=None)

```

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

### youtube-dl Basic Output and Filename Restriction

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Demonstrates how to specify output filenames using template variables and the effect of `--restrict-filenames` on handling special characters.

```bash
# Example with special characters
$ youtube-dl --get-filename -o '%(title)s.%(ext)s' BaW_jenozKc
youtube-dl test video ''_ä↭𝕐.mp4

# Example with restricted filenames
$ youtube-dl --get-filename -o '%(title)s.%(ext)s' BaW_jenozKc --restrict-filenames
youtube-dl_test_video_.mp4
```

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

### General Post-processing Options

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Options to control the core post-processing workflow, including extracting audio and managing intermediate files.

```APIDOC
-x, --extract-audio
    Convert video files to audio-only files.
    Requires ffmpeg/avconv and ffprobe/avprobe.

-k, --keep-video
    Keep the video file on disk after post-processing.
    The video is erased by default.

--no-post-overwrites
    Do not overwrite post-processed files.
    Post-processed files are overwritten by default.
```

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

### Git Workflow for Adding a New Extractor

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

These Git commands are used to set up a new branch, commit changes, and push them to a remote repository when adding a new extractor to youtube-dl.

```git
git clone git@github.com:YOUR_GITHUB_USERNAME/youtube-dl.git
cd youtube-dl
git checkout -b yourextractor

# After making changes to extractor files:
git add youtube_dl/extractor/extractors.py
git add youtube_dl/extractor/yourextractor.py
git commit -m '[yourextractor] Add new extractor'
git push origin yourextractor
```

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

### Postprocessor Arguments and Subtitle Conversion

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Options to pass custom arguments to postprocessors and convert subtitle files to different formats.

```APIDOC
--postprocessor-args ARGS
    Give these arguments to the postprocessor.

--convert-subs FORMAT
    Convert the subtitles to other formats.
    Currently supported formats: srt|ass|vtt|lrc.
```

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

### Handle Regex Extraction Failures Gracefully with fatal=False

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Shows how to use `_search_regex` with `fatal=False` to avoid breaking extraction when a pattern is not found. The extractor will emit a warning and continue.

```python
description = self._search_regex(
    r'<span[^>]+id="title"[^>]*>([^<]+)<',
    webpage, 'description', fatal=False)

```

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

### Platzi Extractors

Source: https://github.com/ytdl-org/youtube-dl/blob/master/docs/supportedsites.md

Supports downloading courses and content from Platzi, an online learning platform focused on technology and digital skills.

```APIDOC
Platzi:
  Description: Platzi online learning platform.
  Scope: Downloads general content from Platzi.
```

```APIDOC
PlatziCourse:
  Description: Platzi Courses.
  Scope: Downloads video lessons and materials from Platzi courses.
```

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

### youtube-dl Authentication Options

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Options for user authentication. Supports username/password login, two-factor authentication codes, and using .netrc files for credentials. Also includes options for video-specific passwords.

```APIDOC
-u, --username USERNAME
  Login with this account ID.

-p, --password PASSWORD
  Account password. If this option is left out, youtube-dl will ask interactively.

-2, --twofactor TWOFACTOR
  Two-factor authentication code.

-n, --netrc
  Use .netrc authentication data.

--video-password PASSWORD
  Video password (vimeo, youku).
```

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

### Writing Page Dumps for Analysis

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

When encountering extraction errors, `--write-pages` can generate `.dump` files. Upload these files to a service like Gist for developers to analyze the raw page data.

```shell
--write-pages
```

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

### youtube-dl Output Template Variables

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Defines available metadata sequences (template variables) for customizing output filenames. These variables are replaced with actual values from the downloaded media's metadata. Their presence depends on the extractor and metadata availability, with a placeholder used for missing values via `--output-na-placeholder`.

```APIDOC
Output Template Variables:

General:
  %(title)s: Title of the video
  %(id)s: Video ID
  %(ext)s: File extension
  %(upload_date)s: Upload date (YYYYMMDD)
  %(uploader)s: Uploader name
  %(uploader_id)s: Uploader ID
  %(view_count)s: Number of views
  %(like_count)s: Number of likes
  %(dislike_count)s: Number of dislikes
  %(channel_id)s: Channel ID
  %(channel_url)s: Channel URL
  %(playlist)s: Playlist title
  %(playlist_index)s: Index of the video in the playlist
  %(playlist_title)s: Title of the playlist
  %(playlist_id)s: ID of the playlist
  %(playlist_uploader)s: Uploader of the playlist
  %(playlist_uploader_id)s: Uploader ID of the playlist
  %(chapter)s: Chapter title
  %(chapter_number)s: Chapter number
  %(season)s: Season title
  %(season_number)s: Season number
  %(episode)s: Episode title
  %(episode_number)s: Episode number
  %(series)s: Series title
  %(release_year)s: Year of release

Media Specific (Tracks/Albums):
  %(episode_id)s: Id of the video episode
  %(track)s: Title of the track
  %(track_number)s: Number of the track within an album or a disc
  %(track_id)s: Id of the track
  %(artist)s: Artist(s) of the track
  %(genre)s: Genre(s) of the track
  %(album)s: Title of the album the track belongs to
  %(album_type)s: Type of the album
  %(album_artist)s: List of all artists appeared on the album
  %(disc_number)s: Number of the disc or other physical medium the track belongs to

Numeric Formatting:
  Use standard Python format specifiers, e.g., `%(view_count)05d` for zero-padding to 5 digits.

Special Characters Handling:
  Use `--restrict-filenames` to sanitize filenames for systems with limited character support.

Output to stdout:
  Use `-o -` to stream output to standard output.
```

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

### RayWenderlich Extractors

Source: https://github.com/ytdl-org/youtube-dl/blob/master/docs/supportedsites.md

Supports downloading content from RayWenderlich.com, a platform for learning programming and app development, including courses.

```APIDOC
RayWenderlich:
  Description: RayWenderlich.com content.
  Scope: Downloads articles and tutorials from the platform.
```

```APIDOC
RayWenderlichCourse:
  Description: RayWenderlich.com Courses.
  Scope: Downloads video lessons and materials from RayWenderlich courses.
```

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

### QuantumTV Extractor

Source: https://github.com/ytdl-org/youtube-dl/blob/master/docs/supportedsites.md

Supports downloading content from QuantumTV, a platform for video content.

```APIDOC
QuantumTV:
  Description: QuantumTV video platform.
  Scope: Downloads videos from QuantumTV.
```

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

### Safely Extract Optional Metadata from Dictionary

Source: https://github.com/ytdl-org/youtube-dl/blob/master/README.md

Demonstrates the correct way to extract an optional field from a dictionary using `.get()` to prevent `KeyError` if the key is missing. This ensures extraction continues gracefully.

```python
description = meta.get('summary')  # correct
```