CodeVetter · Repo Unpack · Feature catalog
ytdl-org/youtube-dl
User-facing surface = one CLI command `youtube-dl` with ~200 options defined in options.py plus the embeddable YoutubeDL API. Features cluster around: site extraction (~1200 supported sites), format/playlist/subtitle selection, sidecar file output (info JSON, description, annotations, thumbnails), ffmpeg-based postprocessing (audio extraction, recoding, embedding), authentication (username/password, netrc, video passwords, Adobe Pass TV providers), geo-restriction bypass, external downloaders, self-update, and simulation/printing modes for scripting.
- Site support: ~810 extractor modules under youtube_dl/extractor/ back roughly 1225 documented sites in docs/supportedsites.md; `--list-extractors` and `--extractor-descriptions` enumerate them at runtime via list_extractors().
- Format selection via `-f/--format` implements a mini-DSL (best/worst, format_id, filters like `[height<=?720]`, merge with `+`, fallback with `/`, groups) parsed by `YoutubeDL.build_format_selector` into selector functions.
- Playlist features include --playlist-start/--playlist-end, --playlist-items (comma list/ranges), --playlist-reverse, --playlist-random, --max-downloads, and --flat-playlist (extract_flat), implemented in __process_playlist.
- Subtitle support: --write-sub/--write-auto-subs/--all-subs/--list-subs download or enumerate subtitle tracks, with --sub-format and --sub-langs filtering in process_subtitles; --convert-subs converts to srt/ass/vtt/lrc via FFmpegSubtitlesConvertorPP.
- Audio extraction `-x/--extract-audio` appends an FFmpegExtractAudio postprocessor honoring --audio-format (best/aac/flac/mp3/m4a/opus/vorbis/wav) and --audio-quality; recoding via --recode-video maps to FFmpegVideoConvertorPP.
- Sidecar outputs: --write-info-json, --write-description, --write-annotations, --write-thumbnail/--write-all-thumbnails, and --xattrs (filesystem extended attributes) are all emitted from process_info/_write_info_json/_write_thumbnails.
- --download-archive records `extractor_key + ' ' + video_id` lines (via _make_archive_id) into a text file; in_download_archive checks it inside _match_entry to skip already-downloaded videos; writes go through locked_file for interprocess safety.
- Authentication options cover --username/--password (+ interactive getpass when password omitted), --twofactor, --netrc, --video-password, and Adobe Pass TV-provider login via --ap-mso/--ap-username/--ap-password with --ap-list-mso listing MSO_INFO providers.
- Self-update: `-U/--update` invokes update_self(), which only applies to the zip/frozen builds, verifies a pinned RSA signature over versions.json, then sha256-checks and replaces the running binary (via a .bat swap on Windows).
- Geo-bypass fakes an X-Forwarded-For header with a random IP drawn from per-extractor _GEO_COUNTRIES/_GEO_IP_BLOCKS or --geo-bypass-country/--geo-bypass-ip-block, with automatic retry on GeoRestrictedError inside InfoExtractor.extract.
- External downloaders: --external-downloader selects among aria2c, aria2p (JSON-RPC library), axel, curl, ffmpeg/avconv, httpie and wget; each ExternalFD subclass builds a CLI via _make_cmd and runs it with subprocess.Popen; --external-downloader-args injects extra args.
- Simulation/inspection modes: --simulate, --skip-download, --dump-json/--dump-single-json, --print-json, --get-url/--get-title/--get-id/--get-filename family, --list-formats and --list-thumbnails, plus --load-info-json to reprocess a saved info dict.
- Output templating `-o` supports %(field)s substitution over the info dict (plus `epoch`, `autonumber`), NA placeholders, numeric-field format patching, env-var/`~` expansion, and `outtmpl='-'` to stream media to stdout.
- --exec CMD registers ExecAfterDownloadPP which substitutes `{}` with the shlex-quoted final filepath and runs the command through the system shell after all other postprocessing.
- Rate/robustness controls: --limit-rate (throttling via FileDownloader.slow_down), --retries/--fragment-retries (incl. 'inf'), --sleep-interval/--max-sleep-interval randomized delays, --http-chunk-size segmented downloading, --buffer-size and --no-resize-buffer adaptive block sizing.