Starter kit for a short-video pipeline

What you get

Left to you, because no check can do it: Listen to one finished video before anything is published: a check can measure loudness, not whether the voice reads well. Decide then whether the pauses between sentences are too long (--trim-silence) and whether the voice is loud enough. Create the Pixabay account and put the key into .env.

Pipeline

Installed along with them: Requests 2.34.2, python-dotenv 1.2.4, pytest 9.1.1, SoundFile 0.14.0, PyAV below 19, NumPy below 2.5.

Content

Publish

For your agent

Licenses of the assets

License terms as the sources state them, read on the dates shown. The kit's CREDITS.md starts with these rows and the brief tells the agent to add one for every file it brings in. This is a record, not legal advice.

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 pipeline --help lists the commands and python -m pytest runs.
   • The kit files listed under "Before you start" are still there.
2. Script format · done when:
   • An invalid script fails with a message that names the missing field.
3. Voice · done when:
   • narration.wav holds the whole script, and the per-beat durations plus the pauses add up to its length.
   • The narration is between 20 and 60 seconds long; the stage refuses to go on otherwise.
4. Caption timing · done when:
   • A unit test feeds fixed word timings in and gets the expected caption groups out.
   • For the example script, the recognised word count equals the script's in every line, and no caption is wider than 960 px.
5. Footage · done when:
   • Running the stage for the example script fills the cache and the credits record, and a second run makes no network calls.
   • A property test over random scripts (the standard random module is enough) finds every shot between 90 and 180 frames long.
6. Assembly · done when:
   • final.mp4 exists and ffprobe reports 1080x1920, 30 fps, one H.264 video stream and one AAC audio stream, as long as the narration.
   • A frame grabbed in the middle of the widest caption shows complete letters: nothing is cut off at the sides, and descenders such as g, j, p and y are whole.
   • The picture differs between the frame before and the frame at every planned cut.
7. Checks and credits · done when:
   • python -m pipeline check out/example prints a pass for every line.
8. Verify · done when:
   • Every line under Definition of done is true, and anything that could not be verified (for example the live footage search without a key) 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.

• MoviePy 2 removed moviepy.editor. Import from moviepy; set_* methods became with_*; resize, crop and subclip became resized, cropped and subclipped; effects are classes passed to with_effects([...]), which takes a list. MoviePy docs, checked by running 2.2.1
• With Pillow 11.2 or newer, MoviePy 2.2.1's TextClip cuts off the bottom of the text and of the stroke. The Stack pins Pillow below 11.2, and the vertical margin of half the font size protects you if the pin is ever lifted. The 12 px at the sides keep the stroke of the first and last letter whole. measured with Pillow 11.1.0 and 11.3.0, Oct 12, 2026
• Always pass TextClip the path of a font file you ship. A family name raises ValueError: Invalid font; leaving font out does not fail, it quietly uses Pillow's default font. MoviePy docs and test build
• write_videofile puts MP3 audio into an .mp4 unless you pass audio_codec='aac'. checked by running 2.2.1, Oct 12, 2026
• Google Fonts ships some families only as a variable file whose default weight is thin (Montserrat is one). TextClip cannot choose a weight, so captions come out as hairlines. Use the static file named under Assets. google/fonts, checked Oct 12, 2026
• kokoro 0.9.4 needs Python below 3.13. pip refuses it on 3.13, but uv installs it there without a word, so check the interpreter yourself. PyPI, checked with pip and uv, Oct 12, 2026
• When its espeak fallback is missing, Kokoro skips words it does not know and says nothing: its logger is switched off. The package brings its own espeak-ng through espeakng-loader, so the system package the README asks for was not needed in the test build. Check anyway: the recognised word count must equal the script's. Kokoro source and second test build
• The speech recogniser returns what it heard, not what you wrote: numbers, names and homophones can differ. Captions show the script's spelling with the recognised times. test build
• "At least 1080 px tall" is not enough for a vertical video: a 1920x1080 clip passes that test and still has to be enlarged 1.78 times. Test the size of the 9:16 crop. Pixabay API docs and test build
• Cache search results for 24 hours and download only the clips you use; Pixabay asks for both. AgentGid: Pixabay
• faster-whisper 1.2.1 breaks with PyAV 19, which came out on Sep 29, 2026: TypeError: open() got an unexpected keyword argument 'metadata_errors' at the first transcribe. The Stack pins av below 19. PyAV changelog and second test build
• A four-word caption at 84 px can be 1,400 px wide. TextClip makes the clip as wide as the text and the composite crops what does not fit, without an error. second test build
• CompositeVideoClip(..., use_bgclip=True) takes its length from the captions, not from the background: without with_duration the video stops when the last caption does. checked by running 2.2.1, Oct 12, 2026
• A TextClip has no start, no length and position (0, 0) until you set them: left alone, every caption sits in the top left corner for the whole video. second test build

Checks on this kit

• Note Pillow is pinned to 10.4 to 11.1. moviepy 2.2.1 accepts pillow >=9.2.0 and <12.0, but with 11.2 or newer its captions are cut off at the bottom. The pin installs 11.1.0 today. Source
• Note numpy is pinned below 2.5: with 2.5, moviepy 2.2.1 prints a DeprecationWarning for every decoded frame. Source
• Note PyAV is pinned below 19: faster-whisper 1.2.1 passes an argument to av.open that PyAV 19 removed, and there is no newer faster-whisper yet. Source
• Note Use Python 3.12. kokoro 0.9.4 requires Python <3.13,>=3.10. pip refuses a newer interpreter; uv does not. Source
• Note Kokoro pulls in PyTorch and over a hundred packages: about 3 GB with the default GPU wheels, about 1.7 GB with CPU-only PyTorch. First run downloads a voice model of about 330 MB. 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 30-second narrated video with word-timed captions, rendered from a real voice model. 81 of 81 words were recognised. 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: 7 pinned packages all still exist on their registries; the pip lines resolve together; 25 links in the brief: all open (1 refused automated requests, which some sites do). npm lines are checked pin by pin, not installed.

Not checked by anyone yet

• The live footage search: there was no Pixabay key, so the build used the example clip from the API documentation
• How the voice sounds: nobody listened
• An NVIDIA GPU, macOS and Windows
• The hosted-voice and YouTube upload variants

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)
ffmpeg

python3.12 -m venv .venv && source .venv/bin/activate   # with uv: uv venv --python 3.12 .venv && source .venv/bin/activate, then write "uv pip install" below
python --version   # must print 3.12.x
# no NVIDIA GPU: run the next line first (CPU-only PyTorch, about 2 GB less to download). With an NVIDIA GPU, skip it.
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install kokoro==0.9.4 faster-whisper==1.2.1 moviepy==2.2.1 "pillow>=10.4,<11.2" requests==2.34.2 python-dotenv==1.2.4 pytest==9.1.1 soundfile==0.14.0 "av<19" "numpy<2.5"

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": "short-video", "answers": {"agent": "cursor"}, "files": true}). Every brief also tells the agent to ask AgentGid before it adds a part that is not listed.

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

Comments

Other kits