______________________________________________________________________________

YTD v1.50+                                                   (c) 2009-15 Pepak
http://www.pepak.net/ytd                                  http://www.pepak.net
______________________________________________________________________________

YouTube Downloader is an utility designed for downloading multimedia content
from YouTube and other online streaming services. It works from command-line,
where it accepts any number of URLs or a text file with a list of URLs. It
saves the movies under their "human-readable" name from YouTube. When a movie
has several variants, the highest-quality one is downloaded.



0. TABLE OF CONTENTS
--------------------
1. Supported providers
2. HTTPS protocol
3. RTMP protocol
4. MMS/RTSP protocols
5. HDS protocol
6. HLS protocol
7. Playlists
8. Conversion of downloaded files
9. The distribution archive
10. Configuration
11. Command-line syntax
12. Result codes
13. Localization
14. Support
15. Compiling
16. License



1. SUPPORTED PROVIDERS
----------------------

The list of supported providers, along with demo URLs and notes for each, is
located in file providers.txt.



2. HTTPS PROTOCOL
-----------------

In order to support the HTTPS protocol (user by e.g. RockStarGames.tv) YTD
requires OpenSSL libraries (CRYPTOEAY32.DLL, SSLEAY32.DLL), preferably in
version 0.98, to be installed in your Windows. You can download the libraries
from the OpenSSL project's server (http://www.openssl.org).



3. RTMP PROTOCOL
----------------

Since version 0.15 the program supports "real" streaming video according to
the RTMP protocol. The protocol is implemented with a library RTMPDUMP_DLL,
which is heavily based on project RTMPDUMP (http://rtmpdump.mplayerhq.hu)
- basically, the library is the same as RTMPDUMP, except that it has a DLL
interface rather than command-line. The implementation has several problems:

1) It is not possible to determine total video size exactly. The size is
   just guessed, based on the total time of video and the time and size of
   downloaded data.

2) Errors are not passed to YouTube Downloader. Instead, they are written
   to a log file in the user's temporary directory.

3) In order to download RTMP streams, including those which are not encrypted,
   these libraries are required in the exe-file's directory:
   - RTMPDUMP_DLL.DLL - provided with YouTube Downloader.

4) It's impossible to reliably detect whether a download was complete or not.
   Please check each downloaded file to make sure it is complete.

Since version 0.78, URLs with RTMP protocol can be downloaded directly - you
can enter URLs such as "rtmp://iconcerts.infomaniak.ch/icpreview/mp4:trk-09-black_kids_nme_awards_shows-001_site_16-9-2500.mp4"
directly into YTD. It will only work if the provider's server only needs video
URL to start a playback - if it needs extra parameters, you can't use YTD and
will need to use RTMPDUMP directly.

Since version 1.50, the support library is not included in the distribution
archive. YTD will offer to download it for you when you start the GUI version,
or you can download it manually from:

    http://www.pepak.net/files/youtube/external/rtmpdump.zip

Unzip the downloaded file to YTD's directory.



4. MMS/RTSP PROTOCOLS
---------------------

Since version 0.17, protocol family around MMS and RTSP (e.g. Microsoft's
streaming servers, Real servers and a number of others) is supported. The
protocol is implemented by library MDSL_DLL.DLL, which is a wrapper around
the MDSL project (http://msdl.sf.net). The library is built in much the same
way as the RTMPDUMP library above, with similar drawbacks.

Note: As with RTMP, the total size of a stream is just guessed. It is quite
possible that a download ends at 93% and turns out to be complete. The same
cautionary note as with RTMP applies: Please test every downloaded file to 
make sure it really is complete.

Since version 0.78, URLs with MMS protocol can be downloaded directly - you
can enter URLs such as "mms://netshow.play.cz/proglas/audio_15681.wma"
directly into YTD. It will only work if the provider's server only needs video
URL to start a playback - if it needs extra parameters, you can't use YTD and
will need to use MSDL directly.

Since version 1.50, the support library is not included in the distribution
archive. YTD will offer to download it for you when you start the GUI version,
or you can download it manually from:

    http://www.pepak.net/files/youtube/external/msdl.zip

Unzip the downloaded file to YTD's directory.



5. HDS PROTOCOL
---------------

Since version 1.15 the Adobe HDS protocol is supported. It is a HTTP-based
protocol consisting of a manifest (header) and a sequence of fragments of
a FLV file, which must be downloaded separately and combined. My implementation
is based on the AdobeHDS.php script (https://raw.github.com/K-S-V/Scripts/master/AdobeHDS.php) 
by K-S-V, which I modified in a number of aspects.

The simplified implementation (DEFINE SIMPLIFIEDHDSDOWNLOADER) is based on a 
number of assumptions which are quite sufficient for YTD's needs and should 
be satisfied by most servers. The advantage if this approach is a much 
simplified code, although it may fail with some servers. The most significant
disadvantage is the inability to resume broken downloads (which are not
supported by YTD, anyway).



6. HLS PROTOCOL
---------------

Since version 1.42, the HLS protocol is supported. It is a HTTP-based protocol
built around a .m3u playlist, which contains several other .m3u playlists
(one for each video quality) and these in turn contain links to the movie
chunks. So far I have only seen an implementation which uses a .ts format
for these chunks, which makes it easy to combine them and then play the 
result using an advanced media player such as Mplayer, VideoLAN or KMPlayer.
It is possible that other implementations will use different formats, ones
which won't be as easy to combine. When that happens, I will see what can
I do about it.



7. PLAYLISTS
------------

Since version 0.19, sources which contain multiple files on one page are
supported (e.g. Markiza.sk). At the moment it is not possible to choose which
files to download and which to skip - YTD simply downloads them all. You can
of course use the GUI version and delete unwanted streams from there.



8. CONVERSION OF DOWNLOADED FILES
---------------------------------

Version 0.50 added support for calling external applications after a download
is finished. Among other common uses of this function is the possibility to
 convert downloaded content to a desired format, as long as you can find
a command-line driven converter.

If you delete your configuration file and start YouTube Downloader in the
GUI mode, it will generate a default configuration file with three basic
conversions, which use the application MEncoder (a part of the MPlayer project, 
http://www.mplayerhq.hu) to perform these three tasks:

a) Change the video container to AVI. This function is very fast and doesn't
   change the quality of the source movie in any way, but unfortunately only
   works for some sources (many, if not all, .FLV files can't be converted
   this way) and, most importantly, only changes the container, not the
   actual content. This means that in order to play the movie, you still need
   all the codecs used in the original file. For this reason the conversion
   is only useful if you have all required codecs but your software doesn't
   work with the more exotic containers.

b) Convert the video to AVI container with XVID+MP3 codecs. This is a "full"
   conversion, with pros and cons pretty much opposite to the previous one:
   The conversion is slow and the movie loses some quality, but it works for
   every (almost?) source and the result will be playable with every XVID
   supporting player (which is just about every one, these days).

c) Convert the video to AVI container with H264+MP3 codecs. Much the same
   thing as the previous conversion, except that a newer codecs with higher
   quality and slower speed is used.

Some basic settings are provided for all three options, but since my experience
with movie conversions is very low, they are sure to be suboptimal. Don't be
surprised by the low-quality of the results; until someone provides me with 
a better set of options, this problem will not change.

What you need to do to start using the conversions:

1. Download and install the full MPlayer package (it includes MEncoder.exe).

2. Copy MEncoder.exe to a directory in PATH, or to the directory where YouTube
   Downloader is installed.

3. Activate the converter functionality. Activation is controlled by setting
   <converters><activated>; by default it is set to 0 (zero), and needs to
   be changed to 1 (one) for converters to work. You can open the configuration
   file from within the program by clicking the "Edit config file" button,
   then search for "<activated>" (without quotes) in it and change the zero
   to one.

4. a) If you want to automatically convert all downloaded files:

      In the GUI version, click on the "Select converter" icon (a movie strip
      with a pen) and choose one of the predefined converters. Since this
      moment, all new downloaded files will be passed to this converter (by
      default, sequentially, one at a time, so that only one conversion
      process is running).

   b) If you only want to convert files you choose manually:

      In the GUI version, select one or more files and click on the "Convert"
      icon (a movie strip with a green arrow). The conversion will be started
      for all selected files, no matter how many there are, and no matter
      whether their download finished successfully, failed or was aborted.

Since version 1.01 the default configuration also supports software FFmpeg
(http://ffmpeg.org/) (thanks ffmpegmann), with the three conversion scenarios
listed above. The installation is basically the same, except that you need to
substitute ffmpeg.exe in place of mencoder.exe.

The advanced users may, through editing the configuration files, change the
parameters of conversion tasks or even create a completely new converters.
You needn't limit yourself to MEncoder or any video converter, for that
matter - the function is called "converters" because that will be its most
common use, but it can be used for e.g. sending the downloaded files through
e-mail or even running complex BAT scripts on them. The detailed description
of the configuration can be found further in this document.

The command-line version of YouTube Downloader doesn't support this function,
reason being, the conversion introduces a lot of complexity and possible
errors and since the command-line version is inherently scriptable, it would
bring too few advantages to overcome this drawback. If you need to convert
the downloaded files, you can always do so in a BAT file.



9. THE DISTRIBUTION ARCHIVE
---------------------------

Up to version 0.86, YTD was distrubuted in the form of a standard ZIP archive,
which would be manually unpacked to any desired location. Unfortunately, many
people failed to do that, and instead opened the archive as a folder (supported
in Windows XP or newer) and executed the ytd.exe file, while blisfully ignoring
Windows' warning that they should unpack all files or the product may not work
properly. And it didn't.

Since version 0.87, a new distribution scheme is used. YTD is now distributed
as an .exe file. But I took a lot of pains to maintain as many good features
of the ZIP archive as possible while adding new ones:

1. The distribution archive is a standard self-extracting archive in 7-zip
   (http://www.7-zip.org) format, which you can manually unpack using 7-zip
   instead of performing the "installation" (quoted, because YTD traditionally
   works without any installation if only you unpack it to any chosen folder).

2. Upon execution, the distribution archive shows a basic install dialog. You
   can select a desired target directory and decide which, if any, shortcuts
   you want made, then click the Install button. All required files will be
   copied to the chosen directory, shortcuts will be made and the GUI version
   of YTD started. No changes are made to the registry or the filesystem, 
   outside of the selected directory and (if enabled) the shortcuts.

3. The install dialog also provides a button for running YTD right away,
   without installation. That starts a full-featured YTD, only somewhat slower
   to start (the files need to be unpacked to a temporary directory first)
   and less friendly to firewalls (because a different temp directory will be 
   used every time).

4. If you start the distribution archive with --gui argument, the graphical
   version from item 3 will be started right away, without user interaction.

5. If you start the distribution archive with other arguments, these will be
   passed to the command-line version of YTD and processed in the usual way.
   That means you can e.g. download a movie without ever unpacking the archive.

6. One nice side benefit of an .exe-based distribution is that it's quite easy
   to provide automatic program upgrade, so I did that in both GUI and the
   CLI (see argument -u).



10. CONFIGURATION
----------------

Since version 0.50 stores YouTube Downloader its configuration in a XML file
"ytd.xml". This file can be found in three locations:

1) Current working directory. This is the primary location.

2) The directory where YTD.exe resides. This location is used if it contains
   an ytd.xml file and there is no such file in the primary location.

3) Directory "YouTube Downloader" in a user profile of Windows (%APPDATA%).
   This location is only considered if the primary XML doesn't exist or
   if the primary XML doesn't require a portable mode.

The configuration parameters are stored as values of XML tags. Consistent
with the XML standard, names of the tags are case sensitive; the values are
not case sensitive, but it is a recommended practice to stick to lower case
except in file/directory names. Logical values (true-false) are stored as
"1" (true) and "0" (false).

<ytd> 
  - The root element. It's name can currently be anything at all since the
    program doesn't check it (yet, anyway).

<config>
  - Child of <ytd>; contains the configuration options common to graphical
    and command-line version of the application.

  <portable_mode>
    - Child of <config>; stores a logical value that determines whether YTD
      runs in a portable mode or as a regular application. In neither of the 
      modes does YTD write to registry, the difference is simply that in
      portable mode only the "ytd.xml" file in application directory is used,
      while in regular mode it is the "ytd.xml" stored in user's profile.
      The drawback of portable mode is that the application needs to have
      a write access to the directory where it is installed, which is a poor
      practice and in Windows Vista or newer Microsoft tries to stop it.
      (If you don't have a write access, no error message will be shown, but 
      the configuration changes will not be stored.)
    - Possible values are "1" (run in portable mode) and "0" (regular mode).
    - Default value is "0" (regular mode).

  <language>
    - Child of <config>; let's you choose the language for texts displayed
      by the program.
    - Possible values are two-letter ISO codes of languages (see the
      Localization section below), as well as an empty string, which lets
      the application choose a language automatically based on your operating
      system's settings.
    - Default value is an empty string (automatic decision).
    - Note: Currently only czech ("cs") and english ("en") translations are
      available. You'll find more info on providing a new translation below.

  <destination_path>
    - Child of <config>; specifies a directory where the downloaded videos
      will be saved.
    - Possible values are an empty string (current working directory, which
      is usually the directory from which you started the program) or any
      valid path, absolute ("c:\download") or relative to the current working
      directory ("..\download").
      In case of portable version it is strongly recommended to not use an
      absolute path.
    - Default value is an empty string (current working directory).
    - Can be overridden by parameter -o on command-line.

  <error_log>
    - Child of <config>; specifies a file into which a list of failed URLs
      will be stored.
    - Possible values are an empty string (no log will be written) or a file
      name (including path, if desired).
    - Default value is an empty string (no log will be written).
    - The graphical version doesn't use this option (yet).
    - Can be overriden by parameter -e on command-line.

  <overwrite_mode>
    - Child of <config>; specifies what to do if a file already exists when
      trying to save a new movie.
    - Possible values are:
        "ask" - ask the user what to do; matches -k on command-line.
        "never" - skip the file; matches -n on command-line.
        "always" - overwrite the file; matches -a on command-line.
        "rename" - rename the new file so that its name is unique; matches
                   -r on command line.
    - Default value is "ask" (ask the user).
    - Can be overriden by command-line parameters -k (ask), -n (never),
      -a (always) and -r (rename).

  <auto_try_html_parser>
    - Child of <config>; enables or disables support for automatic application
      of HTML parser to unknown URLs; i.e., YTD tries to match an URL to one
      of the supported downloaders, and if it fails, it downloads that URL as
      a HTML page and tries to search that for known URLs (just like the -s
      command-line parameter). That provides support for servers such as 
      Zive.cz or Vlaky.net, which use third-party providers for their video
      needs.
    - Possible values are "1" (enable automatic HTML parser) and "0" (disable).
    - Default value is "1" (enable automatic HTML parser).
    - Can be overriden by parameters -ah and -ah- on command-line.

  <download_retry_count>
    - Child of <config>; determines the number of automatic retries for failed
      downloads, if the number if greater than zero.
    - Possible values are integer numbers.
    - Default value is "0" (do not automatically retry downloads).

  <subtitles_enabled>
    - Child of <config>; provides you with the ability to turn subtitle support
      on or off in the whole application.
    - Possible values are "1" (enable subtitle support) and "0" (disable).
    - Default value is "1" (enable subtitle support).

  <download_to_temp_files>
    - Child of <config>; if turned on, media currently being downloaded have
      an additional extension ".part", which will be removed after the download
      has finished. If turned off, media will be saved under the final name
      even while downloading.
    - Possible values are "1" (enable extension .part) and "0" (disable).
    - Default value is "0" (disable extension .part).

  <download_to_provider_subdirectories>
    - Child of <config>; determines whether the media files will be stored
      directly in directory <destination_path> or in its subdirectory with
      name based on media provider's name (e.g. YouTube videos would be stored
      in YouTube.com subdirectory).
    - Possible values are "1" (enable subdirectories) and "0" (disable).
    - Default value is "0" (disable subdirectories).

  <proxy_server>
    - Child of <config>; let's you specify a proxy server if your network
      uses one (or if you want to overcome regional restrictions of some
      providers). It is supported and working with protocols HTTP and MMS/RTSP.
      It is used even for protocol RTMP, but it seems not to work (or maybe
      I used a wrong proxy server).

    <active>
      - Child of <proxy_server>; allows enabling or disabling the use of proxy
        server quickly.
      - Possible values are "1" (use proxy) and "0" (don't use proxy).
      - Default value is "0" (don't use proxy).

    <host>
      - Child of <proxy_server>; specifies a network address of the proxy.
      - Possible values: an empty string (don't use proxy) or any valid
        TCP/IP address, either numeric or a domain name.
      - Default value is an empty string (don't use proxy).

    <port>
      - Child of <proxy_server>; specifies a TCP port of the proxy.
      - Possible values: numbers from 1 to 65535, with 3128 and 8080 being the
        most common.
      - Default value is 3128.

    <user>
      - Child of <proxy_server>; specifies a user name used to authenticate
        to your proxy server. Authentization is only supported for HTTP 
        protocol, and even then hasn't been tested.
      - Possible values is an empty string (don't use authentization) or any
        valid username.
      - Default value is an empty string (don't use authentization).

    <password>
      - Child of <proxy_server>; specifies a password to the proxy server.
      - Any string is possible here.
      - Default value is an empty string (no password).

  <ignore_missing_openssl>
    - Child of <config>; lets you disable the warning about missing OpenSSL
      libraries.
    - Possible values are "1" (disable the warning) and "0" (enable).
    - Default value is "1" (enable the warning).

  <ignore_missing_rtmpdump>
    - Child of <config>; lets you disable the warning about missing RtmpDump
      libraries.
    - Possible values are "1" (disable the warning) and "0" (enable).
    - Default value is "1" (enable the warning).

  <ignore_missing_msdl>
    - Child of <config>; lets you disable the warning about missing MSDL
      libraries.
    - Possible values are "1" (disable the warning) and "0" (enable).
    - Default value is "1" (enable the warning).

  <add_index_to_names>
    - Child of <config>; specifies if and how the movie titles will be modified
      when downloading playlists.
    - Possible values are:
      - "none" - the names are not modified.
      - "start" - add the playlist index at the beginning of a name.
      - "end" - add the playlist index at the end of a name.
    - Default value is "none" (do not modify names).

<gui>
  - Child of <ytd>; stores settings specific to the graphical version of YTD.
    Usually, you don't change these settings here; they have their own controls
    in the program.

  <auto_start_downloads>
    - Child of <gui>; specifies, whether a newly added links will start 
      downloading automatically or wait until you click on the Start button.
    - Possible values are "1" (start automatically) and "0" (manual start).
    - Default value is "1" (start automatically).

  <auto_delete_finished_downloads>
    - Child of <gui>; specifies, whether a successfully downloaded URL should
      be automatically deleted from the URL list. Note, however, that it is
      not always possible to precisely determine the success; sometimes YTD has
      to guess whether the download finished successfully or not.
    - Possible values are "1" (delete) and "0" (don't delete).
    - Default value is "0" (don't delete).

  <check_for_new_version>
    - Child of <gui>; specifies, whether a check for new version may be 
      performed at the start of the GUI version. Even if you disable this
      automatic check, you can still perform the check manually by either
      using the command-line argument -v or by opening the About window.
    - Possible values are "1" (enable the check) and "0" (disable it).
    - Default value is "1" (enable the check for new version).

  <monitor_clipboard>
    - Child of <gui>; if turned on, instructs YouTube downloader to monitor
      changes in clipboard content and automatically add known URLs to the
      download list.
    - Possible values are "1" (enable monitoring) and "0" (disable it).
    - Default value is "0" (disable monitoring).

  <minimize_to_tray>
    - Child of <gui>; if turned on, YTD will minimize to a tray icon, otherwise
      normal Windows minimalization is used.
      download list.
    - Possible values are "1" (tray) and "0" (normal).
    - Default value is "1" (tray).

    - Potomek <gui>; určuje, jestli se má program při zmenšení skrýt do
      ikonky v systémovém tray nebo se minimalizovat normálně.
    - Možné hodnoty jsou "1" (tray) a "0" (normální).
    - Výchozí hodnotou je "1" (tray).


<modules>
  - Child of <ytd>. This section stores provider-specific options.

  <CeskaTelevize_cz>
    - Potomek <modules>; contains settings used by CeskaTelevize.cz.

    <max_bitrate>
      - Child of <CeskaTelevize_cz>; sets the maximum video bitrate that YTD
        will download. That is, if it has a choice - if there are only videos
        in higher bitrate, they will still get downloaded.
      - Possible value is any integer number. If that number is negative
        or a zero, there will be no limit on video bitrate. 
        At the moment (2012-06-03), CeskaTelevize.cz uses bitrates 2000, 1000
        and 500.
      - Default value is "0" (no limit on video bitrate).

  <Joj_sk>
    - Child of <modules>; contains settings used by Joj.sk.

    <server>
      - Child of <Joj_sk>; enables you to manually enforce server used to 
        download videos. At the moment it seems that all servers contain the
        same content, so there's no need to set the server, but the option is
        here in case of future need.
      - Possible values are the server names. I know of servers "n06.joj.sk"
        and "n15.joj.sk", and likely there are others. Empty string means
        that the hard-coded server will be used.
      - Default value is an empty string (use the hardcoded server).

  <Markiza_sk>
    - Child of <modules>; contains settings used by Markiza.sk. The settings
      are exactly the same as those for <Nova_cz>.

  <Nova_cz>
    - Child of <modules>; contains settings used by Nova.cz.

    <low_quality>
      - Child of <Nova_cz>; provides an option to download movies in low
        quality rather than high. The reason is, some movies are not available
        in high quality and it doesn't seem possible to reliably detect this
        fact.
      - Possible values are "0" (high quality) a "1" (low quality).
      - Default value is "0" (high quality).

    <secret>
      - Child of <Nova_cz>; defines the secret password used by Nova servers
        to identify valid clients. In order to request movies from the server, 
        you need this password. I will not disclose how to get it, for legal 
        reasons; try Google or other search engines.
      - Any value is possible here.
      - Default value is an empty string (which won't work).

    <config_password>
      - Child of <Nova_cz>; allows YTD to decrypt the configuration files used
        by some subpages of Nova, such as poklicka.nova.cz or poker.nova.cz.
        It is not needed for Voyo movies.
      - Any value is possible here.
      - Default value is an empty string (which won't work).

  <YouTube_com>
    - Child of <modules>; contains settings specific to YouTube.

    <max_video_width>
      - Child of <YouTube_com>; determines the maximum horizontal resolution 
        of movies downloaded by YTD; movies with larger resolution will be
        ignored.
      - Possible value is any integer number. If that number is negative
        or a zero, there will be no limit on video resolution.
      - Default value is "0" (no limit on video resolution).

    <max_video_height>
      - Child of <YouTube_com>; determines the maximum vertical resolution 
        of movies downloaded by YTD; movies with larger resolution will be
        ignored.
      - Possible value is any integer number. If that number is negative
        or a zero, there will be no limit on video resolution.
      - Default value is "0" (no limit on video resolution).

    <preferred_languages>
      - Child of <YouTube_com>; determines the preferred subtitle languages
        and their priority. If the value exists, YTD will attempt to first
        download subtitles in the first listed language, then the second,
        etc. If no preferred language succeeded, the first available subtitles
        will be downloaded instead, regardless of their language.
      - The expected value is in the form "language1,language2,language3" -
        that is, a string of language shortcodes separated by a comma (and
        only a comma, no spaces!). The shortcodes are probably in the ISO
        format, at least the tested values "cs" (Czech) and "en" (English)
        followed this rule. An example value would be "en,cs".
      - Default value is "en" - download english subtitles first.

    <avoid_webm>
      - Child of <YouTube_com>; determines whether movies in the .webm format 
        (container) will be downloaded.
      - Possible values are "1" (disable WebM) and "0" (enable).
      - Default value is "0" (enable WebM).

  - All providers have these settings:

    <subtitles_enabled>
      - Child of a provider; gives you with the ability to turn subtitle
        support on or off for that provider.
      - Possible values are "1" (enable subtitle support) and "0" (disable).
      - Default value is "1" (enable subtitle support).

    <convert_subtitles>
      - Child of a provider; let's you specify whether you want to convert
        the subtitles from the native format to .srt format.
      - Possible values are "1" (enable conversion) and "0" (disable).
      - Default value is "1" (enable conversion).

    <live_stream>
      - Child of a provider; gives you an option to choose, whether you want 
        to download videos as files (faster download, but with sensitive to
        client-server synchronization; can lead to damaged video or audio in 
        the downloaded file) or as live streams (slower, but more compatible).
      - Note: This setting only applies to RTMP-based providers.
      - Possible values are "0" (download as file) and "1" (download as
        live stream).
      - Default value is "0" (download as file) for most servers.

    <realtime>
      - Child of a provider; gives you an option to choose, whether you want 
        to download videos as fast as possible, or whether you prefer slower
        but safer. RTMPDUMP tries to speed-up the downloading by sending a 
        frequent pause request followed by a continue request, which forces
        the server to send a quick burst of data to facilitate buffering;
        unfortunatelly, some servers tend to skip back a few seconds when
        paused, and stream downloaded after such skip-back is virtually useless
        for playback. The realtime mode prevents this pause/continue hack.
      - Note: This setting only applies to RTMP-based providers.
      - Possible values are "0" (download as fast as possible) and "1" 
        (download in realtime mode).
      - Default value is "1" (download in realtime mode).

    <secure_token>
      - Child of a provider; defines the SecureToken used by the provider's
        servers to identify valid clients. In order to request movies from
        the server, you need this token. I will not disclose how to get this
        token, for legal reasons; try Google or other search engines.
      - Note: This setting only applies to providers which use a secure token.
      - Any value is possible here.
      - Default value is an empty string (which won't work).

    <username>
      - The username you use to log into the provider's server.
      - Note: This setting only applies to providers which support/require 
        a login.
      - Any value is possible here.
      - Default value is an empty string.

    <password>
      - The password you use to log into the provider's server.
      - Note: This setting only applies to providers which support/require 
        a login.
      - Any value is possible here.
      - Default value is an empty string.


<converters>
  - Child of <ytd>. This section defines a list of converters (applications
    called either on user's request or automatically after a successful 
    download).

  <activated>
    - Child of <converters>; serves as a proof that the user read the 
      documentation and thus is aware of the sad fact that for the converters
      to work, they need to be properly set up first.
    - Possible values are "0" (converters are inactive) and "1" (active).
    - Default value is "0" (converters are inactive).

  <selected>
    - Child of <converters>; informs the application which converter should
      be used automatically after a download successfully completes.
    - Possible values: an empty string (no automatic conversion will be run,
      conversions will be only on user's explicit request) or one of the
      values of attribute "id" of <converter> tags (e.g. "test" if an element
      <converter id="tags"> exists).
    - Default value is an empty string (no automatic conversions).

  <max_threads>
    - Child of <converters>; defines, how many automatic conversion tasks
      may run at the same time. Recommended value is 1 (all conversion tasks
      will run sequentially, one at a time); if you decide to increase it,
      it is strongly recommended to keep it at most equal to the number of
      CPU cores in your computer.
    - Any integer (non-fractional) number is possible here. Zero (or lower)
      prevent automatic conversions from running.
    - Default value is 1.

  <converter>
    - Child of <converters>; you may provide any number of these elements,
      each will define one converter. Each converter should have attribute
      "id" with a unique value which will represent it in <selected>.

    <title>
      - Child of <converter>; a converter's description, will be shown to
        the user in all dialogs which show a converter list.
      - Any string is possible here. It is recommended that title is kept
        short and easy to understand, while descriptive.
      - Default value is an empty string (which is useless, of course).

    <exe_path>
      - Child of <converter>; provides a filename (and path, if required)
        of an executable program or script which should be run. Path may
        be omitted if the executable is located in YouTube Downloader's
        directory or in PATH.
      - Any valid filename is permitted here. If it contains spaces, DO NOT
        quote it, just leave it as is.
      - Default value is an empty string.

    <command_line>
      - Child of <converter>; defines command-line arguments which will be
        passed to the application defined in <exe_path>. You may use several
        special symbols which will be replaced by specific parameters of a
        movie being converted:

          {$FULLPATH} .... Full path to movie
          {$FILENAME} .... Just filename without path
          {$FILEPATH} .... Just path without filename
          {$FILEEXT} ..... Just file extension, including the leading dot
          {$FILENOEXT} ... Just filename without path and extension
          {$TITLE} ....... Title of the movie (may be used for tagging, f.e.)

      - Any string is permitted here.
      - Default value is an empty string.

    <visibility>
      - Child of <converter>; defines whether the converter's window will be
        visible to the user.
      - Possible values are "visible" (normal execution), "minimized" (the
        converter will run normally, but its window will be minimized on
        startup) and "hidden" (the converter will run, but its window will
        be hidden and inaccessible to the user).
      - Default value is "minimized".



11. COMMAND-LINE SYNTAX
-----------------------

  ytd.exe <param> [<param>] [<param>] ...

  where <param> is either an URL or one of the following:

  For the command-line version:

    -h, -? ........ Show help.
    -i <file> ..... Downloads all URLs listed in the text file <file>, where
                    each line represents one URL.
    -o <dir> ...... Downloaded files will be stored in directory <dir>. If this
                    option is not used, the current working directory will be
                    used.
    -e <file> ..... Log all failed downloads to file <file>.
    -s <source> ... <source> (local file or URL) is searched for known URLs and
                    these will be downloaded.
    -n ............ Never overwrite existing files. Skip the download instead.
    -a ............ Always overwrite existing files.
    -r ............ If a file with matching filename already exists, generate
                    a new unique filename.
    -k ............ Ask the user what to do if a file already exists (default).
    -l ............ Displays a list of supported media providers.
    -v ............ Checks for availability of a newer version of YTD.
    -u ............ If a new version is available, downloads it and upgrades
                    itself. Note that you should not call YTD again until about
                    0.5 second after it returns from an upgrade, otherwise its
                    .exe file may not be overwritten correctly.
    -ah[-] ........ [Don't] try to use HTML parser on unknown URLs.
    -nd ........... Just display command-line which would download the video,
                    but skip the download itself. This may be useful in cases
                    where you want to add your own custom arguments.


  For the graphical version:

    --gui ......... This parameter must be present if any arguments are to be
                    used with the GUI version: by default, a presence of 
                    command-line arguments instructs YTD to run in command-line
                    mode.
    -new .......... Run a new instance of YTD, instead of the default behavior
                    of switching to an existing one.


  Ex.: ytd.exe "http://www.youtube.com/watch?v=6wXkI4t7nuc"
       ytd.exe -i c:\temp\seznam.txt
       ytd.exe -a "http://www.youtube.com/watch?v=6wXkI4t7nuc"
       ytd.exe --gui "http://www.youtube.com/watch?v=6wXkI4t7nuc"

  If no arguments are provided, the graphical version of YTD is started.

  Note: There are three undocumented arguments used for setup, install or 
  upgrade. If you are interested in them, look at the FindStartupType function
  in YTD.dpr.



12. RESULT CODES
----------------

The command-line version supports result codes (errorlevel). Possible values
are:

  0 ..... All operations succeeded.
          Note! In case of multidownloads (downloading from a playlist, list
          file or a HTML source), it is enough if any one of the URLs was
          successfully downloaded. If you depend on errorlevels, it is
          strongly recommended to only download one URL at a time.
  1 ..... Download error in any URL.
  2 ..... No known URLs were found among the arguments.
  3 ..... Invalid syntax. Generally, it means either an unknown argument, or 
          a known argument but without a required parametr (e.g. in case of
          argument -i, see above).
  4 ..... Invalid content of a parameter. A required parameter was provided,
          but its content was somehow invalid (file didn't exist, list file
          didn't contain any URLs etc.).
  5 ..... Failed to find or download the newest version.
  253 ... Installation or upgrade failed.
  254 ... User abort.
  255 ... Exception was raised. As all exceptions should be handled, this code
          indicates a bug in YouTube Downloader.



13. LOCALIZATION
----------------

YouTube Downloader uses GNU GetText for its localization needs. If you are
experienced with GetText, you can start translating right away. If you have
no experience with GetText, don't worry - it is easy enough to learn it. The
only problem will be finding a good tutorial - I have yet to find one that
doesn't require "experience with GetText" as one of its prerequisites... But
with a good tool such as POEdit (http://www.poedit.net) you can learn GetText
as you go along.

For translations, you will need the untranslated "default.pot" file. It is
located in "Source\Locale" directory. Using POEdit, or any other tool (even
Notepad, though that one's use is far from comfortable), you can translate
all language-specific strings in YouTube Downloader. Then you will need to
compile the "default.po" file into "default.mo" (POEdit can do it for you).
Once this is done, simply copy the "default.mo" file into its destination
directory "(exe)\Locale\(language)\LC_MESSAGES":
   - "(exe)" is the directory where "ytd.exe" is stored.
   - "(language)" is a subdirectory named after the two-letter ISO code of
     your translation's language (e.g. "en" for English or "de" for German).

Unless your Windows' locale is set for that language, you will need to
override the "Language" option in the INI file (see above).

I would appreciate if you could send me your translation (both "default.mo"
and "default.po" files) for inclusion in future versions of YouTube Downloader.



14. SUPPORT
-----------

Support is provided at:

- Pepak Forum: 
  http://forum.pepak.net
- YouTube Downloader page: 
  http://www.pepak.net/download/youtube-downloader/
- YouTube Downloader Support page: 
  http://www.pepak.net/download/youtube-downloader-podpora/



15. COMPILING
-------------

Source code to YouTube Downloader can be downloaded from the program's
homepage. The code is completely self-contained in the sense that it doesn't
require any third-party components to be installed - it is created to make do
with default components.

These compilers are supported:

- Delphi 5.0
- Delphi 7.0
- Delphi 2007
- Delphi 2009
- Delphi XE2
- Delphi XE4
- FreePascal

It should be possible to compile the program with other versions of Delphi
(newer than 5.0), but some minor modifications to the source code may be
necessary.

The recommended way to build YouTube Downloader is by running the BUILD.BAT
script in SOURCE directory. This script will handle all dependencies and
compiler-specific requirements. It can accept a number of arguments:

  -? ............ Show the help screen.
  -h ............ Show the help screen.

  delphi ........ Compile with Delphi (any version). DCC32 must be in the PATH.
  fpc ........... Compile with FreePascal. FPC must be in the PATH.

  cli ........... Include the command-line version in YTD.
  nocli ......... Remove the command-line version from YTD.
  gui ........... Include the graphical version in YTD.
  nogui ......... Remove the graphical version from YTD.
  xxx ........... Include support for porn providers in YTD.
  noxxx ......... Remove support for porn providers from YTD.
  setup ......... Include support for automatic installation and upgrade.
  nosetup ....... Remove support for automatic installation and upgrade.

  (and several others, which are undocumented and unsupported)

Compiling from Delphi IDE is also possible, e.g. to facilitate debuging, but
each version of Delphi requires somewhat different settings of directories
in Project Options; specifically, the Search Path must be updated according
to your version of Delphi:

- Directory "lib\pepak\delphi5" MUST be the first path in Delphi 5.0 (and,
  untested but likely, Delphi 6.0) and MUST NOT be used at all in newer
  versions.
- Path to the DxGetText library must be:
  - Delphi 5.0 - "lib\dxgettext\delphi5"
  - Delphi 2009 - "lib\dxgettext\delphi2009"
  - FreePascal - "lib\dxgettext\fpc"
  - others - "lib\dxgettext"

With FreePascal, the graphical interface is only supported in the WinAPI mode
(DEFINE GUI_WINAPI in ytd.inc).



16. LICENSE
-----------

YouTube Downloader is published under the new BSD license. You can read the
full terms and conditions in file DOC/LICENSE.TXT.

If you need to use a different license in your derived program, contact me.

Third-party components, located in the SOURCE/LIB directory, are governed
by their own respective licenses. For this reason YouTube Downloader as a
whole can't be released under GNU GPL (any version). The same is true for
derivative works - while YTD's license is compatible with GPL and could be
re-licensed, you'd have to rewrite the concerned libraries.

Used libraries and their licenses:

- AdobeHDS
  - author: K-S-V
  - source: https://raw.github.com/K-S-V/Scripts/master/AdobeHDS.php
  - license: unknown open-source
  - description: Downloading of the Adobe HDS streams.

- DxGetText
  - authors: Lars B. Dybdahl, Peter Thörnqvist
  - source: http://dxgettext.po.dk/
  - license: custom, freeware
  - description: Support for internationalization

- FastMM
  - author: Pierre le Riche
  - source: http://fastmm.sourceforge.net/
  - license: GNU LGPL 2.1 / Mozilla Public License 1.1
  - description: A fast memory manager (used only in the DEBUG mode because it
                 can detect memory leaks)

- lkJSON
  - author: Leonid Koninin
  - source: http://sourceforge.net/projects/lkjson/files
  - license: BSD
  - description: Library providing JSON support

- MSDL
  - author: Jun "metro" Oyama (me_t_ro@yahoo.com)
  - source: http://msdl.sourceforge.net/
  - license: GNU GPL v3
  - description: Tool for downloading MMS, RTSP and related protocols

- MSDL_DLL
  - author: Pepak
  - source: http://www.pepak.net/download/youtube-downloader/
  - license: GNU GPL v3
  - description: MSDL modified to the form of a DLL

- NativeXml
  - author: Nils Haeck
  - source: http://www.simdesign.nl/xml.html
  - license: custom, freeware
  - XML support

- PerlRegEx
  - author: Jan Goyvaerts
  - source: http://www.regular-expressions.info/delphi.html
  - license: Mozilla Public License 1.1
  - description: Regular expressions support

- RTMPDUMP
  - autoři: Andrej Stepanchuk, Howard Chu
  - source: http://rtmpdump.mplayerhq.hu/
            https://github.com/svnpenn/rtmpdump
  - license: GNU GPL v2
  - description: Tool for ddownloading RTMP and related protocols

- RTMPDUMP_DLL
  - author: Pepak
  - source: http://www.pepak.net/download/youtube-downloader/
  - license: GNU GPL v2
  - description: RTMPDUMP modified to the form of a DLL

- Silk Icon Pack
  - author: Mark James
  - source: http://www.famfamfam.com/lab/icons/silk/
  - license: Creative Common Attribution 2.5
  - description: Icons used in the GUI version of YouTube Downloader

- Synapse
  - author: Lukáš Gebauer
  - source: http://synapse.ararat.cz/
  - license: custom, freeware
  - description: Support for TCP/IP, HTTP and other common protocols

Translations:

- Russian: Litew (litew9@gmail.com).
- Slovak: Vladimír Kubala (kubalav@gmail.com).

Graphics:

- The program icon was created by user KRYSPIN of Hofyland.cz.
