README.md

   1 [![PyPi](https://img.shields.io/pypi/v/youtube-dlc.svg)](https://pypi.org/project/youtube-dlc)
   2 [![Build Status](https://travis-ci.com/blackjack4494/youtube-dlc.svg?branch=master)](https://travis-ci.com/blackjack4494/youtube-dlc)
   3 [![Downloads](https://pepy.tech/badge/youtube-dlc)](https://pepy.tech/project/youtube-dlc)
   4
   5 [![Gitter chat](https://badges.gitter.im/youtube-dlc/gitter.png)](https://gitter.im/youtube-dlc)
   6 [![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](https://github.com/blackjack4494/youtube-dlc/blob/master/LICENSE)
   7
   8 youtube-dlc - download videos from youtube.com or other video platforms.
   9
  10 youtube-dlc is a fork of youtube-dl with the intention of getting features tested by the community merged in the tool faster, since youtube-dl's development seems to be slowing down. (https://github.com/ytdl-org/youtube-dl/issues/26462)
  11
  12 - [INSTALLATION](#installation)
  13 - [DESCRIPTION](#description)
  14 - [OPTIONS](#options)
  15   - [Network Options:](#network-options)
  16   - [Geo Restriction:](#geo-restriction)
  17   - [Video Selection:](#video-selection)
  18   - [Download Options:](#download-options)
  19   - [Filesystem Options:](#filesystem-options)
  20   - [Thumbnail images:](#thumbnail-images)
  21   - [Verbosity / Simulation Options:](#verbosity--simulation-options)
  22   - [Workarounds:](#workarounds)
  23   - [Video Format Options:](#video-format-options)
  24   - [Subtitle Options:](#subtitle-options)
  25   - [Authentication Options:](#authentication-options)
  26   - [Adobe Pass Options:](#adobe-pass-options)
  27   - [Post-processing Options:](#post-processing-options)
  28   - [Extractor Options:](#extractor-options)
  29
  30 # INSTALLATION
  31
  32 **All Platforms**
  33 Preferred way using pip:
  34 You may want to use `python3` instead of `python`
  35
  36     python -m pip install --upgrade youtube-dlc
  37
  38 **UNIX** (Linux, macOS, etc.)
  39 Using wget:
  40
  41     sudo wget https://github.com/blackjack4494/youtube-dlc/releases/latest/download/youtube-dlc -O /usr/local/bin/youtube-dlc
  42     sudo chmod a+rx /usr/local/bin/youtube-dlc
  43
  44 Using curl:
  45
  46     sudo curl -L https://github.com/blackjack4494/youtube-dlc/releases/latest/download/youtube-dlc -o /usr/local/bin/youtube-dlc
  47     sudo chmod a+rx /usr/local/bin/youtube-dlc
  48
  49
  50 **Windows** users can download [youtube-dlc.exe](https://github.com/blackjack4494/youtube-dlc/releases/latest/download/youtube-dlc.exe) (**do not** put in `C:\Windows\System32`!).
  51
  52 **Compile**
  53 To build the Windows executable yourself
  54
  55     python -m pip install --upgrade pyinstaller
  56     pyinstaller.exe youtube_dlc\__main__.py --onefile --name youtube-dlc
  57
  58 Or simply execute the `make_win.bat` if pyinstaller is installed.
  59 There will be a `youtube-dlc.exe` in `/dist`
  60
  61 For Unix:
  62 You will need the required build tools
  63 python, make (GNU), pandoc, zip, nosetests
  64 Then simply type this
  65
  66     make
  67
  68
  69 # DESCRIPTION
  70 **youtube-dlc** is a command-line program to download videos from YouTube.com and a few more sites. It requires the Python interpreter, version 2.6, 2.7, or 3.2+, and it is not platform specific. It should work on your Unix box, on Windows or on macOS. It is released to the public domain, which means you can modify it, redistribute it or use it however you like.
  71
  72     youtube-dlc [OPTIONS] URL [URL...]
  73
  74 # OPTIONS
  75     -h, --help                       Print this help text and exit
  76     --version                        Print program version and exit
  77     -U, --update                     Update this program to latest version. Make
  78                                      sure that you have sufficient permissions
  79                                      (run with sudo if needed)
  80     -i, --ignore-errors              Continue on download errors, for example to
  81                                      skip unavailable videos in a playlist
  82     --abort-on-error                 Abort downloading of further videos (in the
  83                                      playlist or the command line) if an error
  84                                      occurs
  85     --dump-user-agent                Display the current browser identification
  86     --list-extractors                List all supported extractors
  87     --extractor-descriptions         Output descriptions of all supported
  88                                      extractors
  89     --force-generic-extractor        Force extraction to use the generic
  90                                      extractor
  91     --default-search PREFIX          Use this prefix for unqualified URLs. For
  92                                      example "gvsearch2:" downloads two videos
  93                                      from google videos for youtube-dlc "large
  94                                      apple". Use the value "auto" to let
  95                                      youtube-dlc guess ("auto_warning" to emit a
  96                                      warning when guessing). "error" just throws
  97                                      an error. The default value "fixup_error"
  98                                      repairs broken URLs, but emits an error if
  99                                      this is not possible instead of searching.
 100     --ignore-config                  Do not read configuration files. When given
 101                                      in the global configuration file
 102                                      /etc/youtube-dlc.conf: Do not read the user
 103                                      configuration in ~/.config/youtube-
 104                                      dlc/config (%APPDATA%/youtube-
 105                                      dlc/config.txt on Windows)
 106     --config-location PATH           Location of the configuration file; either
 107                                      the path to the config or its containing
 108                                      directory.
 109     --flat-playlist                  Do not extract the videos of a playlist,
 110                                      only list them.
 111     --mark-watched                   Mark videos watched (YouTube only)
 112     --no-mark-watched                Do not mark videos watched (YouTube only)
 113     --no-color                       Do not emit color codes in output
 114
 115 ## Network Options:
 116     --proxy URL                      Use the specified HTTP/HTTPS/SOCKS proxy.
 117                                      To enable SOCKS proxy, specify a proper
 118                                      scheme. For example
 119                                      socks5://127.0.0.1:1080/. Pass in an empty
 120                                      string (--proxy "") for direct connection
 121     --socket-timeout SECONDS         Time to wait before giving up, in seconds
 122     --source-address IP              Client-side IP address to bind to
 123     -4, --force-ipv4                 Make all connections via IPv4
 124     -6, --force-ipv6                 Make all connections via IPv6
 125
 126 ## Geo Restriction:
 127     --geo-verification-proxy URL     Use this proxy to verify the IP address for
 128                                      some geo-restricted sites. The default
 129                                      proxy specified by --proxy (or none, if the
 130                                      option is not present) is used for the
 131                                      actual downloading.
 132     --geo-bypass                     Bypass geographic restriction via faking
 133                                      X-Forwarded-For HTTP header
 134     --no-geo-bypass                  Do not bypass geographic restriction via
 135                                      faking X-Forwarded-For HTTP header
 136     --geo-bypass-country CODE        Force bypass geographic restriction with
 137                                      explicitly provided two-letter ISO 3166-2
 138                                      country code
 139     --geo-bypass-ip-block IP_BLOCK   Force bypass geographic restriction with
 140                                      explicitly provided IP block in CIDR
 141                                      notation
 142
 143 ## Video Selection:
 144     --playlist-start NUMBER          Playlist video to start at (default is 1)
 145     --playlist-end NUMBER            Playlist video to end at (default is last)
 146     --playlist-items ITEM_SPEC       Playlist video items to download. Specify
 147                                      indices of the videos in the playlist
 148                                      separated by commas like: "--playlist-items
 149                                      1,2,5,8" if you want to download videos
 150                                      indexed 1, 2, 5, 8 in the playlist. You can
 151                                      specify range: "--playlist-items
 152                                      1-3,7,10-13", it will download the videos
 153                                      at index 1, 2, 3, 7, 10, 11, 12 and 13.
 154     --match-title REGEX              Download only matching titles (regex or
 155                                      caseless sub-string)
 156     --reject-title REGEX             Skip download for matching titles (regex or
 157                                      caseless sub-string)
 158     --max-downloads NUMBER           Abort after downloading NUMBER files
 159     --min-filesize SIZE              Do not download any videos smaller than
 160                                      SIZE (e.g. 50k or 44.6m)
 161     --max-filesize SIZE              Do not download any videos larger than SIZE
 162                                      (e.g. 50k or 44.6m)
 163     --date DATE                      Download only videos uploaded in this date
 164     --datebefore DATE                Download only videos uploaded on or before
 165                                      this date (i.e. inclusive)
 166     --dateafter DATE                 Download only videos uploaded on or after
 167                                      this date (i.e. inclusive)
 168     --min-views COUNT                Do not download any videos with less than
 169                                      COUNT views
 170     --max-views COUNT                Do not download any videos with more than
 171                                      COUNT views
 172     --match-filter FILTER            Generic video filter. Specify any key (see
 173                                      the "OUTPUT TEMPLATE" for a list of
 174                                      available keys) to match if the key is
 175                                      present, !key to check if the key is not
 176                                      present, key > NUMBER (like "comment_count
 177                                      > 12", also works with >=, <, <=, !=, =) to
 178                                      compare against a number, key = 'LITERAL'
 179                                      (like "uploader = 'Mike Smith'", also works
 180                                      with !=) to match against a string literal
 181                                      and & to require multiple matches. Values
 182                                      which are not known are excluded unless you
 183                                      put a question mark (?) after the operator.
 184                                      For example, to only match videos that have
 185                                      been liked more than 100 times and disliked
 186                                      less than 50 times (or the dislike
 187                                      functionality is not available at the given
 188                                      service), but who also have a description,
 189                                      use --match-filter "like_count > 100 &
 190                                      dislike_count <? 50 & description" .
 191     --no-playlist                    Download only the video, if the URL refers
 192                                      to a video and a playlist.
 193     --yes-playlist                   Download the playlist, if the URL refers to
 194                                      a video and a playlist.
 195     --age-limit YEARS                Download only videos suitable for the given
 196                                      age
 197     --download-archive FILE          Download only videos not listed in the
 198                                      archive file. Record the IDs of all
 199                                      downloaded videos in it.
 200     --include-ads                    Download advertisements as well
 201                                      (experimental)
 202
 203 ## Download Options:
 204     -r, --limit-rate RATE            Maximum download rate in bytes per second
 205                                      (e.g. 50K or 4.2M)
 206     -R, --retries RETRIES            Number of retries (default is 10), or
 207                                      "infinite".
 208     --fragment-retries RETRIES       Number of retries for a fragment (default
 209                                      is 10), or "infinite" (DASH, hlsnative and
 210                                      ISM)
 211     --skip-unavailable-fragments     Skip unavailable fragments (DASH, hlsnative
 212                                      and ISM)
 213     --abort-on-unavailable-fragment  Abort downloading when some fragment is not
 214                                      available
 215     --keep-fragments                 Keep downloaded fragments on disk after
 216                                      downloading is finished; fragments are
 217                                      erased by default
 218     --buffer-size SIZE               Size of download buffer (e.g. 1024 or 16K)
 219                                      (default is 1024)
 220     --no-resize-buffer               Do not automatically adjust the buffer
 221                                      size. By default, the buffer size is
 222                                      automatically resized from an initial value
 223                                      of SIZE.
 224     --http-chunk-size SIZE           Size of a chunk for chunk-based HTTP
 225                                      downloading (e.g. 10485760 or 10M) (default
 226                                      is disabled). May be useful for bypassing
 227                                      bandwidth throttling imposed by a webserver
 228                                      (experimental)
 229     --playlist-reverse               Download playlist videos in reverse order
 230     --playlist-random                Download playlist videos in random order
 231     --xattr-set-filesize             Set file xattribute ytdl.filesize with
 232                                      expected file size
 233     --hls-prefer-native              Use the native HLS downloader instead of
 234                                      ffmpeg
 235     --hls-prefer-ffmpeg              Use ffmpeg instead of the native HLS
 236                                      downloader
 237     --hls-use-mpegts                 Use the mpegts container for HLS videos,
 238                                      allowing to play the video while
 239                                      downloading (some players may not be able
 240                                      to play it)
 241     --external-downloader COMMAND    Use the specified external downloader.
 242                                      Currently supports
 243                                      aria2c,avconv,axel,curl,ffmpeg,httpie,wget
 244     --external-downloader-args ARGS  Give these arguments to the external
 245                                      downloader
 246
 247 ## Filesystem Options:
 248     -a, --batch-file FILE            File containing URLs to download ('-' for
 249                                      stdin), one URL per line. Lines starting
 250                                      with '#', ';' or ']' are considered as
 251                                      comments and ignored.
 252     --id                             Use only video ID in file name
 253     -o, --output TEMPLATE            Output filename template, see the "OUTPUT
 254                                      TEMPLATE" for all the info
 255     --autonumber-start NUMBER        Specify the start value for %(autonumber)s
 256                                      (default is 1)
 257     --restrict-filenames             Restrict filenames to only ASCII
 258                                      characters, and avoid "&" and spaces in
 259                                      filenames
 260     -w, --no-overwrites              Do not overwrite files
 261     -c, --continue                   Force resume of partially downloaded files.
 262                                      By default, youtube-dlc will resume
 263                                      downloads if possible.
 264     --no-continue                    Do not resume partially downloaded files
 265                                      (restart from beginning)
 266     --no-part                        Do not use .part files - write directly
 267                                      into output file
 268     --no-mtime                       Do not use the Last-modified header to set
 269                                      the file modification time
 270     --write-description              Write video description to a .description
 271                                      file
 272     --write-info-json                Write video metadata to a .info.json file
 273     --write-annotations              Write video annotations to a
 274                                      .annotations.xml file
 275     --load-info-json FILE            JSON file containing the video information
 276                                      (created with the "--write-info-json"
 277                                      option)
 278     --cookies FILE                   File to read cookies from and dump cookie
 279                                      jar in
 280     --cache-dir DIR                  Location in the filesystem where youtube-
 281                                      dlc can store some downloaded information
 282                                      permanently. By default
 283                                      $XDG_CACHE_HOME/youtube-dlc or
 284                                      ~/.cache/youtube-dlc . At the moment, only
 285                                      YouTube player files (for videos with
 286                                      obfuscated signatures) are cached, but that
 287                                      may change.
 288     --no-cache-dir                   Disable filesystem caching
 289     --rm-cache-dir                   Delete all filesystem cache files
 290
 291 ## Thumbnail images:
 292     --write-thumbnail                Write thumbnail image to disk
 293     --write-all-thumbnails           Write all thumbnail image formats to disk
 294     --list-thumbnails                Simulate and list all available thumbnail
 295                                      formats
 296
 297 ## Verbosity / Simulation Options:
 298     -q, --quiet                      Activate quiet mode
 299     --no-warnings                    Ignore warnings
 300     -s, --simulate                   Do not download the video and do not write
 301                                      anything to disk
 302     --skip-download                  Do not download the video
 303     -g, --get-url                    Simulate, quiet but print URL
 304     -e, --get-title                  Simulate, quiet but print title
 305     --get-id                         Simulate, quiet but print id
 306     --get-thumbnail                  Simulate, quiet but print thumbnail URL
 307     --get-description                Simulate, quiet but print video description
 308     --get-duration                   Simulate, quiet but print video length
 309     --get-filename                   Simulate, quiet but print output filename
 310     --get-format                     Simulate, quiet but print output format
 311     -j, --dump-json                  Simulate, quiet but print JSON information.
 312                                      See the "OUTPUT TEMPLATE" for a description
 313                                      of available keys.
 314     -J, --dump-single-json           Simulate, quiet but print JSON information
 315                                      for each command-line argument. If the URL
 316                                      refers to a playlist, dump the whole
 317                                      playlist information in a single line.
 318     --print-json                     Be quiet and print the video information as
 319                                      JSON (video is still being downloaded).
 320     --newline                        Output progress bar as new lines
 321     --no-progress                    Do not print progress bar
 322     --console-title                  Display progress in console titlebar
 323     -v, --verbose                    Print various debugging information
 324     --dump-pages                     Print downloaded pages encoded using base64
 325                                      to debug problems (very verbose)
 326     --write-pages                    Write downloaded intermediary pages to
 327                                      files in the current directory to debug
 328                                      problems
 329     --print-traffic                  Display sent and read HTTP traffic
 330     -C, --call-home                  Contact the youtube-dlc server for
 331                                      debugging
 332     --no-call-home                   Do NOT contact the youtube-dlc server for
 333                                      debugging
 334
 335 ## Workarounds:
 336     --encoding ENCODING              Force the specified encoding (experimental)
 337     --no-check-certificate           Suppress HTTPS certificate validation
 338     --prefer-insecure                Use an unencrypted connection to retrieve
 339                                      information about the video. (Currently
 340                                      supported only for YouTube)
 341     --user-agent UA                  Specify a custom user agent
 342     --referer URL                    Specify a custom referer, use if the video
 343                                      access is restricted to one domain
 344     --add-header FIELD:VALUE         Specify a custom HTTP header and its value,
 345                                      separated by a colon ':'. You can use this
 346                                      option multiple times
 347     --bidi-workaround                Work around terminals that lack
 348                                      bidirectional text support. Requires bidiv
 349                                      or fribidi executable in PATH
 350     --sleep-interval SECONDS         Number of seconds to sleep before each
 351                                      download when used alone or a lower bound
 352                                      of a range for randomized sleep before each
 353                                      download (minimum possible number of
 354                                      seconds to sleep) when used along with
 355                                      --max-sleep-interval.
 356     --max-sleep-interval SECONDS     Upper bound of a range for randomized sleep
 357                                      before each download (maximum possible
 358                                      number of seconds to sleep). Must only be
 359                                      used along with --min-sleep-interval.
 360
 361 ## Video Format Options:
 362     -f, --format FORMAT              Video format code, see the "FORMAT
 363                                      SELECTION" for all the info
 364     --all-formats                    Download all available video formats
 365     --prefer-free-formats            Prefer free video formats unless a specific
 366                                      one is requested
 367     -F, --list-formats               List all available formats of requested
 368                                      videos
 369     --youtube-skip-dash-manifest     Do not download the DASH manifests and
 370                                      related data on YouTube videos
 371     --youtube-skip-hls-manifest      Do not download the HLS manifests and
 372                                      related data on YouTube videos
 373     --merge-output-format FORMAT     If a merge is required (e.g.
 374                                      bestvideo+bestaudio), output to given
 375                                      container format. One of mkv, mp4, ogg,
 376                                      webm, flv. Ignored if no merge is required
 377
 378 ## Subtitle Options:
 379     --write-sub                      Write subtitle file
 380     --write-auto-sub                 Write automatically generated subtitle file
 381                                      (YouTube only)
 382     --all-subs                       Download all the available subtitles of the
 383                                      video
 384     --list-subs                      List all available subtitles for the video
 385     --sub-format FORMAT              Subtitle format, accepts formats
 386                                      preference, for example: "srt" or
 387                                      "ass/srt/best"
 388     --sub-lang LANGS                 Languages of the subtitles to download
 389                                      (optional) separated by commas, use --list-
 390                                      subs for available language tags
 391
 392 ## Authentication Options:
 393     -u, --username USERNAME          Login with this account ID
 394     -p, --password PASSWORD          Account password. If this option is left
 395                                      out, youtube-dlc will ask interactively.
 396     -2, --twofactor TWOFACTOR        Two-factor authentication code
 397     -n, --netrc                      Use .netrc authentication data
 398     --video-password PASSWORD        Video password (vimeo, smotri, youku)
 399
 400 ## Adobe Pass Options:
 401     --ap-mso MSO                     Adobe Pass multiple-system operator (TV
 402                                      provider) identifier, use --ap-list-mso for
 403                                      a list of available MSOs
 404     --ap-username USERNAME           Multiple-system operator account login
 405     --ap-password PASSWORD           Multiple-system operator account password.
 406                                      If this option is left out, youtube-dlc
 407                                      will ask interactively.
 408     --ap-list-mso                    List all supported multiple-system
 409                                      operators
 410
 411 ## Post-processing Options:
 412     -x, --extract-audio              Convert video files to audio-only files
 413                                      (requires ffmpeg or avconv and ffprobe or
 414                                      avprobe)
 415     --audio-format FORMAT            Specify audio format: "best", "aac",
 416                                      "flac", "mp3", "m4a", "opus", "vorbis", or
 417                                      "wav"; "best" by default; No effect without
 418                                      -x
 419     --audio-quality QUALITY          Specify ffmpeg/avconv audio quality, insert
 420                                      a value between 0 (better) and 9 (worse)
 421                                      for VBR or a specific bitrate like 128K
 422                                      (default 5)
 423     --remux-video FORMAT             Remux the video to another container format
 424                                      if necessary (currently supported: mp4|mkv,
 425                                      target container format must support video
 426                                      / audio encoding, remuxing may fail)
 427     --recode-video FORMAT            Encode the video to another format if
 428                                      necessary (currently supported:
 429                                      mp4|flv|ogg|webm|mkv|avi)
 430     --postprocessor-args ARGS        Give these arguments to the postprocessor
 431     -k, --keep-video                 Keep the video file on disk after the post-
 432                                      processing; the video is erased by default
 433     --no-post-overwrites             Do not overwrite post-processed files; the
 434                                      post-processed files are overwritten by
 435                                      default
 436     --embed-subs                     Embed subtitles in the video (only for mp4,
 437                                      webm and mkv videos)
 438     --embed-thumbnail                Embed thumbnail in the audio as cover art
 439     --add-metadata                   Write metadata to the video file
 440     --metadata-from-title FORMAT     Parse additional metadata like song title /
 441                                      artist from the video title. The format
 442                                      syntax is the same as --output. Regular
 443                                      expression with named capture groups may
 444                                      also be used. The parsed parameters replace
 445                                      existing values. Example: --metadata-from-
 446                                      title "%(artist)s - %(title)s" matches a
 447                                      title like "Coldplay - Paradise". Example
 448                                      (regex): --metadata-from-title
 449                                      "(?P<artist>.+?) - (?P<title>.+)"
 450     --xattrs                         Write metadata to the video file's xattrs
 451                                      (using dublin core and xdg standards)
 452     --fixup POLICY                   Automatically correct known faults of the
 453                                      file. One of never (do nothing), warn (only
 454                                      emit a warning), detect_or_warn (the
 455                                      default; fix file if we can, warn
 456                                      otherwise)
 457     --prefer-avconv                  Prefer avconv over ffmpeg for running the
 458                                      postprocessors
 459     --prefer-ffmpeg                  Prefer ffmpeg over avconv for running the
 460                                      postprocessors (default)
 461     --ffmpeg-location PATH           Location of the ffmpeg/avconv binary;
 462                                      either the path to the binary or its
 463                                      containing directory.
 464     --exec CMD                       Execute a command on the file after
 465                                      downloading and post-processing, similar to
 466                                      find's -exec syntax. Example: --exec 'adb
 467                                      push {} /sdcard/Music/ && rm {}'
 468     --convert-subs FORMAT            Convert the subtitles to other format
 469                                      (currently supported: srt|ass|vtt|lrc)
 470
 471 ## Extractor Options:
 472     --ignore-dynamic-mpd             Do not process dynamic DASH manifests
 473