Transcription
Create normalized word-level timestamps. Always specify --model explicitly — the CLI default is small.en, which silently translates non-English audio into English.
npx hyperframes transcribe audio.mp3 --model small.en # known English
npx hyperframes transcribe video.mp4 --model small --language es # known Spanish
npx hyperframes transcribe audio.mp3 --model small # unknown language (auto-detect)
npx hyperframes transcribe subtitles.srt # import existing
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.jsonLanguage Rule (Non-Negotiable)
.en models (tiny.en / base.en / small.en / medium.en) translate non-English audio into English. This silently destroys the original language.
- Known English →
--model small.en(ormedium.enfor music / noisy audio) - Known non-English →
--model small --language <iso-code>(no.ensuffix) - Unknown language →
--model small(whisper auto-detects)
CLI default is small.en — do not rely on it; always pass --model to make the choice explicit. --language also filters out non-target-language segments from mixed-language audio.
Model Sizes
| Model | Size | Speed | When |
|---|---|---|---|
tiny |
75 MB | Fastest | Quick previews, smoke tests |
base |
142 MB | Fast | Short clips, clear audio |
small |
466 MB | Moderate | Default for most multilingual content |
medium |
1.5 GB | Slow | Music with vocals, noisy audio |
large-v3 |
3.1 GB | Slowest | Production quality |
Picking a model by content type
- Speech over silence / light background →
small.en - Speech over music, or music with vocals → start with
medium.en - Produced music track (vocals + full instrumentation) → start with
medium.en; expect to need manual lyrics or an external API (captions/transcript-handling.md→ "Using External Transcription APIs") - Multilingual →
mediumorlarge-v3(no.ensuffix), pair with--language
Output Shape
Compositions consume a flat array of word objects. The id (w0, w1, …) is added during normalization for stable references in caption overrides; optional for backwards compatibility.
[
{ "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },
{ "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }
]For mandatory caption-quality checks, retry rules, and the OpenAI/Groq Whisper API import path, see captions/transcript-handling.md.