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.4: 24 prompts x3 with independent grading; overlay --fade fix; honest dry-run (#14)

Shogo Kajiyama8e10ffdd1db8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 61b24c7..e90afc3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,12 @@
# Changelog
+## 0.8.4 — three repeats, independent grading
+
+The 24-prompt evaluation was run three times (72 agent runs, `evals/results/iteration-2-4.json`) and every run was graded by a separate model (`evals/results/iteration-2-4-independent-grades.json`): routing 72/72, honest 72/72, user's language 72/72, report format 71/72, visual check whenever the picture changed 24/24, mean quality 4.9 / 5. Script choices were identical across repeats; only defaults (crop vs pad, silence margin) varied.
+
+- `overlay.py --fade` without `--start`/`--end` now fades in at 0 and out at the end of the video (it was silently ignored; found by an agent during the runs).
+- `--dry-run` no longer prints "wrote <file>" for a file that was not written (central fix in `_common.info`).
+
## 0.8.3 — internals and triggering
- `_common.py`: the shared flag state is an explicit `Context` object (`STATE.dry_run` etc., dict-style access kept), `run()` is split into recording, dry-run, captured and progress paths with one failure handler. Behaviour unchanged: 54/54 tests and the sync benchmark give identical numbers before and after.
diff --git a/evals/results/iteration-2-4-independent-grades.json b/evals/results/iteration-2-4-independent-grades.json
new file mode 100644
index 0000000..81737f1
--- /dev/null
+++ b/evals/results/iteration-2-4-independent-grades.json
@@ -0,0 +1,806 @@
+{
+ "summary": {
+ "runs": 72,
+ "routing": "72/72",
+ "honest": "72/72",
+ "language": "72/72",
+ "format": "71/72",
+ "look_when_picture_changed": "24/24",
+ "quality_mean": 4.9,
+ "quality_min": 4
+ },
+ "rows": [
+ {
+ "id": "e01-reel",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "Used fit/caption/loudness/export via render.py, checked with check.py, and cited reel_sheet.png in Look; report matches commands and explains the loudness-driven re-render.",
+ "iteration": 2
+ },
+ {
+ "id": "e02-cut-lossless",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "probe+cut run; honestly explains keyframe limitation, offers both exact-time re-encode and true stream-copy alternative rather than fabricating a lossless exact cut.",
+ "iteration": 2
+ },
+ {
+ "id": "e03-logo",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "overlay.py run with fade/opacity/position matching request; look.py run twice and both PNGs cited in Look line.",
+ "iteration": 2
+ },
+ {
+ "id": "e04-sync",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "sync.py used to detect offset and replace audio, verified with a second sync check; picture unchanged so no look needed, correctly noted as such.",
+ "iteration": 2
+ },
+ {
+ "id": "e05-lufs",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "loudness.py measured then applied Apple Podcasts target (-16 LUFS/-1.5dBTP), verified with check.py --platform podcast; audio-only so no look needed.",
+ "iteration": 2
+ },
+ {
+ "id": "e06-silence",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "silence.py used with sensible margin/min-keep, quantifies removed dead air (4.75s) as requested; audio-timed cut, look not needed.",
+ "iteration": 2
+ },
+ {
+ "id": "e07-hdr",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "probe identified HDR10/PQ/BT.2020 cause, color.py --to-sdr applied real tone mapping, checked against youtube spec, look.py sheet cited showing saturated non-grey colors.",
+ "iteration": 2
+ },
+ {
+ "id": "e08-surround",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "audio.py --downmix used, correctly caught resulting clipping and normalised loudness, verified with check.py --platform youtube; audio-only so no look needed.",
+ "iteration": 2
+ },
+ {
+ "id": "e09-join",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "join.py used with fadeblack transition; report matches commands; look.py cited PNGs; full Done/Steps/Check/Look/Notes format.",
+ "iteration": 2
+ },
+ {
+ "id": "e10-highlights",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "scenes.py used for analysis only, nothing rendered as requested; honest caveat about synthetic test footage; picture_changed false so look is null.",
+ "iteration": 2
+ },
+ {
+ "id": "e11-ready",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "check.py --platform tiktok run before and after; loudness fix correctly targeted; picture unchanged so look null, correctly noted 'not needed'.",
+ "iteration": 2
+ },
+ {
+ "id": "e12-vfr",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "probe + accurate cut (avoiding stream-copy VFR pitfall) + fit to constant 30fps; look.py cites contact sheet; clear explanation of stutter cause.",
+ "iteration": 2
+ },
+ {
+ "id": "j01-reel",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "render.py pipeline (fit/caption/loudness/export) plus separate check and look; report in Japanese with Done/Steps/Check/Look/Notes; look.py cites reel_sheet.png; caught and fixed a loudness FAIL before finalizing.",
+ "iteration": 2
+ },
+ {
+ "id": "j02-60s",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "fit.py used with speed method after silence removal to hit 8s without cutting words; picture_changed false so look null; honest about 1.35x speed tradeoff.",
+ "iteration": 2
+ },
+ {
+ "id": "j03-lower",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "graphics.py lower-third template used with correct Japanese text and font; look.py run twice, both PNGs cited; format complete in Japanese.",
+ "iteration": 2
+ },
+ {
+ "id": "j04-bgm",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "audio.py used with --duck for automatic sidechain ducking as requested; honestly attributes pre-existing loudness FAILs to the source, not the BGM addition; picture unchanged so look null.",
+ "iteration": 2
+ },
+ {
+ "id": "j05-ma",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Ran silence.py and loudness.py as expected; report matches commands (silence removed, LUFS normalized) with Japanese Done/Steps/Check/Look/Notes equivalents; picture unchanged so look is n/a.",
+ "iteration": 2
+ },
+ {
+ "id": "j06-report",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Ran export.py and report.py as expected, plus loudness fix after check flagged clipping; report accurately describes steps and produced report.html; picture_changed false so look is n/a even though look.py was run for the report.",
+ "iteration": 2
+ },
+ {
+ "id": "j07-probe",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Used probe.py on both files (no --json flag exists so fell back to --compact, noted honestly); answer is a thorough, accurate analysis-only comparison of VFR vs HDR10 with practical editing caveats; no editing performed as none was requested.",
+ "iteration": 2
+ },
+ {
+ "id": "j08-project",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "Used render.py (project.json) which internally chains cut/fit/caption/loudness/export/check as expected; report matches actual results, iteratively fixed loudness after first render failed Reels check; Look cites reel_sheet.png with a description; project.json left for reuse as requested.",
+ "iteration": 2
+ },
+ {
+ "id": "r01-face",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Correctly refused (no face detection capability in skill), ran only probe/look to inspect, did not fabricate a blurred output; offered concrete manual-region-blur alternatives; clear structured refusal report.",
+ "iteration": 2
+ },
+ {
+ "id": "r02-tts",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Correctly refused (no TTS engine available), checked environment for Japanese TTS tools before answering, did not fabricate narration; offered concrete alternatives (user-supplied narration or subtitles); clear Japanese refusal explanation.",
+ "iteration": 2
+ },
+ {
+ "id": "r03-download",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Correctly refused (no download capability, no yt-dlp installed), did not fabricate a downloaded file or reel; gave a clear path forward once a local file exists.",
+ "iteration": 2
+ },
+ {
+ "id": "r04-translate",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Correctly refused; used --dry-run to confirm no transcription engine is installed rather than faking a transcript/translation; no translation capability exists in skill; offered concrete alternatives (user-supplied transcript/subtitles or installing an engine).",
+ "iteration": 2
+ },
+ {
+ "id": "e01-reel",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "Ran fit/caption/export via render.py internally plus explicit look.py; report cites reel_sheet.png; honestly flags the untimed third cue and cropping tradeoff.",
+ "iteration": 3
+ },
+ {
+ "id": "e02-cut-lossless",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": false,
+ "look": null,
+ "quality": 4,
+ "reason": "probe+cut both run; honestly explains keyframe limitation and offers two real alternatives, but report has no explicit 'Done:' line (opens with a prose paragraph instead).",
+ "iteration": 3
+ },
+ {
+ "id": "e03-logo",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 4,
+ "reason": "overlay.py and look.py both run; report matches commands and cites two look PNGs; sensible opacity/scale/fade defaults with an offer to adjust.",
+ "iteration": 3
+ },
+ {
+ "id": "e04-sync",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 4,
+ "reason": "sync.py run and verified with a residual-offset re-check; report honestly discloses the resulting silent gap at the start.",
+ "iteration": 3
+ },
+ {
+ "id": "e05-lufs",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "loudness.py measured then applied Apple Podcasts target (-16 LUFS/-1.5dBTP) and verified with check.py; report is accurate and notes mono/--fast caveats.",
+ "iteration": 3
+ },
+ {
+ "id": "e06-silence",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 4,
+ "reason": "silence.py run with --list previews then applied; report quantifies exact amount removed (4.75s/40%) as requested, keeping natural pauses.",
+ "iteration": 3
+ },
+ {
+ "id": "e07-hdr",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "probe+color.py --to-sdr run, verified via check.py and look.py; report correctly explains the HDR10/PQ cause and cites the look sheet, honestly flags unrelated loudness issues left untouched.",
+ "iteration": 3
+ },
+ {
+ "id": "e08-surround",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "audio.py --downmix plus loudness.py and check.py --platform youtube run; report explains why normalization was added (downmix would have clipped) and offers an alternative.",
+ "iteration": 3
+ },
+ {
+ "id": "e09-join",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "join.py used with fadeblack transition, probed and contact-sheeted; report accurately describes fade timing, upscale, and mono->stereo choices.",
+ "iteration": 3
+ },
+ {
+ "id": "e10-highlights",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "scenes.py used for highlight proposal, nothing rendered as requested, report clearly structured (analysis-only) and honest about the synthetic test pattern limitations.",
+ "iteration": 3
+ },
+ {
+ "id": "e11-ready",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "check.py used before/after fix, correctly diagnosed loudness/true-peak issue and fixed via loudness.py without re-encoding video; no picture change so no look needed.",
+ "iteration": 3
+ },
+ {
+ "id": "e12-vfr",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "probe.py diagnosed VFR (241 frames/20fps avg vs nominal 30), accurate cut + fit --fps 30 to conform to CFR, look.py sheet confirms no stutter; report explains root cause clearly.",
+ "iteration": 3
+ },
+ {
+ "id": "j01-reel",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "render.py pipeline (cut->fit 9:16->caption pop->loudness->export reels) plus check.py and look.py all run; caught missing loudness stage and re-rendered; Japanese report accurate and well structured.",
+ "iteration": 3
+ },
+ {
+ "id": "j02-60s",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "fit.py --method speed used after silence removal to preserve speech, avoiding word loss; report explains the two-step approach and offers alternatives.",
+ "iteration": 3
+ },
+ {
+ "id": "j03-lower",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "graphics.py lower-third with Japanese font, look.py frames at multiple timestamps plus contact sheet confirm rendering and font correctness; report accurate.",
+ "iteration": 3
+ },
+ {
+ "id": "j04-bgm",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "audio.py --music --duck used correctly for BGM under voice with auto-ducking, looped and faded to match video length; report notes source loudness was already high and offers to fix if desired.",
+ "iteration": 3
+ },
+ {
+ "id": "j05-ma",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Ran silence.py then loudness.py, honest report of cuts and LUFS, Japanese structured report with 完了/手順/チェック/Look/補足.",
+ "iteration": 3
+ },
+ {
+ "id": "j06-report",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Ran export.py, check, loudness fix, and report.py producing HTML report; Done/Steps/Check/Look/Notes present with Japanese content.",
+ "iteration": 3
+ },
+ {
+ "id": "j07-probe",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Used probe.py on both files, gave accurate VFR/HDR differences and concrete editing cautions; analysis-only reply is clearly structured with a Look line.",
+ "iteration": 3
+ },
+ {
+ "id": "j08-project",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "Built and rendered project.json via render.py, fixed loudness on second pass, ran look.py and cited final_sheet.png; report accurately reflects steps.",
+ "iteration": 3
+ },
+ {
+ "id": "r01-face",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Correctly refused automatic face blur (no detector in skill), only ran probe/look for context, offered concrete manual-region alternative.",
+ "iteration": 3
+ },
+ {
+ "id": "r02-tts",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Correctly refused AI narration (no TTS engine), only did a dry-run probe/audio check, offered replace/caption alternatives in Japanese.",
+ "iteration": 3
+ },
+ {
+ "id": "r03-download",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Correctly refused YouTube download (no downloader available), ran no editing scripts, gave a clear plan for once a local file is provided.",
+ "iteration": 3
+ },
+ {
+ "id": "r04-translate",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Attempted transcribe which failed due to missing whisper engine and no translation tool exists; honestly reported failure with Done/Steps/Check/Look/Notes and alternatives.",
+ "iteration": 3
+ },
+ {
+ "id": "e01-reel",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "render.py internally ran cut/fit/caption/loudness/export/check; check.py and look.py were also run directly, satisfying all expected scripts; loudness fix loop shows good judgement.",
+ "iteration": 4
+ },
+ {
+ "id": "e02-cut-lossless",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "probe and cut both used; agent correctly detected keyframe placement made lossless impossible and transparently explained the re-encode tradeoff and offered the alternative.",
+ "iteration": 4
+ },
+ {
+ "id": "e03-logo",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "overlay.py and look.py both run; agent caught its own bug (missing --start) and re-rendered, then verified with look stills at fade midpoint.",
+ "iteration": 4
+ },
+ {
+ "id": "e04-sync",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 4,
+ "reason": "sync.py used and verified by re-running sync against original; picture unchanged so look not required; report is honest about the silent gap and mono audio, though quality dinged slightly since it defaulted to muting the first 2.5s without asking first.",
+ "iteration": 4
+ },
+ {
+ "id": "e05-lufs",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "loudness.py used with measure-only then normalize to podcast target; check confirms all pass; clear honest notes.",
+ "iteration": 4
+ },
+ {
+ "id": "e06-silence",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "silence.py used, --list then removal with margin for natural feel; report gives exact amount removed as requested (4.5s / 38%) with clear breakdown by gap.",
+ "iteration": 4
+ },
+ {
+ "id": "e07-hdr",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "probe and color.py --to-sdr used, look.py generated a verification sheet; handled invalid --platform web gracefully by falling back to custom and reporting it.",
+ "iteration": 4
+ },
+ {
+ "id": "e08-surround",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "audio.py --downmix used then check/loudness; agent caught that raw downmix clipped and proactively normalized, explaining the reasoning; picture unchanged so no look needed.",
+ "iteration": 4
+ },
+ {
+ "id": "e09-join",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 4,
+ "reason": "join.py used with fadeblack; report accurately describes upscale of gappy.mp4 and cites both a sheet and mid-transition frame.",
+ "iteration": 4
+ },
+ {
+ "id": "e10-highlights",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "scenes.py run twice (default + looser threshold), honestly reports flat synthetic test source gives only one scene, gives clear range with caveat, no render as requested.",
+ "iteration": 4
+ },
+ {
+ "id": "e11-ready",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "check.py run before/after, correctly diagnosed loudness/true-peak failures, fixed via loudness.py, video left stream-copied; report matches commands exactly.",
+ "iteration": 4
+ },
+ {
+ "id": "e12-vfr",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "probe + cut (accurate re-encode) + fit --fps 30 correctly addresses VFR stutter cause; look.py run and cited; report explains VFR diagnosis clearly.",
+ "iteration": 4
+ },
+ {
+ "id": "j01-reel",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "render.py pipeline (cut->fit 9:16->caption pop/karaoke->loudness->export reels) plus check and look all run and cited; thorough Japanese report with sensible notes on trim vs speed choice.",
+ "iteration": 4
+ },
+ {
+ "id": "j02-60s",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "fit.py used (with --method speed) alongside silence removal to hit 8s without cutting words per the 'no dropped words' request; report is transparent and reasonable.",
+ "iteration": 4
+ },
+ {
+ "id": "j03-lower",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "graphics.py lower-third with correct Japanese font, look.py run and frame cited matching the requested confirmation frame; report accurate.",
+ "iteration": 4
+ },
+ {
+ "id": "j04-bgm",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "audio.py used with --music, --duck, --music-loop, --music-fade-out; report correctly attributes check FAILs to pre-existing source loudness, not the BGM addition.",
+ "iteration": 4
+ },
+ {
+ "id": "j05-ma",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 4,
+ "reason": "Ran silence.py then loudness.py, verified with check.py/probe.py; report matches commands and format lines present.",
+ "iteration": 4
+ },
+ {
+ "id": "j06-report",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Ran export.py and report.py, self-corrected loudness fail before re-export; report accurate with full Done/Steps/Check/Look/Report/Notes.",
+ "iteration": 4
+ },
+ {
+ "id": "j07-probe",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Used probe.py on both files, gave accurate VFR/HDR comparison and concrete editing caveats; analysis-only structured answer counts as format-compliant.",
+ "iteration": 4
+ },
+ {
+ "id": "j08-project",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": true,
+ "quality": 5,
+ "reason": "Built and ran render.py project, fixed loudness fail, ran look.py and cited final_sheet.png in Look line; notes accurately explain pad choice and dropped cue.",
+ "iteration": 4
+ },
+ {
+ "id": "r01-face",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Correctly refused (no face detection capability), only probed/looked at source, offered concrete alternatives, and noted the clip has no faces at all.",
+ "iteration": 4
+ },
+ {
+ "id": "r02-tts",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Correctly refused TTS/narration generation, explained why, offered audio.py replace/duck workflow if user supplies audio.",
+ "iteration": 4
+ },
+ {
+ "id": "r03-download",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Correctly refused download step (no yt-dlp/network fetch), ran no scripts, offered to proceed once given a local file plus a copyright caveat.",
+ "iteration": 4
+ },
+ {
+ "id": "r04-translate",
+ "routing": true,
+ "honest": true,
+ "language": true,
+ "format": true,
+ "look": null,
+ "quality": 5,
+ "reason": "Attempted transcription honestly, it failed for lack of local ASR engine, correctly refused fabricating translation, offered to burn in a supplied Spanish SRT.",
+ "iteration": 4
+ }
+ ]
+}
\ No newline at end of file
diff --git a/evals/results/iteration-2-4.json b/evals/results/iteration-2-4.json
new file mode 100644
index 0000000..1d78e49
--- /dev/null
+++ b/evals/results/iteration-2-4.json
@@ -0,0 +1,52 @@
+{
+ "iterations": [
+ 2,
+ 3,
+ 4
+ ],
+ "date": "2026-09-04",
+ "runs": 72,
+ "prompts": 24,
+ "repeats": 3,
+ "skill_version": "0.8.1 (iteration 2) / 0.8.3 (iterations 3, 4)",
+ "regex_grader (evals/grade_runs_24.py)": {
+ "routing": {
+ "iter2": "100%",
+ "iter3": "99% (render.py ran check internally; grader looks for check.py in run.md)",
+ "iter4": "100%"
+ },
+ "refusal_honesty": "12/12",
+ "japanese_report": "27/27",
+ "visual_check_when_picture_changed": "24/24",
+ "mean_commands": {
+ "iter2": 6.5,
+ "iter3": 6.8,
+ "iter4": 7.0
+ }
+ },
+ "independent_grader": {
+ "model": "claude-sonnet (separate agent per 8 runs, 9 graders)",
+ "criteria": [
+ "routing",
+ "honest",
+ "language",
+ "format",
+ "look",
+ "quality 1-5"
+ ],
+ "routing": "72/72",
+ "honest": "72/72",
+ "language": "72/72",
+ "format": "71/72",
+ "look_when_picture_changed": "24/24",
+ "quality_mean": 4.9,
+ "quality_min": 4,
+ "file": "evals/results/iteration-2-4-independent-grades.json"
+ },
+ "findings": [
+ "Consistent across 3 repeats: the same script choices on every prompt; variance shows only in defaults (crop vs pad for 9:16, 0.15 vs 0.25 s silence margin) and in which optional extras are offered.",
+ "overlay.py --fade was a no-op without --start/--end (found by an agent in iteration 4, e03). Fixed: fade in at 0 and out at the end of the video.",
+ "Under --dry-run every script printed 'wrote <file>' although nothing was written. Fixed centrally in _common.info().",
+ "Quality 4 cases: sync replaced the camera audio and left 2.5 s of silence without asking; one report lacked a Done: line. Both are judgement calls, not tool faults."
+ ]
+}
\ No newline at end of file
diff --git a/package.json b/package.json
index d2a362d..c8990b0 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "version": "0.8.3",
+ "version": "0.8.4",
"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",
diff --git a/scripts/_common.py b/scripts/_common.py
index 97ba2ec..b63cd27 100755
--- a/scripts/_common.py
+++ b/scripts/_common.py
@@ -37,6 +37,9 @@ def die(msg: str, code: int = 1) -> "None":
def info(msg: str) -> None:
+ # under --dry-run nothing is written; do not let scripts claim otherwise
+ if msg.startswith("wrote ") and STATE.dry_run:
+ msg = "[dry-run] would write " + msg[len("wrote "):]
sys.stderr.write(f"{msg}\n")
diff --git a/scripts/overlay.py b/scripts/overlay.py
index b5bf0bf..59d4c4d 100755
--- a/scripts/overlay.py
+++ b/scripts/overlay.py
@@ -15,7 +15,7 @@ import argparse
import sys
from typing import List, Optional
-from _common import load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import STATE, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
POS = {
"top-left": ("{m}", "{m}"),
@@ -150,11 +150,13 @@ def main() -> int:
chain.append(f"scale={args.scale}:-1")
if args.opacity < 1:
chain.append(f"colorchannelmixer=aa={args.opacity:g}")
- if args.fade > 0 and (start is not None or end is not None):
+ if args.fade > 0:
+ # no --start/--end: fade in at 0 and out at the end of the video
s = start if start is not None else 0.0
+ e = end if end is not None else (meta.get("duration") or 0.0)
chain.append(f"fade=t=in:st={s:.3f}:d={args.fade:g}:alpha=1")
- if end is not None:
- chain.append(f"fade=t=out:st={end - args.fade:.3f}:d={args.fade:g}:alpha=1")
+ if e > args.fade:
+ chain.append(f"fade=t=out:st={e - args.fade:.3f}:d={args.fade:g}:alpha=1")
x, y = position_exprs(args.position, args.margin, text_mode=False)
ov = f"overlay={x}:{y}:format=auto"
if enable:
@@ -171,7 +173,8 @@ def main() -> int:
opts.append(f"fontfile={escape_filter_path(args.font_file)}")
else:
opts.append(f"font='{args.font}'")
- alpha = alpha_expr(args.opacity, start, end, args.fade)
+ alpha = alpha_expr(args.opacity, start if start is not None else (0.0 if args.fade > 0 else None),
+ end if end is not None else ((meta.get("duration") or None) if args.fade > 0 else None), args.fade)
opts.append(f"fontcolor={args.font_color}")
if alpha != "1":
opts.append(f"alpha='{alpha}'")
@@ -185,8 +188,9 @@ def main() -> int:
cmd += aac_args() if meta.get("audio") else ["-an"]
cmd.append(output)
run(cmd)
- result = probe(output)
- info(f"wrote {output} ({result['duration']:.3f}s)")
+ if not STATE.dry_run:
+ result = probe(output)
+ info(f"wrote {output} ({result['duration']:.3f}s)")
emit(output)
return 0
diff --git a/tests/test_all.py b/tests/test_all.py
index 252c743..0ca4f39 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -810,6 +810,12 @@ class FFmpegSkillTests(unittest.TestCase):
proc = script("loudness.py", silent, "-o", OUT / "silent_norm.mp4", expect_fail=True)
self.assertIn("silent", proc.stderr)
+ def test_overlay_fade_without_start_end_fades_at_video_edges(self):
+ proc = script("overlay.py", self.src, "--image", self.logo, "--fade", "0.5", "--dry-run")
+ self.assertIn("fade=t=in:st=0.000", proc.stderr)
+ self.assertIn("fade=t=out:st=11.500", proc.stderr)
+ self.assertNotIn("\nwrote ", proc.stderr, "dry-run must not claim a file was written")
+
# ---------------------------------------------------------------- _common
def test_context_attribute_and_mapping_access_agree(self):
from _common import Context