X-Git-Url: https://git.rapsys.eu/youtubedl/blobdiff_plain/b8d8e13c1f9e4d3cdd7d41c5c9d711a36dd5f9c3..f1024829e24c7bb91e563541f33200c993e35a55:/README.txt?ds=inline diff --git a/README.txt b/README.txt index 24d4314..a42d837 100644 --- a/README.txt +++ b/README.txt @@ -122,11 +122,23 @@ Network Options: --source-address IP Client-side IP address to bind to -4, --force-ipv4 Make all connections via IPv4 -6, --force-ipv6 Make all connections via IPv6 + + +Geo Restriction: + --geo-verification-proxy URL Use this proxy to verify the IP address for some geo-restricted sites. The default proxy specified by --proxy (or none, if the options is not present) is used for the actual downloading. + --geo-bypass Bypass geographic restriction via faking + X-Forwarded-For HTTP header (experimental) + --no-geo-bypass Do not bypass geographic restriction via + faking X-Forwarded-For HTTP header + (experimental) + --geo-bypass-country CODE Force bypass geographic restriction with + explicitly provided two-letter ISO 3166-2 + country code (experimental) Video Selection: @@ -160,22 +172,24 @@ Video Selection: --max-views COUNT Do not download any videos with more than COUNT views --match-filter FILTER Generic video filter. Specify any key (see - help for -o for a list of available keys) - to match if the key is present, !key to - check if the key is not present,key > - NUMBER (like "comment_count > 12", also - works with >=, <, <=, !=, =) to compare - against a number, and & to require multiple - matches. Values which are not known are - excluded unless you put a question mark (?) - after the operator.For example, to only - match videos that have been liked more than - 100 times and disliked less than 50 times - (or the dislike functionality is not - available at the given service), but who - also have a description, use --match-filter - "like_count > 100 & dislike_count NUMBER (like "comment_count + > 12", also works with >=, <, <=, !=, =) to + compare against a number, key = 'LITERAL' + (like "uploader = 'Mike Smith'", also works + with !=) to match against a string literal + and & to require multiple matches. Values + which are not known are excluded unless you + put a question mark (?) after the operator. + For example, to only match videos that have + been liked more than 100 times and disliked + less than 50 times (or the dislike + functionality is not available at the given + service), but who also have a description, + use --match-filter "like_count > 100 & + dislike_count .+?) - (?P.+)" --xattrs Write metadata to the video file's xattrs (using dublin core and xdg standards) --fixup POLICY Automatically correct known faults of the @@ -464,7 +474,7 @@ Post-processing Options: syntax. Example: --exec 'adb push {} /sdcard/Music/ && rm {}' --convert-subs FORMAT Convert the subtitles to other format - (currently supported: srt|ass|vtt) + (currently supported: srt|ass|vtt|lrc) @@ -535,7 +545,9 @@ To activate authentication with the .netrc file you should pass --netrc to youtube-dl or place it in the configuration file. On Windows you may also need to setup the %HOME% environment variable -manually. +manually. For example: + + set HOME=%USERPROFILE% @@ -548,84 +560,103 @@ names. TL;DR: navigate me to examples. The basic usage is not to set any template arguments when downloading a -single file, like in youtube-dl -o funny_video.flv "http://some/video". +single file, like in youtube-dl -o funny_video.flv "https://some/video". However, it may contain special sequences that will be replaced when -downloading each video. The special sequences have the format %(NAME)s. -To clarify, that is a percent symbol followed by a name in parentheses, -followed by a lowercase S. Allowed names are: - -- id: Video identifier -- title: Video title -- url: Video URL -- ext: Video filename extension -- alt_title: A secondary title of the video -- display_id: An alternative identifier for the video -- uploader: Full name of the video uploader -- license: License name the video is licensed under -- creator: The creator of the video -- release_date: The date (YYYYMMDD) when the video was released -- timestamp: UNIX timestamp of the moment the video became available -- upload_date: Video upload date (YYYYMMDD) -- uploader_id: Nickname or id of the video uploader -- location: Physical location where the video was filmed -- duration: Length of the video in seconds -- view_count: How many users have watched the video on the platform -- like_count: Number of positive ratings of the video -- dislike_count: Number of negative ratings of the video -- repost_count: Number of reposts of the video -- average_rating: Average rating give by users, the scale used depends - on the webpage -- comment_count: Number of comments on the video -- age_limit: Age restriction for the video (years) -- format: A human-readable description of the format -- format_id: Format code specified by --format -- format_note: Additional info about the format -- width: Width of the video -- height: Height of the video -- resolution: Textual description of width and height -- tbr: Average bitrate of audio and video in KBit/s -- abr: Average audio bitrate in KBit/s -- acodec: Name of the audio codec in use -- asr: Audio sampling rate in Hertz -- vbr: Average video bitrate in KBit/s -- fps: Frame rate -- vcodec: Name of the video codec in use -- container: Name of the container format -- filesize: The number of bytes, if known in advance -- filesize_approx: An estimate for the number of bytes -- protocol: The protocol that will be used for the actual download -- extractor: Name of the extractor -- extractor_key: Key name of the extractor -- epoch: Unix epoch when creating the file -- autonumber: Five-digit number that will be increased with each - download, starting at zero -- playlist: Name or id of the playlist that contains the video -- playlist_index: Index of the video in the playlist padded with - leading zeros according to the total length of the playlist -- playlist_id: Playlist identifier -- playlist_title: Playlist title +downloading each video. The special sequences may be formatted according +to python string formatting operations. For example, %(NAME)s or +%(NAME)05d. To clarify, that is a percent symbol followed by a name in +parentheses, followed by a formatting operations. Allowed names along +with sequence type are: + +- id (string): Video identifier +- title (string): Video title +- url (string): Video URL +- ext (string): Video filename extension +- alt_title (string): A secondary title of the video +- display_id (string): An alternative identifier for the video +- uploader (string): Full name of the video uploader +- license (string): License name the video is licensed under +- creator (string): The creator of the video +- release_date (string): The date (YYYYMMDD) when the video was + released +- timestamp (numeric): UNIX timestamp of the moment the video became + available +- upload_date (string): Video upload date (YYYYMMDD) +- uploader_id (string): Nickname or id of the video uploader +- location (string): Physical location where the video was filmed +- duration (numeric): Length of the video in seconds +- view_count (numeric): How many users have watched the video on the + platform +- like_count (numeric): Number of positive ratings of the video +- dislike_count (numeric): Number of negative ratings of the video +- repost_count (numeric): Number of reposts of the video +- average_rating (numeric): Average rating give by users, the scale + used depends on the webpage +- comment_count (numeric): Number of comments on the video +- age_limit (numeric): Age restriction for the video (years) +- format (string): A human-readable description of the format +- format_id (string): Format code specified by --format +- format_note (string): Additional info about the format +- width (numeric): Width of the video +- height (numeric): Height of the video +- resolution (string): Textual description of width and height +- tbr (numeric): Average bitrate of audio and video in KBit/s +- abr (numeric): Average audio bitrate in KBit/s +- acodec (string): Name of the audio codec in use +- asr (numeric): Audio sampling rate in Hertz +- vbr (numeric): Average video bitrate in KBit/s +- fps (numeric): Frame rate +- vcodec (string): Name of the video codec in use +- container (string): Name of the container format +- filesize (numeric): The number of bytes, if known in advance +- filesize_approx (numeric): An estimate for the number of bytes +- protocol (string): The protocol that will be used for the actual + download +- extractor (string): Name of the extractor +- extractor_key (string): Key name of the extractor +- epoch (numeric): Unix epoch when creating the file +- autonumber (numeric): Five-digit number that will be increased with + each download, starting at zero +- playlist (string): Name or id of the playlist that contains the + video +- playlist_index (numeric): Index of the video in the playlist padded + with leading zeros according to the total length of the playlist +- playlist_id (string): Playlist identifier +- playlist_title (string): Playlist title Available for the video that belongs to some logical chapter or section: -- chapter: Name or title of the chapter the video belongs to - -chapter_number: Number of the chapter the video belongs to - chapter_id: -Id of the chapter the video belongs to + +- chapter (string): Name or title of the chapter the video belongs to +- chapter_number (numeric): Number of the chapter the video belongs to +- chapter_id (string): Id of the chapter the video belongs to Available for the video that is an episode of some series or programme: -- series: Title of the series or programme the video episode belongs to -- season: Title of the season the video episode belongs to - -season_number: Number of the season the video episode belongs to - -season_id: Id of the season the video episode belongs to - episode: -Title of the video episode - episode_number: Number of the video episode -within a season - episode_id: Id of the video episode - -Available for the media that is a track or a part of a music album: - -track: Title of the track - track_number: Number of the track within an -album or a disc - track_id: Id of the track - artist: Artist(s) of the -track - genre: Genre(s) of the track - album: Title of the album the -track belongs to - album_type: Type of the album - album_artist: List of -all artists appeared on the album - disc_number: Number of the disc or -other physical medium the track belongs to - release_year: Year (YYYY) -when the album was released + +- series (string): Title of the series or programme the video episode + belongs to +- season (string): Title of the season the video episode belongs to +- season_number (numeric): Number of the season the video episode + belongs to +- season_id (string): Id of the season the video episode belongs to +- episode (string): Title of the video episode +- episode_number (numeric): Number of the video episode within a + season +- episode_id (string): Id of the video episode + +Available for the media that is a track or a part of a music album: + +- track (string): Title of the track +- track_number (numeric): Number of the track within an album or a + disc +- track_id (string): Id of the track +- artist (string): Artist(s) of the track +- genre (string): Genre(s) of the track +- album (string): Title of the album the track belongs to +- album_type (string): Type of the album +- album_artist (string): List of all artists appeared on the album +- disc_number (numeric): Number of the disc or other physical medium + the track belongs to +- release_year (numeric): Year (YYYY) when the album was released Each aforementioned sequence when referenced in an output template will be replaced by the actual value corresponding to the sequence name. Note @@ -638,6 +669,10 @@ youtube-dl test video and id BaW_jenozKcj, this will result in a youtube-dl test video-BaW_jenozKcj.mp4 file created in the current directory. +For numeric sequences you can use numeric related formatting, for +example, %(view_count)05d will result in a string with view count padded +with zeros up to 5 characters, like in 00042. + Output templates can also contain arbitrary hierarchical path, e.g. -o '%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s' which will result in downloading each video in a directory corresponding to this @@ -665,7 +700,8 @@ should stay intact: -o "C:\%HOMEPATH%\Desktop\%%(title)s.%%(ext)s". Output template examples -Note on Windows you may need to use double quotes instead of single. +Note that on Windows you may need to use double quotes instead of +single. $ youtube-dl --get-filename -o '%(title)s.%(ext)s' BaW_jenozKc youtube-dl test video ''_ä↭𝕐.mp4 # All kinds of weird characters @@ -683,7 +719,7 @@ Note on Windows you may need to use double quotes instead of single. $ youtube-dl -u user -p password -o '~/MyVideos/%(playlist)s/%(chapter_number)s - %(chapter)s/%(title)s.%(ext)s' https://www.udemy.com/java-tutorial/ # Download entire series season keeping each series and each season in separate directory under C:/MyVideos - $ youtube-dl -o "C:/MyVideos/%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s" http://videomore.ru/kino_v_detalayah/5_sezon/367617 + $ youtube-dl -o "C:/MyVideos/%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s" https://videomore.ru/kino_v_detalayah/5_sezon/367617 # Stream the video being downloaded to stdout $ youtube-dl -o - BaW_jenozKc @@ -764,8 +800,8 @@ fields: - ext: File extension - acodec: Name of the audio codec in use - vcodec: Name of the video codec in use - container: Name of the container format - protocol: The protocol that will be used for the actual download, lower-case (http, https, rtsp, rtmp, rtmpe, mms, f4m, -ism, m3u8, or m3u8_native) - format_id: A short description of the -format +ism, http_dash_segments, m3u8, or m3u8_native) - format_id: A short +description of the format Note that none of the aforementioned meta fields are guaranteed to be present since this solely depends on the metadata obtained by particular @@ -812,7 +848,8 @@ file in order not to type it every time you run youtube-dl. Format selection examples -Note on Windows you may need to use double quotes instead of single. +Note that on Windows you may need to use double quotes instead of +single. # Download best mp4 format available or any other best if no mp4 available $ youtube-dl -f 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best' @@ -872,7 +909,7 @@ If you have installed youtube-dl using a package manager like _apt-get_ or _yum_, use the standard system update mechanism to update. Note that distribution packages are often outdated. As a rule of thumb, youtube-dl releases at least once a month, and often weekly or even daily. Simply -go to http://yt-dl.org/ to find out the current version. Unfortunately, +go to https://yt-dl.org to find out the current version. Unfortunately, there is nothing we youtube-dl developers can do if your distribution serves a really outdated version. You can (and should) complain to your distribution in their bugtracker or support forum. @@ -1077,11 +1114,11 @@ all of your downloads, put the option into your configuration file. How do I download a video starting with a -? -Either prepend http://www.youtube.com/watch?v= or separate the ID from +Either prepend https://www.youtube.com/watch?v= or separate the ID from the options with --: youtube-dl -- -wNyEUrxzFU - youtube-dl "http://www.youtube.com/watch?v=-wNyEUrxzFU" + youtube-dl "https://www.youtube.com/watch?v=-wNyEUrxzFU" How do I pass cookies to youtube-dl? @@ -1112,7 +1149,7 @@ You will first need to tell youtube-dl to stream media to stdout with capable of this for streaming) and then pipe former to latter. For example, streaming to vlc can be achieved with: - youtube-dl -o - "http://www.youtube.com/watch?v=BaW_jenozKcj" | vlc - + youtube-dl -o - "https://www.youtube.com/watch?v=BaW_jenozKcj" | vlc - How do I download only new videos from a playlist? @@ -1209,7 +1246,7 @@ How can I detect whether a given URL is supported by youtube-dl? For one, have a look at the list of supported sites. Note that it can sometimes happen that the site changes its URL scheme (say, from -http://example.com/video/1234567 to http://example.com/v/1234567 ) and +https://example.com/video/1234567 to https://example.com/v/1234567 ) and youtube-dl reports an URL of a service in that list as unsupported. In that case, simply report a bug. @@ -1273,6 +1310,9 @@ test file directly; any of the following work: python test/test_download.py nosetests +See item 6 of new extractor tutorial for how to run extractor specific +test cases. + If you want to create a build of youtube-dl yourself, you'll need - python @@ -1314,7 +1354,7 @@ yourextractor): class YourExtractorIE(InfoExtractor): _VALID_URL = r'https?://(?:www\.)?yourextractor\.com/watch/(?P<id>[0-9]+)' _TEST = { - 'url': 'http://yourextractor.com/watch/42', + 'url': 'https://yourextractor.com/watch/42', 'md5': 'TODO: md5 sum of the first 10241 bytes of the video file (use --test)', 'info_dict': { 'id': '42', @@ -1351,7 +1391,8 @@ yourextractor): _TEST to _TESTS and make it into a list of dictionaries. The tests will then be named TestDownload.test_YourExtractor, TestDownload.test_YourExtractor_1, - TestDownload.test_YourExtractor_2, etc. + TestDownload.test_YourExtractor_2, etc. Note that tests with + only_matching key in test's dict are not counted in. 7. Have a look at youtube_dl/extractor/common.py for possible helper methods and a detailed description of what your extractor should and may return. Add tests and code for as many as you want. @@ -1549,7 +1590,7 @@ fashion, like this: ydl_opts = {} with youtube_dl.YoutubeDL(ydl_opts) as ydl: - ydl.download(['http://www.youtube.com/watch?v=BaW_jenozKc']) + ydl.download(['https://www.youtube.com/watch?v=BaW_jenozKc']) Most likely, you'll want to use various options. For a list of options available, have a look at youtube_dl/YoutubeDL.py. For a start, if you @@ -1590,7 +1631,7 @@ downloads/converts the video to an mp3 file: 'progress_hooks': [my_hook], } with youtube_dl.YoutubeDL(ydl_opts) as ydl: - ydl.download(['http://www.youtube.com/watch?v=BaW_jenozKc']) + ydl.download(['https://www.youtube.com/watch?v=BaW_jenozKc']) @@ -1612,7 +1653,7 @@ to this: $ youtube-dl -v <your command line> [debug] System config: [] [debug] User config: [] - [debug] Command-line args: [u'-v', u'http://www.youtube.com/watch?v=BaW_jenozKcj'] + [debug] Command-line args: [u'-v', u'https://www.youtube.com/watch?v=BaW_jenozKcj'] [debug] Encodings: locale cp1251, fs mbcs, out cp866, pref cp1251 [debug] youtube-dl version 2015.12.06 [debug] Git HEAD: 135392e @@ -1667,9 +1708,9 @@ command-line) or upload the .dump files you get when you add SITE SUPPORT REQUESTS MUST CONTAIN AN EXAMPLE URL. An example URL is a URL you might want to download, like -http://www.youtube.com/watch?v=BaW_jenozKc. There should be an obvious +https://www.youtube.com/watch?v=BaW_jenozKc. There should be an obvious video present. Except under very special circumstances, the main page of -a video service (e.g. http://www.youtube.com/) is _not_ an example URL. +a video service (e.g. https://www.youtube.com/) is _not_ an example URL. Are you using the latest version?