From 77d48bb8c43917f9b8d313ae2d7e9f3fa3e33f3e Mon Sep 17 00:00:00 2001
From: arabcoders <admin@arabcoders.org>
Date: Wed, 19 Nov 2025 16:17:15 +0300
Subject: [PATCH] Doc: update FAQ.md to include explainer for how prevent live
 premiere works.

---
 FAQ.md                       | 18 ++++++++++++++++++
 app/library/DownloadQueue.py |  5 +++--
 app/library/config.py        |  3 +++
 3 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/FAQ.md b/FAQ.md
index acb74aa0..789eff1b 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -40,6 +40,7 @@ or the `environment:` section in `compose.yaml` file.
 | YTP_YTDLP_VERSION              | The version of yt-dlp to use. Defaults to latest version           | `(not_set)`           |
 | YTP_BASE_PATH                  | Set this if you are serving YTPTube from sub-folder                | `/`                   |
 | YTP_PREVENT_LIVE_PREMIERE      | Prevents the initial youtube premiere stream from being downloaded | `false`               |
+| YTP_LIVE_PREMIERE_BUFFER       | buffer time in minutes to add to video duration                    | `5`                   |
 | YTP_TASKS_HANDLER_TIMER        | The cron expression for the tasks handler timer                    | `15 */1 * * *`        |
 | YTP_PLAYLIST_ITEMS_CONCURRENCY | The number of playlist items be to processed at same time          | `1`                   |
 | YTP_TEMP_DISABLED              | Disable temp files handling.                                       | `false`               |
@@ -550,3 +551,20 @@ services:
 
 After making the changes, restart your container. This should resolve the "No space left on device" 
 error during download.
+
+
+# How to prevent loading screen during YouTube premieres?
+
+Depending on how you look at it, YTPTube live download implementation is rather great and fast. However, during YouTube 
+premieres, usually streams will contain a loading screen of say, 1-5 minutes before the actual video content starts 
+playing. By default we wait for 5min + the duration of the video before starting the download to ensure we get the full video without
+the loading screen. However, you can override the behavior by setting the following environment variable:
+
+```env
+YTP_PREVENT_LIVE_PREMIERE=true
+YTP_LIVE_PREMIERE_BUFFER=10
+```
+
+Where `YTP_LIVE_PREMIERE_BUFFER` is the buffer time in minutes to add to the video duration before the download starts. 
+This will help in case the premiere has a longer loading screen than usual.
+
diff --git a/app/library/DownloadQueue.py b/app/library/DownloadQueue.py
index fe0fde00..89c154f3 100644
--- a/app/library/DownloadQueue.py
+++ b/app/library/DownloadQueue.py
@@ -1240,10 +1240,11 @@ class DownloadQueue(metaclass=Singleton):
                 continue
 
             if self.config.prevent_live_premiere and is_premiere and duration:
-                premiere_ends: datetime = starts_in + timedelta(minutes=5, seconds=duration)
+                buffer_time = self.config.live_premiere_buffer if self.config.live_premiere_buffer >= 0 else 5
+                premiere_ends: datetime = starts_in + timedelta(minutes=buffer_time, seconds=duration)
                 if time_now < premiere_ends:
                     LOG.debug(
-                        f"Item '{item_ref}' is premiering, download will start in '{(starts_in + timedelta(minutes=5, seconds=duration)).astimezone().isoformat()}'"
+                        f"Item '{item_ref}' is premiering, download will start in '{(starts_in + timedelta(minutes=buffer_time, seconds=duration)).astimezone().isoformat()}'"
                     )
                     continue
 
diff --git a/app/library/config.py b/app/library/config.py
index ad78464c..f7d3aa05 100644
--- a/app/library/config.py
+++ b/app/library/config.py
@@ -189,6 +189,9 @@ class Config(metaclass=Singleton):
     prevent_live_premiere: bool = False
     """Prevent downloading of the initial premiere live broadcast."""
 
+    live_premiere_buffer: int = 5
+    """The buffer time in minutes to add to video duration to wait before starting premiere download."""
+
     playlist_items_concurrency: int = 4
     """The number of concurrent playlist items to be processed at same time."""