tubetranscript 0.1.0__tar.gz
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-0.1.0/.gitignore +6 -0
- tubetranscript-0.1.0/CHANGELOG.md +8 -0
- tubetranscript-0.1.0/LICENSE +21 -0
- tubetranscript-0.1.0/PKG-INFO +187 -0
- tubetranscript-0.1.0/README.md +144 -0
- tubetranscript-0.1.0/pyproject.toml +80 -0
- tubetranscript-0.1.0/src/tubetranscript/__init__.py +50 -0
- tubetranscript-0.1.0/src/tubetranscript/__main__.py +5 -0
- tubetranscript-0.1.0/src/tubetranscript/_cli.py +74 -0
- tubetranscript-0.1.0/src/tubetranscript/_client.py +456 -0
- tubetranscript-0.1.0/src/tubetranscript/_compat.py +181 -0
- tubetranscript-0.1.0/src/tubetranscript/_errors.py +88 -0
- tubetranscript-0.1.0/src/tubetranscript/_version.py +1 -0
- tubetranscript-0.1.0/src/tubetranscript/py.typed +0 -0
- tubetranscript-0.1.0/tests/conftest.py +84 -0
- tubetranscript-0.1.0/tests/test_client.py +190 -0
- tubetranscript-0.1.0/tests/test_compat.py +188 -0
- tubetranscript-0.1.0/tests/test_hardening.py +312 -0
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 (2026-11-15)
|
|
4
|
+
|
|
5
|
+
- `YouTubeTranscriptApi`: drop-in for youtube-transcript-api 1.2+. `fetch()` falls back to the TubeTranscript API on `RequestBlocked`, `IpBlocked`, `PoTokenRequired`, `FailedToCreateConsentCookie`, `YouTubeDataUnparsable` and `YouTubeRequestFailed`; optionally on `TranscriptsDisabled`.
|
|
6
|
+
- `TubeTranscript` client for `POST /api/v1/extract`: typed errors, waiting while audio transcription runs, retries with backoff for transient failures, no redirects, API key format check before any request.
|
|
7
|
+
- `tubetranscript` command: text, JSON or SRT output, `-v` for debug logs.
|
|
8
|
+
- Debug logging on the `tubetranscript` logger; the key and transcript text are never logged.
|
|
@@ -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.
|
|
@@ -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,144 @@
|
|
|
1
|
+
# tubetranscript
|
|
2
|
+
|
|
3
|
+
YouTube transcripts that keep working on cloud servers.
|
|
4
|
+
|
|
5
|
+
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:
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
youtube_transcript_api._errors.RequestBlocked: Could not retrieve a transcript for the video ...
|
|
9
|
+
YouTube is blocking requests from your IP.
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
`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.
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
pip install tubetranscript
|
|
16
|
+
export TUBETRANSCRIPT_API_KEY=tt_live_... # create one at https://tubetranscript.io/dashboard/api
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
# from youtube_transcript_api import YouTubeTranscriptApi
|
|
21
|
+
from tubetranscript import YouTubeTranscriptApi
|
|
22
|
+
|
|
23
|
+
fetched = YouTubeTranscriptApi().fetch("jNQXAC9IVRw")
|
|
24
|
+
for snippet in fetched:
|
|
25
|
+
print(snippet.start, snippet.text)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Formatters from `youtube_transcript_api.formatters` work on the result unchanged. Requires Python 3.9+ and youtube-transcript-api 1.2+.
|
|
29
|
+
|
|
30
|
+
## Why YouTube blocks you
|
|
31
|
+
|
|
32
|
+
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.
|
|
33
|
+
|
|
34
|
+
## Drop-in options
|
|
35
|
+
|
|
36
|
+
```python
|
|
37
|
+
YouTubeTranscriptApi(
|
|
38
|
+
api_key=None, # default: TUBETRANSCRIPT_API_KEY
|
|
39
|
+
fallback_on_no_captions=False, # also send videos with captions disabled to the API
|
|
40
|
+
try_direct_first=True, # False: skip the direct request (servers YouTube always blocks)
|
|
41
|
+
wait=600, # seconds to keep waiting while the API transcribes audio
|
|
42
|
+
proxy_config=None, # passed to youtube-transcript-api as before
|
|
43
|
+
http_client=None, # passed to youtube-transcript-api as before
|
|
44
|
+
)
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
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`.
|
|
48
|
+
|
|
49
|
+
**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__`.
|
|
50
|
+
|
|
51
|
+
**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.
|
|
52
|
+
|
|
53
|
+
**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.
|
|
54
|
+
|
|
55
|
+
**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.
|
|
56
|
+
|
|
57
|
+
## Using the API directly
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from tubetranscript import TubeTranscript
|
|
61
|
+
|
|
62
|
+
with TubeTranscript() as client: # reads TUBETRANSCRIPT_API_KEY
|
|
63
|
+
result = client.transcript("https://www.youtube.com/watch?v=jNQXAC9IVRw", features=["hooks"])
|
|
64
|
+
|
|
65
|
+
print(result.source) # "captions", "audio", "media" or "existing_job"
|
|
66
|
+
print(result.text)
|
|
67
|
+
print(result.chunks[0]) # Chunk(text=..., start=0.0, duration=4.2)
|
|
68
|
+
print(result.features["hooks"])
|
|
69
|
+
print(result.rate_limit_remaining)
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
`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`.
|
|
73
|
+
|
|
74
|
+
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.
|
|
75
|
+
|
|
76
|
+
### Retries
|
|
77
|
+
|
|
78
|
+
Transient failures are retried twice by default, with exponential backoff and jitter:
|
|
79
|
+
|
|
80
|
+
- Always, because the API cannot have counted the request: no connection could be made (DNS, refused, connect timeout) and `RATE_LIMIT_UNAVAILABLE`.
|
|
81
|
+
- 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.
|
|
82
|
+
|
|
83
|
+
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.
|
|
84
|
+
|
|
85
|
+
### Errors
|
|
86
|
+
|
|
87
|
+
Every error is a `TubeTranscriptError` with `.code`, `.status`, `.message`, `.details` and, when the API sent one, `.data`.
|
|
88
|
+
|
|
89
|
+
| Exception | When |
|
|
90
|
+
|---|---|
|
|
91
|
+
| `ConfigurationError` | No API key, a key not in the `tt_live_` format, a non-https base URL, or a base URL that redirects |
|
|
92
|
+
| `AuthenticationError` | Unknown or revoked key (401) |
|
|
93
|
+
| `PlanRequiredError` | The key's team is not on Pro or Enterprise (403) |
|
|
94
|
+
| `InvalidRequestError` | The URL or the features were rejected (400) |
|
|
95
|
+
| `RateLimitError` | Allowance used up (429), or another AI run of your team is in progress (409 `BUSY`); see `.retry_after` |
|
|
96
|
+
| `TranscriptNotFoundError` | Video unavailable (404) |
|
|
97
|
+
| `ExtractionFailedError` | Private, removed, no speech (422) |
|
|
98
|
+
| `ExtractionInProgressError` | Audio transcription still running after `wait` seconds. Call again with the same URL; the job resumes. See `.job_id` |
|
|
99
|
+
| `FeaturesFailedError` | Some AI features failed (502); `.data` has the transcript and the features that worked |
|
|
100
|
+
| `ServiceUnavailableError` | 5xx, network failure or read timeout, after retries |
|
|
101
|
+
| `TubeTranscriptError` (base) | Anything else, for example `UNEXPECTED_RESPONSE` (a non-API page, usually a wrong `base_url`) |
|
|
102
|
+
|
|
103
|
+
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"]`.
|
|
104
|
+
|
|
105
|
+
### Logging
|
|
106
|
+
|
|
107
|
+
The package logs fallbacks, retries and waits at `DEBUG` on the `tubetranscript` logger. It never logs the API key or transcript text.
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
import logging
|
|
111
|
+
logging.basicConfig()
|
|
112
|
+
logging.getLogger("tubetranscript").setLevel(logging.DEBUG)
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## Command line
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
tubetranscript https://youtu.be/jNQXAC9IVRw
|
|
119
|
+
tubetranscript jNQXAC9IVRw --format srt > video.srt
|
|
120
|
+
tubetranscript jNQXAC9IVRw --features hooks,mindmap # JSON
|
|
121
|
+
tubetranscript jNQXAC9IVRw -v # log retries and waits
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Pricing
|
|
125
|
+
|
|
126
|
+
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.
|
|
127
|
+
|
|
128
|
+
## Security and privacy
|
|
129
|
+
|
|
130
|
+
- 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.
|
|
131
|
+
- 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.
|
|
132
|
+
- The direct path is youtube-transcript-api's own code; nothing from it is sent to TubeTranscript.
|
|
133
|
+
|
|
134
|
+
Report a security issue privately to support@tubetranscript.io (subject: "Security"), not in a public issue.
|
|
135
|
+
|
|
136
|
+
## Contributing
|
|
137
|
+
|
|
138
|
+
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.
|
|
139
|
+
|
|
140
|
+
## Disclosure
|
|
141
|
+
|
|
142
|
+
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.
|
|
143
|
+
|
|
144
|
+
MIT License.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "tubetranscript"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "YouTube transcripts that work from cloud servers. Drop-in fallback for youtube-transcript-api when YouTube blocks your IP, plus the TubeTranscript API client."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.9"
|
|
13
|
+
authors = [{ name = "TubeTranscript" }]
|
|
14
|
+
keywords = [
|
|
15
|
+
"youtube", "transcript", "subtitles", "captions", "youtube-transcript-api",
|
|
16
|
+
"RequestBlocked", "IpBlocked", "whisper", "llm", "rag",
|
|
17
|
+
]
|
|
18
|
+
classifiers = [
|
|
19
|
+
"Development Status :: 4 - Beta",
|
|
20
|
+
"Intended Audience :: Developers",
|
|
21
|
+
"Operating System :: OS Independent",
|
|
22
|
+
"Programming Language :: Python :: 3",
|
|
23
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
24
|
+
"Programming Language :: Python :: 3.9",
|
|
25
|
+
"Programming Language :: Python :: 3.10",
|
|
26
|
+
"Programming Language :: Python :: 3.11",
|
|
27
|
+
"Programming Language :: Python :: 3.12",
|
|
28
|
+
"Programming Language :: Python :: 3.13",
|
|
29
|
+
"Programming Language :: Python :: 3.14",
|
|
30
|
+
"Topic :: Multimedia :: Video",
|
|
31
|
+
"Topic :: Software Development :: Libraries",
|
|
32
|
+
"Typing :: Typed",
|
|
33
|
+
]
|
|
34
|
+
dependencies = [
|
|
35
|
+
"requests>=2.25",
|
|
36
|
+
"urllib3>=1.26",
|
|
37
|
+
"youtube-transcript-api>=1.2,<2",
|
|
38
|
+
]
|
|
39
|
+
|
|
40
|
+
[project.optional-dependencies]
|
|
41
|
+
test = ["pytest>=7"]
|
|
42
|
+
dev = ["pytest>=7", "mypy>=1.10", "ruff>=0.6", "types-requests", "build", "twine"]
|
|
43
|
+
|
|
44
|
+
[project.urls]
|
|
45
|
+
Homepage = "https://tubetranscript.io/youtube-transcript-api"
|
|
46
|
+
Documentation = "https://tubetranscript.io/docs/api"
|
|
47
|
+
Pricing = "https://tubetranscript.io/pricing"
|
|
48
|
+
Source = "https://github.com/mrkenzi/tubetranscript-python"
|
|
49
|
+
Issues = "https://github.com/mrkenzi/tubetranscript-python/issues"
|
|
50
|
+
Changelog = "https://github.com/mrkenzi/tubetranscript-python/blob/main/CHANGELOG.md"
|
|
51
|
+
|
|
52
|
+
[project.scripts]
|
|
53
|
+
tubetranscript = "tubetranscript._cli:main"
|
|
54
|
+
|
|
55
|
+
[tool.hatch.version]
|
|
56
|
+
path = "src/tubetranscript/_version.py"
|
|
57
|
+
|
|
58
|
+
[tool.hatch.build.targets.wheel]
|
|
59
|
+
packages = ["src/tubetranscript"]
|
|
60
|
+
|
|
61
|
+
[tool.hatch.build.targets.sdist]
|
|
62
|
+
include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
|
|
63
|
+
|
|
64
|
+
[tool.pytest.ini_options]
|
|
65
|
+
testpaths = ["tests"]
|
|
66
|
+
|
|
67
|
+
[tool.mypy]
|
|
68
|
+
strict = true
|
|
69
|
+
files = ["src"]
|
|
70
|
+
|
|
71
|
+
[tool.ruff]
|
|
72
|
+
target-version = "py39"
|
|
73
|
+
line-length = 120
|
|
74
|
+
src = ["src", "tests"]
|
|
75
|
+
|
|
76
|
+
[tool.ruff.lint]
|
|
77
|
+
select = ["E", "F", "W", "B", "SIM", "S", "RUF"]
|
|
78
|
+
|
|
79
|
+
[tool.ruff.lint.per-file-ignores]
|
|
80
|
+
"tests/*" = ["S101", "S105", "S106", "B017", "E501"]
|
|
@@ -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,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())
|