CuriousDragon's picture
Publish verified Flow Smart Segments curated-category-encoder-ensemble-20261004
8fcf7c9 verified
Raw History Blame Contribute Delete
7.66 kB
from __future__ import annotations
import math
import re
import time
from dataclasses import dataclass
from typing import Callable, Sequence
import requests
TRANSCRIPT_API_ENDPOINT = "https://transcriptapi.com/api/v2/youtube/transcript"
class TranscriptApiError(RuntimeError):
pass
class TranscriptApiNoTranscriptError(TranscriptApiError):
pass
class TranscriptApiConfigurationError(TranscriptApiError):
pass
class TranscriptApiRetryableError(TranscriptApiError):
pass
@dataclass(frozen=True)
class TranscriptApiSnippet:
text: str
start: float
duration: float
class TranscriptApiFetchedTranscript:
def __init__(self, snippets: Sequence[TranscriptApiSnippet]) -> None:
self._snippets = tuple(snippets)
def __iter__(self):
return iter(self._snippets)
class TranscriptApiTranscript:
def __init__(
self,
*,
language_code: str,
snippets: Sequence[TranscriptApiSnippet],
) -> None:
self.language = language_code
self.language_code = language_code
self.is_generated = language_code.lower().startswith("asr-")
self.source = "transcript_api"
self.source_version = "v2"
self._snippets = tuple(snippets)
def fetch(self) -> TranscriptApiFetchedTranscript:
return TranscriptApiFetchedTranscript(self._snippets)
class TranscriptApiTranscriptList:
def __init__(self, client: TranscriptApiClient, video_id: str) -> None:
self._client = client
self._video_id = video_id
def find_transcript(self, languages: Sequence[str]) -> TranscriptApiTranscript:
return self._client.fetch(self._video_id, languages)
class TranscriptApiClient:
def __init__(
self,
api_key: str,
*,
request_timeout_seconds: float = 30.0,
max_retries: int = 2,
sleep: Callable[[float], None] = time.sleep,
request_get: Callable[..., object] = requests.get,
) -> None:
if not api_key:
raise ValueError("TranscriptAPI key cannot be empty")
if request_timeout_seconds <= 0:
raise ValueError("request timeout must be positive")
if max_retries < 0:
raise ValueError("max retries cannot be negative")
self._api_key = api_key
self._request_timeout_seconds = request_timeout_seconds
self._max_retries = max_retries
self._sleep = sleep
self._request_get = request_get
def list(self, video_id: str) -> TranscriptApiTranscriptList:
return TranscriptApiTranscriptList(self, video_id)
def fetch(
self, video_id: str, languages: Sequence[str]
) -> TranscriptApiTranscript:
parameters = {
"video_url": video_id,
"format": "json",
"include_timestamp": "true",
"language": ",".join(_language_priority(languages)),
}
headers = {
"Authorization": f"Bearer {self._api_key}",
"Accept": "application/json",
}
for attempt in range(self._max_retries + 1):
try:
response = self._request_get(
TRANSCRIPT_API_ENDPOINT,
headers=headers,
params=parameters,
timeout=self._request_timeout_seconds,
)
if response.status_code != 200:
api_error = _classify_http_error(response)
if not isinstance(api_error, TranscriptApiRetryableError):
raise api_error
if attempt >= self._max_retries:
raise api_error
self._sleep(_retry_delay_seconds(response.headers, attempt))
continue
payload = response.json()
return _parse_transcript(payload)
except requests.exceptions.RequestException as error:
api_error = TranscriptApiRetryableError(
f"TranscriptAPI network request failed: {type(error).__name__}"
)
if attempt >= self._max_retries:
raise api_error from None
self._sleep(min(5.0, 2.0**attempt))
raise AssertionError("TranscriptAPI retry loop exited unexpectedly")
def _language_priority(languages: Sequence[str]) -> list[str]:
priority: list[str] = []
for language in languages:
base_language = language.partition("-")[0].lower()
for code in (base_language, f"asr-{base_language}"):
if code not in priority:
priority.append(code)
return priority
def _parse_transcript(payload: object) -> TranscriptApiTranscript:
if not isinstance(payload, dict):
raise TranscriptApiError("TranscriptAPI returned a non-object response")
language_code = payload.get("language")
raw_snippets = payload.get("transcript")
if not isinstance(language_code, str) or not language_code:
raise TranscriptApiError("TranscriptAPI response omitted the transcript language")
if not isinstance(raw_snippets, list):
raise TranscriptApiError("TranscriptAPI response omitted timestamped transcript cues")
snippets: list[TranscriptApiSnippet] = []
for raw_snippet in raw_snippets:
if not isinstance(raw_snippet, dict):
raise TranscriptApiError("TranscriptAPI returned an invalid transcript cue")
text = re.sub(r"\s+", " ", str(raw_snippet.get("text", ""))).strip()
try:
start = float(raw_snippet["start"])
duration = float(raw_snippet["duration"])
except (KeyError, TypeError, ValueError) as error:
raise TranscriptApiError(
"TranscriptAPI returned a cue without valid timestamps"
) from error
if not math.isfinite(start) or not math.isfinite(duration):
raise TranscriptApiError("TranscriptAPI returned non-finite cue timestamps")
if not text:
continue
snippets.append(
TranscriptApiSnippet(
text=text,
start=max(0.0, start),
duration=max(0.0, duration),
)
)
if not snippets:
raise TranscriptApiNoTranscriptError("TranscriptAPI returned no usable cues")
return TranscriptApiTranscript(language_code=language_code, snippets=snippets)
def _classify_http_error(response) -> TranscriptApiError:
detail = _error_detail(response)
if response.status_code == 404:
return TranscriptApiNoTranscriptError(detail)
if response.status_code in {400, 401, 402, 422}:
return TranscriptApiConfigurationError(detail)
if response.status_code in {408, 429, 500, 503}:
return TranscriptApiRetryableError(detail)
return TranscriptApiError(detail)
def _error_detail(response) -> str:
try:
payload = response.json()
detail = payload.get("detail")
if isinstance(detail, dict):
detail = detail.get("message") or detail.get("reason")
if detail:
return (
f"TranscriptAPI request failed ({response.status_code}): {detail}"
)
except (AttributeError, TypeError, ValueError):
pass
return f"TranscriptAPI request failed ({response.status_code})"
def _retry_delay_seconds(headers, attempt: int) -> float:
retry_after = headers.get("Retry-After") if headers else None
if retry_after:
try:
return max(0.0, min(60.0, float(retry_after)))
except ValueError:
pass
return min(5.0, 2.0**attempt)