Transcribe Maker

Speech-to-text utility. Take audio or video file → output subtitle file (SRT / VTT) or transcript (JSON / text).

Distinct from voiceover-maker:

• voiceover-maker generates SPEECH from text. This goes the OPPOSITE direction: speech → text.
• Both wrap an OpenAI audio API endpoint.

Distinct from subtitle-burner:

• subtitle-burner takes an existing subtitle file and burns it into video. THIS skill GENERATES the subtitle file. Chain them: transcribe-maker → subtitle-burner.

This skill does NOT:

• Translate the transcript (Whisper supports it via separate endpoint; not exposed in v1 — use OpenAI's /v1/audio/translations directly if needed)
• Identify speakers / diarize (Whisper doesn't natively diarize — use deepgram or assemblyai for that)
• Process files >25 MB (Whisper API limit — split with ffmpeg first)
• Run locally (uses OpenAI API; for offline use whisper.cpp directly)
• Edit / clean up transcript (raw Whisper output may have minor errors — manual cleanup needed for production captions)

ROLE

Read audio/video input → call OpenAI Whisper API with the requested format → save subtitle / transcript file.

PIPELINE

1. Resolve input:

• --input — audio (.mp3, .wav, .m4a) or video (.mp4, .mov, .webm) (required)

1. Pick output format:

• --format srt (default) — for subtitle-burner consumption
• --format vtt — WebVTT (YouTube / HTML5 ``)
• --format text — plain transcript, no timestamps
• --format json — Whisper raw JSON (simple)
• --format verbose_json — JSON with word-level timestamps + segments

1. Resolve language (optional):

• --lang en / --lang ru / --lang de etc. — ISO-639-1 hint
• Auto-detect if omitted

1. Pre-flight:

• Check OPENAIAPIKEY set
• Check file ≤25 MB
• Cost estimate via ffprobe

1. Execute — POST to OpenAI /v1/audio/transcriptions.

1. Save:

• Default: . next to source
• Custom: --output

MODES

Required

• transcribe-maker --input

Optional

• --format srt|vtt|json|text|verbose_json (default srt)
• --model whisper-1|gpt-4o-transcribe|gpt-4o-mini-transcribe (default whisper-1)
• --lang — language hint (default: auto-detect)
• --temperature — Whisper sampling temp (default 0; deterministic)
• --output — explicit output path
• --yes — skip cost confirmation
• --check — verify env + connectivity
• --cost-only — print estimated cost + exit

PICKING A MODEL

The choice is decided by the output format, not by quality — only whisper-1 emits subtitles.

| Need | Model | Cost/min | |---|---|---| | SRT / VTT / word-level timestamps | whisper-1 | $0.006 | | Plain transcript, highest accuracy | gpt-4o-transcribe | $0.006 | | Plain transcript, bulk / cheapest | gpt-4o-mini-transcribe | $0.003 |

The GPT-4o transcribe models return json/text only. Asking one of them for srt fails fast with a message rather than handing subtitle-burner something it cannot burn. So anything feeding the subtitle pipeline stays on whisper-1; the GPT-4o tiers are for transcripts a human or an LLM will read.

REFERENCES (load on demand)

| File | When to load | |---|---| | [references/formats.md](references/formats.md) | Output format details, when to pick each, Whisper segment behavior | | [references/preprocessing.md](references/preprocessing.md) | When file >25MB: how to split / compress with ffmpeg | | [references/troubleshoot.md](references/troubleshoot.md) | When transcription has errors, language mis-detected, timestamps drift |

EXAMPLES

See [examples/before-after.md](examples/before-after.md) — 3 calibration runs: tutorial video to SRT, Russian podcast to text transcript, multilingual interview with word-level timestamps.

CONSTRAINTS

• OpenAI API key required. Set via /skills-keys add OPENAI_API_KEY ....

• File size limit: 25 MB. Whisper API hard limit. For larger files:
• Audio: re-encode to lower bitrate (ffmpeg -i input.wav -b:a 64k input.mp3)
• Video: extract audio only (ffmpeg -i video.mp4 -vn -acodec copy audio.aac)
• Long files: split with ffmpeg into <25 MB chunks, transcribe each, concatenate

• Cost: ~$0.006/min. A 60-min podcast = ~$0.36. Very affordable for most use cases.

• Language auto-detect is good but not perfect. For multilingual content, pass --lang explicitly for best results.

• Whisper has known weaknesses:
• Names / proper nouns sometimes wrong
• Technical jargon often substituted with phonetic alternatives
• Very quiet audio → hallucination of plausible-but-wrong text
• Background music interference

• Always proofread for production use. Raw Whisper output is ~95% accurate for clean speech; 80-90% for noisy/accented/technical content.

• No speaker diarization. Whisper transcribes ALL speech but doesn't tag who's speaking. For multi-speaker tagging: use Deepgram / AssemblyAI (not in scope for v1).

• SRT format includes timestamps. Word-level timestamps via --format verbose_json. Sentence-level via --format srt or vtt.

• For burning captions on video: chain with subtitle-burner:

`` transcribe-maker --input video.mp4 --format srt --output captions.srt --execute subtitle-burner burn ./video.mp4 --subtitle ./captions.srt --style modern ``

• Never print API keys.

INVOCATION HINTS

When the user says any of:

• "transcribe this video / audio", "subtitles from audio", "speech to text"
• "распознай речь", "сделай субтитры из видео", "превратить аудио в текст"
• "whisper this", "extract dialogue from video"

If the user wants final burned-in captions: suggest chaining with subtitle-burner.

If the user has only audio: transcribe works the same. If only video: works (transcribes audio track).

Defaults: --format srt --temperature 0 (best for captions). For plain transcript / blog post draft: --format text. For analytics / word-level alignment: --format verbose_json.

This skill is distinct from:

• voiceover-maker — text → speech (opposite direction)
• subtitle-burner — burns existing subtitles onto video; this produces them
• audio-mix-maker — mixing, not recognition
• music-prompt — generates music, not transcription

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Mikefluff
• Source: Mikefluff/skills
• License: MIT
• Homepage: https://www.npmjs.com/package/@mikefluff/skills

Install and usage instructions live in the source repository linked above.