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.
@@ -0,0 +1,6 @@
1
+ dist/
2
+ build/
3
+ *.egg-info/
4
+ __pycache__/
5
+ .pytest_cache/
6
+ .venv/
@@ -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,5 @@
1
+ import sys
2
+
3
+ from ._cli import main
4
+
5
+ sys.exit(main())
@@ -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())