Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

docs: before/after demo gallery (23 demos, demos/build.py, docs/demos.md) (#222)

claude[bot]b91b45fc933b
diff --git a/.gitignore b/.gitignore
index 677dab7..3a4634b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
# demo / test output
examples/out/
+demos/out/
tests/out/
*.log
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c5b332d..3d36124 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -72,6 +72,11 @@ would have caught the original bug isn't done yet.
table, the contract table, gotchas), `SKILL.md`, `references/scripts.md`,
`docs/contract.md` and `CHANGELOG.md`. The README is read by people who never
open SKILL.md, so a feature that only SKILL.md knows about is half shipped.
+- A `feat` PR adds at least one before/after demo to `demos/build.py` and
+ `docs/demos.md` (the page is generated: add the demo to the table in
+ `demos/build.py`, then run `python3 demos/build.py --docs`). A feature nobody
+ can see working is hard to review and harder to trust; the demo also runs the
+ new tool end to end, so a broken flag fails the build instead of the reader.
## Reporting issues
diff --git a/README.md b/README.md
index 4d9ee5e..df1baf9 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,18 @@
npx ffmpeg-skill
```
-![before / after demo](assets/demo.gif)
+<table>
+ <tr>
+ <td width="50%"><img src="docs/demos/captions_pop_karaoke.gif" alt="animated captions with a karaoke highlight"><br><sub><code>caption.py --animate pop --karaoke</code></sub></td>
+ <td width="50%"><img src="docs/demos/reframe_crop.gif" alt="16:9 reframed to 9:16"><br><sub><code>fit.py --aspect 9:16 --fit crop</code></sub></td>
+ </tr>
+ <tr>
+ <td width="50%"><img src="docs/demos/silence_removal.gif" alt="silence removed, timeline shorter"><br><sub><code>silence.py --threshold -35</code></sub></td>
+ <td width="50%"><img src="docs/demos/loudness.gif" alt="waveform before and after loudness normalisation"><br><sub><code>loudness.py -I -14 --tp -1</code></sub></td>
+ </tr>
+</table>
+
+Left half is the input, right half is what the command produced. **[All 23 before/after demos, with the exact command under each one →](docs/demos.md)** — all of it generated from synthetic footage by `python3 demos/build.py`, so you can rebuild every frame of it yourself.
`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **42 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.
@@ -107,7 +118,7 @@ python3 $S/export.py input.mp4 --preset reels --json # structure
On Windows in Git Bash, `python3` is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes `python` (or the `py` launcher) instead — replace `python3` with `python` above if you see a "command not found". `bin/install.js` and `doctor`/`contract` already handle this for you; only the raw script examples above need it spelled out manually.
-More requests and the commands behind them: [examples/README.md](examples/README.md). To see everything run end-to-end on generated footage: `npm run demo`.
+More requests and the commands behind them: [examples/README.md](examples/README.md). To see everything run end-to-end on generated footage: `npm run demo` (the gallery in [docs/demos.md](docs/demos.md)).
## How it works
@@ -437,7 +448,8 @@ FFmpeg itself:
```bash
npm test # tests/test_all.py (end-to-end incl. VFR, rotated, 5.1, HDR10, drifting sources) + tests/test_contract.py
npm run release-check # pack, install, contract from the installed copy, MCP == contract, doctor, tests, contract evals
-npm run demo # generate footage, run every tool, rebuild assets/demo.gif
+npm run demo # python3 demos/build.py: synthetic footage -> every before/after demo + docs/demos/*.gif
+npm run demo:pipeline # examples/make_demo.sh: the older single end-to-end run of every script
python3 evals/run.py --list # agent eval prompts (see evals/)
node bin/install.js --dir /tmp/skills # try the installer without touching ~/.claude
```
diff --git a/demos/CI.md b/demos/CI.md
new file mode 100644
index 0000000..be2a054
--- /dev/null
+++ b/demos/CI.md
@@ -0,0 +1,123 @@
+# CI for the demo gallery — the YAML to add
+
+The changes described here are **not applied**: they touch `.github/workflows/`, which the
+App token used for these PRs is not allowed to merge. A maintainer copies the two blocks
+below into the named files; nothing else in this PR depends on them.
+
+Both are cheap: `ubuntu-latest` bills at 1x, and the whole gallery renders in about two and a
+half minutes on a runner of that size.
+
+---
+
+## 1. `.github/workflows/ci.yml` — a `demos` job
+
+Add this as a sibling of `test` / `test-ffmpeg-5` (same indentation, under `jobs:`). It
+installs ffmpeg and fonts exactly the way the existing Linux matrix leg does — `fonts-dejavu-core`
+for the BEFORE/AFTER labels, plus the CJK and Arabic families the caption demos need, or those
+demos skip themselves and the job silently proves less than it looks like it does.
+
+```yaml
+ # Renders the whole before/after gallery from synthetic footage on every PR. This is a real
+ # end-to-end test of 23 tool invocations (caption, graphics, overlay, fit, join, silence,
+ # loudness, audio, color, export, check, render, look, reverse) and it is also the gate on
+ # what lands in docs/demos/: build.py fails when a committed preview goes over 500 KB, so a
+ # PR cannot quietly grow the repo's binaries. Linux only -- it bills at 1x and the demos are
+ # about the tools, not about per-OS ffmpeg differences, which the test matrix already covers.
+ demos:
+ name: demo gallery (ubuntu-latest)
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ with:
+ python-version: "3.9"
+ # Same apt line as the matrix job, plus the CJK/Arabic faces: without them the
+ # captions_ja / _zh / _ko / _ar demos skip, and a skipped demo proves nothing.
+ - name: Install ffmpeg and fonts
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y ffmpeg fonts-dejavu-core fonts-ipafont-gothic \
+ fonts-wqy-zenhei fonts-noto-core
+ - name: Build the demo gallery
+ run: python3 demos/build.py
+ # The previews are committed, so CI must fail when the working tree's versions differ
+ # from what a fresh render produces -- otherwise docs/demos.md shows a picture of an
+ # older build of the tool. Only the generated page is diffed, not the GIFs: GIF bytes
+ # vary with the ffmpeg build, the page text does not.
+ - name: docs/demos.md is up to date with demos/build.py
+ run: |
+ python3 demos/build.py --docs
+ git diff --exit-code -- docs/demos.md
+ - uses: actions/upload-artifact@v7
+ if: always()
+ with:
+ name: demo-gallery
+ path: |
+ demos/out/*.mp4
+ docs/demos/*
+ retention-days: 14
+```
+
+Add `demos` to the branch-protection ruleset's required status checks if the intent is that a
+red gallery blocks a merge (`main` currently requires 8 checks; this would make 9).
+
+### Why the previews are not regenerated by CI and committed back
+
+A bot commit pushing 4 MB of GIFs onto every PR would churn the repo's history for changes
+that are usually invisible (GIF bytes differ between ffmpeg builds even when the picture is
+identical). The author runs `python3 demos/build.py` and commits the result; CI only proves it
+still renders and that `docs/demos.md` matches the table in `demos/build.py`.
+
+---
+
+## 2. `.github/workflows/release.yml` — attach the full MP4s to the release
+
+The gallery in `docs/demos.md` shows 480 px GIFs because they have to live in git. The
+640 px side-by-side MP4s (and the full-resolution `_before` / `_after` pairs) are the better
+artefact, and a GitHub Release is the right place for them: it is versioned, it is not in the
+repo's history, and it costs nothing to drop.
+
+Two steps, inserted into the existing release job immediately **before** the
+`Create tag and GitHub Release` step (`softprops/action-gh-release@v3`, around line 242), and
+one addition to that step itself.
+
+```yaml
+ # Build the gallery at the exact commit being released and zip it, so the release
+ # carries watchable proof of what this version does. `|| true` is deliberate: a failed
+ # demo render must never block a release that npm and the tag are already committed to
+ # -- the missing asset is visible on the release page, a half-published version is not.
+ - name: Render the demo gallery for the release assets
+ if: steps.check.outputs.already_released == 'false'
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y ffmpeg fonts-dejavu-core fonts-ipafont-gothic \
+ fonts-wqy-zenhei fonts-noto-core
+ python3 demos/build.py || true
+ mkdir -p release_assets
+ # Side-by-side comparisons only: the _before/_after pairs are another ~60 MB and are
+ # reproducible from the same one command, which is named in the zip's README.
+ cp demos/out/*.mp4 release_assets/ 2>/dev/null || true
+ rm -f release_assets/*_before.mp4 release_assets/*_after.mp4
+ cp -r docs/demos release_assets/previews
+ printf 'Rebuild these with:\n\n python3 demos/build.py\n' > release_assets/README.txt
+ cd release_assets && zip -r ../demo-gallery-${{ steps.check.outputs.tag }}.zip .
+```
+
+and on the existing release step:
+
+```yaml
+ - name: Create tag and GitHub Release
+ if: steps.check.outputs.already_released == 'false'
+ uses: softprops/action-gh-release@v3
+ with:
+ tag_name: ${{ steps.check.outputs.tag }}
+ target_commitish: ${{ steps.check.outputs.sha }}
+ body_path: release_notes.md
+ generate_release_notes: true
+ files: demo-gallery-${{ steps.check.outputs.tag }}.zip # <- the one added line
+ fail_on_unmatched_files: false # <- and its guard
+```
+
+`fail_on_unmatched_files: false` pairs with the `|| true` above: if the render failed, the
+release still publishes without the asset. The release notes can then link the gallery with
+a line in the CHANGELOG template — `Demos: docs/demos.md (full MP4s attached below)`.
diff --git a/demos/build.py b/demos/build.py
new file mode 100644
index 0000000..39fc3b5
--- /dev/null
+++ b/demos/build.py
@@ -0,0 +1,768 @@
+#!/usr/bin/env python3
+"""Build the before/after demo gallery: synthetic footage in, previews out.
+
+Everything here is generated from nothing -- ffmpeg's own synthetic sources (testsrc2,
+mandelbrot, life, aevalsrc) make the footage, and every "after" file is produced by running
+this repo's own scripts, so a demo that renders is also a smoke test of the tool behind it.
+
+ python3 demos/build.py # build every demo
+ python3 demos/build.py --list # names + groups, render nothing
+ python3 demos/build.py --only captions_ja
+ python3 demos/build.py --docs # rewrite docs/demos.md from the table, render nothing
+
+Each demo writes demos/out/<name>_before.mp4, demos/out/<name>_after.mp4, a side-by-side
+demos/out/<name>.mp4 (640 px wide, <= 6 s) and a palette-optimised preview
+docs/demos/<name>.gif (<= 480 px, 10-12 fps). The preview is the only file committed, so the
+build FAILS if any of them is over 500 KB rather than letting a fat binary into git.
+
+demos/out/ is gitignored; --keep-fixtures (the default) reuses fixtures across runs, so a
+second run of --only is fast. Python 3.9 standard library only.
+"""
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPTS = ROOT / "scripts"
+OUT = Path(os.environ.get("DEMO_OUT", ROOT / "demos" / "out"))
+FIX = OUT / "fixtures"
+PREVIEWS = ROOT / "docs" / "demos"
+
+PREVIEW_MAX_BYTES = 500 * 1024 # hard limit: the build fails rather than commit a fatter file
+PREVIEW_TARGET_BYTES = 250 * 1024 # what the ladder aims for, so the cap is never a near miss
+CELL_W, CELL_H = 320, 180 # each half of the side-by-side; 640 px wide in total
+COMPARE_MAX_SECONDS = 6.0
+PY = sys.executable or "python3"
+
+sys.path.insert(0, str(SCRIPTS))
+from _common import font_for_script, script_font_status # noqa: E402
+
+# A speech-like bed: a two-formant "voice" gated by a slow square wave, so there are real
+# pauses for silence.py to find and real level changes for loudness.py to move.
+SPEECH = ("0.45*(sin(2*PI*180*t)+0.5*sin(2*PI*420*t)+0.25*sin(2*PI*900*t))"
+ "*gt(sin(2*PI*0.55*t)\\,0.15)*(0.6+0.4*sin(2*PI*5*t))")
+# A music-like tone bed: a held triad with a pulsing fifth, quiet enough to duck under speech.
+MUSIC = "0.30*sin(2*PI*110*t)+0.22*sin(2*PI*165*t)+0.18*sin(2*PI*220*t)*gt(sin(2*PI*2*t)\\,0)"
+
+
+# --------------------------------------------------------------------------- process helpers
+class BuildError(RuntimeError):
+ pass
+
+
+def run(cmd, capture=False):
+ proc = subprocess.run([str(c) for c in cmd], stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace")
+ if proc.returncode != 0:
+ raise BuildError("command failed: %s\n%s\n%s" % (" ".join(str(c) for c in cmd),
+ proc.stdout[-2000:], proc.stderr[-2000:]))
+ return proc.stdout if capture else None
+
+
+def ffmpeg(*args):
+ run(["ffmpeg", "-y", "-hide_banner", "-loglevel", "error"] + list(args))
+
+
+def duration(path) -> float:
+ out = run(["ffprobe", "-v", "error", "-show_entries", "format=duration",
+ "-of", "default=nw=1:nk=1", str(path)], capture=True)
+ try:
+ return float(out.strip())
+ except ValueError:
+ return 0.0
+
+
+def label_font() -> str:
+ """A concrete font file for the BEFORE/AFTER labels drawn on the comparison."""
+ for script in ("latin", "ja"):
+ path = font_for_script(script)
+ if path:
+ return path
+ for guess in ("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+ "/System/Library/Fonts/Supplemental/Arial.ttf",
+ "C:\\Windows\\Fonts\\arial.ttf"):
+ if Path(guess).exists():
+ return guess
+ raise BuildError("no usable font found for the BEFORE/AFTER labels")
+
+
+def esc(path: str) -> str:
+ """Escape a path for use inside an ffmpeg filter argument (fontfile=)."""
+ return str(path).replace("\\", "/").replace(":", "\\:").replace("'", "\\'")
+
+
+# --------------------------------------------------------------------------- context
+class Ctx:
+ """One demo's working area. Records every skill-script invocation it makes, so the gallery
+ page can print the exact command that produced the picture instead of a retyped one."""
+
+ def __init__(self, name, verbose=True):
+ self.name = name
+ self.verbose = verbose
+ self.commands = []
+ self.notes = []
+
+ def path(self, suffix):
+ return OUT / ("%s_%s" % (self.name, suffix))
+
+ def script(self, tool, *args, capture=False):
+ """Run scripts/<tool> and record it as a copyable one-liner."""
+ cmd = [PY, str(SCRIPTS / tool)] + [str(a) for a in args]
+ self.commands.append(" ".join(["python3", "scripts/" + tool] + [_short(a) for a in args]))
+ if self.verbose:
+ print(" $ " + self.commands[-1])
+ return run(cmd, capture=capture)
+
+ def note(self, text):
+ self.notes.append(text)
+
+
+def _short(arg) -> str:
+ """Render an argument for the docs: absolute paths under demos/out become relative."""
+ text = str(arg)
+ for base, prefix in ((OUT, "demos/out"), (ROOT, "")):
+ try:
+ rel = Path(text).resolve().relative_to(base)
+ except (ValueError, OSError):
+ continue
+ text = (prefix + "/" + str(rel).replace("\\", "/")).lstrip("/")
+ break
+ return "'%s'" % text if " " in text and not text.startswith("'") else text
+
+
+# --------------------------------------------------------------------------- fixtures
+def build_fixtures(force=False):
+ """Synthetic source material. Nothing here is downloaded and nothing is committed."""
+ FIX.mkdir(parents=True, exist_ok=True)
+ made = []
+
+ def need(name):
+ path = FIX / name
+ if force or not path.exists() or path.stat().st_size == 0:
+ made.append(name)
+ return path
+ return None
+
+ # 1. The main clip: a moving test pattern with speech-like audio (pauses included).
+ path = need("motion.mp4")
+ if path:
+ ffmpeg("-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30",
+ "-f", "lavfi", "-i", "aevalsrc='%s':s=48000" % SPEECH,
+ "-t", "8", "-c:v", "libx264", "-preset", "veryfast", "-crf", "22",
+ "-pix_fmt", "yuv420p", "-c:a", "aac", "-b:a", "128k", str(path))
+
+ # 2. A fractal zoom: real, non-repeating motion, so a transition or a speed change is
+ # actually visible frame to frame (a static pattern hides both).
+ path = need("mandel.mp4")
+ if path:
+ ffmpeg("-f", "lavfi", "-i", "mandelbrot=size=1280x720:rate=30:maxiter=200",
+ "-f", "lavfi", "-i", "aevalsrc='%s':s=48000" % MUSIC,
+ "-t", "6", "-c:v", "libx264", "-preset", "veryfast", "-crf", "22",
+ "-pix_fmt", "yuv420p", "-c:a", "aac", "-b:a", "128k", str(path))
+
+ # 3. Conway's life: coarse cells at 12 fps -- real motion that a GIF palette can still
+ # carry (a fine-grained life pattern changes every pixel every frame and blows the budget).
+ path = need("life.mp4")
+ if path:
+ ffmpeg("-f", "lavfi", "-i",
+ "life=size=80x45:rate=12:mold=32:ratio=0.1:death_color=#101030:life_color=#39ff88",
+ "-f", "lavfi", "-i", "aevalsrc='%s':s=48000" % MUSIC,
+ "-t", "6", "-vf", "scale=1280:720:flags=neighbor,fps=30", "-c:v", "libx264",
+ "-preset", "veryfast", "-crf", "22", "-pix_fmt", "yuv420p",
+ "-c:a", "aac", "-b:a", "128k", str(path))
+
+ # 4. A music bed on its own, for the ducking demo.
+ path = need("music.m4a")
+ if path:
+ ffmpeg("-f", "lavfi", "-i", "aevalsrc='%s':s=48000" % MUSIC,
+ "-t", "8", "-c:a", "aac", "-b:a", "128k", str(path))
+
+ # 5. A 5.1 clip: six distinct tones, one per channel, so a downmix is audible and provable.
+ path = need("surround.mp4")
+ if path:
+ tones = ["0.5*sin(2*PI*%d*t)" % f for f in (220, 330, 440, 60, 550, 660)]
+ ffmpeg("-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30",
+ "-f", "lavfi", "-i", "aevalsrc='%s':s=48000:c=5.1" % "|".join(tones),
+ "-t", "6", "-c:v", "libx264", "-preset", "veryfast", "-crf", "23",
+ "-pix_fmt", "yuv420p", "-c:a", "aac", "-ac", "6", str(path))
+
+ # 6. An HDR10 clip: 10-bit HEVC tagged PQ / BT.2020, like tests/ builds.
+ path = need("hdr10.mp4")
+ if path:
+ ffmpeg("-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30",
+ "-f", "lavfi", "-i", "aevalsrc='%s':s=48000" % MUSIC, "-t", "5",
+ "-vf", "format=yuv420p10le", "-c:v", "libx265", "-preset", "ultrafast",
+ "-x265-params", "colorprim=bt2020:transfer=smpte2084:colormatrix=bt2020nc:log-level=error",
+ "-tag:v", "hvc1", "-c:a", "aac", str(path))
+
+ # 7. A semi-transparent logo for the overlay demo.
+ path = need("logo.png")
+ if path:
+ ffmpeg("-f", "lavfi", "-i", "[email protected]:s=240x90,format=rgba",
+ "-frames:v", "1", str(path))
+
+ # 8. Caption cues, one file per script, in caption.py's plain-text cue format.
+ cues = {
+ "cues_en.txt": ["0:00-0:02 Shot on nothing but FFmpeg",
+ "0:02-0:04 Captions burned in with libass",
+ "0:04-0:06 No cloud. No API keys.",
+ "0:06-0:08 Just python3 and ffmpeg."],
+ "cues_ja.txt": ["0:00-0:02 FFmpeg だけで作った映像です",
+ "0:02-0:04 字幕は libass で焼き込み",
+ "0:04-0:06 クラウドも API キーも不要",
+ "0:06-0:08 python3 と ffmpeg だけ"],
+ "cues_zh.txt": ["0:00-0:02 完全由 FFmpeg 生成的画面",
+ "0:02-0:04 字幕用 libass 烧录",
+ "0:04-0:06 不需要云端,也不需要密钥",
+ "0:06-0:08 只要 python3 和 ffmpeg"],
+ "cues_ko.txt": ["0:00-0:02 FFmpeg 만으로 만든 영상입니다",
+ "0:02-0:04 자막은 libass 로 굽습니다",
+ "0:04-0:06 클라우드도 API 키도 필요 없습니다",
+ "0:06-0:08 python3 과 ffmpeg 만 있으면 됩니다"],
+ "cues_ar.txt": ["0:00-0:02 فيديو من صنع FFmpeg وحده",
+ "0:02-0:04 الترجمة محروقة عبر libass",
+ "0:04-0:06 بلا سحابة وبلا مفاتيح",
+ "0:06-0:08 يكفي python3 و ffmpeg"],
+ "cues_pop.txt": ["0:00-0:02 word by word",
+ "0:02-0:04 the karaoke highlight tracks the beat",
+ "0:04-0:06 pop scales each cue in",
+ "0:06-0:08 all of it is plain ASS"],
+ }
+ for name, lines in cues.items():
+ path = need(name)
+ if path:
+ path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+ # 9. A render.py project that stitches several of the above into one edit.
+ path = need("project.json")
+ if path:
+ project = {
+ "output": str(OUT / "render_project_after.mp4"),
+ "frame": {"aspect": "16:9", "width": 960, "fps": 30},
+ "clips": [{"src": str(FIX / "motion.mp4"), "in": 0, "out": 3},
+ {"src": str(FIX / "mandel.mp4"), "in": 0, "out": 3}],
+ "transition": {"type": "fade", "duration": 0.5},
+ "captions": {"text": str(FIX / "cues_en.txt"), "animate": "pop", "size": 26,
+ "position": "bottom"},
+ "graphics": [{"template": "title", "title": "ffmpeg-skill",
+ "subtitle": "one project file, one render", "start": 0, "end": 2.5}],
+ "export": {"preset": "youtube"},
+ }
+ path.write_text(json.dumps(project, indent=2, ensure_ascii=False), encoding="utf-8")
+
+ return made
+
+
+# --------------------------------------------------------------------------- comparison + preview
+def _side(idx, label, font, seconds):
+ """One half of the side-by-side: letterboxed into a fixed cell so a 9:16 'after' and a
+ 16:9 'before' still stack cleanly, held on its last frame if it is the shorter of the two."""
+ return ("[%d:v]scale=%d:%d:force_original_aspect_ratio=decrease,"
+ "pad=%d:%d:(ow-iw)/2:(oh-ih)/2:color=0x101014,setsar=1,fps=25,"
+ "tpad=stop_mode=clone:stop_duration=%.2f,"
+ "drawtext=fontfile='%s':text='%s':fontsize=18:fontcolor=white:borderw=2:"
+ "[email protected]:x=(w-text_w)/2:y=6[v%d]"
+ % (idx, CELL_W, CELL_H, CELL_W, CELL_H, seconds, esc(font), label, idx))
+
+
+def make_compare(before, after, dest, font):
+ """640x180 side-by-side, <= 6 s. Both sides are held on their last frame to the same
+ length, so silence removal (a genuinely shorter 'after') reads as the timeline shrinking
+ rather than as one side simply vanishing."""
+ seconds = min(COMPARE_MAX_SECONDS, max(duration(before), duration(after)) or COMPARE_MAX_SECONDS)
+ chain = "%s;%s;[v0][v1]hstack=inputs=2[out]" % (_side(0, "BEFORE", font, COMPARE_MAX_SECONDS),
+ _side(1, "AFTER", font, COMPARE_MAX_SECONDS))
+ ffmpeg("-i", str(before), "-i", str(after), "-filter_complex", chain,
+ "-map", "[out]", "-t", "%.2f" % seconds, "-an", "-c:v", "libx264",
+ "-preset", "veryfast", "-crf", "24", "-pix_fmt", "yuv420p", str(dest))
+ return dest
+
+
+def make_wave_compare(before, after, dest, font, labels=("BEFORE", "AFTER")):
+ """For audio-only work there is nothing to see in the video, so the comparison is the two
+ waveforms (showwavespic) side by side, held for 3 s."""
+ pics = []
+ for idx, src in enumerate((before, after)):
+ pic = OUT / ("%s_wave%d.png" % (dest.stem, idx))
+ ffmpeg("-i", str(src), "-filter_complex",
+ "[0:a]aformat=channel_layouts=stereo,showwavespic=s=%dx%d:colors=0x39ff88|0x33aaff"
+ % (CELL_W, CELL_H), "-frames:v", "1", str(pic))
+ pics.append(pic)
+ chain = ";".join([
+ "[0:v]pad=%d:%d:0:0:color=0x101014,drawtext=fontfile='%s':text='%s':fontsize=18:"
+ "fontcolor=white:borderw=2:[email protected]:x=(w-text_w)/2:y=6[v0]"
+ % (CELL_W, CELL_H, esc(font), labels[0]),
+ "[1:v]pad=%d:%d:0:0:color=0x101014,drawtext=fontfile='%s':text='%s':fontsize=18:"
+ "fontcolor=white:borderw=2:[email protected]:x=(w-text_w)/2:y=6[v1]"
+ % (CELL_W, CELL_H, esc(font), labels[1]),
+ "[v0][v1]hstack=inputs=2,format=yuv420p[out]"])
+ ffmpeg("-loop", "1", "-t", "3", "-i", str(pics[0]), "-loop", "1", "-t", "3", "-i", str(pics[1]),
+ "-filter_complex", chain, "-map", "[out]", "-r", "10", "-c:v", "libx264",
+ "-preset", "veryfast", "-crf", "24", str(dest))
+ return dest
+
+
+def make_preview(compare_mp4, dest):
+ """Palette-optimised GIF, aiming at 250 KB and hard-capped at 500 KB.
+
+ The ladder steps quality down only as far as it has to: a still waveform comparison lands
+ at a few KB on the first rung, a noisy fractal walks several rungs down. Aiming below the
+ cap rather than at it matters because GIF size varies with the ffmpeg build -- a preview
+ that squeaks in at 499 KB here would fail the same check on a different runner.
+ """
+ # fps, width, palette colours, seconds: the preview is a taster, not the deliverable, so
+ # it is allowed to be shorter than the 6 s side-by-side it is cut from.
+ ladder = [(12, 480, 96, 4.0), (10, 480, 64, 4.0), (10, 480, 48, 3.5), (10, 420, 48, 3.5),
+ (10, 380, 32, 3.5), (10, 320, 24, 3.0)]
+ last = None
+ for fps, width, colors, seconds in ladder:
+ chain = ("fps=%d,scale=%d:-2:flags=lanczos,split[s0][s1];"
+ "[s0]palettegen=max_colors=%d:stats_mode=diff[p];"
+ "[s1][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle"
+ % (fps, width, colors))
+ ffmpeg("-i", str(compare_mp4), "-t", "%.2f" % seconds, "-filter_complex", chain,
+ "-loop", "0", str(dest))
+ last = (dest.stat().st_size, fps, width, colors)
+ if last[0] <= PREVIEW_TARGET_BYTES:
+ return last
+ if last[0] <= PREVIEW_MAX_BYTES: # under the cap, just not under the target
+ return last
+ raise BuildError("preview %s is %d bytes, over the %d byte budget even at the smallest "
+ "setting -- shorten the demo or drop its frame rate"
+ % (dest.name, last[0], PREVIEW_MAX_BYTES))
+
+
+# --------------------------------------------------------------------------- demos
+def _caption_demo(ctx, cues, extra=()):
+ before = FIX / "motion.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("caption.py", before, "--text", FIX / cues, "--size", "30", "--bold",
+ "--position", "bottom", "--margin", "40", *extra, "-o", after)
+ return before, after
+
+
+def demo_captions_en(ctx):
+ return _caption_demo(ctx, "cues_en.txt")
+
+
+def demo_captions_ja(ctx):
+ return _caption_demo(ctx, "cues_ja.txt")
+
+
+def demo_captions_zh(ctx):
+ return _caption_demo(ctx, "cues_zh.txt")
+
+
+def demo_captions_ko(ctx):
+ return _caption_demo(ctx, "cues_ko.txt")
+
+
+def demo_captions_ar(ctx):
+ return _caption_demo(ctx, "cues_ar.txt")
+
+
+def demo_captions_pop_karaoke(ctx):
+ return _caption_demo(ctx, "cues_pop.txt", ("--animate", "pop", "--karaoke",
+ "--highlight-color", "#39ff88"))
+
+
+def demo_lower_third(ctx):
+ before = FIX / "motion.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("graphics.py", before, "--template", "lower-third", "--name", "Ada Lovelace",
+ "--title", "Analytical Engine", "--start", "0.5", "--end", "5", "-o", after)
+ return before, after
+
+
+def demo_title_card(ctx):
+ before = FIX / "mandel.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("graphics.py", before, "--template", "title", "--title", "Episode 12",
+ "--subtitle", "The math of video", "--start", "0", "--end", "4", "-o", after)
+ return before, after
+
+
+def demo_logo_overlay(ctx):
+ before = FIX / "motion.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("overlay.py", before, "--image", FIX / "logo.png", "--position", "top-right",
+ "--scale", "200", "--opacity", "0.9", "--start", "0.5", "--end", "7.5",
+ "--fade", "0.6", "-o", after)
+ return before, after
+
+
+def demo_hdr_tonemap(ctx):
+ before = FIX / "hdr10.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("color.py", before, "--to-sdr", "--tonemap", "hable", "--preset", "veryfast",
+ "-o", after)
+ return before, after
+
+
+def demo_reframe_crop(ctx):
+ before = FIX / "mandel.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("fit.py", before, "--aspect", "9:16", "--fit", "crop", "--width", "540",
+ "--preset", "veryfast", "-o", after)
+ return before, after
+
+
+def demo_reframe_pad(ctx):
+ before = FIX / "mandel.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("fit.py", before, "--aspect", "9:16", "--fit", "pad", "--pad-fill", "blur",
+ "--width", "540", "--preset", "veryfast", "-o", after)
+ return before, after
+
+
+def demo_speed_up(ctx):
+ before = FIX / "motion.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("fit.py", before, "--duration", "4", "--method", "speed", "--preset", "veryfast",
+ "-o", after)
+ return before, after
+
+
+def demo_reverse(ctx):
+ before = FIX / "life.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("reverse.py", before, "--preset", "veryfast", "-o", after)
+ return before, after
+
+
+def demo_join_fade(ctx):
+ before = FIX / "motion.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("join.py", FIX / "motion.mp4", FIX / "mandel.mp4", "--transition", "fade",
+ "--duration", "0.8", "--width", "960", "--preset", "veryfast", "-o", after)
+ return before, after
+
+
+def demo_join_fadeblack(ctx):
+ before = FIX / "motion.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("join.py", FIX / "motion.mp4", FIX / "mandel.mp4", "--transition", "fadeblack",
+ "--duration", "0.8", "--width", "960", "--preset", "veryfast", "-o", after)
+ return before, after
+
+
+def demo_silence_removal(ctx):
+ before = FIX / "motion.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("silence.py", before, "--threshold", "-35", "--min-silence", "0.4",
+ "--margin", "0.1", "--preset", "veryfast", "-o", after)
+ ctx.note("%.2f s in, %.2f s out" % (duration(before), duration(after)))
+ return before, after
+
+
+def demo_loudness(ctx):
+ """The input is deliberately quiet, so the two waveforms differ by more than rounding."""
+ before = ctx.path("before.mp4")
+ ffmpeg("-i", str(FIX / "motion.mp4"), "-af", "volume=-14dB", "-c:v", "copy", "-c:a", "aac",
+ str(before))
+ after = ctx.path("after.mp4")
+ ctx.script("loudness.py", before, "-I", "-14", "--tp", "-1", "-o", after)
+ return before, after
+
+
+def demo_downmix_51(ctx):
+ before = FIX / "surround.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("audio.py", before, "--downmix", "-o", after)
+ return before, after
+
+
+def demo_bgm_ducking(ctx):
+ before = FIX / "motion.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("audio.py", before, "--music", FIX / "music.m4a", "--duck", "--duck-amount", "12",
+ "--music-volume", "0.6", "--fade-out", "1.5", "-o", after)
+ return before, after
+
+
+def demo_export_reels(ctx):
+ before = FIX / "motion.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("export.py", before, "--preset", "reels", "--fit", "crop", "-o", after)
+ report = ctx.script("check.py", after, "--platform", "reels", "--json", capture=True)
+ if report:
+ (OUT / ("%s_check.json" % ctx.name)).write_text(report, encoding="utf-8")
+ ctx.note("check.py --platform reels: %s" % json.loads(report).get("status", "?"))
+ return before, after
+
+
+def demo_render_project(ctx):
+ before = FIX / "motion.mp4"
+ after = ctx.path("after.mp4")
+ ctx.script("render.py", FIX / "project.json", "--fast")
+ if not after.exists():
+ raise BuildError("render.py did not write %s" % after)
+ return before, after
+
+
+def demo_contact_sheet(ctx):
+ """look.py answers 'did that actually work?' with a picture; the 'after' side of the
+ comparison is that contact sheet, held as video so the gallery can show it inline."""
+ before = FIX / "mandel.mp4"
+ sheet = ctx.path("sheet.png")
+ ctx.script("look.py", before, "--tiles", "4x3", "--width", "960", "-o", sheet)
+ after = ctx.path("after.mp4")
+ ffmpeg("-loop", "1", "-t", "3", "-i", str(sheet), "-vf",
+ "scale=960:-2,format=yuv420p", "-r", "10", "-c:v", "libx264", "-preset", "veryfast",
+ "-crf", "24", str(after))
+ return before, after
+
+
+CAPTIONS, PICTURE, AUDIO, DELIVERY, PROJECTS = (
+ "Captions & text", "Picture", "Audio", "Delivery & checks", "Projects & inspection")
+
+DEMOS = [
+ # name, group, title, what to look for, builder, comparison kind, required script
+ ("captions_en", CAPTIONS, "Burned-in captions (English)",
+ "Plain-text cues become an SRT and are rendered by libass -- outline and margin come from the flags, not from a template.",
+ demo_captions_en, "video", "latin"),
+ ("captions_ja", CAPTIONS, "Japanese captions",
+ "The font is chosen per script: Japanese cues get a CJK face automatically, so no box-glyph tofu appears.",
+ demo_captions_ja, "video", "ja"),
+ ("captions_zh", CAPTIONS, "Chinese captions",
+ "Same command, Han text: line breaking and the font switch are handled without a --font flag.",
+ demo_captions_zh, "video", "zh"),
+ ("captions_ko", CAPTIONS, "Korean captions",
+ "Hangul wins script detection even when Latin words are mixed into the same cue.",
+ demo_captions_ko, "video", "ko"),
+ ("captions_ar", CAPTIONS, "Arabic captions",
+ "Right-to-left text shaped by libass; the Latin fragments inside it stay left-to-right.",
+ demo_captions_ar, "video", "ar"),
+ ("captions_pop_karaoke", CAPTIONS, "Animated pop captions with karaoke",
+ "Each cue scales in, and the highlight colour walks word by word across the line.",
+ demo_captions_pop_karaoke, "video", "latin"),
+ ("lower_third", CAPTIONS, "Lower third",
+ "Name and role slide in from the left over the picture and slide out again -- no image asset involved.",
+ demo_lower_third, "video", "latin"),
+ ("title_card", CAPTIONS, "Title card",
+ "A centred title and subtitle fade in over the first seconds and leave the rest of the clip untouched.",
+ demo_title_card, "video", "latin"),
+
+ ("logo_overlay", PICTURE, "Logo overlay with fade",
+ "The semi-transparent logo fades in at 0.5 s and out before the end; the underlying picture is unchanged.",
+ demo_logo_overlay, "video", None),
+ ("hdr_tonemap", PICTURE, "HDR10 to SDR",
+ "The PQ / BT.2020 source is tone-mapped to BT.709: on an SDR screen the 'before' is the washed-out one.",
+ demo_hdr_tonemap, "video", None),
+ ("reframe_crop", PICTURE, "16:9 to 9:16 by cropping",
+ "The vertical frame is cut out of the centre of the wide one -- full height, sides lost.",
+ demo_reframe_crop, "video", None),
+ ("reframe_pad", PICTURE, "16:9 to 9:16 by padding",
+ "Nothing is lost: the wide frame is kept whole and the gap above and below is filled with a blurred copy.",
+ demo_reframe_pad, "video", None),
+ ("speed_up", PICTURE, "Speed change to hit a duration",
+ "An 8 s clip retimed to land exactly on 4 s; audio is pitch-corrected rather than chipmunked.",
+ demo_speed_up, "video", None),
+ ("reverse", PICTURE, "Reverse",
+ "The life pattern runs backwards -- cells un-die; the audio is reversed with it.",
+ demo_reverse, "video", None),
+ ("join_fade", PICTURE, "Join with a cross fade",
+ "Two clips of different content become one; watch the 0.8 s dissolve in the middle.",
+ demo_join_fade, "video", None),
+ ("join_fadeblack", PICTURE, "Join through black",
+ "The same join with fadeblack: the cut dips to black instead of blending the two pictures.",
+ demo_join_fadeblack, "video", None),
+
+ ("silence_removal", AUDIO, "Silence removal",
+ "The 'after' side runs out of material and freezes: that held frame is the part of the timeline that was cut.",
+ demo_silence_removal, "video", None),
+ ("loudness", AUDIO, "Loudness normalisation to -14 LUFS",
+ "Two showwavespic plots: the quiet input on the left, the same programme brought up to broadcast level on the right without clipping.",
+ demo_loudness, "wave", None),
+ ("downmix_51", AUDIO, "5.1 to stereo downmix",
+ "Six discrete tones folded into two channels at the standard coefficients -- the centre and LFE are still audible.",
+ demo_downmix_51, "wave", None),
+ ("bgm_ducking", AUDIO, "Music bed with ducking",
+ "The bed drops by 12 dB whenever the speech-like track is active and comes back up in the pauses.",
+ demo_bgm_ducking, "wave", None),
+
+ ("export_reels", DELIVERY, "Reels export, then checked",
+ "One command produces the 1080x1920 deliverable; check.py then reports the spec row by row and exits non-zero on a FAIL.",
+ demo_export_reels, "video", None),
+
+ ("render_project", PROJECTS, "Whole edit from one project file",
+ "Clips, a transition, captions and a title card described as JSON and rendered in one pass.",
+ demo_render_project, "video", "latin"),
+ ("contact_sheet", PROJECTS, "Contact sheet",
+ "Twelve timecoded frames in one PNG: the fastest way to confirm an edit landed where it should.",
+ demo_contact_sheet, "video", None),
+]
+
+GROUP_ORDER = [CAPTIONS, PICTURE, AUDIO, DELIVERY, PROJECTS]
+BY_NAME = {d[0]: d for d in DEMOS}
+
+
+# --------------------------------------------------------------------------- docs
+DOC_HEADER = """# Demo gallery
+
+Every clip on this page was generated from nothing: ffmpeg's own synthetic sources make the
+footage, and each "after" is produced by running one of this repo's scripts on it. Rebuild the
+whole page's material with:
+
+```bash
+python3 demos/build.py # or: npm run demo
+python3 demos/build.py --list # what gets built
+python3 demos/build.py --only captions_ja
+```
+
+The full-resolution `<name>_before.mp4`, `<name>_after.mp4` and side-by-side `<name>.mp4` land
+in `demos/out/` (gitignored). Only the small previews below are committed, and the build fails
+if any of them exceeds 500 KB.
+
+In every preview the left half is the input and the right half is what the command produced.
+"""
+
+
+def write_docs(path=ROOT / "docs" / "demos.md"):
+ """Generate the gallery page from the same table the builder runs, so the command printed
+ under a preview cannot drift from the command that made it."""
+ lines = [DOC_HEADER]
+ for group in GROUP_ORDER:
+ lines.append("\n## %s\n" % group)
+ for name, grp, title, look, builder, _kind, _script in DEMOS:
+ if grp != group:
+ continue
+ lines.append("### %s\n" % title)
+ lines.append("![%s](demos/%s.gif)\n" % (title, name))
+ lines.append("```bash\n%s\n```\n" % "\n".join(_commands_for(name)))
+ lines.append("**Look for:** %s\n" % look)
+ lines.append("\n---\n")
+ lines.append("Missing a feature you use? A `feat` PR is expected to add a demo here and in "
+ "`demos/build.py` -- see [CONTRIBUTING.md](../CONTRIBUTING.md).\n")
+ path.write_text("\n".join(lines), encoding="utf-8")
+ return path
+
+
+class _DryCtx(Ctx):
+ """Records what a builder would run without running any of it."""
+
+ def script(self, tool, *args, capture=False):
+ self.commands.append(" ".join(["python3", "scripts/" + tool] + [_short(a) for a in args]))
+ return ""
+
+
+def _commands_for(name):
+ """Replay a demo's builder against a recorder, so the docs print the exact command the
+ build runs rather than a hand-copied approximation of it."""
+ ctx = _DryCtx(name, verbose=False)
+ global ffmpeg, duration
+ real_ffmpeg, real_duration = ffmpeg, duration
+ ffmpeg, duration = (lambda *a: None), (lambda p: 0.0)
+ try:
+ BY_NAME[name][4](ctx)
+ except Exception: # a builder that inspects its own output stops early; its commands stand
+ pass
+ finally:
+ ffmpeg, duration = real_ffmpeg, real_duration
+ return ctx.commands or ["python3 scripts/%s.py ..." % name]
+
+
+# --------------------------------------------------------------------------- driver
+def build_demo(name, font, verbose=True):
+ _, group, title, _look, builder, kind, need_script = BY_NAME[name]
+ if need_script and need_script != "latin" and script_font_status(need_script) == "missing":
+ return {"name": name, "status": "skipped",
+ "reason": "no font on this machine covers script %r" % need_script}
+ print("==> %s (%s)" % (name, group))
+ ctx = Ctx(name, verbose=verbose)
+ started = time.time()
+ before, after = builder(ctx)
+
+ # Normalise the "before" side into demos/out/ so a demo's three files sit together.
+ before_copy = OUT / ("%s_before.mp4" % name)
+ if Path(before).resolve() != before_copy.resolve():
+ shutil.copyfile(str(before), str(before_copy))
+
+ compare = OUT / ("%s.mp4" % name)
+ if kind == "wave":
+ make_wave_compare(before_copy, after, compare, font)
+ else:
+ make_compare(before_copy, after, compare, font)
+
+ PREVIEWS.mkdir(parents=True, exist_ok=True)
+ size, fps, width, colors = make_preview(compare, PREVIEWS / ("%s.gif" % name))
+ return {"name": name, "status": "ok", "title": title, "group": group,
+ "bytes": size, "fps": fps, "width": width, "colors": colors,
+ "seconds": round(time.time() - started, 1), "commands": ctx.commands,
+ "notes": ctx.notes}
+
+
+def main(argv=None):
+ ap = argparse.ArgumentParser(description=__doc__.splitlines()[0],
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=__doc__)
+ ap.add_argument("--only", action="append", metavar="NAME",
+ help="build just this demo (repeatable); --list shows the names")
+ ap.add_argument("--list", action="store_true", help="list the demos and exit")
+ ap.add_argument("--docs", action="store_true",
+ help="rewrite docs/demos.md from the table and exit, rendering nothing")
+ ap.add_argument("--force-fixtures", action="store_true",
+ help="regenerate the synthetic source material even if it is already there")
+ ap.add_argument("--json", action="store_true", help="print the result as JSON")
+ args = ap.parse_args(argv)
+
+ if args.list:
+ for name, group, title, _look, _b, _k, _s in DEMOS:
+ print("%-22s %-20s %s" % (name, group, title))
+ return 0
+ if args.docs:
+ print("wrote %s" % write_docs())
+ return 0
+
+ for tool in ("ffmpeg", "ffprobe"):
+ if not shutil.which(tool):
+ print("%s not found on PATH" % tool, file=sys.stderr)
+ return 127
+
+ names = args.only or [d[0] for d in DEMOS]
+ unknown = [n for n in names if n not in BY_NAME]
+ if unknown:
+ print("unknown demo(s): %s (try --list)" % ", ".join(unknown), file=sys.stderr)
+ return 2
+
+ started = time.time()
+ OUT.mkdir(parents=True, exist_ok=True)
+ made = build_fixtures(force=args.force_fixtures)
+ if made:
+ print("==> fixtures: %s" % ", ".join(made))
+
+ font = label_font()
+ results = [build_demo(n, font) for n in names]
+ if not args.only:
+ write_docs()
+
+ ok = [r for r in results if r["status"] == "ok"]
+ skipped = [r for r in results if r["status"] == "skipped"]
+ total = sum(r["bytes"] for r in ok)
+ elapsed = time.time() - started
+ if args.json:
+ print(json.dumps({"demos": results, "preview_bytes": total,
+ "seconds": round(elapsed, 1)}, indent=2, ensure_ascii=False))
+ else:
+ print("\n%-24s %8s %s" % ("demo", "preview", "notes"))
+ for r in results:
+ if r["status"] == "ok":
+ print("%-24s %7.1fK %s" % (r["name"], r["bytes"] / 1024.0, "; ".join(r["notes"])))
+ else:
+ print("%-24s %8s %s" % (r["name"], "skip", r["reason"]))
+ print("\n%d demos, %d skipped, docs/demos/ total %.1f KB, %.1f s"
+ % (len(ok), len(skipped), total / 1024.0, elapsed))
+ return 0
+
+
+if __name__ == "__main__":
+ try:
+ sys.exit(main())
+ except BuildError as exc:
+ print("demo build failed: %s" % exc, file=sys.stderr)
+ sys.exit(1)
diff --git a/docs/demos.md b/docs/demos.md
new file mode 100644
index 0000000..6ac00ea
--- /dev/null
+++ b/docs/demos.md
@@ -0,0 +1,268 @@
+# Demo gallery
+
+Every clip on this page was generated from nothing: ffmpeg's own synthetic sources make the
+footage, and each "after" is produced by running one of this repo's scripts on it. Rebuild the
+whole page's material with:
+
+```bash
+python3 demos/build.py # or: npm run demo
+python3 demos/build.py --list # what gets built
+python3 demos/build.py --only captions_ja
+```
+
+The full-resolution `<name>_before.mp4`, `<name>_after.mp4` and side-by-side `<name>.mp4` land
+in `demos/out/` (gitignored). Only the small previews below are committed, and the build fails
+if any of them exceeds 500 KB.
+
+In every preview the left half is the input and the right half is what the command produced.
+
+
+## Captions & text
+
+### Burned-in captions (English)
+
+![Burned-in captions (English)](demos/captions_en.gif)
+
+```bash
+python3 scripts/caption.py demos/out/fixtures/motion.mp4 --text demos/out/fixtures/cues_en.txt --size 30 --bold --position bottom --margin 40 -o demos/out/captions_en_after.mp4
+```
+
+**Look for:** Plain-text cues become an SRT and are rendered by libass -- outline and margin come from the flags, not from a template.
+
+### Japanese captions
+
+![Japanese captions](demos/captions_ja.gif)
+
+```bash
+python3 scripts/caption.py demos/out/fixtures/motion.mp4 --text demos/out/fixtures/cues_ja.txt --size 30 --bold --position bottom --margin 40 -o demos/out/captions_ja_after.mp4
+```
+
+**Look for:** The font is chosen per script: Japanese cues get a CJK face automatically, so no box-glyph tofu appears.
+
+### Chinese captions
+
+![Chinese captions](demos/captions_zh.gif)
+
+```bash
+python3 scripts/caption.py demos/out/fixtures/motion.mp4 --text demos/out/fixtures/cues_zh.txt --size 30 --bold --position bottom --margin 40 -o demos/out/captions_zh_after.mp4
+```
+
+**Look for:** Same command, Han text: line breaking and the font switch are handled without a --font flag.
+
+### Korean captions
+
+![Korean captions](demos/captions_ko.gif)
+
+```bash
+python3 scripts/caption.py demos/out/fixtures/motion.mp4 --text demos/out/fixtures/cues_ko.txt --size 30 --bold --position bottom --margin 40 -o demos/out/captions_ko_after.mp4
+```
+
+**Look for:** Hangul wins script detection even when Latin words are mixed into the same cue.
+
+### Arabic captions
+
+![Arabic captions](demos/captions_ar.gif)
+
+```bash
+python3 scripts/caption.py demos/out/fixtures/motion.mp4 --text demos/out/fixtures/cues_ar.txt --size 30 --bold --position bottom --margin 40 -o demos/out/captions_ar_after.mp4
+```
+
+**Look for:** Right-to-left text shaped by libass; the Latin fragments inside it stay left-to-right.
+
+### Animated pop captions with karaoke
+
+![Animated pop captions with karaoke](demos/captions_pop_karaoke.gif)
+
+```bash
+python3 scripts/caption.py demos/out/fixtures/motion.mp4 --text demos/out/fixtures/cues_pop.txt --size 30 --bold --position bottom --margin 40 --animate pop --karaoke --highlight-color #39ff88 -o demos/out/captions_pop_karaoke_after.mp4
+```
+
+**Look for:** Each cue scales in, and the highlight colour walks word by word across the line.
+
+### Lower third
+
+![Lower third](demos/lower_third.gif)
+
+```bash
+python3 scripts/graphics.py demos/out/fixtures/motion.mp4 --template lower-third --name 'Ada Lovelace' --title 'Analytical Engine' --start 0.5 --end 5 -o demos/out/lower_third_after.mp4
+```
+
+**Look for:** Name and role slide in from the left over the picture and slide out again -- no image asset involved.
+
+### Title card
+
+![Title card](demos/title_card.gif)
+
+```bash
+python3 scripts/graphics.py demos/out/fixtures/mandel.mp4 --template title --title 'Episode 12' --subtitle 'The math of video' --start 0 --end 4 -o demos/out/title_card_after.mp4
+```
+
+**Look for:** A centred title and subtitle fade in over the first seconds and leave the rest of the clip untouched.
+
+
+## Picture
+
+### Logo overlay with fade
+
+![Logo overlay with fade](demos/logo_overlay.gif)
+
+```bash
+python3 scripts/overlay.py demos/out/fixtures/motion.mp4 --image demos/out/fixtures/logo.png --position top-right --scale 200 --opacity 0.9 --start 0.5 --end 7.5 --fade 0.6 -o demos/out/logo_overlay_after.mp4
+```
+
+**Look for:** The semi-transparent logo fades in at 0.5 s and out before the end; the underlying picture is unchanged.
+
+### HDR10 to SDR
+
+![HDR10 to SDR](demos/hdr_tonemap.gif)
+
+```bash
+python3 scripts/color.py demos/out/fixtures/hdr10.mp4 --to-sdr --tonemap hable --preset veryfast -o demos/out/hdr_tonemap_after.mp4
+```
+
+**Look for:** The PQ / BT.2020 source is tone-mapped to BT.709: on an SDR screen the 'before' is the washed-out one.
+
+### 16:9 to 9:16 by cropping
+
+![16:9 to 9:16 by cropping](demos/reframe_crop.gif)
+
+```bash
+python3 scripts/fit.py demos/out/fixtures/mandel.mp4 --aspect 9:16 --fit crop --width 540 --preset veryfast -o demos/out/reframe_crop_after.mp4
+```
+
+**Look for:** The vertical frame is cut out of the centre of the wide one -- full height, sides lost.
+
+### 16:9 to 9:16 by padding
+
+![16:9 to 9:16 by padding](demos/reframe_pad.gif)
+
+```bash
+python3 scripts/fit.py demos/out/fixtures/mandel.mp4 --aspect 9:16 --fit pad --pad-fill blur --width 540 --preset veryfast -o demos/out/reframe_pad_after.mp4
+```
+
+**Look for:** Nothing is lost: the wide frame is kept whole and the gap above and below is filled with a blurred copy.
+
+### Speed change to hit a duration
+
+![Speed change to hit a duration](demos/speed_up.gif)
+
+```bash
+python3 scripts/fit.py demos/out/fixtures/motion.mp4 --duration 4 --method speed --preset veryfast -o demos/out/speed_up_after.mp4
+```
+
+**Look for:** An 8 s clip retimed to land exactly on 4 s; audio is pitch-corrected rather than chipmunked.
+
+### Reverse
+
+![Reverse](demos/reverse.gif)
+
+```bash
+python3 scripts/reverse.py demos/out/fixtures/life.mp4 --preset veryfast -o demos/out/reverse_after.mp4
+```
+
+**Look for:** The life pattern runs backwards -- cells un-die; the audio is reversed with it.
+
+### Join with a cross fade
+
+![Join with a cross fade](demos/join_fade.gif)
+
+```bash
+python3 scripts/join.py demos/out/fixtures/motion.mp4 demos/out/fixtures/mandel.mp4 --transition fade --duration 0.8 --width 960 --preset veryfast -o demos/out/join_fade_after.mp4
+```
+
+**Look for:** Two clips of different content become one; watch the 0.8 s dissolve in the middle.
+
+### Join through black
+
+![Join through black](demos/join_fadeblack.gif)
+
+```bash
+python3 scripts/join.py demos/out/fixtures/motion.mp4 demos/out/fixtures/mandel.mp4 --transition fadeblack --duration 0.8 --width 960 --preset veryfast -o demos/out/join_fadeblack_after.mp4
+```
+
+**Look for:** The same join with fadeblack: the cut dips to black instead of blending the two pictures.
+
+
+## Audio
+
+### Silence removal
+
+![Silence removal](demos/silence_removal.gif)
+
+```bash
+python3 scripts/silence.py demos/out/fixtures/motion.mp4 --threshold -35 --min-silence 0.4 --margin 0.1 --preset veryfast -o demos/out/silence_removal_after.mp4
+```
+
+**Look for:** The 'after' side runs out of material and freezes: that held frame is the part of the timeline that was cut.
+
+### Loudness normalisation to -14 LUFS
+
+![Loudness normalisation to -14 LUFS](demos/loudness.gif)
+
+```bash
+python3 scripts/loudness.py demos/out/loudness_before.mp4 -I -14 --tp -1 -o demos/out/loudness_after.mp4
+```
+
+**Look for:** Two showwavespic plots: the quiet input on the left, the same programme brought up to broadcast level on the right without clipping.
+
+### 5.1 to stereo downmix
+
+![5.1 to stereo downmix](demos/downmix_51.gif)
+
+```bash
+python3 scripts/audio.py demos/out/fixtures/surround.mp4 --downmix -o demos/out/downmix_51_after.mp4
+```
+
+**Look for:** Six discrete tones folded into two channels at the standard coefficients -- the centre and LFE are still audible.
+
+### Music bed with ducking
+
+![Music bed with ducking](demos/bgm_ducking.gif)
+
+```bash
+python3 scripts/audio.py demos/out/fixtures/motion.mp4 --music demos/out/fixtures/music.m4a --duck --duck-amount 12 --music-volume 0.6 --fade-out 1.5 -o demos/out/bgm_ducking_after.mp4
+```
+
+**Look for:** The bed drops by 12 dB whenever the speech-like track is active and comes back up in the pauses.
+
+
+## Delivery & checks
+
+### Reels export, then checked
+
+![Reels export, then checked](demos/export_reels.gif)
+
+```bash
+python3 scripts/export.py demos/out/fixtures/motion.mp4 --preset reels --fit crop -o demos/out/export_reels_after.mp4
+python3 scripts/check.py demos/out/export_reels_after.mp4 --platform reels --json
+```
+
+**Look for:** One command produces the 1080x1920 deliverable; check.py then reports the spec row by row and exits non-zero on a FAIL.
+
+
+## Projects & inspection
+
+### Whole edit from one project file
+
+![Whole edit from one project file](demos/render_project.gif)
+
+```bash
+python3 scripts/render.py demos/out/fixtures/project.json --fast
+```
+
+**Look for:** Clips, a transition, captions and a title card described as JSON and rendered in one pass.
+
+### Contact sheet
+
+![Contact sheet](demos/contact_sheet.gif)
+
+```bash
+python3 scripts/look.py demos/out/fixtures/mandel.mp4 --tiles 4x3 --width 960 -o demos/out/contact_sheet_sheet.png
+```
+
+**Look for:** Twelve timecoded frames in one PNG: the fastest way to confirm an edit landed where it should.
+
+
+---
+
+Missing a feature you use? A `feat` PR is expected to add a demo here and in `demos/build.py` -- see [CONTRIBUTING.md](../CONTRIBUTING.md).
diff --git a/docs/demos/bgm_ducking.gif b/docs/demos/bgm_ducking.gif
new file mode 100644
index 0000000..589ca09
Binary files /dev/null and b/docs/demos/bgm_ducking.gif differ
diff --git a/docs/demos/captions_ar.gif b/docs/demos/captions_ar.gif
new file mode 100644
index 0000000..d09e665
Binary files /dev/null and b/docs/demos/captions_ar.gif differ
diff --git a/docs/demos/captions_en.gif b/docs/demos/captions_en.gif
new file mode 100644
index 0000000..afe65da
Binary files /dev/null and b/docs/demos/captions_en.gif differ
diff --git a/docs/demos/captions_ja.gif b/docs/demos/captions_ja.gif
new file mode 100644
index 0000000..b9c970b
Binary files /dev/null and b/docs/demos/captions_ja.gif differ
diff --git a/docs/demos/captions_ko.gif b/docs/demos/captions_ko.gif
new file mode 100644
index 0000000..c9d947a
Binary files /dev/null and b/docs/demos/captions_ko.gif differ
diff --git a/docs/demos/captions_pop_karaoke.gif b/docs/demos/captions_pop_karaoke.gif
new file mode 100644
index 0000000..988558f
Binary files /dev/null and b/docs/demos/captions_pop_karaoke.gif differ
diff --git a/docs/demos/captions_zh.gif b/docs/demos/captions_zh.gif
new file mode 100644
index 0000000..fe99b14
Binary files /dev/null and b/docs/demos/captions_zh.gif differ
diff --git a/docs/demos/contact_sheet.gif b/docs/demos/contact_sheet.gif
new file mode 100644
index 0000000..348f287
Binary files /dev/null and b/docs/demos/contact_sheet.gif differ
diff --git a/docs/demos/downmix_51.gif b/docs/demos/downmix_51.gif
new file mode 100644
index 0000000..e56d02a
Binary files /dev/null and b/docs/demos/downmix_51.gif differ
diff --git a/docs/demos/export_reels.gif b/docs/demos/export_reels.gif
new file mode 100644
index 0000000..0dd3e9e
Binary files /dev/null and b/docs/demos/export_reels.gif differ
diff --git a/docs/demos/hdr_tonemap.gif b/docs/demos/hdr_tonemap.gif
new file mode 100644
index 0000000..259b33c
Binary files /dev/null and b/docs/demos/hdr_tonemap.gif differ
diff --git a/docs/demos/join_fade.gif b/docs/demos/join_fade.gif
new file mode 100644
index 0000000..a3faf82
Binary files /dev/null and b/docs/demos/join_fade.gif differ
diff --git a/docs/demos/join_fadeblack.gif b/docs/demos/join_fadeblack.gif
new file mode 100644
index 0000000..a3faf82
Binary files /dev/null and b/docs/demos/join_fadeblack.gif differ
diff --git a/docs/demos/logo_overlay.gif b/docs/demos/logo_overlay.gif
new file mode 100644
index 0000000..d65571f
Binary files /dev/null and b/docs/demos/logo_overlay.gif differ
diff --git a/docs/demos/loudness.gif b/docs/demos/loudness.gif
new file mode 100644
index 0000000..5d0e267
Binary files /dev/null and b/docs/demos/loudness.gif differ
diff --git a/docs/demos/lower_third.gif b/docs/demos/lower_third.gif
new file mode 100644
index 0000000..943cfeb
Binary files /dev/null and b/docs/demos/lower_third.gif differ
diff --git a/docs/demos/reframe_crop.gif b/docs/demos/reframe_crop.gif
new file mode 100644
index 0000000..53bc638
Binary files /dev/null and b/docs/demos/reframe_crop.gif differ
diff --git a/docs/demos/reframe_pad.gif b/docs/demos/reframe_pad.gif
new file mode 100644
index 0000000..15886b0
Binary files /dev/null and b/docs/demos/reframe_pad.gif differ
diff --git a/docs/demos/render_project.gif b/docs/demos/render_project.gif
new file mode 100644
index 0000000..81839c1
Binary files /dev/null and b/docs/demos/render_project.gif differ
diff --git a/docs/demos/reverse.gif b/docs/demos/reverse.gif
new file mode 100644
index 0000000..ba0e426
Binary files /dev/null and b/docs/demos/reverse.gif differ
diff --git a/docs/demos/silence_removal.gif b/docs/demos/silence_removal.gif
new file mode 100644
index 0000000..09f6ee7
Binary files /dev/null and b/docs/demos/silence_removal.gif differ
diff --git a/docs/demos/speed_up.gif b/docs/demos/speed_up.gif
new file mode 100644
index 0000000..efb1043
Binary files /dev/null and b/docs/demos/speed_up.gif differ
diff --git a/docs/demos/title_card.gif b/docs/demos/title_card.gif
new file mode 100644
index 0000000..8a7a096
Binary files /dev/null and b/docs/demos/title_card.gif differ
diff --git a/examples/make_demo.sh b/examples/make_demo.sh
index 7e33a2b..6fc08d6 100755
--- a/examples/make_demo.sh
+++ b/examples/make_demo.sh
@@ -2,6 +2,10 @@
# Generate demo footage from nothing (ffmpeg testsrc2 + synthesized audio),
# run every script in scripts/ on it, and build assets/demo.gif (before/after).
#
+# This is the single end-to-end pipeline run (one clip through every script). For the
+# per-feature before/after gallery in docs/demos.md, use demos/build.py instead --
+# that is what `npm run demo` runs now; this script is `npm run demo:pipeline`.
+#
# bash examples/make_demo.sh # writes examples/out/
# OUT=/tmp/demo bash examples/make_demo.sh
set -euo pipefail
diff --git a/package.json b/package.json
index 19836f6..163748a 100644
--- a/package.json
+++ b/package.json
@@ -42,7 +42,8 @@
"scripts": {
"test": "python3 tests/test_all.py && python3 tests/test_contract.py",
"release-check": "bash tests/release_check.sh",
- "demo": "bash examples/make_demo.sh",
+ "demo": "python3 demos/build.py",
+ "demo:pipeline": "bash examples/make_demo.sh",
"contract": "python3 scripts/_contract.py --json",
"doctor": "python3 scripts/_contract.py doctor"
},
diff --git a/tests/test_all.py b/tests/test_all.py
index cfbe8f0..8d7b5e9 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -4415,6 +4415,56 @@ class ScriptFontTests(unittest.TestCase):
self.assertEqual(font_for_script("ja"), font_for_script("ja"))
+class DemoGalleryTests(unittest.TestCase):
+ """The gallery in docs/demos.md is committed, so its builder is a shipped artefact: if
+ demos/build.py stops rendering, the README's pictures quietly describe an older tool.
+
+ One cheap demo is enough to prove the whole path -- fixtures, a real script invocation, the
+ side-by-side, the preview and the size budget -- without spending two minutes of CI on all
+ 23 of them (the `demos` job in demos/CI.md runs the full set)."""
+
+ def test_build_one_demo_and_stay_under_the_preview_budget(self):
+ if not shutil.which("ffmpeg"):
+ if os.environ.get("CI"):
+ raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step")
+ raise unittest.SkipTest("ffmpeg not on PATH")
+ from _common import script_font_status
+ if script_font_status("ja") == "missing":
+ # Not a failure: the demo itself skips for the same reason. A machine with no CJK
+ # font cannot render Japanese captions, and a tofu-filled GIF would be worse than none.
+ raise unittest.SkipTest("no font on this machine covers Japanese: captions_ja cannot render")
+ preview = ROOT / "docs" / "demos" / "captions_ja.gif"
+ before = preview.read_bytes() if preview.exists() else None
+ try:
+ sh(sys.executable, ROOT / "demos" / "build.py", "--only", "captions_ja")
+ self.assertTrue(preview.exists(), f"{preview} was not written")
+ size = preview.stat().st_size
+ self.assertLessEqual(size, 500 * 1024,
+ f"{preview.name} is {size} bytes; previews are committed and "
+ f"capped at 500 KB (demos/build.py enforces this too)")
+ self.assertGreater(size, 1024, "a preview that small did not render anything")
+ for name in ("captions_ja_before.mp4", "captions_ja_after.mp4", "captions_ja.mp4"):
+ self.assertTrue((ROOT / "demos" / "out" / name).exists(), f"demos/out/{name} missing")
+ finally:
+ # Leave the committed preview exactly as it was: this machine's ffmpeg writes
+ # different GIF bytes than the one that built the gallery, and a test must not
+ # dirty the working tree it ran in.
+ if before is not None:
+ preview.write_bytes(before)
+
+ def test_every_demo_in_the_table_is_listed_and_documented(self):
+ """--list and docs/demos.md are two views of the same table; a demo added to the
+ builder without a gallery entry is a picture nobody ever sees."""
+ listed = sh(sys.executable, ROOT / "demos" / "build.py", "--list").stdout
+ names = [line.split()[0] for line in listed.splitlines() if line.strip()]
+ self.assertGreaterEqual(len(names), 10, "the gallery lost most of its demos")
+ page = (ROOT / "docs" / "demos.md").read_text(encoding="utf-8")
+ for name in names:
+ self.assertIn(f"demos/{name}.gif", page,
+ f"{name} is built but has no section in docs/demos.md "
+ f"(run: python3 demos/build.py --docs)")
+
+
def _families_for(script):
"""Families fontconfig lists for `script`, or [] where there is no fontconfig to ask (Windows
resolves fonts by file name, so font_for_script() answers there without an fc-list on PATH --