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 the tool

(Supports Python 3.10–3.13; Python 3.12 is recommended)

Linux / macOS:

export GEMINI_API_KEY=your_key_here
uv tool install --python 3.12 gemini-transcribe-wrapper@latest
gtw -v

Windows (Command Prompt):

set GEMINI_API_KEY=your_key_here
uv tool install --python 3.12 gemini-transcribe-wrapper@latest
gtw -v

Transcribe for free

gtw sample.mp4   # with `GEMINI_API_KEY` set
# or
gtw --gemini-api-key YOUR_API_KEY sample.mp4
# or, with multiple keys for round-robin + 429 fallback:
gtw --gemini-api-keys KEY1,KEY2,KEY3 sample.mp4

Output (default: --no-diarize — no speaker labels, fewer API calls):

sample.transcript.json
sample.srt
sample.txt

For speaker-diarized output, opt in with --diarize:

gtw --diarize sample.mp4

Output (with --diarize):

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 (with --diarize) .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 'spk:0=Host;spk:1=Guest') 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 (59-min logical units for --no-diarize, 29-min chunks for --diarize) and transparently stitching timestamps together.
  • Rate Limit Throttling (Max 2 RPM): Applies a monotonic rate limiter (default 60s interval) 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 calls today 2026-08-30 (PST-08:00) with key 'AIza****abcd': attempted 3 (free tier limit: ~25)).
  • Free-Tier-Friendly Defaults: --no-diarize is the default to maximize audio duration per API call and minimize API consumption.
  • Multi-Key Round-Robin + 429 Fallback: Pass several keys with --gemini-api-keys=KEY1,KEY2,.... The wrapper cycles keys in round-robin order across chunks; on a 429 with retry hint it cools down on the current key once and retries, then falls through to the next key. All keys exhausted → graceful abort with exit code 2. See Multi-Key Strategy for details.
  • Graceful 429 Abort: 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 immediately (exit code 2) to prevent wasting quota.

Documentation & Guides

Relevant Repositories

License

MIT

Project links

Data verified by PyPI on Aug 31, 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 Aug 31, 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.0.50.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.0.50-py3-none-any.whl (50.0 kB view details)

Uploaded Python 3

File details

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

File metadata

File hashes

Hashes for gemini_transcribe_wrapper-0.0.50.tar.gz
Algorithm Hash digest
SHA256 09c07bad6ba949f01c5c70e7eba9dac73ddc9bd87e7f70d61bd8532ed3ef8c73
MD5 70ddf026c509b908d8f08bbb5e41ca66
BLAKE2b-256 dd799c86de406189a1252cac28d083952a50d935143d7687cd3dd0bf3ff5a957

See more details on using hashes here.

Provenance

The following attestation bundles were made for gemini_transcribe_wrapper-0.0.50.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.0.50-py3-none-any.whl.

File metadata

File hashes

Hashes for gemini_transcribe_wrapper-0.0.50-py3-none-any.whl
Algorithm Hash digest
SHA256 34f0934f0556b4d80f1a9db00f8f8e2d8fb5927c1c9af10f24748aa2cfcd757c
MD5 bb87d41a7dcd92272d8d3e05b196ce36
BLAKE2b-256 5c753dbdb1144ab5a7a3bd47fc3b4798f951772ce79b493152e906245d77d50c

See more details on using hashes here.

Provenance

The following attestation bundles were made for gemini_transcribe_wrapper-0.0.50-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

0.1.9

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

This release

0.0.50 This release

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