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.
This commit is contained in:
Ross Patterson
parent
9307f672b1
commit
d0fdb11ac4
6 changed files with 175 additions and 147 deletions
|
|
@ -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"
|
||||
|
||||
|
|
|
|||
|
|
@ -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>`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
149
docs/source/guides/getting_started/subscriptions.rst
Normal file
149
docs/source/guides/getting_started/subscriptions.rst
Normal 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>`.
|
||||
Loading…
Reference in a new issue