2465acb451
* docs(docker): Clarify where the configuration is The docs move from installation with Docker straight to modifying the configuration without detailing where those files are. * docs(start): Defining comments is discracting This one is squarely me with my editor's red pen, do what you will. I whole heartedly agree with this statement about comments and the intention (I assume) to encourage new users to comment their configurations early and often. I just think this isn't the right place for it and makes this document less focused and effective. * docs(start): Less technical YAML key description * docs(intro): Update and clarify goals/motivation To help calibrate our collaboration, I went uninhibited with these changes including: - assumptions about history I don't actually know: "this project was one of the early entrants" - description of the yt-dlp/ytdl-sub division of labor I'm not actually certain about - max opinion, both about this project and the domain in general - max cheeky/fun writing tone, with the intention of being personable - max editor's red pen, cut mercilessly IOW, review carefully and reject early and often to help me submit future changes that require less review and revision. To that end, give me more rather than less feedback on this change in particular. I include an endorsement of Pinchflat because [they do the same for ytdl-sub](https://github.com/kieraneglin/pinchflat?tab=readme-ov-file#what-it-does). It would be my next choice if ytdl-sub couldn't meet my needs or vanquished me. More than that link, in other Reddit comments and the like, the Pinchflat author clearly expresses preference for ytdl-sub as their own "next option".
121 lines
3.6 KiB
ReStructuredText
121 lines
3.6 KiB
ReStructuredText
==================
|
|
Subscription File
|
|
==================
|
|
|
|
A subscription file is designed to both define and organize many things
|
|
to download in condensed YAML.
|
|
|
|
.. hint::
|
|
|
|
Read the :ref:`getting started guide <guides/getting_started/index:Getting Started>`
|
|
first before reviewing this section.
|
|
|
|
File Preset
|
|
-----------
|
|
Many examples show ``__preset__`` at the top. This is known as the *subscription file preset*.
|
|
It is where a single :ref:`preset <guides/getting_started/first_config:Custom Preset Definition>`
|
|
can be defined that gets applied to each subscription within the file.
|
|
|
|
This is a good place to apply file-wide variables such as ``tv_show_directory`` or
|
|
supply a cookies file path.
|
|
|
|
.. code-block:: yaml
|
|
|
|
__preset__:
|
|
overrides:
|
|
tv_show_directory: "/tv_shows"
|
|
|
|
ytdl_options:
|
|
cookiefile: "/config/cookie.txt"
|
|
|
|
|
|
Layout
|
|
------
|
|
A subscription file is comprised of YAML keys and values. Keys can be either
|
|
|
|
- a preset
|
|
- an override value
|
|
- a subscription name
|
|
|
|
Take the following example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
Jellyfin TV Show by Date:
|
|
= News:
|
|
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
|
|
"BBC News": "https://www.youtube.com/@BBCNews"
|
|
|
|
All three types of keys are used for the following:
|
|
|
|
- ``Jellyfin TV Show by Date`` - a prebuilt preset
|
|
- ``= News`` - an override value for genre
|
|
- ``Breaking News``, ``BBC News`` - The subscription names
|
|
|
|
The lowest level, most indented keys should always be the subscription name.
|
|
It is good practice to put subscription names in quotes to differentiate
|
|
between preset names and subscription names.
|
|
|
|
Values should always be the subscription itself. The simplest form is
|
|
just the URL. Further sections will show more exotic examples that go beyond
|
|
a single URL.
|
|
|
|
|
|
Inheritance
|
|
-----------
|
|
A subscription inherits every key above it. In the above example,
|
|
both ``Breaking News`` and ``BBC News`` inherits the ``Jellyfin TV Show by Date``
|
|
preset and the ``= News`` override value.
|
|
|
|
.. note::
|
|
|
|
There are no limits or boundaries on how one structures
|
|
their presets. This flexibility is intended for subscription authors
|
|
to organize their downloads as they see fit.
|
|
|
|
Multi Keys
|
|
----------
|
|
Subscription keys support pipe syntax, or ``|``, which allows multiple
|
|
keys to be defined on a single line. The following is equivalent to the above
|
|
example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
Jellyfin TV Show by Date | = News:
|
|
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
|
|
"BBC News": "https://www.youtube.com/@BBCNews"
|
|
|
|
Override Mode
|
|
-------------
|
|
Often times, it is convenient to set multiple override values for
|
|
a single subscription. We can put a preset in *override mode* by
|
|
using tilda syntax, or ``~``.
|
|
|
|
Suppose we want to apply the :ref:`Only Recent <prebuilt_presets/helpers:Only Recent>`
|
|
preset to the above examples. But for ``BBC News`` specifically, we want to
|
|
set the date range to be different than the default ``2months`` value to
|
|
``2weeks``.
|
|
|
|
We can change it as follows:
|
|
|
|
.. code-block:: yaml
|
|
|
|
Jellyfin TV Show by Date
|
|
= News | Only Recent:
|
|
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
|
|
"~BBC News":
|
|
url: "https://www.youtube.com/@BBCNews"
|
|
only_recent_date_range: "2weeks"
|
|
|
|
.. important::
|
|
|
|
When using override mode, we need to set the ``url``
|
|
variable since we are no longer using the simplified
|
|
*subscription_value*. For more info on how this works,
|
|
read about :ref:`subscription variables <config_reference/scripting/static_variables:Subscription Variables>`.
|
|
|
|
Map Mode
|
|
--------
|
|
Map mode is for highly advanced presets that benefit
|
|
from a more complex subscription definition. TODO: Show music video
|
|
example here.
|