Transcript: detect IP-block (SSL/EOF) + retry; expose module-level demo

- youtube-transcript-api hits www.youtube.com, which datacenter IPs get blocked from
(TLS reset / SSL EOF). Retry transient connection failures and, on a clear block, the
error now tells the user to set the YT_PROXY (residential) secret. Fixed a substring
bug where "transcripts" matched the "ip" block keyword.
- app.py exposes module-level `demo` so HF's SSR launcher stops warning
"Launching demo not found in __main__".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app.py

@@ -285,5 +285,10 @@ def build_ui():
     return demo
 
 
+# Expose a module-level `demo` so HF Spaces' SSR launcher finds it (avoids the
+# "Launching demo not found in __main__" fallback warning).
+demo = build_ui()
+demo.queue()
+
 if __name__ == "__main__":
-    build_ui().queue().launch()
+    demo.launch()

pipeline/transcribe.py

@@ -1,56 +1,77 @@
 """Stage 4: fetch a timestamped transcript via youtube-transcript-api (no download).
 
-youtube-transcript-api returns caption snippets that already carry ``start`` (and
-``duration``) timestamps, so we just normalize them into ``{start, end, text}`` segments
-for the rest of the pipeline. No Whisper, no audio, no video.
+youtube-transcript-api scrapes ``www.youtube.com``, which datacenter IPs (like a Space)
+often get blocked from — usually as a TLS reset / SSL EOF rather than a clean 4xx. We
+retry a few times for transient failures and, when it's clearly a block, point the user at
+the ``YT_PROXY`` fallback. The returned snippets already carry ``start``/``duration``
+timestamps, which we normalize into ``{start, end, text}`` segments.
 """
 from __future__ import annotations
 
+import time
+
 
 class TranscriptError(RuntimeError):
     """Raised when no usable transcript can be fetched (disabled, blocked, none)."""
 
 
+def _fetch_raw(video_id: str, langs: list[str], proxy: str | None) -> list[dict]:
+    from youtube_transcript_api import YouTubeTranscriptApi
+
+    # --- 1.x instance API ---
+    api = None
+    if proxy:
+        try:
+            from youtube_transcript_api.proxies import GenericProxyConfig
+            api = YouTubeTranscriptApi(
+                proxy_config=GenericProxyConfig(http_url=proxy, https_url=proxy))
+        except Exception:
+            api = YouTubeTranscriptApi()
+    else:
+        api = YouTubeTranscriptApi()
+
+    if hasattr(api, "fetch"):
+        fetched = api.fetch(video_id, languages=langs)
+        return [{"text": s.text, "start": s.start, "duration": s.duration} for s in fetched]
+
+    # --- 0.6.x classmethod API ---
+    kwargs = {"languages": langs}
+    if proxy:
+        kwargs["proxies"] = {"http": proxy, "https": proxy}
+    data = YouTubeTranscriptApi.get_transcript(video_id, **kwargs)
+    return [{"text": d["text"], "start": d["start"], "duration": d.get("duration", 0)} for d in data]
+
+
+def _is_transient(exc: Exception) -> bool:
+    s = (type(exc).__name__ + " " + str(exc)).lower()
+    return any(k in s for k in ("ssl", "eof", "timed out", "timeout", "reset",
+                                "connection", "max retries", "temporarily"))
+
+
 def get_segments(video_id: str, languages=("en", "en-US", "en-GB"),
-                 proxy: str | None = None) -> list[dict]:
+                 proxy: str | None = None, attempts: int = 3) -> list[dict]:
     """Return timestamped segments ``[{start, end, text}]`` for ``video_id``.
 
-    Works across youtube-transcript-api 1.x (instance ``.fetch``) and older 0.6.x
-    (classmethod ``.get_transcript``). ``proxy`` is an optional http(s) proxy URL used as
-    a thin fallback when the Space's IP is blocked.
+    Retries transient connection/TLS failures; raises TranscriptError otherwise.
+    ``proxy`` (the YT_PROXY secret) routes around datacenter-IP blocks.
     """
-    from youtube_transcript_api import YouTubeTranscriptApi
-
     langs = list(languages)
-    raw = None
-    try:
-        # --- 1.x instance API ---
-        api = None
-        if proxy:
-            try:
-                from youtube_transcript_api.proxies import GenericProxyConfig
-                api = YouTubeTranscriptApi(
-                    proxy_config=GenericProxyConfig(http_url=proxy, https_url=proxy))
-            except Exception:
-                api = YouTubeTranscriptApi()
-        else:
-            api = YouTubeTranscriptApi()
-
-        if hasattr(api, "fetch"):
-            fetched = api.fetch(video_id, languages=langs)
-            raw = [{"text": s.text, "start": s.start, "duration": s.duration} for s in fetched]
-        else:
-            # --- 0.6.x classmethod API ---
-            kwargs = {"languages": langs}
-            if proxy:
-                kwargs["proxies"] = {"http": proxy, "https": proxy}
-            data = YouTubeTranscriptApi.get_transcript(video_id, **kwargs)
-            raw = [{"text": d["text"], "start": d["start"], "duration": d.get("duration", 0)} for d in data]
-    except Exception as exc:
-        raise TranscriptError(_hint(exc)) from exc
+    raw, last = None, None
+    for attempt in range(attempts):
+        try:
+            raw = _fetch_raw(video_id, langs, proxy)
+            break
+        except Exception as exc:
+            last = exc
+            if _is_transient(exc) and attempt < attempts - 1:
+                time.sleep(1.5 * (attempt + 1))
+                continue
+            raise TranscriptError(_hint(exc)) from exc
+    if raw is None:
+        raise TranscriptError(_hint(last) if last else "Unknown transcript error.")
 
     segs = []
-    for r in raw or []:
+    for r in raw:
         text = (r.get("text") or "").strip()
         if not text:
             continue
@@ -75,14 +96,17 @@ def _hint(exc: Exception) -> str:
     name = type(exc).__name__
     msg = str(exc)
     low = (name + " " + msg).lower()
+    # Check specific transcript states first (note: "transcripts" contains "ip").
     if "disabled" in low or "transcriptsdisabled" in low:
         return "This video has transcripts/captions disabled — pick another video."
     if "notranscript" in low or "no transcript" in low:
         return "No transcript is available for this video in the requested languages."
     if "unavailable" in low or "videounavailable" in low:
         return "The video is unavailable (private/removed/region-locked)."
-    if "block" in low or "ip" in low or "too many" in low or "429" in low:
-        return ("YouTube blocked the transcript request (common from datacenter IPs). "
-                "Set a YT_PROXY Space secret (residential proxy) and retry. "
+    if any(k in low for k in ("ssl", "eof", "reset", "connection", "max retries",
+                              "timed out", "blocked", "forbidden", "too many", "429")):
+        return ("YouTube blocked the transcript request from this Space's IP "
+                "(datacenter IPs are commonly blocked — seen here as a TLS/SSL reset). "
+                "Set a residential proxy as the YT_PROXY Space secret and retry. "
                 f"[{name}]")
     return f"Could not fetch transcript: {name}: {msg[:200]}"