ffmpeg-skill 0.8.1 → 0.8.2

package/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
 

package/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": {

package/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]")

package/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:

package/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)

package/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:

package/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")):