adb08ed5f9
* 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).
167 lines
5.9 KiB
ReStructuredText
167 lines
5.9 KiB
ReStructuredText
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>`.
|