ffmpeg-skill 0.8.1 → 0.8.3

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.3",
   "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/_common.py

@@ -56,7 +56,46 @@ def require_tool(name: str) -> str:
 
 
 X264_PRESETS = ("ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow", "placebo")
-STATE: Dict[str, Any] = {"dry_run": False, "json": False, "commands": [], "progress": False, "fast": False, "duration_hint": None}
+
+
+class Context:
+    """Per-process settings that the shared flags (--dry-run, --json, --progress, --fast) set once.
+
+    Scripts read it as attributes (``STATE.dry_run``) or, for older call sites, like a dict
+    (``STATE["dry_run"]``). Keeping it a single explicit object rather than module globals makes
+    it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
+    """
+
+    __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands")
+    _KEYS = ("dry_run", "json", "progress", "fast", "duration_hint", "commands")
+
+    def __init__(self) -> None:
+        self.reset()
+
+    def reset(self) -> None:
+        self.dry_run = False      # print ffmpeg commands, run nothing (ffprobe still runs)
+        self.json = False         # emit() prints a JSON document instead of the output path
+        self.progress = False     # run() streams percent / ETA to stderr for ffmpeg
+        self.fast = False         # x264 preset forced to veryfast
+        self.duration_hint: Optional[float] = None  # expected output length, for the progress percent
+        self.commands: List[str] = []               # every ffmpeg command line, for --json and --dry-run
+
+    # mapping-style access kept for backwards compatibility
+    def __getitem__(self, key: str) -> Any:
+        if key not in self._KEYS:
+            raise KeyError(key)
+        return getattr(self, key)
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        if key not in self._KEYS:
+            raise KeyError(key)
+        setattr(self, key, value)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return getattr(self, key, default) if key in self._KEYS else default
+
+
+STATE = Context()
 
 
 def add_common(ap: "argparse.ArgumentParser") -> None:
@@ -69,19 +108,19 @@ def add_common(ap: "argparse.ArgumentParser") -> None:
 
 
 def apply_common(args: "argparse.Namespace") -> None:
-    STATE["dry_run"] = bool(getattr(args, "dry_run", False))
-    STATE["json"] = bool(getattr(args, "json", False))
-    STATE["progress"] = bool(getattr(args, "progress", False))
-    STATE["fast"] = bool(getattr(args, "fast", False))
-    if STATE["fast"] and getattr(args, "preset", None) in X264_PRESETS:
+    STATE.dry_run = bool(getattr(args, "dry_run", False))
+    STATE.json = bool(getattr(args, "json", False))
+    STATE.progress = bool(getattr(args, "progress", False))
+    STATE.fast = bool(getattr(args, "fast", False))
+    if STATE.fast and getattr(args, "preset", None) in X264_PRESETS:
         args.preset = "veryfast"
 
 
 def emit(output: Optional[str], **extra: Any) -> None:
     """Final stdout line: the output path, or a JSON document with --json."""
-    if STATE["json"]:
-        doc: Dict[str, Any] = {"output": output, "dry_run": STATE["dry_run"], "commands": list(STATE["commands"])}
-        if output and not STATE["dry_run"] and os.path.exists(output):
+    if STATE.json:
+        doc: Dict[str, Any] = {"output": output, "dry_run": STATE.dry_run, "commands": list(STATE.commands)}
+        if output and not STATE.dry_run and os.path.exists(output):
             doc["probe"] = probe(output)
         doc.update(extra)
         print_json(doc)
@@ -89,32 +128,58 @@ def emit(output: Optional[str], **extra: Any) -> None:
         print(output)
 
 
+def _cmdline(cmd: Sequence[str]) -> str:
+    return " ".join(shell_quote(c) for c in cmd)
+
+
+def _is_ffmpeg(cmd: Sequence[str]) -> bool:
+    return os.path.basename(cmd[0]).startswith("ffmpeg")
+
+
+def _fail(cmd: Sequence[str], returncode: int, stderr: str) -> None:
+    tail = "\n".join(stderr.strip().splitlines()[-15:])
+    die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=returncode or 1)
+
+
 def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:
     """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.
 
-    With --dry-run, ffmpeg invocations are printed and skipped (ffprobe still runs so
-    scripts can plan); a fake successful CompletedProcess is returned.
+    ffmpeg invocations are recorded in STATE.commands (for --json), skipped under --dry-run
+    (a fake successful CompletedProcess is returned so scripts can keep planning), and run
+    with a progress readout under --progress. ffprobe and other tools always run.
     """
-    is_ffmpeg = os.path.basename(cmd[0]).startswith("ffmpeg")
+    is_ffmpeg = _is_ffmpeg(cmd)
     if is_ffmpeg:
-        STATE["commands"].append(" ".join(shell_quote(c) for c in cmd))
+        STATE.commands.append(_cmdline(cmd))
     if not quiet:
-        info(("[dry-run] $ " if STATE["dry_run"] and is_ffmpeg else "$ ") + " ".join(shell_quote(c) for c in cmd))
-    if STATE["dry_run"] and is_ffmpeg:
+        info(("[dry-run] $ " if STATE.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd))
+    if STATE.dry_run and is_ffmpeg:
         return subprocess.CompletedProcess(list(cmd), 0, "", "")
-    if STATE["progress"] and is_ffmpeg and cmd[-1] != "-":
+    if STATE.progress and is_ffmpeg and cmd[-1] != "-":
         return _run_with_progress(list(cmd), check)
+    return _run_captured(list(cmd), check)
+
+
+def _run_captured(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
+    """Plain run with stdout/stderr captured."""
     proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
     if check and proc.returncode != 0:
-        tail = "\n".join(proc.stderr.strip().splitlines()[-15:])
-        die(f"command failed ({proc.returncode}): {cmd[0]}\n{tail}", code=proc.returncode or 1)
+        _fail(cmd, proc.returncode, proc.stderr)
     return proc
 
 
+def _progress_line(done: float, total: float, elapsed: float) -> str:
+    if total > 0:
+        pct = min(99.9, done / total * 100)
+        eta = (elapsed / pct * (100 - pct)) if pct > 0.5 else 0
+        return f"\r  {pct:5.1f}%  {done:7.1f}s / {total:.1f}s  ETA {eta:4.0f}s"
+    return f"\r  {done:7.1f}s encoded"
+
+
 def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
     """Run ffmpeg with -progress on a pipe and print percent/ETA to stderr."""
     import time
-    total = STATE.get("duration_hint") or 0.0
+    total = STATE.duration_hint or 0.0
     full = cmd[:1] + ["-progress", "pipe:1", "-nostats"] + cmd[1:]
     t0 = time.time()
     proc = subprocess.Popen(full, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
@@ -126,13 +191,7 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
                 done = int(line.split("=")[1]) / 1_000_000
             except ValueError:
                 continue
-            if total > 0:
-                pct = min(99.9, done / total * 100)
-                elapsed = time.time() - t0
-                eta = (elapsed / pct * (100 - pct)) if pct > 0.5 else 0
-                msg = f"\r  {pct:5.1f}%  {done:7.1f}s / {total:.1f}s  ETA {eta:4.0f}s"
-            else:
-                msg = f"\r  {done:7.1f}s encoded"
+            msg = _progress_line(done, total, time.time() - t0)
             if msg != last:
                 sys.stderr.write(msg)
                 sys.stderr.flush()
@@ -140,11 +199,9 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
     _, err = proc.communicate()
     if last:
         sys.stderr.write("\r" + " " * len(last) + "\r")
-    result = subprocess.CompletedProcess(full, proc.returncode, "", err)
     if check and proc.returncode != 0:
-        tail = "\n".join(err.strip().splitlines()[-15:])
-        die(f"command failed ({proc.returncode}): {cmd[0]}\n{tail}", code=proc.returncode or 1)
-    return result
+        _fail(cmd, proc.returncode, err)
+    return subprocess.CompletedProcess(full, proc.returncode, "", err)
 
 
 def shell_quote(s: str) -> str:

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

package/scripts/sync.py

@@ -30,6 +30,22 @@ from _common import video_args, add_common, apply_common, emit, aac_args, audio_
 
 SR = 8000  # decode sample rate
 
+# Scoring constants for coarse alignment. Both come from tests/bench_sync.py on real dialogue and
+# music with +/-30 s offsets, gain, noise and EQ (see evals/results and CHANGELOG 0.8.0):
+#
+# MIN_OVERLAP_FRACTION: lags whose overlap with the other track is shorter than this share of the
+#   shorter track are never candidates. With the documented rule "analysis window >= 4x the largest
+#   expected offset" a true offset keeps >= 75 % overlap, so 0.35 costs nothing there, while the
+#   coincidental peaks on quasi-periodic material (music, tone beds) live below it. Raising it to
+#   0.5 started rejecting true 28 s offsets in 60 s windows; lowering it to 0.2 let the partial
+#   matches back in (86 % -> 95 % of 60 s stress cases fixed by this alone).
+# OVERLAP_WEIGHT_EXP: normalised similarity is multiplied by (overlap fraction) ** exponent so a
+#   perfect match over 55 % of the window cannot tie a perfect match over 100 %. 0.5 keeps a true
+#   75 % overlap at x0.87 and a 53 % one (28 s in 60 s) at x0.73 while a coincidental 40 % match
+#   drops to x0.63; exponent 1.0 over-penalised large true offsets, 0.25 left exact ties.
+MIN_OVERLAP_FRACTION = 0.35
+OVERLAP_WEIGHT_EXP = 0.5
+
 
 def decode_mono(path: str, seconds: float, start: float = 0.0) -> List[float]:
     ffmpeg = require_tool("ffmpeg")
@@ -119,10 +135,7 @@ def cross_correlate(ref: List[float], other: List[float], max_lag: int):
     lr, lo = len(ref), len(other)
     max_lag = min(max_lag, n // 2 - 1)
     best_lag, best_val, second = 0, -float("inf"), -float("inf")
-    # ignore lags with less than 35 % overlap: with the documented rule (analysis window >= 4x the
-    # largest expected offset) true offsets always keep >= 75 % overlap, while short-overlap lags are
-    # where coincidental matches on quasi-periodic material (music, tone beds) live
-    min_overlap = max(10, int(0.35 * min(lr, lo)))
+    min_overlap = max(10, int(MIN_OVERLAP_FRACTION * min(lr, lo)))  # see constants above
     scores = []
     for lag in range(-max_lag, max_lag + 1):
         # corr[lag] = sum_i ref[i] * other[i - lag]  -> ref index range and other index range overlap:
@@ -135,10 +148,8 @@ def cross_correlate(ref: List[float], other: List[float], max_lag: int):
         if denom <= 0:
             continue
         val = corr[lag % n].real / denom
-        # mild preference for longer overlaps: a perfect match over 55 % of the window must not tie
-        # with a perfect match over 100 % (quasi-periodic material). Exponent 0.5: with the window rule (>= 4x offset) a true match keeps >= 75 % overlap (x0.87) while a coincidental 55 % match drops to x0.74; keeps large true
-        # offsets (28 s in 60 s = 53 % overlap -> x0.94) competitive while still breaking exact ties.
-        val *= ((r1 - r0) / min(lr, lo)) ** 0.5
+        val *= ((r1 - r0) / min(lr, lo)) ** OVERLAP_WEIGHT_EXP  # longer overlap wins ties
+
         scores.append((val, lag))
         if val > best_val:
             second = best_val