training-srt-transcriber

name	training-srt-transcriber
sheetId	4.11
description	Turn an audio/video file (.m4a/.mp3/.wav/.mp4…) into a timestamped .srt using local Whisper. Two modes: transcribe (fresh speech-to-text with audio-accurate timestamps) or retime (keep an existing transcript's exact wording and re-derive every timestamp from the audio via forced alignment). Use when the user says 'turn this m4a into an srt', 'transcribe this audio to subtitles', '把這段錄音轉成字幕', '幫我做 srt', 'the srt wording is right but the timing is wrong, realign it', or hands over an audio file wanting subtitles. This is the FIRST step before training-srt-optimizer — it produces the raw-STT .srt; the optimizer then cleans the text. It does NOT edit/clean subtitle wording (that is training-srt-optimizer) and does NOT summarize into a recap (that is training-lecture-recap).
category	training
project	training-srt-transcriber
platform	multi
status	Done
author	Peter Tu
input	One audio or video file (e.g. .m4a). Optional: an existing reference .srt/.txt when re-timing known wording.
process	Bootstrap a local Whisper venv (stable-ts + torch) -> transcribe the audio OR force-align a supplied transcript -> emit a segment-level .srt -> validate timing
output	A timestamped .srt with audio-accurate cue timing, ready to hand to training-srt-optimizer for zh-TW cleanup
synergy	["training-srt-optimizer","training-lecture-recap"]

Training SRT Transcriber

npx skills add https://github.com/peter-tu-zynkr/zynkr-skill-builder --skill training-srt-transcriber

Turn an audio file into a timestamped .srt. It runs Whisper locally (via stable-ts) so it needs no API key and works offline. Use it when you have a recording (a lecture, an interview, a product demo .m4a) and want subtitles with timestamps that actually land on the spoken words. It has two modes: transcribe a recording from scratch, or — when you already have the correct words but the timing is broken — retime by force-aligning those exact words back onto the audio. It is the upstream half of the subtitle pipeline: it produces the raw STT .srt, then training-srt-optimizer minimally cleans the wording into readable Traditional Chinese.

---

When to use which mode

• transcribe — you have audio and no transcript (or the existing transcript is not worth keeping). Fresh Whisper STT; timestamps come from the audio.
• retime — you have a transcript whose wording is correct but whose timestamps are wrong (e.g. an .srt re-used from a different take, or with placeholder/round-number times). Keeps every word, re-derives every timestamp by forced alignment.

Step 1 — Provision the local Whisper engine (one-time)

The script self-bootstraps a dedicated virtualenv (stable-ts + torch, ~2GB) on first use, so this step is optional — but run it explicitly the first time so the install cost is visible and separate from the transcription run:

python3 scripts/transcribe_srt.py setup

The venv defaults to ~/.cache/zynkr-srt-transcriber/venv (override with the SRT_VENV env var). The Whisper model weights are cached under ~/.cache/whisper on first transcription.

Requires ffmpeg on PATH (Whisper decodes audio through it) and either uv or a Python 3.12 interpreter to build the venv.

Step 2 — Produce the SRT

Transcribe from scratch:

python3 scripts/transcribe_srt.py transcribe "input.m4a" --out "output.srt" --lang zh

Or re-time a transcript whose wording is right but timing is wrong (reference may be an .srt — its timestamps are ignored, only the wording is used — or a .txt with one cue per line):

python3 scripts/transcribe_srt.py retime "input.m4a" "reference.srt" --out "output.srt" --lang zh

Defaults: --model medium, --lang zh, --device cpu. Bump to --model large-v3 for maximum fidelity on hard audio (slower); switch --device mps on Apple Silicon or --device cuda on an NVIDIA box to speed things up.

Step 3 — Validate the timing

python3 scripts/transcribe_srt.py validate "output.srt" --audio "input.m4a"

Checks that cues are monotonic, non-overlapping, non-negative in duration, and never run past the audio's real length (read via ffprobe). Fix or re-run before shipping if it reports errors.

Step 4 — Hand off to the optimizer

The output is deliberately raw STT — accurate timing, unpolished wording. Pass it straight to training-srt-optimizer to minimally clean the text into subtitle-friendly Traditional Chinese while preserving these timestamps:

Use $training-srt-optimizer on output.srt

Inputs

• audio — any audio/video ffmpeg can decode (.m4a, .mp3, .wav, .mp4, …).
• reference (retime only) — an .srt (wording used, timing discarded) or a .txt (one cue per line).

Outputs

• A segment-level .srt with audio-accurate cue timing, indexed from 1, ready for training-srt-optimizer.

Configuration

• SRT_VENV — override the managed venv location (default ~/.cache/zynkr-srt-transcriber/venv).
• See ./references/transcription_notes.md for model-size trade-offs, device notes, and the dependency-pin rationale.

Limitations

• Not a text cleaner. It preserves whatever Whisper heard (transcribe) or whatever you supplied (retime); it does not remove filler or fix STT wording — that is training-srt-optimizer.
• retime assumes the words match the audio. If the reference transcript diverges substantially from what is actually spoken, alignment can drift where they differ. Spot-check the result.
• Local compute. A ~11-minute clip on medium/CPU aligns in roughly 7 minutes; large models and long files are slower. Use --device mps/cuda to accelerate.
• Language defaults to zh; pass --lang for other languages.