README.md

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