danvics/ytdl-sub
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[DOCS] start: Clarify subscriptions file tutorial (#1310)

Browse source 
* docs(presets): Stale copied prebuilt comment

* docs(start): How to configure subscriptions

Revise the subscriptions file Getting Started tutorial from the perspective of a new
user. The idea is that the ref docs describe a component as the code sees it, whereas
the how-to/tutorial/getting-started docs provide a narrative description of the
component from the external perspective of a typical new user.

* docs(start): Document subscription override mode

It's debatable whether this belongs here. Having moved onto my own custom presets, the
only use cases for override mode in my subscriptions file are for those series that also
have TVDB metadata. Those ytdl-sub downloads I integrate into my Sonarr library need
per-subscription overrides such as:

- Sonarr manages years 2020-2023 for one series and ytdl-sub fills in
  from there, so set a `sonarr_series_after: "20240101"` override

- each series needs a directory named per Sonarr's configuration with the TVDB ID, the subscription key,
  but also a series name prefix without the TVDB ID for each episode file, so set a
  `sonarr_series_prefix: "Foo Series (2020)"` override

So are there other use cases for override mode that are more common and less niche than
mine?

* docs(docker): Revert example bind mount volumes

Per [PR feedback](https://github.com/jmbannon/ytdl-sub/pull/1310#discussion_r2306067263).
This commit is contained in:
Ross Patterson 2025-08-28 07:09:05 -07:00 committed by GitHub
parent 283ccc8608
commit adb08ed5f9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 195 additions and 150 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/source/config_reference/subscription_yaml.rst
View file

@ -25,9 +25,11 @@ supply a cookies file path.
.. code-block:: yaml
__preset__:
# Variables that override defaults from `overrides:` for presets in YAML keys:
overrides:
tv_show_directory: "/tv_shows"
# Directly set plugin options:
ytdl_options:
cookiefile: "/config/cookie.txt"

8
docs/source/guides/getting_started/automating_downloads.rst
View file

@ -59,3 +59,11 @@ out for us)
.. code-block:: powershell
ytdl-sub.exe --config \path\to\config\config.yaml sub \path\to\config\subscriptions.yaml
Next Steps
----------
Once you have a significant quantity of subscriptions or have use cases not served using
:doc:`YAML keys and the special characters <./subscriptions>`, it's time to start
:doc:`defining your own custom presets <./first_config>`.

4
docs/source/guides/getting_started/first_download.rst
View file

@ -1,8 +1,8 @@
Initial Download
================
Once you have a ``subscriptions.yaml`` file created, you can perform your first
download. Access ``ytdl-sub``, navigate to the directory containing your
Once you've created :doc:`a subscriptions file <./subscriptions>`, you can perform your
first download. Access ``ytdl-sub``, navigate to the directory containing your
``subscriptions.yaml`` file.

128
docs/source/guides/getting_started/first_sub.rst
View file

@ -1,128 +0,0 @@
Initial Subscription
====================
Your first subscription file should look something like this:
.. code-block:: yaml
:linenos:
__preset__:
overrides:
tv_show_directory: "/tv_shows"
music_directory: "/music"
# Can choose between:
# - Plex TV Show by Date:
# - Jellyfin TV Show by Date:
# - Kodi TV Show by Date:
#
Jellyfin TV Show by Date:
= Documentaries:
"NOVA PBS": "https://www.youtube.com/@novapbs"
= Kids | = TV-Y:
"Jake Trains": "https://www.youtube.com/@JakeTrains"
YouTube Releases:
= Jazz: # Sets genre tag to "Jazz"
"Thelonious Monk": "https://www.youtube.com/@theloniousmonk3870/releases"
YouTube Full Albums:
= Lofi:
"Game Chops": "https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i"
Let's break this down:
.. code-block:: yaml
:lineno-start: 1
__preset__:
overrides:
tv_show_directory: "/tv_shows"
music_directory: "/music"
The first :ref:`__preset__ <config_reference/subscription_yaml:File Preset>` section is
where we can set modifications that apply to every subscription in this file.
This snippet specifically adds two :ref:`override <config_reference/plugins:Overrides>`
variables, which are used by the presets below.
.. note::
It is tempting to put any override underneath ``overrides``. Keep in mind that this
section is solely for variable defining. Other :ref:`plugins
<config_reference/plugins:Plugins>` need to be set at the same indentation level as
``overrides``, not within it.
-------------------------------------
.. code-block:: yaml
:lineno-start: 11
Jellyfin TV Show by Date:
On line 11, we set the key to ``Jellyfin TV Show by Date``. This is a :ref:`prebuilt
preset <prebuilt_presets/index:prebuilt presets>` that configures subscriptions to look
like TV shows in the Jellyfin media player (can be changed to one of the presets
outlined in the comment above). Setting it as a YAML key implies that all subscriptions
underneath it will *inherit* this preset.
This preset expects the variable ``tv_show_directory`` to be set, which we do above.
-------------------------------------
.. code-block:: yaml
:lineno-start: 11
Jellyfin TV Show by Date:
= Documentaries:
Line 12 sets the key to ``= Documentaries``. When keys are prefixed with ``=``, it means
we are setting the genre. This value will get written to the respective metadata tags
for both TV show and music presets.
Behind the scenes, this sets the override variable ``subscription_indent_1``. Further
documentation can be found here for :ref:`subscription syntax
<config_reference/subscription_yaml:Subscription File>` and :ref:`subscription variables
<config_reference/scripting/static_variables:Subscription Variables>`.
-------------------------------------
.. code-block:: yaml
:lineno-start: 11
Jellyfin TV Show by Date:
= Documentaries:
"NOVA PBS": "https://www.youtube.com/@novapbs"
Line 13 is where we define our first subscription. We set the subscription name to
``NOVA PBS``, and the subscription value to ``https://www.youtube.com/@novapbs``.
To see how presets ingest subscription definitions, refer to the :ref:`preset references
<config_reference/prebuilt_presets/tv_show:TV Show>`, we can see that
``{subscription_name}`` is used to set the ``tv_show_name`` variable.
-------------------------------------
.. code-block:: yaml
:lineno-start: 11
Jellyfin TV Show by Date:
= Documentaries:
"NOVA PBS": "https://www.youtube.com/@novapbs"
= Kids | = TV-Y:
"Jake Trains": "https://www.youtube.com/@JakeTrains"
Line 15 underneath ``Jellyfin TV Show by Date``, but at the same level as ``=
Documentaries``. This means we'll inherit the TV show preset, but not the documentaries
indent variable. We instead set the indent variables to ``= Kids | = TV-Y``. This sets
two indent variables. We can set multiple presets and/or indent variables on the same
key by using ``|`` as a separator.
Referring to the :ref:`TV show preset reference
<config_reference/prebuilt_presets/tv_show:TV Show>`, the first two indent variables map
to the TV show genre and TV show content rating.
The above info should be enough to understand the rest of the subscription file.

31
docs/source/guides/getting_started/index.rst
View file

@ -39,7 +39,7 @@ For most users, ``ytdl-sub`` works as follows:
Subscriptions use presets
~~~~~~~~~~~~~~~~~~~~~~~~~
Run ``$ ytdl-sub sub`` to read :doc:`a subscription file <./first_sub>` that defines
Run ``$ ytdl-sub sub`` to read :doc:`a subscription file <./subscriptions>` that defines
what subscriptions to download and place into your media library. Each subscription
selects which :doc:`presets <../../prebuilt_presets/index>` to apply. Those presets
configure how each subscription is downloaded and placed in the media library.
@ -94,11 +94,12 @@ Genres are also more often shared between subscriptions than not. To accommodate
reality, the ancestor keys of subscriptions may also use :ref:`the special '= ...'
prefix to pass specific overrides
<config_reference/scripting/static_variables:subscription_indent_i>` supported by the
preset. By convention in the built-in presets, the first ``= ...`` value specifies the
genre for all descendant subscriptions.
preset. By convention in the built-in software and media type presets, the first ``=
...`` value specifies the genre for all descendant subscriptions.
Finally, ancestor keys may use the ``... | ...`` special character to combine multiple
presets and/or genres for the descendant subscriptions beneath.
Finally, ancestor keys may use :ref:`the '... | ...' special character
<config_reference/subscription_yaml:multi keys>` to combine multiple presets and/or
genres for the descendant subscriptions beneath.
The configuration file extends pre-defined presets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -139,22 +140,18 @@ complete details, but for almost all of the use cases served by ``ytdl-sub``, th
is accurate and representative.
Ready to Start?
---------------
Next Steps
----------
Now that you've completed your install of ``ytdl-sub``, it's time to get started. It is
recommended to go through the below sections in order to fully grasp ytdl-sub.
With ``ytdl-sub`` installed and the above understood, the next step is to :doc:`start
adding subscriptions <./subscriptions>`.
.. toctree::
:maxdepth: 2
first_sub
first_download
automating_downloads
first_config
.. toctree::
:hidden:
subscriptions
first_download
automating_downloads
first_config
quick_start

167
docs/source/guides/getting_started/subscriptions.rst Normal file
View file

@ -0,0 +1,167 @@
Subscriptions
=============
Once you understand :ref:`how ytdl-sub works
<guides/getting_started/index:architecture>`, it's time to start writing your
:doc:`../../config_reference/subscription_yaml`.
Media library paths
-------------------
Everyone's media library may use different paths so ``ytdl-sub`` can't provide
defaults. Tell ``ytdl-sub`` where to put your media using :ref:`overrides
<guides/getting_started/index:presets and subscriptions accept overrides>`:
.. code-block:: yaml
:caption: subscriptions.yaml
:emphasize-lines: 3-
__preset__:
overrides:
tv_show_directory: "/tv_shows"
music_directory: "/music"
music_video_directory: "/music_videos"
See the reference documentation for details about :ref:`the '__preset__:' special key
<config_reference/subscription_yaml:file preset>`.
Media library software and media types
--------------------------------------
Different media library software, such as `Jellyfin`_, `Kodi`_, Plex, or Emby, have
different requirements for where media files are placed, how those files are named, how
metadata is formatted, and more. Those software also have different requirements for
different types of media, such as shows/series, music, music videos, etc.. Use
:doc:`prebuilt presets <../../prebuilt_presets/index>` in :ref:`YAML keys
<guides/getting_started/index:subscriptions are grouped by indentation>` to tell
``ytdl-sub`` which media library software and media type to process downloaded files
for.
The actual subscription is defined in the lowest indentation level YAML keys. The
example below defines a subscription named ``NOVA PBS`` to archive downloads from the
entries in the ``https://www.youtube.com/@novapbs`` URL.
.. code-block:: yaml
:caption: subscriptions.yaml
:emphasize-lines: 1,4
Jellyfin TV Show by Date:
"NOVA PBS": "https://www.youtube.com/@novapbs"
Bandcamp:
"Emily Hopkins": "https://emilyharpist.bandcamp.com/"
.. _`Jellyfin`:
https://jellyfin.org/
.. _`Kodi`:
https://kodi.tv/
Which entries
-------------
The :doc:`helper presets <../../prebuilt_presets/helpers>` also provide support for
controlling which entries are downloaded and archived. These presets are intended to be
combined with the library software and media type presets.
Combine presets using :ref:`the '.. | ...' special character
<guides/getting_started/index:subscriptions are grouped by indentation>` in the YAML
keys:
.. code-block:: yaml
:caption: subscriptions.yaml
:emphasize-lines: 2,6
# Only download entries whose upload date is within the past 2 months:
Kodi TV Show by Date | Only Recent:
"NOVA PBS": "https://www.youtube.com/@novapbs"
# Only download 20 entries per run:
Soundcloud Discography | Chunk Downloads:
"UKNOWY": "https://soundcloud.com/uknowymunich"
What format, quality, or resolution
-----------------------------------
The :doc:`media quality presets <../../prebuilt_presets/media_quality>` provide support
for controlling which ``yt-dlp`` media "format" to download, such as ``1080p`` video
resolution or ``320k`` audio bitrate.
Users may also group and combine presets :ref:`using the YAML hierarchy
<guides/getting_started/index:subscriptions are grouped by indentation>`. Subscriptions
merge all the presets from their ancestor YAML keys. The hierarchy indentation depth may
be as deep as needed to group your subscriptions for easy maintenance:
.. code-block:: yaml
:caption: subscriptions.yaml
:emphasize-lines: 3,7,12
Jellyfin TV Show by Date | Only Recent:
# Download the highest resolution available:
Max Video Quality:
"NOVA PBS": "https://www.youtube.com/@novapbs"
"National Geographic": "https://www.youtube.com/@NatGeo"
# Download the highest resolution available that is 720p or less:
Max 720p:
"Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"
Soundcloud Discography | Chunk Downloads:
# Only download audio using the Opus codec, not MP3 or other codecs:
Max Opus Quality:
"UKNOWY": "https://soundcloud.com/uknowymunich"
Genre and rating metadata
-------------------------
Presets may also support using arbitrary values from :ref:`YAML keys prefixed with '=
...' <guides/getting_started/index:subscriptions are grouped by indentation>`. The ``=
...`` prefix may be used at any indentation depth and may also be combined with presets
and other ``= ...`` values using the ``... | ...`` special character to best group your
subscriptions.
:ref:`By convention <config_reference/scripting/static_variables:subscription_indent_i>`
in the built-in library software and media type presets, the first ``= ...`` value
specifies the genre for all descendant subscriptions. For the ``TV Show ...`` presets,
the second ``= ...`` value specifies the rating for all descendant subscriptions:
.. code-block:: yaml
:caption: subscriptions.yaml
:emphasize-lines: 1,3
= Kids:
Jellyfin TV Show by Date | = TV-Y:
"Jake Trains": "https://www.youtube.com/@JakeTrains"
"Kids Toys Play": "https://www.youtube.com/@KidsToysPlayChannel"
Soundcloud Discography:
"Foo Kids Band": "https://soundcloud.com/foo-kids-band"
Override variables for one subscription
---------------------------------------
Most variable overrides aren't actually specific to just one subscription and should be
set in :doc:`your own custom presets <./first_config>`. But use :ref:`the override mode
'~...' prefix <config_reference/subscription_yaml:override mode>` when an override is
specific to only one subscription and will never be shared with another:
.. code-block:: yaml
:caption: subscriptions.yaml
:emphasize-lines: 2-
Jellyfin TV Show by Date:
"~NOVA PBS":
url: "https://www.youtube.com/@novapbs"
tv_show_directory: "/media/Unique/Series/Path"
Next Steps
----------
Once you've defined your subscriptions, it's time to :doc:`test the configuration and
try your first download <./first_download>`.

5
src/ytdl_sub/prebuilt_presets/helpers/filter_duration.yaml
View file

@ -1,9 +1,8 @@
presets:
#############################################################################
# Include Keywords
# Include or exclude media with any of the listed keywords in their titles
# Keywords will check a lower-cased title or description
# Filter Duration
# Include or exclude media based on its play time duration
Filter Duration:
overrides:
filter_duration_min_s: 0