TLDR: I needed to turn a batch of screen recordings into a YouTube-ready comparison video for CarouselBot. I tried two approaches with Claude Code: building a structured CLI tool, and just installing FFmpeg, Puppeteer, and the Nano Banana 2 API and letting Claude Code figure it out. The tool-empowered approach won by a large margin.
Disclosure: This article was written by me, a human. Claude helped me research tool specs; I also used Claude Code to develop test scripts for the video pipeline and make direct edits to my sample video.
A word from our sponsor
This article is brought to you by CarouselBot, which now lets you turn blogs and articles into eBooks in five minutes or less. This YouTube video directly compares CarouselBot’s document generation feature to Gamma’s.
p.s., The YouTube video is not as polished as I would have liked, as it’s missing a title card for my “talking head” and the audio track could have benefited from a good scrub for ums, ahs, etc.
I recently set up a YouTube channel, mostly to promote CarouselBot and make sure my content appears in Google’s video search results. And, since I’ve learned that YouTube favors product comparison videos, I decided to make a video directly comparing CarouselBot with Gamma for document generation.
I started by breaking the narrative into chapters (intro, create with Gamma, create with CarouselBot, etc.) and used ScreenStudio to record each one, which left me with a pile of clips. To connect these clips into a watchable video, l needed to splice in a branded cover image, chapter divider cards, a speaker name card overlay, and a back cover, and fade transitions between everything. And, because I anticipate creating multiple videos like this, I wanted some way to automate it all.
In my previous life as a director at a content agency, I’d sometimes pitch in and help edit videos during busy periods, so I know how tricky this work is. Fiddling with transitions, syncing audio tracks, and getting the timing right on a simple fade in Premiere Pro is all incredibly time-consuming. That’s why I decided to build an automation that would handle the whole post-production assembly for me, from raw clips to upload-ready video, and do it in a way that I could repeat across multiple videos.
This article is about what I learned in the process, and specifically about why empowering Claude Code with the right tools worked so much better than the structured CLI tool I tried to build first.
Two approaches, very different results
I tried this two ways.
A CLI video editing tool
First, I had Claude Code build me a proper CLI tool that included:
Inquirer menus for selecting which clips and cards to include.
A commander for argument parsing.
Project configuration files that stored the video structure: cover, then the Gamma screen recording, then a chapter card, then the CarouselBot recording, then the next chapter card, and so on. (As noted above, the idea was to create something repeatable I could run for every comparison video in the series.)
The problem was that every chapter in the video needed a constant stream of micro-adjustments. Delete this clip, it’s redundant, add a longer transition here, move the speaker card, etc. It was hard to standardize a pipeline when the edits kept changing, and trying to express all of those one-off fixes through CLI arguments or config files felt like fighting the tool instead of using it.
Conversation with Claude Code
So I tried a different approach which was giving Claude Code some tools and working conversationally.
I installed FFmpeg and Puppeteer locally, set up a Nano Banana 2 API key, and then just talked to Claude Code in plain English: “Here are the screen recordings for the CarouselBot vs Gamma comparison. Put the cover image first with a one-second fade, then the chapter one clips, then this chapter divider, then chapter two. Overlay the speaker name card on the first five seconds. Normalize the audio.”
This was better. When I needed a micro-adjustment, I could just say so and Claude Code would tweak the FFmpeg command, re-run, and I’d review the result. “That fade between the chapter card and the Gamma recording is too long” and it was fixed in seconds. “Move the speaker card down, it’s overlapping the CarouselBot toolbar” and it was done. The conversational approach handled the constant small changes much more naturally and flexibly.
I think the CLI would have been significantly better if I’d spent more time considering my requirements before scoping it.
It failed because I was trying to standardize a process I hadn’t fully figured out yet, which meant the tool kept needing changes almost as fast as the videos did. Once I know which decisions are truly repeatable and which ones need to stay flexible, I will probably take another pass at the tool. But for a first attempt, the conversational approach was the faster path to a finished video.
The tools that made it work
I gave Claude Code access to a collection of useful video production tools and let it figure out the orchestration.
FFmpeg
FFmpeg is the command-line tool that handles the actual video processing: encoding, concatenating clips, overlaying images, and normalizing audio. Claude Code runs it natively because it’s already a CLI tool, so no MCP server is needed.
What it handled for my comparison videos: concatenating everything in order (cover image clip, chapter one Gamma recording, chapter divider card clip, chapter one CarouselBot recording, next divider, and on through the whole structure). Overlaying a transparent PNG speaker card on the intro. Encoding still card images into short video clips with fade transitions. Normalizing audio to YouTube’s -14 LUFS standard.
What it can’t do: anything requiring visual judgment. Text rendering through FFmpeg’s drawtext filter is unreliable (it might not even be compiled in on your system), and it has absolutely no concept of whether something looks good.
Don’t re-encode everything all the time
My first assembly attempt took 15+ minutes per chapter, and that was entirely my fault. I had Claude Code re-encoding every source clip, including the screen recordings that didn’t need to change at all.
If you’re coming from a video editing background this is probably obvious, but it took me a while to understand that you only need to encode what you’re creating from scratch (the card images turned into short video clips). Everything else can be joined using transport stream concatenation, which essentially copies the original streams without touching them. Once Claude Code and I figured that out, final assembly dropped to 30 seconds.
Consider audio-only re-encoding
There’s one more gotcha worth knowing about. When you concatenate clips from different sources (the encoded card clips and the Screen Studio recordings have slightly different audio configurations), you get scratchy pops at every join point. The fix is a final audio-only re-encode pass that smooths the transitions without touching the video, and it’s fast enough that you barely notice it in the assembly time.
Cost: Free, open source.
Puppeteer
Puppeteer is headless Chrome automation. I used it to render HTML/CSS templates into pixel-perfect PNG images for the chapter divider cards, speaker name card, and cover image.
Why Puppeteer instead of FFmpeg for the visual design work? Because HTML/CSS gives you everything FFmpeg’s drawtext can’t do: rounded corners, gradients, Google Fonts with proper rendering, flexbox layout, and transparency for the speaker card overlay. Claude Code writes the HTML template, Puppeteer renders it to PNG, and FFmpeg composites it onto the video.
This is where the tool-empowered approach worked really well.
I’d say: “Make me a chapter divider card for the comparison video. Charcoal gradient, CarouselBot logo in the corner, chapter title ‘Generating your first document’ in Inter Bold.” Claude Code would write the HTML, render it with Puppeteer, and show me the result. I’d ask for a bigger title and get a new render in seconds and then change my mind entirely and say “actually, make it more like the Gamma card but with our brand colors.” All of that happened in a single conversation.
That last request is the kind of thing a CLI tool simply cannot handle. I generated consistent chapter cards for all the comparison videos this way, iterating in conversation until the design felt right.
Remember to convert images to bas364 data URIs
One tip if you go this route: Puppeteer’s setContent() blocks local file:// image loads, so if you’re embedding images in your HTML templates, you’ll need to convert them to base64 data URIs first. Otherwise you’ll end up with blank images and no obvious error message telling you why.
Cost: Free, open source.
Nano Banana 2
Nano Banana 2 is Google DeepMind’s image generation model (API model ID: gemini-3.1-flash-image-preview), accessed through Google AI Studio. I used it to generate images of my avatar that I could incorporate into the chapter divider cards and cover image.
I also set up Recraft’s background removal API so Claude Code could strip the backgrounds from the generated avatar images. Recraft is an AI image generation and editing platform that offers a background removal endpoint through its API, which made it easy to turn Nano Banana’s generated avatars into transparent PNGs that could be composited onto the card designs in Puppeteer.
My newsletter readers are used to seeing my avatar in different settings (thanks to Nano Banana), so I wanted the video cards to have the same feel. I had Claude Code call the API directly, review results with me, and iterate. “She needs to be facing the camera.” “Can she point upwards?” And so on. The conversational approach worked well here, allowing me to make small changes. Once I was happy with an avatar image, Claude Code would run it through Recraft to remove the background and drop the transparent PNG straight into the card template.
Consider pairing Nano Banana with text overlay via Puppeteer
Text rendering in Nano Banana 2 is better than any other image gen model I’ve tried, but it’s still not perfect, and since I was overlaying text with Puppeteer anyway, I didn’t want Nano Banana adding its own.
The hybrid approach that worked best: Nano Banana 2 for the avatar artwork, Recraft for background removal, then Puppeteer for compositing everything together with chapter titles, logos, and any other text. Claude Code orchestrated all three tools seamlessly. I didn’t have to think about the handoffs between them.
Cost: Nano Banana 2 starts at $0.045/image at 1K resolution, up to ~$0.15/image at 4K. Free tier available through Google AI Studio. Recraft offers a free tier for background removal.
Why the tool-empowered approach worked better
I’ve been thinking about why the conversational approach worked so much better than the CLI, and I don’t think it’s just that the CLI was poorly scoped (though it was). There are a few things about video post-production specifically that make it a better fit for direct agent interaction.
Claude Code is good at combining tools.
The final pipeline chains three tools: Puppeteer renders cards, FFmpeg encodes and assembles, and Nano Banana 2 generates thumbnails. Getting those tools to talk to each other was the hard part, and Claude Code handled the glue code, temp file management, and format conversions without me having to think about any of it.
The optimizations were collaborative.
I didn’t know about transport stream concatenation or the audio smoothing trick before this project. Claude Code suggested both in response to problems we hit together, and that kind of problem-solving only happens in conversation, not inside a pre-built tool.
You have to explore before you can formalize.
This is the point I keep coming back to. The CLI wasn’t a bad idea, it was a premature idea. I was trying to build a repeatable pipeline before I understood which parts of the process are actually repeatable. The micro-adjustments that derailed the CLI weren’t a bug in my workflow. They’re just what video post-production looks like.
What I tried that didn’t work
Not everything was a win.
Complex filter_complex concatenation
Audio sync issues everywhere. The Screen Studio recordings and the encoded card clips had different audio configurations, and filter_complex could not work through the mismatch. Transport stream concat was bulletproof.
Re-encoding every clip for “consistency”
This is what gave me 55-minute assembly times. Once I switched to encoding only the new card clips and stream-copying the original recordings, it dropped to 30 seconds.
AI chapter detection from transcripts
I tried having Claude figure out where the chapter breaks should go based on what I was saying. It always guessed just a little bit wrong. Splitting the screen recordings into separate files per chapter and naming them in order (01-intro.mov, 02-gamma-setup.mov, 03-carouselbot-setup.mov) was simpler and perfectly accurate. Sometimes the low-tech approach is the right one.
Tools I looked at but didn’t use (yet)
Remotion is a React framework for creating videos programmatically. Every frame is a React component rendered at a specific timestamp, which means anything you can build in React becomes a video element. You could create kinetic typography where words animate onto screen, data visualizations that build themselves over time, logo reveals with spring easing, lower thirds that slide in instead of just appearing, or animated transitions between chapters instead of a static fade-to-card.
The piece that’s most relevant to my use case is that Remotion compositions are parameterized. You build a chapter card template once, then feed in different titles, colors, and durations for each chapter, and the animation stays consistent while only the content changes. For a comparison video series where every chapter card should look and move the same way, that’s powerful.
I started setting it up but pivoted. For where I am right now, the static Puppeteer cards are working fine and I’m still iterating on the design. Remotion is where I’d go once I’ve locked in a card template and want animated transitions across the whole series. It’s on the roadmap.
Licensing note: Remotion uses a custom source-available license. Free for individuals and companies up to three people. Larger companies need a paid license.
Motion Canvas is similar to Remotion but uses TypeScript and a canvas-based rendering approach. MIT licensed. Good for educational content and animated explainers.
Cloud video APIs like Shotstack and Creatomate let you define a video as a JSON timeline and submit it for cloud rendering. These might be the most agent-friendly video tools that exist. Claude Code writes a JSON spec, submits it via REST API, polls for completion, downloads the result. No local FFmpeg wrestling. The tradeoff is speed: you give up 30-second local assembly for cloud rendering queues. Both start around $49/month.
AI video generation (Veo 3/3.1, Runway Gen-4.5, Pika, etc.) is impressive but not practical for a production pipeline yet. Generation takes 30-120 seconds per clip, quality varies wildly, and you can’t reliably predict what you’ll get. For something like an animated intro generated from your thumbnail, maybe. For reliable automated assembly, not yet.
MCP vs local install
This came up a lot during the build, so here’s the framework I landed on.
Use local install when the tool is a CLI that Claude Code can run directly. FFmpeg and Puppeteer both fall here because they need fast synchronous execution and direct file system access to large video files.
Use an MCP server when the tool is an API that benefits from session management, structured schemas, or sharing across multiple agents. Nano Banana 2 could go either way, but would benefit from an MCP wrapper for prompt templates and reference image management. Cloud video APIs, AI video generators, and ElevenLabs (voice generation, from $5/month) are all natural MCP candidates. YouTube upload is a good fit too, since it needs OAuth token management.
Key takeaways
Empower the agent, don’t constrain it. Give Claude Code access to good tools and let it figure out the orchestration. You’ll get to a working result faster than if you try to pre-build the pipeline.
Smart rendering is non-negotiable. Never re-encode source clips. Encode only what you create. Use transport stream concatenation for everything else.
Scope the CLI after you’ve done it by hand. The conversational approach teaches you which decisions are repeatable and which ones need to stay flexible. That’s the knowledge you need before building a tool.
Hardware acceleration matters. VideoToolbox on macOS Apple Silicon made the difference between 3-minute and 30-minute encodes. Always check for h264_videotoolbox.
Audio is the silent killer. Every concat method introduces potential audio artifacts. Always do a final audio-smoothing pass.
AI image generation is ready for thumbnails. AI video generation is not ready for production pipelines. Nano Banana 2 can generate useful thumbnails with the right prompts and references. Veo and Runway generate impressive clips but lack the precision needed for automated assembly.
What’s next
Now that I’ve done one video the conversational way, I have a much better sense of which parts of the process are actually repeatable. The assembly structure (cover, chapters interleaved with divider cards, speaker overlay, back cover, audio pass) should be basically the same every time. The card design is locked in. The fade durations are settled.
That’s exactly the knowledge I was missing when I tried to build the CLI the first time around. I think there’s a version of that tool worth revisiting, one that handles the predictable assembly steps automatically but still lets me drop into conversation with Claude for the one-off adjustments that come up with every video. A hybrid approach where the boring parts are scripted and the creative parts stay flexible.
I’m also keeping an eye on Remotion for the next iteration of the chapter cards. Static fades are fine, but animated transitions between chapters would make the series feel more polished, and Remotion’s parameterized templates are a natural fit for a series where the structure repeats but the content changes.
If you’re thinking about building something similar, my advice is to start with the tools and the conversation. The automation can come later, once you actually know what you’re automating.
Just here to support KSpin, former daily poet, and former director. Who knew?
I really enjoyed the contrast between trying to force structure with a CLI and then moving to a more conversational workflow. I keep bumping into the same wall, and creative work doesn’t fit neatly into rigid systems. Thanks for sharing the fails too, it makes you even more of the Wonder Woman of AI in my eyes. 🩷🦩