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