gemini-transcribe-wrapper

A free video transcription CLI using gemini-3.5-transcribe that outputs .diarized.srt, .srt, and .txt files.

Quick Start

Prerequisites

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 .txt paragraphs, and .diarized.srt files 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 .txt is 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.json to 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 PATH reads one key per line (defaults to ./gemini-api-keys.txt when present). On Linux/macOS the file must be chmod 600 or 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 to auto which 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 (default ko-KR;en-US) to Gemini as language_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

Relevant Repositories

License

MIT

Project links

Data verified by PyPI on Sep 4, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.10)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for tayaee from gravatar.com tayaee

Credits

Author: tayaee

GitHub Statistics

Data verified by PyPI on Sep 4, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Tags

diarization gemini speech-to-text srt stt subtitles transcription

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gemini_transcribe_wrapper-0.1.9.tar.gz (93.5 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

gemini_transcribe_wrapper-0.1.9-py3-none-any.whl (80.9 kB view details)

Uploaded Python 3

File details

Details for the file gemini_transcribe_wrapper-0.1.9.tar.gz.

File metadata

File hashes

Hashes for gemini_transcribe_wrapper-0.1.9.tar.gz
Algorithm Hash digest
SHA256 5fdcf3ff6b08cac5ab779a3da393ae20843bb69fffc65daa233f6c98fab249f8
MD5 89e1a34fd41dae6a8bcbf2ab883fec39
BLAKE2b-256 86b7d2ae20cc4dd857e0e0f2b0ea794e006536b65cc77ddce0ff6ae9dd6c1968

See more details on using hashes here.

Provenance

The following attestation bundles were made for gemini_transcribe_wrapper-0.1.9.tar.gz:

Publisher: publish.yml on tayaee/gemini-transcribe-wrapper

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gemini_transcribe_wrapper-0.1.9-py3-none-any.whl.

File metadata

File hashes

Hashes for gemini_transcribe_wrapper-0.1.9-py3-none-any.whl
Algorithm Hash digest
SHA256 11ffcdc0cff05b32e27557c37b444c26be06e207cc0423b3f648c60a02ff58de
MD5 9325ed0cae8b9e9a6f6c10f56c8b945c
BLAKE2b-256 d8ff53a1121f7c541fa3bd6366e9bb0a674bf3d6f766dc11c1511116581db183

See more details on using hashes here.

Provenance

The following attestation bundles were made for gemini_transcribe_wrapper-0.1.9-py3-none-any.whl:

Publisher: publish.yml on tayaee/gemini-transcribe-wrapper

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.10

2 files

This release

0.1.9 This release

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.69

2 files

0.0.68

2 files

0.0.67

2 files

0.0.66

2 files

0.0.65

2 files

0.0.64

2 files

0.0.63

2 files

0.0.62

2 files

0.0.61

2 files

0.0.60

2 files

0.0.59

2 files

0.0.58

2 files

0.0.57

2 files

0.0.56

2 files

0.0.55

2 files

0.0.54

2 files

0.0.53

2 files

0.0.52

2 files

0.0.51

2 files

0.0.50

2 files

0.0.49

2 files

0.0.48

2 files

0.0.47

2 files

0.0.46

2 files

0.0.45

2 files

0.0.44

2 files

0.0.43

2 files

0.0.42

2 files

0.0.41

2 files

0.0.40

2 files

0.0.39

2 files

0.0.38

2 files

0.0.37

2 files

0.0.35

2 files

0.0.34

2 files

0.0.32

2 files

0.0.31

2 files

0.0.30

2 files

0.0.29

2 files

0.0.28

2 files

0.0.27

2 files

0.0.26

2 files

0.0.25

2 files

0.0.24

2 files

0.0.23

2 files

0.0.22

2 files

0.0.21

2 files

0.0.20

2 files

0.0.19

2 files

0.0.18

2 files

0.0.17

2 files

0.0.16

2 files

0.0.15

2 files

0.0.14

2 files

0.0.13

2 files

0.0.12

2 files

0.0.11

2 files

0.0.10

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page