diff --git a/docs/source/guides/getting_started/first_config.rst b/docs/source/guides/getting_started/first_config.rst index ce314ceb..f7a43a85 100644 --- a/docs/source/guides/getting_started/first_config.rst +++ b/docs/source/guides/getting_started/first_config.rst @@ -6,8 +6,9 @@ A configuration file serves two purposes: 1. Set advanced functionality that is not specifiable in a subscription file, such as working directory location. These are set underneath ``configuration``. 2. Create custom presets, which can drastically simplify your subscription file. These are defined underneath ``presets``. + Presets are intended to be applicable and reusable across multiple subscriptions. -Below is a basic configuration: +Below is a common configuration: .. code-block:: yaml :linenos: @@ -19,25 +20,184 @@ Below is a basic configuration: TV Show: preset: - "Jellyfin TV Show by Date" + - "Max 1080p" + embed_thumbnail: True + + throttle_protection: + sleep_per_download_s: + min: 2.2 + max: 10.8 + sleep_per_subscription_s: + min: 9.0 + max: 14.1 + max_downloads_per_subscription: + min: 10 + max: 36 overrides: tv_show_directory: "/ytdl_sub_tv_shows" TV Show Only Recent: preset: + - "TV Show" - "Only Recent" +Configuration Section +--------------------- -The first two lines in this ``config.yaml`` file are the ``configuration``, and define the ``working_directory``, which is described near the bottom of :ref:`this section ` +The :ref:`configuration ` section sets options for ytdl-sub execution. + +.. code-block:: yaml + :lineno-start: 1 + + configuration: + working_directory: '/mnt/ssd/.ytdl-sub-downloads' + +Preset Section +-------------- + +Underneath ``presets``, we define two custom presets with the names ``TV Show`` and ``TV Show Only Recent``. + +.. code-block:: yaml + + presets: + TV Show: + ... + TV Show Only Recent: + ... + +The indentation example above shows how to define multiple presets. + +Custom Preset Definition +------------------------ + +Before we break down the above ``TV Show`` preset, lets first outline a preset layout: + +.. code-block:: yaml + + Preset Name: + preset: + ... + + plugin(s): + ... + + overrides: + ... + +Presets can contain three important things: + +1. ``preset`` section, which can inherit `prebuilt presets ` + or other presets defined in your config. +2. `Plugin definitions ` +3. `overrides `, which can override inherited preset variables + +Presets do not have to define all of these, as we'll see in the ``TV Show Only Recent`` preset. + +Inheriting Presets +~~~~~~~~~~~~~~~~~~ + +.. code-block:: yaml + :lineno-start: 5 + + TV Show: + preset: + - "Jellyfin TV Show by Date" + - "Max 1080p" + +The following snippet shows that the ``TV Show`` preset will inherit all properties +of the prebuilt presets ``Jellyfin TV Show by Date`` and ``Max 1080p`` in that order. + +Order matters for preset inheritance. Bottom-most presets will override ones above them. + +It is highly advisable to use `prebuilt presets ` as +a starting point for custom preset building, as they do the work of preset building to ensure things show as expected +in their respective media players. Read on to see how to override prebuilt preset specifics such as title. + +Defining Plugins +~~~~~~~~~~~~~~~~ + +.. code-block:: yaml + :lineno-start: 10 + + embed_thumbnail: True + + throttle_protection: + sleep_per_download_s: + min: 2.2 + max: 10.8 + sleep_per_subscription_s: + min: 9.0 + max: 14.1 + max_downloads_per_subscription: + min: 10 + max: 36 + +Our ``TV Show`` sets two plugins, `throttle_protection ` and +`embed_thumbnail `. Each plugin's documentation shows the respective +fields that they support. + +If an inherited preset defines the same plugin, the custom preset will use 'merge-and-append' strategy to +combine their definitions. What this means is: + +1. If the field is a map (i.e. has sub-params like ``sleep_per_download_s`` above) or array, it will try to merge them +2. If both the inherited preset and custom preset set the same exact field and value (i.e. ``embed_thumbnail``) + the custom preset will overwrite it -Line 4 begins the definition of your custom ``presets``, with line 5 being the name of your first custom ``preset``. +Setting Override Variables +~~~~~~~~~~~~~~~~~~~~~~~~~~ -Lines 7 and 8 tell ``ytdl-sub`` which :doc:`/prebuilt_presets/index` to expand on; these ``presets`` already indicate that the downloaded files should be: +.. code-block:: yaml + :lineno-start: 20 -- in a format usable by, and with metadata accessible to, Jellyfin -- sorted by upload date, and -- only uploaded in the last 2 months (and will also delete any files in the media library which were uploaded over 2 months ago) + overrides: + tv_show_directory: "/ytdl_sub_tv_shows" -Line 11 is an override variable, ``tv_show_directory``, that tells ``ytdl-sub`` where to save your downloaded files once they've been processed, also known as the ``output_directory``. In this case, the downloaded files will be saved to the ``youtube`` folder in the root ``tv_shows`` directory. \ No newline at end of file +All override variables reside underneath the `overrides ` section. + +It is important to remember that individual subscriptions can override specific override variables. +When defining variables in a preset, it is best practice to define them with the intention that + +1. All subscriptions will use its value them +2. Use them as placeholders to perform other logic, then have subscriptions or child presets + define their specific value + +For simplicity, we'll focus on (1) for now. The above snippet sets the ``tv_show_directory`` +variable to a file path. This variable name is specific to the prebuilt TV show presets. + +See the `prebuilt preset reference