361 lines
10 KiB
ReStructuredText
361 lines
10 KiB
ReStructuredText
Config
|
|
======
|
|
ytdl-sub is configured using a ``config.yaml`` file.
|
|
|
|
.. _config_yaml:
|
|
|
|
config.yaml
|
|
-----------
|
|
|
|
The ``config.yaml`` is made up of two sections:
|
|
|
|
.. code-block:: yaml
|
|
|
|
configuration:
|
|
presets:
|
|
|
|
You can jump to any section and subsection of the config using the navigation
|
|
section to the left.
|
|
|
|
configuration
|
|
^^^^^^^^^^^^^
|
|
The ``configuration`` section contains app-wide configs applied to all presets
|
|
and subscriptions.
|
|
|
|
.. autoclass:: ytdl_sub.config.config_validator.ConfigOptions()
|
|
:members:
|
|
:member-order: bysource
|
|
|
|
|
|
presets
|
|
^^^^^^^
|
|
``presets`` define a `formula` for how to format downloaded media and metadata.
|
|
|
|
download_strategy
|
|
"""""""""""""""""
|
|
Download strategies dictate what is getting downloaded from a source. Each
|
|
download strategy has its own set of parameters.
|
|
|
|
.. _url:
|
|
|
|
url
|
|
'''
|
|
.. autoclass:: ytdl_sub.downloaders.generic.url.UrlDownloadOptions()
|
|
:members: url, playlist_thumbnails, source_thumbnails
|
|
:member-order: bysource
|
|
|
|
multi_url
|
|
'''''''''
|
|
.. autoclass:: ytdl_sub.downloaders.generic.multi_url.MultiUrlDownloadOptions()
|
|
:members: urls, variables
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
output_options
|
|
""""""""""""""
|
|
|
|
.. autoclass:: ytdl_sub.config.preset_options.OutputOptions()
|
|
:members:
|
|
:member-order: bysource
|
|
:exclude-members: get_upload_date_range_to_keep
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
.. _ytdl_options:
|
|
|
|
ytdl_options
|
|
""""""""""""
|
|
.. autoclass:: ytdl_sub.config.preset_options.YTDLOptions()
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
.. _overrides:
|
|
|
|
overrides
|
|
"""""""""
|
|
.. autoclass:: ytdl_sub.config.preset_options.Overrides()
|
|
|
|
.. _parent preset:
|
|
|
|
preset
|
|
""""""
|
|
Presets support inheritance by defining a parent preset:
|
|
|
|
.. code-block:: yaml
|
|
|
|
presets:
|
|
custom_preset:
|
|
...
|
|
parent_preset:
|
|
...
|
|
child_preset:
|
|
preset: "parent_preset"
|
|
|
|
In the example above, ``child_preset`` inherits all fields defined in ``parent_preset``.
|
|
It is advantageous to use parent presets where possible to reduce duplicate yaml
|
|
definitions.
|
|
|
|
Presets also support inheritance from multiple presets:
|
|
|
|
.. code-block:: yaml
|
|
|
|
child_preset:
|
|
preset:
|
|
- "custom_preset"
|
|
- "parent_preset"
|
|
|
|
In this example, ``child_preset`` will inherit all fields from ``custom_preset``
|
|
and ``parent_preset`` in that order. The bottom-most preset has the highest
|
|
priority.
|
|
|
|
If you are only inheriting from one preset, the syntax ``preset: "parent_preset"`` is
|
|
valid YAML. Inheriting from multiple presets require use of a list.
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
Plugins
|
|
"""""""
|
|
Plugins are used to perform any type of post-processing to the already downloaded files.
|
|
|
|
audio_extract
|
|
'''''''''''''
|
|
.. autoclass:: ytdl_sub.plugins.audio_extract.AudioExtractOptions()
|
|
:members:
|
|
:member-order: bysource
|
|
:exclude-members: partial_validate
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
chapters
|
|
''''''''
|
|
.. autoclass:: ytdl_sub.plugins.chapters.ChaptersOptions()
|
|
:members:
|
|
:member-order: bysource
|
|
:exclude-members: partial_validate
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
date_range
|
|
''''''''''
|
|
.. autoclass:: ytdl_sub.plugins.date_range.DateRangeOptions()
|
|
:members:
|
|
:member-order: bysource
|
|
:exclude-members: partial_validate
|
|
|
|
file_convert
|
|
''''''''''''
|
|
.. autoclass:: ytdl_sub.plugins.file_convert.FileConvertOptions()
|
|
:members:
|
|
:member-order: bysource
|
|
:exclude-members: partial_validate
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
match_filters
|
|
'''''''''''''
|
|
.. autoclass:: ytdl_sub.plugins.match_filters.MatchFiltersOptions()
|
|
:members:
|
|
:exclude-members: partial_validate
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
music_tags
|
|
''''''''''
|
|
.. autoclass:: ytdl_sub.plugins.music_tags.MusicTagsOptions()
|
|
:members:
|
|
:exclude-members: partial_validate
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
nfo_tags
|
|
''''''''
|
|
.. autoclass:: ytdl_sub.plugins.nfo_tags.NfoTagsOptions()
|
|
:members: nfo_name, nfo_root, tags, kodi_safe
|
|
:member-order: bysource
|
|
:exclude-members: partial_validate
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
output_directory_nfo_tags
|
|
'''''''''''''''''''''''''
|
|
.. autoclass:: ytdl_sub.plugins.output_directory_nfo_tags.OutputDirectoryNfoTagsOptions()
|
|
:members: nfo_name, nfo_root, tags, kodi_safe
|
|
:member-order: bysource
|
|
:exclude-members: partial_validate
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
regex
|
|
'''''
|
|
.. autoclass:: ytdl_sub.plugins.regex.RegexOptions()
|
|
:members: skip_if_match_fails
|
|
|
|
.. autoclass:: ytdl_sub.plugins.regex.SourceVariableRegex()
|
|
:members: match, capture_group_names, capture_group_defaults
|
|
:member-order: bysource
|
|
:exclude-members: partial_validate
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
split_by_chapters
|
|
'''''''''''''''''
|
|
.. autoclass:: ytdl_sub.plugins.split_by_chapters.SplitByChaptersOptions()
|
|
:members: when_no_chapters
|
|
:member-order: bysource
|
|
:exclude-members: partial_validate
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
subtitles
|
|
'''''''''
|
|
.. autoclass:: ytdl_sub.plugins.subtitles.SubtitleOptions()
|
|
:members: subtitles_name, subtitles_type, embed_subtitles, languages, allow_auto_generated_subtitles
|
|
:member-order: bysource
|
|
:exclude-members: partial_validate
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
video_tags
|
|
''''''''''
|
|
.. autoclass:: ytdl_sub.plugins.video_tags.VideoTagsOptions()
|
|
:members:
|
|
:exclude-members: partial_validate
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
.. _subscription_yaml:
|
|
|
|
subscription.yaml
|
|
-----------------
|
|
The ``subscription.yaml`` file is where we use our `presets`_ in the `config.yaml`_
|
|
to define a `subscription`: something we want to recurrently download such as a specific
|
|
channel or playlist.
|
|
|
|
The only difference between a ``subscription`` and ``preset`` is that the subscription
|
|
must have all required fields and ``{variables}`` defined so it can perform a download.
|
|
|
|
Below is an example that downloads a YouTube playlist:
|
|
|
|
.. code-block:: yaml
|
|
:caption: config.yaml
|
|
|
|
presets:
|
|
playlist_preset_ex:
|
|
download:
|
|
download_strategy: "url"
|
|
url: "{url}"
|
|
output_options:
|
|
output_directory: "{output_directory}/{playlist_name}"
|
|
file_name: "{playlist_name}.{title}.{ext}"
|
|
overrides:
|
|
output_directory: "/path/to/ytdl-sub-videos"
|
|
|
|
.. code-block:: yaml
|
|
:caption: subscription.yaml
|
|
|
|
my_subscription_name:
|
|
preset: "playlist_preset_ex"
|
|
overrides:
|
|
playlist_name: "diy-playlist"
|
|
url: "https://youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg"
|
|
|
|
Our preset ``playlist_preset_ex`` defines three
|
|
custom variables: ``{output_directory}``, ``{playlist_name}``, and ``{url}``. The subscription sets
|
|
the `parent preset`_ to ``playlist_preset_ex``, and must define the variables ``{playlist_name}``
|
|
and ``{url}`` since the preset did not.
|
|
|
|
File Preset
|
|
^^^^^^^^^^^
|
|
You can apply a preset to all subscriptions in the ``subscription.yaml`` file
|
|
by using the file-wide ``__preset__``:
|
|
|
|
.. code-block:: yaml
|
|
:caption: subscription.yaml
|
|
|
|
__preset__:
|
|
preset: "playlist_preset_ex"
|
|
|
|
my_subscription_name:
|
|
overrides:
|
|
url: "https://youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg"
|
|
playlist_name: "diy-playlist"
|
|
|
|
This ``subscription.yaml`` is equivalent to the one above it because all
|
|
subscriptions automatically set ``__preset__`` as a `parent preset`_.
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
.. _source-variables:
|
|
|
|
Source Variables
|
|
----------------
|
|
|
|
.. autoclass:: ytdl_sub.entries.variables.entry_variables.EntryVariables
|
|
:members:
|
|
:inherited-members:
|
|
:undoc-members:
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
Config Types
|
|
------------
|
|
The `config.yaml`_ uses various types for its configurable fields. Below is a definition for each type.
|
|
|
|
.. autoclass:: ytdl_sub.validators.string_formatter_validators.StringFormatterValidator()
|
|
|
|
.. autoclass:: ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator()
|
|
|
|
.. autoclass:: ytdl_sub.validators.string_datetime.StringDatetimeValidator()
|
|
|
|
.. autoclass:: ytdl_sub.validators.string_formatter_validators.DictFormatterValidator()
|
|
|
|
.. autoclass:: ytdl_sub.validators.string_formatter_validators.OverridesDictFormatterValidator()
|
|
|
|
Deprecation Updates
|
|
-------------------
|
|
|
|
.. _yt_deprecate:
|
|
|
|
youtube download strategy
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
The ``youtube`` download strategies will be removed in ytdl-sub 0.6 in favor of the
|
|
:ref:`url` download strategy. Update your configs from:
|
|
|
|
.. code-block:: yaml
|
|
:caption: deprecated download strategy
|
|
|
|
my_subscription_name:
|
|
youtube:
|
|
download_strategy: "channel"
|
|
channel_url: "https://www.youtube.com/c/ProjectZombie603"
|
|
channel_avatar_path: "poster.jpg"
|
|
channel_banner_path: "banner.jpg"
|
|
|
|
to
|
|
|
|
.. code-block:: yaml
|
|
:caption: updated download strategy
|
|
|
|
my_subscription_name:
|
|
download:
|
|
download_strategy: "url"
|
|
url: "https://www.youtube.com/c/ProjectZombie603"
|
|
playlist_thumbnails:
|
|
- name: "poster.jpg"
|
|
uid: "avatar_uncropped"
|
|
- name: "banner.jpg"
|
|
uid: "banner_uncropped"
|
|
|
|
Despite the longer definition, this more generic download strategy will work
|
|
with any yt-dlp supported site and can better adapt to external changes without
|
|
needing to change the codebase.
|
|
|
|
.. _sc_deprecate:
|
|
|
|
soundcloud download strategy
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
The ``soundcloud`` download strategies will be removed in ytdl-sub 0.6 in favor
|
|
of the :ref:`url` download strategy. Refer to the
|
|
`soundcloud discography config <https://github.com/jmbannon/ytdl-sub/blob/master/examples/soundcloud_discography_config.yaml>`_.
|
|
example on how to update.
|