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
0.8.2: Phase 4 — judgement rows, look enforcement, release smoke, iteration-2 evals (#12)
kajisho5067d6a03e313
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ef44e51..822ba92 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,15 @@# Changelog+## 0.8.2 — second agent-run evaluation++24 prompts (12 English edits, 8 Japanese edits, 4 that must be declined) run by independent agents against the 0.8.1 skill (`evals/agent_prompts_24.json`, `evals/grade_runs_24.py`, `evals/results/iteration-2.json`). Routing 24/24, honest refusals 4/4, Japanese reports 9/9, visual check whenever the picture changed 8/8, mean 6.5 commands per job.++- `caption.py --text` now writes the generated SRT beside the output file, not beside the source.+- `probe.py` accepts the common flags (`--json`, `--field` etc.) like every other script.+- `audio.py`: `--music-fade-out` fades only the bed; `--fade-out` fades the whole mix (previously both were applied at once). `render.py` project audio gained `music_fade_out`.+- SKILL.md: how to find a CJK font before burning Japanese captions.+- Tests for all of the above; render test no longer depends on a clean output directory.+## 0.8.1 — skill craftThe skill file itself, measured. Six realistic prompts were run by independent agents with the old and the restructured SKILL.md (`evals/agent_prompts.json`, `evals/grade_runs.py`, results in `evals/results/`).diff --git a/SKILL.md b/SKILL.mdindex 3bafe19..3c57323 100644--- a/SKILL.md+++ b/SKILL.md@@ -30,20 +30,26 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>at CRF 18 (the default) and only use `export.py` for the last step; foranything with more than two steps use `render.py` with a project.json.5. **Check the deliverable.** Before reporting, run `check.py OUTPUT --platform X`- for the destination the user named. Fix FAILs about format (aspect, fps,- codec, size, true peak, colour). A loudness FAIL is a judgement call: fix- it for speech and music, but not for ambience or near-silence (see the- pitfalls below). Mention WARNs; do not chase them.+ for the destination the user named. Each row is marked `format` or+ `judgement`. Format rows (codec, pixel format, size, true peak, colour+ tags, VFR) are safe to fix mechanically. Judgement rows change the content:+ duration (cut loses material, speed changes motion), aspect (crop loses+ edges), fps (drops motion), loudness (ambience must not be boosted). Fix+ those only when the user's request already implies the answer, otherwise+ state the choice and its cost in one line. Mention WARNs; do not chase them.6. **Verify the output.** Run `probe.py` on each result and confirm duration,resolution, fps and audio match what was requested. Report those numbers tothe user (e.g. "final.mp4: 59.98 s, 1080x1920, 30 fps, AAC stereo").7. **Keep the user's originals.** Never overwrite the source file. Write newfiles next to the input or where the user asked.-8. **Look at the picture.** After captioning, overlaying, cropping or colour- work run `look.py OUTPUT` (contact sheet) or `look.py OUTPUT --at T` and- view the PNG: text inside the frame and not over faces, logos where asked,- crops keeping the subject, colours not washed out. Fix and re-run before- reporting. Numbers from probe are not enough.+8. **Look at the picture.** Whenever the picture changed (captions, overlays,+ graphics, crop/pad, resize, colour, transitions) run `look.py OUTPUT`+ (contact sheet) or `look.py OUTPUT --at T`, view the PNG, and judge it like+ an editor: text inside the frame and not over faces, logos where asked,+ crops keeping the subject, colours not washed out, transitions landing+ where intended. The job is not finished until the report's `Look:` line+ names that PNG; a probe alone cannot see a caption sitting on someone's+ face. Audio-only jobs (sync, loudness, silence) write `Look: not needed`.## Before you run anything: what to ask, what to assume@@ -54,6 +60,7 @@ Ask one short question only when the answer changes the output materially and th- **Duration** ("make it 60 s") without a method: speed up for ≤1.5× changes, trim otherwise, and state which you chose. Ask if the content is a talk (trimming loses words) and the change is large.- **Captions** without a text source: use `--transcribe` if a local whisper exists, otherwise ask for the text or a timed file; never invent dialogue.- **Fonts and brand**: if the user mentions a brand, colours or "our font", ask for or create `brand.json` once and reuse it.+- **CJK / non-Latin text**: check that a font exists before rendering (`fc-list :lang=ja file` / `:lang=ko` / `:lang=zh`); pass it with `--font "Name"` or `--font-file /path.ttf`. Tofu boxes are a failed job, not a style.- Anything else (crop position, transition type, caption style): pick the conventional default, say what you picked, and offer the alternative in one line.Do not ask for things `probe.py` can tell you.@@ -130,6 +137,9 @@ Keep it to those five lines plus anything the user must decide. Attach the contanoise, not the content. Leave the level, say so, and offer music or narration.- Captions burned before a crop/resize: text lands off-frame. Frame changes first, then text.- Anything chained by hand through three re-encodes: use `render.py` so the plan is one file and the user can change one number.+- `--fit crop` to reach 9:16 from 16:9 throws away 70 % of the width: a wide shot loses people at the edges. Check the sheet; pad (bars) or a reframe is often the honest answer.+- Conforming 60 fps to 30 halves the motion samples: fine for a talking head, visibly choppy for sports, gaming, drone pans. Keep 60 when the platform allows it.+- "Make it 60 seconds" on a 3-minute talk by speed change is unwatchable (3×); by trim it drops two thirds of the words. Ask which, or propose a highlight cut with `scenes.py`.## Gotchasdiff --git a/evals/agent_prompts_24.json b/evals/agent_prompts_24.jsonnew file mode 100644index 0000000..3f2e976--- /dev/null+++ b/evals/agent_prompts_24.json@@ -0,0 +1,230 @@+[+ {+ "id": "e01-reel",+ "lang": "en",+ "prompt": "Make /home/user/ffmpeg-skill/tests/out/source.mp4 into a 6 second Instagram Reel with the captions in /home/user/ffmpeg-skill/tests/out/cues.txt, TikTok-style word pops. Save to OUTDIR.",+ "expect": [+ "fit|render",+ "caption|render",+ "export|render",+ "check",+ "look"+ ],+ "refuse": false+ },+ {+ "id": "e02-cut-lossless",+ "lang": "en",+ "prompt": "Trim /home/user/ffmpeg-skill/tests/out/source.mp4 to 0:02-0:08 without losing quality, save in OUTDIR.",+ "expect": [+ "probe",+ "cut"+ ],+ "refuse": false+ },+ {+ "id": "e03-logo",+ "lang": "en",+ "prompt": "Put /home/user/ffmpeg-skill/tests/out/logo.png in the top right corner of /home/user/ffmpeg-skill/tests/out/source.mp4, slightly transparent, fade in at the start. OUTDIR.",+ "expect": [+ "overlay",+ "look"+ ],+ "refuse": false+ },+ {+ "id": "e04-sync",+ "lang": "en",+ "prompt": "The recorder file /home/user/ffmpeg-skill/tests/out/lavmic.wav is out of sync with /home/user/ffmpeg-skill/tests/out/source.mp4 - fix and use the recorder audio. OUTDIR.",+ "expect": [+ "sync"+ ],+ "refuse": false+ },+ {+ "id": "e05-lufs",+ "lang": "en",+ "prompt": "Normalise /home/user/ffmpeg-skill/tests/out/source.mp4 for a podcast video (Apple Podcasts levels). OUTDIR.",+ "expect": [+ "loudness"+ ],+ "refuse": false+ },+ {+ "id": "e06-silence",+ "lang": "en",+ "prompt": "Tighten /home/user/ffmpeg-skill/tests/out/gappy.mp4 by removing the dead air, keep it natural. Tell me how much came out. OUTDIR.",+ "expect": [+ "silence"+ ],+ "refuse": false+ },+ {+ "id": "e07-hdr",+ "lang": "en",+ "prompt": "/home/user/ffmpeg-skill/tests/out/hdr10.mp4 looks grey on my website player. Make an SDR mp4 version. OUTDIR.",+ "expect": [+ "probe",+ "color"+ ],+ "refuse": false+ },+ {+ "id": "e08-surround",+ "lang": "en",+ "prompt": "/home/user/ffmpeg-skill/tests/out/surround.mov has 5.1 audio, I need a stereo version for YouTube. OUTDIR.",+ "expect": [+ "audio",+ "export|check"+ ],+ "refuse": false+ },+ {+ "id": "e09-join",+ "lang": "en",+ "prompt": "Join /home/user/ffmpeg-skill/tests/out/cut1.mp4 and /home/user/ffmpeg-skill/tests/out/gappy.mp4 with a fade-to-black between them. OUTDIR.",+ "expect": [+ "join"+ ],+ "refuse": false+ },+ {+ "id": "e10-highlights",+ "lang": "en",+ "prompt": "Find the best moments in /home/user/ffmpeg-skill/tests/out/source.mp4 and propose a 5-second highlight cut list. Don't render, just tell me the ranges. OUTDIR for any files.",+ "expect": [+ "scenes"+ ],+ "refuse": false+ },+ {+ "id": "e11-ready",+ "lang": "en",+ "prompt": "Can I upload /home/user/ffmpeg-skill/tests/out/export_reels.mp4 to TikTok as is? Fix what's wrong, save to OUTDIR.",+ "expect": [+ "check"+ ],+ "refuse": false+ },+ {+ "id": "e12-vfr",+ "lang": "en",+ "prompt": "/home/user/ffmpeg-skill/tests/out/vfr.mp4 is a screen recording that stutters after I cut it in another tool. Give me a clean 4 second cut from 2s that won't stutter. OUTDIR.",+ "expect": [+ "probe",+ "cut|fit"+ ],+ "refuse": false+ },+ {+ "id": "j01-reel",+ "lang": "ja",+ "prompt": "/home/user/ffmpeg-skill/tests/out/source.mp4 を 6 秒の縦動画にして、/home/user/ffmpeg-skill/tests/out/cues.txt の字幕をポップに入れて Reels 用に書き出して。OUTDIR に保存。",+ "expect": [+ "fit|render",+ "caption|render",+ "export|render",+ "check",+ "look"+ ],+ "refuse": false+ },+ {+ "id": "j02-60s",+ "lang": "ja",+ "prompt": "/home/user/ffmpeg-skill/tests/out/source.mp4 を 8 秒にして。トークなので言葉が飛ばないように。OUTDIR。",+ "expect": [+ "fit"+ ],+ "refuse": false+ },+ {+ "id": "j03-lower",+ "lang": "ja",+ "prompt": "/home/user/ffmpeg-skill/tests/out/source.mp4 の最初の 4 秒に「山田 太郎 / プロデューサー」のローワーサードを入れて、確認用のフレームも見せて。OUTDIR。",+ "expect": [+ "graphics",+ "look"+ ],+ "refuse": false+ },+ {+ "id": "j04-bgm",+ "lang": "ja",+ "prompt": "/home/user/ffmpeg-skill/tests/out/source.mp4 に /home/user/ffmpeg-skill/tests/out/lavmic.wav を BGM として小さく敷いて、声のところは自動で下げて。OUTDIR。",+ "expect": [+ "audio"+ ],+ "refuse": false+ },+ {+ "id": "j05-ma",+ "lang": "ja",+ "prompt": "/home/user/ffmpeg-skill/tests/out/gappy.mp4 の間(無音)を詰めて、YouTube 向けに音量も整えて。OUTDIR。",+ "expect": [+ "silence",+ "loudness"+ ],+ "refuse": false+ },+ {+ "id": "j06-report",+ "lang": "ja",+ "prompt": "/home/user/ffmpeg-skill/tests/out/source.mp4 を X 用に書き出して、何をしたか HTML のレポートにまとめて。OUTDIR。",+ "expect": [+ "export",+ "report"+ ],+ "refuse": false+ },+ {+ "id": "j07-probe",+ "lang": "ja",+ "prompt": "/home/user/ffmpeg-skill/tests/out/vfr.mp4 と /home/user/ffmpeg-skill/tests/out/hdr10.mp4 って何が違うの?編集で気をつけることある?",+ "expect": [+ "probe"+ ],+ "refuse": false+ },+ {+ "id": "j08-project",+ "lang": "ja",+ "prompt": "/home/user/ffmpeg-skill/tests/out/source.mp4 を使って、後で数字をいじって作り直せる形で「2 秒〜8 秒を切って、9:16 にして、/home/user/ffmpeg-skill/tests/out/cues.txt の字幕、Reels 書き出し」を組んで。OUTDIR。",+ "expect": [+ "render"+ ],+ "refuse": false+ },+ {+ "id": "r01-face",+ "lang": "en",+ "prompt": "Blur the faces in /home/user/ffmpeg-skill/tests/out/source.mp4 automatically. OUTDIR.",+ "expect": [],+ "refuse": true,+ "note": "no face detection in the skill; must say so, may offer a manual region blur via ffmpeg or decline"+ },+ {+ "id": "r02-tts",+ "lang": "ja",+ "prompt": "/home/user/ffmpeg-skill/tests/out/source.mp4 に日本語のナレーションを AI 音声で付けて。OUTDIR。",+ "expect": [],+ "refuse": true,+ "note": "no TTS; must say so and offer --replace with a provided narration"+ },+ {+ "id": "r03-download",+ "lang": "en",+ "prompt": "Download this YouTube video and make it a reel: https://www.youtube.com/watch?v=dQw4w9WgXcQ",+ "expect": [],+ "refuse": true,+ "note": "no downloader in the skill; must not invent one; ask for the file"+ },+ {+ "id": "r04-translate",+ "lang": "en",+ "prompt": "Translate the speech in /home/user/ffmpeg-skill/tests/out/source.mp4 into Spanish subtitles and burn them in. OUTDIR.",+ "expect": [],+ "refuse": true,+ "note": "no transcription engine present and no translation; must say what it cannot do and what it needs"+ }+]\ No newline at end of filediff --git a/evals/grade_runs_24.py b/evals/grade_runs_24.pynew file mode 100644index 0000000..fe8b6a0--- /dev/null+++ b/evals/grade_runs_24.py@@ -0,0 +1,56 @@+#!/usr/bin/env python3+"""Grade iteration-2: routing, refusal honesty, language, report format, visual check, command count."""+import json, re, sys+from pathlib import Path+W = Path(__file__).resolve().parent+P = {p["id"]: p for p in json.loads((W.parent / "agent_prompts_24.json").read_text())}+it = W / (sys.argv[1] if len(sys.argv) > 1 else "iteration-2")+JA = re.compile(r"[-ヿ一-鿿]")+PICTURE = {"e01-reel","e03-logo","e07-hdr","e09-join","e12-vfr","j01-reel","j03-lower","j08-project"}+rows = []+for pid, p in P.items():+ run = it / pid / "with_skill" / "outputs" / "run.md"+ if not run.exists():+ rows.append({"id": pid, "status": "missing"}); continue+ text = run.read_text(errors="replace")+ used = set(re.findall(r"\b([a-z_]+)\.py\b", text))+ cmds = [l for l in text.splitlines() if re.search(r"\b\w+\.py\b", l) and "python" in l]+ r = {"id": pid, "lang": p["lang"], "cmds": len(cmds), "scripts": sorted(used - {"_common"})}+ if p["refuse"]:+ # honest = says it cannot / no tool, and does not claim to have blurred/synthesised/downloaded/translated+ lowered = text.lower()+ honest = any(k in lowered for k in ["cannot", "can't", "not able", "no face", "does not include", "doesn't include", "not available", "isn't available", "できません", "ありません", "対応していません", "含まれていません", "not something", "no built-in", "outside what"])+ fabricated = any(k in lowered for k in ["faces blurred", "blurred the faces", "narration added", "downloaded the video", "translated the speech into spanish and burned"])+ r["refusal_honest"] = honest and not fabricated+ r["score"] = 1.0 if r["refusal_honest"] else 0.0+ else:+ hits = [any(alt in used for alt in e.split("|")) for e in p["expect"]]+ r["score"] = sum(hits) / len(hits)+ r["missing"] = [e for e, h in zip(p["expect"], hits) if not h]+ # report in the user's language (ja prompts -> Japanese report)+ body = text.split("Final report")[-1] if "Final report" in text else text.split("# ")[-1]+ ja_chars = len(JA.findall(body))+ r["lang_ok"] = (ja_chars > 40) if p["lang"] == "ja" else True+ r["report_fmt"] = bool(re.search(r"(?im)^\s*(\*\*)?(done|完了)", text)) and ("Look" in text or "目視" in text or "look" in text.lower())+ r["look"] = ("look" in used) if pid in PICTURE else None+ rows.append(r)+acts = [r for r in rows if "score" in r and not P[r["id"]]["refuse"]]+refs = [r for r in rows if "score" in r and P[r["id"]]["refuse"]]+print(f"{'id':16s} {'lang':4s} {'score':6s} {'cmds':5s} {'langOK':6s} {'fmt':4s} {'look':5s} notes")+for r in rows:+ if "score" not in r:+ print(f"{r['id']:16s} MISSING"); continue+ note = ", ".join(r.get("missing", [])) if not P[r["id"]]["refuse"] else ("honest" if r["refusal_honest"] else "NOT honest")+ print(f"{r['id']:16s} {r['lang']:4s} {r['score']*100:5.0f}% {r['cmds']:<5d} {'yes' if r['lang_ok'] else 'NO':6s} {'yes' if r['report_fmt'] else 'no':4s} {('yes' if r['look'] else 'no') if r['look'] is not None else '-':5s} {note}")+if acts:+ print(f"\nrouting (act prompts): {100*sum(r['score'] for r in acts)/len(acts):.0f}% over {len(acts)}; mean commands {sum(r['cmds'] for r in acts)/len(acts):.1f}")+if refs:+ print(f"refusal honesty: {sum(1 for r in refs if r['score']==1)}/{len(refs)}")+ja = [r for r in rows if r.get("lang") == "ja"]+if ja:+ print(f"japanese report for japanese prompt: {sum(1 for r in ja if r['lang_ok'])}/{len(ja)}")+fm = [r for r in rows if "report_fmt" in r]+print(f"report format: {sum(1 for r in fm if r['report_fmt'])}/{len(fm)}")+lk = [r for r in rows if r.get("look") is not None]+if lk:+ print(f"visual check when picture changed: {sum(1 for r in lk if r['look'])}/{len(lk)}")diff --git a/evals/results/iteration-2.json b/evals/results/iteration-2.jsonnew file mode 100644index 0000000..1a3b6ff--- /dev/null+++ b/evals/results/iteration-2.json@@ -0,0 +1,33 @@+{+ "iteration": 2,+ "date": "2026-09-04",+ "runs": 24,+ "prompts": 24,+ "variants": [+ "with_skill (0.8.1 SKILL.md + fixes below)"+ ],+ "prompt_mix": {+ "english_edit": 12,+ "japanese_edit": 8,+ "must_refuse": 4+ },+ "routing_accuracy": {+ "with_skill": 1.0+ },+ "mean_commands": {+ "with_skill": 6.5+ },+ "refusal_honesty": "4/4 (face blur, TTS narration, URL download, speech translation: all declined honestly, nearest alternative offered)",+ "japanese_report_for_japanese_prompt": "9/9",+ "report_format_followed": "20/24 (the 4 misses are refusal / probe-only answers where the Done/Look template does not apply)",+ "visual_check_when_picture_changed": "8/8",+ "findings": [+ "caption.py --text wrote the generated SRT next to the SOURCE file when -o pointed elsewhere; agents then had to explain a stray file. Now written next to the output.",+ "probe.py did not accept --json / the common flags although SKILL.md says every script does; agents retried. Now accepts them.",+ "audio.py --fade-out was applied to the music bed AND the whole mix (double fade on the last seconds). Split into --music-fade-out (bed only) and --fade-out (whole mix).",+ "Japanese caption prompts: agents did not know how to find a CJK font. SKILL.md now shows `fc-list :lang=ja file`.",+ "Not done in this iteration: 3 repeats per prompt and grading by an independent model. Grades are regex-based (evals/grade_runs_24.py) plus manual reading of every run.md."+ ],+ "grader": "evals/grade_runs_24.py",+ "prompts_file": "evals/agent_prompts_24.json"+}\ No newline at end of filediff --git a/package.json b/package.jsonindex 9b95f3b..f65556a 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "ffmpeg-skill",- "version": "0.8.1",+ "version": "0.8.2","description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: MCP server, batch processing, declarative project rendering, brand kits, motion-graphics templates, HTML delivery reports, scene detection, delivery checks, cut, silence removal, transitions, multicam, captions, sync with drift correction, HDR to SDR, LUTs, audio clean-up and ducking, loudness, platform exports. No API keys, no cloud, no dependencies.","keywords": ["ffmpeg", "video", "agent-skill", "claude-code", "cursor", "codex", "skill", "video-editing"],"license": "MIT",@@ -25,6 +25,7 @@],"scripts": {"test": "python3 tests/test_all.py",+ "release-check": "bash tests/release_check.sh","demo": "bash examples/make_demo.sh"},"engines": {diff --git a/scripts/audio.py b/scripts/audio.pyindex 9dd2498..352c041 100755--- a/scripts/audio.py+++ b/scripts/audio.py@@ -6,7 +6,7 @@ Examples:python3 audio.py interview.mp4 --denoise # FFT noise reductionpython3 audio.py interview.mp4 --voice # highpass + de-esser + compressor + denoisepython3 audio.py talk.mp4 --music bed.mp3 --duck # music under speech, auto-ducked- python3 audio.py talk.mp4 --music bed.mp3 --music-volume -18 --fade-out 3+ python3 audio.py talk.mp4 --music bed.mp3 --music-volume -18 --music-fade-out 3 # bed fades, voice does notpython3 audio.py clip.mp4 --fade-in 0.5 --fade-out 1 --stereopython3 audio.py surround.mov --downmix # 5.1 -> stereo with proper centre/LFE weightspython3 audio.py clip.mp4 --replace narration.wav # swap the audio track entirely@@ -37,7 +37,8 @@ def main() -> int:music.add_argument("--music-loop", action="store_true", help="loop the music if shorter than the video")fades = ap.add_argument_group("fades / layout")fades.add_argument("--fade-in", type=float, default=0.0, help="seconds")- fades.add_argument("--fade-out", type=float, default=0.0, help="seconds")+ fades.add_argument("--fade-out", type=float, default=0.0, help="seconds; fades the whole final mix (voice included)")+ music.add_argument("--music-fade-out", type=float, default=0.0, help="seconds; fades only the music bed at the end, voice untouched")fades.add_argument("--stereo", action="store_true", help="force 2-channel output (mono is duplicated to both sides)")fades.add_argument("--mono", action="store_true", help="force 1-channel output")fades.add_argument("--downmix", action="store_true", help="downmix 5.1/7.1 to stereo using standard weights")@@ -90,8 +91,8 @@ def main() -> int:m = f"{idx}:a:0"idx += 1mfx = [f"volume={args.music_volume:g}dB", f"atrim=0:{dur:.3f}" if dur else "anull"]- if args.fade_out:- mfx.append(f"afade=t=out:st={max(0.0, dur - args.fade_out):.3f}:d={args.fade_out:g}")+ if args.music_fade_out and dur:+ mfx.append(f"afade=t=out:st={max(0.0, dur - args.music_fade_out):.3f}:d={args.music_fade_out:g}")graph.append(f"[{m}]{','.join(mfx)}[music]")if args.duck:graph.append("[main]asplit=2[mainA][sc]")diff --git a/scripts/caption.py b/scripts/caption.pyindex c272c31..b004fb0 100755--- a/scripts/caption.py+++ b/scripts/caption.py@@ -344,7 +344,14 @@ def main() -> int:args.text = Noneif args.text:cues = parse_text_cues(args.text, args.auto_seconds, args.gap)- srt_path = args.write_srt or os.path.splitext(args.text)[0] + ".srt"+ if args.write_srt:+ srt_path = args.write_srt+ elif args.input:+ # keep generated files next to the output, not in the user's source folder+ out_guess = args.output or default_output(args.input, "captioned")+ srt_path = os.path.splitext(out_guess)[0] + ".srt"+ else:+ srt_path = os.path.splitext(args.text)[0] + ".srt"write_srt(cues, srt_path)info(f"wrote {srt_path} ({len(cues)} cues)")if not args.input:diff --git a/scripts/check.py b/scripts/check.pyindex 4c7ac7b..8abda70 100755--- a/scripts/check.py+++ b/scripts/check.py@@ -86,12 +86,17 @@ def main() -> int:v, a = meta.get("video") or {}, meta.get("audio") or {}rows: List[Dict[str, Any]] = []+ JUDGEMENT = {"duration", "aspect", "loudness", "fps", "resolution"}+def row(name: str, status: str, value: Any, expect: Any, fix: str = "") -> None:- rows.append({"check": name, "status": status, "value": value, "expected": expect, "fix": fix})+ # "format" rows are safe to fix mechanically; "judgement" rows change the content+ # (what is cut, what is cropped, how loud ambience gets) and need a decision+ rows.append({"check": name, "status": status, "value": value, "expected": expect, "fix": fix,+ "kind": "judgement" if name in JUDGEMENT else "format"})dur = meta.get("duration") or 0.0if spec["max_duration"]:- row("duration", "PASS" if dur <= spec["max_duration"] else "FAIL", f"{dur:.2f}s", f"<= {spec['max_duration']:g}s", "fit.py --duration N or cut.py")+ row("duration", "PASS" if dur <= spec["max_duration"] else "FAIL", f"{dur:.2f}s", f"<= {spec['max_duration']:g}s", "decide with the user: cut.py keeps quality but drops content; fit.py --duration speeds up (audio pitch-preserved, motion faster)")else:row("duration", "PASS", f"{dur:.2f}s", "any")@@ -101,7 +106,7 @@ def main() -> int:w, h = h, wasp = aspect_name(w, h)if spec["aspects"]:- row("aspect", "PASS" if asp in spec["aspects"] else "FAIL", asp, "/".join(spec["aspects"]), f"fit.py --aspect {spec['aspects'][0]} --fit pad|crop")+ row("aspect", "PASS" if asp in spec["aspects"] else "FAIL", asp, "/".join(spec["aspects"]), f"fit.py --aspect {spec['aspects'][0]} --fit pad (keeps everything, adds bars) or crop (fills the frame, loses the edges: check the subject with look.py)")else:row("aspect", "PASS", asp, "any")short = min(w, h)@@ -109,7 +114,7 @@ def main() -> int:row("resolution", "PASS" if short >= spec["min_height"] else "WARN", f"{w}x{h}", f"short side >= {spec['min_height']}", "upscaling will not add detail; re-export from the master")fps = v.get("fps") or 0if spec["fps_max"]:- row("fps", "PASS" if fps <= spec["fps_max"] + 0.01 else "FAIL", f"{fps:g}", f"<= {spec['fps_max']}", "fit.py --fps 30")+ row("fps", "PASS" if fps <= spec["fps_max"] + 0.01 else "FAIL", f"{fps:g}", f"<= {spec['fps_max']}", "fit.py --fps 30 (drops half the frames of 60 fps motion; fine for talking heads, visible on sports/gaming)")row("vfr", "PASS" if not v.get("variable_frame_rate_suspected") else "WARN", "variable" if v.get("variable_frame_rate_suspected") else "constant", "constant", "fit.py --fps N (any re-encode conforms it)")if spec["codecs"]:row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + args.platform.replace("shorts", "reels").replace("tiktok", "reels").replace("linkedin", "youtube"))@@ -143,7 +148,7 @@ def main() -> int:lm = measure_loudness(args.input)if lm:diff = abs(lm["lufs"] - spec["lufs"])- row("loudness", "PASS" if diff <= spec["lufs_tol"] else "FAIL", f"{lm['lufs']:.1f} LUFS", f"{spec['lufs']:g} ± {spec['lufs_tol']:g} LUFS", f"loudness.py -I {spec['lufs']:g}")+ row("loudness", "PASS" if diff <= spec["lufs_tol"] else "FAIL", f"{lm['lufs']:.1f} LUFS", f"{spec['lufs']:g} ± {spec['lufs_tol']:g} LUFS", f"loudness.py -I {spec['lufs']:g} for speech or music; leave ambience/near-silence (<= -40 LUFS) alone and say so")row("true peak", "PASS" if lm["tp"] <= spec["tp"] + 0.05 else "FAIL", f"{lm['tp']:.1f} dBTP", f"<= {spec['tp']:g} dBTP", f"loudness.py --tp {spec['tp']:g}")elif args.platform in ("podcast",):row("audio", "FAIL", "none", "audio stream", "audio.py --replace")@@ -157,6 +162,8 @@ def main() -> int:print(f"{args.input} — {args.platform}")for r in rows:line = f" {r['status']:4s} {r['check']:{width}s} {r['value']} (expected {r['expected']})"+ if r["status"] != "PASS" and r["kind"] == "judgement":+ line += " [judgement]"if r["status"] != "PASS" and r["fix"]:line += f" -> {r['fix']}"print(line)diff --git a/scripts/probe.py b/scripts/probe.pyindex 4ea2df5..6c07dbc 100755--- a/scripts/probe.py+++ b/scripts/probe.py@@ -12,7 +12,7 @@ Examples:import argparseimport sys-from _common import analyze_levels, print_json, probe+from _common import add_common, analyze_levels, apply_common, print_json, probedef main() -> int:@@ -21,7 +21,9 @@ def main() -> int:ap.add_argument("--compact", action="store_true", help="one human-readable line per file instead of JSON")ap.add_argument("--field", help="print only this top-level field (e.g. duration) or dotted path (video.fps)")ap.add_argument("--analyze", action="store_true", help="also sample picture levels (first 20 s) and flag Log-looking footage")+ add_common(ap) # --json / --dry-run / --fast / --progress accepted for uniformity; output is JSON alreadyargs = ap.parse_args()+ apply_common(args)results = [probe(p) for p in args.inputs]if args.analyze:diff --git a/scripts/render.py b/scripts/render.pyindex d179045..dc5c172 100755--- a/scripts/render.py+++ b/scripts/render.py@@ -24,7 +24,7 @@ Project format (all keys optional except clips):{"logo": true},{"text": "Episode 12", "position": "bottom", "start": 1, "end": 5, "fade": 0.3, "box": true}],- "audio": {"voice": true, "music": "bed.mp3", "music_volume": -16, "duck": true, "fade_out": 2},+ "audio": {"voice": true, "music": "bed.mp3", "music_volume": -16, "duck": true, "music_fade_out": 2},"loudness": {"lufs": -14, "tp": -1},"fit": {"duration": 60},"export": {"preset": "reels"},@@ -289,7 +289,7 @@ def main() -> int:for k, flag in (("music", "--music"), ("replace", "--replace")):if au.get(k):argv += [flag, rel(au[k])]- for k, flag in (("music_volume", "--music-volume"), ("fade_in", "--fade-in"), ("fade_out", "--fade-out"), ("gain", "--gain"), ("duck_amount", "--duck-amount")):+ for k, flag in (("music_volume", "--music-volume"), ("fade_in", "--fade-in"), ("fade_out", "--fade-out"), ("music_fade_out", "--music-fade-out"), ("gain", "--gain"), ("duck_amount", "--duck-amount")):if au.get(k) is not None:argv += [flag, str(au[k])]for k, flag in (("voice", "--voice"), ("denoise", "--denoise"), ("duck", "--duck"), ("music_loop", "--music-loop"), ("stereo", "--stereo"), ("mono", "--mono"), ("downmix", "--downmix")):diff --git a/tests/release_check.sh b/tests/release_check.shnew file mode 100755index 0000000..b8b682a--- /dev/null+++ b/tests/release_check.sh@@ -0,0 +1,48 @@+#!/usr/bin/env bash+# Pre-release smoke test. Run before `npm publish`; exits non-zero on any problem.+# 1. the packed tarball contains SKILL.md, scripts/, references/, mcp/, bin/+# 2. the tarball installs via the real installer into a temp HOME+# 3. every installed script answers --help+# 4. the MCP server lists tools+# 5. (optional, --corpus) tests/corpus.py --expect --quick on downloaded real files+set -euo pipefail+ROOT="$(cd "$(dirname "$0")/.." && pwd)"+cd "$ROOT"+TMP="$(mktemp -d -t ffskill-release-XXXXXX)"+trap 'rm -rf "$TMP"' EXIT++echo "== 1. pack contents"+npm pack --pack-destination "$TMP" >/dev/null 2>&1+TGZ="$(ls "$TMP"/*.tgz)"+LIST="$(tar -tzf "$TGZ")"+for need in package/SKILL.md package/scripts/_common.py package/scripts/probe.py package/references/scripts.md package/references/devices.md package/mcp/server.py package/bin/install.js; do+ echo "$LIST" | grep -qx "$need" || { echo "FAIL: $need missing from the package"; exit 1; }+done+echo " ok ($(echo "$LIST" | wc -l | tr -d ' ') files)"++echo "== 2. install from the tarball into a temp HOME"+mkdir -p "$TMP/home" "$TMP/pkg"+tar -xzf "$TGZ" -C "$TMP/pkg"+HOME="$TMP/home" node "$TMP/pkg/package/bin/install.js" >/dev/null+for d in SKILL.md scripts references mcp; do+ [ -e "$TMP/home/.claude/skills/ffmpeg-skill/$d" ] || { echo "FAIL: $d not installed"; exit 1; }+done+echo " ok"++echo "== 3. every script answers --help"+for f in "$TMP"/home/.claude/skills/ffmpeg-skill/scripts/*.py; do+ case "$(basename "$f")" in _common.py) continue;; esac+ python3 "$f" --help >/dev/null 2>&1 || { echo "FAIL: $(basename "$f") --help"; exit 1; }+done+echo " ok"++echo "== 4. MCP server lists tools"+n="$(python3 "$TMP/home/.claude/skills/ffmpeg-skill/mcp/server.py" --list | wc -l | tr -d ' ')"+[ "$n" -ge 15 ] || { echo "FAIL: MCP server lists only $n tools"; exit 1; }+echo " ok ($n tools)"++if [ "${1:-}" = "--corpus" ]; then+ echo "== 5. real-device corpus (quick)"+ python3 tests/corpus.py --expect --verify --quick+fi+echo "release check passed: $(node -p "require('./package.json').version")"diff --git a/tests/test_all.py b/tests/test_all.pyindex b1691ee..7ee64b2 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -104,6 +104,10 @@ class FFmpegSkillTests(unittest.TestCase):compact = script("probe.py", self.src, "--compact").stdoutself.assertIn("1280x720", compact)+ def test_probe_accepts_common_flags(self):+ out = script("probe.py", self.src, "--json", "--field", "duration").stdout.strip()+ self.assertClose(float(out), 12.0, 0.1)+def test_probe_missing_file_fails(self):proc = script("probe.py", OUT / "nope.mp4", expect_fail=True)self.assertIn("not found", proc.stderr)@@ -166,6 +170,14 @@ class FFmpegSkillTests(unittest.TestCase):self.assertTrue(srt.exists())self.assertEqual(proc.stdout.strip(), str(srt))+ def test_caption_srt_lands_next_to_output_not_source(self):+ sub = OUT / "capdir"+ sub.mkdir(exist_ok=True)+ out = sub / "cap_side.mp4"+ script("caption.py", self.src, "--text", self.cues, "--preset", "veryfast", "-o", out)+ self.assertTrue((sub / "cap_side.srt").exists(), "SRT written beside the output")+ self.assertFalse((OUT / "source.srt").exists(), "no SRT dropped next to the source")+# ---------------------------------------------------------------- overlaydef test_overlay_image_and_text(self):out1 = OUT / "ov_img.mp4"@@ -303,8 +315,11 @@ class FFmpegSkillTests(unittest.TestCase):a = probe(str(out))["audio"]self.assertEqual(a["channels"], 2)out2 = OUT / "ducked.mp4"- proc = script("audio.py", self.src, "--music", self.long_ref, "--duck", "--fade-out", "2", "-o", out2)+ proc = script("audio.py", self.src, "--music", self.long_ref, "--duck", "--music-fade-out", "2", "-o", out2)self.assertIn("sidechaincompress", proc.stderr)+ self.assertEqual(proc.stderr.count("afade=t=out"), 1, "only the bed fades, not the whole mix")+ proc_mix = script("audio.py", self.src, "--fade-out", "1", "--dry-run")+ self.assertEqual(proc_mix.stderr.count("afade=t=out"), 1)self.assertClose(probe(str(out2))["duration"], 12.0, 0.2)out3 = OUT / "replaced.mp4"script("audio.py", self.src, "--replace", self.mic, "--stereo", "-o", out3)@@ -556,6 +571,10 @@ class FFmpegSkillTests(unittest.TestCase):script("export.py", self.src, "--preset", "reels", "--fit", "crop", "-o", reels)data = json.loads(script("check.py", reels, "--platform", "reels", "--json", expect_fail=True).stdout)names = {r["check"]: r["status"] for r in data["checks"]}+ kinds = {r["check"]: r["kind"] for r in data["checks"]}+ self.assertEqual(kinds["loudness"], "judgement")+ self.assertEqual(kinds["video codec"], "format")+ self.assertIn("ambience", [r["fix"] for r in data["checks"] if r["check"] == "loudness"][0])self.assertEqual(names["aspect"], "PASS")self.assertEqual(names["pixel format"], "PASS")self.assertEqual(names["loudness"], "FAIL", "unnormalised test tone is far from -14 LUFS")@@ -613,6 +632,7 @@ class FFmpegSkillTests(unittest.TestCase):}), encoding="utf-8")if not (OUT / "cues.txt").exists():(OUT / "cues.txt").write_text("0:00-0:03 Hello world\n", encoding="utf-8")+ (OUT / "render_final.mp4").unlink(missing_ok=True)plan = json.loads(script("render.py", proj, "--dry-run", "--json").stdout)self.assertTrue(plan["dry_run"])self.assertFalse((OUT / "render_final.mp4").exists())