From adb08ed5f912bcb9b7cd223f8634a94460a426c9 Mon Sep 17 00:00:00 2001 From: Ross Patterson Date: Thu, 28 Aug 2025 07:09:05 -0700 Subject: [PATCH] [DOCS] start: Clarify subscriptions file tutorial (#1310) * 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). --- .../config_reference/subscription_yaml.rst | 2 + .../getting_started/automating_downloads.rst | 8 + .../guides/getting_started/first_download.rst | 4 +- .../guides/getting_started/first_sub.rst | 128 -------------- docs/source/guides/getting_started/index.rst | 31 ++-- .../guides/getting_started/subscriptions.rst | 167 ++++++++++++++++++ .../helpers/filter_duration.yaml | 5 +- 7 files changed, 195 insertions(+), 150 deletions(-) delete mode 100644 docs/source/guides/getting_started/first_sub.rst create mode 100644 docs/source/guides/getting_started/subscriptions.rst diff --git a/docs/source/config_reference/subscription_yaml.rst b/docs/source/config_reference/subscription_yaml.rst index 16cf087c..298456f8 100644 --- a/docs/source/config_reference/subscription_yaml.rst +++ b/docs/source/config_reference/subscription_yaml.rst @@ -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" diff --git a/docs/source/guides/getting_started/automating_downloads.rst b/docs/source/guides/getting_started/automating_downloads.rst index 99394283..80e86902 100644 --- a/docs/source/guides/getting_started/automating_downloads.rst +++ b/docs/source/guides/getting_started/automating_downloads.rst @@ -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>`. diff --git a/docs/source/guides/getting_started/first_download.rst b/docs/source/guides/getting_started/first_download.rst index ef8ba426..43e31b05 100644 --- a/docs/source/guides/getting_started/first_download.rst +++ b/docs/source/guides/getting_started/first_download.rst @@ -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. diff --git a/docs/source/guides/getting_started/first_sub.rst b/docs/source/guides/getting_started/first_sub.rst deleted file mode 100644 index f88d9564..00000000 --- a/docs/source/guides/getting_started/first_sub.rst +++ /dev/null @@ -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__ ` section is -where we can set modifications that apply to every subscription in this file. - -This snippet specifically adds two :ref:`override ` -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 - ` 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 ` 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 -` and :ref:`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 -`, 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 -`, 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. diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index f325f862..9b12f9ee 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -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 ` 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 +` 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 diff --git a/docs/source/guides/getting_started/subscriptions.rst b/docs/source/guides/getting_started/subscriptions.rst new file mode 100644 index 00000000..48cf3778 --- /dev/null +++ b/docs/source/guides/getting_started/subscriptions.rst @@ -0,0 +1,167 @@ +Subscriptions +============= + +Once you understand :ref:`how ytdl-sub works +`, 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 +`: + +.. 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 +`. + + +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 +` 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 +` 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 +`. 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 '= +...' `. 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 ` +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 ` 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>`. diff --git a/src/ytdl_sub/prebuilt_presets/helpers/filter_duration.yaml b/src/ytdl_sub/prebuilt_presets/helpers/filter_duration.yaml index e763fff5..0f8b1651 100644 --- a/src/ytdl_sub/prebuilt_presets/helpers/filter_duration.yaml +++ b/src/ytdl_sub/prebuilt_presets/helpers/filter_duration.yaml @@ -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