docs(throttle): resolution/quality throttle asset

I also added the "wait a few hours and try again" hint, sorry I didn't think of this
when reviewing your PR. While doing that I also reformatted the `%concat(...)` arguments
to be more readable to me. Particularly to keep clear what punctuation is about argument
separation as opposed to punctuation meant to be included in the resulting string. Not a
strong preference if you don't like it.
This commit is contained in:
Ross Patterson 2025-08-19 23:59:24 -07:00
parent 775f41e195
commit 4bb96c4374
No known key found for this signature in database
GPG key ID: 2EFF7CCE6828E359
2 changed files with 43 additions and 2 deletions

View file

@ -140,3 +140,39 @@ default. You can change this number by setting the override variable
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.
_throttle_protection
--------------------
.. note::
This preset is already a base preset of those higher-level presets that require it,
so users seldom need to use it directly, for example, unless they're writing presets
from scratch.
This preset is primarily a sensible default configuration of :ref:`the
'throttle_protection' plugin <config_reference/plugins:throttle_protection>` along with
an override to disable the plugin:
.. code-block:: yaml
overrides:
# Disable throttle protection:
enable_throttle_protection: false
In addition to throttling by denying download requests, some services also throttle
downloads by only allowing downloads of the lowest resolution quality. At the time of
writing, only YouTube does this by allowing only 360p downloads when throttled. To work
around this kind of throttling, this preset includes :ref:`an assertion
<config_reference/scripting/scripting_functions:error functions>` that will stop
downloading when ``ytdl-sub`` downloads a video at 360p or lower. It supports the
following overrides:
.. code-block:: yaml
overrides:
# Disable resolution quality throttle protection:
enable_resolution_assert: false
# Change the resolution below which to assume downloading is throttled:
resolution_assert_height_gte: 481

View file

@ -58,8 +58,13 @@ presets:
%assert(
%gte( height, resolution_assert_height_gte ),
%concat(
"Entry ", title, " downloaded at a low resolution (", resolution_readable, ") which is classified as throttle. ",
"Stopping additional downloads. Disable using the override variable `enable_resolution_assert: False`"
"Entry ",
title,
" downloaded at a low resolution (",
resolution_readable,
"), you've probably been throttled. ",
"Stopping further downloads, wait a few hours and try again. ",
"Disable using the override variable `enable_resolution_assert: False`."
)
),
"false is no-op"