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

[DOCS] Consistent headings, newlines, wraps (#1293)

Browse source 
I've been running into variations in style in the docs I've edited so far. I've been
including changes for consistency in with other commits but in many cases that makes one
part of one doc more consistent with the rest but less consistent with itself. It seems
like a bit of cleanup may be in order.

This change applies the following conventions:

- Section heading heirarchy:
  #. ``=`` with overline for document title, IOW first heading
  #. ``-``
  #. ``~``
  #. ``"``

- Two newlines before ``-`` sections for readability

- A newline between every section of any level and the first line of text

- Wrap paragraph lines at 88 characters to match Python's Black

I've only applied these changes to those ``*.rst`` files that aren't generated.

In the future, I might suggest another bulk change to match [the Sphinx conventions for
section
headings](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections).
This commit is contained in:
Ross Patterson 2025-08-20 20:20:19 -07:00 committed by GitHub
parent e980f60519
commit 60ff645750
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
30 changed files with 586 additions and 392 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
docs/source/config_reference/config_yaml.rst
View file

@ -1,7 +1,8 @@
================== ==================
Configuration File Configuration File
================== ==================
-----------
config.yaml config.yaml
----------- -----------
@ -14,17 +15,19 @@ The ``config.yaml`` is made up of two sections:
configuration: configuration:
presets: presets:
You can jump to any section and subsection of the config using the navigation You can jump to any section and subsection of the config using the navigation section to
section to the left. the left.
Note for Windows users, paths can be represented with ``C:/forward/slashes/like/linux``. Note for Windows users, paths can be represented with ``C:/forward/slashes/like/linux``.
If you wish to represent paths like Windows, you will need to ``C:\\double\\bashslash\\paths`` If you wish to represent paths like Windows, you will need to
in order to escape the backslash character. ``C:\\double\\bashslash\\paths`` in order to escape the backslash character.
configuration configuration
~~~~~~~~~~~~~ -------------
The ``configuration`` section contains app-wide configs applied to all presets
and subscriptions. The ``configuration`` section contains app-wide configs applied to all presets and
subscriptions.
.. autoclass:: ytdl_sub.config.config_validator.ConfigOptions() .. autoclass:: ytdl_sub.config.config_validator.ConfigOptions()
:members: :members:
@ -32,9 +35,10 @@ and subscriptions.
:exclude-members: subscription_value, persist_logs, experimental :exclude-members: subscription_value, persist_logs, experimental
persist_logs persist_logs
"""""""""""" ~~~~~~~~~~~~
Within ``configuration``, define whether logs from subscription downloads
should be persisted. Within ``configuration``, define whether logs from subscription downloads should be
persisted.
.. code-block:: yaml .. code-block:: yaml
@ -49,14 +53,17 @@ Log files are stored as
:members: :members:
:member-order: bysource :member-order: bysource
presets presets
~~~~~~~ -------
``presets`` define a `formula` for how to format downloaded media and metadata. ``presets`` define a `formula` for how to format downloaded media and metadata.
This section is work-in-progress! This section is work-in-progress!
preset preset
"""""" ~~~~~~
Presets support inheritance by defining a parent preset: Presets support inheritance by defining a parent preset:
.. code-block:: yaml .. code-block:: yaml

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

@ -2,7 +2,8 @@
Reference Reference
========= =========
This section contains direct references to the code of ``ytdl-sub`` and information on how it functions. This section contains direct references to the code of ``ytdl-sub`` and information on
how it functions.
Terminology Terminology

16
docs/source/config_reference/prebuilt_presets/common.rst
View file

@ -4,22 +4,30 @@ Common
.. highlight:: yaml .. highlight:: yaml
Filter Keywords Filter Keywords
--------------- ---------------
.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/filter_keywords.yaml .. literalinclude::
/../../src/ytdl_sub/prebuilt_presets/helpers/filter_keywords.yaml
Filter Duration Filter Duration
--------------- ---------------
.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/filter_duration.yaml .. literalinclude::
/../../src/ytdl_sub/prebuilt_presets/helpers/filter_duration.yaml
Media Quality Media Quality
------------- -------------
.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/media_quality.yaml .. literalinclude::
/../../src/ytdl_sub/prebuilt_presets/helpers/media_quality.yaml
Only Recent Videos Only Recent Videos
------------------ ------------------
.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml .. literalinclude::
/../../src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml

5
docs/source/config_reference/prebuilt_presets/index.rst
View file

@ -2,9 +2,8 @@
Prebuilt Preset Reference Prebuilt Preset Reference
========================= =========================
This section contains the code for the prebuilt presets. If you just want to understand how to use the presets, check :doc:`this section instead</prebuilt_presets/index>`. This section contains the code for the prebuilt presets. If you just want to understand
how to use the presets, check :doc:`this section instead</prebuilt_presets/index>`.
.. toctree:: .. toctree::
common common

3
docs/source/config_reference/prebuilt_presets/music.rst
View file

@ -6,4 +6,5 @@ All audio music based presets inherit from ``_music_base``.
.. highlight:: yaml .. highlight:: yaml
.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/music/singles.yaml .. literalinclude::
/../../src/ytdl_sub/prebuilt_presets/music/singles.yaml

3
docs/source/config_reference/prebuilt_presets/tv_show.rst
View file

@ -6,4 +6,5 @@ All TV show based presets inherit from ``_episode_base``.
.. highlight:: yaml .. highlight:: yaml
.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/tv_show/episode.yaml .. literalinclude::
/../../src/ytdl_sub/prebuilt_presets/tv_show/episode.yaml

82
docs/source/config_reference/scripting/index.rst
View file

@ -2,8 +2,9 @@
Scripting Scripting
========= =========
``ytdl-sub`` fields (file-names, tags, etc) are defined using variables and scripts. The links below ``ytdl-sub`` fields (file-names, tags, etc) are defined using variables and scripts. The
contain reference documentation for each built-in variable and scripting function. links below contain reference documentation for each built-in variable and scripting
function.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
@ -13,6 +14,7 @@ contain reference documentation for each built-in variable and scripting functio
scripting_functions scripting_functions
scripting_types scripting_types
How it Works How it Works
------------ ------------
@ -44,22 +46,22 @@ We can use this instead of hard-coding it above:
output_directory: "/path/to/tv_shows/{subscription_name}" output_directory: "/path/to/tv_shows/{subscription_name}"
The syntax for variable usage is curly-braces with the variable name within it. Assuming The syntax for variable usage is curly-braces with the variable name within it. Assuming
our subscription is actually named "Custom YTDL-SUB TV Show", then ``ytdl-sub`` our subscription is actually named "Custom YTDL-SUB TV Show", then ``ytdl-sub`` will
will actually write to that directory. actually write to that directory.
Entry Variables Entry Variables
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
For context, an *entry* is a video or audio file downloaded from ``yt-dlp``. For context, an *entry* is a video or audio file downloaded from ``yt-dlp``. *Entry
*Entry variables* are variables that are derived from an entry's ``info.json`` file. This file variables* are variables that are derived from an entry's ``info.json`` file. This file
comes from ``yt-dlp`` and contains every piece of metadata that it scraped. comes from ``yt-dlp`` and contains every piece of metadata that it scraped.
These variables are not considered static since they change per entry download. There are a These variables are not considered static since they change per entry download. There
few fields in ``ytdl-sub`` (i.e. ``output_directory``) that must be static. For others, are a few fields in ``ytdl-sub`` (i.e. ``output_directory``) that must be static. For
we are free to use values that derive from an entry. others, we are free to use values that derive from an entry.
Suppose we want to customize the name of an entry's output file and thumbnail to include its Suppose we want to customize the name of an entry's output file and thumbnail to include
title in its name. We can do that using entry variables: its title in its name. We can do that using entry variables:
.. code-block:: yaml .. code-block:: yaml
@ -74,8 +76,8 @@ Creating Custom Variables
Suppose we want to include the date in our file names. This means we'd need to update Suppose we want to include the date in our file names. This means we'd need to update
both the ``file_name`` and ``thumbnail_name`` fields to include it. both the ``file_name`` and ``thumbnail_name`` fields to include it.
Instead, we can create a custom *override variable*. This is ``ytdl-sub``'s method Instead, we can create a custom *override variable*. This is ``ytdl-sub``'s method for
for creating and overriding custom variables. creating and overriding custom variables.
These are created in the ``overrides`` section. Let's take our above example and create These are created in the ``overrides`` section. Let's take our above example and create
a ``custom_file_name`` variable to use for the entry file and thumbnail fields: a ``custom_file_name`` variable to use for the entry file and thumbnail fields:
@ -97,9 +99,9 @@ For experienced ``yt-dlp`` scrapers, you may be thinking:
- What if the title has characters that do not play nice with my operating system? - What if the title has characters that do not play nice with my operating system?
``ytdl-sub`` is able to *sanitize* any variable, meaning it replaces any problematic characters ``ytdl-sub`` is able to *sanitize* any variable, meaning it replaces any problematic
with safe alternatives that can be used in file names. We can ensure our file names and directories characters with safe alternatives that can be used in file names. We can ensure our file
are safe by using: names and directories are safe by using:
.. code-block:: yaml .. code-block:: yaml
@ -116,16 +118,16 @@ Simply add a ``_sanitized`` suffix to any variable name to make it sanitized.
.. note:: .. note::
Make sure you do not sanitize custom variables that intentionally create directories, Make sure you do not sanitize custom variables that intentionally create directories,
(i.e. sanitizing ``/path/to/tv_shows/``) otherwise they will... be sanitized and not resolve to (i.e. sanitizing ``/path/to/tv_shows/``) otherwise they will... be sanitized and not
directories! resolve to directories!
Using Scripting Functions Using Scripting Functions
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
Let's suppose you are an avid command-line user, and like all of your file names to be Let's suppose you are an avid command-line user, and like all of your file names to be
``snake_cased_with_no_spaces``. We can use the ``snake_cased_with_no_spaces``. We can use the `replace
`replace <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#replace>`_ <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#replace>`_
*scripting function* to create and use a snake-cased title. *scripting function* to create and use a snake-cased title.
.. code-block:: yaml .. code-block:: yaml
@ -143,42 +145,48 @@ Let's suppose you are an avid command-line user, and like all of your file names
custom_file_name: "{upload_date_standardized}_{snake_cased_title_sanitized}" custom_file_name: "{upload_date_standardized}_{snake_cased_title_sanitized}"
Scripting functions are similar to variables - they must be used within curly-braces. Scripting functions are similar to variables - they must be used within curly-braces.
It is good practice to use ``>-`` when defining variables that use functions. It is YAML's way of It is good practice to use ``>-`` when defining variables that use functions. It is
saying: YAML's way of saying:
- Allow a string to be multi-lined, and do not include newlines before or after it. - Allow a string to be multi-lined, and do not include newlines before or after it.
See for yourself `here <https://yaml-online-parser.appspot.com/?yaml=output_options%3A%0A%20%20output_directory%3A%20%22%7Bsubscription_name_sanitized%7D%22%0A%20%20file_name%3A%20%22%7Bcustom_file_name%7D.%7Bext%7D%22%0A%20%20thumbnail_name%3A%20%22%7Bcustom_file_name%7D.%7Bthumbnail_ext%7D%22%0A%0Aoverrides%3A%0A%20%20snake_cased_title%3A%20%3E-%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%25replace%28%20title%2C%20%27%20%27%2C%20%27_%27%20%29%0A%20%20%20%20%7D%0A%20%20custom_file_name%3A%20%22%7Bupload_date_standardized%7D%20%7Bsnake_cased_title_sanitized%7D%22&type=json>`_. See for yourself `here
Any whitespace within curly-braces is okay since it will be parsed out. This is needed to make <https://yaml-online-parser.appspot.com/?yaml=output_options%3A%0A%20%20output_directory%3A%20%22%7Bsubscription_name_sanitized%7D%22%0A%20%20file_name%3A%20%22%7Bcustom_file_name%7D.%7Bext%7D%22%0A%20%20thumbnail_name%3A%20%22%7Bcustom_file_name%7D.%7Bthumbnail_ext%7D%22%0A%0Aoverrides%3A%0A%20%20snake_cased_title%3A%20%3E-%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%25replace%28%20title%2C%20%27%20%27%2C%20%27_%27%20%29%0A%20%20%20%20%7D%0A%20%20custom_file_name%3A%20%22%7Bupload_date_standardized%7D%20%7Bsnake_cased_title_sanitized%7D%22&type=json>`_.
scripting function usage readable. Any whitespace within curly-braces is okay since it will be parsed out. This is needed
to make scripting function usage readable.
.. important:: .. important::
It is important to use ``>-`` over other YAML new-line directives like ``>`` because they It is important to use ``>-`` over other YAML new-line directives like ``>`` because
add newlines before or after curly-braces, and will be included in your variable's output string. they add newlines before or after curly-braces, and will be included in your
variable's output string.
Advanced Scripting Advanced Scripting
------------------ ------------------
Accessing ``info.json`` Fields Accessing ``info.json`` Fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The entirety of an entry's ``info.json`` file resides in the
`Map <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_types.html#map>`_
variable
`entry_metadata <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/entry_variables.html#entry-metadata>`_.
Any field can be accessed by using the The entirety of an entry's ``info.json`` file resides in the `Map
`map_get <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#map-get>`_ <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_types.html#map>`_
variable `entry_metadata
<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/entry_variables.html#entry-metadata>`_.
Any field can be accessed by using the `map_get
<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#map-get>`_
function like so: function like so:
.. code-block:: yaml .. code-block:: yaml
:caption: Fetches the 'artist' value from the .info.json, returns null if it does not exist. :caption:
Fetches the 'artist' value from the .info.json, returns null if it does not exist.
artist: >- artist: >-
{ %map_get( entry_metadata, "artist", null ) } { %map_get( entry_metadata, "artist", null ) }
Creating Custom Functions Creating Custom Functions
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
Custom functions can be created in the overrides section using the following syntax: Custom functions can be created in the overrides section using the following syntax:
.. code-block:: yaml .. code-block:: yaml
@ -187,9 +195,9 @@ Custom functions can be created in the overrides section using the following syn
"%get_entry_metadata_field": >- "%get_entry_metadata_field": >-
{ %map_get( entry_metadata, $0, null ) } { %map_get( entry_metadata, $0, null ) }
Custom function definitions must have ``%`` as a prefix to the function name, be surrounded by Custom function definitions must have ``%`` as a prefix to the function name, be
quotes to make YAML parsing happy, and can support arguments using ``$0``, ``$1``, ... to indicate surrounded by quotes to make YAML parsing happy, and can support arguments using ``$0``,
their first argument, second argument, etc. ``$1``, ... to indicate their first argument, second argument, etc.
Using our new custom function, we can simply the ``artist`` variable definition above to: Using our new custom function, we can simply the ``artist`` variable definition above to:

78
docs/source/config_reference/scripting/scripting_types.rst
View file

@ -1,7 +1,8 @@
===============
Scripting Types Scripting Types
=============== ===============
Types Types
----- -----
@ -16,8 +17,9 @@ Strings are a series of characters surrounded by quotes.
.. note:: .. note::
For non-String types, they must be defined as parameters to scripting functions. This is because For non-String types, they must be defined as parameters to scripting functions. This
anything in a variable definition that is not within curly-braces gets evaluated as a String. is because anything in a variable definition that is not within curly-braces gets
evaluated as a String.
We can define Strings within curly-braces by setting them as parameters to a function: We can define Strings within curly-braces by setting them as parameters to a function:
@ -65,8 +67,8 @@ There are a few ways to make variables that use curly braces more compact, inclu
string_variable: "{ %string('This is a String variable') }" string_variable: "{ %string('This is a String variable') }"
In the case that you want to define a string variable that contains both single and double quotes, In the case that you want to define a string variable that contains both single and
triple-quotes can be used to avoid *closing* the String. double quotes, triple-quotes can be used to avoid *closing* the String.
.. tab-set:: .. tab-set::
@ -88,7 +90,8 @@ triple-quotes can be used to avoid *closing* the String.
%string("""This has both " and ' in it.""") %string("""This has both " and ' in it.""")
} }
If you want a plain string that contains literal curly braces, you can escape them like so: If you want a plain string that contains literal curly braces, you can escape them like
so:
.. code-block:: yaml .. code-block:: yaml
@ -185,8 +188,8 @@ A type is considered boolean if it spells out ``True`` or ``False``, case-insens
Array Array
~~~~~ ~~~~~
An Array contains multiple types of any kind, including nested Arrays and Maps. An Array contains multiple types of any kind, including nested Arrays and Maps. Arrays
Arrays are defined using brackets (``[ ]``), and are accessed using zero-based indexing. are defined using brackets (``[ ]``), and are accessed using zero-based indexing.
.. tab-set:: .. tab-set::
@ -227,8 +230,8 @@ Arrays are defined using brackets (``[ ]``), and are accessed using zero-based i
Map Map
~~~ ~~~
A Map is a key-value store, containing mappings between keys and values. A Map is a key-value store, containing mappings between keys and values. Maps are
Maps are defined using curly-braces (``{ }``), and are accessed using their keys. defined using curly-braces (``{ }``), and are accessed using their keys.
.. tab-set:: .. tab-set::
@ -267,6 +270,7 @@ Maps are defined using curly-braces (``{ }``), and are accessed using their keys
Null Null
~~~~ ~~~~
Null is represented by an empty String, and can be conveyed by spelling out ``null``, Null is represented by an empty String, and can be conveyed by spelling out ``null``,
case-insensitive. case-insensitive.
@ -297,7 +301,9 @@ Function Type-Hints
AnyArgument AnyArgument
~~~~~~~~~~~ ~~~~~~~~~~~
AnyArgument means any of the above Types are valid as input or output to a scripting function.
AnyArgument means any of the above Types are valid as input or output to a scripting
function.
.. note:: .. note::
@ -306,13 +312,15 @@ AnyArgument means any of the above Types are valid as input or output to a scrip
Numeric Numeric
~~~~~~~ ~~~~~~~
Numeric refers to either an Integer or Float. Numeric refers to either an Integer or Float.
Optional Optional
~~~~~~~~ ~~~~~~~~
Optional means a particular scripting function argument can be either provided or not included.
For example, the function Optional means a particular scripting function argument can be either provided or not
`map_get <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#map-get>`_ included. For example, the function `map_get
<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#map-get>`_
has an optional default value. Both of these usages are valid: has an optional default value. Both of these usages are valid:
.. tab-set:: .. tab-set::
@ -331,8 +339,9 @@ has an optional default value. Both of these usages are valid:
Lambda Lambda
~~~~~~ ~~~~~~
Lambda parameters are a reference to a function, and will call that lambda function
on the input. In this example, Lambda parameters are a reference to a function, and will call that lambda function on
the input. In this example,
.. code-block:: yaml .. code-block:: yaml
@ -341,20 +350,23 @@ on the input. In this example,
%array_apply( [ 1, 2, 3, 4], %string ) %array_apply( [ 1, 2, 3, 4], %string )
} }
We apply ``%string`` as a lambda function to We apply ``%string`` as a lambda function to `array_apply
`array_apply <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-apply>`_, <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-apply>`_,
which is called on every element in the input array. The output becomes ``["1", "2", "3", "4"]``. which is called on every element in the input array. The output becomes ``["1", "2",
"3", "4"]``.
This example has one input-argument being passed into the lambda. For other lambda-based functions This example has one input-argument being passed into the lambda. For other lambda-based
like `array_enumerate <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-enumerate>`_, functions like `array_enumerate
<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-enumerate>`_,
it expects the lambda function to have two input arguments. These are denoted using it expects the lambda function to have two input arguments. These are denoted using
``LambdaTwo``, ``LambdaThree``, etc within the function spec. ``LambdaTwo``, ``LambdaThree``, etc within the function spec.
LambdaReduce LambdaReduce
~~~~~~~~~~~~ ~~~~~~~~~~~~
LambdaReduce parameters are a reference to a function that will perform a *reduce* - an operation
that reduces an Array to a single value by calling the LambdaReduce function repeatedly on two LambdaReduce parameters are a reference to a function that will perform a *reduce* - an
elements in the Array until it is reduced to a single value. operation that reduces an Array to a single value by calling the LambdaReduce function
repeatedly on two elements in the Array until it is reduced to a single value.
In this example, In this example,
@ -365,11 +377,12 @@ In this example,
%array_reduce( [ 1, 2, 3, 4], %add ) %array_reduce( [ 1, 2, 3, 4], %add )
} }
We call We call `array_reduce
`array_reduce <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-reduce>`_ <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-reduce>`_
on the input array, using on the input array, using `add
`add <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#add>`_ <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#add>`_
as the LambdaReduce function. This will reduce the Array to a single value by internally calling as the LambdaReduce function. This will reduce the Array to a single value by internally
calling
- *reduce-call 1*: ``%add(1, 2) = 3`` (first two elements) - *reduce-call 1*: ``%add(1, 2) = 3`` (first two elements)
- *reduce-call 2*: ``%add(3, 3) = 6`` (output from first two and third element) - *reduce-call 2*: ``%add(3, 3) = 6`` (output from first two and third element)
@ -380,9 +393,10 @@ And evaluate to ``10``.
ReturnableArguments ReturnableArguments
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
Returnable arguments are used in conditional functions like Returnable arguments are used in conditional functions like `if
`if <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#if>`_, <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#if>`_,
which implies the argument passed into the function is the function's output. For example, which implies the argument passed into the function is the function's output. For
example,
.. code-block:: yaml .. code-block:: yaml

73
docs/source/config_reference/subscription_yaml.rst
View file

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

20
docs/source/deprecation_notices.rst
View file

@ -1,14 +1,16 @@
Deprecation Notices Deprecation Notices
=================== ===================
Sep 2024 Sep 2024
-------- --------
regex plugin regex plugin
~~~~~~~~~~~~ ~~~~~~~~~~~~
Regex plugin has been removed in favor of scripting. The function Regex plugin has been removed in favor of scripting. The function
:ref:`config_reference/scripting/scripting_functions:regex_capture_many` :ref:`config_reference/scripting/scripting_functions:regex_capture_many` has been
has been created to replicate the plugin's behavior. See the following converted example: created to replicate the plugin's behavior. See the following converted example:
.. code-block:: yaml .. code-block:: yaml
:caption: regex plugin :caption: regex plugin
@ -40,13 +42,16 @@ has been created to replicate the plugin's behavior. See the following converted
} }
track_title: "{%array_at(captured_track_title, 1)}" track_title: "{%array_at(captured_track_title, 1)}"
Oct 2023 Oct 2023
-------- --------
subscription preset and value subscription preset and value
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The use of ``__value__`` will go away in Dec 2023 in favor of the method found in The use of ``__value__`` will go away in Dec 2023 in favor of the method found in
:ref:`config_reference/subscription_yaml:Subscription File`. ``__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 July 2023
--------- ---------
@ -54,8 +59,9 @@ July 2023
music_tags music_tags
~~~~~~~~~~ ~~~~~~~~~~
Music tags are getting simplified. ``tags`` will now reside directly under music_tags, and Music tags are getting simplified. ``tags`` will now reside directly under music_tags,
``embed_thumbnail`` is getting moved to its own plugin (supports video files as well). Convert from: and ``embed_thumbnail`` is getting moved to its own plugin (supports video files as
well). Convert from:
.. code-block:: yaml .. code-block:: yaml
@ -79,8 +85,8 @@ The old format will be removed in October 2023.
video_tags video_tags
~~~~~~~~~~ ~~~~~~~~~~
Video tags are getting simplified as well. ``tags`` will now reside directly under video_tags. Video tags are getting simplified as well. ``tags`` will now reside directly under
Convert from: video_tags. Convert from:
.. code-block:: yaml .. code-block:: yaml

96
docs/source/faq/index.rst
View file

@ -2,20 +2,23 @@
FAQ FAQ
=== ===
Since ytdl-sub is relatively new to the public, there has not been many question asked yet. We will update this as more questions get asked. Since ytdl-sub is relatively new to the public, there has not been many question asked
yet. We will update this as more questions get asked.
.. contents:: Frequently Asked Questions .. contents:: Frequently Asked Questions
:depth: 3 :depth: 3
How do I... How do I...
----------- -----------
...remove the date in the video title? ...remove the date in the video title?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :ref:`config_reference/prebuilt_presets/tv_show:TV Show` presets by default include the upload date in the ``episode_title`` The :ref:`config_reference/prebuilt_presets/tv_show:TV Show` presets by default include
override variable. This variable is used to set the title in things like the video metadata, NFO file, etc, which is the upload date in the ``episode_title`` override variable. This variable is used to set
subsequently read by media players. This can be overwritten as you see fit by redefining it: the title in things like the video metadata, NFO file, etc, which is subsequently read
by media players. This can be overwritten as you see fit by redefining it:
.. code-block:: yaml .. code-block:: yaml
@ -31,16 +34,24 @@ If you need support, you can:
* `Join our Discord <https://discord.gg/v8j9RAHb4k>`_ * `Join our Discord <https://discord.gg/v8j9RAHb4k>`_
If you would like to contribute, we're happy to accept any help, even non-coders! To find out how you can help this project, you can: If you would like to contribute, we're happy to accept any help, even non-coders! To
find out how you can help this project, you can:
* `Join our Discord <https://discord.gg/v8j9RAHb4k>`_ and leave a comment in #development with where you think you can assist or what skills you would like to contribute. * `Join our Discord <https://discord.gg/v8j9RAHb4k>`_ and leave a comment in
#development with where you think you can assist or what skills you would like to
contribute.
* If you just want to fix one thing, you're welcome to :ytdl-sub-gh:`submit a pull request <compare>` with information on what issue you're resolving and it will be reviewed as soon as possible. * If you just want to fix one thing, you're welcome to :ytdl-sub-gh:`submit a pull
request <compare>` with information on what issue you're resolving and it will be
reviewed as soon as possible.
...download age-restricted YouTube videos? ...download age-restricted YouTube videos?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See `yt-dl's recommended way <https://github.com/ytdl-org/youtube-dl#how-do-i-pass-cookies-to-youtube-dl>`_ to download your YouTube cookie, then add it to your :ref:`ytdl options <config_reference/plugins:ytdl_options>` section of your config: See `yt-dl's recommended way
<https://github.com/ytdl-org/youtube-dl#how-do-i-pass-cookies-to-youtube-dl>`_ to
download your YouTube cookie, then add it to your :ref:`ytdl options
<config_reference/plugins:ytdl_options>` section of your config:
.. code-block:: yaml .. code-block:: yaml
@ -50,7 +61,8 @@ See `yt-dl's recommended way <https://github.com/ytdl-org/youtube-dl#how-do-i-pa
...automate my downloads? ...automate my downloads?
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
:doc:`This page </guides/getting_started/automating_downloads>` shows how to set up ``ytdl-sub`` to run automatically on various platforms. :doc:`This page </guides/getting_started/automating_downloads>` shows how to set up
``ytdl-sub`` to run automatically on various platforms.
...download large channels? ...download large channels?
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -65,7 +77,8 @@ See the prebuilt preset :doc:`Filter Keywords </prebuilt_presets/helpers>`.
...prevent creation of NFO file ...prevent creation of NFO file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Creation of NFO files is done by the NFO tags plugin. It, as any other plugin, can be disabled: Creation of NFO files is done by the NFO tags plugin. It, as any other plugin, can be
disabled:
.. code-block:: yaml .. code-block:: yaml
@ -75,8 +88,9 @@ Creation of NFO files is done by the NFO tags plugin. It, as any other plugin, c
...prevent download of images ...prevent download of images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :ref:`config_reference/prebuilt_presets/tv_show:TV Show` presets by default downloads images corresponding to show and each episode. The :ref:`config_reference/prebuilt_presets/tv_show:TV Show` presets by default
This can be prevented by overriding following variables: downloads images corresponding to show and each episode. This can be prevented by
overriding following variables:
.. code-block:: yaml .. code-block:: yaml
@ -88,10 +102,11 @@ This can be prevented by overriding following variables:
...use only part of the media's title ...use only part of the media's title
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ytdl-sub offers a range of functions that can be used to parse a subset of a title ytdl-sub offers a range of functions that can be used to parse a subset of a title for
for use in your media player. Consider the example: use in your media player. Consider the example:
* I want to remove "NOVA PBS - " from the title ``NOVA PBS - Hidden Cities All Around Us``. * I want to remove "NOVA PBS - " from the title ``NOVA PBS - Hidden Cities All Around
Us``.
There are several solutions using ytdl-sub's scripting capabilities to override There are several solutions using ytdl-sub's scripting capabilities to override
``episode_title`` by manipulating the original media's ``title``. ``episode_title`` by manipulating the original media's ``title``.
@ -117,7 +132,9 @@ There are several solutions using ytdl-sub's scripting capabilities to override
} }
.. code-block:: yaml .. code-block:: yaml
:caption: Regex capture. Supports multiple capture strings and default values if captures are unsuccessful. :caption:
Regex capture. Supports multiple capture strings and default values if captures
are unsuccessful.
"~Nova PBS": "~Nova PBS":
url: "https://www.youtube.com/@novapbs" url: "https://www.youtube.com/@novapbs"
@ -132,10 +149,10 @@ There are several solutions using ytdl-sub's scripting capabilities to override
episode_title: >- episode_title: >-
{ %array_at( captured_episode_title, 1 ) } { %array_at( captured_episode_title, 1 ) }
There is no single solution to this problem - it will vary case-by-case. See There is no single solution to this problem - it will vary case-by-case. See our full
our full suite of suite of :ref:`scripting functions
:ref:`scripting functions <config_reference/scripting/scripting_functions:Scripting Functions>` <config_reference/scripting/scripting_functions:Scripting Functions>` to create your own
to create your own clever scraping mechanisms. clever scraping mechanisms.
There is a bug where... There is a bug where...
----------------------- -----------------------
@ -143,33 +160,39 @@ There is a bug where...
..ytdl-sub is not downloading ..ytdl-sub is not downloading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Run with ``--log-level verbose`` to see all yt-dlp logs, to rule out whether it is a yt-dlp or ytdl-sub issue. Run with ``--log-level verbose`` to see all yt-dlp logs, to rule out whether it is a
yt-dlp or ytdl-sub issue.
Any logs showing failed downloads, 403 errors, signs of throttles, etc, are a yt-dlp issue. Any logs showing failed downloads, 403 errors, signs of throttles, etc, are a yt-dlp
A good strategy is to see if your same issue has been reported in issue. A good strategy is to see if your same issue has been reported in `yt-dlp's
`yt-dlp's GitHub issues <https://github.com/yt-dlp/yt-dlp/issues>`_, and search to see if there is a comment including GitHub issues <https://github.com/yt-dlp/yt-dlp/issues>`_, and search to see if there is
a fix or workaround. a comment including a fix or workaround.
If it looks like a ytdl-sub issue, run with ``--log-level debug`` and make a If it looks like a ytdl-sub issue, run with ``--log-level debug`` and make a `GitHub
`GitHub issue in ytdl-sub <https://github.com/jmbannon/ytdl-sub/issues>`_ issue in ytdl-sub <https://github.com/jmbannon/ytdl-sub/issues>`_ containing these logs
containing these logs and other relevant info. and other relevant info.
...date_range is not downloading older videos after I changed the range ...date_range is not downloading older videos after I changed the range
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Your preset most likely has ``break_on_existing`` set to True, which will stop downloading additional metadata/videos if the video exists in your download archive. Set the following in your config to skip downloading videos that exist instead of stopping altogether. Your preset most likely has ``break_on_existing`` set to True, which will stop
downloading additional metadata/videos if the video exists in your download archive. Set
the following in your config to skip downloading videos that exist instead of stopping
altogether.
.. code-block:: yaml .. code-block:: yaml
ytdl_options: ytdl_options:
break_on_existing: False break_on_existing: False
After you download your new date_range duration, re-enable ``break_on_existing`` to speed up successive downloads. After you download your new date_range duration, re-enable ``break_on_existing`` to
speed up successive downloads.
...it is downloading non-English title and description metadata ...it is downloading non-English title and description metadata
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most likely the video has a non-English language set to its 'native' language. You can tell yt-dlp to explicitly download English metadata using. Most likely the video has a non-English language set to its 'native' language. You can
tell yt-dlp to explicitly download English metadata using.
.. code-block:: yaml .. code-block:: yaml
@ -185,7 +208,9 @@ Most likely the video has a non-English language set to its 'native' language. Y
1. Set the following for your ytdl-sub library that has been added to Plex. 1. Set the following for your ytdl-sub library that has been added to Plex.
.. figure:: ../../images/plex_scanner_agent.png .. figure:: ../../images/plex_scanner_agent.png
:alt: The Plex library editor, under the advanced settings, showing the required options for Plex to show the TV shows correctly. :alt:
The Plex library editor, under the advanced settings, showing the required options
for Plex to show the TV shows correctly.
- **Scanner:** Plex Series Scanner - **Scanner:** Plex Series Scanner
- **Agent:** Personal Media shows - **Agent:** Personal Media shows
@ -193,7 +218,10 @@ Most likely the video has a non-English language set to its 'native' language. Y
- **Episode sorting:** Library default - **Episode sorting:** Library default
- **YES** Enable video preview thumbnails - **YES** Enable video preview thumbnails
2. Under **Settings** > **Agents**, confirm Plex Personal Media Shows/Movies scanner has **Local Media Assets** enabled. 2. Under **Settings** > **Agents**, confirm Plex Personal Media Shows/Movies scanner has
**Local Media Assets** enabled.
.. figure:: ../../images/plex_agent_sources.png .. figure:: ../../images/plex_agent_sources.png
:alt: The Plex Agents settings page has Local Media Assets enabled for Personal Media Shows and Movies tabs. :alt:
The Plex Agents settings page has Local Media Assets enabled for Personal Media
Shows and Movies tabs.

38
docs/source/guides/development/index.rst
View file

@ -1,8 +1,10 @@
Development and Contributing Development and Contributing
============================ ============================
Requirements Requirements
------------ ------------
- python >= 3.10 - python >= 3.10
- ffmpeg/ffprobe 4.4.5 (test checksums rely on this version) - ffmpeg/ffprobe 4.4.5 (test checksums rely on this version)
- make - make
@ -20,15 +22,18 @@ Local Install
pip install -e .\[test,lint,docs\] pip install -e .\[test,lint,docs\]
Linter Linter
------ ------
All source code contributed must be formatted to our linter specification.
Run the following to auto-format and check for any issues with your code: All source code contributed must be formatted to our linter specification. Run the
following to auto-format and check for any issues with your code:
.. code-block:: shell .. code-block:: shell
make lint make lint
Adding Documentation Adding Documentation
-------------------- --------------------
@ -36,12 +41,14 @@ Docs can be found in ``ytdl-sub/docs/source/``, and are built using the command:
.. code-block:: shell .. code-block:: shell
:caption: Viewable at http://localhost:63342/ytdl-sub/docs/build/html/index.html once built :caption:
Viewable at http://localhost:63342/ytdl-sub/docs/build/html/index.html once built
make docs make docs
Some of the documentation is built using doc-strings from the python source code. The above Some of the documentation is built using doc-strings from the python source code. The
command will rebuild those as well. above command will rebuild those as well.
Testing Testing
------- -------
@ -55,26 +62,31 @@ If integration tests are failing, ensure...
- you are developing on Linux or Mac (have not tested windows yet) - you are developing on Linux or Mac (have not tested windows yet)
- your local ``ytdl-sub`` dependencies are up-to-date - your local ``ytdl-sub`` dependencies are up-to-date
IDE Setup IDE Setup
--------- ---------
PyCharm is our preferred IDE. The codebase is simple enough to where it's not required, but
is highly recommended. PyCharm is our preferred IDE. The codebase is simple enough to where it's not required,
but is highly recommended.
TODO: screenshots of configuration TODO: screenshots of configuration
Debugging Debugging
--------- ---------
Debug Logs Debug Logs
^^^^^^^^^^^^^^^ ^^^^^^^^^^
Run with ``--log-level debug`` to show all debug logs when running ytdl-sub. Run with ``--log-level debug`` to show all debug logs when running ytdl-sub.
Reproducing a Failing Subscription Reproducing a Failing Subscription
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Subscriptions will dump their entire *compiled* yaml at the beginning of exeuction
when using ``--log-level debug``. This can be copy-pasted into the file Subscriptions will dump their entire *compiled* yaml at the beginning of exeuction when
using ``--log-level debug``. This can be copy-pasted into the file
``resources/file_fixtures/repro.yaml``. ``resources/file_fixtures/repro.yaml``.
Running the test ``e2e.test_debug_repro.TestReproduce.test_debug_log_repro`` Running the test ``e2e.test_debug_repro.TestReproduce.test_debug_log_repro`` will fully
will fully reproduce that subscription in order to debug it. reproduce that subscription in order to debug it.

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

@ -9,6 +9,7 @@ Automating Downloads
.. _cron scheduling syntax: https://crontab.guru/#0_*/6_*_*_* .. _cron scheduling syntax: https://crontab.guru/#0_*/6_*_*_*
.. _docker-unraid-setup: .. _docker-unraid-setup:
Docker and Unraid Docker and Unraid
@ -26,11 +27,13 @@ ENV variables to your docker setup.
- CRON_RUN_ON_START=false - CRON_RUN_ON_START=false
- ``CRON_SCHEDULE`` follows the standard `cron scheduling syntax`_. The above value will run the script once every 6 hours. - ``CRON_SCHEDULE`` follows the standard `cron scheduling syntax`_. The above value will
- ``CRON_RUN_ON_START`` toggles whether to run your cron script on container start in addition to the cron schedule. run the script once every 6 hours.
- ``CRON_RUN_ON_START`` toggles whether to run your cron script on container start in
addition to the cron schedule.
The cron script will reside in the main directory with the file name ``cron``. The cron script will reside in the main directory with the file name ``cron``. Cron
Cron logs should show when viewing the Docker logs. logs should show when viewing the Docker logs.
.. _linux-setup: .. _linux-setup:
@ -45,13 +48,13 @@ Must configure crontab manually, like so:
0 */6 * * * /config/run_cron 0 */6 * * * /config/run_cron
.. _windows-setup: .. _windows-setup:
Windows Windows
------- -------
To be tested (please contact code owner or join the discord server if you can test this out for us)
To be tested (please contact code owner or join the discord server if you can test this
out for us)
.. code-block:: powershell .. code-block:: powershell

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

@ -3,10 +3,11 @@ Basic Configuration
A configuration file serves two purposes: A configuration file serves two purposes:
1. Set advanced functionality that is not specifiable in a subscription file, such as working directory location. These 1. Set advanced functionality that is not specifiable in a subscription file, such as
are set underneath ``configuration``. working directory location. These are set underneath ``configuration``.
2. Create custom presets, which can drastically simplify your subscription file. These are defined underneath ``presets``. 2. Create custom presets, which can drastically simplify your subscription file. These
Presets are intended to be applicable and reusable across multiple subscriptions. are defined underneath ``presets``. Presets are intended to be applicable and
reusable across multiple subscriptions.
Below is a common configuration: Below is a common configuration:
@ -43,10 +44,12 @@ Below is a common configuration:
- "TV Show" - "TV Show"
- "Only Recent" - "Only Recent"
Configuration Section Configuration Section
--------------------- ---------------------
The :ref:`configuration <config_reference/config_yaml:Configuration File>` section sets options for ytdl-sub execution. The :ref:`configuration <config_reference/config_yaml:Configuration File>` section sets
options for ytdl-sub execution.
.. code-block:: yaml .. code-block:: yaml
:lineno-start: 1 :lineno-start: 1
@ -54,10 +57,12 @@ The :ref:`configuration <config_reference/config_yaml:Configuration File>` secti
configuration: configuration:
working_directory: '/mnt/ssd/.ytdl-sub-downloads' working_directory: '/mnt/ssd/.ytdl-sub-downloads'
Preset Section Preset Section
-------------- --------------
Underneath ``presets``, we define two custom presets with the names ``TV Show`` and ``TV Show Only Recent``. Underneath ``presets``, we define two custom presets with the names ``TV Show`` and ``TV
Show Only Recent``.
.. code-block:: yaml .. code-block:: yaml
@ -69,6 +74,7 @@ Underneath ``presets``, we define two custom presets with the names ``TV Show``
The indentation example above shows how to define multiple presets. The indentation example above shows how to define multiple presets.
Custom Preset Definition Custom Preset Definition
------------------------ ------------------------
@ -88,12 +94,15 @@ Before we break down the above ``TV Show`` preset, lets first outline a preset l
Presets can contain three important things: Presets can contain three important things:
1. ``preset`` section, which can inherit :ref:`prebuilt presets <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` 1. ``preset`` section, which can inherit :ref:`prebuilt presets
or other presets defined in your config. <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` or other presets
defined in your config.
2. :ref:`Plugin definitions <config_reference/plugins:Plugins>` 2. :ref:`Plugin definitions <config_reference/plugins:Plugins>`
3. :ref:`overrides <config_reference/plugins:overrides>`, which can override inherited preset variables 3. :ref:`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. Presets do not have to define all of these, as we'll see in the ``TV Show Only Recent``
preset.
Inheriting Presets Inheriting Presets
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
@ -106,14 +115,16 @@ Inheriting Presets
- "Jellyfin TV Show by Date" - "Jellyfin TV Show by Date"
- "Max 1080p" - "Max 1080p"
The following snippet shows that the ``TV Show`` preset will inherit all properties The following snippet shows that the ``TV Show`` preset will inherit all properties of
of the prebuilt presets ``Jellyfin TV Show by Date`` and ``Max 1080p`` in that order. 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. Order matters for preset inheritance. Bottom-most presets will override ones above them.
It is highly advisable to use :ref:`prebuilt presets <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` as It is highly advisable to use :ref:`prebuilt presets
a starting point for custom preset building, as they do the work of preset building to ensure things show as expected <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` as a starting point
in their respective media players. Read on to see how to override prebuilt preset specifics such as title. 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 Defining Plugins
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
@ -134,17 +145,18 @@ Defining Plugins
min: 10 min: 10
max: 36 max: 36
Our ``TV Show`` sets two plugins, :ref:`throttle_protection <config_reference/plugins:throttle_protection>` and Our ``TV Show`` sets two plugins, :ref:`throttle_protection
:ref:`embed_thumbnail <config_reference/plugins:embed_thumbnail>`. Each plugin's documentation shows the respective <config_reference/plugins:throttle_protection>` and :ref:`embed_thumbnail
fields that they support. <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 If an inherited preset defines the same plugin, the custom preset will use
combine their definitions. What this means is: '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
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
Setting Override Variables Setting Override Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -155,27 +167,31 @@ Setting Override Variables
overrides: overrides:
tv_show_directory: "/ytdl_sub_tv_shows" tv_show_directory: "/ytdl_sub_tv_shows"
All override variables reside underneath the :ref:`overrides <config_reference/plugins:overrides>` section. All override variables reside underneath the :ref:`overrides
<config_reference/plugins:overrides>` section.
It is important to remember that individual subscriptions can override specific override variables. It is important to remember that individual subscriptions can override specific override
When defining variables in a preset, it is best practice to define them with the intention that 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 1. All subscriptions will use its value them
2. Use them as placeholders to perform other logic, then have subscriptions or child presets 2. Use them as placeholders to perform other logic, then have subscriptions or child
define their specific value presets define their specific value
For simplicity, we'll focus on (1) for now. The above snippet sets the ``tv_show_directory`` For simplicity, we'll focus on (1) for now. The above snippet sets the
variable to a file path. This variable name is specific to the prebuilt TV show presets. ``tv_show_directory`` variable to a file path. This variable name is specific to the
prebuilt TV show presets.
See the :ref:`prebuilt preset reference <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` See the :ref:`prebuilt preset reference
to see all available variables that are overridable. <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` to see all
available variables that are overridable.
Using Custom Presets in Subscriptions Using Custom Presets in Subscriptions
-------------------------------------- --------------------------------------
Subscription files can use custom presets just like any other prebuilt preset. Subscription files can use custom presets just like any other prebuilt preset. Below
Below shows a complete subscription file using the above two custom presets. shows a complete subscription file using the above two custom presets.
.. code-block:: yaml .. code-block:: yaml
@ -193,11 +209,12 @@ Below shows a complete subscription file using the above two custom presets.
Notice how we do not need to define ``tv_show_directory`` in the ``__preset__`` section 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. like in prior examples. This is because our custom presets do the work of defining it.
Reference Custom Config in the CLI Reference Custom Config in the CLI
---------------------------------- ----------------------------------
Be sure to tell ytdl-sub to use your config by using the argument Be sure to tell ytdl-sub to use your config by using the argument ``--config
``--config /path/to/config.yaml``. /path/to/config.yaml``.
If you run ytdl-sub in the same directory, and the config file is named ``config.yaml``, it will If you run ytdl-sub in the same directory, and the config file is named ``config.yaml``,
use it by default. it will use it by default.

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

@ -2,11 +2,13 @@ Initial Download
================ ================
Once you have a ``subscriptions.yaml`` file created, 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`` download. Access ``ytdl-sub``, navigate to the directory containing your
file. ``subscriptions.yaml`` file.
Dry Run Dry Run
------- -------
Performing a dry run is important when applying any change to your subscriptions to 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 ensure output looks as expected. Dry runs will pull metadata to *simulate* a download
without actually downloading the media file. without actually downloading the media file.
@ -15,11 +17,12 @@ without actually downloading the media file.
ytdl-sub --dry-run sub subscriptions.yaml ytdl-sub --dry-run sub subscriptions.yaml
Faster Iteration Cycle 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 Testing subscriptions can take quite some time to perform a full download. This can be
of downloads. speed up by applying an override via command-line to set max number of downloads.
.. code-block:: shell .. code-block:: shell
@ -33,17 +36,20 @@ subscriptions can be dry ran using a match.
ytdl-sub --dry-run sub subscriptions.yaml -o '--ytdl_options.max_downloads 3' --match PBS ytdl-sub --dry-run sub subscriptions.yaml -o '--ytdl_options.max_downloads 3' --match PBS
Downloading Downloading
----------- -----------
Once the subscriptions file is validated, a download can be performed by omitting the dry run argument.
Once the subscriptions file is validated, a download can be performed by omitting the
dry run argument.
.. code-block:: shell .. code-block:: shell
ytdl-sub sub subscriptions.yaml ytdl-sub sub subscriptions.yaml
Multiple subscription file names can be provided to perform a download on all of them. A single file Multiple subscription file names can be provided to perform a download on all of them. A
named ``subscriptions.yaml`` does not require a file name specification since it will single file named ``subscriptions.yaml`` does not require a file name specification
look for that file name by default, making the following command valid. since it will look for that file name by default, making the following command valid.
.. code-block:: shell .. code-block:: shell

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

@ -42,17 +42,18 @@ Let's break this down:
music_directory: "/music" music_directory: "/music"
The first :ref:`__preset__ <config_reference/subscription_yaml:File Preset>` section is where we The first :ref:`__preset__ <config_reference/subscription_yaml:File Preset>` section is
can set modifications that apply to every subscription in this file. 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, This snippet specifically adds two :ref:`override <config_reference/plugins:Overrides>`
which are used by the presets below. variables, which are used by the presets below.
.. note:: .. 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.
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.
------------------------------------- -------------------------------------
@ -61,11 +62,11 @@ which are used by the presets below.
Jellyfin TV Show by Date: Jellyfin TV Show by Date:
On line 11, we set the key to ``Jellyfin TV Show by Date``. This is a On line 11, we set the key to ``Jellyfin TV Show by Date``. This is a :ref:`prebuilt
:ref:`prebuilt preset <prebuilt_presets/index:prebuilt presets>` that configures preset <prebuilt_presets/index:prebuilt presets>` that configures subscriptions to look
subscriptions to look like TV shows in the Jellyfin media player (can be changed to like TV shows in the Jellyfin media player (can be changed to one of the presets
one of the presets outlined in the comment above). Setting it as a YAML key implies that all outlined in the comment above). Setting it as a YAML key implies that all subscriptions
subscriptions underneath it will *inherit* this preset. underneath it will *inherit* this preset.
This preset expects the variable ``tv_show_directory`` to be set, which we do above. This preset expects the variable ``tv_show_directory`` to be set, which we do above.
@ -77,14 +78,14 @@ This preset expects the variable ``tv_show_directory`` to be set, which we do ab
Jellyfin TV Show by Date: Jellyfin TV Show by Date:
= Documentaries: = Documentaries:
Line 12 sets the key to ``= Documentaries``. When keys are prefixed with ``=``, it means we are Line 12 sets the key to ``= Documentaries``. When keys are prefixed with ``=``, it means
setting the genre. This value will get written to the respective metadata tags for both TV show we are setting the genre. This value will get written to the respective metadata tags
and music presets. for both TV show and music presets.
Behind the scenes, this sets the override variable ``subscription_indent_1``. Further documentation Behind the scenes, this sets the override variable ``subscription_indent_1``. Further
can be found here for documentation can be found here for :ref:`subscription syntax
:ref:`subscription syntax <config_reference/subscription_yaml:Subscription File>` and <config_reference/subscription_yaml:Subscription File>` and :ref:`subscription variables
:ref:`subscription variables <config_reference/scripting/static_variables:Subscription Variables>`. <config_reference/scripting/static_variables:Subscription Variables>`.
------------------------------------- -------------------------------------
@ -95,12 +96,12 @@ can be found here for
= Documentaries: = Documentaries:
"NOVA PBS": "https://www.youtube.com/@novapbs" "NOVA PBS": "https://www.youtube.com/@novapbs"
Line 13 is where we define our first subscription. We set the subscription name to ``NOVA PBS``, Line 13 is where we define our first subscription. We set the subscription name to
and the subscription value to ``https://www.youtube.com/@novapbs``. ``NOVA PBS``, and the subscription value to ``https://www.youtube.com/@novapbs``.
To see how presets ingest subscription definitions, refer to the To see how presets ingest subscription definitions, refer to the :ref:`preset references
:ref:`preset references <config_reference/prebuilt_presets/tv_show:TV Show>`, <config_reference/prebuilt_presets/tv_show:TV Show>`, we can see that
we can see that ``{subscription_name}`` is used to set the ``tv_show_name`` variable. ``{subscription_name}`` is used to set the ``tv_show_name`` variable.
------------------------------------- -------------------------------------
@ -114,13 +115,14 @@ we can see that ``{subscription_name}`` is used to set the ``tv_show_name`` vari
= Kids | = TV-Y: = Kids | = TV-Y:
"Jake Trains": "https://www.youtube.com/@JakeTrains" "Jake Trains": "https://www.youtube.com/@JakeTrains"
Line 15 underneath ``Jellyfin TV Show by Date``, but at the same level as ``= Documentaries``. Line 15 underneath ``Jellyfin TV Show by Date``, but at the same level as ``=
This means we'll inherit the TV show preset, but not the documentaries indent variable. We instead Documentaries``. This means we'll inherit the TV show preset, but not the documentaries
set the indent variables to ``= Kids | = TV-Y``. This sets two indent variables. We can set indent variable. We instead set the indent variables to ``= Kids | = TV-Y``. This sets
multiple presets and/or indent variables on the same key by using ``|`` as a separator. two indent variables. We can set multiple presets and/or indent variables on the same
key by using ``|`` as a separator.
Referring to the Referring to the :ref:`TV show preset reference
:ref:`TV show preset reference <config_reference/prebuilt_presets/tv_show:TV Show>`, the first <config_reference/prebuilt_presets/tv_show:TV Show>`, the first two indent variables map
two indent variables map to the TV show genre and TV show content rating. to the TV show genre and TV show content rating.
The above info should be enough to understand the rest of the subscription file. The above info should be enough to understand the rest of the subscription file.

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

@ -1,6 +1,7 @@
Getting Started Getting Started
=============== ===============
Prerequisite Knowledge Prerequisite Knowledge
---------------------- ----------------------
@ -29,13 +30,14 @@ how ``ytdl-sub`` works, how it "thinks". So before you start configuring ``ytdl-
.. _`YAML text files`: http://thomasloven.com/blog/2018/08/YAML-For-Nonprogrammers/ .. _`YAML text files`: http://thomasloven.com/blog/2018/08/YAML-For-Nonprogrammers/
Architecture Architecture
------------ ------------
For most users, ``ytdl-sub`` works as follows: For most users, ``ytdl-sub`` works as follows:
Subscriptions use presets 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 <./first_sub>` that defines
what subscriptions to download and place into your media library. Each subscription what subscriptions to download and place into your media library. Each subscription
@ -43,7 +45,7 @@ selects which :doc:`presets <../../prebuilt_presets/index>` to apply. Those pres
configure how each subscription is downloaded and placed in the media library. configure how each subscription is downloaded and placed in the media library.
Presets configure plugins Presets configure plugins
^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~
:doc:`A preset <../../prebuilt_presets/index>` is effectively a set of plugin :doc:`A preset <../../prebuilt_presets/index>` is effectively a set of plugin
configurations. Specifically, a preset consists of: configurations. Specifically, a preset consists of:
@ -58,7 +60,7 @@ the same keys for a plugin that one of its base plugins configures, the preset
configuration overrides the base presets. configuration overrides the base presets.
Plugins do the work Plugins do the work
^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~
``ytdl-sub`` applies the plugins that the presets configure when it downloads a ``ytdl-sub`` applies the plugins that the presets configure when it downloads a
subscription. :doc:`The plugins <../../config_reference/plugins>` control how to run subscription. :doc:`The plugins <../../config_reference/plugins>` control how to run
@ -67,18 +69,18 @@ metadata for those media, and how to place the resulting files into your media l
and more. and more.
Presets and subscriptions accept overrides Presets and subscriptions accept overrides
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Presets accept override keys and values and the preset uses those overrides to modify Presets accept override keys and values and the preset uses those overrides to modify
their plugin configurations. Similarly, individual subscriptions can supply overrides of their plugin configurations. Similarly, individual subscriptions can supply overrides of
their presets for just that subscription. their presets for just that subscription.
Subscriptions are grouped by indentation Subscriptions are grouped by indentation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most subscriptions have more in common with each other than not. Thus, defining the presets Most subscriptions have more in common with each other than not. Thus, defining the
and overrides for each subscription would result in mostly repetition and would multiply presets and overrides for each subscription would result in mostly repetition and would
the burden of management for the user. The more subscriptions the more work. multiply the burden of management for the user. The more subscriptions the more work.
To avoid this redundant work, and so that the subscription configurations describe the To avoid this redundant work, and so that the subscription configurations describe the
intent of the user, subscriptions are nested/indented under parent/ancestor keys that intent of the user, subscriptions are nested/indented under parent/ancestor keys that
@ -96,14 +98,14 @@ Finally, ancestor keys may use the ``... | ...`` special character to combine mu
presets and/or genres for the descendant subscriptions beneath. presets and/or genres for the descendant subscriptions beneath.
The configuration file extends pre-defined presets The configuration file extends pre-defined presets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Users define additional presets in :doc:`their configuration file <./first_config>` that Users define additional presets in :doc:`their configuration file <./first_config>` that
they then use in most of their subscriptions. Most user-defines presets extend the they then use in most of their subscriptions. Most user-defines presets extend the
:doc:`../../prebuilt_presets/index` provided by ``ytdl-sub``. :doc:`../../prebuilt_presets/index` provided by ``ytdl-sub``.
Caveats Caveats
^^^^^^^ ~~~~~~~
Some of these descriptions are not technically complete. For example, a subscription may Some of these descriptions are not technically complete. For example, a subscription may
use no preset at all and will just run ``yt-dlp`` without any customization or post use no preset at all and will just run ``yt-dlp`` without any customization or post
@ -118,8 +120,10 @@ is accurate and representative.
Ready to Start? Ready to Start?
--------------- ---------------
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. 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:: .. toctree::
:maxdepth: 2 :maxdepth: 2

20
docs/source/guides/install/agnostic.rst
View file

@ -2,13 +2,15 @@
Environment Agnostic Environment Agnostic
==================== ====================
The PIP install method is not recommended; use of this method may cause unintended requirement conflicts if you have other locally installed apps that depend on ffmpeg. The PIP install method is not recommended; use of this method may cause unintended
requirement conflicts if you have other locally installed apps that depend on ffmpeg.
PIP Install PIP Install
-------------- --------------
You can install our
`PyPI package <https://pypi.org/project/ytdl-sub/>`_. You can install our `PyPI package <https://pypi.org/project/ytdl-sub/>`_. Both ffmpeg
Both ffmpeg and Python 3.10 or greater are required. and Python 3.10 or greater are required.
.. code-block:: bash .. code-block:: bash
@ -17,10 +19,13 @@ Both ffmpeg and Python 3.10 or greater are required.
Install for Development Install for Development
======================= =======================
These environment-agnostic methods of installing ``ytdl-sub`` are meant for local development of ``ytdl-sub``. If you want to contribute your changes, please read :doc:`/guides/development/index`. These environment-agnostic methods of installing ``ytdl-sub`` are meant for local
development of ``ytdl-sub``. If you want to contribute your changes, please read
:doc:`/guides/development/index`.
Local Install Local Install
-------------- --------------
With a Python 3.10 virtual environment, you can clone and install the repo. With a Python 3.10 virtual environment, you can clone and install the repo.
.. code-block:: bash .. code-block:: bash
@ -32,8 +37,9 @@ With a Python 3.10 virtual environment, you can clone and install the repo.
Local Docker Build Local Docker Build
------------------- -------------------
Run ``make docker`` in the root directory of this repo to build the image. This
will build the python wheel and install it in the Dockerfile. Run ``make docker`` in the root directory of this repo to build the image. This will
build the python wheel and install it in the Dockerfile.
.. code-block:: bash .. code-block:: bash

5
docs/source/guides/install/docker.rst
View file

@ -10,6 +10,7 @@ the recommended way of managing a ``ytdl-sub`` docker container. See :ref:`Auto
Downloads <guides/getting_started/automating_downloads:docker and unraid>` for how to Downloads <guides/getting_started/automating_downloads:docker and unraid>` for how to
automate running ``ytdl-sub`` in a container running either variant. automate running ``ytdl-sub`` in a container running either variant.
GUI Image GUI Image
--------- ---------
@ -21,6 +22,7 @@ and other details. Once running, open `the web UI`_ to edit the `configuration`_
.. _`the web UI`: http://localhost:8443 .. _`the web UI`: http://localhost:8443
Headless Image Headless Image
-------------- --------------
@ -36,6 +38,7 @@ For example::
$ docker compose run --rm --user="${PUID}:${PGID}" --entrypoint="ytdl-sub" ytdl-sub sub $ docker compose run --rm --user="${PUID}:${PGID}" --entrypoint="ytdl-sub" ytdl-sub sub
Install with Docker Compose Install with Docker Compose
--------------------------- ---------------------------
@ -84,6 +87,7 @@ directory such as:
# devices: # devices:
# - capabilities: ["gpu"] # - capabilities: ["gpu"]
Docker CLI Docker CLI
---------- ----------
@ -109,6 +113,7 @@ host. The following command is for the gui image:
See `the Docker reference <https://docs.docker.com/engine/reference/run/>`_ for further See `the Docker reference <https://docs.docker.com/engine/reference/run/>`_ for further
details. details.
Configuration Configuration
------------- -------------

9
docs/source/guides/install/index.rst
View file

@ -1,5 +1,6 @@
Install by Platform Install by Platform
=================== ===================
``ytdl-sub`` can be installed on the following platforms. ``ytdl-sub`` can be installed on the following platforms.
All installations require a 64-bit CPU. 32-bit is not supported. All installations require a 64-bit CPU. 32-bit is not supported.
@ -8,7 +9,8 @@ All installations require a 64-bit CPU. 32-bit is not supported.
.. tip:: .. tip::
The recommended install method of ``ytdl-sub`` is one of our :doc:`docker containers </guides/install/docker>`. The recommended install method of ``ytdl-sub`` is one of our :doc:`docker containers
</guides/install/docker>`.
:doc:`/guides/install/docker` :doc:`/guides/install/docker`
@ -20,9 +22,8 @@ All installations require a 64-bit CPU. 32-bit is not supported.
:doc:`/guides/install/agnostic` :doc:`/guides/install/agnostic`
Once you've completed your installation, please refer to the
:doc:`../getting_started/index` guide for next steps
Once you've completed your installation, please refer to the :doc:`../getting_started/index` guide for next steps
.. toctree:: .. toctree::
:hidden: :hidden:

10
docs/source/guides/install/linux.rst
View file

@ -2,8 +2,8 @@
Linux Linux
===== =====
``ytdl-sub`` should be installable using any Linux package manager, and requires ffmpeg to be installed. ``ytdl-sub`` should be installable using any Linux package manager, and requires ffmpeg
to be installed.
.. tab-set:: .. tab-set::
@ -15,7 +15,8 @@ Linux
chmod +x ytdl-sub chmod +x ytdl-sub
./ytdl-sub -h ./ytdl-sub -h
You can also install using yt-dlp's ffmpeg builds. This ensures your ffmpeg is up to date: You can also install using yt-dlp's ffmpeg builds. This ensures your ffmpeg is up to
date:
.. code-block:: bash .. code-block:: bash
@ -36,7 +37,8 @@ Linux
chmod +x ytdl-sub chmod +x ytdl-sub
./ytdl-sub -h ./ytdl-sub -h
You can also install using yt-dlp's ffmpeg builds. This ensures your ffmpeg is up to date: You can also install using yt-dlp's ffmpeg builds. This ensures your ffmpeg is up to
date:
.. code-block:: bash .. code-block:: bash

29
docs/source/guides/install/unraid.rst
View file

@ -1,16 +1,29 @@
======
Unraid Unraid
-------------- ======
You can install our :unraid:`unraid community apps <community/apps?q=ytdl-sub#r>` through the `Unraid Community Apps plugin <https://unraid.net/community/apps>`_.
You can install our :unraid:`unraid community apps <community/apps?q=ytdl-sub#r>`
through the `Unraid Community Apps plugin <https://unraid.net/community/apps>`_.
If you installed the ``ytdl-sub-gui`` app, the code-server will be running at http://localhost:8443 (replace ``localhost`` with the IP of the computer running Unraid if you aren't trying to access ``ytdl-sub`` on that computer). Open this page in a browser to access and interact with ``ytdl-sub``. If you installed the ``ytdl-sub-gui`` app, the code-server will be running at
http://localhost:8443 (replace ``localhost`` with the IP of the computer running Unraid
If you installed the ``ytdl-sub`` app (headless), open the normal app-specific console to access and interact with ``ytdl-sub``. Once open, you must first run ``su abc -s /bin/bash`` to change to the non-root user. You can confirm that this command worked by running ``whoami`` and verifying that the result is ``abc``. if you aren't trying to access ``ytdl-sub`` on that computer). Open this page in a
browser to access and interact with ``ytdl-sub``.
If you installed the ``ytdl-sub`` app (headless), open the normal app-specific console
to access and interact with ``ytdl-sub``. Once open, you must first run ``su abc -s
/bin/bash`` to change to the non-root user. You can confirm that this command worked by
running ``whoami`` and verifying that the result is ``abc``.
.. warning:: .. warning::
If you use the below option to access the ``ytdl-sub`` console, be sure to run ``su abc -s /bin/bash`` first thing. You can confirm that this command worked by running ``whoami`` and verifying that the result is ``abc``. Do **NOT** run ``ytdl-sub`` as the root user! Running as root will set the owner of all modified files to root, which prevents most media managers and players from accessing the files. If you use the below option to access the ``ytdl-sub`` console, be sure to run ``su
abc -s /bin/bash`` first thing. You can confirm that this command worked by running
``whoami`` and verifying that the result is ``abc``. Do **NOT** run ``ytdl-sub`` as
the root user! Running as root will set the owner of all modified files to root,
which prevents most media managers and players from accessing the files.
.. figure:: ../../../images/unraid_badconsole.png .. figure:: ../../../images/unraid_badconsole.png
:alt: The Unraid community app plugin GUI, with an arrow pointing at the "Console" option in the dropdown after selecting ytdl-sub-gui :alt:
The Unraid community app plugin GUI, with an arrow pointing at the "Console"
option in the dropdown after selecting ytdl-sub-gui

4
docs/source/guides/install/windows.rst
View file

@ -1,5 +1,7 @@
=======
Windows Windows
-------------- =======
From powershell, run: From powershell, run:
.. code-block:: powershell .. code-block:: powershell

31
docs/source/prebuilt_presets/helpers.rst
View file

@ -6,11 +6,13 @@ Helper Presets
See how to apply helper presets :doc:`here </prebuilt_presets/index>` See how to apply helper presets :doc:`here </prebuilt_presets/index>`
Only Recent Only Recent
----------- -----------
To only download a recent number of videos, apply the ``Only Recent`` preset. Once a video's To only download a recent number of videos, apply the ``Only Recent`` preset. Once a
upload date is outside of the range, or you hit max files, older videos will be deleted automatically. video's upload date is outside of the range, or you hit max files, older videos will be
deleted automatically.
.. code-block:: yaml .. code-block:: yaml
@ -31,9 +33,12 @@ To prevent deletion of files, use the preset ``Only Recent Archive`` instead.
Filter Keywords Filter Keywords
--------------- ---------------
``Filter Keywords`` can include or exclude media with any of the listed keywords. Both keywords and title/description are lower-cased before filtering. ``Filter Keywords`` can include or exclude media with any of the listed keywords. Both
keywords and title/description are lower-cased before filtering.
Default behavior for Keyword evaluation is ANY, meaning the filter will succeed if any of the keywords are present. This can be set to ANY or ALL using the respective ``_eval`` variable. Default behavior for Keyword evaluation is ANY, meaning the filter will succeed if any
of the keywords are present. This can be set to ANY or ALL using the respective
``_eval`` variable.
Supports the following override variables: Supports the following override variables:
@ -71,6 +76,7 @@ Supports the following override variables:
- "maple leafs" - "maple leafs"
- "highlights" - "highlights"
Filter Duration Filter Duration
--------------- ---------------
@ -100,17 +106,19 @@ Supports the following override variables:
url: "https://www.youtube.com/@NHL" url: "https://www.youtube.com/@NHL"
filter_duration_max_s: 180 # Only get highlight videos less than 3m long filter_duration_max_s: 180 # Only get highlight videos less than 3m long
Chunk Downloads Chunk Downloads
--------------- ---------------
If you are archiving a large channel, ``ytdl-sub`` will try pulling each video's metadata from newest to oldest before If you are archiving a large channel, ``ytdl-sub`` will try pulling each video's
starting any downloads. It is a long process and not ideal. A better method is to chunk the process by using the metadata from newest to oldest before starting any downloads. It is a long process and
following preset: not ideal. A better method is to chunk the process by using the following preset:
``Chunk Downloads`` ``Chunk Downloads``
It will download videos starting from the oldest one, and only download 20 at a time by default. You can It will download videos starting from the oldest one, and only download 20 at a time by
change this number by setting the override variable ``chunk_max_downloads``. default. You can change this number by setting the override variable
``chunk_max_downloads``.
.. code-block:: yaml .. code-block:: yaml
@ -129,5 +137,6 @@ change this number by setting the override variable ``chunk_max_downloads``.
= Documentaries: = Documentaries:
"Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U" "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"
Once the entire channel is downloaded, remove the usage of this preset. It will then pull metadata from newest to Once the entire channel is downloaded, remove the usage of this preset. It will then
oldest again, and stop once it reaches a video that has already been downloaded. pull metadata from newest to oldest again, and stop once it reaches a video that has
already been downloaded.

13
docs/source/prebuilt_presets/index.rst
View file

@ -7,11 +7,13 @@ media in various players.
.. hint:: .. hint::
Apply multiple presets to your subscriptions using pipes. Pipes can define multiple presets and values Apply multiple presets to your subscriptions using pipes. Pipes can define multiple
on the same line to apply to all subscriptions nested below them. presets and values on the same line to apply to all subscriptions nested below them.
.. code-block:: yaml .. code-block:: yaml
:caption: Applies Max Video Quality preset to all TV shows, and Chunk Downloads preset to some :caption:
Applies Max Video Quality preset to all TV shows, and Chunk Downloads preset to
some
Plex TV Show by Date | Max Video Quality: Plex TV Show by Date | Max Video Quality:
@ -22,9 +24,8 @@ media in various players.
= Documentaries: = Documentaries:
"Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U" "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"
For advanced users, you can review the prebuilt preset definitions :doc:`here
For advanced users, you can review the prebuilt preset </config_reference/prebuilt_presets/index>`.
definitions :doc:`here </config_reference/prebuilt_presets/index>`.
.. toctree:: .. toctree::
:titlesonly: :titlesonly:

8
docs/source/prebuilt_presets/media_quality.rst
View file

@ -6,8 +6,10 @@ Media Quality Presets
See how to apply media quality presets :doc:`here </prebuilt_presets/index>` See how to apply media quality presets :doc:`here </prebuilt_presets/index>`
Video Video
----- -----
The following presets set video quality specifications to yt-dlp. The following presets set video quality specifications to yt-dlp.
- ``Max Video Quality`` - ``Max Video Quality``
@ -17,10 +19,12 @@ The following presets set video quality specifications to yt-dlp.
- ``Max 720p`` - ``Max 720p``
- ``Max 480p`` - ``Max 480p``
Audio Audio
----- -----
The following presets set audio quality specifications to yt-dlp.
These assume you are only extracting audio (no video). The following presets set audio quality specifications to yt-dlp. These assume you are
only extracting audio (no video).
- ``Max Audio Quality``, format is determined by the source - ``Max Audio Quality``, format is determined by the source
- ``Max MP3 Quality`` - ``Max MP3 Quality``

41
docs/source/prebuilt_presets/music.rst
View file

@ -2,21 +2,21 @@
Music Presets Music Presets
============= =============
Music downloadable by yt-dlp comes in many flavors. ``ytdl-sub`` offers a suite Music downloadable by yt-dlp comes in many flavors. ``ytdl-sub`` offers a suite of
of various presets for handling some of the most popular forms of uploaded music various presets for handling some of the most popular forms of uploaded music content.
content.
.. hint:: .. hint::
The subscription *value* (denoted by =) will set the genre tag for all music scraped under its key The subscription *value* (denoted by =) will set the genre tag for all music scraped
for all music presets. under its key for all music presets.
YouTube Releases YouTube Releases
---------------- ----------------
Many artists, especially those auto-uploaded as ``Topics`` in YouTube have a section on Many artists, especially those auto-uploaded as ``Topics`` in YouTube have a section on
their channel named "Releases", or "Albums and Singles". The ``YouTube Releases`` preset aims to their channel named "Releases", or "Albums and Singles". The ``YouTube Releases`` preset
scrape this *playlist of playlists*. aims to scrape this *playlist of playlists*.
Playlists are recognized as the album, and videos within it are tracks. Playlists are recognized as the album, and videos within it are tracks.
@ -26,8 +26,8 @@ Playlists are recognized as the album, and videos within it are tracks.
= Jazz: # Sets genre tag to "Jazz" = Jazz: # Sets genre tag to "Jazz"
"Thelonious Monk": "https://www.youtube.com/@officialtheloniousmonk/releases" "Thelonious Monk": "https://www.youtube.com/@officialtheloniousmonk/releases"
If you are only interested in a subset of albums, you can provide their playlists as separate values in the form If you are only interested in a subset of albums, you can provide their playlists as
of an array, like so: separate values in the form of an array, like so:
.. code-block:: yaml .. code-block:: yaml
@ -37,11 +37,13 @@ of an array, like so:
- "https://www.youtube.com/playlist?list=OLAK5uy_lcqINwfzkw73TPnAt6MlpB6V0gM9VzQu8" # Monk on Monk - "https://www.youtube.com/playlist?list=OLAK5uy_lcqINwfzkw73TPnAt6MlpB6V0gM9VzQu8" # Monk on Monk
- "https://www.youtube.com/playlist?list=OLAK5uy_nhuvjuZOO3yLIWCbQzbiWfyzkGapSIuYw" # Late Night Thelonious Monk - "https://www.youtube.com/playlist?list=OLAK5uy_nhuvjuZOO3yLIWCbQzbiWfyzkGapSIuYw" # Late Night Thelonious Monk
YouTube Full Albums YouTube Full Albums
------------------- -------------------
In many cases, albums are uploaded to YouTube as a single video, where each track as separated by either
chapters or timestamps in a description. The ``YouTube Full Albums`` preset will take each video and split In many cases, albums are uploaded to YouTube as a single video, where each track as
it by the chapters to form an album. separated by either chapters or timestamps in a description. The ``YouTube Full Albums``
preset will take each video and split it by the chapters to form an album.
Videos are recognized as the album, and chapters within it are tracks. Videos are recognized as the album, and chapters within it are tracks.
@ -51,8 +53,8 @@ Videos are recognized as the album, and chapters within it are tracks.
= Lofi: = Lofi:
"Game Chops": "https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i" "Game Chops": "https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i"
If you are only interested in a subset of albums, you can provide their video as separate values in the form If you are only interested in a subset of albums, you can provide their video as
of an array, like so: separate values in the form of an array, like so:
.. code-block:: yaml .. code-block:: yaml
@ -62,11 +64,14 @@ of an array, like so:
- "https://www.youtube.com/watch?v=m7vBrD7LMLI" # Zelda & Sleep Ensemble Collection - "https://www.youtube.com/watch?v=m7vBrD7LMLI" # Zelda & Sleep Ensemble Collection
- "https://www.youtube.com/watch?v=w0XebCwSpKI" # Study Buddy ~ video game lofi mix - "https://www.youtube.com/watch?v=w0XebCwSpKI" # Study Buddy ~ video game lofi mix
Soundcloud Discography Soundcloud Discography
---------------------- ----------------------
SoundCloud tracks can be uploaded as either a single, part of an album, or a collaboration
with another artist. At this time, ``SoundCloud Discography`` only scrapes singles and albums. SoundCloud tracks can be uploaded as either a single, part of an album, or a
It will attempt to group tracks into albums before falling back to single format. collaboration with another artist. At this time, ``SoundCloud Discography`` only scrapes
singles and albums. It will attempt to group tracks into albums before falling back to
single format.
.. code-block:: yaml .. code-block:: yaml
@ -77,8 +82,10 @@ It will attempt to group tracks into albums before falling back to single format
"Lazerdiscs Records": "https://soundcloud.com/lazerdiscsrecords" "Lazerdiscs Records": "https://soundcloud.com/lazerdiscsrecords"
"Earmake": "https://soundcloud.com/earmake" "Earmake": "https://soundcloud.com/earmake"
Bandcamp Bandcamp
-------- --------
Bandcamp albums and singles can be scraped using the ``Bandcamp`` preset. Bandcamp albums and singles can be scraped using the ``Bandcamp`` preset.
.. code-block:: yaml .. code-block:: yaml

88
docs/source/prebuilt_presets/tv_shows.rst
View file

@ -2,45 +2,57 @@
TV Show Presets TV Show Presets
=============== ===============
Player-Specific Presets
=======================
``ytdl-sub`` provides player-specific versions of certain presets, which apply settings to optimize the downloads for that player. Player-Specific Presets
-----------------------
``ytdl-sub`` provides player-specific versions of certain presets, which apply settings
to optimize the downloads for that player.
The following actions are taken based on the indicated player: The following actions are taken based on the indicated player:
Kodi Kodi
-------- ~~~~
* Everything that the Jellyfin version does * Everything that the Jellyfin version does
* Enables ``kodi_safe`` NFOs, replacing 4-byte unicode characters that break kodi with ``□`` * Enables ``kodi_safe`` NFOs, replacing 4-byte unicode characters that break kodi with
``□``
Jellyfin Jellyfin
-------- ~~~~~~~~
* Places any season-specific poster art in the main show folder * Places any season-specific poster art in the main show folder
* Generates NFO tags * Generates NFO tags
Emby Emby
---- ~~~~
* Places any season-specific poster art in the main show folder * Places any season-specific poster art in the main show folder
* Generates NFO tags * Generates NFO tags
* For named seasons, creates a ``season.nfo`` file per season * For named seasons, creates a ``season.nfo`` file per season
Plex Plex
-------- ~~~~~~~~
* :ref:`Special sanitization <config_reference/scripting/entry_variables:title_sanitized_plex>` of numbers so Plex doesn't recognize numbers that are part of the title as the episode number
* :ref:`Special sanitization
<config_reference/scripting/entry_variables:title_sanitized_plex>` of numbers so Plex
doesn't recognize numbers that are part of the title as the episode number
* Converts all downloaded videos to the mp4 format * Converts all downloaded videos to the mp4 format
* Places any season-specific poster art into the season folder * Places any season-specific poster art into the season folder
---------------------------------------------- ----------------------------------------------
TV Show by Date
===============
TV Show by Date will organize something like a YouTube channel or playlist into a tv show, where seasons and episodes are organized using upload date. TV Show by Date
---------------
TV Show by Date will organize something like a YouTube channel or playlist into a tv
show, where seasons and episodes are organized using upload date.
Example Example
------- ~~~~~~~
Must define ``tv_show_directory``. Available presets: Must define ``tv_show_directory``. Available presets:
* ``Kodi TV Show by Date`` * ``Kodi TV Show by Date``
@ -74,9 +86,10 @@ Must define ``tv_show_directory``. Available presets:
- "https://www.youtube.com/@rickbeato240" - "https://www.youtube.com/@rickbeato240"
Advanced Usage Advanced Usage
-------------- ~~~~~~~~~~~~~~
If you prefer a different season/episode organization method, you can set the following override variables. If you prefer a different season/episode organization method, you can set the following
override variables.
.. code-block:: yaml .. code-block:: yaml
@ -95,12 +108,11 @@ Or for a specific preset
tv_show_by_date_season_ordering: "upload-year-month" tv_show_by_date_season_ordering: "upload-year-month"
tv_show_by_date_episode_ordering: "upload-day" tv_show_by_date_episode_ordering: "upload-day"
The following are supported. Be sure the combined season + episode ordering The following are supported. Be sure the combined season + episode ordering include the
include the year, month, day, i.e. upload-year + upload-month-day. year, month, day, i.e. upload-year + upload-month-day.
Season Ordering Season Ordering
~~~~~~~~~~~~~~~ """""""""""""""
``tv_show_by_date_season_ordering`` supports one of the following: ``tv_show_by_date_season_ordering`` supports one of the following:
@ -109,23 +121,24 @@ Season Ordering
* ``release-year`` * ``release-year``
* ``release-year-month`` * ``release-year-month``
Episode Ordering Episode Ordering
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ """"""""""""""""
``tv_show_by_date_episode_ordering`` supports one of the following: ``tv_show_by_date_episode_ordering`` supports one of the following:
* ``upload-month-day`` (default) * ``upload-month-day`` (default)
* ``upload-month-day-reversed`` * ``upload-month-day-reversed``
* Reversed means more recent episodes appear at the top of a season by having a lower value. * Reversed means more recent episodes appear at the top of a season by having a lower
value.
* ``upload-day`` * ``upload-day``
* ``release-day`` * ``release-day``
* ``release-month-day`` * ``release-month-day``
* ``release-month-day-reversed`` * ``release-month-day-reversed``
* ``download-index`` * ``download-index``
* Episodes are numbered by the download order. **NOTE**: this is fetched using the length of the download archive. Do not use if you intend to remove old videos. * Episodes are numbered by the download order. **NOTE**: this is fetched using the
length of the download archive. Do not use if you intend to remove old videos.
TV Show by Date presets use the following for defaults: TV Show by Date presets use the following for defaults:
@ -135,21 +148,21 @@ TV Show by Date presets use the following for defaults:
tv_show_by_date_episode_ordering: "upload-month-day" tv_show_by_date_episode_ordering: "upload-month-day"
TV Show Collection TV Show Collection
================== ------------------
TV Show Collections set each URL as its own season. If a video belongs to multiple URLs TV Show Collections set each URL as its own season. If a video belongs to multiple URLs
(i.e. a channel and a channel's playlist), the video will only download once and reside in (i.e. a channel and a channel's playlist), the video will only download once and reside
the higher-numbered season. in the higher-numbered season.
Two main use cases of a collection are: Two main use cases of a collection are:
1. Organize a YouTube channel TV show where Season 1 contains any video 1. Organize a YouTube channel TV show where Season 1 contains any video not in a
not in a 'season playlist', Season 2 for 'Playlist A', Season 3 for 'season playlist', Season 2 for 'Playlist A', Season 3 for 'Playlist B', etc.
'Playlist B', etc. 2. Organize one or more YouTube channels/playlists, where each season represents a
2. Organize one or more YouTube channels/playlists, where each season separate channel/playlist.
represents a separate channel/playlist.
Example Example
------- ~~~~~~~
Must define ``tv_show_directory``. Available presets: Must define ``tv_show_directory``. Available presets:
* ``Kodi TV Show Collection`` * ``Kodi TV Show Collection``
@ -173,9 +186,10 @@ Must define ``tv_show_directory``. Available presets:
s02_url: "https://www.youtube.com/playlist?list=PLE62gWlWZk5NWVAVuf0Lm9jdv_-_KXs0W" s02_url: "https://www.youtube.com/playlist?list=PLE62gWlWZk5NWVAVuf0Lm9jdv_-_KXs0W"
Advanced Usage Advanced Usage
-------------- ~~~~~~~~~~~~~~
If you prefer a different episode organization method, you can set the following override variables. If you prefer a different episode organization method, you can set the following
override variables.
.. code-block:: yaml .. code-block:: yaml
@ -198,9 +212,8 @@ Or for a specific preset
The following are supported. The following are supported.
Episode Ordering Episode Ordering
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ """"""""""""""""
``tv_show_collection_episode_ordering`` supports one of the following: ``tv_show_collection_episode_ordering`` supports one of the following:
@ -210,7 +223,8 @@ Episode Ordering
* ``release-year-month-day-reversed`` * ``release-year-month-day-reversed``
* ``playlist-index`` * ``playlist-index``
* Only use ``playlist-index`` episode formatting for playlists that will be fully downloaded once and never again. Otherwise, indices can change. * Only use ``playlist-index`` episode formatting for playlists that will be fully
downloaded once and never again. Otherwise, indices can change.
* ``playlist-index-reversed`` * ``playlist-index-reversed``
TV Show Collection presets use upload-year-month-day as the default. TV Show Collection presets use upload-year-month-day as the default.

28
docs/source/usage.rst
View file

@ -1,5 +1,5 @@
Usage Usage
======= =====
.. code-block:: .. code-block::
@ -7,6 +7,7 @@ Usage
For Windows users, it would be ``ytdl-sub.exe`` For Windows users, it would be ``ytdl-sub.exe``
General Options General Options
--------------- ---------------
@ -28,16 +29,19 @@ General options must be specified before the command (i.e. ``sub``).
-m MATCH [MATCH ...], --match MATCH [MATCH ...] -m MATCH [MATCH ...], --match MATCH [MATCH ...]
match subscription names to one or more substrings, and only run those subscriptions match subscription names to one or more substrings, and only run those subscriptions
Sub Options Sub Options
----------- -----------
Download all subscriptions specified in each ``SUBPATH``. Download all subscriptions specified in each ``SUBPATH``.
.. code-block:: .. code-block::
ytdl-sub [GENERAL OPTIONS] sub [SUBPATH ...] ytdl-sub [GENERAL OPTIONS] sub [SUBPATH ...]
``SUBPATH`` is one or more paths to subscription files, uses ``subscriptions.yaml`` if not provided. ``SUBPATH`` is one or more paths to subscription files, uses ``subscriptions.yaml`` if
It will use the config specified by ``--config``, or ``config.yaml`` if not provided. not provided. It will use the config specified by ``--config``, or ``config.yaml`` if
not provided.
.. code-block:: text .. code-block:: text
:caption: Additional Options :caption: Additional Options
@ -47,16 +51,19 @@ It will use the config specified by ``--config``, or ``config.yaml`` if not prov
-o DL_OVERRIDE, --dl-override DL_OVERRIDE -o DL_OVERRIDE, --dl-override DL_OVERRIDE
override all subscription config values using `dl` syntax, i.e. --dl-override='--ytdl_options.max_downloads 3' override all subscription config values using `dl` syntax, i.e. --dl-override='--ytdl_options.max_downloads 3'
Download Options Download Options
----------------- ----------------
Download a single subscription in the form of CLI arguments. Download a single subscription in the form of CLI arguments.
.. code-block:: .. code-block::
ytdl-sub [GENERAL OPTIONS] dl [SUBSCRIPTION ARGUMENTS] ytdl-sub [GENERAL OPTIONS] dl [SUBSCRIPTION ARGUMENTS]
``SUBSCRIPTION ARGUMENTS`` are exactly the same as YAML arguments, but use periods (``.``) instead ``SUBSCRIPTION ARGUMENTS`` are exactly the same as YAML arguments, but use periods
of indents for specifying YAML from the CLI. For example, you can represent this subscription: (``.``) instead of indents for specifying YAML from the CLI. For example, you can
represent this subscription:
.. code-block:: yaml .. code-block:: yaml
@ -76,11 +83,13 @@ Using the command:
--overrides.tv_show_name "Rick A" \ --overrides.tv_show_name "Rick A" \
--overrides.url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw" --overrides.url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
See how to shorten commands using See how to shorten commands using `download aliases
`download aliases <https://ytdl-sub.readthedocs.io/en/latest/config_reference/config_yaml.html#ytdl_sub.config.config_validator.ConfigOptions.dl_aliases>`_. <https://ytdl-sub.readthedocs.io/en/latest/config_reference/config_yaml.html#ytdl_sub.config.config_validator.ConfigOptions.dl_aliases>`_.
View Options View Options
----------------- ------------
.. code-block:: .. code-block::
ytdl-sub view [-sc] [URL] ytdl-sub view [-sc] [URL]
@ -91,5 +100,4 @@ View Options
-sc, --split-chapters -sc, --split-chapters
View source variables after splitting by chapters View source variables after splitting by chapters
Preview the source variables for a given URL. Helps when creating new configs. Preview the source variables for a given URL. Helps when creating new configs.