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

docs(start): How to configure subscriptions

Browse source 
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.
This commit is contained in:
Ross Patterson 2025-08-18 00:52:48 -07:00
parent 9307f672b1
commit d0fdb11ac4
No known key found for this signature in database
GPG key ID: 2EFF7CCE6828E359
6 changed files with 175 additions and 147 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 .. code-block:: yaml
__preset__: __preset__:
# Variables that override defaults from `overrides:` for presets in YAML keys:
overrides: overrides:
tv_show_directory: "/tv_shows" tv_show_directory: "/tv_shows"
# Directly set plugin options:
ytdl_options: ytdl_options:
cookiefile: "/config/cookie.txt" 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 .. code-block:: powershell
ytdl-sub.exe --config \path\to\config\config.yaml sub \path\to\config\subscriptions.yaml 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 Initial Download
================ ================
Once you have a ``subscriptions.yaml`` file created, you can perform your first Once you've created :doc:`a subscriptions file <./subscriptions>`, you can perform your
download. Access ``ytdl-sub``, navigate to the directory containing your first download. Access ``ytdl-sub``, navigate to the directory containing your
``subscriptions.yaml`` file. ``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 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 what subscriptions to download and place into your media library. Each subscription
selects which :doc:`presets <../../prebuilt_presets/index>` to apply. Those presets selects which :doc:`presets <../../prebuilt_presets/index>` to apply. Those presets
configure how each subscription is downloaded and placed in the media library. 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 '= ...' reality, the ancestor keys of subscriptions may also use :ref:`the special '= ...'
prefix to pass specific overrides prefix to pass specific overrides
<config_reference/scripting/static_variables:subscription_indent_i>` supported by the <config_reference/scripting/static_variables:subscription_indent_i>` supported by the
preset. By convention in the built-in presets, the first ``= ...`` value specifies the preset. By convention in the built-in software and media type presets, the first ``=
genre for all descendant subscriptions. ...`` value specifies the genre for all descendant subscriptions.
Finally, ancestor keys may use the ``... | ...`` special character to combine multiple Finally, ancestor keys may use :ref:`the '... | ...' special character
presets and/or genres for the descendant subscriptions beneath. <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 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. 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 With ``ytdl-sub`` installed and the above understood, the next step is to :doc:`start
recommended to go through the below sections in order to fully grasp ytdl-sub. adding subscriptions <./subscriptions>`.
.. toctree::
:maxdepth: 2
first_sub
first_download
automating_downloads
first_config
.. toctree:: .. toctree::
:hidden: :hidden:
subscriptions
first_download
automating_downloads
first_config
quick_start quick_start

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

@ -0,0 +1,149 @@
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: "/media/Library/Videos/Series"
music_directory: "/media/Library/Music"
music_video_directory: "/media/Library/Videos/Music"
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"
Next Steps
----------
Once you've defined your subscriptions, it's time to :doc:`test the configuration and
try your first download <./first_download>`.