gemini-transcribe-wrapper
A free video transcription CLI using gemini-3.5-transcribe that outputs .diarized.srt, .srt, and .txt files.
Quick Start
Prerequisites
- Get an API key from https://aistudio.google.com/api-keys/ for free.
- Install uv (https://docs.astral.sh/uv/getting-started/installation/).
Install or upgrade the tool
(Supports Python 3.10–3.13; Python 3.12 is recommended)
Method 1: The wrapper is best run via uvx (one-shot, no install step — recommended for free-tier multi-key usage where each run spreads load differently):
Linux / macOS / Windows:
uvx --python 3.12 --from gemini-transcribe-wrapper@latest gtw --gemini-api-keys "<api keys separated by comma or semicolon>" -h
Method 2: For a persistent install (so you can run gtw directly without uvx ...):
Linux / macOS / Windows:
uv tool install --python 3.12 gemini-transcribe-wrapper@latest
gtw --gemini-api-keys "<api keys separated by comma or semicolon>" -h
Transcribe for free
gtw --gemini-api-keys "<api keys separated by comma or semicolon>" /path/to/sample.mp4
Output (default: --diarized-srt-file auto — with speaker diarization):
sample.diarized.transcript.json
sample.diarized.srt
sample.srt
sample.txt
What are improved by this project?
1. Transcription Quality & Usability
- Raw AI Output to Ready-to-Use Subtitles: Converts JSON transcription output directly into formatted
.srt(with natural timestamp alignment and line breaking), readable.txtparagraphs, and.diarized.srtfiles in a single run. - Korean Transcription Error Correction: Automatically post-processes common Gemini Korean misrecognitions (e.g. correcting erroneous romanized
"su"into"수"in patterns like"~할 su 있다/없다","~할 su밖에","~할 su도","~할 su가"with proper Korean spacing and particle attachment). - Fast Speaker Labeling: Allows iterative speaker renaming (
--speakers-txt-file, automatically picking up.speakers.txt) instantly without re-calling the API by reusing saved transcripts.
2. Overcoming Free-Tier Limits & Constraints
- Audio Length Limit Bypass: Handles audio files of any length by auto-splitting into safe units (30-min chunks by default for subtitles, 60-min chunks when only
.txtis output via--diarized-srt-file=off --srt-file=off) and transparently stitching timestamps together. - Rate Limit Throttling (Max 2 RPM): Applies a monotonic rate limiter (default 120s interval on free tier) across all chunks and multi-file batches to prevent 429 rate-limit errors.
- Daily Quota Tracking: Tracks daily Pacific-time API usage locally (
~/.cache/gemini-transcribe-wrapper/usage-<sha256(key)[:12]>.json) with masked key logging (e.g.API call attempts today 2026-08-30 (PT) with key 'AIza****abcd': attempted 3 (free tier limit: ~25)). - Multi-Key Round-Robin + Active/Cooldown Pool: Pass multiple keys with
--gemini-api-keys=KEY1,KEY2,.... The wrapper tracks active keys and keys in cooldown upon 429 errors. When all keys hit 429, it waits 600s before reloading keys into the live pool and retrying. Key usage state is persisted across runs in~/.cache/gemini-transcribe-wrapper/last-used-api-key.jsonto rotate evenly. With 16–20 free-tier keys (2 Gmail accounts × 10 projects each) you can run continuously even when most keys have hit the daily cap. See Multi-Key Strategy for sizing guidance. - Key File with Hot Reload:
--gemini-api-keys-file PATHreads one key per line (defaults to./gemini-api-keys.txt, falling back to~/.config/gemini-transcribe-wrapper/gemini-api-keys.txt). On Linux/macOS the file must bechmod 600or the run aborts with the exact fix command. The file is watched during the run — edit it to add or retire keys and the rotation reloads every key before the next pick, resuming at the key that follows the last used one in the new file order. - Graceful 429 Abort (single key): On HTTP 429 (rate limit or quota exhausted) when running with a single key, calculates the exact sleep seconds until the Pacific midnight reset and aborts the batch gracefully.
- Custom Vocabulary File (
--vocab-txt-file): Register company-internal / frequently-misrecognized terms in a plain text file (one per line) and the wrapper biases the transcript toward those terms as a post-recognition step. Defaults toautowhich automatically picks up.vocab.txt(or<stem>.vocab.txt) when present. Up to 1000 words are accepted by the model; Google recommends ≤100 lines for best results. See Custom Vocabulary for details. - Multi-Language Hint (
--language-codes): Forward a comma-separated list of BCP-47 codes (defaultko-KR;en-US) to Gemini aslanguage_codes. Pass an empty string (--language-codes="") to enable Gemini's auto language detection for mixed-language content. See Language Hints for details.
Documentation & Guides
- On Quota / Rate-Limit (HTTP 429)
- Multi-Key Strategy (active/cooldown pool)
- Custom Vocabulary File
- Language Hints (
--language-codes) - Batch Bulk Transcribing Tip
- Diarizing Tip (Speaker Labels)
Relevant Repositories
- https://github.com/tayaee/gemini-transcribe-wrapper
- https://pypi.org/project/gemini-transcribe-wrapper
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for gemini-transcribe-wrapper 0.1.13
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| gemini_transcribe_wrapper-0.1.13.tar.gz | 93.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| gemini_transcribe_wrapper-0.1.13-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 93.6 MB
Release files / gemini_transcribe_wrapper-0.1.13.tar.gz
| Download URL | gemini_transcribe_wrapper-0.1.13.tar.gz |
|---|---|
| Size | 93.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a66b7995bddb87cb1fdc4d43940695a44d87269f87e76921bb2f4596e87be8e1
|
|
BLAKE2b-256 checksum How to use checksums |
b20adc8a189538bd9f13b92de98367a967790970d2506c4d3cb3ec25cd3a5b72
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / gemini_transcribe_wrapper-0.1.13-py3-none-any.whl
| Download URL | gemini_transcribe_wrapper-0.1.13-py3-none-any.whl |
|---|---|
| Size | 82.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4fe7ffa4c109f2c399f12f1e63976404290b4b24c2334eb00e42a18932ec37a8
|
|
BLAKE2b-256 checksum How to use checksums |
9980bfa36fe6b818076ca57070bc44c80e3aedf4694ab52ae1619ccec3037dc6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency log
