Splitting config.rst
Also some minor accessibility updates (alt text on intro images)
This commit is contained in:
Qualis Svagtlys
parent
1579d4430a
commit
c61f7f60d3
10 changed files with 440 additions and 445 deletions
|
|
@ -1,443 +1,6 @@
|
||||||
Config
|
|
||||||
======
|
|
||||||
ytdl-sub is configured using a ``config.yaml`` file.
|
|
||||||
|
|
||||||
.. _config:
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Note for Windows users, paths can be represented with ``C:/forward/slashes/like/linux``.
|
|
||||||
If you wish to represent paths like Windows, you will need to ``C:\\double\\bashslash\\paths``
|
|
||||||
in order to escape the backslash character.
|
|
||||||
|
|
||||||
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
|
|
||||||
:exclude-members: subscription_value, persist_logs, experimental
|
|
||||||
|
|
||||||
persist_logs
|
|
||||||
""""""""""""
|
|
||||||
Within ``configuration``, define whether logs from subscription downloads
|
|
||||||
should be persisted.
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
configuration:
|
|
||||||
persist_logs:
|
|
||||||
logs_directory: "/path/to/log/directory"
|
|
||||||
|
|
||||||
Log files are stored as
|
|
||||||
``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``.
|
|
||||||
|
|
||||||
.. autoclass:: ytdl_sub.config.config_validator.PersistLogsValidator()
|
|
||||||
: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.url.url.UrlDownloadOptions()
|
|
||||||
:members: url, playlist_thumbnails, source_thumbnails, download_reverse
|
|
||||||
:member-order: bysource
|
|
||||||
|
|
||||||
multi_url
|
|
||||||
'''''''''
|
|
||||||
.. autoclass:: ytdl_sub.downloaders.url.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, partial_validate
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
.. _ytdl_options:
|
|
||||||
|
|
||||||
ytdl_options
|
|
||||||
""""""""""""
|
|
||||||
.. autoclass:: ytdl_sub.config.preset_options.YTDLOptions()
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
.. _overrides:
|
|
||||||
|
|
||||||
overrides
|
|
||||||
"""""""""
|
|
||||||
.. autoclass:: ytdl_sub.config.overrides.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
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
embed_thumbnail
|
|
||||||
''''''''''''''''
|
|
||||||
|
|
||||||
.. autoclass:: ytdl_sub.plugins.embed_thumbnail.EmbedThumbnailOptions()
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
file_convert
|
|
||||||
''''''''''''
|
|
||||||
.. autoclass:: ytdl_sub.plugins.file_convert.FileConvertOptions()
|
|
||||||
:members:
|
|
||||||
:member-order: bysource
|
|
||||||
:exclude-members: partial_validate
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
format
|
|
||||||
''''''
|
|
||||||
.. autoclass:: ytdl_sub.plugins.format.FormatOptions()
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
match_filters
|
|
||||||
'''''''''''''
|
|
||||||
.. autoclass:: ytdl_sub.plugins.match_filters.MatchFiltersOptions()
|
|
||||||
:members:
|
|
||||||
:member-order: bysource
|
|
||||||
:exclude-members: partial_validate
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
music_tags
|
|
||||||
''''''''''
|
|
||||||
.. autoclass:: ytdl_sub.plugins.music_tags.MusicTagsOptions()
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
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.VariableRegex()
|
|
||||||
:members: match, capture_group_names, capture_group_defaults, exclude
|
|
||||||
: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
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
throttle_protection
|
|
||||||
'''''''''''''''''''
|
|
||||||
.. autoclass:: ytdl_sub.plugins.throttle_protection.ThrottleProtectionOptions()
|
|
||||||
:members:
|
|
||||||
:member-order: bysource
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
video_tags
|
|
||||||
''''''''''
|
|
||||||
.. autoclass:: ytdl_sub.plugins.video_tags.VideoTagsOptions()
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
.. _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.
|
|
||||||
|
|
||||||
Beautifying Subscriptions
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
Subscriptions support using presets as keys, and using keys to set override variables as values.
|
|
||||||
For example:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
:caption: subscription.yaml
|
|
||||||
|
|
||||||
TV Show Full Archive:
|
|
||||||
= News:
|
|
||||||
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
|
|
||||||
|
|
||||||
TV Show Only Recent:
|
|
||||||
= Tech | TV-Y:
|
|
||||||
"Two Minute Papers": "https://www.youtube.com/@TwoMinutePapers"
|
|
||||||
|
|
||||||
Will create two subscriptions named "Breaking News" and "Two Minute Papers", equivalent to:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
"Breaking News":
|
|
||||||
preset:
|
|
||||||
- "TV Show Full Archive"
|
|
||||||
|
|
||||||
overrides:
|
|
||||||
subscription_indent_1: "News"
|
|
||||||
subscription_name: "Breaking News"
|
|
||||||
subscription_value: "https://www.youtube.com/@SomeBreakingNews"
|
|
||||||
|
|
||||||
"Two Minute Papers":
|
|
||||||
preset:
|
|
||||||
- "TV Show Only Recent"
|
|
||||||
|
|
||||||
overrides:
|
|
||||||
subscription_indent_1: "Tech"
|
|
||||||
subscription_indent_2: "TV-Y"
|
|
||||||
subscription_name: "Two Minute Papers"
|
|
||||||
subscription_value: "https://www.youtube.com/@TwoMinutePapers"
|
|
||||||
|
|
||||||
You can provide as many parent presets in the form of keys, and subscription indents as ``=keys``.
|
|
||||||
This can drastically simplify subscription definitions by setting things like so in your
|
|
||||||
parent preset:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
presets:
|
|
||||||
"TV Show Preset":
|
|
||||||
overrides:
|
|
||||||
subscription_indent_1: "default-genre"
|
|
||||||
subscription_indent_2: "default-content-rating"
|
|
||||||
|
|
||||||
tv_show_name: "{subscription_name}"
|
|
||||||
url: "{subscription_value}"
|
|
||||||
genre: "{subscription_indent_1}"
|
|
||||||
content_rating: "{subscription_indent_2}"
|
|
||||||
|
|
||||||
.. _subscription value:
|
|
||||||
|
|
||||||
File Preset
|
|
||||||
~~~~~~~~~~~
|
|
||||||
NOTE: This is deprecated in favor of using the method in :ref:`code_reference/config:beautifying subscriptions`.
|
|
||||||
|
|
||||||
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`_.
|
|
||||||
|
|
||||||
|
|
||||||
Subscription Value
|
|
||||||
~~~~~~~~~~~~~~~~~~~
|
|
||||||
NOTE: This is deprecated in favor of using the method in :ref:`code_reference/config:beautifying subscriptions`.
|
|
||||||
|
|
||||||
With a clever config and use of ``__preset__``, your subscriptions can typically boil
|
|
||||||
down to a name and url. You can set ``__value__`` to the name of an override variable,
|
|
||||||
and use the override variable ``subscription_name`` to achieve one-liner subscriptions.
|
|
||||||
Using the example above, we can do:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
:caption: subscription.yaml
|
|
||||||
|
|
||||||
__preset__:
|
|
||||||
preset:
|
|
||||||
- "tv_show"
|
|
||||||
overrides:
|
|
||||||
tv_show_name: "{subscription_name}"
|
|
||||||
|
|
||||||
__value__: "url"
|
|
||||||
|
|
||||||
# single-line subscription, sets "Brandon Acker" and the subscription value
|
|
||||||
# to the override variables tv_show_name and url
|
|
||||||
"Brandon Acker": "https://www.youtube.com/@brandonacker"
|
|
||||||
|
|
||||||
Traditional subscriptions that can override presets will still work when using ``__value__``.
|
|
||||||
``__value__`` can also be set within a :ref:`config`.
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
.. _source-variables:
|
|
||||||
|
|
||||||
Source Variables
|
|
||||||
----------------
|
|
||||||
|
|
||||||
.. autoclass:: ytdl_sub.entries.script.variable_definitions.VariableDefinitions()
|
|
||||||
:members:
|
|
||||||
:inherited-members:
|
|
||||||
:undoc-members:
|
|
||||||
|
|
||||||
Override Variables
|
|
||||||
------------------
|
|
||||||
|
|
||||||
.. autoclass:: ytdl_sub.entries.variables.override_variables.OverrideVariables()
|
|
||||||
:members:
|
|
||||||
:member-order: bysource
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Config Types
|
Config Types
|
||||||
------------
|
------------
|
||||||
The `config.yaml`_ uses various types for its configurable fields. Below is a definition for each type.
|
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.StringFormatterValidator()
|
||||||
|
|
||||||
|
|
|
||||||
134
docs/source/code_reference/config_yaml.rst
Normal file
134
docs/source/code_reference/config_yaml.rst
Normal file
|
|
@ -0,0 +1,134 @@
|
||||||
|
==================
|
||||||
|
Configuration File
|
||||||
|
==================
|
||||||
|
-----------
|
||||||
|
config.yaml
|
||||||
|
-----------
|
||||||
|
|
||||||
|
ytdl-sub is configured using a ``config.yaml`` file.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Note for Windows users, paths can be represented with ``C:/forward/slashes/like/linux``.
|
||||||
|
If you wish to represent paths like Windows, you will need to ``C:\\double\\bashslash\\paths``
|
||||||
|
in order to escape the backslash character.
|
||||||
|
|
||||||
|
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
|
||||||
|
:exclude-members: subscription_value, persist_logs, experimental
|
||||||
|
|
||||||
|
persist_logs
|
||||||
|
""""""""""""
|
||||||
|
Within ``configuration``, define whether logs from subscription downloads
|
||||||
|
should be persisted.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
configuration:
|
||||||
|
persist_logs:
|
||||||
|
logs_directory: "/path/to/log/directory"
|
||||||
|
|
||||||
|
Log files are stored as
|
||||||
|
``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``.
|
||||||
|
|
||||||
|
.. autoclass:: ytdl_sub.config.config_validator.PersistLogsValidator()
|
||||||
|
: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.url.url.UrlDownloadOptions()
|
||||||
|
:members: url, playlist_thumbnails, source_thumbnails, download_reverse
|
||||||
|
:member-order: bysource
|
||||||
|
|
||||||
|
multi_url
|
||||||
|
'''''''''
|
||||||
|
.. autoclass:: ytdl_sub.downloaders.url.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, partial_validate
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
.. _ytdl_options:
|
||||||
|
|
||||||
|
ytdl_options
|
||||||
|
""""""""""""
|
||||||
|
.. autoclass:: ytdl_sub.config.preset_options.YTDLOptions()
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
.. _overrides:
|
||||||
|
|
||||||
|
overrides
|
||||||
|
"""""""""
|
||||||
|
.. autoclass:: ytdl_sub.config.overrides.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.
|
||||||
8
docs/source/code_reference/entry_variables.rst
Normal file
8
docs/source/code_reference/entry_variables.rst
Normal file
|
|
@ -0,0 +1,8 @@
|
||||||
|
===============
|
||||||
|
Entry Variables
|
||||||
|
===============
|
||||||
|
|
||||||
|
.. autoclass:: ytdl_sub.entries.script.variable_definitions.VariableDefinitions()
|
||||||
|
:members:
|
||||||
|
:inherited-members:
|
||||||
|
:undoc-members:
|
||||||
|
|
@ -4,4 +4,9 @@ Code Reference
|
||||||
This section contains direct references to the code of ``ytdl-sub`` and information on how it functions.
|
This section contains direct references to the code of ``ytdl-sub`` and information on how it functions.
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
|
config_yaml
|
||||||
|
subscriptions_yaml
|
||||||
|
plugins
|
||||||
|
entry_variables
|
||||||
|
override_variables
|
||||||
config
|
config
|
||||||
7
docs/source/code_reference/override_variables.rst
Normal file
7
docs/source/code_reference/override_variables.rst
Normal file
|
|
@ -0,0 +1,7 @@
|
||||||
|
==================
|
||||||
|
Override Variables
|
||||||
|
==================
|
||||||
|
|
||||||
|
.. autoclass:: ytdl_sub.entries.variables.override_variables.OverrideVariables()
|
||||||
|
:members:
|
||||||
|
:member-order: bysource
|
||||||
128
docs/source/code_reference/plugins.rst
Normal file
128
docs/source/code_reference/plugins.rst
Normal file
|
|
@ -0,0 +1,128 @@
|
||||||
|
=======
|
||||||
|
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
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
embed_thumbnail
|
||||||
|
''''''''''''''''
|
||||||
|
|
||||||
|
.. autoclass:: ytdl_sub.plugins.embed_thumbnail.EmbedThumbnailOptions()
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
file_convert
|
||||||
|
''''''''''''
|
||||||
|
.. autoclass:: ytdl_sub.plugins.file_convert.FileConvertOptions()
|
||||||
|
:members:
|
||||||
|
:member-order: bysource
|
||||||
|
:exclude-members: partial_validate
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
format
|
||||||
|
''''''
|
||||||
|
.. autoclass:: ytdl_sub.plugins.format.FormatOptions()
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
match_filters
|
||||||
|
'''''''''''''
|
||||||
|
.. autoclass:: ytdl_sub.plugins.match_filters.MatchFiltersOptions()
|
||||||
|
:members:
|
||||||
|
:member-order: bysource
|
||||||
|
:exclude-members: partial_validate
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
music_tags
|
||||||
|
''''''''''
|
||||||
|
.. autoclass:: ytdl_sub.plugins.music_tags.MusicTagsOptions()
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
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.VariableRegex()
|
||||||
|
:members: match, capture_group_names, capture_group_defaults, exclude
|
||||||
|
: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
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
throttle_protection
|
||||||
|
'''''''''''''''''''
|
||||||
|
.. autoclass:: ytdl_sub.plugins.throttle_protection.ThrottleProtectionOptions()
|
||||||
|
:members:
|
||||||
|
:member-order: bysource
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
video_tags
|
||||||
|
''''''''''
|
||||||
|
.. autoclass:: ytdl_sub.plugins.video_tags.VideoTagsOptions()
|
||||||
150
docs/source/code_reference/subscriptions_yaml.rst
Normal file
150
docs/source/code_reference/subscriptions_yaml.rst
Normal file
|
|
@ -0,0 +1,150 @@
|
||||||
|
==================
|
||||||
|
Subscriptions File
|
||||||
|
==================
|
||||||
|
------------------
|
||||||
|
subscriptions.yaml
|
||||||
|
------------------
|
||||||
|
|
||||||
|
The ``subscriptions.yaml`` file is where we use our :ref:`code_reference/config_yaml:presets` in the :ref:`code_reference/config_yaml: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.
|
||||||
|
|
||||||
|
Beautifying Subscriptions
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
Subscriptions support using presets as keys, and using keys to set override variables as values.
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
:caption: subscription.yaml
|
||||||
|
|
||||||
|
TV Show Full Archive:
|
||||||
|
= News:
|
||||||
|
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
|
||||||
|
|
||||||
|
TV Show Only Recent:
|
||||||
|
= Tech | TV-Y:
|
||||||
|
"Two Minute Papers": "https://www.youtube.com/@TwoMinutePapers"
|
||||||
|
|
||||||
|
Will create two subscriptions named "Breaking News" and "Two Minute Papers", equivalent to:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
"Breaking News":
|
||||||
|
preset:
|
||||||
|
- "TV Show Full Archive"
|
||||||
|
|
||||||
|
overrides:
|
||||||
|
subscription_indent_1: "News"
|
||||||
|
subscription_name: "Breaking News"
|
||||||
|
subscription_value: "https://www.youtube.com/@SomeBreakingNews"
|
||||||
|
|
||||||
|
"Two Minute Papers":
|
||||||
|
preset:
|
||||||
|
- "TV Show Only Recent"
|
||||||
|
|
||||||
|
overrides:
|
||||||
|
subscription_indent_1: "Tech"
|
||||||
|
subscription_indent_2: "TV-Y"
|
||||||
|
subscription_name: "Two Minute Papers"
|
||||||
|
subscription_value: "https://www.youtube.com/@TwoMinutePapers"
|
||||||
|
|
||||||
|
You can provide as many parent presets in the form of ``keys``, and subscription indents as ``= keys``.
|
||||||
|
This can drastically simplify subscription definitions by setting things like so in your
|
||||||
|
parent preset:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
presets:
|
||||||
|
"TV Show Preset":
|
||||||
|
overrides:
|
||||||
|
subscription_indent_1: "default-genre"
|
||||||
|
subscription_indent_2: "default-content-rating"
|
||||||
|
|
||||||
|
tv_show_name: "{subscription_name}"
|
||||||
|
url: "{subscription_value}"
|
||||||
|
genre: "{subscription_indent_1}"
|
||||||
|
content_rating: "{subscription_indent_2}"
|
||||||
|
|
||||||
|
.. _subscription value:
|
||||||
|
|
||||||
|
File Preset
|
||||||
|
~~~~~~~~~~~
|
||||||
|
NOTE: This is deprecated in favor of using the method in :ref:`code_reference/subscriptions_yaml:beautifying subscriptions`.
|
||||||
|
|
||||||
|
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``.
|
||||||
|
|
||||||
|
|
||||||
|
Subscription Value
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
NOTE: This is deprecated in favor of using the method in :ref:`code_reference/subscriptions_yaml:beautifying subscriptions`.
|
||||||
|
|
||||||
|
With a clever config and use of ``__preset__``, your subscriptions can typically boil
|
||||||
|
down to a name and url. You can set ``__value__`` to the name of an override variable,
|
||||||
|
and use the override variable ``subscription_name`` to achieve one-liner subscriptions.
|
||||||
|
Using the example above, we can do:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
:caption: subscription.yaml
|
||||||
|
|
||||||
|
__preset__:
|
||||||
|
preset:
|
||||||
|
- "tv_show"
|
||||||
|
overrides:
|
||||||
|
tv_show_name: "{subscription_name}"
|
||||||
|
|
||||||
|
__value__: "url"
|
||||||
|
|
||||||
|
# single-line subscription, sets "Brandon Acker" and the subscription value
|
||||||
|
# to the override variables tv_show_name and url
|
||||||
|
"Brandon Acker": "https://www.youtube.com/@brandonacker"
|
||||||
|
|
||||||
|
Traditional subscriptions that can override presets will still work when using ``__value__``.
|
||||||
|
``__value__`` can also be set within a :ref:`code_reference/config_yaml:config.yaml`.
|
||||||
|
|
@ -7,7 +7,7 @@ Oct 2023
|
||||||
subscription preset and value
|
subscription preset and value
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
The use of ``__value__`` will go away in Dec 2023 in favor of the method found in
|
The use of ``__value__`` will go away in Dec 2023 in favor of the method found in
|
||||||
:ref:`code_reference/config:beautifying subscriptions`. ``__preset__`` will still be supported for the time being.
|
:ref:`code_reference/subscriptions_yaml:beautifying subscriptions`. ``__preset__`` will still be supported for the time being.
|
||||||
|
|
||||||
July 2023
|
July 2023
|
||||||
---------
|
---------
|
||||||
|
|
|
||||||
|
|
@ -1,5 +0,0 @@
|
||||||
Initial Setup
|
|
||||||
=============
|
|
||||||
If you haven't read it yet, it's highly recommended to go through our
|
|
||||||
`walk-through guide <https://github.com/jmbannon/ytdl-sub/wiki/1.-Introduction>`_
|
|
||||||
to get familiar with how ``ytdl-sub`` works.
|
|
||||||
|
|
@ -1,3 +1,4 @@
|
||||||
|
=================
|
||||||
What is ytdl-sub?
|
What is ytdl-sub?
|
||||||
=================
|
=================
|
||||||
|
|
||||||
|
|
@ -10,21 +11,25 @@ What is ytdl-sub?
|
||||||
``ytdl-sub`` is a command-line tool that downloads media via `yt-dlp`_ and prepares it for your favorite media player (`Kodi`_, `Jellyfin`_, `Plex`_, `Emby`_, modern music players).
|
``ytdl-sub`` is a command-line tool that downloads media via `yt-dlp`_ and prepares it for your favorite media player (`Kodi`_, `Jellyfin`_, `Plex`_, `Emby`_, modern music players).
|
||||||
|
|
||||||
Visual examples
|
Visual examples
|
||||||
---------------
|
===============
|
||||||
|
|
||||||
.. figure:: https://user-images.githubusercontent.com/10107080/182677243-b4184e51-9780-4094-bd40-ea4ff58555d0.PNG
|
.. figure:: https://user-images.githubusercontent.com/10107080/182677243-b4184e51-9780-4094-bd40-ea4ff58555d0.PNG
|
||||||
|
:alt: The Jellyfin web interface, showing the thumbnails of various YouTube shows.
|
||||||
|
|
||||||
Youtube channels as TV shows in Jellyfin
|
Youtube channels as TV shows in Jellyfin
|
||||||
|
|
||||||
.. figure:: https://user-images.githubusercontent.com/10107080/182677256-43aeb029-0c3f-4648-9fd2-352b9666b262.PNG
|
.. figure:: https://user-images.githubusercontent.com/10107080/182677256-43aeb029-0c3f-4648-9fd2-352b9666b262.PNG
|
||||||
|
:alt: The Jellyfin web interace, showing the thumbnails of various music videos starring the Red Hot Chili Peppers
|
||||||
|
|
||||||
Music videos and concerts in Jellyfin
|
Music videos and concerts in Jellyfin
|
||||||
|
|
||||||
.. figure:: https://user-images.githubusercontent.com/10107080/182677268-d1bf2ff0-9b9c-4a04-98ec-443a67ada734.png
|
.. figure:: https://user-images.githubusercontent.com/10107080/182677268-d1bf2ff0-9b9c-4a04-98ec-443a67ada734.png
|
||||||
|
:alt: The Kodi app interface, showing a list of artists available to watch under the "Music videos" heading
|
||||||
|
|
||||||
Music videos and concerts in Kodi
|
Music videos and concerts in Kodi
|
||||||
|
|
||||||
.. figure:: https://user-images.githubusercontent.com/10107080/182685415-06adf477-3dd3-475d-bbcd-53b0152b9f0a.PNG
|
.. figure:: https://user-images.githubusercontent.com/10107080/182685415-06adf477-3dd3-475d-bbcd-53b0152b9f0a.PNG
|
||||||
|
:alt: The MusicBee app interface, showing a list of album artists and the thumbnails of all downloaded songs produced by the currently selected artist
|
||||||
|
|
||||||
SoundCloud albums and singles in MusicBee
|
SoundCloud albums and singles in MusicBee
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue