sub reference
This commit is contained in:
Jesse Bannon
parent
30d9513ff8
commit
094a5d8405
1 changed files with 80 additions and 92 deletions
|
|
@ -1,114 +1,102 @@
|
||||||
==================
|
==================
|
||||||
Subscriptions File
|
Subscription File
|
||||||
==================
|
==================
|
||||||
|
|
||||||
The ``subscriptions.yaml`` file is where we use :ref:`config_reference/config_yaml:presets`
|
A subscription file is designed to both define and organize many things
|
||||||
to define a ``subscription``: something we want to recurrently download, such as a specific
|
to download in condensed YAML.
|
||||||
channel or playlist.
|
|
||||||
|
|
||||||
The only difference between a ``subscription`` and ``preset`` is that the subscription
|
.. hint::
|
||||||
must have all required variables defined to perform a download.
|
|
||||||
|
|
||||||
Below is an example that downloads a YouTube playlist:
|
Read the :ref:`getting started guide <guides/getting_started:Getting Started>`
|
||||||
|
first before reviewing this section.
|
||||||
|
|
||||||
|
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
|
.. code-block:: yaml
|
||||||
:caption: config.yaml
|
|
||||||
|
|
||||||
presets:
|
Jellyfin TV Show by Date:
|
||||||
playlist_preset_ex:
|
|
||||||
download: "{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:
|
= News:
|
||||||
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
|
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
|
||||||
|
"BBC News": "https://www.youtube.com/@BBCNews"
|
||||||
|
|
||||||
TV Show Only Recent:
|
All three types of keys are used for the following:
|
||||||
= Tech | TV-Y:
|
|
||||||
"Two Minute Papers": "https://www.youtube.com/@TwoMinutePapers"
|
|
||||||
|
|
||||||
Will create two subscriptions named "Breaking News" and "Two Minute Papers", equivalent to:
|
- ``Jellyfin TV Show by Date`` - a prebuilt preset
|
||||||
|
- ``= News`` - an override value for genre
|
||||||
|
- ``Breaking News``, ``BBC News`` - The subscription names
|
||||||
|
|
||||||
.. code-block:: yaml
|
The bottom-most keys, or leaf 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.
|
||||||
|
|
||||||
"Breaking News":
|
Values should always be the subscription itself. The simplest form is
|
||||||
preset:
|
just the URL. Further sections will show more exotic examples that go beyond
|
||||||
- "TV Show Full Archive"
|
a single URL.
|
||||||
|
|
||||||
overrides:
|
|
||||||
subscription_indent_1: "News"
|
|
||||||
subscription_name: "Breaking News"
|
|
||||||
subscription_value: "https://www.youtube.com/@SomeBreakingNews"
|
|
||||||
|
|
||||||
"Two Minute Papers":
|
Inheritance
|
||||||
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}"
|
|
||||||
|
|
||||||
File Preset
|
|
||||||
-----------
|
-----------
|
||||||
|
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.
|
||||||
|
|
||||||
You can apply a preset to all subscriptions in the ``subscription.yaml`` file
|
.. note::
|
||||||
by using the file-wide ``__preset__``:
|
|
||||||
|
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
|
.. code-block:: yaml
|
||||||
:caption: subscription.yaml
|
|
||||||
|
|
||||||
__preset__:
|
Jellyfin TV Show by Date | = News:
|
||||||
preset: "playlist_preset_ex"
|
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
|
||||||
|
"BBC News": "https://www.youtube.com/@BBCNews"
|
||||||
|
|
||||||
my_subscription_name:
|
Override Mode
|
||||||
overrides:
|
-------------
|
||||||
url: "https://youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg"
|
Often times, it is convenient to set multiple override values for
|
||||||
playlist_name: "diy-playlist"
|
a single subscription. We can put a preset in *override mode* by
|
||||||
|
using tilda syntax, or ``~``.
|
||||||
|
|
||||||
This ``subscription.yaml`` is equivalent to the one above it because all
|
Suppose we want to apply the :ref:`Only Recent <prebuilt_presets/helpers:Only Recent>`
|
||||||
subscriptions automatically set ``__preset__`` as a ``parent preset``.
|
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.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue