From bc7149f6cf2a1617a803237648500a4d86aa7d0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jaime=20Marqui=CC=81nez=20Ferra=CC=81ndiz?= Date: Wed, 26 Mar 2014 14:04:27 +0100 Subject: [PATCH] docs/manpage: Add CONFIGURATION, OUTPUT TEMPLATE and VIDEO SELECTION sections --- docs/youtube-dl.1.rst | 49 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/youtube-dl.1.rst b/docs/youtube-dl.1.rst index 7d68a9a60..1c1a5ed29 100644 --- a/docs/youtube-dl.1.rst +++ b/docs/youtube-dl.1.rst @@ -21,4 +21,53 @@ OPTIONS ======= .. include:: options.rst.inc +CONFIGURATION +============= + +You can configure youtube-dl by placing default arguments (such as ``--extract-audio --no-mtime`` to always extract the audio and not copy the mtime) into :file:`/etc/youtube-dl.conf` and/or :file:`~/.config/youtube-dl/config`. On Windows, the configuration file locations are :file:`%APPDATA%\\youtube-dl\\config.txt` and :file:`C:\Users\\\\youtube-dl.conf`. + +OUTPUT TEMPLATE +=============== + +The ``-o`` option allows users to indicate a template for the output file 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. + +The current default template is ``%(title)s-%(id)s.%(ext)s``. + +In some cases, you don't want special characters such as 中, spaces, or &, such as when transferring the downloaded filename to a Windows system or the filename through an 8bit-unsafe channel. In these cases, add the ``--restrict-filenames`` flag to get a shorter title:: + + $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc + youtube-dl test video ''_ä↭𝕐.mp4 # All kinds of weird characters + $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames + youtube-dl_test_video_.mp4 # A simple file name + +VIDEO SELECTION +=============== + +Videos can be filtered by their upload date using the options ``--date``, ``--datebefore`` or ``--dateafter``, they accept dates in two formats: + + - Absolute dates: Dates in the format ``YYYYMMDD``. + - Relative dates: Dates in the format ``(now|today)[+-][0-9](day|week|month|year)(s)?`` + +Examples:: + + # Download only the videos uploaded in the last 6 months + $ youtube-dl --dateafter now-6months + + # Download only the videos uploaded on January 1, 1970 + $ youtube-dl --date 19700101 + + $ # will only download the videos uploaded in the 200x decade + $ youtube-dl --dateafter 20000101 --datebefore 20091231 + .. include:: faq.rst