tubetranscript 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tubetranscript/__init__.py +50 -0
- tubetranscript/__main__.py +5 -0
- tubetranscript/_cli.py +74 -0
- tubetranscript/_client.py +456 -0
- tubetranscript/_compat.py +181 -0
- tubetranscript/_errors.py +88 -0
- tubetranscript/_version.py +1 -0
- tubetranscript/py.typed +0 -0
- tubetranscript-0.1.0.dist-info/METADATA +187 -0
- tubetranscript-0.1.0.dist-info/RECORD +13 -0
- tubetranscript-0.1.0.dist-info/WHEEL +4 -0
- tubetranscript-0.1.0.dist-info/entry_points.txt +2 -0
- tubetranscript-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""YouTube transcripts that work from cloud servers, including videos without captions.
|
|
2
|
+
|
|
3
|
+
Two ways to use it:
|
|
4
|
+
|
|
5
|
+
- ``from tubetranscript import YouTubeTranscriptApi``: a drop-in for youtube-transcript-api whose ``fetch()``
|
|
6
|
+
falls back to the TubeTranscript API when YouTube blocks your IP.
|
|
7
|
+
- ``TubeTranscript().transcript(url)``: the TubeTranscript API directly (YouTube, TikTok, Instagram, Facebook).
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
import logging
|
|
11
|
+
|
|
12
|
+
from ._version import __version__
|
|
13
|
+
from ._client import Chunk, TranscriptResult, TubeTranscript
|
|
14
|
+
from ._compat import YouTubeTranscriptApi, to_fetched_transcript
|
|
15
|
+
from ._errors import (
|
|
16
|
+
AuthenticationError,
|
|
17
|
+
ConfigurationError,
|
|
18
|
+
ExtractionFailedError,
|
|
19
|
+
ExtractionInProgressError,
|
|
20
|
+
FeaturesFailedError,
|
|
21
|
+
InvalidRequestError,
|
|
22
|
+
PlanRequiredError,
|
|
23
|
+
RateLimitError,
|
|
24
|
+
ServiceUnavailableError,
|
|
25
|
+
TranscriptNotFoundError,
|
|
26
|
+
TubeTranscriptError,
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
# Library convention: log only when the application configures logging (logging.getLogger("tubetranscript")).
|
|
30
|
+
logging.getLogger("tubetranscript").addHandler(logging.NullHandler())
|
|
31
|
+
|
|
32
|
+
__all__ = [ # noqa: RUF022 (dunder first, then classes, then functions)
|
|
33
|
+
"__version__",
|
|
34
|
+
"AuthenticationError",
|
|
35
|
+
"Chunk",
|
|
36
|
+
"ConfigurationError",
|
|
37
|
+
"ExtractionFailedError",
|
|
38
|
+
"ExtractionInProgressError",
|
|
39
|
+
"FeaturesFailedError",
|
|
40
|
+
"InvalidRequestError",
|
|
41
|
+
"PlanRequiredError",
|
|
42
|
+
"RateLimitError",
|
|
43
|
+
"ServiceUnavailableError",
|
|
44
|
+
"TranscriptNotFoundError",
|
|
45
|
+
"TranscriptResult",
|
|
46
|
+
"TubeTranscript",
|
|
47
|
+
"TubeTranscriptError",
|
|
48
|
+
"YouTubeTranscriptApi",
|
|
49
|
+
"to_fetched_transcript",
|
|
50
|
+
]
|
tubetranscript/_cli.py
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
"""Command line: ``tubetranscript <video URL or ID> [--format text|json|srt] [--features hooks,mindmap]``."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import logging
|
|
8
|
+
import sys
|
|
9
|
+
from dataclasses import asdict
|
|
10
|
+
from typing import List, Optional, Sequence
|
|
11
|
+
|
|
12
|
+
from ._client import FEATURES, Chunk, TubeTranscript, iter_features
|
|
13
|
+
from ._errors import TubeTranscriptError
|
|
14
|
+
from ._version import __version__
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _srt_time(seconds: float) -> str:
|
|
18
|
+
millis = max(round(seconds * 1000), 0)
|
|
19
|
+
hours, millis = divmod(millis, 3_600_000)
|
|
20
|
+
minutes, millis = divmod(millis, 60_000)
|
|
21
|
+
secs, millis = divmod(millis, 1000)
|
|
22
|
+
return f"{hours:02d}:{minutes:02d}:{secs:02d},{millis:03d}"
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def to_srt(chunks: Sequence[Chunk]) -> str:
|
|
26
|
+
blocks: List[str] = []
|
|
27
|
+
for index, chunk in enumerate(chunks, start=1):
|
|
28
|
+
end = chunk.start + chunk.duration
|
|
29
|
+
blocks.append(f"{index}\n{_srt_time(chunk.start)} --> {_srt_time(end)}\n{chunk.text.strip()}\n")
|
|
30
|
+
return "\n".join(blocks)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def main(argv: Optional[Sequence[str]] = None) -> int:
|
|
34
|
+
parser = argparse.ArgumentParser(
|
|
35
|
+
prog="tubetranscript",
|
|
36
|
+
description="Get a video transcript from the TubeTranscript API (needs TUBETRANSCRIPT_API_KEY).",
|
|
37
|
+
)
|
|
38
|
+
parser.add_argument("video", help="YouTube video URL or ID, or a TikTok, Instagram or Facebook video URL")
|
|
39
|
+
parser.add_argument("--format", choices=("text", "json", "srt"), default="text")
|
|
40
|
+
parser.add_argument("--features", action="append", default=[],
|
|
41
|
+
help=f"AI extras, comma-separated: {', '.join(FEATURES)} (implies --format json)")
|
|
42
|
+
parser.add_argument("--wait", type=float, default=600.0,
|
|
43
|
+
help="Seconds to keep waiting for audio transcription (default 600)")
|
|
44
|
+
parser.add_argument("-v", "--verbose", action="store_true", help="Log retries and waits to stderr")
|
|
45
|
+
parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
|
|
46
|
+
args = parser.parse_args(argv)
|
|
47
|
+
if args.verbose:
|
|
48
|
+
logging.basicConfig(level=logging.DEBUG, format="tubetranscript: %(message)s")
|
|
49
|
+
# urllib3 debug lines would print request URLs and headers' presence; keep them out.
|
|
50
|
+
logging.getLogger("urllib3").setLevel(logging.WARNING)
|
|
51
|
+
|
|
52
|
+
# Windows consoles default to a legacy code page: never crash on characters it cannot show.
|
|
53
|
+
reconfigure = getattr(sys.stdout, "reconfigure", None)
|
|
54
|
+
if reconfigure is not None:
|
|
55
|
+
reconfigure(errors="replace")
|
|
56
|
+
|
|
57
|
+
features = iter_features(args.features)
|
|
58
|
+
try:
|
|
59
|
+
result = TubeTranscript().transcript(args.video, features=features, wait=args.wait)
|
|
60
|
+
except TubeTranscriptError as error:
|
|
61
|
+
print(f"tubetranscript: {error}", file=sys.stderr)
|
|
62
|
+
return 1
|
|
63
|
+
|
|
64
|
+
if args.format == "json" or features:
|
|
65
|
+
print(json.dumps(asdict(result), ensure_ascii=False, indent=2))
|
|
66
|
+
elif args.format == "srt":
|
|
67
|
+
print(to_srt(result.chunks))
|
|
68
|
+
else:
|
|
69
|
+
print(result.text)
|
|
70
|
+
return 0
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
if __name__ == "__main__": # pragma: no cover
|
|
74
|
+
sys.exit(main())
|
|
@@ -0,0 +1,456 @@
|
|
|
1
|
+
"""Client for the TubeTranscript REST API (``POST /api/v1/extract``).
|
|
2
|
+
|
|
3
|
+
Contract: https://tubetranscript.io/docs/api
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import logging
|
|
9
|
+
import os
|
|
10
|
+
import random
|
|
11
|
+
import re
|
|
12
|
+
import time
|
|
13
|
+
from collections.abc import Mapping
|
|
14
|
+
from dataclasses import dataclass, field
|
|
15
|
+
from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple
|
|
16
|
+
from urllib.parse import urlparse
|
|
17
|
+
|
|
18
|
+
import requests
|
|
19
|
+
import requests.auth
|
|
20
|
+
from urllib3.exceptions import NewConnectionError
|
|
21
|
+
|
|
22
|
+
from ._errors import (
|
|
23
|
+
AuthenticationError,
|
|
24
|
+
ConfigurationError,
|
|
25
|
+
ExtractionFailedError,
|
|
26
|
+
ExtractionInProgressError,
|
|
27
|
+
FeaturesFailedError,
|
|
28
|
+
InvalidRequestError,
|
|
29
|
+
PlanRequiredError,
|
|
30
|
+
RateLimitError,
|
|
31
|
+
ServiceUnavailableError,
|
|
32
|
+
TranscriptNotFoundError,
|
|
33
|
+
TubeTranscriptError,
|
|
34
|
+
)
|
|
35
|
+
from ._version import __version__
|
|
36
|
+
|
|
37
|
+
logger = logging.getLogger("tubetranscript")
|
|
38
|
+
|
|
39
|
+
DEFAULT_BASE_URL = "https://tubetranscript.io"
|
|
40
|
+
API_KEY_ENV = "TUBETRANSCRIPT_API_KEY"
|
|
41
|
+
BASE_URL_ENV = "TUBETRANSCRIPT_BASE_URL"
|
|
42
|
+
|
|
43
|
+
FEATURES = ("hooks", "mindmap", "action_items")
|
|
44
|
+
# The server answers within ~280 s and documents a 300 s client timeout; connecting should take seconds.
|
|
45
|
+
CONNECT_TIMEOUT_SECONDS = 10.0
|
|
46
|
+
REQUEST_TIMEOUT_SECONDS = 300.0
|
|
47
|
+
DEFAULT_RETRY_AFTER_SECONDS = 60.0
|
|
48
|
+
# How long transcript() keeps resending a request while audio transcription runs (202).
|
|
49
|
+
DEFAULT_WAIT_SECONDS = 600.0
|
|
50
|
+
DEFAULT_MAX_RETRIES = 2
|
|
51
|
+
# Longest pause between two retries of a transient failure, whatever Retry-After says.
|
|
52
|
+
MAX_RETRY_DELAY_SECONDS = 30.0
|
|
53
|
+
|
|
54
|
+
_VIDEO_ID = re.compile(r"^[A-Za-z0-9_-]{11}$")
|
|
55
|
+
# Mirrors the API's key format. The API's edge only lets a key of this exact shape skip
|
|
56
|
+
# the per-IP guest limit, so any other string would spend the caller's guest quota before failing.
|
|
57
|
+
_API_KEY = re.compile(r"^tt_live_[A-Za-z0-9_-]{32}$")
|
|
58
|
+
_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
|
|
59
|
+
# Refused before the request is counted (the quota store is down): always safe to resend. WORKER_UNAVAILABLE is not
|
|
60
|
+
# here: it comes after the request was counted and means minutes of maintenance, so quick retries would only spend
|
|
61
|
+
# quota.
|
|
62
|
+
_TRANSIENT_CODES = {"RATE_LIMIT_UNAVAILABLE"}
|
|
63
|
+
# 502/503 without the API's JSON envelope are the gateway in front of the API (for example during a restart). 504 is
|
|
64
|
+
# not here: the API had the request for the gateway's whole timeout.
|
|
65
|
+
_GATEWAY_STATUSES = {502, 503}
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class _BearerAuth(requests.auth.AuthBase):
|
|
69
|
+
"""Sets ``Authorization: Bearer <key>``; never shows the key in ``repr``."""
|
|
70
|
+
|
|
71
|
+
def __init__(self, key: str) -> None:
|
|
72
|
+
self._key = key
|
|
73
|
+
|
|
74
|
+
def __call__(self, request: requests.PreparedRequest) -> requests.PreparedRequest:
|
|
75
|
+
request.headers["Authorization"] = f"Bearer {self._key}"
|
|
76
|
+
return request
|
|
77
|
+
|
|
78
|
+
def __repr__(self) -> str:
|
|
79
|
+
return "_BearerAuth(<hidden>)"
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def _never_connected(error: requests.RequestException) -> bool:
|
|
83
|
+
"""True when no connection to the API was made (DNS failure, refused, connect timeout): nothing was sent."""
|
|
84
|
+
if isinstance(error, requests.ConnectTimeout):
|
|
85
|
+
return True
|
|
86
|
+
reason = getattr(error.args[0], "reason", None) if error.args else None
|
|
87
|
+
return isinstance(reason, NewConnectionError)
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
@dataclass(frozen=True)
|
|
91
|
+
class Chunk:
|
|
92
|
+
"""One timed piece of a transcript, in seconds."""
|
|
93
|
+
|
|
94
|
+
text: str
|
|
95
|
+
start: float
|
|
96
|
+
duration: float
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
@dataclass(frozen=True)
|
|
100
|
+
class TranscriptResult:
|
|
101
|
+
"""A transcript as returned by the API."""
|
|
102
|
+
|
|
103
|
+
video_id: str
|
|
104
|
+
"""The YouTube video ID; for TikTok, Instagram and Facebook links, an internal key such as ``t:3f9a...``."""
|
|
105
|
+
text: str
|
|
106
|
+
chunks: List[Chunk]
|
|
107
|
+
source: str
|
|
108
|
+
"""``captions``, ``audio`` (no captions, so the audio was transcribed), ``media`` (a TikTok, Instagram or
|
|
109
|
+
Facebook link, transcribed) or ``existing_job`` (reused from an earlier request of your team)."""
|
|
110
|
+
platform: str = "youtube"
|
|
111
|
+
language: Optional[str] = None
|
|
112
|
+
video_title: Optional[str] = None
|
|
113
|
+
channel_name: Optional[str] = None
|
|
114
|
+
job_id: Optional[str] = None
|
|
115
|
+
features: Dict[str, Any] = field(default_factory=dict)
|
|
116
|
+
rate_limit_remaining: Optional[int] = None
|
|
117
|
+
|
|
118
|
+
@classmethod
|
|
119
|
+
def from_api(cls, data: Mapping[str, Any], headers: Optional[Mapping[str, str]] = None) -> TranscriptResult:
|
|
120
|
+
"""``headers`` should be case-insensitive (``requests`` response headers are)."""
|
|
121
|
+
transcript = data.get("transcript") or {}
|
|
122
|
+
chunks = [
|
|
123
|
+
Chunk(
|
|
124
|
+
text=str(chunk.get("text", "")),
|
|
125
|
+
start=float(chunk.get("start") or 0.0),
|
|
126
|
+
duration=float(chunk.get("duration") or 0.0),
|
|
127
|
+
)
|
|
128
|
+
for chunk in transcript.get("chunks") or []
|
|
129
|
+
if isinstance(chunk, Mapping)
|
|
130
|
+
]
|
|
131
|
+
remaining = (headers or {}).get("X-RateLimit-Remaining")
|
|
132
|
+
features = data.get("features")
|
|
133
|
+
return cls(
|
|
134
|
+
video_id=str(data.get("video_id") or ""),
|
|
135
|
+
text=str(transcript.get("text") or ""),
|
|
136
|
+
chunks=chunks,
|
|
137
|
+
source=str(data.get("source") or ""),
|
|
138
|
+
platform=str(data.get("platform") or "youtube"),
|
|
139
|
+
language=data.get("language"),
|
|
140
|
+
video_title=data.get("video_title"),
|
|
141
|
+
channel_name=data.get("channel_name"),
|
|
142
|
+
job_id=data.get("job_id"),
|
|
143
|
+
features=dict(features) if isinstance(features, Mapping) else {},
|
|
144
|
+
rate_limit_remaining=int(remaining) if remaining and remaining.isdigit() else None,
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def video_url(video_or_url: str) -> str:
|
|
149
|
+
"""Turns an 11-character YouTube video ID into a watch URL; anything else is passed through as a URL."""
|
|
150
|
+
value = video_or_url.strip()
|
|
151
|
+
if _VIDEO_ID.match(value):
|
|
152
|
+
return f"https://www.youtube.com/watch?v={value}"
|
|
153
|
+
return value
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
class TubeTranscript:
|
|
157
|
+
"""Client for the TubeTranscript API.
|
|
158
|
+
|
|
159
|
+
>>> client = TubeTranscript() # reads TUBETRANSCRIPT_API_KEY
|
|
160
|
+
>>> result = client.transcript("https://youtu.be/jNQXAC9IVRw")
|
|
161
|
+
>>> print(result.text)
|
|
162
|
+
|
|
163
|
+
``max_retries`` resends a request after a transient failure, with exponential backoff: always when the API cannot
|
|
164
|
+
have counted it (no connection made, ``RATE_LIMIT_UNAVAILABLE``); and, for calls without ``features``, after a
|
|
165
|
+
dropped connection or a 502/503 page from the gateway. Quota refusals (429), ``WORKER_UNAVAILABLE`` and other
|
|
166
|
+
errors are not retried.
|
|
167
|
+
|
|
168
|
+
The client uses a ``requests.Session``. Sharing one client between threads works in practice; for strict
|
|
169
|
+
guarantees, use one client per thread.
|
|
170
|
+
"""
|
|
171
|
+
|
|
172
|
+
def __init__(
|
|
173
|
+
self,
|
|
174
|
+
api_key: Optional[str] = None,
|
|
175
|
+
*,
|
|
176
|
+
base_url: Optional[str] = None,
|
|
177
|
+
timeout: float = REQUEST_TIMEOUT_SECONDS,
|
|
178
|
+
max_retries: int = DEFAULT_MAX_RETRIES,
|
|
179
|
+
session: Optional[requests.Session] = None,
|
|
180
|
+
sleep: Callable[[float], None] = time.sleep,
|
|
181
|
+
) -> None:
|
|
182
|
+
key = (api_key if api_key is not None else os.environ.get(API_KEY_ENV, "")).strip()
|
|
183
|
+
if not key:
|
|
184
|
+
raise ConfigurationError(
|
|
185
|
+
f"No API key. Pass api_key=... or set {API_KEY_ENV}. "
|
|
186
|
+
"Create a key at https://tubetranscript.io/dashboard/api",
|
|
187
|
+
code="MISSING_API_KEY",
|
|
188
|
+
)
|
|
189
|
+
if not _API_KEY.match(key):
|
|
190
|
+
# Never echo the value: it may be a real secret with a typo.
|
|
191
|
+
raise ConfigurationError(
|
|
192
|
+
"The API key is not in the expected format (tt_live_ followed by 32 characters). "
|
|
193
|
+
"Copy it again from https://tubetranscript.io/dashboard/api",
|
|
194
|
+
code="INVALID_API_KEY_FORMAT",
|
|
195
|
+
)
|
|
196
|
+
if max_retries < 0:
|
|
197
|
+
raise ConfigurationError("max_retries must be 0 or more.", code="INVALID_MAX_RETRIES")
|
|
198
|
+
self._api_key = key
|
|
199
|
+
self.base_url = _check_base_url(base_url or os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL)
|
|
200
|
+
self.timeout = timeout
|
|
201
|
+
self.max_retries = max_retries
|
|
202
|
+
self._session = session or requests.Session()
|
|
203
|
+
self._sleep = sleep
|
|
204
|
+
|
|
205
|
+
def __repr__(self) -> str: # never print the key
|
|
206
|
+
return f"TubeTranscript(base_url={self.base_url!r})"
|
|
207
|
+
|
|
208
|
+
def close(self) -> None:
|
|
209
|
+
"""Closes the underlying HTTP session."""
|
|
210
|
+
self._session.close()
|
|
211
|
+
|
|
212
|
+
def __enter__(self) -> TubeTranscript:
|
|
213
|
+
return self
|
|
214
|
+
|
|
215
|
+
def __exit__(self, *_exc: object) -> None:
|
|
216
|
+
self.close()
|
|
217
|
+
|
|
218
|
+
def transcript(
|
|
219
|
+
self,
|
|
220
|
+
video: str,
|
|
221
|
+
*,
|
|
222
|
+
features: Sequence[str] = (),
|
|
223
|
+
wait: float = DEFAULT_WAIT_SECONDS,
|
|
224
|
+
) -> TranscriptResult:
|
|
225
|
+
"""Returns the transcript of a YouTube video (ID or URL), or a TikTok, Instagram or Facebook video URL.
|
|
226
|
+
|
|
227
|
+
``features`` asks for AI extras in the same call: any of ``hooks``, ``mindmap``, ``action_items``.
|
|
228
|
+
|
|
229
|
+
When the video has no captions the server transcribes the audio, which can take minutes. The server holds
|
|
230
|
+
each request for up to ~280 s and answers 202 if it is still running; the request is then resent after
|
|
231
|
+
``Retry-After`` until ``wait`` seconds have passed, and :class:`ExtractionInProgressError` is raised. Because a
|
|
232
|
+
request already in flight is not cut short, the call can last up to about ``wait`` + 300 s. Every resend
|
|
233
|
+
counts as one request against the plan's daily limit.
|
|
234
|
+
"""
|
|
235
|
+
if isinstance(features, str):
|
|
236
|
+
features = [features]
|
|
237
|
+
unknown = [name for name in features if name not in FEATURES]
|
|
238
|
+
if unknown:
|
|
239
|
+
raise InvalidRequestError(
|
|
240
|
+
f"Unknown feature(s): {', '.join(unknown)}. Use any of: {', '.join(FEATURES)}.",
|
|
241
|
+
code="INVALID_INPUT",
|
|
242
|
+
)
|
|
243
|
+
if not video or not video.strip():
|
|
244
|
+
raise InvalidRequestError("video must be a YouTube video ID or a video URL.", code="INVALID_INPUT")
|
|
245
|
+
body = {"url": video_url(video), "features": list(dict.fromkeys(features))}
|
|
246
|
+
deadline = time.monotonic() + max(wait, 0.0)
|
|
247
|
+
# A request that may have reached the API is resent only without features: features spend AI runs, which a
|
|
248
|
+
# lost response must never charge twice.
|
|
249
|
+
retry_ambiguous = not body["features"]
|
|
250
|
+
while True:
|
|
251
|
+
response = self._send("/api/v1/extract", body, retry_ambiguous=retry_ambiguous)
|
|
252
|
+
payload = _json(response)
|
|
253
|
+
if response.status_code != 202:
|
|
254
|
+
data = payload.get("data")
|
|
255
|
+
if response.status_code == 200 and payload.get("success") is True and isinstance(data, Mapping):
|
|
256
|
+
try:
|
|
257
|
+
return TranscriptResult.from_api(data, response.headers)
|
|
258
|
+
except (TypeError, ValueError) as error:
|
|
259
|
+
raise TubeTranscriptError(
|
|
260
|
+
f"The API returned a transcript this client cannot read: {error}",
|
|
261
|
+
code="INVALID_RESPONSE", status=200,
|
|
262
|
+
) from None
|
|
263
|
+
raise _error_from(response, payload)
|
|
264
|
+
retry_after = _retry_after(response) or DEFAULT_RETRY_AFTER_SECONDS
|
|
265
|
+
remaining = deadline - time.monotonic()
|
|
266
|
+
if remaining <= 0:
|
|
267
|
+
code, message, _details = _error_parts(payload)
|
|
268
|
+
data = payload.get("data")
|
|
269
|
+
raise ExtractionInProgressError(
|
|
270
|
+
message or "Audio transcription is still running. Call again later.",
|
|
271
|
+
code=code or "EXTRACTION_IN_PROGRESS",
|
|
272
|
+
status=202,
|
|
273
|
+
data=data if isinstance(data, dict) else None,
|
|
274
|
+
)
|
|
275
|
+
logger.debug("Transcription still running; asking again in %.0f s", min(retry_after, remaining))
|
|
276
|
+
self._sleep(min(retry_after, remaining))
|
|
277
|
+
|
|
278
|
+
def _send(self, path: str, body: Dict[str, Any], *, retry_ambiguous: bool) -> requests.Response:
|
|
279
|
+
"""POSTs once, then resends after transient failures (up to ``max_retries`` times).
|
|
280
|
+
|
|
281
|
+
Always resent: failures where the API certainly did not count the request (no connection made,
|
|
282
|
+
``RATE_LIMIT_UNAVAILABLE``). Resent only when ``retry_ambiguous``: failures after the request may have reached
|
|
283
|
+
the API (connection dropped after sending, a 502/503 page from the gateway), which can count one more request.
|
|
284
|
+
"""
|
|
285
|
+
attempt = 0
|
|
286
|
+
while True:
|
|
287
|
+
try:
|
|
288
|
+
response = self._post(path, body)
|
|
289
|
+
except ServiceUnavailableError as error:
|
|
290
|
+
retryable = error.code == "CONNECT_ERROR" or (retry_ambiguous and error.code == "NETWORK_ERROR")
|
|
291
|
+
if not retryable or attempt >= self.max_retries:
|
|
292
|
+
raise
|
|
293
|
+
delay = _backoff(attempt)
|
|
294
|
+
logger.debug("%s; retry %d/%d in %.1f s", error.message, attempt + 1, self.max_retries, delay)
|
|
295
|
+
else:
|
|
296
|
+
if attempt >= self.max_retries or not _is_transient(response, retry_ambiguous=retry_ambiguous):
|
|
297
|
+
return response
|
|
298
|
+
delay = min(_retry_after(response) or _backoff(attempt), MAX_RETRY_DELAY_SECONDS)
|
|
299
|
+
logger.debug("HTTP %d from the API; retry %d/%d in %.1f s",
|
|
300
|
+
response.status_code, attempt + 1, self.max_retries, delay)
|
|
301
|
+
attempt += 1
|
|
302
|
+
self._sleep(delay)
|
|
303
|
+
|
|
304
|
+
def _post(self, path: str, body: Dict[str, Any]) -> requests.Response:
|
|
305
|
+
url = self.base_url + path
|
|
306
|
+
try:
|
|
307
|
+
response = self._session.post(
|
|
308
|
+
url,
|
|
309
|
+
json=body,
|
|
310
|
+
# Passed as auth (not a header) so a ~/.netrc entry for the host cannot replace it.
|
|
311
|
+
auth=_BearerAuth(self._api_key),
|
|
312
|
+
headers={
|
|
313
|
+
"User-Agent": f"tubetranscript-python/{__version__}",
|
|
314
|
+
"Accept": "application/json",
|
|
315
|
+
},
|
|
316
|
+
timeout=(min(CONNECT_TIMEOUT_SECONDS, self.timeout), self.timeout),
|
|
317
|
+
# A redirect would turn the POST into a GET and drop the key; the API never redirects.
|
|
318
|
+
allow_redirects=False,
|
|
319
|
+
)
|
|
320
|
+
except requests.RequestException as error:
|
|
321
|
+
# The exception keeps the prepared request, whose headers hold the key; error trackers that walk
|
|
322
|
+
# the __cause__ chain must not find it.
|
|
323
|
+
error.request = None
|
|
324
|
+
if isinstance(error, requests.ReadTimeout):
|
|
325
|
+
# The server already had the full 300 s: resending would only double the wait. Not retried.
|
|
326
|
+
raise ServiceUnavailableError(
|
|
327
|
+
f"{self.base_url} did not answer within {self.timeout:.0f} s", code="READ_TIMEOUT"
|
|
328
|
+
) from error
|
|
329
|
+
if isinstance(error, (requests.ConnectionError, requests.Timeout)):
|
|
330
|
+
code = "CONNECT_ERROR" if _never_connected(error) else "NETWORK_ERROR"
|
|
331
|
+
raise ServiceUnavailableError(
|
|
332
|
+
f"Could not reach {self.base_url}: {type(error).__name__}", code=code
|
|
333
|
+
) from error
|
|
334
|
+
raise TubeTranscriptError(
|
|
335
|
+
f"Request to {self.base_url} failed: {type(error).__name__}", code="REQUEST_ERROR"
|
|
336
|
+
) from error
|
|
337
|
+
if 300 <= response.status_code < 400:
|
|
338
|
+
location = response.headers.get("Location", "")
|
|
339
|
+
raise ConfigurationError(
|
|
340
|
+
f"{url} redirects to {location or 'another address'}. "
|
|
341
|
+
f"Set base_url to the final address (the default is {DEFAULT_BASE_URL}).",
|
|
342
|
+
code="UNEXPECTED_REDIRECT",
|
|
343
|
+
status=response.status_code,
|
|
344
|
+
)
|
|
345
|
+
return response
|
|
346
|
+
|
|
347
|
+
|
|
348
|
+
def _check_base_url(url: str) -> str:
|
|
349
|
+
parsed = urlparse(url.strip())
|
|
350
|
+
if parsed.scheme not in ("https", "http") or not parsed.hostname:
|
|
351
|
+
raise ConfigurationError(f"Invalid base URL: {url!r}", code="INVALID_BASE_URL")
|
|
352
|
+
# Never send the key in clear text to a remote host.
|
|
353
|
+
if parsed.scheme == "http" and parsed.hostname not in _LOCAL_HOSTS:
|
|
354
|
+
raise ConfigurationError("The base URL must use https (http is allowed for localhost only).",
|
|
355
|
+
code="INVALID_BASE_URL")
|
|
356
|
+
if parsed.username or parsed.password or parsed.query or parsed.fragment:
|
|
357
|
+
raise ConfigurationError("The base URL must not contain credentials, a query or a fragment.",
|
|
358
|
+
code="INVALID_BASE_URL")
|
|
359
|
+
return f"{parsed.scheme}://{parsed.netloc}{parsed.path.rstrip('/')}"
|
|
360
|
+
|
|
361
|
+
|
|
362
|
+
def _json(response: requests.Response) -> Dict[str, Any]:
|
|
363
|
+
try:
|
|
364
|
+
payload = response.json()
|
|
365
|
+
except ValueError:
|
|
366
|
+
return {}
|
|
367
|
+
return payload if isinstance(payload, dict) else {}
|
|
368
|
+
|
|
369
|
+
|
|
370
|
+
def _retry_after(response: requests.Response) -> Optional[float]:
|
|
371
|
+
value = response.headers.get("Retry-After", "")
|
|
372
|
+
try:
|
|
373
|
+
seconds = float(value)
|
|
374
|
+
except ValueError:
|
|
375
|
+
return None
|
|
376
|
+
return seconds if seconds >= 0 else None # NaN fails the comparison too
|
|
377
|
+
|
|
378
|
+
|
|
379
|
+
def _backoff(attempt: int) -> float:
|
|
380
|
+
"""1 s, 2 s, 4 s... with up to 25% jitter, so many clients do not retry in step."""
|
|
381
|
+
base: float = min(2.0 ** attempt, MAX_RETRY_DELAY_SECONDS)
|
|
382
|
+
return base * (1 + random.random() * 0.25) # noqa: S311 (not for security)
|
|
383
|
+
|
|
384
|
+
|
|
385
|
+
def _is_api_body(payload: Mapping[str, Any]) -> bool:
|
|
386
|
+
"""True for a body the API (or the edge limit in front of it) wrote, as opposed to a proxy or framework page."""
|
|
387
|
+
return "success" in payload or isinstance(payload.get("error"), str)
|
|
388
|
+
|
|
389
|
+
|
|
390
|
+
def _is_transient(response: requests.Response, *, retry_ambiguous: bool) -> bool:
|
|
391
|
+
payload = _json(response)
|
|
392
|
+
code, _message, _details = _error_parts(payload)
|
|
393
|
+
if code in _TRANSIENT_CODES:
|
|
394
|
+
return True
|
|
395
|
+
return retry_ambiguous and response.status_code in _GATEWAY_STATUSES and not _is_api_body(payload)
|
|
396
|
+
|
|
397
|
+
|
|
398
|
+
def _error_parts(payload: Mapping[str, Any]) -> Tuple[str, str, Optional[Dict[str, Any]]]:
|
|
399
|
+
"""Code, message and details of an error body.
|
|
400
|
+
|
|
401
|
+
The API answers ``{"success": false, "error": {"code", "message", "details"}}``. A few responses from in front of
|
|
402
|
+
the API (the per-IP guest limit) use ``{"error": "<CODE>", "message": "..."}`` instead.
|
|
403
|
+
"""
|
|
404
|
+
error = payload.get("error")
|
|
405
|
+
if isinstance(error, Mapping):
|
|
406
|
+
details = error.get("details")
|
|
407
|
+
parsed = dict(details) if isinstance(details, Mapping) else None
|
|
408
|
+
return str(error.get("code") or ""), str(error.get("message") or ""), parsed
|
|
409
|
+
if isinstance(error, str):
|
|
410
|
+
return error, str(payload.get("message") or ""), None
|
|
411
|
+
return "", "", None
|
|
412
|
+
|
|
413
|
+
|
|
414
|
+
_BY_STATUS = {
|
|
415
|
+
400: InvalidRequestError,
|
|
416
|
+
401: AuthenticationError,
|
|
417
|
+
403: PlanRequiredError,
|
|
418
|
+
404: TranscriptNotFoundError,
|
|
419
|
+
422: ExtractionFailedError,
|
|
420
|
+
502: FeaturesFailedError,
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
|
|
424
|
+
def _error_from(response: requests.Response, payload: Dict[str, Any]) -> TubeTranscriptError:
|
|
425
|
+
status = response.status_code
|
|
426
|
+
code, message, details = _error_parts(payload)
|
|
427
|
+
data = payload.get("data")
|
|
428
|
+
kwargs: Dict[str, Any] = {
|
|
429
|
+
"code": code or f"HTTP_{status}",
|
|
430
|
+
"status": status,
|
|
431
|
+
"details": details,
|
|
432
|
+
"data": data if isinstance(data, dict) else None,
|
|
433
|
+
}
|
|
434
|
+
message = message or response.reason or "Request failed."
|
|
435
|
+
if 400 <= status < 500 and not _is_api_body(payload):
|
|
436
|
+
# A 4xx page that is not the API's (for example a 404 page because base_url has an extra path).
|
|
437
|
+
kwargs["code"] = "UNEXPECTED_RESPONSE"
|
|
438
|
+
return TubeTranscriptError(
|
|
439
|
+
f"HTTP {status} from {getattr(response, 'url', '') or 'the API'} without an API response body. "
|
|
440
|
+
"Check base_url.",
|
|
441
|
+
**kwargs,
|
|
442
|
+
)
|
|
443
|
+
# 429: an allowance is used up. 409 BUSY: another AI run of the team is in progress. Both mean "try later".
|
|
444
|
+
if status in (409, 429):
|
|
445
|
+
return RateLimitError(message, retry_after=_retry_after(response), **kwargs)
|
|
446
|
+
# A 502 is FEATURES_FAILED only when the API says so; a proxy's 502 page is an outage.
|
|
447
|
+
if status in _BY_STATUS and (status != 502 or kwargs["code"] == "FEATURES_FAILED"):
|
|
448
|
+
return _BY_STATUS[status](message, **kwargs)
|
|
449
|
+
if status >= 500:
|
|
450
|
+
return ServiceUnavailableError(message, **kwargs)
|
|
451
|
+
return TubeTranscriptError(message, **kwargs)
|
|
452
|
+
|
|
453
|
+
|
|
454
|
+
def iter_features(names: Iterable[str]) -> List[str]:
|
|
455
|
+
"""Splits a comma-separated feature list (CLI helper)."""
|
|
456
|
+
return [part.strip() for name in names for part in name.split(",") if part.strip()]
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
"""Drop-in replacement for ``youtube_transcript_api.YouTubeTranscriptApi``.
|
|
2
|
+
|
|
3
|
+
Change one import and ``fetch()`` keeps working when YouTube blocks your server's IP (common on AWS, GCP, Azure,
|
|
4
|
+
Vercel and most VPS providers)::
|
|
5
|
+
|
|
6
|
+
# from youtube_transcript_api import YouTubeTranscriptApi
|
|
7
|
+
from tubetranscript import YouTubeTranscriptApi
|
|
8
|
+
|
|
9
|
+
fetched = YouTubeTranscriptApi().fetch("jNQXAC9IVRw")
|
|
10
|
+
|
|
11
|
+
The direct fetch runs first, exactly as in youtube-transcript-api. Only when it fails because the request was
|
|
12
|
+
blocked (and, if you opt in, because the video has no captions) does the call go to the TubeTranscript API, using
|
|
13
|
+
the key in ``TUBETRANSCRIPT_API_KEY``. The result is a regular ``FetchedTranscript``, so formatters and code that
|
|
14
|
+
read ``snippet.text``/``snippet.start`` keep working.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import warnings
|
|
20
|
+
from typing import Iterable, Optional, Tuple, Type
|
|
21
|
+
|
|
22
|
+
from requests import Session
|
|
23
|
+
from youtube_transcript_api import (
|
|
24
|
+
FailedToCreateConsentCookie,
|
|
25
|
+
FetchedTranscript,
|
|
26
|
+
FetchedTranscriptSnippet,
|
|
27
|
+
PoTokenRequired,
|
|
28
|
+
RequestBlocked,
|
|
29
|
+
TranscriptsDisabled,
|
|
30
|
+
YouTubeDataUnparsable,
|
|
31
|
+
YouTubeRequestFailed,
|
|
32
|
+
)
|
|
33
|
+
from youtube_transcript_api import YouTubeTranscriptApi as _UpstreamApi
|
|
34
|
+
from youtube_transcript_api.proxies import ProxyConfig
|
|
35
|
+
|
|
36
|
+
from ._client import API_KEY_ENV, DEFAULT_WAIT_SECONDS, TranscriptResult, TubeTranscript, logger
|
|
37
|
+
from ._errors import ConfigurationError, TubeTranscriptError
|
|
38
|
+
|
|
39
|
+
# Failures that come from YouTube refusing or confusing this machine (IP blocks including IpBlocked, PO token, consent
|
|
40
|
+
# or bot pages, any other HTTP error from YouTube), not from the video itself. Video-level errors (TranscriptsDisabled,
|
|
41
|
+
# NoTranscriptFound, VideoUnavailable, AgeRestricted, InvalidVideoId...) are re-raised unchanged.
|
|
42
|
+
BLOCKED_ERRORS: Tuple[Type[Exception], ...] = (
|
|
43
|
+
RequestBlocked,
|
|
44
|
+
PoTokenRequired,
|
|
45
|
+
FailedToCreateConsentCookie,
|
|
46
|
+
YouTubeDataUnparsable,
|
|
47
|
+
YouTubeRequestFailed,
|
|
48
|
+
)
|
|
49
|
+
|
|
50
|
+
_warned_missing_key = False
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class YouTubeTranscriptApi(_UpstreamApi):
|
|
54
|
+
"""``youtube_transcript_api.YouTubeTranscriptApi`` with a TubeTranscript fallback for ``fetch()``.
|
|
55
|
+
|
|
56
|
+
Extra keyword arguments (all optional):
|
|
57
|
+
|
|
58
|
+
- ``api_key``: TubeTranscript API key; defaults to the ``TUBETRANSCRIPT_API_KEY`` environment variable.
|
|
59
|
+
Without a key, the class behaves exactly like the original.
|
|
60
|
+
- ``fallback_on_no_captions``: also fall back when the video has captions disabled. The API then transcribes
|
|
61
|
+
the audio, which uses your plan's audio allowance and can take minutes. Default ``False``.
|
|
62
|
+
- ``try_direct_first``: set ``False`` to skip the direct request and always use the API (saves the wasted
|
|
63
|
+
round trip on servers YouTube always blocks). Default ``True``.
|
|
64
|
+
- ``client``: a ready :class:`tubetranscript.TubeTranscript` instance (overrides ``api_key``/``base_url``).
|
|
65
|
+
- ``wait``: seconds to keep resending while the API transcribes audio (see ``TubeTranscript.transcript``).
|
|
66
|
+
|
|
67
|
+
Only ``fetch()`` falls back. ``list()`` and translation still talk to YouTube directly.
|
|
68
|
+
|
|
69
|
+
Note: once a call reaches the API, the API itself transcribes the audio if the video turns out to have no
|
|
70
|
+
captions (it has no captions-only mode). ``fallback_on_no_captions`` only decides whether a direct
|
|
71
|
+
``TranscriptsDisabled`` result is sent to the API at all.
|
|
72
|
+
"""
|
|
73
|
+
|
|
74
|
+
def __init__(
|
|
75
|
+
self,
|
|
76
|
+
proxy_config: Optional[ProxyConfig] = None,
|
|
77
|
+
http_client: Optional[Session] = None,
|
|
78
|
+
*,
|
|
79
|
+
api_key: Optional[str] = None,
|
|
80
|
+
base_url: Optional[str] = None,
|
|
81
|
+
fallback_on_no_captions: bool = False,
|
|
82
|
+
try_direct_first: bool = True,
|
|
83
|
+
client: Optional[TubeTranscript] = None,
|
|
84
|
+
wait: float = DEFAULT_WAIT_SECONDS,
|
|
85
|
+
) -> None:
|
|
86
|
+
super().__init__(proxy_config=proxy_config, http_client=http_client)
|
|
87
|
+
self._client = client
|
|
88
|
+
self._wait = wait
|
|
89
|
+
self._api_key = api_key
|
|
90
|
+
self._base_url = base_url
|
|
91
|
+
self._fallback_on_no_captions = fallback_on_no_captions
|
|
92
|
+
self._try_direct_first = try_direct_first
|
|
93
|
+
|
|
94
|
+
def fetch(
|
|
95
|
+
self,
|
|
96
|
+
video_id: str,
|
|
97
|
+
languages: Iterable[str] = ("en",),
|
|
98
|
+
preserve_formatting: bool = False,
|
|
99
|
+
) -> FetchedTranscript:
|
|
100
|
+
"""Fetches a transcript; see the class docstring for when the TubeTranscript API is used.
|
|
101
|
+
|
|
102
|
+
On the fallback path ``languages`` and ``preserve_formatting`` are not applied: the API returns the video's
|
|
103
|
+
default transcript language, reported in ``FetchedTranscript.language_code``.
|
|
104
|
+
"""
|
|
105
|
+
if not self._try_direct_first:
|
|
106
|
+
return self._fetch_from_api(video_id, cause=None)
|
|
107
|
+
try:
|
|
108
|
+
return super().fetch(video_id, languages=languages, preserve_formatting=preserve_formatting)
|
|
109
|
+
except BLOCKED_ERRORS as error:
|
|
110
|
+
cause: Exception = error
|
|
111
|
+
except TranscriptsDisabled as error:
|
|
112
|
+
if not self._fallback_on_no_captions:
|
|
113
|
+
raise
|
|
114
|
+
cause = error
|
|
115
|
+
return self._fetch_from_api(video_id, cause=cause)
|
|
116
|
+
|
|
117
|
+
def _fetch_from_api(self, video_id: str, cause: Optional[Exception]) -> FetchedTranscript:
|
|
118
|
+
try:
|
|
119
|
+
client = self._get_client()
|
|
120
|
+
except ConfigurationError as error:
|
|
121
|
+
if cause is not None:
|
|
122
|
+
raise error from cause
|
|
123
|
+
raise
|
|
124
|
+
if client is None:
|
|
125
|
+
if cause is None:
|
|
126
|
+
raise ConfigurationError(
|
|
127
|
+
f"try_direct_first=False needs an API key: pass api_key=... or set {API_KEY_ENV}.",
|
|
128
|
+
code="MISSING_API_KEY",
|
|
129
|
+
)
|
|
130
|
+
_warn_missing_key()
|
|
131
|
+
raise cause
|
|
132
|
+
if cause is not None:
|
|
133
|
+
logger.debug("Direct fetch of %s failed with %s; using the TubeTranscript API",
|
|
134
|
+
video_id, type(cause).__name__)
|
|
135
|
+
try:
|
|
136
|
+
result = client.transcript(video_id, wait=self._wait)
|
|
137
|
+
except TubeTranscriptError as error:
|
|
138
|
+
if cause is not None:
|
|
139
|
+
raise error from cause
|
|
140
|
+
raise
|
|
141
|
+
return to_fetched_transcript(result, video_id)
|
|
142
|
+
|
|
143
|
+
def _get_client(self) -> Optional[TubeTranscript]:
|
|
144
|
+
if self._client is None:
|
|
145
|
+
try:
|
|
146
|
+
self._client = TubeTranscript(self._api_key, base_url=self._base_url)
|
|
147
|
+
except ConfigurationError as error:
|
|
148
|
+
if error.code == "MISSING_API_KEY":
|
|
149
|
+
return None
|
|
150
|
+
raise
|
|
151
|
+
return self._client
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def to_fetched_transcript(result: TranscriptResult, video_id: str) -> FetchedTranscript:
|
|
155
|
+
"""Converts an API result into youtube-transcript-api's ``FetchedTranscript``.
|
|
156
|
+
|
|
157
|
+
``is_generated`` is ``True`` when the API transcribed the audio (``audio`` and ``media`` sources). For captions
|
|
158
|
+
the API does not say whether they were uploaded or auto-generated, so it is ``False``; the same for
|
|
159
|
+
``existing_job``, whose origin the API does not report.
|
|
160
|
+
"""
|
|
161
|
+
language = result.language or ""
|
|
162
|
+
return FetchedTranscript(
|
|
163
|
+
snippets=[FetchedTranscriptSnippet(text=c.text, start=c.start, duration=c.duration) for c in result.chunks],
|
|
164
|
+
video_id=result.video_id or video_id,
|
|
165
|
+
language=language or "unknown",
|
|
166
|
+
language_code=language,
|
|
167
|
+
is_generated=result.source in ("audio", "media"),
|
|
168
|
+
)
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def _warn_missing_key() -> None:
|
|
172
|
+
global _warned_missing_key
|
|
173
|
+
if _warned_missing_key:
|
|
174
|
+
return
|
|
175
|
+
_warned_missing_key = True
|
|
176
|
+
warnings.warn(
|
|
177
|
+
f"YouTube blocked this request. Set {API_KEY_ENV} to fall back to the TubeTranscript API "
|
|
178
|
+
"(https://tubetranscript.io/youtube-transcript-api).",
|
|
179
|
+
RuntimeWarning,
|
|
180
|
+
stacklevel=4,
|
|
181
|
+
)
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
"""Errors raised by the TubeTranscript client.
|
|
2
|
+
|
|
3
|
+
Every error carries the API's ``code`` (for example ``RATE_LIMIT_EXCEEDED``), the HTTP ``status`` and, when the API
|
|
4
|
+
returned one, a partial ``data`` payload: a refused AI feature still comes with the transcript.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from typing import Any, Dict, Optional
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class TubeTranscriptError(Exception):
|
|
13
|
+
"""Base class for every error this package raises."""
|
|
14
|
+
|
|
15
|
+
def __init__(
|
|
16
|
+
self,
|
|
17
|
+
message: str,
|
|
18
|
+
*,
|
|
19
|
+
code: str = "UNKNOWN_ERROR",
|
|
20
|
+
status: Optional[int] = None,
|
|
21
|
+
details: Optional[Dict[str, Any]] = None,
|
|
22
|
+
data: Optional[Dict[str, Any]] = None,
|
|
23
|
+
) -> None:
|
|
24
|
+
super().__init__(message)
|
|
25
|
+
self.message = message
|
|
26
|
+
self.code = code
|
|
27
|
+
self.status = status
|
|
28
|
+
self.details = details or {}
|
|
29
|
+
self.data = data
|
|
30
|
+
|
|
31
|
+
def __str__(self) -> str:
|
|
32
|
+
prefix = f"[{self.status} {self.code}]" if self.status else f"[{self.code}]"
|
|
33
|
+
return f"{prefix} {self.message}"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class ConfigurationError(TubeTranscriptError):
|
|
37
|
+
"""The client is missing an API key or has an unusable base URL."""
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class AuthenticationError(TubeTranscriptError):
|
|
41
|
+
"""401: the API key is missing, unknown or revoked."""
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class PlanRequiredError(TubeTranscriptError):
|
|
45
|
+
"""403: the key's team is not on a plan that includes the API."""
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class InvalidRequestError(TubeTranscriptError):
|
|
49
|
+
"""400: the URL or the requested features were rejected."""
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class TranscriptNotFoundError(TubeTranscriptError):
|
|
53
|
+
"""404: the video is unavailable."""
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class ExtractionFailedError(TubeTranscriptError):
|
|
57
|
+
"""422: the video could not be transcribed (private, removed, no speech...)."""
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class RateLimitError(TubeTranscriptError):
|
|
61
|
+
"""429 (an allowance is used up) or 409 ``BUSY`` (another AI run of the team is in progress).
|
|
62
|
+
|
|
63
|
+
``retry_after`` is in seconds when the API sent it (not for ``WHISPER_LIMIT``/``MEDIA_LIMIT``). When the refusal
|
|
64
|
+
is about AI features, ``data`` still holds the transcript.
|
|
65
|
+
"""
|
|
66
|
+
|
|
67
|
+
def __init__(self, message: str, *, retry_after: Optional[float] = None, **kwargs: Any) -> None:
|
|
68
|
+
super().__init__(message, **kwargs)
|
|
69
|
+
self.retry_after = retry_after
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class ExtractionInProgressError(TubeTranscriptError):
|
|
73
|
+
"""The video has no captions and audio transcription was still running when the wait ran out.
|
|
74
|
+
|
|
75
|
+
Call again with the same URL later: the server resumes the same job, nothing is transcribed twice.
|
|
76
|
+
"""
|
|
77
|
+
|
|
78
|
+
@property
|
|
79
|
+
def job_id(self) -> Optional[str]:
|
|
80
|
+
return (self.data or {}).get("job_id")
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
class FeaturesFailedError(TubeTranscriptError):
|
|
84
|
+
"""502: some AI features failed. ``data`` still holds the transcript and the features that succeeded."""
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class ServiceUnavailableError(TubeTranscriptError):
|
|
88
|
+
"""5xx or a network failure: retry later."""
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.1.0"
|
tubetranscript/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: tubetranscript
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: YouTube transcripts that work from cloud servers. Drop-in fallback for youtube-transcript-api when YouTube blocks your IP, plus the TubeTranscript API client.
|
|
5
|
+
Project-URL: Homepage, https://tubetranscript.io/youtube-transcript-api
|
|
6
|
+
Project-URL: Documentation, https://tubetranscript.io/docs/api
|
|
7
|
+
Project-URL: Pricing, https://tubetranscript.io/pricing
|
|
8
|
+
Project-URL: Source, https://github.com/mrkenzi/tubetranscript-python
|
|
9
|
+
Project-URL: Issues, https://github.com/mrkenzi/tubetranscript-python/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/mrkenzi/tubetranscript-python/blob/main/CHANGELOG.md
|
|
11
|
+
Author: TubeTranscript
|
|
12
|
+
License-Expression: MIT
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Keywords: IpBlocked,RequestBlocked,captions,llm,rag,subtitles,transcript,whisper,youtube,youtube-transcript-api
|
|
15
|
+
Classifier: Development Status :: 4 - Beta
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
26
|
+
Classifier: Topic :: Multimedia :: Video
|
|
27
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
28
|
+
Classifier: Typing :: Typed
|
|
29
|
+
Requires-Python: >=3.9
|
|
30
|
+
Requires-Dist: requests>=2.25
|
|
31
|
+
Requires-Dist: urllib3>=1.26
|
|
32
|
+
Requires-Dist: youtube-transcript-api<2,>=1.2
|
|
33
|
+
Provides-Extra: dev
|
|
34
|
+
Requires-Dist: build; extra == 'dev'
|
|
35
|
+
Requires-Dist: mypy>=1.10; extra == 'dev'
|
|
36
|
+
Requires-Dist: pytest>=7; extra == 'dev'
|
|
37
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
38
|
+
Requires-Dist: twine; extra == 'dev'
|
|
39
|
+
Requires-Dist: types-requests; extra == 'dev'
|
|
40
|
+
Provides-Extra: test
|
|
41
|
+
Requires-Dist: pytest>=7; extra == 'test'
|
|
42
|
+
Description-Content-Type: text/markdown
|
|
43
|
+
|
|
44
|
+
# tubetranscript
|
|
45
|
+
|
|
46
|
+
YouTube transcripts that keep working on cloud servers.
|
|
47
|
+
|
|
48
|
+
If you use [`youtube-transcript-api`](https://github.com/jdepoix/youtube-transcript-api) on AWS, GCP, Azure, Vercel or a VPS, you have probably seen this:
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
youtube_transcript_api._errors.RequestBlocked: Could not retrieve a transcript for the video ...
|
|
52
|
+
YouTube is blocking requests from your IP.
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`tubetranscript` is a drop-in replacement. Change one import. The direct request to YouTube still runs first, at no cost. When YouTube blocks it, the call falls back to the [TubeTranscript API](https://tubetranscript.io/youtube-transcript-api) and you get back the same `FetchedTranscript` object.
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pip install tubetranscript
|
|
59
|
+
export TUBETRANSCRIPT_API_KEY=tt_live_... # create one at https://tubetranscript.io/dashboard/api
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
# from youtube_transcript_api import YouTubeTranscriptApi
|
|
64
|
+
from tubetranscript import YouTubeTranscriptApi
|
|
65
|
+
|
|
66
|
+
fetched = YouTubeTranscriptApi().fetch("jNQXAC9IVRw")
|
|
67
|
+
for snippet in fetched:
|
|
68
|
+
print(snippet.start, snippet.text)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Formatters from `youtube_transcript_api.formatters` work on the result unchanged. Requires Python 3.9+ and youtube-transcript-api 1.2+.
|
|
72
|
+
|
|
73
|
+
## Why YouTube blocks you
|
|
74
|
+
|
|
75
|
+
YouTube rate-limits and blocks requests from IP ranges that belong to cloud providers. Your code works on your laptop and fails in production. You can fix that yourself with rotating residential proxies (`youtube-transcript-api` supports them through `proxy_config`), or let an API do it for you. This package is the second option, and it only kicks in when the first request fails.
|
|
76
|
+
|
|
77
|
+
## Drop-in options
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
YouTubeTranscriptApi(
|
|
81
|
+
api_key=None, # default: TUBETRANSCRIPT_API_KEY
|
|
82
|
+
fallback_on_no_captions=False, # also send videos with captions disabled to the API
|
|
83
|
+
try_direct_first=True, # False: skip the direct request (servers YouTube always blocks)
|
|
84
|
+
wait=600, # seconds to keep waiting while the API transcribes audio
|
|
85
|
+
proxy_config=None, # passed to youtube-transcript-api as before
|
|
86
|
+
http_client=None, # passed to youtube-transcript-api as before
|
|
87
|
+
)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Without an API key the class behaves exactly like the original and raises the original errors, with a one-time hint. The one exception: `try_direct_first=False` without a key raises `ConfigurationError`.
|
|
91
|
+
|
|
92
|
+
**When it falls back.** On errors where YouTube refused or confused your machine: `RequestBlocked` (including `IpBlocked`), `PoTokenRequired`, `FailedToCreateConsentCookie`, `YouTubeDataUnparsable` and `YouTubeRequestFailed`. Errors about the video itself (`VideoUnavailable`, `AgeRestricted`, `NoTranscriptFound`, `InvalidVideoId`...) are raised unchanged. When the API call fails too, its error is raised with the original YouTube error as `__cause__`.
|
|
93
|
+
|
|
94
|
+
**Videos without captions.** With `fallback_on_no_captions=True`, a `TranscriptsDisabled` video is also sent to the API. Note that once a call reaches the API for any reason, the API transcribes the audio whenever the video has no captions. That uses your plan's audio allowance and can take minutes. The client keeps resending while it runs, for about `wait` seconds plus up to 5 minutes for the request in flight; each resend counts as one API request.
|
|
95
|
+
|
|
96
|
+
**Snippet length differs on the fallback path.** YouTube returns one snippet per on-screen caption line (a few seconds each). The API returns passages of about 15 to 30 seconds, cut at sentence ends, which suits LLM prompts. Code that reads `snippet.text`, `snippet.start` and `snippet.duration` keeps working; code that expects caption-line timing should not rely on it after a fallback.
|
|
97
|
+
|
|
98
|
+
**What the fallback does not do.** Only `fetch()` falls back. `list()` and `translate()` still talk to YouTube directly. On the fallback path, `languages` and `preserve_formatting` are not applied: you get the video's default transcript language, reported in `fetched.language_code` (empty when the API does not know it). `is_generated` is `True` when the API transcribed the audio, and `False` for captions, because the API does not say whether they were uploaded or auto-generated.
|
|
99
|
+
|
|
100
|
+
## Using the API directly
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
from tubetranscript import TubeTranscript
|
|
104
|
+
|
|
105
|
+
with TubeTranscript() as client: # reads TUBETRANSCRIPT_API_KEY
|
|
106
|
+
result = client.transcript("https://www.youtube.com/watch?v=jNQXAC9IVRw", features=["hooks"])
|
|
107
|
+
|
|
108
|
+
print(result.source) # "captions", "audio", "media" or "existing_job"
|
|
109
|
+
print(result.text)
|
|
110
|
+
print(result.chunks[0]) # Chunk(text=..., start=0.0, duration=4.2)
|
|
111
|
+
print(result.features["hooks"])
|
|
112
|
+
print(result.rate_limit_remaining)
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
`result.chunks` are passages of about 15 to 30 seconds. `transcript()` accepts a YouTube video ID or URL (`watch`, `youtu.be`, `shorts`, `embed`, `live`) and TikTok, Instagram and Facebook video links. For those, `result.video_id` is an internal key, not the platform's ID. `features` can include `hooks`, `mindmap` and `action_items`.
|
|
116
|
+
|
|
117
|
+
Call `client.close()` when done, or use the client as a context manager. The client uses a `requests.Session`; sharing one between threads works in practice, and one client per thread is the strict-safe choice.
|
|
118
|
+
|
|
119
|
+
### Retries
|
|
120
|
+
|
|
121
|
+
Transient failures are retried twice by default, with exponential backoff and jitter:
|
|
122
|
+
|
|
123
|
+
- Always, because the API cannot have counted the request: no connection could be made (DNS, refused, connect timeout) and `RATE_LIMIT_UNAVAILABLE`.
|
|
124
|
+
- Only for calls without `features`: a connection dropped after the request was sent, and a 502/503 page from the gateway in front of the API. These may already have counted one request; with `features` they could also have charged AI runs, so they are not resent.
|
|
125
|
+
|
|
126
|
+
Quota refusals (429), `WORKER_UNAVAILABLE` (maintenance, usually minutes), other 5xx errors and read timeouts are not retried. Set `TubeTranscript(max_retries=0)` to turn retries off.
|
|
127
|
+
|
|
128
|
+
### Errors
|
|
129
|
+
|
|
130
|
+
Every error is a `TubeTranscriptError` with `.code`, `.status`, `.message`, `.details` and, when the API sent one, `.data`.
|
|
131
|
+
|
|
132
|
+
| Exception | When |
|
|
133
|
+
|---|---|
|
|
134
|
+
| `ConfigurationError` | No API key, a key not in the `tt_live_` format, a non-https base URL, or a base URL that redirects |
|
|
135
|
+
| `AuthenticationError` | Unknown or revoked key (401) |
|
|
136
|
+
| `PlanRequiredError` | The key's team is not on Pro or Enterprise (403) |
|
|
137
|
+
| `InvalidRequestError` | The URL or the features were rejected (400) |
|
|
138
|
+
| `RateLimitError` | Allowance used up (429), or another AI run of your team is in progress (409 `BUSY`); see `.retry_after` |
|
|
139
|
+
| `TranscriptNotFoundError` | Video unavailable (404) |
|
|
140
|
+
| `ExtractionFailedError` | Private, removed, no speech (422) |
|
|
141
|
+
| `ExtractionInProgressError` | Audio transcription still running after `wait` seconds. Call again with the same URL; the job resumes. See `.job_id` |
|
|
142
|
+
| `FeaturesFailedError` | Some AI features failed (502); `.data` has the transcript and the features that worked |
|
|
143
|
+
| `ServiceUnavailableError` | 5xx, network failure or read timeout, after retries |
|
|
144
|
+
| `TubeTranscriptError` (base) | Anything else, for example `UNEXPECTED_RESPONSE` (a non-API page, usually a wrong `base_url`) |
|
|
145
|
+
|
|
146
|
+
When you asked for `features` and the API refuses or fails them (409, 429, 502 or 503 about AI), the transcript is still in `error.data["transcript"]`.
|
|
147
|
+
|
|
148
|
+
### Logging
|
|
149
|
+
|
|
150
|
+
The package logs fallbacks, retries and waits at `DEBUG` on the `tubetranscript` logger. It never logs the API key or transcript text.
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
import logging
|
|
154
|
+
logging.basicConfig()
|
|
155
|
+
logging.getLogger("tubetranscript").setLevel(logging.DEBUG)
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## Command line
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
tubetranscript https://youtu.be/jNQXAC9IVRw
|
|
162
|
+
tubetranscript jNQXAC9IVRw --format srt > video.srt
|
|
163
|
+
tubetranscript jNQXAC9IVRw --features hooks,mindmap # JSON
|
|
164
|
+
tubetranscript jNQXAC9IVRw -v # log retries and waits
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
## Pricing
|
|
168
|
+
|
|
169
|
+
The direct path is free. The fallback needs an API key from the TubeTranscript Pro or Enterprise plan; see [pricing](https://tubetranscript.io/pricing) for current limits.
|
|
170
|
+
|
|
171
|
+
## Security and privacy
|
|
172
|
+
|
|
173
|
+
- The key is read from the argument or `TUBETRANSCRIPT_API_KEY`, sent only in the `Authorization` header (a `~/.netrc` entry cannot replace it), and never logged or included in error messages or `repr()`. Network exceptions chained as `__cause__` have their request stripped, so error trackers do not capture the header.
|
|
174
|
+
- Requests go to `https://tubetranscript.io` only when the client falls back. `TUBETRANSCRIPT_BASE_URL` can point elsewhere: https only (http for localhost), no credentials in the URL. Redirects are never followed, so the key cannot be forwarded to another address.
|
|
175
|
+
- The direct path is youtube-transcript-api's own code; nothing from it is sent to TubeTranscript.
|
|
176
|
+
|
|
177
|
+
Report a security issue privately to support@tubetranscript.io (subject: "Security"), not in a public issue.
|
|
178
|
+
|
|
179
|
+
## Contributing
|
|
180
|
+
|
|
181
|
+
Issues and pull requests are welcome at https://github.com/mrkenzi/tubetranscript-python. The package is developed alongside the TubeTranscript service and synced to this repository, so an accepted pull request is applied upstream and arrives back here in the next sync, credited to you.
|
|
182
|
+
|
|
183
|
+
## Disclosure
|
|
184
|
+
|
|
185
|
+
This package is made by the team behind TubeTranscript. It is not affiliated with `youtube-transcript-api` or its author, whose library does the direct fetching here and is a dependency of this package.
|
|
186
|
+
|
|
187
|
+
MIT License.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
tubetranscript/__init__.py,sha256=fK-PLhub_tEqnmimUQ53fCCXOcxxkM-griT0JPs3DZk,1586
|
|
2
|
+
tubetranscript/__main__.py,sha256=arq9FhDc5f2AZchKpqlkQwTT-bKvMcj3iAXJg8GRLCc,53
|
|
3
|
+
tubetranscript/_cli.py,sha256=WvupN2c4UOws_0jso_OxhQsvxibfBNDZcQywZJ2shno,3048
|
|
4
|
+
tubetranscript/_client.py,sha256=04KTJs0UV4m9KLAHW9gsJGQtG9zQjDS3CnggR3ejsOk,20300
|
|
5
|
+
tubetranscript/_compat.py,sha256=VrUGvAP4zrdwkJKLvsMhvewAgZGx9jKSj6yLmK-Iolg,7697
|
|
6
|
+
tubetranscript/_errors.py,sha256=d7vm5vT9gZez2-JaabCCZBsTozvDBMuR-TwOBnmTCJg,2869
|
|
7
|
+
tubetranscript/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
|
|
8
|
+
tubetranscript/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
9
|
+
tubetranscript-0.1.0.dist-info/METADATA,sha256=AuOtcjHEd2j9x-pCpEP6xRzoYL7sg5fxUHv0I1AtZCc,11361
|
|
10
|
+
tubetranscript-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
11
|
+
tubetranscript-0.1.0.dist-info/entry_points.txt,sha256=F-8MdLZk8AtmqAFCCB6tTIE-jsADg0Jtg6ToC1GIqNY,60
|
|
12
|
+
tubetranscript-0.1.0.dist-info/licenses/LICENSE,sha256=Twi5V7nqMyaEPUf99ugZxHnWW3Y12zheXcWp8bMc4LE,1071
|
|
13
|
+
tubetranscript-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 TubeTranscript
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|