f88b27ffec
* docs(preset): Config file top presets vs base * docs(throttle): resolution/quality throttle asset I also added the "wait a few hours and try again" hint, sorry I didn't think of this when reviewing your PR. While doing that I also reformatted the `%concat(...)` arguments to be more readable to me. Particularly to keep clear what punctuation is about argument separation as opposed to punctuation meant to be included in the resulting string. Not a strong preference if you don't like it. * docs(various): Minor typo and formatting fixes * docs(preset): Fix presets vs preset in config file From [feedback](https://github.com/jmbannon/ytdl-sub/pull/1289#discussion_r2289960678). * test(throttle): Match modified assertion text If it were my test, I'd only make assertions on the spirit of error message text necessary to confirm it's the right error message and not another. * docs(throttle): More likely override value From [feedback](https://github.com/jmbannon/ytdl-sub/pull/1289#discussion_r2289976156).
117 lines
3.1 KiB
ReStructuredText
117 lines
3.1 KiB
ReStructuredText
==================
|
|
Configuration File
|
|
==================
|
|
|
|
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
|
|
-------
|
|
|
|
Each key under ``presets:`` defines a `formula` for how to format downloaded media and
|
|
metadata. The key is the name of the preset and the value is a mapping that defines the
|
|
preset.
|
|
|
|
.. note::
|
|
|
|
The ``presets:`` key at the top of the configuration file contains multiple
|
|
user-defined presets, but *each preset* itself may include a ``preset:`` key that
|
|
defines *that preset's* base presets. For example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
presets:
|
|
Foo Preset:
|
|
preset:
|
|
- "Jellyfin TV Show by Date"
|
|
- "Only Recent"
|
|
|
|
preset
|
|
~~~~~~
|
|
|
|
Presets support inheritance by defining one or more parent presets:
|
|
|
|
.. 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``.
|
|
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. More
|
|
specifically, presets are merged using `mergedeep`_ via `a TYPESAFE_ADDITIVE merge`_,
|
|
which means:
|
|
|
|
- if two conflicting keys arent lists or mappings, overwrite the higher priority one
|
|
- otherwise, combine then re-evaluate
|
|
|
|
If you are only inheriting from one preset, using a single string instead of a list is
|
|
valid, for example ``preset: "parent_preset"``, but we recommend always using a list for
|
|
consistent readability between presets.
|
|
|
|
.. _`mergedeep`:
|
|
https://mergedeep.readthedocs.io/en/latest/
|
|
.. _`a TYPESAFE_ADDITIVE merge`:
|
|
https://mergedeep.readthedocs.io/en/latest/index.html#merge-strategies
|