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.
@@ -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
+ ]
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from ._cli import main
4
+
5
+ sys.exit(main())
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"
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,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ tubetranscript = tubetranscript._cli:main
@@ -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.