ffmpeg-skill 3.6.0 → 3.6.2

package/scripts/_common/wrap.py

@@ -29,7 +29,11 @@ ADVANCE_EM = {"ja": 1.0, "zh": 1.0, "ko": 1.0, "th": 1.0, "hi": 0.7, "ar": 0.6,
 # a word. A Thai run is therefore one atom, broken only at the spaces (or the manual `|`) the
 # writer put there; an over-long run stays long on its own line, the rule long Latin words
 # already follow.
-NO_SPACE_SCRIPTS = ("ja", "zh", "ko")
+# Korean is NOT here: it is written with spaces between words (eojeol), so a Hangul run is a word
+# like a Latin one -- broken at its spaces, and cut inside only by _slice_atom's escape hatch.
+# Per-character atoms broke `시작|합니다` and, once a pass moved the break, joined the halves
+# with no space (`늦지마세요`) while the result said text_unchanged.
+NO_SPACE_SCRIPTS = ("ja", "zh")
 NO_BOUNDARY_SCRIPTS = ("th",)   # per-character breaking would chop words: keep the run whole
 
 
@@ -304,9 +308,11 @@ def _join(left: str, atom: str, spaced: bool) -> str:
 
 
 def _break_spaced(first: str, second: str) -> bool:
-    """Did a space stand at the break between these two wrapped lines? Only spaced scripts put one
-    there -- a CJK/Thai break sits between two characters that were written with nothing between
-    them, and re-joining them with a space would insert a character the cue never had."""
+    """A guess at whether a space stood at the break between these two wrapped lines, from the
+    scripts on each side. The wrapper's own passes do not use it: the greedy fill records the real
+    answer per break (`gaps`) and every pass carries it along, because a script cannot tell -- a
+    Japanese cue written with spaces (`はい そうです`) lost one whenever a pass moved a break that
+    stood at a space. Kept as the fallback for a caller that has only the two strings."""
     if not first or not second:
         return False
     return char_script(first[-1]) not in NO_SPACE_SCRIPTS and char_script(second[0]) not in NO_SPACE_SCRIPTS \
@@ -477,7 +483,18 @@ def best_break(atoms: "Sequence[Tuple[str, bool]]", max_em: float,
     return None if best is None else best[1]
 
 
-def _fix_orphans(lines: "List[str]", max_em: float) -> "List[str]":
+def _gaps(lines: "List[str]", gaps: "Optional[List[bool]]") -> "List[bool]":
+    """The per-break space flags a pass reads and updates: the caller's list (updated in place, so
+    the next pass sees the moved breaks), or the _break_spaced() guess when the caller has none."""
+    if gaps is None:
+        return [_break_spaced(a, b) for a, b in zip(lines, lines[1:])]
+    if len(gaps) != max(len(lines) - 1, 0):
+        raise ValueError("gaps must hold one flag per break")
+    return gaps
+
+
+def _fix_orphans(lines: "List[str]", max_em: float,
+                 gaps: "Optional[List[bool]]" = None) -> "List[str]":
     """No last line that is a single stranded atom.
 
     Greedy wrapping leaves one character alone whenever the line before it filled exactly: eval 14
@@ -486,6 +503,7 @@ def _fix_orphans(lines: "List[str]", max_em: float) -> "List[str]":
     onto it -- but only while the result still fits and the line above does not become an orphan
     itself, so a two-word cue is never made worse."""
     lines = list(lines)
+    gaps = _gaps(lines, gaps)
     for _ in range(len(lines)):
         if len(lines) < 2:
             break
@@ -499,14 +517,16 @@ def _fix_orphans(lines: "List[str]", max_em: float) -> "List[str]":
         new_prev = ""
         for atom, sp in prev[:-1]:
             new_prev = _join(new_prev, atom, sp)
-        new_last = _join(moved, tail[0][0], _break_spaced(lines[-2], lines[-1]))
+        new_last = _join(moved, tail[0][0], gaps[-1])
         if text_width_em(new_last) > max_em or text_width_em(new_prev) < ORPHAN_MIN_EM:
             break
         lines[-2], lines[-1] = new_prev, new_last
+        gaps[-1] = spaced
     return lines
 
 
-def _fix_weak_lines(lines: "List[str]", max_em: float) -> "List[str]":
+def _fix_weak_lines(lines: "List[str]", max_em: float,
+                    gaps: "Optional[List[bool]]" = None) -> "List[str]":
     """R2, generalised: _fix_orphans run at *every* boundary, against _is_weak_line.
 
     1.15 only ever looked at the last line, so a stranded digit or kana in the middle of a
@@ -514,6 +534,7 @@ def _fix_weak_lines(lines: "List[str]", max_em: float) -> "List[str]":
     of the line above moves down onto it -- with 1.15's two guards intact (the result must still
     fit, and the line above must not itself become weak), so the line count never changes."""
     lines = list(lines)
+    gaps = _gaps(lines, gaps)
     for i in range(len(lines) - 1, 0, -1):
         for _ in range(len(lines)):
             if not _is_weak_line(lines[i]):
@@ -521,19 +542,21 @@ def _fix_weak_lines(lines: "List[str]", max_em: float) -> "List[str]":
             prev = _atoms(lines[i - 1])
             if len(prev) < 2:
                 break
-            moved, _spaced = prev[-1]
+            moved, spaced = prev[-1]
             new_prev = ""
             for atom, sp in prev[:-1]:
                 new_prev = _join(new_prev, atom, sp)
-            new_last = _join(moved, lines[i], _break_spaced(lines[i - 1], lines[i]))
+            new_last = _join(moved, lines[i], gaps[i - 1])
             if text_width_em(new_last) > max_em or _is_weak_line(new_prev) \
                     or text_width_em(new_prev) < ORPHAN_MIN_EM:
                 break
             lines[i - 1], lines[i] = new_prev, new_last
+            gaps[i - 1] = spaced
     return lines
 
 
-def _rebalance(lines: "List[str]", max_em: float) -> "List[str]":
+def _rebalance(lines: "List[str]", max_em: float,
+               gaps: "Optional[List[bool]]" = None) -> "List[str]":
     """Move each break to the one that minimises the widest line of the pair, without changing the
     line count.
 
@@ -544,11 +567,12 @@ def _rebalance(lines: "List[str]", max_em: float) -> "List[str]":
     if len(lines) < 2:
         return lines
     out = list(lines)
+    gaps = _gaps(out, gaps)
     for i in range(len(out) - 1):
         first, second = out[i], out[i + 1]
         tail_atoms = _atoms(second)
         if tail_atoms:
-            tail_atoms[0] = (tail_atoms[0][0], _break_spaced(first, second))
+            tail_atoms[0] = (tail_atoms[0][0], gaps[i])
         atoms = _atoms(first) + tail_atoms
         if not atoms or any(char_script(ch) in NO_SPACE_SCRIPTS for ch in first + second):
             continue
@@ -568,13 +592,15 @@ def _rebalance(lines: "List[str]", max_em: float) -> "List[str]":
                 continue
             key = (max(wa, wb), abs(wa - wb))
             if best is None or key < best[0]:
-                best = (key, a, b)
+                best = (key, a, b, atoms[cut][1])
         if best is not None:
             out[i], out[i + 1] = best[1], best[2]
+            gaps[i] = best[3]
     return out
 
 
-def _rebalance_phrase(lines: "List[str]", max_em: float, lang: "Optional[str]") -> "Tuple[List[str], int]":
+def _rebalance_phrase(lines: "List[str]", max_em: float, lang: "Optional[str]",
+                      gaps: "Optional[List[bool]]" = None) -> "Tuple[List[str], int]":
     """_rebalance with R1-R4 deciding, for every script rather than spaced ones only.
 
     Returns the new lines and how many breaks a phrase rule moved away from the position 1.15's
@@ -582,12 +608,13 @@ def _rebalance_phrase(lines: "List[str]", max_em: float, lang: "Optional[str]")
     if len(lines) < 2:
         return list(lines), 0
     out = list(lines)
+    gaps = _gaps(out, gaps)
     moved = 0
     for i in range(len(out) - 1):
         first, second = out[i], out[i + 1]
         tail_atoms = _atoms(second)
         if tail_atoms:
-            tail_atoms[0] = (tail_atoms[0][0], _break_spaced(first, second))
+            tail_atoms[0] = (tail_atoms[0][0], gaps[i])
         atoms = _split_hyphens(_atoms(first) + tail_atoms)
         if len(atoms) < 2:
             continue
@@ -602,11 +629,13 @@ def _rebalance_phrase(lines: "List[str]", max_em: float, lang: "Optional[str]")
         if (a, b) != (first, second):
             moved += 1
         out[i], out[i + 1] = a, b
+        gaps[i] = atoms[cut][1]
     return out, moved
 
 
 def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
-                   sliced: "Optional[List[int]]" = None) -> "List[str]":
+                   sliced: "Optional[List[int]]" = None,
+                   gaps: "Optional[List[bool]]" = None) -> "List[str]":
     """The greedy fill on its own: the line count every mode must keep.
 
     `slice_overlong` (off by default -- only caption.py's final burn-in pass turns it on, never
@@ -615,47 +644,65 @@ def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
     katakana run that already fits is completely untouched -- is hard-sliced by _slice_atom()
     instead of kept whole. `sliced`, when given, gets one entry (the number of extra lines that
     one atom produced) per atom actually sliced, which is how the caller counts
-    `broken_inside_word` without re-deriving it from the output lines."""
+    `broken_inside_word` without re-deriving it from the output lines.
+
+    `gaps`, when given, is filled with one flag per break: did a space stand there in `raw`? The
+    passes in _balance() carry it, so a break they move keeps (or drops) exactly that space."""
     current = ""
+    current_gap = False   # did a space stand before `current`'s first atom
     chunk: "List[str]" = []
-    for atom, spaced in _atoms(raw):
-        if slice_overlong and not current and text_width_em(atom) > max_em:
+    breaks: "List[bool]" = []
+
+    def emit(line: str, gap_before: bool) -> None:
+        if chunk:
+            breaks.append(gap_before)
+        chunk.append(line)
+
+    def start_line(atom: str, spaced: bool) -> "Tuple[str, bool]":
+        """The new current line opening with `atom`, sliced first when it is too wide alone."""
+        if slice_overlong and text_width_em(atom) > max_em:
             pieces = _slice_atom(atom, max_em)
             if sliced is not None and len(pieces) > 1:
                 sliced.append(len(pieces) - 1)
-            chunk.extend(pieces[:-1])
-            current = pieces[-1]
+            if len(pieces) > 1:
+                emit(pieces[0], spaced)
+                for piece in pieces[1:-1]:
+                    emit(piece, False)
+                return pieces[-1], False
+        return atom, spaced
+
+    for atom, spaced in _atoms(raw):
+        if not current:
+            current, current_gap = start_line(atom, spaced)
             continue
         candidate = _join(current, atom, spaced)
-        if current and text_width_em(candidate) > max_em:
-            chunk.append(current)
-            if slice_overlong and text_width_em(atom) > max_em:
-                pieces = _slice_atom(atom, max_em)
-                if sliced is not None and len(pieces) > 1:
-                    sliced.append(len(pieces) - 1)
-                chunk.extend(pieces[:-1])
-                current = pieces[-1]
-            else:
-                current = atom
+        if text_width_em(candidate) > max_em:
+            emit(current, current_gap)
+            current, current_gap = start_line(atom, spaced)
         else:
             current = candidate
     if current:
-        chunk.append(current)
+        emit(current, current_gap)
+    if gaps is not None:
+        gaps[:] = breaks
     return chunk
 
 
-def _balance(chunk: "List[str]", max_em: float, mode: str, lang: "Optional[str]") -> "List[str]":
+def _balance(chunk: "List[str]", max_em: float, mode: str, lang: "Optional[str]",
+             gaps: "Optional[List[bool]]" = None) -> "List[str]":
     """The post-passes for one greedy chunk, in the mode's own order. Never changes the count:
     a pass that would is discarded, exactly as 1.15 did."""
     if len(chunk) < 2:
         return chunk
+    gaps = list(gaps) if gaps is not None else None
     if mode == "measured":
-        fixed = _fix_orphans(chunk, max_em)
-        rebalanced = _rebalance(fixed, max_em)
+        fixed = _fix_orphans(chunk, max_em, gaps)
+        rebalanced = _rebalance(fixed, max_em, list(gaps) if gaps is not None else None)
     else:
-        fixed = _fix_weak_lines(_fix_orphans(chunk, max_em), max_em)
-        rebalanced, _moved = _rebalance_phrase(fixed, max_em, lang)
-        rebalanced = _fix_weak_lines(rebalanced, max_em)
+        fixed = _fix_weak_lines(_fix_orphans(chunk, max_em, gaps), max_em, gaps)
+        later = list(gaps) if gaps is not None else None
+        rebalanced, _moved = _rebalance_phrase(fixed, max_em, lang, later)
+        rebalanced = _fix_weak_lines(rebalanced, max_em, later)
     if len(rebalanced) == len(chunk):
         return rebalanced
     return fixed if len(fixed) == len(chunk) else chunk
@@ -681,8 +728,9 @@ def wrap_text(text: str, max_em: float, *, balance: bool = True, mode: str = "ph
     for raw in text.split("\n"):
         if not raw.strip():
             continue
-        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced)
-        lines.extend(_balance(chunk, max_em, mode, lang) if balance else chunk)
+        gaps: "List[bool]" = []
+        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps)
+        lines.extend(_balance(chunk, max_em, mode, lang, gaps) if balance else chunk)
     return lines or [text]
 def wrap_variants(text: str, max_em: float, *, mode: str = "phrase",
                   lang: "Optional[str]" = None, slice_overlong: bool = False,
@@ -701,10 +749,12 @@ def wrap_variants(text: str, max_em: float, *, mode: str = "phrase",
     for raw in text.split("\n"):
         if not raw.strip():
             continue
-        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced)
+        gaps: "List[bool]" = []
+        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps)
         greedy.extend(chunk)
-        wrapped.extend(_balance(list(chunk), max_em, mode, lang))
-        measured.extend(chunk if mode == "measured" else _balance(list(chunk), max_em, "measured", None))
+        wrapped.extend(_balance(list(chunk), max_em, mode, lang, gaps))
+        measured.extend(chunk if mode == "measured"
+                        else _balance(list(chunk), max_em, "measured", None, gaps))
     if not greedy:
         greedy = [text]
     return (wrapped or [text], greedy, measured or [text])

package/scripts/_contract.py

@@ -178,8 +178,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                      video_required=False, audio_only=True, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "silence": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["silence list JSON (--list)", "artifact with silences removed", "EDL text (--edl)"],
                     required=FF + ["filter:silencedetect"], optional=[{"capability": X264, "when": "removing silences from a video"}, HDR_X265, {"capability": AAC, "when": "removing silences from a video"},
-                                                                    {"capability": "external:whisper", "when": "--filler --transcribe"},
-                                                                    {"capability": "external:parakeet", "when": "--filler --transcribe (English; either engine family satisfies it)"}] + AUDIO_OUT,
+                                                                    {"capability": "external:whisper", "when": "--transcribe (with --filler or a sentence flag)"},
+                                                                    {"capability": "external:parakeet", "when": "--transcribe (with --filler or a sentence flag; English; either engine family satisfies it)"}] + AUDIO_OUT,
                     video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "join": dict(role="execution", inputs=["two or more video assets, or two or more audio-only assets"], outputs=["concatenated video artifact", "concatenated audio artifact (audio-only inputs, audio output extension)"],
                  required=FF + ["filter:xfade", "filter:acrossfade"],
@@ -289,7 +289,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
     "caption":   dict(video="conditional", audio="conditional", note="--mode burn (default) always re-encodes both streams to render pixels; --mode mux copies video and audio untouched and only adds a subtitle stream"),
     "overlay":   dict(video="always", audio="always"),
     "graphics":  dict(video="always", audio="always"),
-    "sync":      dict(video="conditional", audio="conditional", note="video is -c:v copy only for --trim-second when the second file started earlier (offset<0) and the copy succeeds; it is re-encoded whenever --replace-audio's stream copy fails, or in --trim-second when the second file started later (offset>=0, the common case) or --fix-drift is used"),
+    "sync":      dict(video="conditional", audio="conditional", note="video is -c:v copy only for --replace-audio (the reference picture) while that copy succeeds; --trim-second always re-encodes a video second file, since a copy would start at the keyframe before the trim point; a sound-only second file that started earlier is stream-copied"),
     "multicam":  dict(video="always", audio="always"),
     "audio":     dict(video="never", audio="always", note="video stream is always -c:v copy when present; this tool's job is the audio"),
     "loudness":  dict(video="never", audio="always"),
@@ -421,10 +421,12 @@ ERROR_REASONS = {
     "input_incomplete": "kind ffmpeg: the input has no index (\"moov atom not found\"): a recording cut off or a copy not finished; --repair cannot rebuild it; details: {}",
     "input_unreadable": "kind ffmpeg: ffmpeg could not read the input as media (\"Invalid data found when processing input\"); details: {}",
     "ffmpeg_unsupported": "kind missing_tool: the ffmpeg/ffprobe on PATH reports a version older than 6.1, which 3.0.0 no longer supports (5.x was deprecated in 2.14.0); details: {version, required}",
+    "read_only_plan_refused": "--plan in a process run with FFMPEG_SKILL_READ_ONLY=1 (mcp/server.py sets it for the tools annotated readOnlyHint: probe, check, cropdetect), which must write no file; details: {plan}",
     "output_exists": "an output already exists and --overwrite was not given; details.outputs: [{path, resolved, size, mtime_ns}]",
     "output_is_input": "the output resolves to the same file as an input; details: {output, input, resolved}",
     "output_is_directory": "the output path is a directory; details: {output}",
-    "media_path_is_playlist": "an input is a playlist (HLS .m3u8/.m3u or an ffconcat list, by name or by its first bytes) that ffmpeg would follow to the files it names; the skill takes media files only; details: {path}",
+    "media_path_is_playlist": "an input is a playlist that ffmpeg would follow to the files or URLs it names: HLS .m3u8/.m3u or an ffconcat list (by name or by its first bytes), a DASH manifest or an IMF composition playlist (by name or by the content ffmpeg's own probe looks for, whatever the file is called); the skill takes media files only; details: {path}",
+    "media_path_has_line_break": "a path written into a concat list (loop.py, join.py --copy, sequence.py, multi-part cuts) contains a line break, which the concat format cannot hold: each line is a directive, so the name would add entries to the list; details: {path}",
     "media_path_not_a_file": "an input exists but is not a regular file (a FIFO or a device), which ffmpeg would block on or read as a stream; details: {path}",
     "join_copy_mismatch": "join.py --copy: a clip's streams do not match the first clip's, it hides pre-roll frames with an edit list, or its picture and sound end more than 50 ms apart; details: {clips: [{index?, path, differs}]}",
     "output_path_taken": "two files one run writes (a side file and the output, or two side files) resolve to the same path, so the second would replace the first; details: {output, other}",
@@ -443,9 +445,9 @@ ERROR_REASONS = {
     "plan_argv_invalid": "render.py PLAN: argv is not a list; details: {plan, plan_sha256, checked_at, argv_type, audit_log}",
     "decoder_missing": "color.py / graphics.py / overlay.py: a VP9 source or --video layer stored with an alpha layer, on a build with no libvpx-vp9 decoder (FFmpeg's own VP9 decoder drops the alpha), kind missing_tool; details: {name}",
     "encoder_missing": "--codec av1/prores: the build's encoder list was read and has no encoder for the codec (kind missing_tool; details: {codec, encoders}); or ffmpeg itself reported \"Unknown encoder\" for the encoder the command named (kind ffmpeg; details: {name}; the hint points at doctor)",
-    "asr_engine_missing": "kind missing_tool: --transcribe (caption.py, silence.py --filler) found no local speech-to-text engine; the message lists the install lines; details: {}",
+    "asr_engine_missing": "kind missing_tool: --transcribe (caption.py; silence.py with --filler or a sentence flag) found no local speech-to-text engine; the message lists the install lines; details: {}",
     "encoder_list_unreadable": "--codec av1/prores: the build's encoder list could not be read, so whether it has the encoder is unknown (kind ffmpeg); details: {codec, encoders, error}",
-    "no_speech": "kind input: --transcribe (caption.py, silence.py --filler) ran a local speech engine that heard no speech in the input; details: {engine}; also top-level reason and engine",
+    "no_speech": "kind input: --transcribe (caption.py; silence.py with --filler or a sentence flag) ran a local speech engine that heard no speech in the input; details: {engine}; also top-level reason and engine",
     "engine_failed": "kind input: --transcribe: an installed speech engine ran and failed (a named --engine, or every engine --engine auto found); details: {engine, detail | engines: [{engine, reason, detail}]}; also top-level reason, engine and detail/engines",
     "english_only": "kind input: --transcribe under --engine auto found only Parakeet engines, which it runs for English speech only, and the language is not English; details: {engine, engines}; also top-level reason, engine and engines",
 }
@@ -617,7 +619,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
             "verified": {"type": "boolean", "description": "true only when the artifact was written, probed, and every self-check the tool ran (verification) met its target; false under --dry-run"},
             "verification": {"type": "array", "items": {"type": "object", "properties": {"step": {"type": "string"}, "ok": {"type": "boolean"}, "stage": {"type": "string"}, "property": {"type": "string"}, "expected": {}, "measured": {}, "delta": {}, "tolerance": {}, "provenance": {"enum": ["specification", "user_specified", "independent_measurement", "input_premeasurement"]}, "attribution": {"enum": ["artifact", "reference", "instrument", "provenance", "unresolved"]}}}, "description": "what the tool itself verified: probe, plus loudness (loudness.py, export platform presets; ok false with reason not_measured when it could not be read), check (render), report.py's sections (loudness, compliance, contact_sheet) and batch.py's items (item). render.py also lists every stage's own steps beyond its artifact probe, tagged with `stage` (a cached stage's as recorded), so its `verified` is the conjunction of every stage's. Since 2.18 a step may carry the property it measured with expected, measured, delta, tolerance and the provenance of the expected value; cut, join and export add a `streams` step comparing the output's video/audio streams with the input's; a step with ok false carries `attribution` (unresolved until a tool knows the cause)"},
             "unverified": {"type": "array", "items": {"type": "string"}, "description": "2.18: the properties of the output this tool did not measure (the unverified range), e.g. caption's rendered_placement; `verified` covers the measured properties only"},
-            "source_carry": {"type": "object", "description": "what the first input carried besides its picture and sound, compared with the written file: {kept: [...], dropped: [...]} over subtitles, chapters, cover_art, audio_channels (a surround source only), creation_time, audio_language, timecode. Present only when the source had at least one of them; absent under --dry-run, for a still or GIF output, and when two or more inputs have a picture or sound. A report, not a check: `verified` does not depend on it. A dropped subtitles/chapters/cover_art/audio_channels also records a source_items_dropped warning"},
+            "source_carry": {"type": "object", "description": "what the first input carried besides its picture and sound, compared with the written file: {kept: [...], dropped: [...]} over subtitles, chapters, cover_art, audio_channels (a surround source only), creation_time, audio_language, timecode (kept only when the written start timecode is the label of the frame the output starts on: the source's own, or moved there by a tool that moved the picture's start; a join of several ranges writes none). Present only when the source had at least one of them; absent under --dry-run, for a still or GIF output, and when two or more inputs have a picture or sound. A report, not a check: `verified` does not depend on it. A dropped subtitles/chapters/cover_art/audio_channels also records a source_items_dropped warning"},
             "diagnostics": DIAGNOSTICS_SCHEMA}
     extra: Dict[str, Any] = {}
     if name == "check":
@@ -665,7 +667,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "hint": {"type": "string", "description": "when nothing sat below --threshold: the track's measured level and the --threshold that would find its pauses"},
                  "speech_aware": {"type": "object", "description": "--speech-aware (1.18): {min_silence, floor, breaths_kept, breaths_kept_seconds, breaths}"},
                  "filler": {"type": "object", "description": "--filler: {lang, source (whisper-json:FILE | whisper:ENGINE | parakeet:ENGINE), engine, transcription (with --transcribe: {engine, model, language, routing}), removed, removed_count, matched_untimed (listed words in the transcript with no usable timing, not removed), matched_too_long (listed words longer than a filler, kept), ...}"},
-                 "notes": {"type": "array", "items": {"type": "string"}, "description": "--filler --transcribe under --engine auto: present when the English-only Parakeet model ran on English assumed (no --filler-lang, no language detected, no Whisper engine installed or none that succeeded); the transcript is wrong if the speech is not English"}}
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "--transcribe (with --filler or a sentence flag) under --engine auto: present when the English-only Parakeet model ran on English assumed (no --filler-lang, no language detected, no Whisper engine installed or none that succeeded); the transcript is wrong if the speech is not English"}}
     elif name == "sync":
         extra = {"reference": {"type": "string"}, "second": {"type": "string"}, "offset_seconds": {"type": "number"}, "confidence": {"type": "number"}, "meaning": {"type": "string"}, "drift": {"type": "object"},
                  "sources": {"type": "array", "description": "1.18: [{path, offset_s, confidence, drift_ppm}], one per SOURCE; the only per-source shape once more than one SOURCE is given; with --fix-drift each also carries drift_skipped_reason"},
@@ -693,7 +695,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "files": {"type": "array", "description": "one entry per file: {file, probe, steps, skipped}. A step is {step, ok, seconds, error (one line, for the table)}, plus the tool's verified when it completed, and on a failure its own kind, reason, message, details and exit_code (reason step_timeout or step_output_unparsed when the tool printed no failure document); skipped lists the steps that do not apply as {step, reason: quick|no_video|no_audio|not_hdr|not_multichannel|input_unreadable, message}"},
                  "failed": {"type": "integer"}, "total": {"type": "integer"}}
     elif name == "batch":
-        extra = {"results": {"type": "array", "description": "one row per input, every input (an interrupted batch included): ok (every step completed), verified (every step also verified what it wrote; false under --dry-run) and unverified ([{step, tool, failed}] naming the steps that did not); a failed row's error {step, tool, kind, message, code, reason, details, hint, exit_code} from the failing step's own document; diagnostics from its steps (tagged with step); cache_miss {reason: output_missing|output_changed|entry_unverifiable, ...} when a cache entry was not served; skipped \"timeout\" or \"interrupted\" for an item that never started and interrupted true for one stopped while running. A row whose recipe ran cut.py carries cut_reencoded (each cut.py call's reencoded) and cut_reencode_reasons (each reason those calls named, once per call)"},
+        extra = {"results": {"type": "array", "description": "one row per input, every input (an interrupted batch included): ok (every step completed), verified (every step also verified what it wrote; false under --dry-run) and unverified ([{step, tool, failed}] naming the steps that did not); a failed row's error {step, tool, kind, message, code, reason, details, hint, exit_code} from the failing step's own document; diagnostics from its steps (tagged with step); cache_miss {reason: output_missing|output_changed|entry_unverifiable, ...} when a cache entry was not served; skipped \"timeout\" or \"interrupted\" for an item that never started and interrupted true for one stopped while running; under --watch, skipped \"settling\" (ok false, not cached) for a source that changed since the previous poll, or, first seen, was modified within one poll interval: it is processed on a later pass. A row whose recipe ran cut.py carries cut_reencoded (each cut.py call's reencoded) and cut_reencode_reasons (each reason those calls named, once per call)"},
                  "processed": {"type": "integer"}, "total": {"type": "integer"},
                  "cut_stream_copy": {"type": ["object", "null"], "description": "cut.py calls across the folder: {calls, stream_copy, reencoded, stream_copy_rate}; null when no cut.py step ran"},
                  "cut_reencode_reasons": {"type": ["object", "null"], "description": "how many cut.py calls named each reencode_reason ({} when none re-encoded); a re-encoded call whose row came from a cache an earlier 2.x batch wrote, which recorded no reasons, counts as unknown; null when no cut.py step ran"}}
@@ -1758,6 +1760,17 @@ MCP_JSON_EXEMPT = ("look", "probe")
 # them out of every inputSchema (1.10.0-1.x kept them unless FFMPEG_SKILL_MCP_LEAN=1). A client
 # that still sends them is not refused -- build_argv() maps them like any other key.
 MCP_TRANSPORT_FLAGS = ("json", "progress")
+# what a read-only tool's (mcp_read_only: probe, check, cropdetect) MCP inputSchema says of the two
+# keys that would write a file: `plan` is refused over MCP and `overwrite` only governed that plan.
+# The names stay (3.x never removes an inputSchema property); the CLI keeps both working (every
+# tool gets --plan, docs/design-decisions.md).
+MCP_READ_ONLY_REFUSED = {
+    "plan": "refused over MCP (read-only tool; error.reason read_only_plan_refused): this tool writes no file here; run it from the CLI to write a plan",
+    "overwrite": "no effect over MCP: this read-only tool writes no file (it governed --plan, which is refused here)",
+}
+# set by mcp/server.py in the environment of a read-only tool's process: --plan is refused
+# (kind input, error.reason read_only_plan_refused), however the raw argv spells it
+READ_ONLY_ENV = "FFMPEG_SKILL_READ_ONLY"
 # default MCP tools/list surface (roadmap P1-7, shipped 1.18.3): the 42-tool schema dump costs
 # every MCP session context whether it needs it or not. These 12 are the tools eval iterations
 # 17-20's ground-truth `expect` lists actually name most often across the 118 agent prompts in
@@ -1904,6 +1917,13 @@ def mcp_input_schema(spec: Dict[str, Any]) -> Dict[str, Any]:
         structured["anyOf"] = one_of[0] if len(one_of) == 1 else [{"allOf": [{"anyOf": g} for g in one_of]}]
     for dest in MCP_TRANSPORT_FLAGS:
         props.pop(dest, None)
+    if mcp_read_only(spec):
+        # a tool that writes no artifact is annotated readOnlyHint; --plan is the one file it could
+        # still write (and --overwrite only governs that file). mcp/server.py runs the tool with
+        # FFMPEG_SKILL_READ_ONLY=1, which refuses --plan however it is spelled; the descriptions say so
+        for dest, text in MCP_READ_ONLY_REFUSED.items():
+            if dest in props:
+                props[dest]["description"] = text
     if structured.get("required"):
         structured["required"] = [d for d in structured["required"] if d not in MCP_TRANSPORT_FLAGS]
         if not structured["required"]:
@@ -1924,14 +1944,23 @@ def mcp_tool(spec: Dict[str, Any]) -> Dict[str, Any]:
             "annotations": mcp_annotations(spec)}
 
 
+def mcp_read_only(spec: Dict[str, Any]) -> bool:
+    """A tool that writes no artifact and does not touch its input: over MCP it writes nothing at
+    all (mcp/server.py refuses its `plan`, see mcp_input_schema), so it is annotated readOnlyHint."""
+    return not (bool(spec.get("produces_artifact")) or bool(spec.get("mutates_input")))
+
+
 def mcp_annotations(spec: Dict[str, Any]) -> Dict[str, Any]:
     """MCP ToolAnnotations (spec 2025-06-18) derived from the ToolSpec flags. Hints only: clients
-    must not treat them as a security boundary. Every tool runs locally (no open world); none edits
-    its input in place; a tool that writes nothing is read-only."""
-    writes = bool(spec.get("produces_artifact")) or bool(spec.get("mutates_input"))
+    must not treat them as a security boundary. Every tool runs locally (no open world). A tool
+    that writes nothing is read-only (mcp_read_only: the server runs it with
+    FFMPEG_SKILL_READ_ONLY=1, which refuses `--plan` however it is spelled). Every other tool is
+    destructive: none edits its input in place, but with `overwrite` it replaces an existing file at its output or plan path, which is not an
+    additive update."""
+    writes = not mcp_read_only(spec)
     return {"title": spec["name"],
             "readOnlyHint": not writes,
-            "destructiveHint": bool(spec.get("mutates_input")),
+            "destructiveHint": writes,
             "idempotentHint": spec.get("idempotency_hint") in ("bit_exact", "content_equivalent", "cached"),
             "openWorldHint": False}
 
@@ -1979,7 +2008,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
             # first time it runs; faster-whisper is a library, so its fetch is made from the skill's own
             # process. A caller that sandboxes the network must know that before a first --transcribe.
             "model_downloads": {
-                "when": "first use of a speech engine (--transcribe; silence.py --filler --transcribe runs it under --dry-run too, caption.py --transcribe does not) whose model is not cached yet; media is never uploaded",
+                "when": "first use of a speech engine (--transcribe; silence.py --transcribe, with --filler or a sentence flag, runs it under --dry-run too, caption.py --transcribe does not) whose model is not cached yet; media is never uploaded",
                 "in_process": {"faster-whisper": "Hugging Face (Systran/faster-whisper-<model>)"},
                 "child_process": {"parakeet-mlx": "Hugging Face (mlx-community/parakeet-*)",
                                   "openai-whisper": "OpenAI (its model checkpoint)"},
@@ -1993,8 +2022,8 @@ def build(detect: bool = True) -> Dict[str, Any]:
                 "canonical": True,
                 "transports": ["cli", "mcp"],
                 "argument_mapping": {
-                    "positional": "listed in input_schema.positional, in order; array values expand to several arguments",
-                    "options": "key -> --key with '_' replaced by '-'; booleans are flags; arrays repeat the flag; input_schema.properties[key].cli lists the accepted spellings",
+                    "positional": "listed in input_schema.positional, in order; array values expand to several arguments; when any of them starts with '-', all of them follow '--' after every option, so none is read as an option",
+                    "options": "key -> --key with '_' replaced by '-'; booleans are flags; arrays repeat the flag; input_schema.properties[key].cli lists the accepted spellings; a value starting with '-' is one token, --long-flag=value (\"-50%\" is text, not an option)",
                     "exceptions": "per tool in mcp.argument_exceptions (key -> flag), e.g. output -> -o, loudness.lufs -> -I, graphics.count_from -> --from",
                     "json": "--json is appended for every tool except look and probe (probe prints JSON by default)",
                 },

package/scripts/audio.py

@@ -13,7 +13,7 @@ Examples:
   python3 audio.py clip.mp4 --fade-in 0.5 --fade-out 1 --stereo
   python3 audio.py talk.mp4 --music bed.mp3 --duck --duck-threshold -30 --duck-release 250   # ducks earlier and recovers faster
   python3 audio.py band.wav --stereo-widen 0.5 -o wide.wav      # wider stereo image (a real stereo source; mono is refused)
-  python3 audio.py surround.mov --downmix                       # 5.1 -> stereo with proper centre/LFE weights
+  python3 audio.py surround.mov --downmix                       # 5.1 -> stereo, ITU-R BS.775 weights, scaled not to clip
   python3 audio.py clip.mp4 --replace narration.wav             # swap the audio track entirely
   python3 audio.py interview.mp4 -o interview.wav               # extract the audio (no video in the output)
   python3 audio.py multi.mkv --audio-stream 1 --voice -o lav.m4a # pick the second audio track, clean it, write M4A
@@ -29,6 +29,8 @@ from _common.probe import SILENT_PEAK_DBFS
 from _common import STATE, add_common, dry_run_input_pending, require_tool, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, measured_level_dbfs, probe, run, run_keeping_subtitles, fmt_secs
 from _common.emit import warn
 
+# --downmix: ITU-R BS.775 fold-down, renormalised by pan's '<' (see main()).
+DOWNMIX_PAN = "pan=stereo|FL<FL+0.707*FC+0.707*BL+0.707*SL|FR<FR+0.707*FC+0.707*BR+0.707*SR"
 VOICE_CHAIN = "highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2"
 
 # --voice [light|medium|strong] (1.13). "medium" is the chain --voice has always produced, so a
@@ -191,7 +193,7 @@ def main() -> int:
                        help="widen the stereo image, 0..1 (0 = untouched, 1 = maximum); needs a real stereo source: a mono input is "
                             "refused (duplicating it leaves both channels identical, so there is nothing to widen) and more than two "
                             "channels are refused unless --downmix folds them to stereo first")
-    fades.add_argument("--downmix", action="store_true", help="downmix 5.1/7.1 to stereo using standard weights")
+    fades.add_argument("--downmix", action="store_true", help="downmix 5.1/7.1 to stereo with the ITU-R BS.775 weights (centre and surrounds -3 dB, LFE dropped), scaled so the fold-down cannot clip")
     fades.add_argument("--replace", help="replace the audio with this file (trimmed/padded to the video)")
     dyn = ap.add_argument_group("dynamics (typed; each flag is one option of ffmpeg's acompressor / alimiter / agate)")
     dyn.add_argument("--compress", action="store_true", help="compressor (acompressor); order: gate -> compressor -> limiter")
@@ -301,7 +303,11 @@ def main() -> int:
 
     fx: List[str] = []
     if args.downmix:
-        fx.append("pan=stereo|FL=0.707*FC+FL+0.5*BL+0.5*SL+0.5*LFE|FR=0.707*FC+FR+0.5*BR+0.5*SR+0.5*LFE")
+        # ITU-R BS.775: centre and surrounds at -3 dB (0.707), LFE dropped. pan's '<' scales each
+        # output so its gains sum to 1 over the channels the input has (1/2.414 on 5.1, 1/3.121 on
+        # 7.1), so in-phase channels at full scale cannot clip; '=' summed 2.7x and clipped a loud
+        # 5.1 while the run said verified.
+        fx.append(DOWNMIX_PAN)
     if args.voice:
         fx.append(VOICE_LEVELS[args.voice])
     elif args.denoise: