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