-names. 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". 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 parenthesis, followed by a
-lowercase S. Allowed names are:
-
-- id: The sequence will be replaced by the video identifier.
-- url: The sequence will be replaced by the video URL.
-- uploader: The sequence will be replaced by the nickname of the
- person who uploaded the video.
-- upload_date: The sequence will be replaced by the upload date in
- YYYYMMDD format.
-- title: The sequence will be replaced by the video title.
-- ext: The sequence will be replaced by the appropriate extension
- (like flv or mp4).
-- epoch: The sequence will be replaced by the Unix epoch when creating
- the file.
-- autonumber: The sequence will be replaced by a five-digit number
- that will be increased with each download, starting at zero.
-- playlist: The name or the id of the playlist that contains the
- video.
-- playlist_index: The index of the video in the playlist, a five-digit
- number.
+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 "https://some/video".
+However, it may contain special sequences that will be replaced when
+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)
+- is_live (boolean): Whether this video is a live stream or a
+ fixed-length video
+- start_time (numeric): Time in seconds where the reproduction should
+ start, as specified in the URL
+- end_time (numeric): Time in seconds where the reproduction should
+ end, as specified in the URL
+- 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
+- playlist_uploader (string): Full name of the playlist uploader
+- playlist_uploader_id (string): Nickname or id of the playlist
+ uploader
+
+Available for the video that belongs to some logical chapter or section:
+
+- 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 (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
+that some of the sequences are not guaranteed to be present since they
+depend on the metadata obtained by a particular extractor. Such
+sequences will be replaced with NA.
+
+For example for -o %(title)s-%(id)s.%(ext)s and an mp4 video with title
+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
+path template. Any missing directory will be automatically created for
+you.
+
+To use percent literals in an output template use %%. To output to
+stdout use -o -.
Rapsys Git / youtubedl / blobdiff