[DOCS] Consistent headings, newlines, wraps (#1293)
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
GitHub
parent
e980f60519
commit
60ff645750
30 changed files with 586 additions and 392 deletions
|
|
@ -1,7 +1,8 @@
|
|||
==================
|
||||
Configuration File
|
||||
==================
|
||||
-----------
|
||||
|
||||
|
||||
config.yaml
|
||||
-----------
|
||||
|
||||
|
|
@ -14,17 +15,19 @@ The ``config.yaml`` is made up of two sections:
|
|||
configuration:
|
||||
presets:
|
||||
|
||||
You can jump to any section and subsection of the config using the navigation
|
||||
section to the left.
|
||||
You can jump to any section and subsection of the config using the navigation section to
|
||||
the left.
|
||||
|
||||
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``
|
||||
in order to escape the backslash character.
|
||||
If you wish to represent paths like Windows, you will need to
|
||||
``C:\\double\\bashslash\\paths`` in order to escape the backslash character.
|
||||
|
||||
|
||||
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()
|
||||
:members:
|
||||
|
|
@ -32,9 +35,10 @@ and subscriptions.
|
|||
:exclude-members: subscription_value, persist_logs, experimental
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -49,14 +53,17 @@ Log files are stored as
|
|||
:members:
|
||||
:member-order: bysource
|
||||
|
||||
|
||||
presets
|
||||
~~~~~~~
|
||||
-------
|
||||
|
||||
``presets`` define a `formula` for how to format downloaded media and metadata.
|
||||
|
||||
This section is work-in-progress!
|
||||
|
||||
preset
|
||||
""""""
|
||||
~~~~~~
|
||||
|
||||
Presets support inheritance by defining a parent preset:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
|
|||
|
|
@ -2,7 +2,8 @@
|
|||
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
|
||||
|
|
|
|||
|
|
@ -4,22 +4,30 @@ Common
|
|||
|
||||
.. highlight:: yaml
|
||||
|
||||
|
||||
Filter Keywords
|
||||
---------------
|
||||
|
||||
.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/filter_keywords.yaml
|
||||
.. literalinclude::
|
||||
/../../src/ytdl_sub/prebuilt_presets/helpers/filter_keywords.yaml
|
||||
|
||||
|
||||
Filter Duration
|
||||
---------------
|
||||
|
||||
.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/filter_duration.yaml
|
||||
.. literalinclude::
|
||||
/../../src/ytdl_sub/prebuilt_presets/helpers/filter_duration.yaml
|
||||
|
||||
|
||||
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
|
||||
------------------
|
||||
|
||||
.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml
|
||||
.. literalinclude::
|
||||
/../../src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml
|
||||
|
|
|
|||
|
|
@ -2,11 +2,10 @@
|
|||
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::
|
||||
common
|
||||
tv_show
|
||||
music
|
||||
music
|
||||
|
|
|
|||
|
|
@ -6,4 +6,5 @@ All audio music based presets inherit from ``_music_base``.
|
|||
|
||||
.. highlight:: yaml
|
||||
|
||||
.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/music/singles.yaml
|
||||
.. literalinclude::
|
||||
/../../src/ytdl_sub/prebuilt_presets/music/singles.yaml
|
||||
|
|
|
|||
|
|
@ -6,4 +6,5 @@ All TV show based presets inherit from ``_episode_base``.
|
|||
|
||||
.. highlight:: yaml
|
||||
|
||||
.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/tv_show/episode.yaml
|
||||
.. literalinclude::
|
||||
/../../src/ytdl_sub/prebuilt_presets/tv_show/episode.yaml
|
||||
|
|
|
|||
|
|
@ -2,8 +2,9 @@
|
|||
Scripting
|
||||
=========
|
||||
|
||||
``ytdl-sub`` fields (file-names, tags, etc) are defined using variables and scripts. The links below
|
||||
contain reference documentation for each built-in variable and scripting function.
|
||||
``ytdl-sub`` fields (file-names, tags, etc) are defined using variables and scripts. The
|
||||
links below contain reference documentation for each built-in variable and scripting
|
||||
function.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
|
@ -13,6 +14,7 @@ contain reference documentation for each built-in variable and scripting functio
|
|||
scripting_functions
|
||||
scripting_types
|
||||
|
||||
|
||||
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}"
|
||||
|
||||
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``
|
||||
will actually write to that directory.
|
||||
our subscription is actually named "Custom YTDL-SUB TV Show", then ``ytdl-sub`` will
|
||||
actually write to that directory.
|
||||
|
||||
Entry Variables
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
For context, an *entry* is a video or audio file downloaded from ``yt-dlp``.
|
||||
*Entry variables* are variables that are derived from an entry's ``info.json`` file. This file
|
||||
For context, an *entry* is a video or audio file downloaded from ``yt-dlp``. *Entry
|
||||
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.
|
||||
|
||||
These variables are not considered static since they change per entry download. There are a
|
||||
few fields in ``ytdl-sub`` (i.e. ``output_directory``) that must be static. For others,
|
||||
we are free to use values that derive from an entry.
|
||||
These variables are not considered static since they change per entry download. There
|
||||
are a few fields in ``ytdl-sub`` (i.e. ``output_directory``) that must be static. For
|
||||
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
|
||||
title in its name. We can do that using entry variables:
|
||||
Suppose we want to customize the name of an entry's output file and thumbnail to include
|
||||
its title in its name. We can do that using entry variables:
|
||||
|
||||
.. 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
|
||||
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
|
||||
for creating and overriding custom variables.
|
||||
Instead, we can create a custom *override variable*. This is ``ytdl-sub``'s method for
|
||||
creating and overriding custom variables.
|
||||
|
||||
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:
|
||||
|
|
@ -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?
|
||||
|
||||
``ytdl-sub`` is able to *sanitize* any variable, meaning it replaces any problematic characters
|
||||
with safe alternatives that can be used in file names. We can ensure our file names and directories
|
||||
are safe by using:
|
||||
``ytdl-sub`` is able to *sanitize* any variable, meaning it replaces any problematic
|
||||
characters with safe alternatives that can be used in file names. We can ensure our file
|
||||
names and directories are safe by using:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -116,16 +118,16 @@ Simply add a ``_sanitized`` suffix to any variable name to make it sanitized.
|
|||
.. note::
|
||||
|
||||
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
|
||||
directories!
|
||||
(i.e. sanitizing ``/path/to/tv_shows/``) otherwise they will... be sanitized and not
|
||||
resolve to directories!
|
||||
|
||||
|
||||
Using Scripting Functions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
`replace <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#replace>`_
|
||||
``snake_cased_with_no_spaces``. We can use the `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.
|
||||
|
||||
.. 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}"
|
||||
|
||||
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
|
||||
saying:
|
||||
It is good practice to use ``>-`` when defining variables that use functions. It is
|
||||
YAML's way of saying:
|
||||
|
||||
- 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>`_.
|
||||
Any whitespace within curly-braces is okay since it will be parsed out. This is needed to make
|
||||
scripting function usage readable.
|
||||
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>`_.
|
||||
Any whitespace within curly-braces is okay since it will be parsed out. This is needed
|
||||
to make scripting function usage readable.
|
||||
|
||||
.. important::
|
||||
|
||||
It is important to use ``>-`` over other YAML new-line directives like ``>`` because they
|
||||
add newlines before or after curly-braces, and will be included in your variable's output string.
|
||||
It is important to use ``>-`` over other YAML new-line directives like ``>`` because
|
||||
they add newlines before or after curly-braces, and will be included in your
|
||||
variable's output string.
|
||||
|
||||
|
||||
Advanced Scripting
|
||||
------------------
|
||||
|
||||
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
|
||||
`map_get <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#map-get>`_
|
||||
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 `map_get
|
||||
<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#map-get>`_
|
||||
function like so:
|
||||
|
||||
.. 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: >-
|
||||
{ %map_get( entry_metadata, "artist", null ) }
|
||||
|
||||
Creating Custom Functions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Custom functions can be created in the overrides section using the following syntax:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -187,9 +195,9 @@ Custom functions can be created in the overrides section using the following syn
|
|||
"%get_entry_metadata_field": >-
|
||||
{ %map_get( entry_metadata, $0, null ) }
|
||||
|
||||
Custom function definitions must have ``%`` as a prefix to the function name, be surrounded by
|
||||
quotes to make YAML parsing happy, and can support arguments using ``$0``, ``$1``, ... to indicate
|
||||
their first argument, second argument, etc.
|
||||
Custom function definitions must have ``%`` as a prefix to the function name, be
|
||||
surrounded by quotes to make YAML parsing happy, and can support arguments using ``$0``,
|
||||
``$1``, ... to indicate their first argument, second argument, etc.
|
||||
|
||||
Using our new custom function, we can simply the ``artist`` variable definition above to:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
|
||||
===============
|
||||
Scripting Types
|
||||
===============
|
||||
|
||||
|
||||
Types
|
||||
-----
|
||||
|
||||
|
|
@ -16,8 +17,9 @@ Strings are a series of characters surrounded by quotes.
|
|||
|
||||
.. note::
|
||||
|
||||
For non-String types, they must be defined as parameters to scripting functions. This is because
|
||||
anything in a variable definition that is not within curly-braces gets evaluated as a String.
|
||||
For non-String types, they must be defined as parameters to scripting functions. This
|
||||
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:
|
||||
|
||||
|
|
@ -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') }"
|
||||
|
||||
In the case that you want to define a string variable that contains both single and double quotes,
|
||||
triple-quotes can be used to avoid *closing* the String.
|
||||
In the case that you want to define a string variable that contains both single and
|
||||
double quotes, triple-quotes can be used to avoid *closing* the String.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
|
|
@ -88,7 +90,8 @@ triple-quotes can be used to avoid *closing* the String.
|
|||
%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
|
||||
|
||||
|
|
@ -185,8 +188,8 @@ A type is considered boolean if it spells out ``True`` or ``False``, case-insens
|
|||
Array
|
||||
~~~~~
|
||||
|
||||
An Array contains multiple types of any kind, including nested Arrays and Maps.
|
||||
Arrays are defined using brackets (``[ ]``), and are accessed using zero-based indexing.
|
||||
An Array contains multiple types of any kind, including nested Arrays and Maps. Arrays
|
||||
are defined using brackets (``[ ]``), and are accessed using zero-based indexing.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
|
|
@ -227,8 +230,8 @@ Arrays are defined using brackets (``[ ]``), and are accessed using zero-based i
|
|||
Map
|
||||
~~~
|
||||
|
||||
A Map is a key-value store, containing mappings between keys and values.
|
||||
Maps are defined using curly-braces (``{ }``), and are accessed using their keys.
|
||||
A Map is a key-value store, containing mappings between keys and values. Maps are
|
||||
defined using curly-braces (``{ }``), and are accessed using their keys.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
|
|
@ -267,6 +270,7 @@ Maps are defined using curly-braces (``{ }``), and are accessed using their keys
|
|||
|
||||
Null
|
||||
~~~~
|
||||
|
||||
Null is represented by an empty String, and can be conveyed by spelling out ``null``,
|
||||
case-insensitive.
|
||||
|
||||
|
|
@ -297,7 +301,9 @@ Function Type-Hints
|
|||
|
||||
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::
|
||||
|
||||
|
|
@ -306,13 +312,15 @@ AnyArgument means any of the above Types are valid as input or output to a scrip
|
|||
|
||||
Numeric
|
||||
~~~~~~~
|
||||
|
||||
Numeric refers to either an Integer or Float.
|
||||
|
||||
Optional
|
||||
~~~~~~~~
|
||||
Optional means a particular scripting function argument can be either provided or not included.
|
||||
For example, the function
|
||||
`map_get <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#map-get>`_
|
||||
|
||||
Optional means a particular scripting function argument can be either provided or not
|
||||
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:
|
||||
|
||||
.. tab-set::
|
||||
|
|
@ -331,8 +339,9 @@ has an optional default value. Both of these usages are valid:
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -341,20 +350,23 @@ on the input. In this example,
|
|||
%array_apply( [ 1, 2, 3, 4], %string )
|
||||
}
|
||||
|
||||
We apply ``%string`` as a lambda function to
|
||||
`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"]``.
|
||||
We apply ``%string`` as a lambda function to `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"]``.
|
||||
|
||||
This example has one input-argument being passed into the lambda. For other lambda-based functions
|
||||
like `array_enumerate <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-enumerate>`_,
|
||||
This example has one input-argument being passed into the lambda. For other lambda-based
|
||||
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
|
||||
``LambdaTwo``, ``LambdaThree``, etc within the function spec.
|
||||
|
||||
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
|
||||
elements in the Array until it is reduced to a single value.
|
||||
|
||||
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 elements in the Array until it is reduced to a single value.
|
||||
|
||||
In this example,
|
||||
|
||||
|
|
@ -365,11 +377,12 @@ In this example,
|
|||
%array_reduce( [ 1, 2, 3, 4], %add )
|
||||
}
|
||||
|
||||
We call
|
||||
`array_reduce <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-reduce>`_
|
||||
on the input array, using
|
||||
`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
|
||||
We call `array_reduce
|
||||
<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-reduce>`_
|
||||
on the input array, using `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
|
||||
|
||||
- *reduce-call 1*: ``%add(1, 2) = 3`` (first two elements)
|
||||
- *reduce-call 2*: ``%add(3, 3) = 6`` (output from first two and third element)
|
||||
|
|
@ -380,9 +393,10 @@ And evaluate to ``10``.
|
|||
ReturnableArguments
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Returnable arguments are used in conditional functions like
|
||||
`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,
|
||||
Returnable arguments are used in conditional functions like `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,
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -391,4 +405,4 @@ which implies the argument passed into the function is the function's output. Fo
|
|||
%if( True, "Return this if True", "Return this if False" )
|
||||
}
|
||||
|
||||
is going to return ``"Return this if True"`` since the condition parameter is ``True``.
|
||||
is going to return ``"Return this if True"`` since the condition parameter is ``True``.
|
||||
|
|
|
|||
|
|
@ -2,19 +2,22 @@
|
|||
Subscription File
|
||||
==================
|
||||
|
||||
A subscription file is designed to both define and organize many things
|
||||
to download in condensed YAML.
|
||||
A subscription file is designed to both define and organize many things to download in
|
||||
condensed YAML.
|
||||
|
||||
.. hint::
|
||||
|
||||
Read the :ref:`getting started guide <guides/getting_started/index:Getting Started>`
|
||||
first before reviewing this section.
|
||||
|
||||
|
||||
File Preset
|
||||
-----------
|
||||
Many examples show ``__preset__`` at the top. This is known as the *subscription file preset*.
|
||||
It is where a single :ref:`preset <guides/getting_started/first_config:Custom Preset Definition>`
|
||||
can be defined that gets applied to each subscription within the file.
|
||||
|
||||
Many examples show ``__preset__`` at the top. This is known as the *subscription file
|
||||
preset*. It is where a single :ref:`preset <guides/getting_started/first_config:Custom
|
||||
Preset Definition>` can be defined that gets applied to each subscription within the
|
||||
file.
|
||||
|
||||
This is a good place to apply file-wide variables such as ``tv_show_directory`` or
|
||||
supply a cookies file path.
|
||||
|
|
@ -28,9 +31,9 @@ supply a cookies file path.
|
|||
ytdl_options:
|
||||
cookiefile: "/config/cookie.txt"
|
||||
|
||||
|
||||
Layout
|
||||
------
|
||||
|
||||
A subscription file is comprised of YAML keys and values. Keys can be either
|
||||
|
||||
- a preset
|
||||
|
|
@ -52,32 +55,33 @@ All three types of keys are used for the following:
|
|||
- ``= News`` - an override value for genre
|
||||
- ``Breaking News``, ``BBC News`` - The subscription names
|
||||
|
||||
The lowest level, most indented keys should always be the subscription name.
|
||||
It is good practice to put subscription names in quotes to differentiate
|
||||
between preset names and subscription names.
|
||||
The lowest level, most indented keys should always be the subscription name. It is good
|
||||
practice to put subscription names in quotes to differentiate between preset names and
|
||||
subscription names.
|
||||
|
||||
Values should always be the subscription itself. The simplest form is
|
||||
just the URL. Further sections will show more exotic examples that go beyond
|
||||
a single URL.
|
||||
Values should always be the subscription itself. The simplest form is just the
|
||||
URL. Further sections will show more exotic examples that go beyond a single URL.
|
||||
|
||||
|
||||
Inheritance
|
||||
-----------
|
||||
A subscription inherits every key above it. In the above example,
|
||||
both ``Breaking News`` and ``BBC News`` inherits the ``Jellyfin TV Show by Date``
|
||||
preset and the ``= News`` override value.
|
||||
|
||||
A subscription inherits every key above it. In the above example, both ``Breaking News``
|
||||
and ``BBC News`` inherits the ``Jellyfin TV Show by Date`` preset and the ``= News``
|
||||
override value.
|
||||
|
||||
.. note::
|
||||
|
||||
There are no limits or boundaries on how one structures
|
||||
their presets. This flexibility is intended for subscription authors
|
||||
to organize their downloads as they see fit.
|
||||
There are no limits or boundaries on how one structures their presets. This
|
||||
flexibility is intended for subscription authors to organize their downloads as they
|
||||
see fit.
|
||||
|
||||
|
||||
Multi Keys
|
||||
----------
|
||||
Subscription keys support pipe syntax, or ``|``, which allows multiple
|
||||
keys to be defined on a single line. The following is equivalent to the above
|
||||
example:
|
||||
|
||||
Subscription keys support pipe syntax, or ``|``, which allows multiple keys to be
|
||||
defined on a single line. The following is equivalent to the above example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -85,16 +89,16 @@ example:
|
|||
"Breaking News": "https://www.youtube.com/@SomeBreakingNews"
|
||||
"BBC News": "https://www.youtube.com/@BBCNews"
|
||||
|
||||
|
||||
Override Mode
|
||||
-------------
|
||||
Often times, it is convenient to set multiple override values for
|
||||
a single subscription. We can put a preset in *override mode* by
|
||||
using tilda syntax, or ``~``.
|
||||
|
||||
Often times, it is convenient to set multiple override values for a single
|
||||
subscription. We can put a preset in *override mode* by using tilda syntax, or ``~``.
|
||||
|
||||
Suppose we want to apply the :ref:`Only Recent <prebuilt_presets/helpers:Only Recent>`
|
||||
preset to the above examples. But for ``BBC News`` specifically, we want to
|
||||
set the date range to be different than the default ``2months`` value to
|
||||
``2weeks``.
|
||||
preset to the above examples. But for ``BBC News`` specifically, we want to set the date
|
||||
range to be different than the default ``2months`` value to ``2weeks``.
|
||||
|
||||
We can change it as follows:
|
||||
|
||||
|
|
@ -109,13 +113,14 @@ We can change it as follows:
|
|||
|
||||
.. important::
|
||||
|
||||
When using override mode, we need to set the ``url``
|
||||
variable since we are no longer using the simplified
|
||||
*subscription_value*. For more info on how this works,
|
||||
read about :ref:`subscription variables <config_reference/scripting/static_variables:Subscription Variables>`.
|
||||
When using override mode, we need to set the ``url`` variable since we are no longer
|
||||
using the simplified *subscription_value*. For more info on how this works, read about
|
||||
:ref:`subscription variables <config_reference/scripting/static_variables:Subscription
|
||||
Variables>`.
|
||||
|
||||
|
||||
Map Mode
|
||||
--------
|
||||
Map mode is for highly advanced presets that benefit
|
||||
from a more complex subscription definition. TODO: Show music video
|
||||
example here.
|
||||
|
||||
Map mode is for highly advanced presets that benefit from a more complex subscription
|
||||
definition. TODO: Show music video example here.
|
||||
|
|
|
|||
|
|
@ -1,14 +1,16 @@
|
|||
Deprecation Notices
|
||||
===================
|
||||
|
||||
|
||||
Sep 2024
|
||||
--------
|
||||
|
||||
regex plugin
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Regex plugin has been removed in favor of scripting. The function
|
||||
:ref:`config_reference/scripting/scripting_functions:regex_capture_many`
|
||||
has been created to replicate the plugin's behavior. See the following converted example:
|
||||
:ref:`config_reference/scripting/scripting_functions:regex_capture_many` has been
|
||||
created to replicate the plugin's behavior. See the following converted example:
|
||||
|
||||
.. code-block:: yaml
|
||||
: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)}"
|
||||
|
||||
|
||||
Oct 2023
|
||||
--------
|
||||
|
||||
subscription preset and value
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The use of ``__value__`` will go away in Dec 2023 in favor of the method found in
|
||||
:ref:`config_reference/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
|
||||
---------
|
||||
|
|
@ -54,8 +59,9 @@ July 2023
|
|||
music_tags
|
||||
~~~~~~~~~~
|
||||
|
||||
Music tags are getting simplified. ``tags`` will now reside directly under music_tags, and
|
||||
``embed_thumbnail`` is getting moved to its own plugin (supports video files as well). Convert from:
|
||||
Music tags are getting simplified. ``tags`` will now reside directly under music_tags,
|
||||
and ``embed_thumbnail`` is getting moved to its own plugin (supports video files as
|
||||
well). Convert from:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -79,8 +85,8 @@ The old format will be removed in October 2023.
|
|||
video_tags
|
||||
~~~~~~~~~~
|
||||
|
||||
Video tags are getting simplified as well. ``tags`` will now reside directly under video_tags.
|
||||
Convert from:
|
||||
Video tags are getting simplified as well. ``tags`` will now reside directly under
|
||||
video_tags. Convert from:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
|
|||
|
|
@ -2,20 +2,23 @@
|
|||
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
|
||||
:depth: 3
|
||||
|
||||
|
||||
How do I...
|
||||
-----------
|
||||
|
||||
...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``
|
||||
override variable. This variable is used to set 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:
|
||||
The :ref:`config_reference/prebuilt_presets/tv_show:TV Show` presets by default include
|
||||
the upload date in the ``episode_title`` override variable. This variable is used to set
|
||||
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
|
||||
|
||||
|
|
@ -31,16 +34,24 @@ If you need support, you can:
|
|||
|
||||
* `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?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -50,7 +61,8 @@ See `yt-dl's recommended way <https://github.com/ytdl-org/youtube-dl#how-do-i-pa
|
|||
...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?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -65,7 +77,8 @@ See the prebuilt preset :doc:`Filter Keywords </prebuilt_presets/helpers>`.
|
|||
...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
|
||||
|
||||
|
|
@ -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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The :ref:`config_reference/prebuilt_presets/tv_show:TV Show` presets by default downloads images corresponding to show and each episode.
|
||||
This can be prevented by overriding following variables:
|
||||
The :ref:`config_reference/prebuilt_presets/tv_show:TV Show` presets by default
|
||||
downloads images corresponding to show and each episode. This can be prevented by
|
||||
overriding following variables:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -88,10 +102,11 @@ This can be prevented by overriding following variables:
|
|||
...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
|
||||
for use in your media player. Consider the example:
|
||||
ytdl-sub offers a range of functions that can be used to parse a subset of a title for
|
||||
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
|
||||
``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
|
||||
: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":
|
||||
url: "https://www.youtube.com/@novapbs"
|
||||
|
|
@ -132,10 +149,10 @@ There are several solutions using ytdl-sub's scripting capabilities to override
|
|||
episode_title: >-
|
||||
{ %array_at( captured_episode_title, 1 ) }
|
||||
|
||||
There is no single solution to this problem - it will vary case-by-case. See
|
||||
our full suite of
|
||||
:ref:`scripting functions <config_reference/scripting/scripting_functions:Scripting Functions>`
|
||||
to create your own clever scraping mechanisms.
|
||||
There is no single solution to this problem - it will vary case-by-case. See our full
|
||||
suite of :ref:`scripting functions
|
||||
<config_reference/scripting/scripting_functions:Scripting Functions>` to create your own
|
||||
clever scraping mechanisms.
|
||||
|
||||
There is a bug where...
|
||||
-----------------------
|
||||
|
|
@ -143,33 +160,39 @@ There is a bug where...
|
|||
..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.
|
||||
A good strategy is to see if your same issue has been reported in
|
||||
`yt-dlp's GitHub issues <https://github.com/yt-dlp/yt-dlp/issues>`_, and search to see if there is a comment including
|
||||
a fix or workaround.
|
||||
Any logs showing failed downloads, 403 errors, signs of throttles, etc, are a yt-dlp
|
||||
issue. A good strategy is to see if your same issue has been reported in `yt-dlp's
|
||||
GitHub issues <https://github.com/yt-dlp/yt-dlp/issues>`_, and search to see if there is
|
||||
a comment including a fix or workaround.
|
||||
|
||||
If it looks like a ytdl-sub issue, run with ``--log-level debug`` and make a
|
||||
`GitHub issue in ytdl-sub <https://github.com/jmbannon/ytdl-sub/issues>`_
|
||||
containing these logs and other relevant info.
|
||||
If it looks like a ytdl-sub issue, run with ``--log-level debug`` and make a `GitHub
|
||||
issue in ytdl-sub <https://github.com/jmbannon/ytdl-sub/issues>`_ containing these logs
|
||||
and other relevant info.
|
||||
|
||||
...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
|
||||
|
||||
ytdl_options:
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
.. 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
|
||||
- **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
|
||||
- **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
|
||||
: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.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,10 @@
|
|||
Development and Contributing
|
||||
============================
|
||||
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
- python >= 3.10
|
||||
- ffmpeg/ffprobe 4.4.5 (test checksums rely on this version)
|
||||
- make
|
||||
|
|
@ -20,15 +22,18 @@ Local Install
|
|||
|
||||
pip install -e .\[test,lint,docs\]
|
||||
|
||||
|
||||
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
|
||||
|
||||
make lint
|
||||
|
||||
|
||||
Adding Documentation
|
||||
--------------------
|
||||
|
||||
|
|
@ -36,12 +41,14 @@ Docs can be found in ``ytdl-sub/docs/source/``, and are built using the command:
|
|||
|
||||
|
||||
.. 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
|
||||
|
||||
Some of the documentation is built using doc-strings from the python source code. The above
|
||||
command will rebuild those as well.
|
||||
Some of the documentation is built using doc-strings from the python source code. The
|
||||
above command will rebuild those as well.
|
||||
|
||||
|
||||
Testing
|
||||
-------
|
||||
|
|
@ -55,26 +62,31 @@ If integration tests are failing, ensure...
|
|||
- you are developing on Linux or Mac (have not tested windows yet)
|
||||
- your local ``ytdl-sub`` dependencies are up-to-date
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
Debugging
|
||||
---------
|
||||
|
||||
Debug Logs
|
||||
^^^^^^^^^^^^^^^
|
||||
^^^^^^^^^^
|
||||
|
||||
Run with ``--log-level debug`` to show all debug logs when running ytdl-sub.
|
||||
|
||||
|
||||
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``.
|
||||
|
||||
Running the test ``e2e.test_debug_repro.TestReproduce.test_debug_log_repro``
|
||||
will fully reproduce that subscription in order to debug it.
|
||||
Running the test ``e2e.test_debug_repro.TestReproduce.test_debug_log_repro`` will fully
|
||||
reproduce that subscription in order to debug it.
|
||||
|
|
|
|||
|
|
@ -9,6 +9,7 @@ Automating Downloads
|
|||
|
||||
.. _cron scheduling syntax: https://crontab.guru/#0_*/6_*_*_*
|
||||
|
||||
|
||||
.. _docker-unraid-setup:
|
||||
|
||||
Docker and Unraid
|
||||
|
|
@ -26,11 +27,13 @@ ENV variables to your docker setup.
|
|||
- 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_RUN_ON_START`` toggles whether to run your cron script on container start in addition to the cron schedule.
|
||||
- ``CRON_SCHEDULE`` follows the standard `cron scheduling syntax`_. The above value will
|
||||
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``.
|
||||
Cron logs should show when viewing the Docker logs.
|
||||
The cron script will reside in the main directory with the file name ``cron``. Cron
|
||||
logs should show when viewing the Docker logs.
|
||||
|
||||
|
||||
.. _linux-setup:
|
||||
|
|
@ -45,13 +48,13 @@ Must configure crontab manually, like so:
|
|||
0 */6 * * * /config/run_cron
|
||||
|
||||
|
||||
|
||||
|
||||
.. _windows-setup:
|
||||
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -3,10 +3,11 @@ Basic Configuration
|
|||
|
||||
A configuration file serves two purposes:
|
||||
|
||||
1. Set advanced functionality that is not specifiable in a subscription file, such as working directory location. These
|
||||
are set underneath ``configuration``.
|
||||
2. Create custom presets, which can drastically simplify your subscription file. These are defined underneath ``presets``.
|
||||
Presets are intended to be applicable and reusable across multiple subscriptions.
|
||||
1. Set advanced functionality that is not specifiable in a subscription file, such as
|
||||
working directory location. These are set underneath ``configuration``.
|
||||
2. Create custom presets, which can drastically simplify your subscription file. These
|
||||
are defined underneath ``presets``. Presets are intended to be applicable and
|
||||
reusable across multiple subscriptions.
|
||||
|
||||
Below is a common configuration:
|
||||
|
||||
|
|
@ -43,10 +44,12 @@ Below is a common configuration:
|
|||
- "TV Show"
|
||||
- "Only Recent"
|
||||
|
||||
|
||||
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
|
||||
:lineno-start: 1
|
||||
|
|
@ -54,10 +57,12 @@ The :ref:`configuration <config_reference/config_yaml:Configuration File>` secti
|
|||
configuration:
|
||||
working_directory: '/mnt/ssd/.ytdl-sub-downloads'
|
||||
|
||||
|
||||
Preset Section
|
||||
--------------
|
||||
|
||||
Underneath ``presets``, we define two custom presets with the names ``TV Show`` and ``TV Show Only Recent``.
|
||||
Underneath ``presets``, we define two custom presets with the names ``TV Show`` and ``TV
|
||||
Show Only Recent``.
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
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:
|
||||
|
||||
1. ``preset`` section, which can inherit :ref:`prebuilt presets <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>`
|
||||
or other presets defined in your config.
|
||||
1. ``preset`` section, which can inherit :ref:`prebuilt presets
|
||||
<config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` or other presets
|
||||
defined in your config.
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -106,14 +115,16 @@ Inheriting Presets
|
|||
- "Jellyfin TV Show by Date"
|
||||
- "Max 1080p"
|
||||
|
||||
The following snippet shows that the ``TV Show`` preset will inherit all properties
|
||||
of the prebuilt presets ``Jellyfin TV Show by Date`` and ``Max 1080p`` in that order.
|
||||
The following snippet shows that the ``TV Show`` preset will inherit all properties of
|
||||
the prebuilt presets ``Jellyfin TV Show by Date`` and ``Max 1080p`` in that order.
|
||||
|
||||
Order matters for preset inheritance. Bottom-most presets will override ones above them.
|
||||
|
||||
It is highly advisable to use :ref:`prebuilt presets <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` as
|
||||
a starting point for custom preset building, as they do the work of preset building to ensure things show as expected
|
||||
in their respective media players. Read on to see how to override prebuilt preset specifics such as title.
|
||||
It is highly advisable to use :ref:`prebuilt presets
|
||||
<config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` as a starting point
|
||||
for custom preset building, as they do the work of preset building to ensure things show
|
||||
as expected in their respective media players. Read on to see how to override prebuilt
|
||||
preset specifics such as title.
|
||||
|
||||
Defining Plugins
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
|
@ -134,17 +145,18 @@ Defining Plugins
|
|||
min: 10
|
||||
max: 36
|
||||
|
||||
Our ``TV Show`` sets two plugins, :ref:`throttle_protection <config_reference/plugins:throttle_protection>` and
|
||||
:ref:`embed_thumbnail <config_reference/plugins:embed_thumbnail>`. Each plugin's documentation shows the respective
|
||||
fields that they support.
|
||||
Our ``TV Show`` sets two plugins, :ref:`throttle_protection
|
||||
<config_reference/plugins:throttle_protection>` and :ref:`embed_thumbnail
|
||||
<config_reference/plugins:embed_thumbnail>`. Each plugin's documentation shows the
|
||||
respective fields that they support.
|
||||
|
||||
If an inherited preset defines the same plugin, the custom preset will use 'merge-and-append' strategy to
|
||||
combine their definitions. What this means is:
|
||||
|
||||
1. If the field is a map (i.e. has sub-params like ``sleep_per_download_s`` above) or array, it will try to merge them
|
||||
2. If both the inherited preset and custom preset set the same exact field and value (i.e. ``embed_thumbnail``)
|
||||
the custom preset will overwrite it
|
||||
If an inherited preset defines the same plugin, the custom preset will use
|
||||
'merge-and-append' strategy to combine their definitions. What this means is:
|
||||
|
||||
1. If the field is a map (i.e. has sub-params like ``sleep_per_download_s`` above) or
|
||||
array, it will try to merge them
|
||||
2. If both the inherited preset and custom preset set the same exact field and value
|
||||
(i.e. ``embed_thumbnail``) the custom preset will overwrite it
|
||||
|
||||
Setting Override Variables
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -155,27 +167,31 @@ Setting Override Variables
|
|||
overrides:
|
||||
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.
|
||||
When defining variables in a preset, it is best practice to define them with the intention that
|
||||
It is important to remember that individual subscriptions can override specific override
|
||||
variables. When defining variables in a preset, it is best practice to define them with
|
||||
the intention that
|
||||
|
||||
1. All subscriptions will use its value them
|
||||
2. Use them as placeholders to perform other logic, then have subscriptions or child presets
|
||||
define their specific value
|
||||
2. Use them as placeholders to perform other logic, then have subscriptions or child
|
||||
presets define their specific value
|
||||
|
||||
For simplicity, we'll focus on (1) for now. The above snippet sets the ``tv_show_directory``
|
||||
variable to a file path. This variable name is specific to the prebuilt TV show presets.
|
||||
For simplicity, we'll focus on (1) for now. The above snippet sets the
|
||||
``tv_show_directory`` variable to a file path. This variable name is specific to the
|
||||
prebuilt TV show presets.
|
||||
|
||||
See the :ref:`prebuilt preset reference <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>`
|
||||
to see all available variables that are overridable.
|
||||
See the :ref:`prebuilt preset reference
|
||||
<config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` to see all
|
||||
available variables that are overridable.
|
||||
|
||||
|
||||
Using Custom Presets in Subscriptions
|
||||
--------------------------------------
|
||||
|
||||
Subscription files can use custom presets just like any other prebuilt preset.
|
||||
Below shows a complete subscription file using the above two custom presets.
|
||||
Subscription files can use custom presets just like any other prebuilt preset. Below
|
||||
shows a complete subscription file using the above two custom presets.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -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
|
||||
like in prior examples. This is because our custom presets do the work of defining it.
|
||||
|
||||
|
||||
Reference Custom Config in the CLI
|
||||
----------------------------------
|
||||
|
||||
Be sure to tell ytdl-sub to use your config by using the argument
|
||||
``--config /path/to/config.yaml``.
|
||||
Be sure to tell ytdl-sub to use your config by using the argument ``--config
|
||||
/path/to/config.yaml``.
|
||||
|
||||
If you run ytdl-sub in the same directory, and the config file is named ``config.yaml``, it will
|
||||
use it by default.
|
||||
If you run ytdl-sub in the same directory, and the config file is named ``config.yaml``,
|
||||
it will use it by default.
|
||||
|
|
|
|||
|
|
@ -2,11 +2,13 @@ Initial Download
|
|||
================
|
||||
|
||||
Once you have a ``subscriptions.yaml`` file created, you can perform your first
|
||||
download. Access ``ytdl-sub``, navigate to the directory containing your ``subscriptions.yaml``
|
||||
file.
|
||||
download. Access ``ytdl-sub``, navigate to the directory containing your
|
||||
``subscriptions.yaml`` file.
|
||||
|
||||
|
||||
Dry Run
|
||||
-------
|
||||
|
||||
Performing a dry run is important when applying any change to your subscriptions to
|
||||
ensure output looks as expected. Dry runs will pull metadata to *simulate* a download
|
||||
without actually downloading the media file.
|
||||
|
|
@ -15,11 +17,12 @@ without actually downloading the media file.
|
|||
|
||||
ytdl-sub --dry-run sub subscriptions.yaml
|
||||
|
||||
|
||||
Faster Iteration Cycle
|
||||
----------------------
|
||||
Testing subscriptions can take quite some time to perform a full download.
|
||||
This can be speed up by applying an override via command-line to set max number
|
||||
of downloads.
|
||||
|
||||
Testing subscriptions can take quite some time to perform a full download. This can be
|
||||
speed up by applying an override via command-line to set max number of downloads.
|
||||
|
||||
.. 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
|
||||
|
||||
|
||||
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
|
||||
|
||||
ytdl-sub sub subscriptions.yaml
|
||||
|
||||
Multiple subscription file names can be provided to perform a download on all of them. A single file
|
||||
named ``subscriptions.yaml`` does not require a file name specification since it will
|
||||
look for that file name by default, making the following command valid.
|
||||
Multiple subscription file names can be provided to perform a download on all of them. A
|
||||
single file named ``subscriptions.yaml`` does not require a file name specification
|
||||
since it will look for that file name by default, making the following command valid.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
|
|
|||
|
|
@ -42,17 +42,18 @@ Let's break this down:
|
|||
music_directory: "/music"
|
||||
|
||||
|
||||
The first :ref:`__preset__ <config_reference/subscription_yaml:File Preset>` section is where we
|
||||
can set modifications that apply to every subscription in this file.
|
||||
The first :ref:`__preset__ <config_reference/subscription_yaml:File Preset>` section is
|
||||
where we can set modifications that apply to every subscription in this file.
|
||||
|
||||
This snippet specifically adds two :ref:`override <config_reference/plugins:Overrides>` variables,
|
||||
which are used by the presets below.
|
||||
This snippet specifically adds two :ref:`override <config_reference/plugins:Overrides>`
|
||||
variables, which are used by the presets below.
|
||||
|
||||
.. note::
|
||||
It is tempting to put any override underneath ``overrides``. Keep in mind that this section
|
||||
is solely for variable defining. Other :ref:`plugins <config_reference/plugins:Plugins>` need to be
|
||||
set at the same indentation level as ``overrides``, not within it.
|
||||
|
||||
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:
|
||||
|
||||
On line 11, we set the key to ``Jellyfin TV Show by Date``. This is a
|
||||
:ref:`prebuilt preset <prebuilt_presets/index:prebuilt presets>` that configures
|
||||
subscriptions to look like TV shows in the Jellyfin media player (can be changed to
|
||||
one of the presets outlined in the comment above). Setting it as a YAML key implies that all
|
||||
subscriptions underneath it will *inherit* this preset.
|
||||
On line 11, we set the key to ``Jellyfin TV Show by Date``. This is a :ref:`prebuilt
|
||||
preset <prebuilt_presets/index:prebuilt presets>` that configures subscriptions to look
|
||||
like TV shows in the Jellyfin media player (can be changed to one of the presets
|
||||
outlined in the comment above). Setting it as a YAML key implies that all subscriptions
|
||||
underneath it will *inherit* this preset.
|
||||
|
||||
This preset expects the variable ``tv_show_directory`` to be set, which we do above.
|
||||
|
||||
|
|
@ -77,14 +78,14 @@ This preset expects the variable ``tv_show_directory`` to be set, which we do ab
|
|||
Jellyfin TV Show by Date:
|
||||
= Documentaries:
|
||||
|
||||
Line 12 sets the key to ``= Documentaries``. When keys are prefixed with ``=``, it means we are
|
||||
setting the genre. This value will get written to the respective metadata tags for both TV show
|
||||
and music presets.
|
||||
Line 12 sets the key to ``= Documentaries``. When keys are prefixed with ``=``, it means
|
||||
we are setting the genre. This value will get written to the respective metadata tags
|
||||
for both TV show and music presets.
|
||||
|
||||
Behind the scenes, this sets the override variable ``subscription_indent_1``. Further documentation
|
||||
can be found here for
|
||||
:ref:`subscription syntax <config_reference/subscription_yaml:Subscription File>` and
|
||||
:ref:`subscription variables <config_reference/scripting/static_variables:Subscription Variables>`.
|
||||
Behind the scenes, this sets the override variable ``subscription_indent_1``. Further
|
||||
documentation can be found here for :ref:`subscription syntax
|
||||
<config_reference/subscription_yaml:Subscription File>` and :ref:`subscription variables
|
||||
<config_reference/scripting/static_variables:Subscription Variables>`.
|
||||
|
||||
-------------------------------------
|
||||
|
||||
|
|
@ -95,12 +96,12 @@ can be found here for
|
|||
= Documentaries:
|
||||
"NOVA PBS": "https://www.youtube.com/@novapbs"
|
||||
|
||||
Line 13 is where we define our first subscription. We set the subscription name to ``NOVA PBS``,
|
||||
and the subscription value to ``https://www.youtube.com/@novapbs``.
|
||||
Line 13 is where we define our first subscription. We set the subscription name to
|
||||
``NOVA PBS``, and the subscription value to ``https://www.youtube.com/@novapbs``.
|
||||
|
||||
To see how presets ingest subscription definitions, refer to the
|
||||
:ref:`preset references <config_reference/prebuilt_presets/tv_show:TV Show>`,
|
||||
we can see that ``{subscription_name}`` is used to set the ``tv_show_name`` variable.
|
||||
To see how presets ingest subscription definitions, refer to the :ref:`preset references
|
||||
<config_reference/prebuilt_presets/tv_show:TV Show>`, we can see that
|
||||
``{subscription_name}`` is used to set the ``tv_show_name`` variable.
|
||||
|
||||
-------------------------------------
|
||||
|
||||
|
|
@ -114,13 +115,14 @@ we can see that ``{subscription_name}`` is used to set the ``tv_show_name`` vari
|
|||
= Kids | = TV-Y:
|
||||
"Jake Trains": "https://www.youtube.com/@JakeTrains"
|
||||
|
||||
Line 15 underneath ``Jellyfin TV Show by Date``, but at the same level as ``= Documentaries``.
|
||||
This means we'll inherit the TV show preset, but not the documentaries indent variable. We instead
|
||||
set the indent variables to ``= Kids | = TV-Y``. This sets two indent variables. We can set
|
||||
multiple presets and/or indent variables on the same key by using ``|`` as a separator.
|
||||
Line 15 underneath ``Jellyfin TV Show by Date``, but at the same level as ``=
|
||||
Documentaries``. This means we'll inherit the TV show preset, but not the documentaries
|
||||
indent variable. We instead set the indent variables to ``= Kids | = TV-Y``. This sets
|
||||
two indent variables. We can set multiple presets and/or indent variables on the same
|
||||
key by using ``|`` as a separator.
|
||||
|
||||
Referring to the
|
||||
:ref:`TV show preset reference <config_reference/prebuilt_presets/tv_show:TV Show>`, the first
|
||||
two indent variables map to the TV show genre and TV show content rating.
|
||||
Referring to the :ref:`TV show preset reference
|
||||
<config_reference/prebuilt_presets/tv_show:TV Show>`, the first two indent variables map
|
||||
to the TV show genre and TV show content rating.
|
||||
|
||||
The above info should be enough to understand the rest of the subscription file.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
Getting Started
|
||||
===============
|
||||
|
||||
|
||||
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/
|
||||
|
||||
|
||||
|
||||
Architecture
|
||||
------------
|
||||
|
||||
For most users, ``ytdl-sub`` works as follows:
|
||||
|
||||
Subscriptions use presets
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
|
|
@ -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.
|
||||
|
||||
Presets configure plugins
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
:doc:`A preset <../../prebuilt_presets/index>` is effectively a set of plugin
|
||||
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.
|
||||
|
||||
Plugins do the work
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``ytdl-sub`` applies the plugins that the presets configure when it downloads a
|
||||
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.
|
||||
|
||||
Presets and subscriptions accept overrides
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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 presets for just that subscription.
|
||||
|
||||
Subscriptions are grouped by indentation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Most subscriptions have more in common with each other than not. Thus, defining the presets
|
||||
and overrides for each subscription would result in mostly repetition and would multiply
|
||||
the burden of management for the user. The more subscriptions the more work.
|
||||
Most subscriptions have more in common with each other than not. Thus, defining the
|
||||
presets and overrides for each subscription would result in mostly repetition and would
|
||||
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
|
||||
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.
|
||||
|
||||
The configuration file extends pre-defined presets
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
:doc:`../../prebuilt_presets/index` provided by ``ytdl-sub``.
|
||||
|
||||
Caveats
|
||||
^^^^^^^
|
||||
~~~~~~~
|
||||
|
||||
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
|
||||
|
|
@ -118,8 +120,10 @@ is accurate and representative.
|
|||
|
||||
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::
|
||||
:maxdepth: 2
|
||||
|
|
|
|||
|
|
@ -2,13 +2,15 @@
|
|||
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
|
||||
--------------
|
||||
You can install our
|
||||
`PyPI package <https://pypi.org/project/ytdl-sub/>`_.
|
||||
Both ffmpeg and Python 3.10 or greater are required.
|
||||
|
||||
You can install our `PyPI package <https://pypi.org/project/ytdl-sub/>`_. Both ffmpeg
|
||||
and Python 3.10 or greater are required.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -17,10 +19,13 @@ Both ffmpeg and Python 3.10 or greater are required.
|
|||
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
|
||||
--------------
|
||||
|
||||
With a Python 3.10 virtual environment, you can clone and install the repo.
|
||||
|
||||
.. code-block:: bash
|
||||
|
|
@ -32,12 +37,13 @@ With a Python 3.10 virtual environment, you can clone and install the repo.
|
|||
|
||||
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
|
||||
|
||||
git clone https://github.com/jmbannon/ytdl-sub.git
|
||||
cd ytdl-sub
|
||||
|
||||
make docker
|
||||
make docker
|
||||
|
|
|
|||
|
|
@ -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
|
||||
automate running ``ytdl-sub`` in a container running either variant.
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
Headless Image
|
||||
--------------
|
||||
|
||||
|
|
@ -36,6 +38,7 @@ For example::
|
|||
|
||||
$ docker compose run --rm --user="${PUID}:${PGID}" --entrypoint="ytdl-sub" ytdl-sub sub
|
||||
|
||||
|
||||
Install with Docker Compose
|
||||
---------------------------
|
||||
|
||||
|
|
@ -84,6 +87,7 @@ directory such as:
|
|||
# devices:
|
||||
# - capabilities: ["gpu"]
|
||||
|
||||
|
||||
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
|
||||
details.
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
Install by Platform
|
||||
===================
|
||||
|
||||
``ytdl-sub`` can be installed on the following platforms.
|
||||
|
||||
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::
|
||||
|
||||
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`
|
||||
|
||||
|
|
@ -20,9 +22,8 @@ All installations require a 64-bit CPU. 32-bit is not supported.
|
|||
|
||||
: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::
|
||||
:hidden:
|
||||
|
|
|
|||
|
|
@ -2,8 +2,8 @@
|
|||
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::
|
||||
|
||||
|
|
@ -15,7 +15,8 @@ Linux
|
|||
chmod +x ytdl-sub
|
||||
./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
|
||||
|
||||
|
|
@ -36,7 +37,8 @@ Linux
|
|||
chmod +x ytdl-sub
|
||||
./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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,16 +1,29 @@
|
|||
======
|
||||
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 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``.
|
||||
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
|
||||
:alt: The Unraid community app plugin GUI, with an arrow pointing at the "Console" option in the dropdown after selecting ytdl-sub-gui
|
||||
.. 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
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
=======
|
||||
Windows
|
||||
--------------
|
||||
=======
|
||||
|
||||
From powershell, run:
|
||||
|
||||
.. code-block:: powershell
|
||||
|
|
@ -12,4 +14,4 @@ From powershell, run:
|
|||
|
||||
# Download ytdl-sub
|
||||
curl.exe -L -o ytdl-sub.exe https://github.com/jmbannon/ytdl-sub/releases/latest/download/ytdl-sub.exe
|
||||
ytdl-sub.exe -h
|
||||
ytdl-sub.exe -h
|
||||
|
|
|
|||
|
|
@ -6,11 +6,13 @@ Helper Presets
|
|||
|
||||
See how to apply helper presets :doc:`here </prebuilt_presets/index>`
|
||||
|
||||
|
||||
Only Recent
|
||||
-----------
|
||||
|
||||
To only download a recent number of videos, apply the ``Only Recent`` preset. Once a video's
|
||||
upload date is outside of the range, or you hit max files, older videos will be deleted automatically.
|
||||
To only download a recent number of videos, apply the ``Only Recent`` preset. Once a
|
||||
video's upload date is outside of the range, or you hit max files, older videos will be
|
||||
deleted automatically.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -31,9 +33,12 @@ To prevent deletion of files, use the preset ``Only Recent Archive`` instead.
|
|||
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:
|
||||
|
||||
|
|
@ -71,6 +76,7 @@ Supports the following override variables:
|
|||
- "maple leafs"
|
||||
- "highlights"
|
||||
|
||||
|
||||
Filter Duration
|
||||
---------------
|
||||
|
||||
|
|
@ -100,17 +106,19 @@ Supports the following override variables:
|
|||
url: "https://www.youtube.com/@NHL"
|
||||
filter_duration_max_s: 180 # Only get highlight videos less than 3m long
|
||||
|
||||
|
||||
Chunk Downloads
|
||||
---------------
|
||||
|
||||
If you are archiving a large channel, ``ytdl-sub`` will try pulling each video's metadata from newest to oldest before
|
||||
starting any downloads. It is a long process and not ideal. A better method is to chunk the process by using the
|
||||
following preset:
|
||||
If you are archiving a large channel, ``ytdl-sub`` will try pulling each video's
|
||||
metadata from newest to oldest before starting any downloads. It is a long process and
|
||||
not ideal. A better method is to chunk the process by using the following preset:
|
||||
|
||||
``Chunk Downloads``
|
||||
|
||||
It will download videos starting from the oldest one, and only download 20 at a time by default. You can
|
||||
change this number by setting the override variable ``chunk_max_downloads``.
|
||||
It will download videos starting from the oldest one, and only download 20 at a time by
|
||||
default. You can change this number by setting the override variable
|
||||
``chunk_max_downloads``.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -129,5 +137,6 @@ change this number by setting the override variable ``chunk_max_downloads``.
|
|||
= Documentaries:
|
||||
"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
|
||||
oldest again, and stop once it reaches a video that has already been downloaded.
|
||||
Once the entire channel is downloaded, remove the usage of this preset. It will then
|
||||
pull metadata from newest to oldest again, and stop once it reaches a video that has
|
||||
already been downloaded.
|
||||
|
|
|
|||
|
|
@ -7,11 +7,13 @@ media in various players.
|
|||
|
||||
.. hint::
|
||||
|
||||
Apply multiple presets to your subscriptions using pipes. Pipes can define multiple presets and values
|
||||
on the same line to apply to all subscriptions nested below them.
|
||||
Apply multiple presets to your subscriptions using pipes. Pipes can define multiple
|
||||
presets and values on the same line to apply to all subscriptions nested below them.
|
||||
|
||||
.. 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:
|
||||
|
||||
|
|
@ -22,9 +24,8 @@ media in various players.
|
|||
= Documentaries:
|
||||
"Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"
|
||||
|
||||
|
||||
For advanced users, you can review the prebuilt preset
|
||||
definitions :doc:`here </config_reference/prebuilt_presets/index>`.
|
||||
For advanced users, you can review the prebuilt preset definitions :doc:`here
|
||||
</config_reference/prebuilt_presets/index>`.
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
|
|
@ -33,4 +34,4 @@ definitions :doc:`here </config_reference/prebuilt_presets/index>`.
|
|||
music
|
||||
music_videos
|
||||
media_quality
|
||||
helpers
|
||||
helpers
|
||||
|
|
|
|||
|
|
@ -6,8 +6,10 @@ Media Quality Presets
|
|||
|
||||
See how to apply media quality presets :doc:`here </prebuilt_presets/index>`
|
||||
|
||||
|
||||
Video
|
||||
-----
|
||||
|
||||
The following presets set video quality specifications to yt-dlp.
|
||||
|
||||
- ``Max Video Quality``
|
||||
|
|
@ -17,10 +19,12 @@ The following presets set video quality specifications to yt-dlp.
|
|||
- ``Max 720p``
|
||||
- ``Max 480p``
|
||||
|
||||
|
||||
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 MP3 Quality``
|
||||
|
|
|
|||
|
|
@ -2,21 +2,21 @@
|
|||
Music Presets
|
||||
=============
|
||||
|
||||
Music downloadable by yt-dlp comes in many flavors. ``ytdl-sub`` offers a suite
|
||||
of various presets for handling some of the most popular forms of uploaded music
|
||||
content.
|
||||
Music downloadable by yt-dlp comes in many flavors. ``ytdl-sub`` offers a suite of
|
||||
various presets for handling some of the most popular forms of uploaded music content.
|
||||
|
||||
.. hint::
|
||||
|
||||
The subscription *value* (denoted by =) will set the genre tag for all music scraped under its key
|
||||
for all music presets.
|
||||
The subscription *value* (denoted by =) will set the genre tag for all music scraped
|
||||
under its key for all music presets.
|
||||
|
||||
|
||||
YouTube Releases
|
||||
----------------
|
||||
|
||||
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
|
||||
scrape this *playlist of playlists*.
|
||||
their channel named "Releases", or "Albums and Singles". The ``YouTube Releases`` preset
|
||||
aims to scrape this *playlist of playlists*.
|
||||
|
||||
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"
|
||||
"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
|
||||
of an array, like so:
|
||||
If you are only interested in a subset of albums, you can provide their playlists as
|
||||
separate values in the form of an array, like so:
|
||||
|
||||
.. 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_nhuvjuZOO3yLIWCbQzbiWfyzkGapSIuYw" # Late Night Thelonious Monk
|
||||
|
||||
|
||||
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
|
||||
it by the chapters to form an album.
|
||||
|
||||
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 it by the chapters to form an album.
|
||||
|
||||
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:
|
||||
"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
|
||||
of an array, like so:
|
||||
If you are only interested in a subset of albums, you can provide their video as
|
||||
separate values in the form of an array, like so:
|
||||
|
||||
.. 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=w0XebCwSpKI" # Study Buddy ~ video game lofi mix
|
||||
|
||||
|
||||
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.
|
||||
It will attempt to group tracks into albums before falling back to single format.
|
||||
|
||||
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. It will attempt to group tracks into albums before falling back to
|
||||
single format.
|
||||
|
||||
.. 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"
|
||||
"Earmake": "https://soundcloud.com/earmake"
|
||||
|
||||
|
||||
Bandcamp
|
||||
--------
|
||||
|
||||
Bandcamp albums and singles can be scraped using the ``Bandcamp`` preset.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
|
|||
|
|
@ -2,4 +2,4 @@
|
|||
Music Video Presets
|
||||
===================
|
||||
|
||||
WIP
|
||||
WIP
|
||||
|
|
|
|||
|
|
@ -2,45 +2,57 @@
|
|||
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:
|
||||
|
||||
Kodi
|
||||
--------
|
||||
~~~~
|
||||
|
||||
* 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
|
||||
--------
|
||||
~~~~~~~~
|
||||
|
||||
* Places any season-specific poster art in the main show folder
|
||||
* Generates NFO tags
|
||||
|
||||
Emby
|
||||
----
|
||||
~~~~
|
||||
|
||||
* Places any season-specific poster art in the main show folder
|
||||
* Generates NFO tags
|
||||
|
||||
* For named seasons, creates a ``season.nfo`` file per season
|
||||
|
||||
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
|
||||
* 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
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
Must define ``tv_show_directory``. Available presets:
|
||||
|
||||
* ``Kodi TV Show by Date``
|
||||
|
|
@ -74,9 +86,10 @@ Must define ``tv_show_directory``. Available presets:
|
|||
- "https://www.youtube.com/@rickbeato240"
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -95,12 +108,11 @@ Or for a specific preset
|
|||
tv_show_by_date_season_ordering: "upload-year-month"
|
||||
tv_show_by_date_episode_ordering: "upload-day"
|
||||
|
||||
The following are supported. Be sure the combined season + episode ordering
|
||||
include the year, month, day, i.e. upload-year + upload-month-day.
|
||||
|
||||
The following are supported. Be sure the combined season + episode ordering include the
|
||||
year, month, day, i.e. upload-year + upload-month-day.
|
||||
|
||||
Season Ordering
|
||||
~~~~~~~~~~~~~~~
|
||||
"""""""""""""""
|
||||
|
||||
``tv_show_by_date_season_ordering`` supports one of the following:
|
||||
|
||||
|
|
@ -109,23 +121,24 @@ Season Ordering
|
|||
* ``release-year``
|
||||
* ``release-year-month``
|
||||
|
||||
|
||||
Episode Ordering
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
""""""""""""""""
|
||||
|
||||
``tv_show_by_date_episode_ordering`` supports one of the following:
|
||||
|
||||
* ``upload-month-day`` (default)
|
||||
* ``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``
|
||||
* ``release-day``
|
||||
* ``release-month-day``
|
||||
* ``release-month-day-reversed``
|
||||
* ``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:
|
||||
|
||||
|
|
@ -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 Collection
|
||||
==================
|
||||
------------------
|
||||
|
||||
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
|
||||
the higher-numbered season.
|
||||
(i.e. a channel and a channel's playlist), the video will only download once and reside
|
||||
in the higher-numbered season.
|
||||
|
||||
Two main use cases of a collection are:
|
||||
1. Organize a YouTube channel TV show where Season 1 contains any video
|
||||
not in a 'season playlist', Season 2 for 'Playlist A', Season 3 for
|
||||
'Playlist B', etc.
|
||||
2. Organize one or more YouTube channels/playlists, where each season
|
||||
represents a separate channel/playlist.
|
||||
1. Organize a YouTube channel TV show where Season 1 contains any video not in a
|
||||
'season playlist', Season 2 for 'Playlist A', Season 3 for 'Playlist B', etc.
|
||||
2. Organize one or more YouTube channels/playlists, where each season represents a
|
||||
separate channel/playlist.
|
||||
|
||||
Example
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
Must define ``tv_show_directory``. Available presets:
|
||||
|
||||
* ``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"
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -198,9 +212,8 @@ Or for a specific preset
|
|||
|
||||
The following are supported.
|
||||
|
||||
|
||||
Episode Ordering
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
""""""""""""""""
|
||||
|
||||
``tv_show_collection_episode_ordering`` supports one of the following:
|
||||
|
||||
|
|
@ -210,7 +223,8 @@ Episode Ordering
|
|||
* ``release-year-month-day-reversed``
|
||||
* ``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``
|
||||
|
||||
TV Show Collection presets use upload-year-month-day as the default.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
Usage
|
||||
=======
|
||||
=====
|
||||
|
||||
.. code-block::
|
||||
|
||||
|
|
@ -7,6 +7,7 @@ Usage
|
|||
|
||||
For Windows users, it would be ``ytdl-sub.exe``
|
||||
|
||||
|
||||
General Options
|
||||
---------------
|
||||
|
||||
|
|
@ -28,16 +29,19 @@ General options must be specified before the command (i.e. ``sub``).
|
|||
-m MATCH [MATCH ...], --match MATCH [MATCH ...]
|
||||
match subscription names to one or more substrings, and only run those subscriptions
|
||||
|
||||
|
||||
Sub Options
|
||||
-----------
|
||||
|
||||
Download all subscriptions specified in each ``SUBPATH``.
|
||||
|
||||
.. code-block::
|
||||
|
||||
ytdl-sub [GENERAL OPTIONS] sub [SUBPATH ...]
|
||||
|
||||
``SUBPATH`` is one or more paths to subscription files, uses ``subscriptions.yaml`` if not provided.
|
||||
It will use the config specified by ``--config``, or ``config.yaml`` if not provided.
|
||||
``SUBPATH`` is one or more paths to subscription files, uses ``subscriptions.yaml`` if
|
||||
not provided. It will use the config specified by ``--config``, or ``config.yaml`` if
|
||||
not provided.
|
||||
|
||||
.. code-block:: text
|
||||
: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
|
||||
override all subscription config values using `dl` syntax, i.e. --dl-override='--ytdl_options.max_downloads 3'
|
||||
|
||||
|
||||
Download Options
|
||||
-----------------
|
||||
----------------
|
||||
|
||||
Download a single subscription in the form of CLI arguments.
|
||||
|
||||
.. code-block::
|
||||
|
||||
ytdl-sub [GENERAL OPTIONS] dl [SUBSCRIPTION ARGUMENTS]
|
||||
|
||||
``SUBSCRIPTION ARGUMENTS`` are exactly the same as YAML arguments, but use periods (``.``) instead
|
||||
of indents for specifying YAML from the CLI. For example, you can represent this subscription:
|
||||
``SUBSCRIPTION ARGUMENTS`` are exactly the same as YAML arguments, but use periods
|
||||
(``.``) instead of indents for specifying YAML from the CLI. For example, you can
|
||||
represent this subscription:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -76,11 +83,13 @@ Using the command:
|
|||
--overrides.tv_show_name "Rick A" \
|
||||
--overrides.url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
|
||||
|
||||
See how to shorten commands using
|
||||
`download aliases <https://ytdl-sub.readthedocs.io/en/latest/config_reference/config_yaml.html#ytdl_sub.config.config_validator.ConfigOptions.dl_aliases>`_.
|
||||
See how to shorten commands using `download aliases
|
||||
<https://ytdl-sub.readthedocs.io/en/latest/config_reference/config_yaml.html#ytdl_sub.config.config_validator.ConfigOptions.dl_aliases>`_.
|
||||
|
||||
|
||||
View Options
|
||||
-----------------
|
||||
------------
|
||||
|
||||
.. code-block::
|
||||
|
||||
ytdl-sub view [-sc] [URL]
|
||||
|
|
@ -91,5 +100,4 @@ View Options
|
|||
-sc, --split-chapters
|
||||
View source variables after splitting by chapters
|
||||
|
||||
|
||||
Preview the source variables for a given URL. Helps when creating new configs.
|
||||
|
|
|
|||
Loading…
Reference in a new issue