Video Short
Input: a raw talking-head recording. Output:
at 1080x1920 and 30 fps, a 720p copy in
small enough to send, and the
that produced it.
You make every editorial call; the scripts measure, render, and serve the review page. Commands, the
format, graphics, and style keys live in
reference.md.
On first use, run
. If it lists missing tools, tell the user Video Short needs them and offer to install them with the commands it prints. A Gemini API key with billing enabled is optional, for generated images, video, and music. Ask the user to save it in
~/.config/video-short/.env
rather than paste it into chat.
1. Cut
Make one folder per Short, named with a short slug, where the user asks, else
from the style file, else the current folder. Leave the recording untouched and point
at it.
Run
and read every line of
. The transcript keeps ums, stutters, and restarts, so retakes show in the text. When the recording is longer than the Short, such as a full tutorial, first pick its strongest 30 to 60 seconds: cuts can be one or a few ranges from anywhere in the file. Write
in
:
- Keep the last complete take of any repeated line. Drop false starts, stray fillers, and dead air.
- Cut between words, never inside one; use the word times in the for a restart mid-sentence.
- Start about 0.1s before the first word and end about 0.1s after the last. Leave a natural breath after commas and list items. Never speed up the voice.
Run
and read the gridded stills, taken from the kept footage, for
, the face center. A landscape recording crops to vertical around that point. Add
to compare a subtle ffmpeg grade side by side, or use
when the footage already looks good.
Run
, then read
. Fix any clipped word or surviving retake and run it again. All scene times use this cut timeline.
2. Plan
Research what the Short needs, then write
in
, one row per shot, with start and end on spoken words. When the user shares a reel they like, study it first with contact sheets and cut strips for its pacing, layouts, and transitions; borrow how it moves, never its words or assets.
- Hook in the first 3 seconds. Ask whether a viewer would now watch to the end. Open on the hook line with the speaker or the strongest visual, and make it clear with the sound off, since most phone viewers start muted. Plant one question there that the Short answers before it ends. Close on the speaker, and when it fits, bring back the hook's visual so the Short comes full circle.
- Layouts: (full-screen speaker), (tighter speaker for emphasis), (visual on top, speaker below), (visual full screen).
- Keep the speaker present for at least half the Short, and end each full-screen B-roll shot within about 3.5 seconds, because viewers connect with a face.
- Visuals show what the words don't: the product doing the thing, the result, the proof. Captions already carry the words. Show the real product or UI, captured from the actual screen, and mock it up only when the real one isn't available. Never invent numbers or results.
- Everything off-camera moves. Real footage first. Otherwise a list card that adds a row per spoken item, a that counts up to a stat the speaker says, or a you write for anything else, such as a flow or a before and after. Never use a still image as B-roll; an image is only the first frame of a generated video clip, or a capture that scrolls. Skip dim UI panels and waveforms, which lose viewers. When a graphic leads into a clip, end it on the clip's first frame so the cut disappears.
- Readable and clean. A graphic fills its panel, with text a viewer can read on a phone at a glance. Never put a card or overlay over the speaker's face. Never show another captioned video full screen under this Short's captions.
- Pace: Change the shot every few seconds, since a phone viewer swipes away from a static frame. Good starting points, which the script can override: the first cut within about a second, on the first strong word, and most shots around 1 to 2 seconds, with a longer hold when a demo or a key line needs time to land. When the speaker names several things in a row, give each its own clip or card row on its spoken word. Use each clip once.
Find B-roll in this order: the user's own footage, including the screen-share parts of a longer recording, then official demos and the media in posts or launch pages about the topic. Use each clip's useful seconds with
, and
its last frame instead of letting a short clip loop. Keep every line of on-screen text whole: capture web pages with
, which reflows them to phone width, and show them as
drifting down one complete section. When product UI is too small to read,
into one complete card or field rather than cropping text at the edges. Use footage the user has the right to use. Show a brand's logo only from its official file, never redrawn or generated; without one, write the name.
When the user has a Gemini key and a shot has no good footage, propose generating it: a Nano Banana image, a Gemini Omni Flash video clip, or a Lyria music bed. Generate only what the user approves, because each call costs money.
Add
for misspelled names, and
for the rare term that earns a box in the caption, such as a product name or the main number, so captions stay quiet. For music, use the user's track, a Lyria bed they approve, or none. Lyria sometimes returns slow solo piano, so share a generated bed for a listen and regenerate it if it lacks the groove the user asked for. When the user names a song or artist, describe its genre, tempo, and instruments in the Lyria prompt instead of the name. When the speaker mentions the music, raise it there with
. Leave sound effects off unless the user asks.
Show the plan in chat and wait for a go:
- One line per scene: time, layout, what's on screen, and the words spoken.
- The B-roll sources you found, with links.
- What you propose to generate, if anything, and the music.
3. Draft and review
Run
, then
on it, and fix anything in its frames that fails the step 4 checks, so the user's review goes to taste, not mistakes. Then run
in the background. The review page plays the draft on a timeline split into scenes. The user pauses on any frame, presses C to comment, and clicks Send. The script exits and prints each note with its time, scene, spoken words, and a still of the frame the user paused on.
Look at each note's frame, then apply every note to
, render the next draft, and run
; the open page reloads itself. Repeat until the user clicks Looks good.
4. Final
Run
, then
, and fix any failed check. Look at
,
, and
in
:
- Captions never cover the mouth or chin.
- Every cut lands on the right word, with no blank, frozen, or stretched frames.
- Text and clip details are readable at phone size.
You can't hear the mix, so ask the user to listen for music level and clipped words. Run eval.md, then share the video path, duration, and loudness.
Style
Fonts and colors come from a style file:
, then
in the project, then
~/.config/video-short/style.json
, then the bundled default. When the user gives a note about the look, offer to save it to their style file so every Short gets it.