We build LaunchReel, a tool that makes short vertical video ads. The editor exports the final MP4 in the browser with ffmpeg.wasm: trim each clip, concatenate, then burn captions on top. Two small flag choices cost us a lot of debugging. Both are easy to repeat, so here they are.
1. Pin every video input to one frame rate
Our segments come from different sources: AI-generated clips, user uploads from phones, still images turned into short clips. Their native frame rates differ (24, 25, 30, 29.97, variable).
If you trim each one with its own rate and then concat, you get frozen or duplicated frames at the segment boundaries, and anything timed against the output (like a caption highlighting the current word) can briefly show the previous state at fast cuts.
The fix is boring: choose one export rate and force it on every input and output that touches video.
# video segment
ffmpeg -ss 2.0 -t 3.5 -i clip.mp4 -r 30 -c:v libx264 -pix_fmt yuv420p seg1.mp4
# still image held as a segment
ffmpeg -loop 1 -framerate 30 -t 2.0 -i photo.png -r 30 -c:v libx264 -pix_fmt yuv420p seg2.mp4
We keep a test that asserts -r 30 is on every trim command. If it fails, we fix the pipeline, not the assertion.
2. Don't loop a full-frame overlay image with an input frame rate
Captions are rendered as transparent PNGs the size of the video (1080×1920) and composited with overlay, about 30 per filtergraph, each enabled only during its time window.
This version looks harmless:
-loop 1 -framerate 30 -i ovl0.png # repeated for each caption
...
[0:v][1:v]overlay=0:0:enable='between(t,1.2,1.8)'[v1]; ...
-loop 1 with an explicit input rate turns each PNG into a 30 fps stream for the whole video length. ffmpeg then decodes and scales a full ~8 MB RGBA frame 30 times a second per caption input. With 30 inputs chained, that's hundreds of full-frame rescales per output frame. On the single-threaded wasm build, a 90-second export went from about 8 minutes to about an hour, with batches running at ~0.05x.
You won't see it in a small test with one tiny PNG. It needs all four together: input rate, full-frame image, loop, deep chain.
What works: feed each PNG as one still frame and let overlay hold it.
-framerate 30 -i ovl0.png # no -loop, no -t
...
[0:v][1:v]overlay=0:0:enable='gte(t,1.2)*lt(t,1.8)'[v1]; ...
overlay keeps the last frame of a finished input by default (eof_action=repeat), so the single frame stays available for the whole timeline and enable decides when it's drawn. Two things to avoid:
-
shortest=1ends the output when the one-frame input ends. -
eof_action=passstops drawing the caption after its first frame, so it never shows.
Bounding the loop with -t or -itsoffset instead also looked tempting. In our case it deadlocked ffmpeg's frame sync whenever the first caption in a batch started well after t=0.
Takeaways
- One output frame rate, set explicitly everywhere, beats trusting each source.
- A large image input should be one held frame plus
enable, not a looped stream. - Write tests that assert the flags. These bugs return quietly when someone "cleans up" a command.
If you're exporting for TikTok, Reels or Shorts, the target is 1080×1920 (9:16), H.264 MP4, with captions burned in because feeds autoplay muted. We keep a free short-form video ad specs lookup with lengths and caption guidance per platform.
Disclosure: I'm the founder of LaunchReel.
Top comments (2)
The strongest part is tying the flags to user-visible symptoms instead of treating codec settings as folklore. I’d keep a tiny fixture set—short motion, long still frame, and audio transition—and run it in CI when the export pipeline changes. That catches both performance regressions and timestamp mistakes before a browser-specific report does.
The overlay one bites a lot of people. Two things that cut the cost further in ffmpeg.wasm: first, you don't need -loop at all for a static caption. Feed the PNG as a single-frame input and overlay keeps repeating its last frame by default (repeatlast=1), so enable='between(t,a,b)' still works and nothing gets decoded 30 times a second. Second, crop each caption PNG to its text bounding box and overlay it at x:y instead of compositing a full 1080x1920 frame. Most of the per-frame work is blending transparent pixels, so a 1080x200 strip is far cheaper in wasm. On the frame-rate side, if phone clips are VFR, I'd also pin the timescale on each segment (-video_track_timescale 15360 or similar) so the concat demuxer isn't stitching segments with different timebases, which is another source of the boundary stutter.