Skills › HyperFrames › media-use › transcribe.md

transcribe.md

52 lines · skills/media-use/audio/references/transcribe.md at a595755

1# Transcription

3Create normalized word-level timestamps. **Always specify `--model` explicitly** — `npx hyperframes transcribe` uses `small.en` as its default whisper model, which silently translates non-English audio into English.

5```bash

6npx hyperframes transcribe audio.mp3 --model small.en # known English

7npx hyperframes transcribe video.mp4 --model small --language es # known Spanish

8npx hyperframes transcribe audio.mp3 --model small # unknown language (auto-detect)

9npx hyperframes transcribe subtitles.srt # import existing

10npx hyperframes transcribe subtitles.vtt

11npx hyperframes transcribe openai-response.json

12```

Transcription

Create normalized word-level timestamps. **Always specify --model explicitly** — npx hyperframes transcribe uses small.en as its default whisper model, 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.json

Raw lines 1 to 13

14## Language Rule (Non-Negotiable)

16`.en` models (`tiny.en` / `base.en` / `small.en` / `medium.en`) **translate** non-English audio into English. This silently destroys the original language.

181. **Known English** → `--model small.en` (or `medium.en` for music / noisy audio)

192. **Known non-English** → `--model small --language <iso-code>` (no `.en` suffix)

203. **Unknown language** → `--model small` (whisper auto-detects)

22**The CLI's default whisper model 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.

Language 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 (or medium.en for music / noisy audio)
Known non-English → --model small --language <iso-code> (no .en suffix)
Unknown language → --model small (whisper auto-detects)

**The CLI's default whisper model 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.

Raw lines 14 to 23

24## Model Sizes

27| ---------- | ------ | -------- | ------------------------------------- |

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

Raw lines 24 to 33

34### Picking a model by content type

361. Speech over silence / light background → `small.en`

372. Speech over music, or music with vocals → start with `medium.en`

383. Produced music track (vocals + full instrumentation) → start with `medium.en`; expect to need manual lyrics or an external API ([`captions/transcript-handling.md`](captions/transcript-handling.md) → "Using External Transcription APIs")

394. Multilingual → `medium` or `large-v3` (no `.en` suffix), pair with `--language`

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](captions/transcript-handling.md) → "Using External Transcription APIs")
Multilingual → medium or large-v3 (no .en suffix), pair with --language

Raw lines 34 to 40

41## Output Shape

43Compositions 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.

45```json

46[

47 { "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },

48 { "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }

49]

50```

52For mandatory caption-quality checks, retry rules, and the OpenAI/Groq Whisper API import path, see `captions/transcript-handling.md`.

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.

Raw lines 41 to 52