diff --git a/docs/source/guides/getting_started/first_sub.rst b/docs/source/guides/getting_started/first_sub.rst index 1043960ee..f13affbbd 100644 --- a/docs/source/guides/getting_started/first_sub.rst +++ b/docs/source/guides/getting_started/first_sub.rst @@ -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__ ` 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. + ------------------------------------- .. 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 `. -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. - -To better understand what variables are used in prebuilt presets, refer to the -:ref:`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. +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``. Read more about +subscription syntax :ref:`here `. ------------------------------------- @@ -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 `, +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. ------------------------------------- diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index 3aa856bc5..12f8a84c9 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -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,49 +19,38 @@ 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 `. ``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 ` -that will play nicely with well-known media players. +- ``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 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. +- ``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've completed your install of ``ytdl-sub``, it's time to get started. This is a 3-step process: + +- Create your subscription file +- Automate starting ytdl-sub +- (Optional) Create a custom configuration file if further customization is needed -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 `