From 4bb96c4374b71429060659f37acef7bf57187b74 Mon Sep 17 00:00:00 2001
From: Ross Patterson <me@rpatterson.net>
Date: Tue, 19 Aug 2025 23:59:24 -0700
Subject: [PATCH] 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.
---
 docs/source/prebuilt_presets/helpers.rst      | 36 +++++++++++++++++++
 .../helpers/throttle_protection.yaml          |  9 +++--
 2 files changed, 43 insertions(+), 2 deletions(-)

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 <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
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"