diff --git a/docs/source/prebuilt_presets/helpers.rst b/docs/source/prebuilt_presets/helpers.rst index 37e7bcbc..649cb841 100644 --- a/docs/source/prebuilt_presets/helpers.rst +++ b/docs/source/prebuilt_presets/helpers.rst @@ -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 ` 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 +` 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 diff --git a/src/ytdl_sub/prebuilt_presets/helpers/throttle_protection.yaml b/src/ytdl_sub/prebuilt_presets/helpers/throttle_protection.yaml index 1f68ddfb..effca714 100644 --- a/src/ytdl_sub/prebuilt_presets/helpers/throttle_protection.yaml +++ b/src/ytdl_sub/prebuilt_presets/helpers/throttle_protection.yaml @@ -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"