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