Starter kit for a video and audio to text tool

What you get

Left to you, because no check can do it: Read one transcript of a real recording of yours before trusting the tool with important material: names, numbers and technical terms are where speech models slip.

Transcriber

Installed along with them: pytest 9.1.1, PyAV below 19.

For your agent

The plan your agent follows

The agent works one step at a time and does not start a step until the previous one meets its "Done when" lines. The full instructions, with code, are in AGENTS.md.

1. Scaffold · done when:
   • python -m transcribe --help lists the commands and python -m pytest runs.
   • The kit files listed under "Before you start" are still there.
2. Test clips · done when:
   • av.open('media/test-en.mp4') shows one video and one audio stream, and its length matches the audio within a second.
3. Speech recognition · done when:
   • The English test clip comes back with at least 90% word accuracy (a test computes it with a word-level edit distance after lower-casing and stripping punctuation).
   • The silent clip gives zero segments and no invented text. (Whisper still reports a language for it; with no segments, write the language as unknown.)
4. Formats · done when:
   • Unit tests with fixed word timings check cue splitting, both timestamp formats (including times past one hour) and paragraph breaks.
   • A test writes every format for the English clip into a temporary folder and reads the subtitles back with a strict parser of its own (numbered SRT cues with commas; WEBVTT first line and dots), because FFmpeg's readers also accept an SRT with dots and a VTT without the header.
5. Files and folders · done when:
   • Running run media/ twice transcribes each clip once.
6. Verify · done when:
   • Every line under Definition of done is true, and anything that could not be verified is named in PROGRESS.md.

Known traps

What test builds and the official docs showed going wrong with these parts. Each one is in the brief, so the agent reads it before it gets there.

• faster-whisper 1.2.1 accepts any PyAV from 11 up, but PyAV 19 (Sep 29, 2026) removed the metadata_errors argument it passes to av.open, so a fresh install fails at the first transcribe() with a TypeError. The fix is on faster-whisper's main branch but not released; the Stack pins PyAV below 19. PyAV changelog and faster-whisper source, checked Oct 12, 2026
• WhisperModel.transcribe() returns a lazy generator: nothing runs until you loop over the segments, so timing or error handling around the call itself measures nothing. faster-whisper README
• WhisperModel.transcribe() has the voice-activity filter off by default (vad_filter=False), while BatchedInferencePipeline.transcribe() has it on. Pass vad_filter=True yourself. faster-whisper 1.2.1 source
• Without a language, Whisper detects it from the first 30 seconds only. A recording that opens with music, a jingle or a greeting in another language can be transcribed in the wrong language from start to end. faster-whisper 1.2.1 docstring
• FFmpeg's subtitle readers are lenient: ffmpeg -i x.srt accepts dots instead of commas, and a .vtt file without the WEBVTT line opens too. A read-back with FFmpeg or PyAV does not prove the file is valid for players. W3C WebVTT, and measured with PyAV 18.1.0 (bundled FFmpeg), Oct 12, 2026
• Models whose names end in .en know English only. With Russian or any other language they write English-sounding nonsense instead of failing. openai/whisper README
• SRT and WebVTT look alike but differ: SRT numbers its cues and writes milliseconds after a comma; WebVTT needs the WEBVTT first line and a dot. Players reject the wrong separator silently or show nothing. W3C WebVTT

Checks on this kit

• Note PyAV is pinned below 19: faster-whisper 1.2.1 passes an argument to av.open that PyAV 19 removed, and the fix is not released yet. Source
• Note faster-whisper decodes audio and video with PyAV, which bundles FFmpeg's libraries: transcription needs no system FFmpeg. Source

What happened when an agent built from it

The recipe was given to a fresh coding agent in a clean sandbox, twice. The agent got only the kit files. It had to build the project and write down everything in the brief that was wrong, missing or unclear.

Result of the last build. A 77-word synthetic clip transcribed on an Apple M4 CPU with the small model at 100% word accuracy in the second build (94.7% in the first); a strict parser found no fault in the SRT and VTT files, 43 tests pass, and a run with the network blocked worked. Its findings went back into the recipe, which is now at v0.3. That version has not been built again as a whole.

Checked again on Oct 19, 2026. AgentGid checks every recipe each week, without a model: 2 pinned packages all still exist on their registries; the pip lines resolve together; 10 links in the brief: all open. npm lines are checked pin by pin, not installed.

Not checked by anyone yet

• A real recording: the test clips are synthetic speech
• Playback of the subtitles in VLC
• Linux and Windows, and a GPU
• The web page, the hosted engines, Russian clips and the notes step

The kit files

Put them in an empty project folder, open your coding agent there and paste the first prompt (Claude Code first asks you to approve the MCP servers in .mcp.json). These are the files for Claude Code with the default answers; the kit builder writes them for Cursor, Codex, Copilot or another agent, and for other choices. Full guide: how to use a kit.

Download all (.zip)

Read AGENTS.md from top to bottom before you do anything else. The kit files it lists are already in this folder.

Then do step 1 of the plan and stop. Report back with:
1. the commands you ran,
2. what each "Done when" check showed (a screenshot or the output),
3. anything in AGENTS.md that turned out to be wrong, missing or out of date.

Do not start step 2 until I reply.

Read AGENTS.md from top to bottom before you do anything else. The kit files it lists are already in this folder.

Then work through the plan in order. After each step, run its "Done when" checks yourself and write one line in PROGRESS.md: the step, what you checked, and the result.
You may install the packages and download the files that AGENTS.md lists without asking. Stop and ask me only for what its "Before you start" section says needs a person.
When a check fails, fix the cause and run it again. If it still fails after two real fixes, stop and tell me what you tried.
Keep a list in PROGRESS.md of anything in AGENTS.md that turned out to be wrong, missing or out of date.
When every line of the Definition of done is true, stop and show me how to run it.

# system packages (use your OS package manager)
espeak-ng

uv venv --seed --python 3.12 .venv && source .venv/bin/activate   # uv fetches Python 3.12 if it is missing; --seed puts pip into the venv, so the pip line below installs there and not into the system Python
# without uv: python3.12 -m venv .venv && source .venv/bin/activate
python --version   # must print 3.12.x
pip install faster-whisper==1.2.1 pytest==9.1.1 "av<19"

Other versions of this kit

Other versions were not test-built as a whole: the kit says which parts differ from the tested one.

Ask for this kit from your agent

Agents connected to the AgentGid MCP server get the same kit without this page: list_recipes(), then plan_project({"recipe": "transcribe", "answers": {"agent": "cursor"}, "files": true}). Every brief also tells the agent to ask AgentGid before it adds a part that is not listed.

Recipe transcribe v0.3. Data snapshot Oct 12, 2026: versions, licenses and prices change, so check the linked pages before you ship.

Comments

Other kits