How to Make a Video Changelog with AI, Step by Step

A video changelog is the watchable version of your release notes. Customers who never read a changelog will watch 30 seconds of one in a client update or on LinkedIn.

This is what you are making:

What do you need?

Everything here is free except the optional paid voice.

• A changelog. A plain list of what changed in each release. We keep a CHANGELOG.md in the Keep a Changelog format.
• Node.js. Runs the scripts that glue the steps together.
• ffmpeg. The free command-line video tool. It joins the scenes, mixes the sound and writes the final file.
• A headless browser. We use Playwright. It draws the title cards and records the real site.
• A voice. A free macOS voice, a paid stock AI voice, or a clone of your own.
• A transcriber. We use Whisper. It listens back to every line so you do not have to.
• An AI coding agent (optional). It can write the scripts and run every step. You can also do each step by hand.

How do you make a video changelog, step by step?

Step 1: Pick three or four changes

Open the changelog for the release. Pick the three or four changes a customer would notice. Leave out refactors, dependency bumps and anything you would have to explain.

Check: every change you picked is in the written changelog. The video must never claim something the release did not do.

Step 2: Write one scene per change

Each change becomes one scene in a file called script.json. A scene has the words on screen and the words spoken:

{
  "id": "post",
  "tag": "ADDED",
  "title": "A new article on WA cyber attacks",
  "say": "We added a new article on this year's W A cyber attacks.",
  "caption": "We added a new article on this year's WA cyber attacks."
}

say is written for the ear and caption for the eye. A voice may read "WA" as one word, so the spoken line spells it out. "0.0.32" becomes "zero point zero point thirty-two".

Add a short intro scene and a short outro. Five scenes is about 30 seconds.

Check: read the say lines out loud. If you run out of breath, the line is too long.

Step 3: Generate the voice

Make one audio file per scene, and keep each file until its line changes. Then fixing one word means regenerating one line, not the whole clip.

You have three choices of voice:

The free option is one command per line:

say -v Karen -r 175 -o intro.wav --file-format=WAVE --data-format=LEI16@48000 "Here's what shipped in release zero point zero point thirty-two."

Check: a cloned voice needs the person's consent, and a label on the video saying it is an AI voice.

Step 4: Check every line by transcribing it

AI voices make mistakes you will not notice on the tenth listen. They drop the last word, or add a phrase that was never in the script.

So do not listen. Transcribe each audio file with Whisper and compare the text with your script. If the last word of the line is missing, regenerate that line.

Check: the transcript of every line matches its caption.

Step 5: Show the change

There are two ways to put a change on screen.

• Title cards. Small HTML pages in your site's own fonts, saved as images by the headless browser. Quick to make, and enough for most releases.
• Screen recordings. The headless browser opens the real page at phone or desktop size, scrolls and taps through it, and saves about 40 screenshots a second. ffmpeg turns those into video.

For a bug fix, record the page twice: once from the code one commit before the fix, and once from the fix itself.

Check: the recording shows the real site, not a mock-up.

Step 6: Set the timing and add music

• Timing. Each scene lasts as long as its voice line plus about a second. Put a fade, slide or wipe in the gap between scenes.
• Music. Ours is written note by note in code, so there is nothing to license. Use a calm bed for release notes and a brighter 120 to 128 BPM track for social clips.
• Mix. Make the music duck under the voice, then level the whole clip to -16 LUFS, a common loudness target for online video. ffmpeg does both with its sidechaincompress and loudnorm filters.

Check: you can follow every word at low volume.

Step 7: Add captions and export

The scene timings you already have also write the caption file, in WebVTT format. Plenty of people watch on mute, so do not skip this.

For feeds that autoplay without sound, burn the captions into the picture instead:

Export as H.264 video with AAC audio, and put the file's index at the front so the clip starts playing before it has finished downloading:

ffmpeg -i scenes.mp4 -i mix.wav -c:v libx264 -pix_fmt yuv420p -c:a aac -b:a 96k -movflags +faststart changelog.mp4

Check: the file is under about 3 MB for 30 seconds.

Step 8: Watch it twice

A person watches the finished clip once with sound and once without. This is the step you do not hand to the agent.

Check: the words match what shipped, nothing is cut off, and it makes sense on mute.

Which format should you make?

Pick by where the clip will be watched.

The roundup is at the top of this post. Here are the other four.

What does the AI agent do, and what does a person do?

The agent:

• writes the script from the changelog
• generates each voice line and checks it with the transcriber
• records the site and renders the clip

A person:

• confirms the words match what shipped
• gives consent for any cloned voice
• watches and signs off the final cut

It's the same split we use in other AI automation work.

How much does a video changelog cost to make?

Almost nothing per clip. The macOS and cloned-voice clips cost nothing beyond the Mac they ran on. The two Gemini-voiced clips cost about one US cent together.

The real cost is building the pipeline once. After that, a new release is a new script.json and one command.

Where does a video changelog fit in your release process?

At the end, triggered by the same tag that publishes your written notes. That way the video never claims something the release didn't do.

If you'd like that in your own pipeline, it's part of our DevOps consulting. You can also see how we run projects on our process page.

Photo credits. All images used under the Unsplash License, free for commercial use, attribution appreciated:

• Video editing timeline — Peter Stumpf
• Studio microphone — Jonathan Velasquez
• Perth skyline in the release 0.0.32 video — Nathan Hurst