danvics/ytdl-sub
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[DOCS] Rewrite getting started guide (#1129)

Browse source
This commit is contained in:
Jesse Bannon 2024-12-21 09:13:09 -08:00 committed by GitHub
parent ebe9908361
commit 07d810171d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 386 additions and 298 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/source/config_reference/index.rst
View file

@ -6,7 +6,7 @@ This section contains direct references to the code of ``ytdl-sub`` and informat
.. toctree::
config_yaml
subscriptions_yaml
subscription_yaml
plugins
scripting/index
prebuilt_presets/index

121
docs/source/config_reference/subscription_yaml.rst Normal file
View file

@ -0,0 +1,121 @@
==================
Subscription File
==================
A subscription file is designed to both define and organize many things
to download in condensed YAML.
.. hint::
Read the :ref:`getting started guide <guides/getting_started/index:Getting Started>`
first before reviewing this section.
File Preset
-----------
Many examples show ``__preset__`` at the top. This is known as the *subscription file preset*.
It is where a single :ref:`preset <guides/getting_started/first_config:Custom Preset Definition>`
can be defined that gets applied to each subscription within the file.
This is a good place to apply file-wide variables such as ``tv_show_directory`` or
supply a cookies file path.
.. code-block:: yaml
__preset__:
overrides:
tv_show_directory: "/tv_shows"
ytdl_options:
cookiefile: "/config/cookie.txt"
Layout
------
A subscription file is comprised of YAML keys and values. Keys can be either
- a preset
- an override value
- a subscription name
Take the following example:
.. code-block:: yaml
Jellyfin TV Show by Date:
= News:
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
"BBC News": "https://www.youtube.com/@BBCNews"
All three types of keys are used for the following:
- ``Jellyfin TV Show by Date`` - a prebuilt preset
- ``= News`` - an override value for genre
- ``Breaking News``, ``BBC News`` - The subscription names
The bottom-most keys, or leaf keys, should always be the subscription name.
It is good practice to put subscription names in quotes to differentiate
between preset names and subscription names.
Values should always be the subscription itself. The simplest form is
just the URL. Further sections will show more exotic examples that go beyond
a single URL.
Inheritance
-----------
A subscription inherits every key above it. In the above example,
both ``Breaking News`` and ``BBC News`` inherits the ``Jellyfin TV Show by Date``
preset and the ``= News`` override value.
.. note::
There are no limits or boundaries on how one structures
their presets. This flexibility is intended for subscription authors
to organize their downloads as they see fit.
Multi Keys
----------
Subscription keys support pipe syntax, or ``|``, which allows multiple
keys to be defined on a single line. The following is equivalent to the above
example:
.. code-block:: yaml
Jellyfin TV Show by Date | = News:
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
"BBC News": "https://www.youtube.com/@BBCNews"
Override Mode
-------------
Often times, it is convenient to set multiple override values for
a single subscription. We can put a preset in *override mode* by
using tilda syntax, or ``~``.
Suppose we want to apply the :ref:`Only Recent <prebuilt_presets/helpers:Only Recent>`
preset to the above examples. But for ``BBC News`` specifically, we want to
set the date range to be different than the default ``2months`` value to
``2weeks``.
We can change it as follows:
.. code-block:: yaml
Jellyfin TV Show by Date
= News | Only Recent:
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
"~BBC News":
url: "https://www.youtube.com/@BBCNews"
only_recent_date_range: "2weeks"
.. important::
When using override mode, we need to set the ``url``
variable since we are no longer using the simplified
*subscription_value*. For more info on how this works,
read about :ref:`subscription variables <config_reference/scripting/static_variables:Subscription Variables>`.
Map Mode
--------
Map mode is for highly advanced presets that benefit
from a more complex subscription definition. TODO: Show music video
example here.

114
docs/source/config_reference/subscriptions_yaml.rst
View file

@ -1,114 +0,0 @@
==================
Subscriptions File
==================
The ``subscriptions.yaml`` file is where we use :ref:`config_reference/config_yaml:presets`
to define a ``subscription``: something we want to recurrently download, such as a specific
channel or playlist.
The only difference between a ``subscription`` and ``preset`` is that the subscription
must have all required variables defined to perform a download.
Below is an example that downloads a YouTube playlist:
.. code-block:: yaml
:caption: config.yaml
presets:
playlist_preset_ex:
download: "{url}"
output_options:
output_directory: "{output_directory}/{playlist_name}"
file_name: "{playlist_name}.{title}.{ext}"
overrides:
output_directory: "/path/to/ytdl-sub-videos"
.. code-block:: yaml
:caption: subscription.yaml
my_subscription_name:
preset: "playlist_preset_ex"
overrides:
playlist_name: "diy-playlist"
url: "https://youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg"
Our preset ``playlist_preset_ex`` defines three
custom variables: ``{output_directory}``, ``{playlist_name}``, and ``{url}``. The subscription sets
the ``parent preset`` to ``playlist_preset_ex``, and must define the variables ``{playlist_name}``
and ``{url}`` since the preset did not.
Beautifying Subscriptions
-------------------------
Subscriptions support using presets as keys, and using keys to set override variables as values.
For example:
.. code-block:: yaml
:caption: subscription.yaml
TV Show Full Archive:
= News:
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
TV Show Only Recent:
= Tech | TV-Y:
"Two Minute Papers": "https://www.youtube.com/@TwoMinutePapers"
Will create two subscriptions named "Breaking News" and "Two Minute Papers", equivalent to:
.. code-block:: yaml
"Breaking News":
preset:
- "TV Show Full Archive"
overrides:
subscription_indent_1: "News"
subscription_name: "Breaking News"
subscription_value: "https://www.youtube.com/@SomeBreakingNews"
"Two Minute Papers":
preset:
- "TV Show Only Recent"
overrides:
subscription_indent_1: "Tech"
subscription_indent_2: "TV-Y"
subscription_name: "Two Minute Papers"
subscription_value: "https://www.youtube.com/@TwoMinutePapers"
You can provide as many parent presets in the form of ``keys``, and subscription indents as ``= keys``.
This can drastically simplify subscription definitions by setting things like so in your
parent preset:
.. code-block:: yaml
presets:
"TV Show Preset":
overrides:
subscription_indent_1: "default-genre"
subscription_indent_2: "default-content-rating"
tv_show_name: "{subscription_name}"
url: "{subscription_value}"
genre: "{subscription_indent_1}"
content_rating: "{subscription_indent_2}"
File Preset
-----------
You can apply a preset to all subscriptions in the ``subscription.yaml`` file
by using the file-wide ``__preset__``:
.. code-block:: yaml
:caption: subscription.yaml
__preset__:
preset: "playlist_preset_ex"
my_subscription_name:
overrides:
url: "https://youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg"
playlist_name: "diy-playlist"
This ``subscription.yaml`` is equivalent to the one above it because all
subscriptions automatically set ``__preset__`` as a ``parent preset``.

2
docs/source/deprecation_notices.rst
View file

@ -46,7 +46,7 @@ Oct 2023
subscription preset and value
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The use of ``__value__`` will go away in Dec 2023 in favor of the method found in
:ref:`config_reference/subscriptions_yaml:beautifying subscriptions`. ``__preset__`` will still be supported for the time being.
:ref:`config_reference/subscription_yaml:Subscription File`. ``__preset__`` will still be supported for the time being.
July 2023
---------

56
docs/source/guides/getting_started/advanced_configuration.rst
View file

@ -1,56 +0,0 @@
Advanced Configuration
======================
If the :doc:`prebuilt presets </prebuilt_presets/index>` aren't suitable for your needs, you may want to set up an advanced configuration.
Layout of a Config file
-----------------------
The layout of the ``config.yaml`` file is relatively straightforward:
.. code-block:: yaml
presets:
preset_name:
plugin1:
plugin1_option1: value1
This creates a preset named ``preset_name``, which contains the made-up
:doc:`plugin </config_reference/plugins>` ``plugin1``. Under each plugin are its settings.
A preset can contain multiple plugins.
Preset Inheritance
------------------
You can modularize your presets via preset inheritance. For example,
.. code-block:: yaml
presets:
TV Show:
preset:
- "Jellyfin TV Show by Date"
overrides:
tv_show_directory: "/ytdl_sub_tv_shows"
TV Show Only Recent:
preset:
- "TV Show"
- "Only Recent"
overrides:
only_recent_date_range: "3weeks"
This creates two presets:
* ``TV Show``
* Inherits the :doc:`prebuilt </prebuilt_presets/index>` ``Jellyfin TV Show by Date`` preset
* Sets the output tv show directory
* ``TV Show Only Recent``
* Inherits the ``TV Show`` preset made above it and the ``Only Recent`` prebuilt preset
* Sets only_recent preset to only keep the last 3 weeks worth of videos
Inheritance makes it easy to extend existing presets to include logic for your specific needs.

4
docs/source/guides/getting_started/automating_downloads.rst
View file

@ -1,7 +1,9 @@
Automating Downloads
====================
One of the key capabilities of ``ytdl-sub`` is how well it runs without user input, but to take advantage of this you must set up scheduling to execute the commands at some interval. How you set up this scheduling depends on which version of ``ytdl-sub`` you downloaded.
One of the key capabilities of ``ytdl-sub`` automating new downloads.
To take advantage of this, you must set up scheduling to execute the commands at some interval.
How you set up this scheduling depends on which version of ``ytdl-sub`` you downloaded.
:ref:`Guide for Docker and Unraid Containers <guides/getting_started/automating_downloads:docker and unraid>`

15
docs/source/guides/getting_started/examples.rst
View file

@ -1,15 +0,0 @@
=====================
Using Example Configs
=====================
Copy and paste the examples into local yaml files, modify the
``working_directory`` and ``output_directory`` with your desired paths,
and perform a dry-run using
.. code-block:: bash
ytdl-sub \
--dry-run \
--config path/to/config.yaml \
sub path/to/subscriptions.yaml
This will simulate what a download will look like.

190
docs/source/guides/getting_started/first_config.rst
View file

@ -1,33 +1,203 @@
Basic Configuration
===================
Your first configuration will look pretty simple:
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 common configuration:
.. code-block:: yaml
:linenos:
configuration:
working_directory: '.ytdl-sub-downloads'
working_directory: '/mnt/ssd/.ytdl-sub-downloads'
presets:
TV Show:
preset:
- "Jellyfin TV Show by Date"
- "Only Recent"
- "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"
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 <guides/getting_started/index:quick overview of \`\`ytdl-sub\`\`>`
Configuration Section
---------------------
The :ref:`configuration <config_reference/config_yaml:Configuration File>` 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 <config_reference/prebuilt_presets:Prebuilt Preset Reference>`
or other presets defined in your config.
2. `Plugin definitions <config_reference/plugins:Plugins>`
3. `overrides <config_reference/plugins: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 <config_reference/prebuilt_presets:Prebuilt Preset Reference>` 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 <config_reference/plugins:throttle_protection>` and
`embed_thumbnail <config_reference/plugins: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: 23
- 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.
All override variables reside underneath the `overrides <config_reference/plugins: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 <config_reference/prebuilt_presets/index:Prebuilt Preset Reference`
to see all available variables that are overridable.
Using Custom Presets in Subscriptions
--------------------------------------
Subscription files can use custom presets just like any other prebuilt preset.
Below shows a complete subscription file using the above two custom presets.
.. code-block:: yaml
TV Show:
= Documentaries:
"NOVA PBS": "https://www.youtube.com/@novapbs"
= Kids | = TV-Y:
"Jake Trains": "https://www.youtube.com/@JakeTrains"
TV Show Only Recent:
= News:
"BBC News": "https://www.youtube.com/@BBCNews"
Notice how we do not need to define ``tv_show_directory`` in the ``__preset__`` section
like in prior examples. This is because our custom presets do the work of defining it.
Reference Custom Config in the CLI
----------------------------------
Be sure to tell ytdl-sub to use your config by using the argument
``--config /path/to/config.yaml``.
If you run ytdl-sub in the same directory, and the config file is named ``config.yaml``, it will
use it by default.

50
docs/source/guides/getting_started/first_download.rst
View file

@ -1,32 +1,50 @@
Initial Download
================
Once you have a ``subscriptions.yaml`` file created and filled out, you can perform your first
Once you have a ``subscriptions.yaml`` file created, you can perform your first
download. Access ``ytdl-sub``, navigate to the directory containing your ``subscriptions.yaml``
file, then run the below command:
file.
.. tab-set::
Dry Run
-------
Performing a dry run is important when applying any change to your subscriptions to
ensure output looks as expected. Dry runs will pull metadata to *simulate* a download
without actually downloading the media file.
.. tab-item:: Dry run
.. code-block:: shell
A dry run lets you check that your configuration doesn't throw any errors and what the expected output files of actually doing the download are, without actually downloading the full media.
ytdl-sub --dry-run sub subscriptions.yaml
.. code-block:: shell
Faster Iteration Cycle
----------------------
Testing subscriptions can take quite some time to perform a full download.
This can be speed up by applying an override via command-line to set max number
of downloads.
ytdl-sub --dry-run sub
.. code-block:: shell
.. tab-item:: Normal run
ytdl-sub --dry-run sub subscriptions.yaml -o '--ytdl_options.max_downloads 3'
A normal run will download all files as determined by your ``presets`` and, once processing is finished, move the downloaded and processed files to your ``output_directory``.
Having many subscriptions could still make this dry run take a while. A subset of
subscriptions can be dry ran using a match.
.. code-block:: shell
.. code-block:: shell
:caption: Only run subscriptions that have PBS in their names
ytdl-sub sub
ytdl-sub --dry-run sub subscriptions.yaml -o '--ytdl_options.max_downloads 3' --match PBS
.. tab-item:: One-time download
Downloading
-----------
Once the subscriptions file is validated, a download can be performed by omitting the dry run argument.
Sometimes you may only want to download media once, in which case adding them to your ``subscriptions.yaml`` file is unneccessary. As an example, the below code will download the same videos as our subscription file:
.. code-block:: shell
.. code-block:: shell
ytdl-sub dl --preset "Jellyfin TV Show by Date" --overrides.subscription_name "NOVA PBS" --overrides.subscription_value "https://www.youtube.com/@novapbs" --overrides.tv_show_genre "Documentaries"
ytdl-sub sub subscriptions.yaml
Multiple subscription file names can be provided to perform a download on all of them. A single file
named ``subscriptions.yaml`` does not require a file name specification since it will
look for that file name by default, making the following command valid.
.. code-block:: shell
ytdl-sub sub

39
docs/source/guides/getting_started/first_sub.rst
View file

@ -1,7 +1,7 @@
Initial Subscription
====================
Your first subscription should look something like this:
Your first subscription file should look something like this:
.. code-block:: yaml
:linenos:
@ -31,7 +31,7 @@ Your first subscription should look something like this:
= Lofi:
"Game Chops": "https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i"
Lets break this down:
Let's break this down:
.. code-block:: yaml
:lineno-start: 1
@ -42,9 +42,18 @@ Lets break this down:
music_directory: "/music"
The first :ref:`__preset__ <config_reference/subscriptions_yaml:File Preset>` section is where we
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
@ -73,6 +82,8 @@ subscriptions to look like TV shows in the Jellyfin media player (can be changed
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
@ -82,17 +93,13 @@ subscriptions underneath it will *inherit* this preset.
= Documentaries:
Line 12 sets the key to ``= Documentaries``. When keys are prefixed with ``=``, it means we are
setting the
:ref:`subscription indent variable <config_reference/subscriptions_yaml:Beautifying Subscriptions>`.
For TV Show presets, the first subscription indent variable maps to the TV show's genre.
Setting subscription indent variables as a key implies all subscriptions underneath it will
have this variable set.
setting the genre. This value will get written to the respective metadata tags for both TV show
and music presets.
To better understand what variables are used in prebuilt presets, refer to the
:ref:`prebuilt preset reference <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>`.
Here you will see the underlying variables used in prebuilt presets that can be overwritten.
We already overwrote a few of the variables in the ``__preset__`` section above to define our
output directory.
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>`.
-------------------------------------
@ -104,8 +111,10 @@ output directory.
"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``. Referring to the
:ref:`TV show preset reference <config_reference/prebuilt_presets/tv_show:TV Show>`,
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.
-------------------------------------

91
docs/source/guides/getting_started/index.rst
View file

@ -1,25 +1,15 @@
Getting Started
===============
Now that you've completed your install of ``ytdl-sub``, it's time to get started. This is a 3-step process:
- Create your configuration file (if the :doc:`/prebuilt_presets/index` don't fit your needs)
- Create your subscription file
- Automate starting YTDL-Sub
Prerequisite Knowledge
----------------------
.. _navigate directories: https://en.wikipedia.org/wiki/Cd_(command)
.. _YAML syntax: https://yaml.org/spec/1.2.2/#chapter-2-language-overview
In order to use ``ytdl-sub`` in any of the forms listed in these docs, you will need some basic knowledge.
Be sure that you:
☑ Can `navigate directories`_ in a command line interface (or CLI)
☑ Can navigate directories in a command line interface (or CLI)
☑ Have a basic understanding of `YAML syntax`_
☑ Have a basic understanding of YAML syntax
If you plan on using the headless image of ``ytdl-sub``, you:
☑ Can use ``nano`` or ``vim`` to edit OR
@ -29,76 +19,39 @@ If you plan on using the headless image of ``ytdl-sub``, you:
Additional useful (but not required) knowledge:
☑ Understanding how :yt-dlp:`\ ` works
Overview
--------
``ytdl-sub`` uses two types of YAML files:
Terminology
-----------
subscriptions.yaml
~~~~~~~~~~~~~~~~~~
Defines ``subscriptions``, which specify the media we want to recurrently download, like YouTube
channels and playlists, SoundCloud artists, or any
:yt-dlp:`yt-dlp supported site <blob/master/supportedsites.md>`. ``subscriptions`` use ``presets``
to define how ``ytdl-sub`` should handle downloading, processing, and saving them.
Must-know terminology:
``ytdl-sub`` comes packaged with many
:ref:`prebuilt presets <prebuilt_presets/index:Prebuilt Presets>`
that will play nicely with well-known media players.
- ``subscription``: URL(s) that you want to download with specific metadata requirements.
- ``preset``: A media profile comprised of YAML configuration that can specify anything from metadata layout, media quality, or any feature of ytdl-sub, to apply to subscriptions. A preset can inherit other presets.
- ``prebuilt preset``: Presets that are included in ytdl-sub. These do most of the work defining plugins, overrides, etc in order to make downloads ready for player consumption.
- ``override``: Verb describing the act of overriding something in a preset. For example, the TV Show presets practically expect you to *override* the URL variable to tell ytdl-sub where to download from.
- ``override variables``: User-defined variables that are intended to *override* something.
- ``subscription file``: The file to specify all of your subscriptions and some override variables.
config.yaml
~~~~~~~~~~~
To customize ``ytdl-sub`` to beyond the prebuilt presets, you will need a ``config.yaml`` file. This
file is where custom ``presets`` can be defined to orchestrate ``ytdl-sub`` to your very specific needs.
Intermediate terminology:
Running ytdl-sub
~~~~~~~~~~~~~~~~
To invoke ``ytdl-sub`` to download subscriptions, use the following command:
- ``plugin``: Modular logic to apply to a subscription. To use a plugin, it must be defined in a preset.
- ``config file``: An optional file where you can define custom presets and other advanced configuration.
- ``yt-dlp``: The underlying application that handles downloading for ytdl-sub.
.. tab-set-code::
Advanced terminology:
.. code-block:: shell
ytdl-sub sub subscriptions.yaml
.. code-block:: powershell
ytdl-sub.exe sub subscriptions.yaml
``ytdl-sub`` initially downloads all files to a defined ``working_directory``. This is a temporary
storage spot for metadata and media files so that errors during processing- if they occur- don't
affect your existing media library. Once all file processing is complete, your media files are
moved to the ``output_directory``.
- ``entry variables``: Variables that derive from a downloaded yt-dlp entry (media).
- ``static variables``: Variables that do not have a dependency to entry variables.
- ``scripting``: Syntax that allows the use of entry variables, static variables, and functions in override variables.
Ready to Start?
---------------
Now that you have installed ``ytdl-sub``, checked your skills, and gotten a bit of background on how ``ytdl-sub`` functions, read through the articles below to get started:
:doc:`Step 1: Initial Subscriptions <first_sub>`
:doc:`Step 2: Your First Download <first_download>`
:doc:`Step 3: Automating Downloads <automating_downloads>`
Want to go a step further?
If you want to use atypical paths or specific configuration options, check out :doc:`Basic Configuration <first_config>`
For tips on creating your own presets when the prebuilt presets aren't cutting it, check out :doc:`Advanced Configuration <advanced_configuration>`
Other docs that may be of use:
:doc:`/prebuilt_presets/index`
:doc:`examples`
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.
.. toctree::
:hidden:
:caption: Getting Started Guide
:maxdepth: 1
:maxdepth: 2
first_sub
first_download
automating_downloads
first_config
advanced_configuration
examples