==================
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
~~~~~~~~~~~~

Without this key, ``ytdl-sub`` only prints output to it's ``stdout`` and ``stderr``. If
your configuration includes the ``persist_logs:`` key, then ``ytdl-sub`` also writes log
files to disk.

.. warning::

   The log files grow rapidly if ``keep_successful_logs:`` is ``true``, the default, and
   may fill up disk space. Set ``keep_successful_logs: false`` or prune the log files
   regularly.

For example:

.. code-block:: yaml

  configuration:
    persist_logs:
      logs_directory: "/path/to/log/directory"

.. 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