DEV Community: Harsheen

I put together a step-by-step guide to planning and building a Product Hunt launch video as a developer. It covers the storyboard, visual direction, agent-assisted production, review process and publishing.

Harsheen — Tue, 10 Nov 2026 13:38:19 +0000

Harsheen

Nov 10

How to Plan and Build a Product Hunt Launch Video from Scratch?

#producthunt #video #startup #tutorial

10 min read

How to Plan and Build a Product Hunt Launch Video from Scratch?

Harsheen — Tue, 10 Nov 2026 13:32:56 +0000

A Product Hunt launch video earns its place when a stranger can say what the product does after one muted viewing. That takes one audience, one problem, one workflow and one next step, usually in 45 to 60 seconds, with real product footage and text that stays readable on a phone. The trade-off is scope, because every feature that does not serve that one task has to go, and cutting your own work is the hard part.

Developers already have the right habits for this. A launch video behaves like a release, with a spec, a build, review passes and a deploy step, and the workflow below borrows all four. The example product is hypothetical, so swap the beats for whatever you ship.

Spec the video in one sentence

Before opening any editor, I fill in this sentence.

For [specific person] dealing with [specific situation], [product] lets them [visible outcome] by [main action].

Take a made-up CLI called driftwatch that compares config between staging and production. Filled in, the sentence says that for backend developers who learn about config drift after a deploy, driftwatch shows the mismatch before release by diffing two environments in one command.

Every spec needs a test, so I write one. After a single muted viewing, a stranger can state the problem and the outcome. Plain words help it pass. A phrase like "environment parity" means little on screen, while two terminals returning different values for the same setting needs no explanation.

The closing action gets decided now too. A video that promises an instant trial should not end on an unexplained waitlist, so I pick the action the product can support on launch day.

Storyboard four beats

The order is problem, product action, result, next step, all following one task from first friction to resolution.

Seconds	On screen	Text
0–6	Two terminals showing different values for one setting	Same config. Different results.
6–12	Product name appears over the terminal	Catch drift before the deploy does.
12–26	Real recording of one command, the diff scrolls in	One command compares both environments.
26–38	The mismatched key is fixed, the rerun comes back clean	Fix it, rerun it, watch it pass.
38–44	Hold on the clean result	Checked before every release.
44–50	Name and a single destination	Try it on a sample repo.

Running the command and fixing the key get separate shots, each with time to see the action and then its result. Supporting features appear only when the task needs them. Permissions belong in the video if they decide who can approve something, and unrelated analytics can wait for another video.

The on-screen text gets written next to each shot before anything is produced. Every line should describe something the viewer can see, and any number, such as hours saved per week, needs evidence behind it.

Pacing is easier to judge against a finished video than against a table. Rege (@rege_dev) posted this one on X, and I use clips like it to check whether my own beats breathe enough.

// Detect dark theme var iframe = document.getElementById('tweet-2091100152304173211-739'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2091100152304173211&theme=dark" }

Write a style sheet before any motion

A style sheet does for a video what design tokens do for an interface. The decisions get made once and reused in every scene.

I begin with three words for the product and audience. For driftwatch they would be quiet, exact and trustworthy, which points to spacious layouts, legible terminal text and controlled movement. A playful consumer app would pull toward brighter color and looser motion.

Those words guide a small set of references, including my own product screens so the board stays tied to what I am launching. CoAnimator's free product demo and launch video templates are another way to get a baseline, since each one is a finished film that can be recut by asking your agent. Each reference gets a note about what to take from it.

Opening clip: Note how fast it states the problem and when the product appears.
Interface close-up: Note how much surrounding context stays visible around the action.
Motion clip: Save a timestamp and describe the move, for example the cursor arrives, pauses, then clicks before the camera moves.

A short list of things to avoid helps as well, such as tiny interface text or a new transition on every cut. References get credited and studied for their decisions, while the final compositions stay original. If half the board is quiet and the other half runs on loud effects, I pick one direction.

Next come three still frames for the opening, the main action and the closing card, with the real product in the middle one. I fix one type scale, a small palette from the brand and a repeatable spot for labels, then view all three at phone size. A frame that only works on a large monitor needs a new crop or hierarchy before any animation.

Then I animate a five-to-eight-second test with a product action, a callout and a transition, since those are the pieces that repeat. A few written rules sit beside it.

Timing: Let each label be read before the next change, and let each result register before cutting away.
Easing: Let panels settle smoothly, and save bounce for a deliberately playful tone.
Continuity: Keep a shared object in a similar screen position across a transition.
Restraint: Reuse a small set of cuts, and keep the boldest movement for the main reveal.

One finished look is easier to learn from than a list of adjectives. This post from Rege (@rege_dev) is the kind of reference I would pin to a style sheet.

// Detect dark theme var iframe = document.getElementById('tweet-2099378611979768270-755'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2099378611979768270&theme=dark" }

When a move feels wrong, I shorten its distance or remove it before adding another effect. Once the sample works, it becomes the reference for every remaining scene.

Keep each shot to one idea

Reading a headline, tracking a cursor and parsing three animated cards at the same moment is too much for a viewer. For each shot I pick the place the eye should land first, move toward that control, then hold still while the action plays and the result settles. Crowded scenes usually respond to one of these fixes.

Three feature cards arrive at once: Show only the feature the current action needs.
A full dashboard shrinks the key detail: Crop closer while keeping enough context to recognize the screen.
A paragraph sits over moving footage: Cut it to a short label and spread the idea across shots.

Narration is optional, but any narration needs accurate captions.

Capture the footage and gather assets

The storyboard produces the asset list. For driftwatch that means a screen recording of the real command, two staged terminal states, a logo and a closing card, with no generated footage needed.

A demo account with sample data, closed tabs and silenced notifications makes a cleaner recording. I record in short takes with a pause before and after each action, and I label any section where I trimmed loading time if speed is part of the claim. Screen Studio on macOS offers adjustable zooms, and any existing screen recorder works too.

Music stays in a supporting role. The YouTube Audio Library separates tracks that need attribution from those that do not, so I copy any required credit into the description and check the terms before reusing a track in social or ad cuts. A track being available inside a tool does not clear it for every use.

Generated footage is for illustration only, such as a setting or an abstract transition, and never a stand-in for a working feature. Runway's image-to-video guide separates the image's composition and style from the prompt's motion instructions, so I ask for one slow move and keep exact text and logos in the editor.

CoAnimator's plugins cover voice, effects and music through ElevenLabs Audio, images through Gemini Images, and images and video through Grok Imagine. After enabling one and finishing its key setup, I start a fresh agent session so the change is picked up. Provider usage is billed through the provider account, and credentials stay in plugin setup. Real product footage comes from a separate recorder and gets imported.

Build the cut with an agent

With the story and assets ready, the CoAnimator quickstart covers connecting an agent and opening a project. CoAnimator's own product demo is a quick way to see the tool before opening it.

I hand over the scene plan and approved files together and ask the agent to list missing footage before it builds anything. Here is a Product Hunt launch video made in CoAnimator.

A starting brief, to be adapted.

Build a 50-second, 1920x1080 launch video for driftwatch, a CLI that compares config between environments. Use the attached logo, brand font and screen recording. The promise is catching config drift before a deploy. End on "Try it on a sample repo."

Follow this timing: 0–6s mismatch, 6–12s product name, 12–26s the command and the diff, 26–38s the fix and a clean rerun, 38–44s hold on the result, 44–50s closing card.

Match the attached moodboard, style frames and motion test: quiet, exact, trustworthy, one accent color. The story must make sense without audio. Keep text layers separate from footage so they stay editable.

Do not invent commands, output, customer logos or statistics. List any missing assets before starting. When revising one shot, leave approved scenes untouched.

The scene-by-scene brief above is one end of the range. Rege posted a cut where the beats, effects, music and sync were prompted together, which shows the other end.

// Detect dark theme var iframe = document.getElementById('tweet-2092190687806836833-440'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2092190687806836833&theme=dark" }

Starting loose and tightening later is a valid way to work, but I still write the scene plan first. A tight plan makes each revision smaller.

The review runs like code review. I start with an animatic, which is the storyboard frames held on a timeline with rough timings, because a missing step or a weak opening is cheapest to fix there. After that, the full cut gets one pass at a time.

Design: Is the key detail obvious in every frame?
Motion: Is there time to read each label and register each result?
Sound: Do speech, music and effects share one rhythm?
Finish: Does the export keep the intended result, with correct captions, unclipped text and clean audio endings?

Within a pass I change one thing at a time, compare it with the previous version, and keep or revert. CoAnimator keeps projects as editable, git-friendly files, so committing each approved state makes reverting trivial. Feedback to the agent works best as a timestamp, an observation and a specific change.

At 00:28 the clean-state label appears while the camera is still moving. Let the camera settle, then show the label and hold it for two seconds. Leave the surrounding shots alone.

Acceptance criteria get written before the final review, so the work stops when the cut passes the stranger test and every further change solves a named problem. For export, a 1920x1080, 16:9 master is a practical choice for a readable software demo, at 30 fps or matching the recording. Those are production choices and not Product Hunt requirements.

Re-render instead of rebuilding

A launch video goes stale the moment the interface changes, and the editable project is what makes that cheap. For a later release I swap the changed screens and re-render instead of reconstructing the sequence from an exported file. The Coa CLI renders headlessly from scripts, cron jobs or CI pipelines, so a release-day re-render can run without anyone opening the app.

Test it on someone who has never seen the product

The exported file gets one viewing by a person who knows nothing about the product, with no introduction first. I ask four things. Who is it for and what problem does it solve? What did the product actually do? Where did you need more time? What would you do next?

Specific points of confusion beat opinions on production quality. Someone who remembers the animation but cannot explain the workflow means the sequence needs simplifying. Someone who understands the problem but doubts the result means the product evidence is thin. When two openings are competing, I make both with the rest of the cut held constant and ask what each one leads them to expect.

Before launch I also confirm that text and controls are legible on a phone, that every demonstrated feature exists, that no private customer data is visible, and that captions and credits are correct. After launch, the numbers worth watching are the ones tied to the video's job, such as sample-project starts or signups, because upvotes alone say little about whether the video worked. CoAnimator has no built-in analytics, so that tracking comes from YouTube and the product itself.

Get the video to show up on Product Hunt

A passing cut still has to appear on the listing. Product Hunt's posting guide treats the video field, the gallery and the thumbnail separately.

Video field: Needs a full YouTube URL, since shortened links are not supported, and the video cannot be private.
Gallery images: Recommended size is 1270×760, and at least two images are needed for the gallery to display.
Thumbnail: Recommended square size is 240×240, and GIFs must stay under 3 MB.

The gallery size describes still images and has nothing to do with the video canvas, so I export the video separately and paste its YouTube URL into the listing.

Uploading at least a day early gives a buffer. Product Hunt's YouTube troubleshooting guide says a fresh upload may need about 12 hours before the integration works, and embedding restrictions can also block it. I open the link while logged out, then play it inside the draft preview, because a working watch page does not prove the embed works.

What to build after the launch video

The launch video is rarely the last one. Because the project stays editable, the same files can feed a 15-second cut for social, a short clip for every release, or a refreshed demo whenever the interface changes. Keeping the style sheet beside the project means each new video starts from a settled look instead of a blank timeline.

The ceiling is higher than a screen recording. Here is another one from Rege showing where a project can go once the launch cut is done.

// Detect dark theme var iframe = document.getElementById('tweet-2111083277193007438-544'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2111083277193007438&theme=dark" }

The quickest test of all this is to record one real product action and run it through CoAnimator with your own coding agent. A rough first cut will show whether the storyboard holds up.

Google Antigravity can direct a finished video if video software handles the frames. My guide covers the CLI setup, an example brief, editing footage and the limits. Which coding agent do you use for video?

Harsheen — Thu, 05 Nov 2026 13:30:30 +0000

Harsheen

Nov 5

How to Create Videos With Google Antigravity CLI

#ai #tutorial #video #antigravity

8 min read

How to Create Videos With Google Antigravity CLI

Harsheen — Thu, 05 Nov 2026 13:29:25 +0000

Google Antigravity can direct a finished video from a written brief, as long as video software handles the frames. It plans the scenes, edits the project files, runs the render command and checks what came back. Paired with a studio, that loop ends in an MP4 you can watch.

CoAnimator is the studio in this guide. It keeps the video as editable project files, previews changes live and renders on your machine, while Antigravity does the directing and the revisions. The one catch is setup: Antigravity opens as a terminal tab with its own approval flow, and the CoAnimator skill has to be added by hand.

The rest covers the setup I'd use, an example brief, editing footage you already have, and the places this falls short.

How to set up Google Antigravity CLI with CoAnimator

Antigravity is four products: the app, the IDE, the CLI and the SDK. This setup uses the CLI, so check that you aren't in the standalone IDE. Pick any model your CLI offers. The workflow doesn't depend on a specific one, and what the agent can edit depends on your source material.

1. Install CoAnimator and the coa command. Open the app, set up the media tools (rendering needs FFmpeg and FFprobe), then go to Settings → General → Command line & agent skill and install coa. In a fresh terminal:

coa --help
ffmpeg -version
ffprobe -version

On Windows PowerShell, run coa.cmd --help instead.

2. Install the Antigravity CLI and sign in. The documented command pipes a remote script straight into your shell, so I'd download it, read it, then run it:

curl -fsSL https://antigravity.google/cli/install.sh -o install.sh
less install.sh
bash install.sh

On Windows the documented one-liner is irm https://antigravity.google/cli/install.ps1 | iex. The same advice applies: save the script with -OutFile, read it, then run it.

The binary is agy, not gemini or antigravity. Run it once to finish Google's sign-in. That account has nothing to do with your CoAnimator licence.

3. Pick Antigravity in the agent picker. CoAnimator opens agy in a terminal tab inside the project folder. You get Antigravity's own interface, model picker and history, while CoAnimator supplies the folder and the window. CoAnimator's Antigravity guide covers the details.

4. Add the skill. A skill is a folder with a SKILL.md of instructions that the agent reads when a task matches. Google's skills codelab shows the format. CoAnimator's installer covers only Claude Code and Codex, so for Antigravity I'd download SKILL.md from that page and place it here:

.agents/skills/coa-cli/SKILL.md

.agents/skills/ is the current default workspace path, and the older .agent/skills/ is still read. Global skill folders differ between the app, IDE and CLI, which is why I prefer a project-local copy. Run /skills in the CLI to confirm it loaded, then start a fresh session. The skill teaches commands and conventions. It doesn't install coa or sign you in.

5. Run a smoke test before any creative work.

Inspect this CoAnimator project, confirm which tools are available, and explain how you would render it. Do not change the scenes yet.

A good answer names the project folder and the coa render command. The agent should also read the app's bundled docs first, since that is where its project conventions live.

How to brief Antigravity: an example plan for a 20-second video

Pick a change a viewer can see. "Faster deploys" gives an agent nothing to direct. "A dry-run flag that previews changes before anything ships" has a command, an output and a payoff. The example is hypothetical: a 20-second clip announcing release 2.4 of a CLI tool called shipit. Swap in your own.

Gather three files and name them by job: dry-run-demo.mp4 (a recording of the command), release-notes.md and brand-notes.md (fonts and colors). The 0.7.2 plugin list has no desktop screen recorder, so I'd record with a separate tool. If an image is only a style reference, say so in the brief, or the agent may try to rebuild it as a screen.

Ask for a plan before any animation:

Plan a 20-second CoAnimator video announcing shipit 2.4 to existing users. One message: shipit deploy --dry-run shows what would change before anything ships.

Use dry-run-demo.mp4 for the terminal action. Take the claim from release-notes.md and add no others. Read brand-notes.md for fonts and colors. Use 16:9 and make it readable without sound.

Return a scene plan with timings, on-screen text, and which part of the recording each scene uses. List anything the recording does not show. Wait for my approval before building.

The last two instructions do the most work. A plan takes seconds to fix and a finished animation doesn't. Asking for what the recording doesn't show gives the agent permission to report a gap instead of inventing output.

A plan for this clip might look like this:

0 to 4 s: a title card that names the flag
4 to 11 s: the command running, zoomed to the line being typed
11 to 17 s: the preview output, held long enough to read
17 to 20 s: the version number and the upgrade command

Terminal text is the weak point. A small monospace line that reads fine in the editor can turn to mush at delivery size. Before any motion, I'd approve three stills (title, command, output) at the size the video will play. After that, ask for movement with a reason: hold still while the output is readable, bring a caption in when its line appears, and zoom only to isolate one line.

Narration comes last, once the sequence works muted. CoAnimator's plugin docs list an ElevenLabs plugin for it, which needs your own key.

How to edit existing footage with Antigravity

Tell the agent what has to survive the cut, and give boundaries instead of adjectives:

Cut dry-run-demo.mp4 down to the command and its output, source 00:12 to 00:31. Remove the setup typing and any idle pause.

Keep the flag, the full preview output and the final prompt visible. Add a short title before the action. Keep the original recording as a source asset.

Propose the cut points before applying them. Do not speed up the output section.

Quote timestamps from the original file, and name the scene for anything after a cut. Once the opening is trimmed, 00:22 in the source and 00:22 in the export are different moments.

An imported MP4 is flat. Trimming, cropping and overlays work, but text baked into the recording stays baked in, so a wrong terminal line means a new capture. Titles the agent animated itself remain editable.

How to render and check the final MP4

A preview helps you decide. The exported file is what people watch. Ask the agent to render, or run it from the folder that holds your project:

# macOS or Linux
coa render ./shipit-2-4 --resolution 1080p --quality high --out ./shipit-2-4.mp4

# Windows
coa.cmd render .\shipit-2-4 --resolution 1080p --quality high --out .\shipit-2-4.mp4

The coa reference lists every flag. The command exits 0 on success and 1 on failure, which makes it usable in a script. Free exports are 720p with a watermark, and the licensing page lists what a paid licence changes, so --resolution 1080p needs one.

A render the agent says it started is not a finished file. Ask for the output path and any errors, then open the MP4. Check the first frame, the command, the output and the last frame, once with sound and once muted. Encoded files can differ slightly across machines, so judge the file you actually exported. Keep the project folder and its media beside the approved version, because an MP4 can't carry the editable structure.

How to update the video when your product changes

The first export is not the end of the project. Because it is a folder of plain files, I'd treat a product change the way I'd treat a code change. When shipit 2.5 alters the preview output, I'd re-record that one clip, ask the agent to swap it into the output scene, and re-render. The rest of the video stays as approved.

The files also diff, so the video change can sit in a pull request next to the code change it describes. The same files mean switching agents later shouldn't need a rebuild, though I'd confirm that on a small project before relying on it.

Limits of making videos with Antigravity

Quality follows direction. Output depends on the agent, the prompt and how much direction you give. Vague briefs produce vague videos, and learning to direct takes more practice than dragging clips.
Plugins assume Claude Code in places. Some plugin actions need it and its matching skill, so test any plugin from an Antigravity tab before the brief depends on it.
Gaps in 0.7.2. The docs list no AI avatar generation, no hosted rendering and no desktop screen recorder. There are also no built-in viewer analytics, so tracking who watched needs a separate tool.
Separate bills. Your Google plan and any plugin providers charge you directly.
Local rendering doesn't guarantee a fully private workflow. Editing and rendering run on your machine, but prompts, frames and files you hand to an agent or plugin can be sent to that provider.

Antigravity, Remotion or a chat agent?

Remotion is the other route you'll see in Antigravity video tutorials. It publishes agent skills in the shared skills format that Antigravity can load, and videos are React code rendered by the Remotion CLI or on AWS Lambda. That suits a video living inside a React product, or batches rendered from data. It is free for individuals and companies of up to three people, and larger companies need a company licence. I'd choose it when the video is a feature of the product, and a studio when one person is directing and revising a single video.

For CoAnimator's own permission prompts and change receipts, a chat agent such as Claude or ChatGPT gets them and the terminal tab doesn't. I'd choose Antigravity when the team already pays for Google's plans and works in agy daily.

Next step: a video for every release

Once one video works, the same setup can run on a schedule. coa render runs without opening the editor and exits 0 or 1, so a release job can render the announcement clip in the same pipeline that builds the binary, and a failed render fails the build instead of shipping a stale video. Linux runners need a display server such as xvfb-run, and the agent step still needs a signed-in Antigravity session, so I'd try a weekly job on your own machine before moving it to CI.

A launch video that is rebuilt with every release stops being a one-off asset and becomes part of shipping. To find out whether that is worth it for you, make one short clip, inspect the exported file, then time how long the second video takes compared with the first. That gap, not the first export, is the real test of this workflow.

What if I told you Codex can create and edit videos? Not just write code or build apps, but work on video projects too. I put together a guide showing what's possible and how to get started. 👇

Harsheen — Tue, 03 Nov 2026 08:00:08 +0000

Harsheen

Nov 3

Can Codex Create and Edit Videos?

#ai #tutorial #codex #video

10 min read

Can Codex Create and Edit Videos?

Harsheen — Tue, 03 Nov 2026 07:53:19 +0000

Codex's day job is a simple loop of reading a project, editing files, and running a command. A demo video fits that loop, as long as the video is plain files and something can render them.

Getting there depends less on the prompt than on the setup underneath. Codex needs a project format it can edit, a renderer it can run, and a sign-in and environment that line up. Once those are in place, the prompt is the easy part.

This post sets that up on Windows, macOS, and Linux, using CoAnimator for the project format and the renderer. It starts with a five-second test, then covers a brief that holds up and the review steps I would keep.

Can Codex make videos on its own?

No. Codex CLI is a coding agent that runs in your terminal: it reads a project, edits files, and runs commands. None of that is a video renderer, so it needs a project format it can edit and a renderer it can run.

CoAnimator supplies both. A video is stored as plain project files, a stage updates as they change, and a command-line tool called coa renders the MP4 on your machine. Since it is ordinary files, Codex works on it the way it works on code: read, edit, run, look at the result. The alternative is having Codex write for a code-based framework such as Remotion, which means building and maintaining the preview and render stack yourself.

This is not always worth it. For one video you will publish once, a screen recorder is faster. The setup pays off when the video has to change, because a changed video becomes an edit instead of a re-record. Codex will also animate whatever you hand it, including a stale screenshot, so the story and the accuracy stay your job.

Set up Codex CLI and CoAnimator

Setup is terminal work, so this assumes you are comfortable with npm and PATH. The steps follow CoAnimator's docs as I read them on 2 November 2026. CoAnimator updates often, so a menu name or flag may differ from the docs. If it does, trust what your app shows. Keep everything in one environment. On Windows, a tool installed inside WSL may be invisible to the native app that launches Codex, so for a first run I would stay on the Windows side. OpenAI's Windows guide covers both native PowerShell and WSL2.

1. Install CoAnimator

Download the build for your system. The macOS installer is Apple Silicon, Windows is 64-bit, and Linux is chosen by distribution and processor. The docs list macOS 13 or later. The editor is free to use and does not require a CoAnimator account. Then open Settings → Media tools and prepare FFmpeg and FFprobe, which rendering depends on.

2. Install Node.js and Codex CLI

Install an LTS release from the Node.js download page; npm comes with it, and CoAnimator's Settings → Media tools can install Node too. Node is needed for the npm install of Codex and for the adapter in step 3. In a fresh terminal, check both:

node --version
npm --version

In PowerShell, use npm.cmd --version for the second line. Then install Codex and sign in:

Task	macOS / Linux	Windows PowerShell
Install Codex CLI	`npm install -g @openai/codex`	`npm.cmd install -g @openai/codex`
Check the version	`codex --version`	`codex.cmd --version`
Sign in	`codex login`	`codex.cmd login`

In PowerShell, use the .cmd versions of npm and Codex commands if the default execution policy blocks their .ps1 launchers. Command Prompt accepts the regular command namFrees. OpenAI also provides a standalone Codex installer, but this guide uses npm to keep the setup consistent with the CoAnimator adapter's Node.js requirement.

CoAnimator reads the Codex CLI's sign-in from ~/.codex, whether it came from a ChatGPT plan or an API key, so the CLI itself needs to be installed. CoAnimator's Codex page documents this. Never paste credentials into a brief.

3. Connect Codex inside a project

Open a blank project or a template and choose Codex in the agent picker. The app sets up a small adapter between Codex and CoAnimator, which is why Node and npm have to work. If the connection fails, rerun the version checks in a fresh terminal and restart CoAnimator.

4. Install the skill and the coa command

Open Settings → General → Command line & agent skill. There are two installs, and neither includes the other. The skill teaches Codex the project format; choose Codex CLI and it lands in ~/.agents/skills/coa-cli/ (under %USERPROFILE% on Windows). The coa command does the rendering. Start a new Codex session afterwards.

Check the command with coa --help (coa.cmd --help in PowerShell). On Windows the installer adds a per-user coa.cmd to your PATH, with no admin rights or WSL needed. coa ships with its own runtime, so Node matters only for the Codex install and the adapter.

Now verify the FFmpeg and FFprobe from step 1. If they are on your PATH, ffmpeg -version and ffprobe -version should print. Otherwise FFMPEG_PATH and FFPROBE_PATH point CoAnimator at them.

5. Run a five-second smoke test

Before any assets or script, ask Codex to read the skill, find the current project, and create a five-second scene with one heading. Check the stage, then render from the folder that contains the project's project.json. If you do not know where that is, ask Codex for the project path, or pass the project ID instead of the dot:

coa render . --out ./smoke.mp4

On Windows PowerShell:

coa.cmd render . --out .\smoke.mp4

The dot means the current folder. This is the video version of a hello-world, and I think it earns its place. If it fails, the cause is a missing command, the wrong environment, or a project Codex cannot find, and none of those involve your prompt or your assets.

Write a brief Codex can't misread

Three things to settle before the brief.

Assets. Name each file for what it shows, such as config-before.png or watch-rebuild.mp4, so every scene points at one file. Scrub terminal recordings for tokens, hostnames, and home-directory paths, and cut dead air. Use real recordings for anything that claims a feature works. Generated imagery is fine for decoration you cannot capture, but invented interface footage proves nothing. Before building, ask Codex to describe each screenshot and identify the details it intends to use. Check those descriptions against the original files. This catches incorrect interpretations before they make their way into scenes, captions, or narration.

Standing rules. For a series, write colors, caption style, length limits, and wording down once instead of repeating them in every brief. OpenAI's AGENTS.md guide says Codex reads a global file from ~/.codex, then files from the project root down to the working folder, with closer files taking precedence. A starting point for an AGENTS.md in the project folder:

Use the logo and font files that are already in the project.
One main message per scene.
Use real product screenshots for interface details.
Keep text away from the frame edges.
Hold screen movement still while a label is being read.
Ask before replacing an approved asset or changing the script.

Add your color values, font names, and output dimensions. Then ask Codex to identify the instruction files it loaded and quote the relevant rules. This helps you check whether the project instructions were picked up before you start building.

Format. State the aspect ratio up front. A vertical cut needs tighter crops and fewer words, so treat it as its own layout pass. A project can hold several timelines, which lets it sit beside the 16:9 cut.

Now the brief. Take a made-up example: a CLI is shipping a --watch flag, and you have three screenshots, a 15-second terminal recording, and the release notes. A good brief names the assets, the scene order, the closing line, and a checkpoint:

Build a 30-second demo of the new --watch flag. Use the three screenshots and the terminal recording in the project media. Open on rebuilding by hand after every edit, show the flag being enabled in the config, then show the terminal rebuilding on its own after a file save. Close on the line "Stop re-running the build." Share the scene plan and wait for my approval before building.

The last sentence matters most, because a plan is cheaper to fix than a built cut. Read it against the real product. Suppose the release notes say --watch while the recording shows -w. That mismatch needs an answer before Codex writes captions and narration, because a wrong fact copied into three places is tedious to find again.

A 30-second plan could look like this:

Time	Scene	Job
0-5 s	Rebuilding by hand	Show the problem the viewer already knows
5-17 s	Enabling the flag in config	Explain the one change, one setting at a time
17-25 s	Terminal rebuilding after a save	Show what the setting produces
25-30 s	Hold on the result and next step	Give viewers time to read how to try it

Treat the timings as a draft. Read the narration aloud against the recording at real speed, and if something will not fit, cut a secondary point before compressing the main action. A script that reads at 35 seconds against a 30-second target needs shorter narration and retimed scenes, because trimming the last five seconds cuts the closing line instead of the excess. Generated narration comes from a plugin, and plugins carry their own sign-in or API key.

Before the full build, ask for one still frame and approve it as the visual reference for the rest. After that, give timing feedback in plain terms:

Show the config screenshot a second earlier and keep the terminal output hidden until the narration reaches the rebuild.

Review in layers, then render

Watch the rough cut before polishing motion. This order avoids polishing a scene you later cut:

Story. Can a viewer follow the action without a feature list? Cut any scene that does not advance the workflow.
Layout. Is the key label readable at the size viewers will see?
Motion. Does movement point at the next action? Keep the screen still while there is something to read.
Sound. Is the narration clear? Keep music under speech, and keep a licensed track's license with the project.
Export. Does the MP4 match the approved preview? Play the file outside the editor and check text, missing assets, audio, aspect ratio, and the last frame.

Render a preview using the same command, but give each export a new --out filename. Review the MP4 itself rather than relying only on the editor's stage.

Replace the second scene with the new config recording. Keep the opening and closing as they are, adjust the narration to match, keep the total under 30 seconds, render a new preview, and list what you changed.

Compare both exports to confirm that the correct assets were used, only the requested scenes changed, and the text remains readable. CoAnimator's docs say project files diff like source code. If your project folder is in git, commit before each revision. git diff then gives you a second way to confirm Codex touched only what you asked, though how readable that diff is depends on the project.

To re-check just the scene you changed, render a range. The values are seconds, and the end is exclusive:

coa render . --start 5 --end 17 --out ./scene2.mp4

Use coa.cmd the same way in PowerShell. Final exports use the same command, and the CLI reference covers flags such as --resolution and --quality.

Privacy and cost

Rendering happens on your machine, but the model behind Codex does not. Your prompts go to the model provider, and CoAnimator's licensing page says images, video frames, and files supplied to an agent may be sent too. Keep video work in its own folder, send only assets you are allowed to share, and read the permission prompts before allowing unattended edits or commands.

Cost can come from up to three places: Codex access through a ChatGPT plan or API key, any audio or generation plugin, and a CoAnimator license. Free exports use a 720p short side and carry a CoAnimator watermark. A valid paid license unlocks higher resolutions and removes the watermark. Local exports are not metered by CoAnimator credits. For a customer-facing video, check which tier your final render will use before you build around it.

Fix common setup and export problems

Debug from the bottom up: command, path, project, then prompt. A reworded prompt will not fix a missing executable.

Symptom	Check
Terminal cannot find `codex` or `coa`	Open a fresh terminal after installing, and use the `.cmd` form on Windows. If it works in one terminal but not in Codex, restart the Codex session.
Codex runs in the terminal but will not connect in CoAnimator	Confirm `node` and `npm` in a fresh terminal, that the same OS user signed in, and that Codex was not installed only inside WSL. Restart the app.
Codex ignores the project format	Confirm the skill is installed for Codex CLI, then start a new session.
Preview shows missing media	Check that each file named in the brief exists in the project media. Timeline Health can relink it.
Render fails before writing a file	Read the first error. Set `DEBUG=1` for a fuller trace; exit code 1 means failure.
Render fails on a headless Linux machine	It needs a display server. The CLI reference shows the `xvfb-run -a` form, and CoAnimator, FFmpeg, and FFprobe must be installed on that machine.

Next steps: re-render instead of re-record

The payoff of a video made from files is the second version. When the UI changes, the fix can be a pull request instead of a re-shoot, which matters most for teams whose interface moves every sprint. Keep the first demo as the template and let later versions change only the content scenes.

The step beyond that is scheduling. CoAnimator's docs describe a cron job where an agent reads the week's merged pull requests and coa render runs at the end, with the CLI exiting 0 or 1 like any build step. Its changelog-video page sketches the pipeline with a person still pressing publish. Its docs list no hosted render workers, so scheduled renders would run on your machine or on a CI runner you set up. I would review the first several outputs by hand before letting a model with file access run on a schedule.

If you try the smoke test, I would like to hear where your setup broke first, especially on Windows with WSL in the mix. Post it in the comments and I will add it to the troubleshooting table.

Anthropic had an agent edit its own launch video: 17 takes, 25 GB, no video editor opened. The surprising part is that the edit was text. I compare four ways agents hold an edit, list 2026 tools, and build a small editing agent you can run.

Harsheen — Thu, 29 Oct 2026 13:30:48 +0000

Harsheen

Oct 29

How Agentic Video Editing Works: Four Designs and What Each One Costs You

#ai #video #agents #automation

14 min read

How Agentic Video Editing Works: Four Designs and What Each One Costs You

Harsheen — Thu, 29 Oct 2026 13:20:22 +0000

In June 2026, Thariq Shihipar of Anthropic's Claude Code team had Claude Fable 5 edit the launch video for Fable 5 itself: 17 takes of raw 4K footage, about 25 GB. According to his deck, no video editor was opened.

What stands out to me is what the edit consisted of: a JSON file listing every cut with the reason for it, seven color lookup tables (LUTs), and a set of React components. The deck's summary is that "the edit is text", which let Claude read, compare and regenerate it. My argument is that this is the question to ask of any agentic video editing setup: what is the edit made of, and can anyone besides the agent open it?

Quick answer: Agentic video editing means an AI agent takes a goal, plans the steps, runs editing tools itself, checks the result and revises when you push back. Tools differ mainly in where the plan lives, either inside a vendor's app or in files you own. That choice sets what you can inspect, verify and change later.

What is agentic video editing?

An editor is agentic when it works from a goal, uses real editing tools in sequence, checks its own work and revises when you push back. That is Tella's definition. Invideo adds that the agent understands the footage and leaves its work on a timeline a person can change. A single feature such as auto-captions or silence removal does not qualify.

Agentic video editing vs agentic video generation

	Editing	Generation
Starts from	Footage you already have	An idea, script or novel
The agent's job	Decide what to keep, cut and add, then drive editing tools	Plan the story and shots, then call image and video models
Hard problem	Judgment about which moments to keep	Consistency of characters and scenes across shots
Example	The Fable 5 launch edit, video-use, Tella	ViMax

The generation column describes ViMax, an MIT-licensed framework whose configuration needs a chat model, an image generator and a video generator. A Reelful write-up draws the line from the editing side: a generator can always produce something that technically works, while an editor has to find the good moments inside imperfect footage.

A third group sits between the two: agents that author and revise a video as project files, such as CoAnimator. Its own page says it is not built for cutting footage you already shot, so it belongs with the tools for videos that do not exist yet.

How does agentic video editing work?

Most systems run the same loop and differ in how much a person approves along the way.

footage -> understand -> plan -> apply -> check -> render -> review
                           ^                |                   |
                           +-- revise ------+-------------------+

Understand: turn footage into text, such as transcripts with word timestamps.
Plan: write down the intended cuts. Many systems pause here for approval.
Apply: run editing tools, or write a file or code.
Check: validate the plan, re-transcribe the cut, or look at stills.
Render and review: produce the video. Your feedback restarts the loop.

I drew this loop from the examples below. No single source uses these names. Here it is on a real job, with every number taken from Thariq's deck:

Step	What the agent did	What it left behind
1. Listen	Transcribed all 17 takes with word timestamps	`transcripts/*.json`
2. Choose	One subagent per scene picked the best take; verifiers double-checked	`final-edit.json` with in and out points and a written reason for each pick
3. Cut	ffmpeg executed the JSON; Claude re-transcribed its own cut to confirm the filler words were gone	A 2:50 rough cut
4. Grade	Claude wrote candidate looks; Thariq chose one	7 hand-written `.cube` LUTs
5. Graphics	Rebuilt 11 static frames as React components, cued to word timestamps	Remotion components, six timing numbers
6. Design review	Exported to Figma through MCP, imported the designers' redesign, updated the video	A Figma file, two round trips
7. Render	4,334 frames at 3840x2160, 24 fps, with stills screenshotted for review before each full pass	The finished 3:00 file, 653 MB

It took four days (June 6 to 9), with about ten re-renders in one night.

What are the four ways to hold the edit?

Every setup keeps the edit somewhere. MCP, the Model Context Protocol, is the interface that lets an agent call an application's tools.

Design	Where the edit lives	Examples	What it costs you
1. Hosted timeline	Inside the vendor's editor	Invideo's agent works on the same multitrack timeline as manual editing; Goldcast's chat assistant	Whatever the product allows. Goldcast handles videos under five minutes, and a later agent run may restyle captions even though your manual edits are kept
2. Agent over MCP	Inside the vendor's app, reached through tools	Tella, Descript and invideo run hosted MCP servers, per Tella's comparison; Palmier Pro's is local	The agent can do only what the exposed tools allow, and access can depend on a plan or on the app being open
3. Data file	A JSON plan you own	The Fable 5 cuts; video-use, which waits for your approval before cutting; videopython, which validates plans before decoding frames	Only operations the format defines can appear. video-use needs an ElevenLabs API key, and videopython is pre-1.0
4. Code	Source code or project files you own	The Fable 5 graphics, where six timing numbers drive every animation; Reelful, which writes Remotion code; CoAnimator, where agents edit project files that sit in git	Taste has to become parameters, and someone has to be able to review the code

Which agentic video editing tools should you use in 2026?

Tool	Design	Best for	Access and limits
Tella	1 and 2	Screen recordings, demos, tutorials	In-editor agent included with paid plans and free trials, running on credits; hosted MCP
Descript	1 and 2	Talking-head video edited as text	Hosted MCP
Riverside	1 and 2	Podcasts and interviews	MCP on Grow plans and above
invideo	1 and 2	Multitrack timeline plus generation	Hosted MCP; credit-based plans
Goldcast	1	Event and webinar recordings	Videos under five minutes
video-use	3	Spoken footage, cut from a terminal	MIT license; ElevenLabs key; any agent with shell access
videopython	3	Scripted edits in Python	Apache-2.0; pre-1.0; local-first
Remotion	4	Motion graphics, code-based video	Source-available; free for individuals and companies of up to three people
CoAnimator	4	Demos, tutorials, launch videos and motion graphics that an agent authors as project files	Free tier: unlimited local renders at 720p with a watermark. A $299 one-time licence, listed as a limited-time price, adds 4K and no watermark. Works with Claude Code, Codex, Antigravity and OpenClaw.

Tella, Descript, Riverside and invideo rows come from Tella's comparison, a vendor page dated October 16, 2026, and Tella's docs. The rest come from each tool's own pages.

Where to start: for recorded talks or demos without code, a hosted editor. For spoken footage from a terminal, video-use. For control in Python, the agent built below. For demos, tutorials and launch videos that an agent authors as project files you keep in git and render locally, CoAnimator. For motion graphics in React, Remotion with a coding agent, as in its own five-minute tutorial:

Should an editing agent read the transcript or watch the pixels?

Invideo argues that a transcript cannot describe expressions, camera angles or continuity, so the agent should watch the footage. video-use takes the opposite default: its README says the model never watches the video. It reads a packed transcript (about 12 KB in its example) and asks for images only at decision points. The Fable 5 job also relied on transcripts and stills.

My read is that words and silence carry most of what a cut needs. Thariq's second job complicates that. In a July interview covered by Simon Willison, he said Fable noticed an auto-update popup in a slide recording, rebuilt the slides from his HTML deck, and cropped the stage video to follow him as he paced. He does not say how it perceived those things, but they are not transcript-level decisions. That is an opinion, and no source compares the approaches. The editing story starts at 41:50 in the full session:

How do you build an agentic video editing agent?

This agent cuts filler words and long pauses from a talking-head video. It needs Python 3.9 or later and ffmpeg. edit_agent.py uses only the standard library. Tested with Python 3.12 and ffmpeg 6.1.

1. Get word-level timestamps

Any speech recognition tool that returns a start and end time per word will do. Save this hand-made 8.5 second example, with two fillers and a long pause, as transcript.json:

{"words": [
  {"word": "Hello",    "start": 0.40, "end": 0.80},
  {"word": "everyone", "start": 0.85, "end": 1.40},
  {"word": "um",       "start": 1.60, "end": 1.90},
  {"word": "today",    "start": 2.40, "end": 2.80},
  {"word": "we",       "start": 2.85, "end": 3.00},
  {"word": "talk",     "start": 3.05, "end": 3.50},
  {"word": "editing",  "start": 3.55, "end": 4.10},
  {"word": "uh",       "start": 6.00, "end": 6.30},
  {"word": "it",       "start": 7.00, "end": 7.20},
  {"word": "works",    "start": 7.25, "end": 7.70}
]}

2. Write the agent

Save this as edit_agent.py. The model is a function you pass in.

import argparse
import json
import subprocess

MIN_SEGMENT, EPS = 0.5, 0.001  # seconds; EPS absorbs float noise


def probe(path, *args):
    out = subprocess.run(["ffprobe", "-v", "error", *args, path],
                         capture_output=True, text=True, check=True)
    return out.stdout.strip()


def duration(path):
    return float(probe(path, "-show_entries", "format=duration", "-of", "default=nw=1:nk=1"))


def is_num(x):
    return isinstance(x, (int, float)) and not isinstance(x, bool)


def validate(plan, words, total):
    """Return structured errors. An empty list means the plan is safe to render."""
    segs = plan.get("segments") if isinstance(plan, dict) else None
    if not segs or not isinstance(segs, list):
        return [{"error": "plan needs a non-empty 'segments' list"}]
    errors, prev_end = [], 0.0
    bad = lambda i, msg: errors.append({"segment": i, "error": msg})
    for i, seg in enumerate(segs):
        if not (isinstance(seg, dict) and is_num(seg.get("start")) and is_num(seg.get("end"))):
            bad(i, "needs numeric 'start' and 'end'")
            continue
        s, e = seg["start"], seg["end"]
        if s < 0 or e > total + EPS:
            bad(i, f"{s}-{e}s is outside the media (0-{total:.2f}s)")
        if e <= s:
            bad(i, "end must be after start")
            continue
        if e - s < MIN_SEGMENT:
            bad(i, f"shorter than {MIN_SEGMENT}s")
        if s < prev_end - EPS:
            bad(i, f"starts at {s}s, before the previous segment ends at {prev_end}s")
        for t in (s, e):
            for w in words:
                if w["start"] + EPS < t < w["end"] - EPS:
                    bad(i, f"cut at {t}s falls inside the word '{w['word']}' "
                           f"({w['start']}-{w['end']}s)")
        prev_end = max(prev_end, e)
    return errors


def run_agent(brief, words, total, propose, max_rounds=3):
    """Ask the model for a plan, validate it, and feed errors back until it passes."""
    feedback = []
    for n in range(1, max_rounds + 1):
        try:
            plan = propose(brief, words, feedback)
        except ValueError as exc:  # the reply was not usable JSON
            feedback = [{"error": f"reply was not valid JSON: {exc}"}]
            print(f"round {n}: unusable reply")
            continue
        errors = validate(plan, words, total)
        print(f"round {n}: {len(errors)} error(s)")
        for error in errors:
            print("  ", json.dumps(error))
        if not errors:
            return plan
        feedback = errors
    raise SystemExit(f"no valid plan after {max_rounds} rounds")


def render(plan, media, out_path):
    filters, labels = [], []
    for i, seg in enumerate(plan["segments"]):
        s, e = seg["start"], seg["end"]
        filters.append(f"[0:v]trim=start={s}:end={e},setpts=PTS-STARTPTS[v{i}]")
        filters.append(f"[0:a]atrim=start={s}:end={e},asetpts=PTS-STARTPTS[a{i}]")
        labels.append(f"[v{i}][a{i}]")
    filters.append(f"{''.join(labels)}concat=n={len(labels)}:v=1:a=1[v][a]")
    subprocess.run(["ffmpeg", "-y", "-i", media, "-filter_complex", ";".join(filters),
                    "-map", "[v]", "-map", "[a]", "-pix_fmt", "yuv420p", out_path],
                   check=True, capture_output=True)


def verify(plan, out_path, tolerance=0.15):
    """Check the rendered file against the plan. Returns a list of problems."""
    expected = sum(s["end"] - s["start"] for s in plan["segments"])
    actual = duration(out_path)
    problems = []
    if abs(actual - expected) > tolerance:
        problems.append(f"duration {actual:.2f}s, plan says {expected:.2f}s")
    if not probe(out_path, "-select_streams", "a", "-show_entries", "stream=codec_type",
                 "-of", "csv=p=0"):
        problems.append("output has no audio stream")
    return problems


def main(propose, argv=None):
    ap = argparse.ArgumentParser()
    ap.add_argument("media")
    ap.add_argument("transcript", help='JSON: {"words": [{"word", "start", "end"}]}')
    ap.add_argument("brief")
    ap.add_argument("--out", default="out.mp4")
    ap.add_argument("--yes", action="store_true", help="skip the approval prompt")
    args = ap.parse_args(argv)

    with open(args.transcript) as f:
        words = json.load(f)["words"]
    plan = run_agent(args.brief, words, duration(args.media), propose)
    with open("plan.json", "w") as f:
        json.dump(plan, f, indent=2)  # the edit is a file you can diff
    for i, seg in enumerate(plan["segments"]):  # show what each kept range says
        said = " ".join(w["word"] for w in words
                        if seg["start"] <= (w["start"] + w["end"]) / 2 <= seg["end"])
        print(f"{i}: {seg['start']:.2f}-{seg['end']:.2f}s  {said!r}  {seg.get('reason', '')}")
    if not args.yes and input("Render this plan? [y/N] ").strip().lower() != "y":
        raise SystemExit("not approved")
    try:
        render(plan, args.media, args.out)
    except subprocess.CalledProcessError as exc:
        raise SystemExit(exc.stderr.decode())
    problems = verify(plan, args.out)
    if problems:
        raise SystemExit("verification failed: " + "; ".join(problems))
    print(f"rendered {args.out} and verified it against the plan")

validate rejects plans that are malformed, run outside the media, overlap, contain a segment under half a second, or cut inside a spoken word. The last rule follows video-use's README, which says its cuts come from speech boundaries and silence gaps. It returns every error at once.
run_agent is the loop: ask for a plan, validate it, send errors back, repeat. A reply that is not valid JSON counts as an error.
main saves plan.json, prints what each kept range says, waits for your approval, renders, and verifies the duration and audio.

3. Connect a model

Save this as propose_anthropic.py, run pip install anthropic, and set ANTHROPIC_API_KEY. It is the only provider-specific code, and any model that can follow a JSON format will work.

import json

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment
MODEL = "claude-sonnet-5-5"     # any model that can follow a JSON format works

FENCE = "`" * 3  # the code fence some models wrap JSON in

SYSTEM = (
    "You are a video editing planner. Reply with JSON only, in this shape: "
    '{"segments": [{"start": <seconds>, "end": <seconds>, "reason": "<why kept>"}]}. '
    "Segments are the ranges to KEEP, in order, with no overlap. "
    "Every start and end must fall in the silence between two words, never inside a word."
)


def propose(brief, words, feedback):
    lines = "\n".join(f"{w['start']:.2f}-{w['end']:.2f} {w['word']}" for w in words)
    content = f"Brief: {brief}\n\nWord timestamps:\n{lines}"
    if feedback:
        content += ("\n\nYour last plan failed validation. "
                    f"Fix every error:\n{json.dumps(feedback)}")
    message = client.messages.create(
        model=MODEL, max_tokens=2000, system=SYSTEM,
        messages=[{"role": "user", "content": content}],
    )
    text = message.content[0].text.strip()
    if text.startswith(FENCE):  # some replies wrap JSON in a code fence
        text = text.strip("`").removeprefix("json").strip()
    try:
        return json.loads(text)
    except json.JSONDecodeError as exc:
        raise ValueError(str(exc)) from exc


if __name__ == "__main__":
    from edit_agent import main
    main(propose)

It was tested against anthropic 2.3.0 with the HTTP layer mocked, and has not been run against the live API, so run it once with a real key before relying on it. If you mock the SDK yourself, note that 2.x expects httpx2 clients.

4. Run it

To see the loop without a key, use a scripted stand-in whose first reply has two deliberate mistakes. Save this as demo_scripted.py:

from edit_agent import main

# Two replies a model might give: the first has two mistakes, the second fixes them.
REPLIES = iter([
    {"segments": [{"start": 0.0, "end": 1.5, "reason": "greeting"},
                  {"start": 2.6, "end": 4.2, "reason": "main point"},
                  {"start": 6.9, "end": 9.0, "reason": "closing"}]},
    {"segments": [{"start": 0.0, "end": 1.5, "reason": "greeting, drops the 'um'"},
                  {"start": 2.3, "end": 4.2, "reason": "main point"},
                  {"start": 6.9, "end": 7.8, "reason": "closing, drops the 'uh'"}]},
])

main(lambda brief, words, feedback: next(REPLIES))

Create a matching clip and run it:

ffmpeg -f lavfi -i testsrc=duration=8.5:size=640x360:rate=30 \
       -f lavfi -i sine=frequency=440:duration=8.5 \
       -shortest -c:v libx264 -pix_fmt yuv420p -c:a aac talk.mp4

python3 demo_scripted.py talk.mp4 transcript.json \
  "Remove filler words and pauses longer than one second." --yes

round 1: 2 error(s)
   {"segment": 1, "error": "cut at 2.6s falls inside the word 'today' (2.4-2.8s)"}
   {"segment": 2, "error": "6.9-9.0s is outside the media (0-8.50s)"}
round 2: 0 error(s)
0: 0.00-1.50s  'Hello everyone'  greeting, drops the 'um'
1: 2.30-4.20s  'today we talk editing'  main point
2: 6.90-7.80s  'it works'  closing, drops the 'uh'
rendered out.mp4 and verified it against the plan

Round 1 fails twice, for a cut inside "today" and a range past the end of the media. Round 2 passes, and the output is 4.30 seconds, matching the plan. With a real model, run python3 propose_anthropic.py talk.mp4 transcript.json "..." and drop --yes to approve the plan first.

What to add before production

Long videos: this sends every word in one prompt. Pack the transcript instead, as video-use does.
Visual checks: it never looks at a frame. Re-transcribe the output or screenshot stills, as the Fable 5 job did.
Audio fades: video-use adds 30 ms fades at every cut. This cuts hard.
Retries and logs: video-use caps its fix passes at three, and this script caps planning rounds at three. Log every reply and error.
Safety: render to a new file, keep the plan and a reason per cut under version control, and keep a person between plan and render.

Where does agentic video editing still fall short?

Speed is uneven. In the deck, a watchable 2:50 cut arrived within minutes, and the finished video took four days.
Transcripts are imperfect. The transcript misheard the presenter's name, and the cuts still worked because the word timestamps held.
Taste stayed human. Claude produced candidate color looks, and Thariq chose one.
The evidence is selected and not independent. The Reelful write-up cautions that the founder picked the examples shown, and both Fable 5 jobs are described by Thariq, who works at the model's maker. The memories.ai paper names latency and limited fine control as open problems.

Common questions

Do I need to code?

For hosted editors, no. For video-use and Remotion you prompt in plain language but work in a terminal with a coding agent, and you should be able to read what it produces. Remotion's docs note that most coding agents require a paid subscription.

Is it free?

It depends on the design. video-use is MIT-licensed and videopython is Apache-2.0, but the model that drives them may cost money. Remotion calls itself source-available, not open source: free for individuals and companies of up to three people, with a company license for four or more, and its license page says the terms change slightly in Remotion 5.0. Tella's docs say its agent is included with paid plans and free trials. CoAnimator's free tier has no expiry and unlimited local renders, and its one-time licence adds 4K and watermark-free export. Check current pricing first.

Will it replace video editors?

No. I think the role's not gonna disappear, it's definitely gonna change. Invideo says the editor moves from performing every mechanical operation to briefing, reviewing and directing, and in the Fable 5 job a person set the creative direction.

What is the difference between an editing API and an editing agent?

An API or MCP server exposes operations such as cut, zoom or export. An agent decides which to call, checks the result and revises.

What I would ask for before adopting one

I would ask for one thing first: show me the edit as a file. After a revision, I want to open it and see what changed. If the only answer is a rendered video, or a timeline reachable only through the vendor's interface, I would treat the result as a draft I cannot audit. That does not make a hosted editor a bad choice. For a single clip you will never revise, its timeline may be all you need. The file matters once the edit needs a second version.

Then run a small test. Take a 60-second recording, ask the agent for a plan before it renders, approve it, render once, and ask for one small change, such as rewording a single title. If only that piece changes, the design holds your edit in a form you can work with. If the whole cut shifts, you learned that before committing a real project.

In the Fable 5 case, the part worth copying was not the model. It was that the finished edit was a set of files a person could open and read.

Best 9 AI Video Editors for Product demos and Tutorials in 2026

Harsheen — Wed, 28 Oct 2026 13:34:42 +0000

A button gets renamed and the demo video on your docs site is now wrong. Someone re-records the screen, re-cuts the video and exports it again. The same chore comes back with every release, and when it gets skipped, users follow a video of a screen they no longer see.

This is for whoever keeps those videos current. I compared nine AI video editors on that second edit: what it takes to redo, and what it draws from the plan you pay for. I worked from vendor pricing pages and documentation, so the costs below are worked out from published limits. I left out click-through demo tools such as Arcade and Supademo, which build interactive walkthroughs and not videos.

The short answer is that your starting material decides. A screen recording points to Descript or Clueso. A demo that changes every release points to a tool that keeps the video as editable files, where a coding agent changes one scene. If you already cut on a timeline, stay on it. HeyGen and Runway generate presenters and footage, so they only fit where your real interface doesn't need to appear.

The second edit: re-cut, regenerate or change one scene

Say a settings page is redesigned. You can re-record and re-cut: swap the changed footage and export again, paying in time plus whatever your plan meters on recordings or exports. You can regenerate: edit a script or prompt and the tool rebuilds the whole video, which spends credits. Or a coding agent or editor can change the affected scene and leave the approved ones alone.

Nine tools compared: price, free tier and cost of one update

Prices are as listed on 28 October 2026 for the cheapest paid plan that removes the watermark, on each vendor's lead billing basis. The last column works out what one update draws from the plan: a 30-second walkthrough where one screenshot changes and the video stays 30 seconds long.

Tool	Cheapest paid plan (no watermark)	Free access	Automation	One 30-second update draws
Descript	$16/mo billed annually	1 media hour a month, watermarked	Official MCP server for Claude, ChatGPT and Cursor	30 seconds of media, plus AI credits if Underlord edits; Hobbyist's 10 hours cover 1,200 clips that long
Clueso	$40/mo billed yearly	10 export minutes a month, watermarked	MCP on every plan; chat editing and agents on Enterprise	Nothing extra at the same length; the first export used half a minute of Solo's 15
Camtasia	$179.88/yr (Essentials)	Free browser recorder; desktop exports watermarked	n/a	Your time only
DaVinci Resolve	Free, or $295 once for Studio	Full free edition	MCP server in Studio 21.1	Your time only
Adobe Premiere	US$22.99/mo for the first year	7-day desktop trial; free mobile app	AI Assistant, generative tools	Your time only, unless you generate
HeyGen	$29/mo (Creator)	3 watermarked videos a month, 1 minute each	Video Agent chat	10 credits at 20 a minute, more on some modes; Creator has 600
Runway	$12/mo billed annually	125 one-time credits, watermarked	Runway Agent, MCP	360 credits at 12 a second; Standard has 625
CoAnimator	$299 once, plus your agent	Free forever, 720p, watermarked	`coa` CLI for headless renders in CI	Your agent's usage, no render charge
Cardboard	$29/mo (Starter)	Lite in the Mac app: watermarked, 3 exports	Built-in agent; Mac app connects Claude or Codex	Usage credits; the plan limits give no per-edit figure

What stands out to me is how the cost splits. The re-cut tools charge almost nothing in usage and all of it in your time. The regenerate tools charge credits on every pass. The agent tools sit between them, with your agent's usage as the open question.

Re-cut tools: Descript, Clueso, Camtasia, DaVinci Resolve and Premiere

A table can't show how each tool behaves, so here is how I'd describe each one. In these five, an update means swapping footage and exporting again.

Descript: edit the video through its transcript

Deleting a sentence in Descript's transcript removes it from the recording. Its assistant, Underlord, applies edits by instruction, and an official MCP server connects Claude, ChatGPT and Cursor to your projects, with imports drawing on media minutes and Underlord edits on AI credits. Plans give 10 media hours on Hobbyist, 30 plus 5 bonus on Creator and 40 plus 10 bonus on Business, with monthly AI credit pools of 400, 800 and 1,500. A changed screen still has to be re-recorded, so I'd pick Descript for narrated tutorials and talking-head videos before a demo whose visuals change every release. See Descript's pricing.

Clueso: one recording, a video and a help article

Clueso turns a recording, deck, document or prompt into a video and a step-by-step help article from one source. Its MCP server is on every plan and lets an assistant create or update a project, add voiceovers and export. The export rule matters most for updates. Clueso's export-limit page says each video counts by the longest version you export in a billing cycle. Re-exporting a same-length video costs nothing, extending it adds the extra minutes, and each translated copy counts separately. Solo includes 15 export minutes a month (3 hours a year), and Business is $120 a month for two users with 6 hours a year. Chat editing and update agents are Enterprise features. See the pricing page.

Camtasia: a mature recorder and timeline editor

Camtasia suits recorded tutorials and course-style training, and an update is a manual re-cut. TechSmith sells AI by tier. Starter at $39 a year exports with a watermark, so the usable entry is Essentials, the full editor. Create at $249 adds AI scripts and voiceover, and Pro at $599 adds avatars and translation. Everything bills yearly per user, per TechSmith's pricing.

DaVinci Resolve: a free editor with an MCP server in Studio

Resolve's catch is that the automation sits behind the paid edition. The free edition has no time limit, and Studio is $295 once. Version 21.1, released in September 2026, added a native MCP server to Studio, so Claude, Claude Code and ChatGPT Codex can organize media, cut a highlight edit and batch render from plain requests. The same release limited advanced scripting to Studio, though console scripting stays free. The assistant helps around the edit but the update itself is a manual re-cut, so I'd pick Resolve for precise control at a one-time price.

Adobe Premiere: the timeline editor with generative tools

Adobe dropped the Pro suffix with version 26 in January 2026, so the editor is now just Premiere. The single-app plan is US$22.99 a month for the first year for new subscribers, and Creative Cloud Pro is US$69.99 a month at the regular price. An AI Assistant sorts footage into bins by scene, and the Generative Media tool creates clips and sound effects in the timeline using generative credits (25 a month on the single-app plan). It arrived in beta in July and was reported out of beta at IBC in September. Updates are hand re-cuts, so it fits teams already in Adobe tools.

Regenerate tools: HeyGen and Runway

These two trade control for speed. You change the script or prompt and the tool rebuilds the video.

HeyGen: presenter videos from a script

HeyGen generates presenters, so every product screen has to come from assets you attach. That makes it a poor match for a demo and a reasonable one for a presenter-led announcement. You give its Video Agent a script or prompt and revise in chat. Creator has 600 credits, no watermark and 1080p export, Pro starts at $49 a month with 1,000 credits and 4K, and Business is $149 plus $20 per seat, per HeyGen's pricing page. Avatar IV, Avatar V and Video Agent videos each use 20 credits a minute, and rates vary by feature, so check the one you would use.

Runway: generated shots, not your interface

Runway is built for shots you never filmed, so I'd use it for B-roll and concept clips and keep it away from your real interface. It generates video from prompts with its own and third-party models. Per its pricing page, Standard, Pro and Max cost $12, $28 and $76 a month billed annually, with 625, 2,250 and 9,500 credits, and Gen-4.5 uses 12 credits per second of output. Standard and Pro credits expire each month, while Max rolls unused credits over once. Aleph 2.0 edits existing footage by prompt.

Agent-edited tools: CoAnimator and Cardboard

These two keep the video as a project, which is what lets an update touch a single scene.

CoAnimator: a project of files that an agent edits

CoAnimator is a studio you drive with a coding agent such as Claude Code, Codex or Gemini. The agent builds scenes, narration and timing on a live stage that reloads as it works, and projects are plain files you can keep in git. When the product changes, you tell the agent what moved and it edits that scene.

Rendering is local and unmetered, the app works offline, and the coa command line tool renders headlessly, so a pipeline can rebuild the video:

coa render my-demo --preset 1080p60
coa render launch-video.coa --out launch.mp4

The CLI exits 0 or 1 for CI, and --start and --end render part of a timeline. A runner needs the app or CLI, FFmpeg, FFprobe and, on headless Linux, a display server such as xvfb-run (CLI docs).

The free plan includes all templates, screen capture, voiceover and publishing. The lifetime license is listed at $299, down from $499, and adds 4K, no watermark, premium plugins, two devices and a year of updates, then $79 a year. Output is only as good as the agent you connect, which has its own subscription or API cost. Rendering happens on one machine, and the tool isn't built for trimming footage you already shot.

Cardboard: describe the edit, refine by chat

Cardboard builds a first cut from a prompt, footage or both, and you refine it by chat or on the timeline. It runs in Chrome and in a Mac app for Apple Silicon, where footage is processed locally and Claude or Codex connect through an eligible existing subscription. On the web, Lite is $8 a month with a watermark. In the Mac app, Lite is free but watermarked and limited to 3 exports. Starter ($29) drops the watermark, adds 400 generative credits and timeline export to Premiere Pro, Final Cut Pro and DaVinci Resolve. Creator ($59) adds 4K, and Pro is $175. Usage credits pay for the agent and generative credits pay for generation, so each chat request draws on a usage meter. See Cardboard's pricing.

If you would rather write the video yourself

All nine are products. If you would rather own the video as code, two libraries sit next to them. Remotion renders React components to MP4 and can spread renders across serverless functions. HyperFrames, which HeyGen open-sourced, turns HTML, CSS and JavaScript into MP4 and ships skill packs for Claude Code and Codex. Both leave a project in your repo and no editor UI, which is why they aren't in the nine. This Dev.to comparison goes deeper on them.

A one-hour test to run on your own screens

The numbers above come from published limits, so the last check is your own screens. Run one change through two tools with the same inputs, a 60-minute limit and setup time counted.

Build the first version:

Create a 30-second walkthrough of the Invoices page in a fictional billing app,
Ledgerly, from three supplied screenshots: the invoice list, the filter panel
and the export dialog. Explain how to filter overdue invoices, add one callout
on the Filter button and end on "Export in one click." Keep every on-screen
label exact, invent nothing, and keep the project editable.

Then send the update:

Filter is now called Refine and sits top right. Replace the second screenshot,
update the callout and narration, and keep the first and third scenes as
approved. Make the closing line one second longer within the same 30 seconds,
and export a vertical 1080 x 1920 file.

Several free plans cap exports at 720p, so set the resolution target to what each plan allows. Score each check 0 for a fail, 1 for a pass after manual fixes and 2 for a clean pass. Write down the time taken, what the update drew from the plan and whether the project file reopens.

Check	A pass looks like	A red flag
Exact text	Labels, narration and screens match the new interface	Invented labels, clipped text, redrawn screens
Approved scenes	The first and third scenes are unchanged	The whole video was regenerated
Timing	The extra second comes from a visible place	The length drifted without notice
Vertical version	Screens are rearranged and readable on a phone	A cropped horizontal frame
Delivery	The export plays and the project reopens	Only a video file exists

Choosing after the test

Three questions usually decide between the two tools you tried.

Who makes next month's update? Descript suits someone who edits by reading, Resolve or Premiere someone who already cuts on a timeline, and CoAnimator or Cardboard someone comfortable telling an agent what changed.
How often does the interface change? A few times a year, any re-cut tool works and setup effort matters more than update cost. Every release, update cost dominates and one-scene tools start to pay off.
Do you need the project or only the export? Ask whether the tool can change the project you have or only produce a new file. That decides whether the next update takes a sentence or a rebuild.

My default would be to run the test on the two tools that match your answers and keep the project files as well as the exports. If one of them is CoAnimator, the free plan has no expiry and renders locally, so the test costs only your agent's usage. You can download it here.

What do you do today when a release changes a screen?

README Demo GIFs: I Compared FFmpeg, gifski and MP4 on Four Clips

Harsheen — Tue, 27 Oct 2026 12:30:05 +0000

FFmpeg advice for README GIFs tends to be one command and a handful of numbers, with little evidence behind any of them. The failures are familiar: a demo so heavy the page crawls, or one that loads fast but has its text smeared into dots.

I wanted to know which settings actually earn their place, and whether a different tool would do better. So I wrote a script that draws four fake screen recordings and converts each with 17 FFmpeg GIF recipes, then with gifski, gifsicle and MP4, scoring every file for size and fidelity. Then I opened the files, and on one clip the quality score preferred the banded picture to the smooth one.

How I tested

The clips are 8 seconds long, 1280x720 at 30 fps, and drawn with Pillow so anyone can regenerate them exactly:

click: an invoices screen. The cursor moves, clicks the Unpaid filter, the list re-flows and the result holds.
scroll: a long invoice list scrolling under a gradient header, nonstop.
terminal: npm run build and npm test printing line by line in a dark window.
gradient: a smooth color field drifting behind a text card, a stand-in for a marketing-style dashboard background.

Each clip went through 22 conversions, labelled A to V. Quality is SSIM, which compares every frame with the source at the same size and frame rate and returns 1.0 for a perfect match. The versions were FFmpeg 6.1.1 (Ubuntu build), gifski 1.34.0, gifsicle 1.94, Pillow 12.1.1 and Python 3.12.

The limits are real. The clips are synthetic, with no photos, no embedded video and no subpixel text, so real recordings will differ. SSIM scores pixel fidelity, not legibility or looks, so I judged looks by zooming in. I didn't test animated WebP or APNG, and I didn't measure how GitHub renders any of it.

Results

Each cell shows file size, then SSIM in parentheses (1 MB is 1024 KB). Compare SSIM only between rows of the same width: A and N are full width, J is 800 px, and the rest are 600 px. Rows C to M use FFmpeg's palette method at 10 fps unless the row says otherwise. Rows P to V come up in the sections below.

Recipe	Click	Scroll	Terminal	Gradient
A. Default palette, full width, 30 fps	534 KB (0.689)	10.42 MB (0.763)	92 KB (0.538)	8.40 MB (0.608)
B. Default palette, 600 px, 10 fps	101 KB (0.694)	1.50 MB (0.786)	27 KB (0.550)	1.18 MB (0.618)
C. Base recipe: palette, `bayer_scale=3`	208 KB (0.969)	2.89 MB (0.972)	46 KB (0.959)	3.00 MB (0.956)
D. `dither=none`	157 KB (0.998)	2.20 MB (0.996)	41 KB (0.998)	1.86 MB (0.980)
E. `dither=sierra2_4a`	170 KB (0.997)	2.32 MB (0.996)	45 KB (0.998)	6.28 MB (0.947)
F. Base recipe at 8 fps	170 KB (0.969)	2.41 MB (0.972)	42 KB (0.959)	2.54 MB (0.956)
G. Base recipe at 15 fps	256 KB (0.967)	4.34 MB (0.913)	50 KB (0.958)	3.96 MB (0.955)
H. Base recipe at 20 fps	316 KB (0.968)	5.53 MB (0.977)	55 KB (0.959)	4.78 MB (0.956)
I. Base recipe at 25 fps	364 KB (0.969)	6.74 MB (0.977)	59 KB (0.959)	5.41 MB (0.956)
J. Base recipe at 800 px	316 KB (0.969)	4.48 MB (0.975)	65 KB (0.958)	4.92 MB (0.957)
K. Base recipe with 64 colors	143 KB (0.965)	1.93 MB (0.978)	37 KB (0.957)	1.52 MB (0.934)
L. Base recipe plus `diff_mode=rectangle`	217 KB (0.972)	2.99 MB (0.974)	44 KB (0.959)	2.97 MB (0.955)
M. `dither=none` with 64 colors	103 KB (0.995)	1.49 MB (0.993)	34 KB (0.997)	971 KB (0.967)
N. MP4 (H.264, crf 28), full width, 30 fps	67 KB (0.997)	201 KB (0.995)	43 KB (0.999)	266 KB (0.995)
O. MP4 (H.264, crf 28), 600 px, 30 fps	34 KB (0.993)	159 KB (0.985)	19 KB (0.998)	69 KB (0.992)

Does the palette step matter?

Yes. Generating a palette from the clip first is the biggest effect in the table. Row B, FFmpeg's built-in palette with no palettegen pass, looks like a bargain: 101 KB, 1.50 MB, 27 KB and 1.18 MB. Its SSIM is 0.55 to 0.79, and the dotted noise is obvious against the dark terminal background. Building a palette from the clip first costs 1.7 to 2.5 times the bytes and fixes the picture. I treat B's small size as a defect.

Which dither setting should I use?

Use dither=none for flat UI and terminal footage, and bayer_scale=3 or gifski for gradients. The reasoning matters, because the quality score pointed the other way and I zoomed in to check. FFmpeg's bayer dither takes a bayer_scale from 0 to 5, and on every clip a higher scale gave a smaller file and a higher SSIM:

Dither	Click	Scroll	Terminal	Gradient
`bayer_scale=1`	235 KB (0.758)	3.30 MB (0.794)	50 KB (0.682)	3.52 MB (0.755)
`bayer_scale=2`	214 KB (0.900)	2.97 MB (0.920)	46 KB (0.890)	3.24 MB (0.903)
`bayer_scale=3` (base recipe, C)	208 KB (0.969)	2.89 MB (0.972)	46 KB (0.959)	3.00 MB (0.956)
`bayer_scale=4`	187 KB (0.992)	2.61 MB (0.992)	43 KB (0.978)	2.59 MB (0.972)
`bayer_scale=5`	177 KB (0.996)	2.49 MB (0.995)	42 KB (0.997)	2.43 MB (0.978)
`dither=none` (D)	157 KB (0.998)	2.20 MB (0.996)	41 KB (0.998)	1.86 MB (0.980)
`dither=sierra2_4a` (E)	170 KB (0.997)	2.32 MB (0.996)	45 KB (0.998)	6.28 MB (0.947)

If dithering is new to you, two short Computerphile videos cover the two families. Ordered dithering is what bayer does. Error diffusion is the family sierra2_4a belongs to, and the second video covers Floyd-Steinberg, a close relative.

Zoomed in 3x on a text-free patch of the gradient clip, the pictures run the other way. Scale 2 is a coarse checkerboard. Scale 3 is smooth with a fine pattern. Scales 4 and 5 bring back the flat patches of none, because the pattern that hid them is gone. sierra2_4a, the default dither in paletteuse, is smooth with the finest texture. SSIM scored them 0.980 for the banded none, 0.978 for scale 5, 0.956 for scale 3 and 0.947 for sierra2_4a. Dither adds noise on purpose, and SSIM counts noise as error, so it rewards the dither that hides the least.

sierra2_4a also weighed 6.28 MB on that clip, against 3.00 MB for scale 3. I can't say why. My guess is that error diffusion changes the noise pattern from frame to frame, which leaves GIF's frame-to-frame savings with less to work with.

On the flat clips the trade reverses. dither=none (D) was 25%, 24% and 10% smaller than scale 3 on click, scroll and terminal, and scale 3 left a faint dotted texture on flat areas where none stayed clean.

What frame rate should a README GIF use?

10 fps, and the reason is arithmetic. GIF stores each frame's delay in hundredths of a second, and 10 fps is exactly 100 ms. Not every rate fits. The script's delay column shows 15 fps alternating between 60 and 70 ms, 8 fps between 120 and 130 ms and 30 fps between 30 and 40 ms. The average is right, but individual frames last different lengths.

20 fps and 25 fps give exact delays of 50 and 40 ms, but they cost 21% to 92% and 30% to 134% more bytes than 10 fps. Going down to 8 fps saved 8% to 18%, and 15 fps cost 10% to 50% more. On the scroll clip, the 15 fps file scored 0.913 against 0.972 at 10 fps, while 20 and 25 fps scored 0.977. 8 fps is uneven too and showed no drop, so I can't say the timing is the cause.

How much do width and color count matter?

Width and color count both trade bytes for legibility or smoothness. Going from 600 to 800 px (J against C) added 42% to 64% depending on the clip, so crop tighter before you widen. Small text goes first. In the click clip, the 14 px secondary labels shrink to about 7 px at 600 px wide and turned to smudges in every recipe I zoomed into, while the 24 px titles stayed readable. Judge a crop at the final width, not at full size.

Cutting colors saves about as much as narrowing the frame. A 64-color palette (K) was 19% to 49% smaller than the base recipe, and with none (M) it was 18% to 49% smaller than D. Both cost smoothness. On the gradient clip, K gets a coarser pattern and M turns into blotches, and M put wide vertical stripes in the click clip's gradient header. On the terminal clip, which has no gradients, M looked fine.

Not every setting moved the needle. diff_mode=rectangle (L) stayed within 5% of C on every clip, so it isn't in my recipe.

What makes a GIF big?

How much of the frame changes, more than any setting. With one recipe (C), the terminal clip came to 46 KB and the click clip to 208 KB, while the scroll and gradient clips came to 2.89 MB and 3.00 MB. The gradient clip doesn't scroll, yet it weighs about as much as the one that does, because its colors drift and almost every pixel differs from the previous frame. Before asking how long a demo runs, I ask how much of it changes.

Do gifski and gifsicle beat FFmpeg?

gifski often does, and gifsicle barely does. Rows P to R, against the base recipe:

Tool	Click	Scroll	Terminal	Gradient
FFmpeg base recipe (C)	208 KB (0.969)	2.89 MB (0.972)	46 KB (0.959)	3.00 MB (0.956)
Base recipe plus `gifsicle -O3` (R)	201 KB (0.969)	2.75 MB (0.972)	43 KB (0.959)	3.00 MB (0.956)
`gifski -Q 90` (P)	139 KB (0.992)	1.68 MB (0.984)	57 KB (1.000)	1.92 MB (0.966)
`gifski -Q 70` (Q)	73 KB (0.978)	1.15 MB (0.927)	24 KB (0.999)	664 KB (0.940)

gifsicle's -O3 is lossless and trimmed 0% to 5% off the base recipe, which is worth one command but not a workflow.

gifski at -Q 90 was 33%, 42% and 36% smaller than the base recipe on click, scroll and gradient, and 25% larger on the terminal. On the gradient clip it stayed smooth where none bands, with a fine speckle instead. It stores a repeated frame once with a longer delay, which is why its click GIF has 33 frames to FFmpeg's 80, with holds of up to 3.7 seconds. At -Q 70 the files shrank by another 32% to 66%, and the flat white areas of the click and scroll clips showed visible speckle and streaks. At -Q 90 I saw only faint speckle there.

So gifski earns the install for UI and gradient footage. On the terminal clip FFmpeg beat -Q 90 (41 KB against 57 KB) and needs nothing extra, though -Q 70 was smaller still at 24 KB and looked clean on that dark background.

GIF or MP4 in a GitHub README?

MP4 is far smaller on anything with motion, and about the same size on terminal footage. At 600 px the MP4 (O) was about 6x smaller than the base GIF on the click clip, 19x on scroll, 2x on the terminal and 45x on the gradient. Against gifski -Q 90 the gaps narrow to 4x, 11x, 3x and 29x. The terminal GIF made with dither=none was already 41 KB, so the gap barely matters there.

GitHub's limits shape the rest. Attachments cap images and GIFs at 10 MB, and videos at 10 MB on free plans or 100 MB on paid ones. The naive full-size scroll GIF (A) came to 10.42 MB, over the cap. Video upload works anywhere you write Markdown, READMEs included, with one catch several projects have hit: only videos uploaded through GitHub's own uploader, which produces a user-attachments/assets/... URL, get an inline player. An MP4 committed to the repo and linked by path doesn't (one example), and a <video src> tag pointing elsewhere is stripped (another). Test it on your own repo before you rely on it.

Where the line falls between GIF and video depends on length as well as size, and the next section explains why five seconds matters.

Are README GIFs accessible?

Only partly, and the author controls the part that matters. GitHub respects an OS-level preference for reduced motion, and readers can switch animated images off. Those readers see a still image with a play/pause button. My terminal clip fails that test: its first frame is an empty window with a cursor, which tells a reader nothing. Opening on a title frame fixes that.

The rule behind the five-second figure is WCAG's Pause, Stop, Hide: anything that starts moving by itself, keeps going longer than five seconds and sits beside other content needs a way to stop it. WCAG's own technique for animated GIFs, G152, is to make them stop within five seconds, and -loop -1 in FFmpeg does that by encoding a single play. My clips run 8 seconds, so as encoded they would need a pause control, and the only one a reader gets is GitHub's autoplay setting. That is why I keep demos to five seconds or less and give longer ones a video with controls.

The recipe I'd use

Footage	Tool and setting	Why
Terminal output, flat UI	FFmpeg with `dither=none`	Small and clean on both. gifski `-Q 70` beat it on the terminal clip but speckled white UI
Gradients, soft backgrounds	gifski `-Q 90`, or FFmpeg with `bayer_scale=3`	Both stay smooth, and gifski gave the smaller file
Continuous motion, or longer than about five seconds	MP4 uploaded through GitHub	Far smaller, with playback controls

The FFmpeg command builds the palette and applies it in one filter graph:

ffmpeg -i capture.mp4 -filter_complex "[0:v]fps=10,scale=600:-2:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse=dither=none" -an -loop 0 readme-demo.gif

It produced byte-identical files to the two-pass version the benchmark used, on all four clips. -an drops audio, -loop 0 loops forever (use -loop -1 to play once), and scale=600:-2 fixes the width and lets FFmpeg pick an even height. Add -ss and -t before -i to trim. For gradients, replace none with bayer:bayer_scale=3.

The catch is memory. The palette needs every frame before the first one can be encoded, so FFmpeg holds the clip in RAM. Peak memory was 139 MB for the 8-second scroll clip and 599 MB for a 64-second loop of it (-stream_loop 7 -c copy), against about 70 MB when I ran palettegen and the encode as separate passes, which I measured with /usr/bin/time. For a long recording, write the palette to a PNG first and pass it to paletteuse as a second input.

gifski reads its frames from FFmpeg over a pipe:

ffmpeg -i capture.mp4 -vf "fps=10,scale=600:-2:flags=lanczos" -f yuv4mpegpipe - | gifski -Q 90 -o readme-demo.gif -

That command matched the benchmark's gifski files byte for byte. The recording, trimming and embedding steps are covered in more detail in this walkthrough on the CoAnimator blog.

Run it on your own footage

Save the script below as readme_gif_bench.py, then:

pip install pillow
python3 readme_gif_bench.py                  # the four synthetic clips
python3 readme_gif_bench.py --src demo.mp4   # your own recording
python3 readme_gif_bench.py --keep out       # keep the files so you can zoom in
python3 readme_gif_bench.py --quick          # rows A to O only

It needs FFmpeg and ffprobe on your PATH, with libx264 for the MP4 rows. Rows P to R run only if gifski and gifsicle are installed. Use --keep. SSIM can't see banding, and opening the files is how I caught it.

Full script: readme_gif_bench.py

#!/usr/bin/env python3
"""readme_gif_bench.py: measure what README demo-GIF settings actually cost.

Builds four synthetic 1280x720, 30 fps clips (or uses your own with --src), converts each with a
set of FFmpeg GIF recipes plus H.264 MP4, and prints file size, frame count, GIF frame delays
and SSIM (pixel fidelity against the source at the same size and fps; 1.0 = identical).
Rows P and Q (gifski) and R (gifsicle) run only if those tools are on your PATH.

  python3 readme_gif_bench.py                 # synthetic clips: click, scroll, terminal, gradient
  python3 readme_gif_bench.py --src demo.mp4  # your own recording
  python3 readme_gif_bench.py --keep out      # keep the generated files so you can look at them
  python3 readme_gif_bench.py --quick         # core rows A-O only (skip the extras P-V)

Needs python3, Pillow (pip install pillow), and ffmpeg + ffprobe on PATH (libx264 for the MP4 rows).
SSIM measures fidelity, not legibility: always look at the files. Numbers depend on your footage
and FFmpeg build, so re-run before you quote them.
"""
import argparse
import os
import platform
import re
import shutil
import subprocess
import sys
import tempfile

from PIL import Image, ImageChops, ImageDraw, ImageFont

W, H, FPS = 1280, 720, 30


# ------------------------------------------------------------------ small helpers
def font(size, bold=False, mono=False):
    names = (["DejaVuSansMono.ttf", "Menlo.ttc", "Consolas.ttf", "cour.ttf"] if mono else
             ["DejaVuSans-Bold.ttf", "Arial Bold.ttf", "arialbd.ttf"] if bold else
             ["DejaVuSans.ttf", "Arial.ttf", "arial.ttf"])
    for n in names:
        try:
            return ImageFont.truetype(n, size)
        except OSError:
            pass
    try:
        return ImageFont.load_default(size)
    except TypeError:  # Pillow < 10.1
        return ImageFont.load_default()


def lerp(a, b, t):
    return a + (b - a) * t


def ease(t):
    t = max(0.0, min(1.0, t))
    return t * t * (3 - 2 * t)


def mix(c1, c2, t):
    return tuple(int(lerp(a, b, t)) for a, b in zip(c1, c2))


def ff(args):
    r = subprocess.run(["ffmpeg", "-hide_banner", "-nostdin", "-y", *args], capture_output=True, text=True)
    if r.returncode:
        raise RuntimeError("ffmpeg failed:\n" + r.stderr[-800:])


def probe(path, entries):
    r = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-count_frames",
                        "-show_entries", f"stream={entries}", "-of", "csv=p=0", path],
                       capture_output=True, text=True)
    return r.stdout.strip().split(",")


def duration(path):
    r = subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", path],
                       capture_output=True, text=True)
    try:
        return float(r.stdout.strip())
    except ValueError:
        return None


def ssim(test, src, w, fps, seconds):
    r = subprocess.run(
        ["ffmpeg", "-hide_banner", "-nostdin", "-t", str(seconds), "-i", test, "-t", str(seconds), "-i", src,
         "-filter_complex", f"[0:v]format=yuv420p[t];[1:v]fps={fps},scale={w}:-2:flags=lanczos,format=yuv420p[r];"
                            "[t][r]ssim", "-f", "null", "-"], capture_output=True, text=True)
    m = re.search(r"All:([0-9.]+)", r.stderr)
    return float(m.group(1)) if m else None


def gif_delays(path):
    im, seen = Image.open(path), set()
    for i in range(getattr(im, "n_frames", 1)):
        im.seek(i)
        seen.add(im.info.get("duration", 0))
    return "/".join(str(d) for d in sorted(seen)) if len(seen) <= 3 else "mixed"


# ------------------------------------------------------------------ synthetic clips
INVOICES = [("Northwind Traders #1042", "Priya", "Unpaid", True), ("Fabrikam Studio #1043", "Marco", "Paid", False),
            ("Contoso Retail #1044", "Priya", "Unpaid", True), ("Adventure Works #1045", "Lena", "Draft", False),
            ("Tailspin Toys #1046", "Marco", "Unpaid", True), ("Wingtip Supply #1047", "Lena", "Paid", False),
            ("Litware Group #1048", "Priya", "Draft", False)]
CHIPS = ["All", "Draft", "Unpaid", "Paid"]
ROW_W, ROW_H, LIST_X, LIST_Y = 950, 64, 290, 176


def make_row(title, who, due, overdue):
    img = Image.new("RGB", (ROW_W, ROW_H), (255, 255, 255))
    d = ImageDraw.Draw(img)
    d.rectangle([0, 0, ROW_W - 1, ROW_H - 1], outline=(222, 226, 234))
    d.rounded_rectangle([20, 20, 44, 44], 5, outline=(160, 168, 184), width=2)
    d.text((68, 16), title, font=font(24), fill=(28, 32, 44))
    d.text((68, 42), who, font=font(14), fill=(120, 128, 146))
    bg, fg = ((255, 240, 214), (150, 85, 0)) if overdue else ((233, 238, 250), (60, 80, 150))
    d.rounded_rectangle([ROW_W - 190, 18, ROW_W - 24, 46], 14, fill=bg)
    d.text((ROW_W - 168, 22), due, font=font(18, True), fill=fg)
    return img


def make_static():
    img = Image.new("RGB", (W, H), (245, 246, 250))
    d = ImageDraw.Draw(img)
    d.rectangle([0, 0, 240, H], fill=(31, 36, 48))
    d.text((28, 28), "Ledgerly", font=font(28, True), fill=(255, 255, 255))
    for i, s in enumerate(["Overview", "Invoices", "Clients", "Reports", "Settings"]):
        y = 100 + i * 52
        if s == "Invoices":
            d.rounded_rectangle([14, y - 8, 226, y + 34], 8, fill=(52, 60, 82))
        d.text((34, y), s, font=font(20), fill=(210, 216, 230))
    return img


def make_header():
    img = Image.new("RGB", (W - 240, 84))
    d = ImageDraw.Draw(img)
    for x in range(W - 240):  # horizontal gradient: the part dithering exists for
        d.line([(x, 0), (x, 84)], fill=mix((79, 70, 229), (168, 85, 247), x / (W - 240)))
    d.text((50, 22), "Invoices", font=font(34, True), fill=(255, 255, 255))
    return img


STATIC, HEADER = make_static(), make_header()
ROWS = [make_row(*t) for t in INVOICES]
SCROLL_ROWS = [make_row(f"{INVOICES[i % 7][0].rsplit(' #', 1)[0]} #{1042 + i}", *INVOICES[i % 7][1:]) for i in range(40)]


def draw_chips(img, active):
    d, x, pos = ImageDraw.Draw(img), LIST_X, {}
    for c in CHIPS:
        w = int(d.textlength(c, font=font(20, True))) + 44
        on = c == active
        d.rounded_rectangle([x, 104, x + w, 148], 22, fill=(79, 70, 229) if on else (255, 255, 255),
                            outline=(79, 70, 229) if on else (200, 205, 218), width=2)
        d.text((x + 22, 114), c, font=font(20, True), fill=(255, 255, 255) if on else (70, 78, 98))
        pos[c] = (x + w // 2, 126)
        x += w + 14
    return pos


def cursor(img, x, y):
    pts = [(0, 0), (0, 24), (6, 19), (11, 29), (15, 27), (10, 18), (18, 18)]
    ImageDraw.Draw(img).polygon([(x + a, y + b) for a, b in pts], fill=(255, 255, 255), outline=(0, 0, 0))


def frame_click(t):  # mostly static: move, click a chip, list re-flows, hold
    img = STATIC.copy()
    img.paste(HEADER, (240, 0))
    clicked = t >= 2.5
    tx, ty = draw_chips(img, "Unpaid" if clicked else "All")["Unpaid"]
    tr, n = (ease((t - 2.5) / 0.7) if clicked else 0.0), 0
    for i, row in enumerate(INVOICES):
        y0 = LIST_Y + i * (ROW_H + 10)
        if row[3]:
            y, alpha, n = lerp(y0, LIST_Y + n * (ROW_H + 10), tr), 255, n + 1
        else:
            y, alpha = y0, int(255 * (1 - tr))
        if alpha:
            img.paste(ROWS[i], (LIST_X, int(y)), Image.new("L", ROWS[i].size, alpha))
    if t < 1.2:
        cx, cy = 1000, 560
    elif t < 2.4:
        k = ease((t - 1.2) / 1.2)
        cx, cy = lerp(1000, tx, k), lerp(560, ty, k)
    elif t < 3.4:
        cx, cy = tx, ty
    else:
        k = ease((t - 3.4) / 0.6)
        cx, cy = lerp(tx, 800, k), lerp(ty, 420, k)
    cursor(img, int(cx), int(cy))
    return img


def frame_scroll(t):  # continuous motion under a gradient header
    img = STATIC.copy()
    for i, r in enumerate(SCROLL_ROWS):
        y = 100 + i * (ROW_H + 10) - int(t * 140)
        if -ROW_H < y < H:
            img.paste(r, (LIST_X, y))
    img.paste(HEADER, (240, 0))
    return img


GH = Image.linear_gradient("L").transpose(Image.ROTATE_90).resize((W + 600, H), Image.BICUBIC)
GV = Image.linear_gradient("L").resize((W, H + 300), Image.BICUBIC)
GR = Image.radial_gradient("L").resize((W + 500, H + 300), Image.BICUBIC)
CARD = Image.new("RGBA", (W, H), (0, 0, 0, 0))
ImageDraw.Draw(CARD).rounded_rectangle([120, 190, 860, 530], 28, fill=(255, 255, 255, 46))


def frame_gradient(t):  # smooth colour field drifting behind a card: the case dithering is for
    a, b, c = int(t * 70), int(t * 35), int(t * 45)
    r = GH.crop((a, 0, a + W, H)).point(lambda p: 40 + p * 0.6)
    g = GV.crop((0, b, W, b + H)).point(lambda p: 20 + p * 0.55)
    bl = GR.crop((c, int(t * 25), c + W, int(t * 25) + H)).point(lambda p: 90 + p * 0.5)
    img = Image.alpha_composite(Image.merge("RGB", (r, g, bl)).convert("RGBA"), CARD).convert("RGB")
    d = ImageDraw.Draw(img)
    d.text((160, 220), "Release dashboard", font=font(54, True), fill=(255, 255, 255))
    for i, line in enumerate(["Builds passed: 4,812", "Deploys this week: 31", "Median build time: 1m 48s"]):
        d.text((160, 320 + i * 52), line, font=font(28), fill=(240, 242, 255))
    d.text((160, 484), "Updated just now", font=font(16), fill=(225, 228, 245))
    return img


TERM = [  # (start s, prompt, text, colour, typed?)
    (0.4, "$ ", "npm run build", (235, 235, 235), True),
    (1.6, "", "vite v5.4 building for production...", (150, 156, 172), False),
    (2.1, "", "42 modules transformed.", (150, 156, 172), False),
    (2.6, "", "dist/index.html        0.46 kB", (110, 190, 255), False),
    (2.8, "", "dist/assets/app.js    148.20 kB", (110, 190, 255), False),
    (3.0, "", "built in 1.84s", (90, 205, 130), False),
    (4.2, "$ ", "npm test", (235, 235, 235), True),
    (5.2, "", "PASS  src/parse.test.ts", (90, 205, 130), False),
    (5.5, "", "PASS  src/render.test.ts", (90, 205, 130), False),
    (5.8, "", "Tests: 12 passed, 12 total", (235, 235, 235), False),
]


def frame_term(t):  # dark background, monospace text appearing line by line
    img = Image.new("RGB", (W, H), (24, 26, 33))
    d = ImageDraw.Draw(img)
    d.rectangle([0, 0, W, 44], fill=(40, 43, 54))
    for i, c in enumerate([(255, 95, 86), (255, 189, 46), (39, 201, 63)]):
        d.ellipse([20 + i * 28, 14, 36 + i * 28, 30], fill=c)
    f, y, end = font(28, mono=True), 80, (40, 80)
    for start, prompt, text, col, typed in TERM:
        if t < start:
            break
        shown = text[:int((t - start) * 16) + 1] if typed else text
        d.text((40, y), prompt, font=f, fill=(90, 205, 130))
        x = 40 + d.textlength(prompt, font=f)
        d.text((x, y), shown, font=f, fill=col)
        end = (x + d.textlength(shown, font=f), y)
        y += 44
    if int(t * 2) % 2 == 0:
        d.rectangle([end[0] + 4, end[1] + 2, end[0] + 20, end[1] + 32], fill=(235, 235, 235))
    return img


def make_clip(path, fn, seconds):
    p = subprocess.Popen(["ffmpeg", "-hide_banner", "-loglevel", "error", "-y", "-f", "rawvideo", "-pix_fmt", "rgb24",
                          "-s", f"{W}x{H}", "-r", str(FPS), "-i", "-", "-c:v", "libx264", "-crf", "12",
                          "-pix_fmt", "yuv420p", path], stdin=subprocess.PIPE)
    for n in range(int(seconds * FPS)):
        p.stdin.write(fn(n / FPS).tobytes())
    p.stdin.close()
    if p.wait():
        raise RuntimeError("could not encode the synthetic clip (is libx264 available?)")


# ------------------------------------------------------------------ converters
BASE = "bayer:bayer_scale=3"


def gif(src, out, w, fps, seconds, palette=True, dither=BASE, colors=256, diff=False):
    base = f"fps={fps},scale={w}:-2:flags=lanczos"
    if not palette:  # FFmpeg's default palette
        return ff(["-t", str(seconds), "-i", src, "-vf", base, "-loop", "0", out])
    pal = out + ".palette.png"
    gen = f"palettegen=max_colors={colors}" + (":stats_mode=diff" if diff else "")
    ff(["-t", str(seconds), "-i", src, "-vf", f"{base},{gen}", "-frames:v", "1", "-update", "1", pal])
    use = f"paletteuse=dither={dither}" + (":diff_mode=rectangle" if diff else "")
    ff(["-t", str(seconds), "-i", src, "-i", pal, "-filter_complex", f"[0:v]{base}[v];[v][1:v]{use}",
        "-an", "-loop", "0", out])
    os.remove(pal)


def mp4(src, out, w, fps, seconds, crf=28):
    ff(["-t", str(seconds), "-i", src, "-vf", f"fps={fps},scale={w}:-2:flags=lanczos", "-c:v", "libx264",
        "-preset", "slow", "-crf", str(crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart", "-an", out])


def gifski(src, out, w, fps, seconds, quality=90):
    feed = subprocess.Popen(["ffmpeg", "-hide_banner", "-loglevel", "error", "-nostdin", "-t", str(seconds), "-i", src,
                             "-vf", f"fps={fps},scale={w}:-2:flags=lanczos", "-f", "yuv4mpegpipe", "-"],
                            stdout=subprocess.PIPE)
    r = subprocess.run(["gifski", "-Q", str(quality), "-o", out, "-"], stdin=feed.stdout, capture_output=True)
    feed.stdout.close()
    feed.wait()
    if r.returncode:
        raise RuntimeError("gifski failed:\n" + r.stderr.decode()[-500:])


def gifsicle(src_gif, out):
    r = subprocess.run(["gifsicle", "-O3", src_gif, "-o", out], capture_output=True)
    if r.returncode:
        raise RuntimeError("gifsicle failed:\n" + r.stderr.decode()[-500:])


RECIPES = [  # label, kind, width (0 = full width), fps, options
    ("A. default palette, full width, 30 fps", "gif", 0, 30, {"palette": False}),
    ("B. default palette, 600 px, 10 fps", "gif", 600, 10, {"palette": False}),
    ("C. base recipe: palette + bayer_scale=3, 600 px, 10 fps", "gif", 600, 10, {}),
    ("D. dither=none", "gif", 600, 10, {"dither": "none"}),
    ("E. dither=sierra2_4a", "gif", 600, 10, {"dither": "sierra2_4a"}),
    ("F. base recipe at 8 fps", "gif", 600, 8, {}),
    ("G. base recipe at 15 fps", "gif", 600, 15, {}),
    ("H. base recipe at 20 fps", "gif", 600, 20, {}),
    ("I. base recipe at 25 fps", "gif", 600, 25, {}),
    ("J. base recipe at 800 px", "gif", 800, 10, {}),
    ("K. base recipe with 64 colors", "gif", 600, 10, {"colors": 64}),
    ("L. base recipe + diff_mode=rectangle", "gif", 600, 10, {"diff": True}),
    ("M. dither=none with 64 colors", "gif", 600, 10, {"dither": "none", "colors": 64}),
    ("N. MP4 (H.264 crf 28), full width, 30 fps", "mp4", 0, 30, {}),
    ("O. MP4 (H.264 crf 28), 600 px, 30 fps", "mp4", 600, 30, {}),
]
EXTRAS = [  # skipped by --quick; P-R need gifski / gifsicle on PATH
    ("P. gifski -Q 90, 600 px, 10 fps", "gifski", 600, 10, {"quality": 90}),
    ("Q. gifski -Q 70, 600 px, 10 fps", "gifski", 600, 10, {"quality": 70}),
    ("R. base recipe + gifsicle -O3", "gifsicle", 600, 10, {}),
    ("S. bayer_scale=1", "gif", 600, 10, {"dither": "bayer:bayer_scale=1"}),
    ("T. bayer_scale=2", "gif", 600, 10, {"dither": "bayer:bayer_scale=2"}),
    ("U. bayer_scale=4", "gif", 600, 10, {"dither": "bayer:bayer_scale=4"}),
    ("V. bayer_scale=5", "gif", 600, 10, {"dither": "bayer:bayer_scale=5"}),
]


def bench(name, src, seconds, work, have_x264, quick=False):
    src_w = int(probe(src, "width")[0])
    seconds = round(min(seconds, duration(src) or seconds), 2)
    print(f"\n### {name} (source {os.path.getsize(src) / 1024:.0f} KB, {src_w} px wide, {seconds:g} s)\n")
    print("| Recipe | Size | Frames | Delay (ms) | SSIM |\n|---|---:|---:|---:|---:|")
    for label, kind, w, fps, opts in RECIPES + ([] if quick else EXTRAS):
        if kind == "mp4" and not have_x264:
            print(f"| {label} | skipped (no libx264) | | | |")
            continue
        tool = {"gifski": "gifski", "gifsicle": "gifsicle"}.get(kind)
        if tool and not shutil.which(tool):
            print(f"| {label} | skipped ({tool} not on PATH) | | | |")
            continue
        w = min(w or src_w, src_w)
        if kind == "mp4":
            w -= w % 2  # H.264 4:2:0 needs even dimensions
        out = os.path.join(work, f"{name}-{label[0]}." + ("mp4" if kind == "mp4" else "gif"))
        if kind == "gifsicle":
            gifsicle(os.path.join(work, f"{name}-C.gif"), out)
        else:
            {"gif": gif, "mp4": mp4, "gifski": gifski}[kind](src, out, w, fps, seconds, **opts)
        size = os.path.getsize(out)
        s = ssim(out, src, w, fps, seconds)
        human = f"{size / 1048576:.2f} MB" if size > 1048576 else f"{size / 1024:.0f} KB"
        print(f"| {label} | {human} | {probe(out, 'nb_read_frames')[0]} | "
              f"{gif_delays(out) if kind == 'gif' else '-'} | {f'{s:.4f}' if s else '-'} |")


def main():
    ap = argparse.ArgumentParser(description="Benchmark README demo-GIF settings against MP4.")
    ap.add_argument("--src", help="benchmark your own recording instead of the synthetic clips")
    ap.add_argument("--seconds", type=float, default=8.0, help="seconds to convert (default 8)")
    ap.add_argument("--keep", help="keep generated files in this directory")
    ap.add_argument("--quick", action="store_true", help="core rows A-O only")
    a = ap.parse_args()
    for tool in ("ffmpeg", "ffprobe"):
        if not shutil.which(tool):
            sys.exit(f"{tool} not found on PATH")
    if a.src and not os.path.isfile(a.src):
        sys.exit(f"file not found: {a.src}")
    enc = subprocess.run(["ffmpeg", "-hide_banner", "-encoders"], capture_output=True, text=True).stdout
    have_x264 = "libx264" in enc
    ver = subprocess.run(["ffmpeg", "-version"], capture_output=True, text=True).stdout.splitlines()[0]
    print(f"{ver}\nPillow {getattr(Image, '__version__', '?')}, Python {platform.python_version()}, "
          f"{platform.system()}")
    work = a.keep or tempfile.mkdtemp(prefix="gifbench-")
    os.makedirs(work, exist_ok=True)
    try:
        if a.src:
            bench("your-recording", a.src, a.seconds, work, have_x264, a.quick)
        else:
            if not have_x264:
                sys.exit("the synthetic clips need ffmpeg with libx264; pass --src with your own video instead")
            for name, fn in (("click", frame_click), ("scroll", frame_scroll), ("terminal", frame_term),
                             ("gradient", frame_gradient)):
                src = os.path.join(work, f"{name}-source.mp4")
                make_clip(src, fn, a.seconds)
                bench(name, src, a.seconds, work, have_x264, a.quick)
    except RuntimeError as e:
        sys.exit(str(e))
    finally:
        if a.keep:
            print(f"\nFiles kept in {work}")
        else:
            shutil.rmtree(work, ignore_errors=True)


if __name__ == "__main__":
    main()

What I'd test next

Three things I didn't measure, in the order I'd like to see numbers for them.

The first is real footage. My clips are tidy, while screen recordings carry video content, subpixel text and compression noise, and I don't know where the line between none, bayer and gifski falls for them. The second is animated WebP and APNG, which FFmpeg can encode, but I haven't checked what GitHub does with them. The third is a guard in CI: a small check that fails a pull request when a README image passes a size budget would catch the next oversized demo before it merges. I haven't built that yet.

If you run the script on your own recording, I'd like to see your table. Paste it in the comments, especially if it ranks the settings differently.

Hey Guys!! I am back again after a long break. Just published my latest post, show some love👀🤩

Harsheen — Wed, 21 Oct 2026 12:40:07 +0000

How I Triage Release Notes Before Claude Code Turns Them Into a Product Video

Harsheen — Wed, 21 Oct 2026 12:35:31 +0000

Ask an agent to make a video from CHANGELOG.md and it will often treat every line as content, including the dependency bump. Nothing looks wrong until the render, where the React upgrade has six seconds of screen time.

I would rather argue about a cut list than about a finished video. So I wrote a small script that sorts a changelog into keep, cut and "a human should look" before the agent sees it. The sorting turned out to be the boring part. The rows the script refuses to decide are the interesting ones.

Why the raw changelog is a bad input

A changelog is written for the team that shipped the release. It records what happened, in the order a maintainer thinks about it, and nothing in the file says which entries a customer cares about.

That leaves an agent two ways to go wrong. The first is coverage: it can treat every line as content. The second is confidence: when a line is thin, a model tends to fill the gap with a stronger headline than the line supports. A fix for one crash turns into "crashes are gone". Both mistakes are cheap to catch in a table and expensive to catch in a render.

The script

It reads a changelog in the Keep a Changelog layout, takes the newest dated release, and prints a verdict for every entry. It uses only the standard library.

#!/usr/bin/env python3
"""Draft a keep/cut table for the newest dated release in a CHANGELOG.md."""
import argparse
import re
import sys
from pathlib import Path

RELEASE = re.compile(r"^##\s+\[?(?P<ver>[^\]\s]+)\]?\s*(?:-\s*(?P<date>\d{4}-\d{2}-\d{2}))?(?P<tail>.*)$")
INTERNAL = re.compile(r"\b(bump|upgrade[sd]?|dependenc\w+|deps?|refactor\w*|lint\w*|chore|typo|tests?|ci|rename[sd]?)\b", re.I)
JARGON = re.compile(r"\b(race condition|deadlock|mutex|queue|worker|thread|pool|cache|index|orm|migration script)\b", re.I)
COMPARATIVE = re.compile(r"\b(faster|quicker|smaller|lighter|snappier|speed(s|ed)? up|reduced?)\b", re.I)
FIGURE = re.compile(r"\d[\d.,]*\s?(%|x\b|ms\b|(seconds?|secs?|s)\b|(minutes?|mins?)\b|[KMG]B\b|times\b)|\b(half|twice|double|triple)\b", re.I)


def newest_release(lines):
    """Return (version, date, {group: [entries]}) for the first dated, non-yanked release."""
    release, group, found = None, None, []
    for line in lines:
        m = RELEASE.match(line)
        if m:
            release, group = m, None
            if m["date"] and "yanked" not in m["tail"].lower():
                found.append((m["ver"], m["date"], {}))
            continue
        if line.startswith("### "):
            group = line[4:].strip()
        elif re.match(r"^[-*]\s+", line) and release and found and release["date"] \
                and "yanked" not in release["tail"].lower() and group:
            found[-1][2].setdefault(group, []).append(re.sub(r"^[-*]\s+", "", line).strip())
    return found[0] if found else None


def triage(group, entry):
    if group == "Security":
        return "ASK", "a person decides if this goes on screen"
    if INTERNAL.search(entry):
        return "CUT", "reads as internal work"
    if len(entry.split()) < 4:
        return "REWRITE", "too vague to turn into a headline"
    if JARGON.search(entry):
        return "REWRITE", "names a component customers never see"
    if group in ("Deprecated", "Removed"):
        return "SCENE", "customers lose something, say it plainly"
    if COMPARATIVE.search(entry) and not FIGURE.search(entry):
        return "NEEDS NUMBER", "comparative claim with no figure in the notes"
    return "SCENE", ""


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("path")
    ap.add_argument("--title", type=int, default=3, help="title card seconds")
    ap.add_argument("--per", type=int, default=6, help="seconds per scene")
    ap.add_argument("--cap", type=int, default=40, help="runtime cap in seconds")
    ap.add_argument("--strict", action="store_true", help="exit 1 if ASK, REWRITE or NEEDS NUMBER rows remain")
    args = ap.parse_args()

    rel = newest_release(Path(args.path).read_text().splitlines())
    if not rel:
        sys.exit("No dated, non-yanked release found.")
    ver, date, groups = rel

    print(f"Release {ver} ({date})\n")
    print("| Group | Entry | Verdict | Why |")
    print("|---|---|---|---|")
    scenes, open_rows = 0, 0
    for group, entries in groups.items():
        for e in entries:
            verdict, why = triage(group, e)
            scenes += verdict == "SCENE"
            open_rows += verdict in ("ASK", "REWRITE", "NEEDS NUMBER")
            print(f"| {group} | {e} | {verdict} | {why} |")

    runtime = args.title + scenes * args.per
    flag = "  <- over the cap" if runtime > args.cap else ""
    print(f"\n{scenes} scenes, about {runtime}s of {args.cap}s{flag}")
    if args.strict and open_rows:
        sys.exit(1)


if __name__ == "__main__":
    main()

The rules are deliberately dumb:

Skips what shouldn't be read. It ignores [Unreleased], because those lines haven't shipped. It also ignores any release marked [YANKED], because that release was pulled.
CUT. Words like bump, upgrade, refactor, lint and chore suggest internal work.
REWRITE. An entry under four words is too thin for a headline. An entry that names a queue, a worker or a deadlock describes something customers never see.
NEEDS NUMBER. Words like faster, quicker or smaller with no figure in the entry. A figure means a number next to a unit, a percent or a multiplier, or a word like "twice".
ASK. Anything under Security goes to a person, every time.
The runtime budget. A title card plus six seconds per scene, checked against a cap. This catches the "we have eight features and 40 seconds" problem before any scene exists.

A test run on an invented changelog

Here is the file I tested with. The app, Fieldnote, is made up so there is no real customer data in it.

## [Unreleased]

### Added
- Shared folders (behind a feature flag).

## [2.8.0] - 2026-10-14

### Added
- Offline mode for iOS.
- Tag filters in search.

### Changed
- Upgrade React to 19.1.
- Search results open faster on large libraries.

### Removed
- Dropped the legacy Markdown importer.

### Fixed
- Fix race condition in sync queue.
- Fix crash when opening notes over 10,000 characters.
- Misc fixes.

### Security
- Sanitize HTML in the note preview.

## [2.7.1] - 2026-09-30 [YANKED]

### Fixed
- Fix login redirect.

And what python changelog_triage.py CHANGELOG.md printed:

Group	Entry	Verdict	Why
Added	Offline mode for iOS.	SCENE
Added	Tag filters in search.	SCENE
Changed	Upgrade React to 19.1.	CUT	reads as internal work
Changed	Search results open faster on large libraries.	NEEDS NUMBER	comparative claim with no figure in the notes
Removed	Dropped the legacy Markdown importer.	SCENE	customers lose something, say it plainly
Fixed	Fix race condition in sync queue.	REWRITE	names a component customers never see
Fixed	Fix crash when opening notes over 10,000 characters.	SCENE
Fixed	Misc fixes.	REWRITE	too vague to turn into a headline
Security	Sanitize HTML in the note preview.	ASK	a person decides if this goes on screen

The footer reads 4 scenes, about 27s of 40s. The shared-folders flag and the yanked 2.7.1 never appear, which is the point.

Two rows deserve a second look. "Search results open faster on large libraries" is the one a reader caught. My first version let it through as a SCENE, but a speed claim invites a number, and the note doesn't contain one. If an agent writes "twice as fast" on that scene, it made the number up. The script now flags it, and the fix on screen is a side-by-side recording of the slow path and the fast one, not a figure read aloud.

The "Misc fixes" row is the other. No script can fix it. Someone who knows what shipped has to write the real line, and that is the whole argument for doing this triage before the agent runs.

Hand the table to Claude Code

Setup is the boring part and the docs cover it better than I would. In the CoAnimator app, Settings, General, Command line and agent skill has an install button for each, and the CLI docs cover the command. Claude Code comes from Anthropic's setup guide. If you want background on what the agent can do inside a project, this post covers it.

Then I would send the dated section, the table, and a brief like this:

Here is a triage table for Fieldnote 2.8.0 and the dated changelog section it came from. Treat the table as a proposal. For each row, confirm or overrule the verdict and give one sentence of reasoning. For REWRITE rows, propose a customer-facing line and quote the source words it came from. For NEEDS NUMBER rows, do not describe the improvement in words. Ask me for a before and after recording to show it. Do not state any number, speed or percentage that is not in the notes. Build nothing until I reply.

Three instructions do most of the work. "Quote the source words" forces every headline to point at its entry. The NEEDS NUMBER rule turns a claim nobody can verify into a shot someone can record. And "build nothing until I reply" turns the first answer into something you can correct for the price of one sentence. Each SCENE row also needs a screenshot or recording to attach, or the scene will be text on a background.

What I still check by hand

Once the build is approved, the render step is a single coa render <project>. For a quick look at the title card, --start 0 --end 6 renders only the first six seconds. The script can't check the rest, so I go through these:

Headline strength. "Large notes no longer crash the app" matches the crash entry. "Crashes are gone" doesn't.
Version and date against the tag. The card can say 2.8.0 while the repo's latest tag is v2.8.1 after a hotfix. git describe --tags --abbrev=0 prints the latest tag in one second.
Text outside the scenes. Closing cards and subtitles never passed through the table, and that is where stock claims like "faster than ever" show up.

Gate it in CI

--strict makes the script exit 1 while any ASK, REWRITE or NEEDS NUMBER row is unresolved. Fix a REWRITE or NEEDS NUMBER row by editing the entry in the changelog, and the next run passes. I tested the exit code locally, and I haven't wired it into a release pipeline yet. The step itself is two lines:

- name: Changelog triage
  run: python changelog_triage.py CHANGELOG.md --strict

Any Security entry fails strict mode on purpose, so a person has to look at it. Once someone has, run that release without --strict.

The table prints to the job log, so whoever reviews the failed run sees exactly which rows need a person.

Where the heuristics break

It matches words, not meaning, and it will be wrong in both directions:

"Add CI status badge to dashboard" gets CUT because of "CI", though customers see that badge.
"Upgrade your plan from the app" gets CUT because of "upgrade".
"Add index of recent files" gets REWRITE because of "index".
"Add reduce motion option in settings" gets NEEDS NUMBER because of "reduce", though it names an accessibility setting, not a claim.
It only checks that a figure exists, not that it's true. "40% faster" passes even if nobody measured 40%.
A claim worded without a trigger word, like "no more waiting", gets through.

That is why the script proposes and the agent and I decide. It also can't tell whether a change is visible to a customer, because it only sees the words.

One privacy point. The script runs locally, but whatever you paste into an agent can leave your machine for its provider. CoAnimator's quickstart says the same about files and frames sent to an AI provider. Delete embargoed rows from the table before pasting, and crop customer data out of screenshots.

FAQ

Does it work with changelogs that aren't in Keep a Changelog format?
It needs ## [version] - date headings and ### groups. GitHub's generated release notes have neither, so the parser would need a small change.

Does the script replace reading the notes?
No. It's a first draft of the cut list so the conversation with the agent starts from something concrete.

Do I need CoAnimator for this?
No. The table works with any agent or video workflow. I use CoAnimator for the render step.

Next step: let the PR decide

Regex is a fallback. The better signal is the person who wrote the change. A customer-facing label on the pull request, or a one-line release-note field in the PR template, would let the table come from labels and leave the regex to catch whatever nobody labeled. Then the triage happens at merge time, when the author still remembers why the change matters.

A second check: compare each SCENE row with the files its change touched, and flag rows where no UI files moved. Those rows tend to turn into a title card over an unchanged screen, which is where made-up claims creep in. The right unit is the release tag, not the single PR, because a feature often lands across several PRs and only the last one touches the UI. My sample entries carry no PR numbers yet, so the sketch starts there: add them to the end of each entry, take the union of files across a row's PRs with gh pr view <n> --json files, and flag the row only if none of them touched a UI path. git diff --name-only <prev-tag>..<tag> is the cheap release-level version: if no UI file moved at all, every visual row is suspect.

Try the script on your last release and see which rows you disagree with. Those are the decisions your changelog never recorded. If you want to turn the approved rows into a video, the CoAnimator desktop app is where I'd render them or you can use your existing video workflow.