Turn a raw screen recording into a small, fast-loading web demo. Wraps the proven
ffmpeg -c:v libx264 -crf 28 -preset slow -movflags +faststart -an recipe with
sensible flags, plus optional poster frame and GIF.
Requirements
ffmpeg must be installed (no pure-Python fallback exists for video encoding):
- macOS:
brew install ffmpeg - Debian/Ubuntu:
sudo apt-get install ffmpeg
The script checks for ffmpeg and prints the install hint if it's missing.
Running it
scripts/optimize_video.sh <input> [--crf N] [-o out.mp4] [--keep-audio] [--poster] [--gif] [--max-width N]
- Output defaults to
<input>-opt.mp4: H.264,+faststart(streams instantly),yuv420p(plays everywhere), audio removed. --crfquality, lower = better/larger (default 28; try 24–26 for crisper UI text).--max-width Nscales down (keeps aspect, enforces even dimensions for H.264).--posterwrites<input>-poster.jpg(first frame) — use as the<video poster>.--gifwrites<input>.gif(12fps, 720px wide, palette-optimized) for places that can't embed video.--keep-audiokeeps the audio track (off by default — demos rarely need it).
Examples:
optimize_video.sh demo.mov
optimize_video.sh demo.mp4 --crf 26 --poster --gif
optimize_video.sh demo.webm -o public/demo.mp4 --max-width 1280
Workflow guidance (for the agent)
- Always produce the optimized
.mp4first; add--posterwhen the page uses a<video>element (setposter="<input>-poster.jpg"). - Only add
--gifwhen asked or when the target can't embed video — GIFs are far larger than the mp4 for the same content. - Prefer
--max-width 1280(or 1280→1920) for full-screen captures; UI demos read fine at 1280 and stay small. - Report each output's path and size; suggest the
<video>snippet:<video src="demo-opt.mp4" poster="demo-poster.jpg" autoplay muted loop playsinline></video>.
Notes
+faststartmoves the moov atom to the front so the video starts before it's fully downloaded — important for web.- Audio is stripped by default to shave bytes; pass
--keep-audioto keep it. - Tested by
tests/test_web_video.sh(H.264 codec, even/capped width, moov-before-mdat faststart, audio stripped, poster + gif produced).