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.

0.8.2: Phase 4 — judgement rows, look enforcement, release smoke, iteration-2 evals (#12)

kajisho5067d6a03e313
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 craft
The 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.md
index 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; for
anything 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 to
the 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 new
files 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 conta
noise, 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`.
## Gotchas
diff --git a/evals/agent_prompts_24.json b/evals/agent_prompts_24.json
new file mode 100644
index 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 file
diff --git a/evals/grade_runs_24.py b/evals/grade_runs_24.py
new file mode 100644
index 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.json
new file mode 100644
index 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 file
diff --git a/package.json b/package.json
index 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.py
index 9dd2498..352c041 100755
--- a/scripts/audio.py
+++ b/scripts/audio.py
@@ -6,7 +6,7 @@ Examples:
python3 audio.py interview.mp4 --denoise # FFT noise reduction
python3 audio.py interview.mp4 --voice # highpass + de-esser + compressor + denoise
python3 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 not
python3 audio.py clip.mp4 --fade-in 0.5 --fade-out 1 --stereo
python3 audio.py surround.mov --downmix # 5.1 -> stereo with proper centre/LFE weights
python3 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 += 1
mfx = [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.py
index c272c31..b004fb0 100755
--- a/scripts/caption.py
+++ b/scripts/caption.py
@@ -344,7 +344,14 @@ def main() -> int:
args.text = None
if 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.py
index 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.0
if 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, w
asp = 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 0
if 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.py
index 4ea2df5..6c07dbc 100755
--- a/scripts/probe.py
+++ b/scripts/probe.py
@@ -12,7 +12,7 @@ Examples:
import argparse
import sys
-from _common import analyze_levels, print_json, probe
+from _common import add_common, analyze_levels, apply_common, print_json, probe
def 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 already
args = 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.py
index 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.sh
new file mode 100755
index 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.py
index 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").stdout
self.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")
+
# ---------------------------------------------------------------- overlay
def 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())