ffmpeg-skill 3.6.1 → 3.6.3

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,6 +421,7 @@ 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}",
@@ -444,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",
 }
@@ -618,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":
@@ -666,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"},
@@ -694,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"}}
@@ -769,6 +770,9 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
     elif name == "join":
         extra = {"mode": {"enum": ["video", "audio"]}, "clips": {"type": "integer"}, "transition": {"type": "string"},
                  "expected_duration": {"type": ["number", "null"], "description": "clip lengths minus the transitions; null under --dry-run while an input is pending (its length is unknown)"},
+                 "frame_rate": {"type": "string", "description": "video mode only: the join's frame rate as an exact fraction (\"30000/1001\"), the rate every clip length and xfade offset is counted in"},
+                 "clip_frames": {"type": "array", "items": {"type": "integer"}, "description": "video mode only: per clip, the whole frames of frame_rate it holds in the join (its picture's, or the frames that cover a sound running more than a frame past it); its sound is cut to the samples those frames last. A pending --dry-run input counts 0"},
+                 "transition_frames": {"type": "integer", "description": "video mode only: the frames each xfade/acrossfade overlaps (--duration rounded to whole frames, at least 1; 0 for --transition none)"},
                  "sample_rate": {"type": "integer", "description": "audio mode only"}, "channels": {"type": "integer", "description": "audio mode only"},
                  "video": {"type": "boolean", "description": "false in audio mode: the output has no video stream"},
                  "skipped": {"type": "array", "description": "inputs --on-missing skip left out: [{index, path, reason}] ([] when none were)"},
@@ -1759,6 +1763,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
@@ -1905,6 +1920,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"]:
@@ -1925,14 +1947,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}
 
@@ -1980,7 +2011,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)"},
@@ -1994,8 +2025,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:

package/scripts/batch.py

@@ -33,8 +33,10 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool, MEDIA_EXT as _MEDIA_EXT
-from _common.runner import HW_FORCED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw, stop_children
+from _common.runner import (HW_FORCED_ENV, OWNED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw,
+                            owned_identity, stop_children)
 from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
+from _common.decision import rebase_project_paths
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {e for e in _MEDIA_EXT if e not in (".png", ".jpg", ".jpeg", ".webp")}  # one list (_common); a batch walks media, not stills
@@ -117,6 +119,16 @@ def gpu_key() -> str:
 JOBS_CAP = 8   # beyond this, concurrent encodes contend for the same cores and memory
 
 _LOG = threading.local()
+# source -> {real path -> owned_identity()} of every file this process delivered for that item (a
+# --watch loop's earlier passes): its final output and every side file its steps were allowed to
+# write (an .srt beside the video). An existing path that is still exactly that file is the item's
+# own, not someone else's, so a later pass of the SAME item replaces it (design-decisions: "A path
+# this same run wrote ... is never someone else's file"); the permission is per item and per path,
+# and is checked again where the write happens -- by deliver() under the output lock, by a step at
+# its own output check (runner.OWNED_ENV). A file edited or replaced since, one an earlier run
+# left, or one another item delivered (two items naming one side file) is still refused.
+_OWN_OUTPUTS: Dict[str, Dict[str, Dict[str, int]]] = {}
+_OWN_LOCK = threading.Lock()
 # set by batch.py's signal handler: a --jobs worker between two steps must not start the next one
 _STOP = threading.Event()
 
@@ -155,13 +167,15 @@ def step_error(index: Optional[int], tool: Optional[str], doc: Any) -> Dict[str,
     return out
 
 
-def run_step(argv: List[str], per_call: "Optional[float]" = None) -> "tuple[bool, Optional[dict]]":
+def run_step(argv: List[str], per_call: "Optional[float]" = None,
+             owned: "Optional[Path]" = None) -> "tuple[bool, Optional[dict]]":
     """Returns (ok, doc): doc is the step's own --json result document; a failed step that
     printed none that parses gets one in the failure shape (error.reason step_output_unparsed,
     the last stderr line as the message), so its row still says why. {in}/{out} are already resolved by the caller before argv reaches here, so forcing
     --json on every step (harmless: no step reads another step's stdout, only its output path)
     costs nothing and lets a caller like process() read back tool-specific fields, e.g. cut.py's
-    `reencoded`, without adding a bespoke flag per field it might someday want."""
+    `reencoded`, without adding a bespoke flag per field it might someday want. `owned`: the
+    owned_config() file the step reads under runner.OWNED_ENV."""
     script = argv[0]
     if script not in ALLOWED_STEP_SCRIPTS:
         # main() refuses such a recipe before any item runs; this stays as the last line of defence
@@ -173,7 +187,8 @@ def run_step(argv: List[str], per_call: "Optional[float]" = None) -> "tuple[bool
                        "error": {"kind": "interrupted", "message": f"interrupted before {script} started"}}
     cmd = [str(HERE / script)] + argv[1:] + child_args() + (["--json"] if "--json" not in argv[1:] else [])
     log("  → " + " ".join(os.path.basename(c) if i < 1 else c for i, c in enumerate(cmd)))
-    proc = run_tool(cmd, per_call=per_call)
+    env = dict(os.environ, **{OWNED_ENV: str(owned)}) if owned else None
+    proc = run_tool(cmd, per_call=per_call, env=env)
     try:
         doc = json.loads(proc.stdout)
     except ValueError:
@@ -240,9 +255,69 @@ def row_output(src: Path, recipe: Dict[str, Any], outdir: Path) -> Dict[str, Any
     return fields
 
 
-def deliver(src: str, final: Path) -> None:
+def own_expected(src: Path, path: "Path | str") -> "Optional[Dict[str, int]]":
+    """The identity this process left `path` with, if it delivered a file there for `src`."""
+    with _OWN_LOCK:
+        return _OWN_OUTPUTS.get(str(src), {}).get(os.path.realpath(str(path)))
+
+
+def is_own_output(src: Path, final: Path) -> bool:
+    """Whether `final` is still the file this process delivered there for `src` (_OWN_OUTPUTS)."""
+    expected = own_expected(src, final)
+    return expected is not None and owned_identity(str(final)) == expected
+
+
+def record_own(src: Path, committed: "Dict[str, Dict[str, int]]", work: Path) -> None:
+    """Remember the files this item delivered, each with the identity it had when it was written
+    (a step's report_committed(), deliver() for the final path), never as it is now: a sidecar
+    edited while a later step ran no longer matches, so the item's next pass refuses it. Paths in
+    the item's work directory go with it and are skipped. Replaces what an earlier pass of the item
+    recorded."""
+    base = os.path.realpath(str(work))
+    mine: Dict[str, Dict[str, int]] = {}
+    for p, ident in committed.items():
+        real = os.path.realpath(p)
+        if real == base or real.startswith(base + os.sep) or not isinstance(ident, dict):
+            continue
+        mine[real] = ident
+    with _OWN_LOCK:
+        _OWN_OUTPUTS[str(src)] = mine
+
+
+def owned_config(src: Path, work: Path, i: int) -> Path:
+    """The file a step reads under runner.OWNED_ENV: a snapshot of what this process delivered for
+    `src`, taken right before the step starts (one file per step, since a step reads it once), and
+    the directory where each of its processes reports the paths it passed the output check for."""
+    report = work / "owned-report"
+    report.mkdir(exist_ok=True)
+    with _OWN_LOCK:
+        replaceable = dict(_OWN_OUTPUTS.get(str(src), {}))
+    cfg = work / f"owned{i}.json"
+    cfg.write_text(json.dumps({"replaceable": replaceable, "report": str(report)}), encoding="utf-8")
+    return cfg
+
+
+def owned_reports(work: Path) -> "Dict[str, Dict[str, int]]":
+    """{path: identity when written} for every file the item's steps reported committing
+    (owned_config's report directory). A path a step was allowed to write but never reported
+    writing is not in it."""
+    found: Dict[str, Dict[str, int]] = {}
+    for f in sorted((work / "owned-report").glob("*.json")) if (work / "owned-report").is_dir() else []:
+        try:
+            doc = json.loads(f.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        committed = doc.get("committed") if isinstance(doc, dict) else None
+        if isinstance(committed, dict):
+            found.update({p: i for p, i in committed.items() if isinstance(p, str) and isinstance(i, dict)})
+    return found
+
+
+def deliver(src: str, final: Path, expected: "Optional[Dict[str, int]]" = None) -> "Optional[Dict[str, int]]":
     """Move an item's last written intermediate to its final path, under the output guard every
-    tool applies: an existing file is replaced only with --overwrite. A dry run writes nothing."""
+    tool applies: an existing file is replaced only with --overwrite, or when it is still exactly
+    `expected` -- the file this process delivered there on an earlier pass -- checked under the
+    output lock, so a file another process put there since is refused. A dry run writes nothing."""
     if STATE.dry_run:
         # the refusal the real run would meet, as a step writing {out} plans it (#428 review)
         if final.exists() and not STATE.overwrite:
@@ -257,7 +332,7 @@ def deliver(src: str, final: Path) -> None:
     # under the output lock every tool's write holds, so the existence check and the move are one
     # step for another run delivering or writing the same path
     with _OutputLock(str(final), on_locked=locked):
-        if final.exists() and not STATE.overwrite:
+        if final.exists() and not STATE.overwrite and not (expected is not None and owned_identity(str(final)) == expected):
             raise ItemError({"step": None, "tool": None, "kind": "input", "reason": "output_exists",
                              "message": f"refusing to overwrite existing output {str(final)!r}: pass --overwrite to replace it"})
         try:
@@ -279,13 +354,25 @@ def deliver(src: str, final: Path) -> None:
                         pass
                 raise ItemError({"step": None, "tool": None, "kind": "output",
                                  "message": f"could not deliver {src} to {final}: {exc}"})
+        # the delivered file as it was put there, taken under the lock: what a later pass may replace
+        ident = owned_identity(str(final))
     log(f"  delivered the last written file to {final}")
+    return ident
 
 
 def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             deadline: "Optional[float]" = None) -> Dict[str, Any]:
     final = final_path(src, recipe, outdir)
     t0 = time.time()
+    # replacing this run's own earlier output is decided per path and at the write, never here:
+    # each step gets a snapshot of what this process delivered (runner.OWNED_ENV) and checks every
+    # existing file it would write against it; deliver() checks the final path under its lock
+    track = not STATE.dry_run and not STATE.overwrite
+
+    delivered: Dict[str, Dict[str, int]] = {}
+
+    def owned(i: int) -> "Optional[Path]":
+        return owned_config(src, work, i) if track else None
 
     def budget() -> "Optional[float]":
         """What is left of the BATCH's time limit -- not a fresh one per item. A --timeout is a
@@ -306,11 +393,15 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         proj.setdefault("clips", [{}])
         while len(proj["clips"]) <= idx:
             proj["clips"].append({})
+        # the copy is written in the item's work directory, and render.py reads a project's
+        # relative paths against the project file's own directory: they are made absolute
+        # against the recipe's project, or "bed.wav" beside it was looked for in .work/<n>-xxx/
+        proj = rebase_project_paths(proj, Path(str(recipe["project"])).resolve().parent)
         proj["clips"][idx]["src"] = str(src.resolve())
         proj["output"] = str(final.resolve())
         pj = work / "project.json"
         pj.write_text(json.dumps(proj, indent=2), encoding="utf-8")
-        ok, _doc = run_step(["render.py", str(pj)], budget())
+        ok, _doc = run_step(["render.py", str(pj)], budget(), owned=owned(0))
         step_docs = [("render", _doc)]
         failure = None if ok else step_error(0, "render.py", _doc)
         cut_reencoded: List[bool] = []
@@ -334,7 +425,9 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             # what this one read, and when it is the last, the last file written is delivered (#415)
             writes = step_writes(step)
             argv = [str(a).replace("{in}", cur).replace("{out}", out) for a in step]
-            step_ok, doc = run_step(argv, budget())
+            if last and writes and track and is_own_output(src, final):
+                log(f"  {final.name} is this run's own earlier output, unchanged since: it may be replaced")
+            step_ok, doc = run_step(argv, budget(), owned=owned(i))
             step_docs.append((Path(str(argv[0])).stem if argv else "step", doc))
             # only cut.py's own doc carries `reencoded` -- true if ANY range this call cut (or its
             # --segments join) re-encoded, for the reasons in its `reencode_reason` (distinct per
@@ -353,9 +446,15 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             # the last step wrote nothing: the item's deliverable is the last file a step wrote,
             # which is in this item's work directory and would be removed with it (#415)
             try:
-                deliver(cur, final)
+                ident = deliver(cur, final, expected=own_expected(src, final))
+                if ident:
+                    delivered[str(final)] = ident
             except ItemError as exc:
                 ok, failure = False, exc.error
+    if ok and track:
+        # what this item delivered, each file as it was when written: the paths its steps reported
+        # committing (side files included) and the final path deliver() moved into place
+        record_own(src, {**owned_reports(work), **delivered}, work)
     result: Dict[str, Any] = {"file": str(src), **row_output(src, recipe, outdir), "ok": ok, "seconds": round(time.time() - t0, 1)}
     if failure:
         result["error"] = failure
@@ -434,6 +533,8 @@ def main() -> int:
     apply_common(args)
 
     started = time.time()
+    with _OWN_LOCK:
+        _OWN_OUTPUTS.clear()
     folder = Path(args.folder).resolve()  # relative 'bdir' used to become bdir/bdir/out once joined with the default outdir
     if not folder.is_dir():
         die(f"not a folder: {folder}")
@@ -553,6 +654,35 @@ def main() -> int:
                 except (ValueError, OSError):
                     pass
 
+    # --watch: each source's (size, mtime_ns) at the previous poll. A folder files are copied,
+    # downloaded or recorded into is read while they grow: a file processed mid-copy delivered a
+    # fraction of itself as ok (verified, for an MKV or TS), and once it settled every later pass
+    # met that output as someone else's and refused it. A source is processed once it is
+    # unchanged across one poll interval -- the same size and mtime as at the previous poll, or,
+    # first seen, last modified at least one interval ago; until then its row is
+    # skipped: "settling", not cached, and the next pass looks again.
+    last_seen: Dict[str, "tuple[int, int]"] = {}
+
+    def settle_poll(files: List[Path]) -> "set":
+        if not args.watch:
+            return set()
+        unsettled = set()
+        now = time.time()
+        current: Dict[str, "tuple[int, int]"] = {}
+        for src in files:
+            try:
+                st = src.stat()
+            except OSError:
+                continue  # gone since the scan: file_key() reports it as before
+            sig = (st.st_size, st.st_mtime_ns)
+            current[str(src)] = sig
+            before = last_seen.get(str(src))
+            if (before != sig) if before is not None else (now - st.st_mtime < args.watch):
+                unsettled.add(str(src))
+        last_seen.clear()
+        last_seen.update(current)
+        return unsettled
+
     def one_pass() -> List[Dict[str, Any]]:
         files = sorted(p for p in folder.glob(glob) if p.is_file() and p.suffix.lower() in MEDIA_EXT and outdir not in p.parents)
         # Two different sources can compute the same final path (most often a fixed recipe "ext"
@@ -632,7 +762,13 @@ def main() -> int:
         pending: List[tuple] = []
         cache_miss: Dict[int, Dict[str, Any]] = {}
         pass_key = rkey + side_inputs_key(recipe)
+        polled = settle_poll(files)
         for i, src in enumerate(files):
+            if str(src) in polled:
+                info(f"skip (still being written) {src.name}: it changed since the last poll")
+                slots[i] = {"file": str(src), **row_output(src, recipe, outdir), "ok": False, "verified": False,
+                            "seconds": 0.0, "skipped": "settling"}
+                continue
             key = f"{file_key(src)}:{pass_key}"
             hit = cache.get(key)
             if isinstance(hit, dict) and not args.force:
@@ -842,7 +978,9 @@ def main() -> int:
             timed_out=True)
     if done != len(results):
         failed_files = [r["file"] for r in results if not r["ok"]]
-        die(f"{len(results) - done} of {len(results)} items failed: {', '.join(failed_files[:5])}" + (" ..." if len(failed_files) > 5 else ""),
+        settling = sum(1 for r in results if r.get("skipped") == "settling")
+        die(f"{len(results) - done} of {len(results)} items failed: {', '.join(failed_files[:5])}" + (" ..." if len(failed_files) > 5 else "")
+            + (f" ({settling} of them still being written when the watch stopped, skipped: settling, not processed)" if settling else ""),
             kind="verification", output=None, dry_run=STATE.dry_run, results=results, processed=done, total=len(results))
     # cut.py's own `reencoded`, rolled up across every cut.py step this batch ran: how much of the
     # folder landed on the fast lossless path (mode "copy") vs re-encoded on at least one range.

package/scripts/broll.py

@@ -22,7 +22,7 @@ import sys
 from typing import Any, Dict, List
 
 from _common.decision import av_trim, frame_rate, grid_at_or_after, stream_starts
-from _common import STATE, add_common, aac_args, apply_common, cfr_args, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
+from _common import STATE, add_common, aac_args, apply_common, cfr_args, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, overlay_format, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 from _common.emit import note, record_fallback
 from _common.probe import display_size, square_pixels, square_pixels_note
 
@@ -136,7 +136,7 @@ def main() -> int:
         b_sq = (square_pixels(c["meta"]["video"]) + ",") if square_pixels(c["meta"]["video"]) else ""
         parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
                      f"{convert[i + 1]}{b_sq}{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
-        parts.append(f"{cur}[b{i}]overlay=0:0:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
+        parts.append(f"{cur}[b{i}]overlay=0:0{overlay_format(meta_a)}:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
         cur = f"[v{i}]"
     vout = cur