[DOCS] Rewrite getting started
This commit is contained in:
Jesse Bannon
parent
0f542ac4e5
commit
b979f3c3cb
2 changed files with 35 additions and 54 deletions
|
|
@ -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:
|
||||
|
|
@ -45,6 +45,9 @@ Lets break this down:
|
|||
The first :ref:`__preset__ <config_reference/subscriptions_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.
|
||||
|
||||
-------------------------------------
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -73,6 +76,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 +87,11 @@ 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``. Read more about
|
||||
subscription syntax :ref:`here <config_reference/subscriptions_yaml:Subscriptions File>`.
|
||||
|
||||
-------------------------------------
|
||||
|
||||
|
|
@ -104,8 +103,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.
|
||||
|
||||
-------------------------------------
|
||||
|
|
|
|||
|
|
@ -3,23 +3,20 @@ 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
|
||||
- Automate starting ytdl-sub
|
||||
- (Optional) Create a custom configuration file if further customization is needed
|
||||
|
||||
|
||||
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
|
||||
|
|
@ -31,48 +28,31 @@ Additional useful (but not required) knowledge:
|
|||
|
||||
Overview
|
||||
--------
|
||||
``ytdl-sub`` uses two types of YAML files:
|
||||
|
||||
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.
|
||||
|
||||
``ytdl-sub`` comes packaged with many
|
||||
:ref:`prebuilt presets <prebuilt_presets/index:Prebuilt Presets>`
|
||||
that will play nicely with well-known media players.
|
||||
|
||||
config.yaml
|
||||
Terminology
|
||||
~~~~~~~~~~~
|
||||
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.
|
||||
|
||||
Running ytdl-sub
|
||||
~~~~~~~~~~~~~~~~
|
||||
To invoke ``ytdl-sub`` to download subscriptions, use the following command:
|
||||
Must-know terminology:
|
||||
- ``subscription``: URL(s) that you want to download with specific metadata requirements.
|
||||
- ``preset``: Reusable 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 parent 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 a preset will use in its definition.
|
||||
- ``subscription file``: The file to specify all of your subscriptions and some override variables.
|
||||
|
||||
.. tab-set-code::
|
||||
Intermediate terminology:
|
||||
- ``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.
|
||||
|
||||
.. 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``.
|
||||
Advanced terminology:
|
||||
- ``entry variables``: Variables that derive from a downloaded yt-dlp entry.
|
||||
- ``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>`
|
||||
|
|
|
|||
Loading…
Reference in a new issue