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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
docs: before/after demo gallery (23 demos, demos/build.py, docs/demos.md) (#222)
claude[bot]b91b45fc933b
diff --git a/.gitignore b/.gitignoreindex 677dab7..3a4634b 100644--- a/.gitignore+++ b/.gitignore@@ -1,5 +1,6 @@# demo / test outputexamples/out/+demos/out/tests/out/*.logdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 neveropen 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 issuesdiff --git a/README.md b/README.mdindex 4d9ee5e..df1baf9 100644--- a/README.md+++ b/README.md@@ -28,7 +28,18 @@npx ffmpeg-skill```-+<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 # structureOn 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:```bashnpm test # tests/test_all.py (end-to-end incl. VFR, rotated, 5.1, HDR10, drifting sources) + tests/test_contract.pynpm 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 scriptpython3 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.mdnew file mode 100644index 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.pynew file mode 100644index 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("\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.mdnew file mode 100644index 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)++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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++++```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.gifnew file mode 100644index 0000000..589ca09Binary files /dev/null and b/docs/demos/bgm_ducking.gif differdiff --git a/docs/demos/captions_ar.gif b/docs/demos/captions_ar.gifnew file mode 100644index 0000000..d09e665Binary files /dev/null and b/docs/demos/captions_ar.gif differdiff --git a/docs/demos/captions_en.gif b/docs/demos/captions_en.gifnew file mode 100644index 0000000..afe65daBinary files /dev/null and b/docs/demos/captions_en.gif differdiff --git a/docs/demos/captions_ja.gif b/docs/demos/captions_ja.gifnew file mode 100644index 0000000..b9c970bBinary files /dev/null and b/docs/demos/captions_ja.gif differdiff --git a/docs/demos/captions_ko.gif b/docs/demos/captions_ko.gifnew file mode 100644index 0000000..c9d947aBinary files /dev/null and b/docs/demos/captions_ko.gif differdiff --git a/docs/demos/captions_pop_karaoke.gif b/docs/demos/captions_pop_karaoke.gifnew file mode 100644index 0000000..988558fBinary files /dev/null and b/docs/demos/captions_pop_karaoke.gif differdiff --git a/docs/demos/captions_zh.gif b/docs/demos/captions_zh.gifnew file mode 100644index 0000000..fe99b14Binary files /dev/null and b/docs/demos/captions_zh.gif differdiff --git a/docs/demos/contact_sheet.gif b/docs/demos/contact_sheet.gifnew file mode 100644index 0000000..348f287Binary files /dev/null and b/docs/demos/contact_sheet.gif differdiff --git a/docs/demos/downmix_51.gif b/docs/demos/downmix_51.gifnew file mode 100644index 0000000..e56d02aBinary files /dev/null and b/docs/demos/downmix_51.gif differdiff --git a/docs/demos/export_reels.gif b/docs/demos/export_reels.gifnew file mode 100644index 0000000..0dd3e9eBinary files /dev/null and b/docs/demos/export_reels.gif differdiff --git a/docs/demos/hdr_tonemap.gif b/docs/demos/hdr_tonemap.gifnew file mode 100644index 0000000..259b33cBinary files /dev/null and b/docs/demos/hdr_tonemap.gif differdiff --git a/docs/demos/join_fade.gif b/docs/demos/join_fade.gifnew file mode 100644index 0000000..a3faf82Binary files /dev/null and b/docs/demos/join_fade.gif differdiff --git a/docs/demos/join_fadeblack.gif b/docs/demos/join_fadeblack.gifnew file mode 100644index 0000000..a3faf82Binary files /dev/null and b/docs/demos/join_fadeblack.gif differdiff --git a/docs/demos/logo_overlay.gif b/docs/demos/logo_overlay.gifnew file mode 100644index 0000000..d65571fBinary files /dev/null and b/docs/demos/logo_overlay.gif differdiff --git a/docs/demos/loudness.gif b/docs/demos/loudness.gifnew file mode 100644index 0000000..5d0e267Binary files /dev/null and b/docs/demos/loudness.gif differdiff --git a/docs/demos/lower_third.gif b/docs/demos/lower_third.gifnew file mode 100644index 0000000..943cfebBinary files /dev/null and b/docs/demos/lower_third.gif differdiff --git a/docs/demos/reframe_crop.gif b/docs/demos/reframe_crop.gifnew file mode 100644index 0000000..53bc638Binary files /dev/null and b/docs/demos/reframe_crop.gif differdiff --git a/docs/demos/reframe_pad.gif b/docs/demos/reframe_pad.gifnew file mode 100644index 0000000..15886b0Binary files /dev/null and b/docs/demos/reframe_pad.gif differdiff --git a/docs/demos/render_project.gif b/docs/demos/render_project.gifnew file mode 100644index 0000000..81839c1Binary files /dev/null and b/docs/demos/render_project.gif differdiff --git a/docs/demos/reverse.gif b/docs/demos/reverse.gifnew file mode 100644index 0000000..ba0e426Binary files /dev/null and b/docs/demos/reverse.gif differdiff --git a/docs/demos/silence_removal.gif b/docs/demos/silence_removal.gifnew file mode 100644index 0000000..09f6ee7Binary files /dev/null and b/docs/demos/silence_removal.gif differdiff --git a/docs/demos/speed_up.gif b/docs/demos/speed_up.gifnew file mode 100644index 0000000..efb1043Binary files /dev/null and b/docs/demos/speed_up.gif differdiff --git a/docs/demos/title_card.gif b/docs/demos/title_card.gifnew file mode 100644index 0000000..8a7a096Binary files /dev/null and b/docs/demos/title_card.gif differdiff --git a/examples/make_demo.sh b/examples/make_demo.shindex 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.shset -euo pipefaildiff --git a/package.json b/package.jsonindex 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.pyindex 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 (Windowsresolves fonts by file name, so font_for_script() answers there without an fc-list on PATH --