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