ffmpeg-skill 3.8.6 → 3.8.8

package/scripts/_common/timeline.py

@@ -142,11 +142,15 @@ def start_tc_frames(tc: Dict[str, Any], rate: Fraction) -> int:
 
 def _tc_label(frames: int, rate: Fraction, drop: bool) -> str:
     """`frames` as hh:mm:ss:ff at the nominal integer rate; drop-frame (`;`) for an NTSC source
-    whose own timecode is drop-frame, so the label is the one the media itself shows."""
+    whose own timecode is drop-frame, so the label is the one the media itself shows. Timecode
+    wraps at 24 hours as the media's own does (output_timecode_args() counts the same day): a
+    source starting at 23:59:50:00 is labelled 00:00:00:00 ten seconds in, not 24:00:00:00, which
+    no editor reads (A266)."""
     nominal = int(round(float(rate)))
     if not _drop_frame(drop, rate):
-        return _tc(frames, nominal)
+        return _tc(frames % (nominal * 86400), nominal) if nominal >= 1 else _tc(frames, nominal)
     d = nominal // 15
+    frames %= (nominal * 600 - d * 9) * 144
     per_10, per_min = nominal * 600 - d * 9, nominal * 60 - d
     tens, rem = divmod(frames, per_10)
     frames += d * 9 * tens + (d * ((rem - d) // per_min) if rem > d else 0)
@@ -376,6 +380,19 @@ def _tc(frames: int, fps_int: int) -> str:
     return f"{h:02d}:{m:02d}:{s:02d}:{f:02d}"
 
 
+# CMX 3600 numbers events in a three-digit field, and record timecode runs from 01:00:00:00 within
+# one 24-hour day.
+EDL_MAX_EVENTS = 999
+
+
+def _edl_text(value: Any) -> str:
+    """Caller text (a file name, a clip or chapter name, the title) on one EDL line. The format is
+    one statement per line with no escape, so a line break -- any str.splitlines() boundary -- or
+    another control character in a name added lines, or whole events, that parse_error() then
+    accepted (A261). Each becomes a space."""
+    return "".join(" " if (ch in "\x85\u2028\u2029" or ord(ch) < 32 or ord(ch) == 127) else ch for ch in str(value))
+
+
 def to_edl(tl: Dict[str, Any]) -> str:
     """CMX 3600, non-drop timecode at the nominal integer rate, record starting at 01:00:00:00.
     Every event is reel AX (the convention for file-based media) with the file named in
@@ -386,16 +403,24 @@ def to_edl(tl: Dict[str, Any]) -> str:
     from where the previous one stopped to where the next dissolve begins."""
     fps_int = int(round(float(tl["rate"])))
     hour = fps_int * 3600
+    rate = tl["rate"]
     clips = tl["clips"]
     d = tl["transition_frames"]
     # record range of each event: starts `trim_head` before its visible start (the dissolve
     # window), ends where the next event starts
     starts = [c["record_in"] - c["trim_head"] for c in clips]
     ends = starts[1:] + [tl["total"]]
-    lines = [f"TITLE: {tl['name']}", "FCM: NON-DROP FRAME", ""]
+    events = len(clips) + (1 if tl["music"] else 0)
+    if events > EDL_MAX_EVENTS:
+        # A265: f"{n:03d}" wrote event 1000 as four digits, outside the field
+        raise TimelineError(f"an EDL numbers its events in three digits (at most {EDL_MAX_EVENTS}); this timeline has "
+                            f"{events} -- export .fcpxml or .otio, or split the project")
+    if hour + tl["total"] > fps_int * 86400:
+        raise TimelineError(f"the timeline ({float(Fraction(tl['total']) / rate):.0f}s) runs past 24:00:00:00 when the "
+                            "EDL's record starts at 01:00:00:00 -- export .fcpxml or .otio, or split the project")
+    lines = [f"TITLE: {_edl_text(tl['name'])}", "FCM: NON-DROP FRAME", ""]
     n = 0
     prev_src_end = ""
-    rate = tl["rate"]
 
     def src_tc(c: Dict[str, Any], seq_frames: int) -> str:
         """The source timecode `seq_frames` (sequence frames of source media) after the clip's in
@@ -415,13 +440,13 @@ def to_edl(tl: Dict[str, Any]) -> str:
                          f"{_tc(rec_in, fps_int)} {_tc(rec_in, fps_int)}")
             lines.append(f"{n:03d}  AX       {chan:<5} D    {d:03d} {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
-            lines.append(f"* FROM CLIP NAME: {clips[i - 1]['name']}")
-            lines.append(f"* TO CLIP NAME: {c['name']}")
+            lines.append(f"* FROM CLIP NAME: {_edl_text(clips[i - 1]['name'])}")
+            lines.append(f"* TO CLIP NAME: {_edl_text(c['name'])}")
         else:
             lines.append(f"{n:03d}  AX       {chan:<5} C        {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
-            lines.append(f"* FROM CLIP NAME: {c['name']}")
-        lines.append(f"* SOURCE FILE: {c['src']}")
+            lines.append(f"* FROM CLIP NAME: {_edl_text(c['name'])}")
+        lines.append(f"* SOURCE FILE: {_edl_text(c['src'])}")
         if abs(c["speed"] - 1.0) > 1e-6:
             # the speed in source frames per second, at the rate the source labels are counted in
             own_fps = int(round(float(c.get("rate") or rate)))
@@ -433,11 +458,11 @@ def to_edl(tl: Dict[str, Any]) -> str:
         m = tl["music"]
         lines.append(f"{n:03d}  AX       A2    C        {_tc(0, fps_int)} {_tc(m['length'], fps_int)} "
                      f"{_tc(hour, fps_int)} {_tc(hour + m['length'], fps_int)}")
-        lines.append(f"* FROM CLIP NAME: {m['name']}")
-        lines.append(f"* SOURCE FILE: {m['src']}")
+        lines.append(f"* FROM CLIP NAME: {_edl_text(m['name'])}")
+        lines.append(f"* SOURCE FILE: {_edl_text(m['src'])}")
         lines.append("")
     for mk in tl["markers"]:
-        lines.append(f"* LOC: {_tc(hour + mk['at'], fps_int)} WHITE   {mk['title']}")
+        lines.append(f"* LOC: {_tc(hour + mk['at'], fps_int)} WHITE   {_edl_text(mk['title'])}")
     return "\n".join(lines).rstrip("\n") + "\n"
 
 
@@ -459,6 +484,14 @@ def _url(path: str) -> str:
     return Path(os.path.abspath(path)).as_uri()
 
 
+def _xml_text(value: Any) -> str:
+    """Caller text as XML 1.0 can hold it: a control character other than tab, line feed and
+    carriage return (and U+FFFE/U+FFFF) has no representation at all, not even escaped, so a clip
+    or chapter name carrying one made the FCPXML not well-formed (the sibling of A261). Each
+    becomes a space."""
+    return "".join(" " if ((ord(ch) < 32 and ch not in "\t\n\r") or ch in "\ufffe\uffff") else ch for ch in str(value))
+
+
 def to_fcpxml(tl: Dict[str, Any]) -> str:
     """FCPXML 1.10 (Final Cut Pro 10.6+, DaVinci Resolve): one library/event/project, a spine of
     asset-clips with cross dissolves between them, the music bed as a connected clip on lane -1
@@ -466,7 +499,7 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
     sequence has its own format (r1); each video asset has its source's, and a clip of another
     aspect states its spatial conform (adjust-conform) for frame.fit."""
     rate = tl["rate"]
-    q = lambda s: _xml_escape(str(s), {'"': "&quot;"})  # noqa: E731
+    q = lambda s: _xml_escape(_xml_text(s), {'"': "&quot;"})  # noqa: E731
     fd = _t(1, rate)
     res: List[str] = []
     ids: Dict[Any, str] = {}  # a format's (width, height, frameDuration) or an asset's path -> its id

package/scripts/_contract.py

@@ -239,6 +239,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
 # on PATH). "analysis_only": ffmpeg still decodes/measures the input under --dry-run, but nothing
 # is encoded and no file is written. Every other tool with the flag runs no ffmpeg at all.
 DRY_RUN_ANALYSIS = {
+    # #466 A193: probe was "none" with an ffprobe note while --analyze decoded with ffmpeg
+    "probe": "read-only tool; --dry-run changes nothing: ffprobe still runs, and only with --analyze ffmpeg decodes the first 20 s of each video input to sample picture levels",
     "sync": "audio is decoded to find the offset; the aligned output is not written",
     "multicam": "audio is decoded to align the cameras; the switched output is not written",
     "scenes": "scene and audio-peak measurement runs; --sheet and --edl are not written",
@@ -255,7 +257,6 @@ DRY_RUN_ANALYSIS = {
     "overlay": "only for a multi-line --text on FFmpeg 8.0, 8.0.1 or 8.1.0: one drawtext measures each line on a generated one-frame picture (the input is not read), so the planned per-line positions are the ones a run uses; otherwise no ffmpeg runs and the composited output is never written",
 }
 DRY_RUN_NOTES = {
-    "probe": "read-only tool; --dry-run changes nothing (ffprobe still runs)",
     "verify": "not supported: the flag is accepted but the steps run and outputs are written",
 }
 
@@ -581,7 +582,7 @@ def alpha_result_schema(name: str) -> Dict[str, Any]:
     out["alpha_codec"]["description"] += " (an RGB source that is neither HDR nor BT.2020, on a prores4444/vp9 line has no matrix to keep: it is converted to BT.709 and tagged so; an HDR or BT.2020 one is not: FFmpeg's own conversion makes its YUV, as before)"
     out["alpha_dropped"] = {"type": "boolean", "description": "true when the source's alpha is used (a frame below opaque, or a stored alpha plane that could not be read) and the output does not keep it (color.py --retag too, when its copy fell back to an H.264 re-encode): without --keep-alpha the `alpha` verification step fails (reason alpha_dropped, attribution artifact, with an alpha_dropped warning); with --drop-alpha there is no such step and a note says the alpha was dropped on purpose. Absent on a source without alpha"}
     if name == "color":
-        out["alpha_codec"]["description"] += ". --correct / --lut only: the grade works on the colour (at 4:4:4) and the source's alpha is merged back unchanged; the `alpha` step compares the written alpha with the source's frame by frame, tolerance 2 of 255 (comparison {ok, paired, worst_delta, worst_frame}; frames {expected, measured}; written {codec, pix_fmt, alpha_plane})"
+        out["alpha_codec"]["description"] += ". --correct / --lut only: the grade works on the colour (at 4:4:4) and the source's alpha is merged back onto that 8-bit picture (an 8-bit alpha unchanged; a 10- or 12-bit ProRes 4444 alpha keeps 8 bits of precision); the `alpha` step compares the written alpha with the source's frame by frame, tolerance 2 of 255 (comparison {ok, paired, worst_delta, worst_frame}; frames {expected, measured}; written {codec, pix_fmt, alpha_plane})"
     else:
         out["alpha_codec"]["description"] += ". Drawn on the input's alpha at 4:4:4 (layers composited with their alpha, text drawn into it); the `alpha` step (property alpha_at_least_source) passes when the written stream stores an alpha plane, every frame's alpha is at or above the source's (tolerance 2 of 255) and the output did not turn opaque in every frame the source was transparent in (reason: opaque_everywhere, alpha_below_source or no_alpha_plane when it fails)"
     out["alpha_codec"]["description"] += ". A source that stores an alpha plane whose alpha could not be read is never taken as opaque: its step fails with reason source_alpha_unmeasured"
@@ -608,6 +609,60 @@ NON_AV_STREAM_TOOLS = frozenset({"audio", "broll", "color", "cut", "deinterlace"
                                  "sphere", "straighten"})
 
 
+# Top-level keys a tool emits that its own branch in output_schema() does not list (#466 A194: the
+# schemas were written by hand and left these out). tests/test_contract.py's
+# test_every_emitted_top_level_key_is_in_the_output_schema runs each tool and fails on a key that
+# is in neither.
+EMITTED_KEYS: Dict[str, Dict[str, Any]] = {
+    "cropdetect": {
+        "file": {"type": "string", "description": "the input path, as given"},
+        "source_width": {"type": "integer", "description": "the displayed frame's width (a 90/270 degree rotation swaps the stored size; a non-square-pixel source is squared at its display aspect): the frame crop and motion_centre are in"},
+        "source_height": {"type": "integer", "description": "the displayed frame's height, as source_width"},
+        "crop": {"type": ["object", "null"], "description": "{width, height, x, y}: the rectangle cropdetect read most often over the sampled windows, in source pixels (the full frame when there are no bars); null when it produced no reading"},
+        "confidence": {"type": "number", "description": "present with a crop: the share of readings (0..1) that gave that rectangle"},
+        "motion_centre": {"type": "array", "description": "--motion-centre only: [{time, x, y, x_frac, y_frac, motion}] per second over the same windows; x/y null for a window with no measured motion. Report only"}},
+    "graphics": {
+        "template": {"type": "string", "description": "the --template drawn"},
+        "text_renderer": {"enum": ["ass", "drawtext"], "description": "what drew the text: libass (a generated .ass) or drawtext"},
+        "script": {"type": "string", "description": "the writing system detected in the text, which picks the font (latin, han, ...)"},
+        "ass": {"type": "string", "description": "text_renderer ass only: the generated .ass path (--write-ass, else <output>_gfx.ass); under --dry-run the path that would be written"},
+        "emoji": {"type": "object", "description": "text with emoji only: {mode, count, clusters, assets, missing, overlays}"},
+        "broken_inside_word": {"type": "integer", "description": "present when above 0: words hard-sliced because they did not fit a line alone"}},
+    "loudness": {
+        "loudnorm_mode": {"enum": ["linear", "dynamic"], "description": "--dry-run only (a real run reports it in result): the mode loudnorm's planned pass 2 runs in for the measured input"}},
+    "join": {
+        "reencoded": {"type": "boolean", "description": "--copy --transition none only: false, the clips were joined by stream copy"},
+        "audio_substituted": {"type": "array", "items": {"type": "string"}, "description": "a re-encoded video join: the clips with no audio stream, whose span of the join is generated silence (notes says the same); [] when every clip has sound"},
+        "inputs_duration": {"type": ["number", "null"], "description": "the clips' own total length, seconds"},
+        "transition_shortening": {"type": ["number", "null"], "description": "how much the transitions took out of inputs_duration, seconds"}},
+    "multicam": {
+        "inputs": {"type": "array", "items": {"type": "string"}, "description": "the input paths as given, reference first; a camera number in cuts indexes this list"}},
+    "broll": {
+        "cutaways": {"type": "array", "description": "[{insert, at, end, from}] per cutaway: the B clip, where it starts and ends on A's timeline (seconds), and where in B it starts"},
+        "audio": {"enum": ["a", "b", "mix"], "description": "--audio: what plays under a cutaway"}},
+    "grid": {
+        "cols": {"type": "integer"}, "rows": {"type": "integer"},
+        "clips": {"type": "integer", "description": "how many input clips the grid holds"}},
+    "scenes": {
+        "highlights": {"type": "array", "description": "--highlights only: [{start, end, duration}] the proposed ranges"},
+        "highlights_total": {"type": "number", "description": "--highlights only: the ranges' total seconds"},
+        "highlights_rank_by": {"enum": ["audio", "duration"], "description": "--highlights only: --rank-by"},
+        "sheet": {"type": "string", "description": "--sheet only: the contact sheet path (under --dry-run the path that would be written; nothing is drawn)"}},
+    "batch": {
+        "jobs": {"type": "integer", "description": "the parallelism actually applied"},
+        "jobs_requested": {"type": ["integer", "null"], "description": "the --jobs asked for (auto resolved to a number)"},
+        "wall_seconds": {"type": "number", "description": "the batch's wall clock"},
+        "item_seconds_total": {"type": "number", "description": "the sum of the per-item times"},
+        "timed_out": {"type": "boolean", "description": "whether the shared --timeout budget ran out (a timed-out item's row carries skipped: timeout)"}},
+    "render": {
+        "template": {"type": "string", "description": "--write-project only: the template the written project was filled from"},
+        "pack": {"type": "array", "description": "--template naming several destinations (a social pack) only: one row per destination {platform, file, path, size_bytes, duration, check, guidance, ok}; output is then the <stem>_pack.md table"},
+        "outputs": {"type": "array", "items": {"type": "string"}, "description": "a social pack only: each destination's output path"}},
+    "report": {
+        "pack": {"type": "array", "description": "--pack only: the pack table's rows as {column: cell} objects, as read from the file"}},
+}
+
+
 def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str, Any]:
     """What the tool prints on stdout with --json (keys observed in the implementation). `hw`: the
     tool takes --hw, so its `notes` can also carry a VideoToolbox encode's quality line."""
@@ -618,7 +673,15 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                                "timecode": {"type": "object", "description": "3.0.0: the source's start timecode {value, drop_frame, source}: the first HH:MM:SS[:;.]FF timecode tag from the video stream, then a tmcd data stream, then the container; all three null when none carries one"},
                                "chapters": {"type": "array", "description": "the container's chapter markers [{index, start, end, title}]"},
                                "subtitle_stream_details": {"type": "array", "description": "every subtitle stream in file order [{index (the n of -map 0:s:n), codec, language, title, default (the stream's default disposition)}]"},
-                               "keyframes": {"type": "array", "description": "--keyframes-near only: one entry per time [{at, window, keyframes (the video keyframes within window seconds of it), before (the nearest of those at or before it, or null when none is within the window), after (at or after it, likewise)}], seconds from the file's start; a failed keyframe read fails the run (kind ffmpeg)"}},
+                               "keyframes": {"type": "array", "description": "--keyframes-near only: one entry per time [{at, window, keyframes (the video keyframes within window seconds of it), before (the nearest of those at or before it, or null when none is within the window), after (at or after it, likewise)}], seconds from the file's start; a failed keyframe read fails the run (kind ffmpeg)"},
+                               "start_time": {"type": ["number", "null"], "description": "where the container's timeline starts, seconds (an MPEG-TS file often starts above 0)"},
+                               "bitrate": {"type": ["integer", "null"], "description": "the container's overall bit rate, bits per second, as ffprobe reads it; null when it states none"},
+                               "subtitle_streams": {"type": "integer", "description": "how many subtitle streams the file carries"},
+                               "data_streams": {"type": "integer", "description": "how many data streams (a tmcd timecode track, telemetry) the file carries"},
+                               "stream_counts": {"type": "object", "description": "{video, audio}: picture streams (a cover picture is not one) and sound streams"},
+                               "tags": {"type": "object", "description": "the container's title, artist, album, comment, date and genre tags that are set, keys lower-cased"},
+                               "audio_streams": {"type": "array", "description": "every audio stream in file order [{index (the n of -map 0:a:n), codec, channels, channel_layout, sample_rate, language, title}]"},
+                               "levels": {"type": "object", "description": "--analyze only, on an input with a video stream: picture levels sampled at 2 fps over the first 20 s, on an 8-bit scale inferred from the values measured (a 10-bit or deeper picture whose luma never passes code 255 is read as 8-bit and left unscaled) {scale, y_min, y_max, y_avg, y_low_p5, y_high_p95, saturation_avg, looks_like_log, note}; {error} when no frame was analysed. Measured under --dry-run too"}},
                 "additionalProperties": True}
     base = {"status": {"enum": ["completed"]}, "output": {"type": ["string", "null"], "description": "path written, or null"},
             "dry_run": {"type": "boolean"}, "commands": {"type": "array", "items": {"type": "string"}, "description": "the ffmpeg command lines this run planned or ran to write its output (render.py and waveform.py: their stages' too); a measurement pass is listed only where the tool records it (e.g. loudness.py pass 1, check.py, stabilize.py pass 1), and batch.py lists none of its steps' (each results row's step documents carry their own)"},
@@ -688,7 +751,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "guides": {"type": "array", "description": "--guides only: each outline drawn on the PNG, {guide: action|title, fraction (0.93 / 0.90 of the frame, SMPTE ST 2046-1), of: frame} or {guide: 4:3, window, action: 0.90, title: 0.80}; drawn on the preview only"}}
     elif name == "render":
         extra = {"stages": {"type": "array", "items": {"type": "string"}}, "check": {"type": ["object", "null"], "description": "check.py's document for a \"check\" stage with a platform, \"content\": true, or both; when check.py printed none, a failure document with error.reason check_output_unparsed"},
-                 "cache": {"type": ["object", "null"], "description": "--cache: {dir, ffmpeg, hits, misses, miss_reasons: [{stage, reason: not_cached|sidecar_missing|artifact_missing|sidecar_corrupt|artifact_truncated|no_output_path, ...}], saved_seconds, entries, would_hit (--dry-run)}"},
+                 "cache": {"type": ["object", "null"], "description": "--cache: {dir, ffmpeg, hits, misses, miss_reasons: [{stage, reason: not_cached|sidecar_missing|artifact_missing|sidecar_corrupt|artifact_truncated|no_output_path|destination_not_owned, ...}], saved_seconds, entries, would_hit (--dry-run)}"},
                  "caption": {"type": ["object", "null"], "description": "the caption stage's own block, forwarded verbatim from caption.py (cue-layout counts and fit-size keys); null without a caption stage"},
                  "snap": {"type": ["object", "null"], "description": "a project's \"snap\": cut.py's snap block for the first snapped clip, with every clip's in clips; null when nothing was snapped"},
                  "intermediate_preset": {"type": ["string", "null"], "description": "2.15: the x264/x265 preset the stages before an encoding export ran at (--intermediate-preset, default superfast since 2.16); null when no stage received it (no encoding export reached, --fast, --stop-after before the export, a copy export, or nothing but the export encoded)"},
@@ -700,7 +763,10 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "tool_result": {"type": "object", "description": "plan execution: the tool's own --json document"},
                  "timeline": {"type": "object", "description": "--export-timeline: format, rate, duration, frames, clips, transition, "
                               "transition_frames, music, markers, notes, and not_exported (what the project asks for that an "
-                              "editor timeline cannot carry)"}}
+                              "editor timeline cannot carry)"},
+                 "templates": {"type": "array", "description": "--list-templates --json: one row per shipped template, {template, "
+                               "destination, frame: {width, height} or null (audio), fit, max_duration, lufs, safe: {top, bottom, "
+                               "left, right}}; without --json the same rows are a table"}}
     elif name == "verify":
         extra = {"report": {"type": ["string", "null"]},
                  "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}"},
@@ -781,7 +847,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "drift_ppm": {"type": "array", "items": {"type": ["number", "null"]}, "description": "--fix-drift: per input, the drift measured against the reference (the reference itself 0, the clock); null for a camera whose drift was not measured, with the reason in drift_skipped_reason (also a diagnostics.skipped entry, drift_correction_skipped)"},
                  "drift_skipped_reason": {"type": "array", "items": {"enum": ["too_short", "low_confidence", None]}, "description": "--fix-drift: per input, why its drift was not measured (too_short: no tail window far enough from the head; low_confidence: the tail did not correlate), null when it was and for the reference"}}
     elif name == "join":
-        extra = {"mode": {"enum": ["video", "audio"]}, "clips": {"type": "integer"}, "transition": {"type": "string"},
+        extra = {"mode": {"enum": ["video", "audio", "copy"], "description": "copy: --copy --transition none wrote a stream copy"}, "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"},
@@ -802,6 +868,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "present with `silent`: which tracks were silent and how to refuse them"},
                  "timing": {"type": "object", "description": "#486: {tempo, atempo, length_samples, sample_rate}: the --tempo factor (null without it), the atempo stages (each 0.5..2.0, [] at tempo 1) whose product it is, --length-samples (null without it) and the sample rate that count is in (null when not measured yet); with --length-samples a length_samples verification step counts the written track's decoded samples (exact for PCM/FLAC/ALAC, within tolerance_samples, one codec frame, for a lossy codec)"},
                  "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, channel (--channel N, the 0-based channel kept, else null), sample_rate (--sample-rate, else null; both are read back from the output as the channels / sample_rate verification steps), effects/effects_volume, and with --music the music_volume plus duck (null when --duck was not given, else the threshold in dB and linear, ratio, attack_ms, release_ms, amount_db actually used)"}}
+    for key, prop in EMITTED_KEYS.get(name, {}).items():
+        extra.setdefault(key, prop)
     if name in ("overlay", "graphics", "caption", "grid"):
         extra["font_used"] = FONT_USED_SCHEMA
     if name in ALPHA_LINE_TOOLS:
@@ -1672,6 +1740,18 @@ def _merge_optional(base: List[Dict[str, Any]], extra: List[Dict[str, Any]]) ->
     return out
 
 
+_SENTENCE_END = re.compile(r"(?<!\be\.g)(?<!\bi\.e)(?<!\betc)[.!?](?=\s|$)")
+
+
+def summary_sentence(docstring: str) -> str:
+    """The docstring's first sentence, its wrapped lines joined (#466 A195: the first physical line
+    cut 16 descriptions mid-phrase). A first paragraph with no full stop is taken whole."""
+    para = re.split(r"\n\s*\n", docstring.strip(), maxsplit=1)[0]
+    joined = " ".join(line.strip() for line in para.splitlines())
+    end = _SENTENCE_END.search(joined)
+    return joined[:end.end()] if end else joined
+
+
 def tool_spec(name: str, version: str) -> Dict[str, Any]:
     if name not in TOOL_META:
         # a public script without metadata is drift: fail loudly instead of guessing its role or capabilities
@@ -1696,7 +1776,7 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
         "id": f"{SKILL_ID}/{name}",
         "name": name,
         "version": version,
-        "description": (parser.description or "").strip().splitlines()[0] if parser.description else "",
+        "description": summary_sentence(parser.description or ""),
         "executable": f"scripts/{name}.py",
         # 1.20.0: SKILL.md's own request-table rows for this tool, machine-readable
         "examples": skill_examples().get(name, []),
@@ -2079,7 +2159,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
                                       "hidden .<output>.ffskill-audit.jsonl beside the output, and a cache event's .ffskill-audit.jsonl in the "
                                       "cache directory (render.py --cache DIR) or the batch's output_dir. Never written under --dry-run; a write that "
                                       "fails is a diagnostics.warnings entry (audit_log_unwritable), never a failure"},
-            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH, or older than the supported 6.1 (error.reason ffmpeg_unsupported)", "timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT) and was killed; partial output removed; exit 124", "verification": "the tool ran but its result failed the requested check: check.py platform rows (checks attached), render.py's check stage (output written, check attached), batch.py items (results attached), verify.py steps (files attached), color.py --retag (output written, but ffprobe does not read the requested colour tags on it); exit 1", "interrupted": "the tool received SIGINT or SIGTERM: the running ffmpeg (or sibling script) was stopped and its partial output removed; exit 130 or 143"},
+            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "something the run needs is not installed: ffmpeg or ffprobe not on PATH, or older than the supported 6.1 (error.reason ffmpeg_unsupported) (both exit 127); an encoder this build lacks for --codec, an export.py preset or an alpha line (encoder_missing); the libvpx-vp9 decoder for a VP9 source with an alpha layer (decoder_missing); no local speech-to-text engine for --transcribe (asr_engine_missing), or a named --engine that is not installed (these exit 1)","timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT; verify.py's --timeout is per step, default 600 s) and was killed; partial output removed; exit 124", "verification": "the tool ran but its result failed the requested check: check.py platform rows (checks attached), render.py's check stage (output written, check attached), a render.py --template social pack with a destination that failed (pack rows attached; a destination that timed out or was interrupted gives that kind instead), batch.py items (results attached), verify.py steps (files attached), color.py --retag (output written, but ffprobe does not read the requested colour tags on it), loudness.py (output written, its true peak still above --tp after the re-encodes; result attached), join.py --copy (the stream-copied join does not hold the clips it was given; it is not moved to the output path, verification attached); exit 1", "interrupted": "the tool received SIGINT or SIGTERM: the running ffmpeg (or sibling script) was stopped and its partial output removed; exit 130 or 143"},
             "success_criterion": "exit 0 AND the output exists AND is non-empty AND ffprobe reads a stream from it; only then is status completed printed and the output probe attached",
         },
         "capabilities": caps,

package/scripts/batch.py

@@ -37,7 +37,8 @@ from _common import STATE, add_common, apply_common, child_args, die, emit, info
 from _common.runner import (HW_FORCED_ENV, OWNED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw, read_json,
                             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
+from _common.decision import NO_DEFAULT_ENCODE_EXT, rebase_project_paths
+from _common.runner import parse_json
 
 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
@@ -51,9 +52,16 @@ ALLOWED_STEP_SCRIPTS = {p.name for p in HERE.glob("*.py") if not p.name.startswi
 
 
 def file_key(path: Path) -> str:
+    """A cheap change detector: the name, the size, the modification time in nanoseconds and the
+    first and last MiB. A rewrite of the middle of a file keeps its size and its ends, so the
+    modification time is what tells it apart: in whole seconds (up to 3.8.4) two writes within
+    one second shared a key, and the old output was served as cached. A file whose mtime is reset
+    to the earlier value (``touch -r``, a copy that preserves it) or a filesystem that keeps
+    whole seconds (FAT keeps two) still shares one; hashing every byte would cost a read of the
+    whole file per item per run (docs/design-decisions.md, "After 3.8.4")."""
     st = path.stat()
     h = hashlib.sha1(usedforsecurity=False)  # a change detector, not a secret
-    h.update(f"{path.name}|{st.st_size}|{int(st.st_mtime)}".encode())
+    h.update(f"{path.name}|{st.st_size}|{st.st_mtime_ns}".encode())
     with open(path, "rb") as fh:  # first and last MB: cheap and good enough to detect changes
         h.update(fh.read(1 << 20))
         if st.st_size > 2 << 20:
@@ -86,6 +94,30 @@ def side_inputs_key(recipe: Dict[str, Any]) -> str:
     return h.hexdigest()[:8]
 
 
+def caseless_glob(pattern: str) -> str:
+    """`pattern` with every letter outside a [...] class matched in either case: "*.mp4" finds
+    GOPR0001.MP4, as it already did on macOS's and Windows' default filesystems, so a recipe means
+    the same files on every platform (A82: on Linux a camera folder was an empty batch). pathlib's
+    case_sensitive= needs Python 3.12; 3.10 is the floor."""
+    out: List[str] = []
+    in_class = False
+    first = -1  # index of the class's first member: a "]" there is a member, not the end ("[]a]", "[!]a]")
+    for i, ch in enumerate(pattern):
+        if in_class:
+            out.append(ch)
+            if ch == "]" and i > first:
+                in_class = False
+        elif ch == "[":
+            first = i + 2 if pattern[i + 1:i + 2] == "!" else i + 1
+            in_class = "]" in pattern[first + 1:]  # an unclosed [ ("[!]x") is a literal character to fnmatch
+            out.append(ch if in_class else "[[]")
+        elif ch.isalpha() and ch.lower() != ch.upper():
+            out.append(f"[{ch.lower()}{ch.upper()}]")
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
 def recipe_key(recipe: Dict[str, Any]) -> str:
     # A "project" recipe is just {"project": "<path>", "clip_key": N} -- the actual settings
     # (export preset, captions, everything) live in the file at that path, not in this dict.
@@ -93,18 +125,57 @@ def recipe_key(recipe: Dict[str, Any]) -> str:
     # itself) left the key, and so every cache hit, unchanged: a preset swapped from "copy" to
     # "x" (a real re-encode) still served the old cached output. Fold the referenced file's own
     # content into the key so a content change invalidates the cache like any other edit would.
+    # main() calls this on every pass, so a --watch loop sees an edit made while it runs (A81).
     project_content = ""
     if recipe.get("project"):
         try:
             project_content = Path(recipe["project"]).read_text(encoding="utf-8")
         except (OSError, UnicodeDecodeError) as exc:
             # keyed on the recipe alone: an unreadable project cannot invalidate the cache by its
-            # content, so say so (each item that needs it then fails on reading it)
-            warn(f"recipe.project {recipe['project']} could not be read ({exc}); the cache key covers the recipe only",
-                 "recipe_project_unreadable", path=str(recipe["project"]), error=str(exc))
+            # content, so say so (each item that needs it then fails on reading it); once per run
+            entry = {"code": "recipe_project_unreadable", "path": str(recipe["project"])}
+            if not any(all(w.get(k) == v for k, v in entry.items()) for w in STATE.warnings if isinstance(w, dict)):
+                warn(f"recipe.project {recipe['project']} could not be read ({exc}); the cache key covers the recipe only",
+                     "recipe_project_unreadable", path=str(recipe["project"]), error=str(exc))
+        else:
+            project_content += "\0" + project_files_key(recipe, project_content)
     return hashlib.sha1((json.dumps(recipe, sort_keys=True) + "\0" + project_content).encode(), usedforsecurity=False).hexdigest()[:12]
 
 
+def project_files_key(recipe: Dict[str, Any], text: str) -> str:
+    """The files a project recipe's project names (music, cues, the brand and its logo and font,
+    overlay images and videos, the chapters file, every clip but the one each item replaces),
+    each keyed by its own content as file_key() keys a source (A80): an edited cue file or music
+    bed changes the output, so it has to change the key. The list is render.py's own
+    project_input_files(), read against the project file's directory as render reads it. A
+    project that does not parse adds nothing: each item then fails reading it."""
+    try:
+        proj = parse_json(text)
+    except ValueError:
+        return ""
+    if not isinstance(proj, dict):
+        return ""
+    from render import project_input_files  # here, not at the top: render.py imports this module
+    base = Path(str(recipe["project"])).resolve().parent
+    clips = proj.get("clips")
+    idx = int(recipe.get("clip_key") or 0)  # check_recipe_types() has refused anything else
+    if isinstance(clips, list) and idx < len(clips) and isinstance(clips[idx], dict):
+        # the clip every item replaces with itself: its placeholder is no input of any item
+        proj = dict(proj, clips=[dict(c, src=None) if i == idx else c for i, c in enumerate(clips)])
+
+    def rel(p: Any) -> str:
+        return str(p) if os.path.isabs(str(p)) else str(base / str(p))
+    h = hashlib.sha1(usedforsecurity=False)
+    for name in sorted(set(project_input_files(proj, rel))):
+        path = Path(name)
+        try:
+            ident = file_key(path) if path.is_file() else "-"
+        except OSError:
+            ident = "-"
+        h.update(f"{name}\0{ident}\0".encode())
+    return h.hexdigest()
+
+
 def gpu_key() -> str:
     """The GPU setting the steps resolve, as a suffix for the item cache key: a VideoToolbox file is
     not the CPU's bytes, so a --hw output is never served to a --no-hw run or the other way round
@@ -222,6 +293,11 @@ def final_path(src: Path, recipe: Dict[str, Any], outdir: Path) -> Path:
     # detection of its own; see one_pass()'s pre-flight check, which uses this same computation
     # to catch that before any file is actually processed (and the earlier one silently clobbered).
     final_ext = recipe.get("ext") or src.suffix.lstrip(".") or "mp4"
+    if not recipe.get("ext") and src.suffix.lower() in NO_DEFAULT_ENCODE_EXT:
+        # the #415 default-name rule (default_output()): the steps re-encode to x264/AAC, which a
+        # WebM cannot hold, so every .webm item was refused output_container_codecs (A83). A
+        # recipe that keeps WebM (a stream copy, export.py --preset vp9-alpha) sets "ext".
+        final_ext = "mp4"
     steps = recipe.get("steps") or []
     if not recipe.get("ext") and not recipe.get("project") and steps and not step_writes(steps[-1]) and not writes_nothing(recipe):
         # the last step writes nothing, so what is delivered is an intermediate: its name says its
@@ -649,7 +725,6 @@ def main() -> int:
             audit("batch_cache_reset", {"path": str(cache_path), "size": size, "error": str(exc)},
                   default_path=str(outdir / ".ffskill-audit.jsonl"))
             cache = {}
-    rkey = recipe_key(recipe) + gpu_key()
     glob = recipe.get("glob") or "*"
 
     # --jobs: every item is itself an ffmpeg that already threads across cores, so beyond a few
@@ -706,6 +781,7 @@ def main() -> int:
     # 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]"] = {}
+    shown_empty = {"done": False}
 
     def settle_poll(files: List[Path]) -> "set":
         if not args.watch:
@@ -728,7 +804,12 @@ def main() -> int:
         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)
+        files = sorted(p for p in folder.glob(caseless_glob(glob)) if p.is_file() and p.suffix.lower() in MEDIA_EXT and outdir not in p.parents)
+        if not files and not shown_empty["done"]:
+            # a batch of nothing completed with total 0 and not a word (A82): say what matched nothing
+            shown_empty["done"] = True
+            note(f"no media file in {folder} matches the recipe's glob {glob!r} (matched without regard to case); "
+                 "nothing was processed")
         # Two different sources can compute the same final path (most often a fixed recipe "ext"
         # collapsing e.g. clip.mp4 and clip.mov to the same clip_out.mp4) -- catch that before
         # processing anything, rather than letting the later one silently overwrite the earlier
@@ -805,7 +886,9 @@ def main() -> int:
         slots: "List[Optional[Dict[str, Any]]]" = [None] * len(files)
         pending: List[tuple] = []
         cache_miss: Dict[int, Dict[str, Any]] = {}
-        pass_key = rkey + side_inputs_key(recipe)
+        # read on every pass: a --watch loop serves nothing from an edited project.json, cue file or
+        # music bed (computed once before the loop, it did: A81)
+        pass_key = recipe_key(recipe) + gpu_key() + side_inputs_key(recipe)
         polled = settle_poll(files)
         for i, src in enumerate(files):
             if str(src) in polled:

package/scripts/export.py

@@ -484,7 +484,7 @@ def main() -> int:
     ap.add_argument("--max-mb", type=float, metavar="MB",
                     help="fit the file under MB megabytes (MiB): a two-pass x264 encode at the video bitrate the "
                          "running time leaves after the audio, measured afterwards (H.264 presets; not with --crf or --hw)")
-    ap.add_argument("--normalize", action="store_true", help="youtube/youtube4k/reels/x: when the written file misses the platform's loudness spec, run loudness.py on it (audio re-encoded, video copied) so one export delivers")
+    ap.add_argument("--normalize", action="store_true", help=f"the platform presets ({', '.join(sorted(PLATFORM_OF))}): when the written file misses the platform's loudness spec, run loudness.py on it (audio re-encoded, video copied) so one export delivers")
     ap.add_argument("--alpha-mode", choices=["straight", "premultiplied"],
                     help="alpha presets (prores4444, prores4444xq, qtrle, vp9-alpha, hap-alpha): write the colour straight "
                          "(default, as decoded) or premultiplied by the alpha; written to the result as alpha_mode")

package/scripts/graphics.py

@@ -55,6 +55,9 @@ from _common.emit import input_length  # noqa: E402
 TEXT = "@TEXT@"
 BOX = "@BOX@"  # a box's place in the filter chain, followed by its index (graphics.main fill_box)
 TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug", "sticker", "hook", "meme"]
+# --dry-run on an input that does not exist yet, with no --end: how long after --start the planned
+# graphic ends (its length is unknown; the plan says so in a note)
+PENDING_PLACEHOLDER_SECONDS = 10.0
 
 
 def ff_color(hex_rgb: str, alpha: float = 1.0) -> str:
@@ -208,7 +211,17 @@ def main(force_route: Optional[str] = None) -> int:
         info(f"--platform {args.platform}: safe margins top {m_top} / bottom {m_bottom} / left {m_left} / right {m_right} px")
     fps = meta["video"].get("fps")
     s = time_arg(args.start, "--start", fps) if args.start else 0.0
-    e = time_arg(args.end, "--end", fps) if args.end else input_length(meta)  # no --end is the clip's end (#491)
+    if args.end:
+        e = time_arg(args.end, "--end", fps)
+    elif meta.get("dry_run"):
+        # #466 A202: an input an earlier --dry-run stage would write is probe()'s stub, whose
+        # length is unknown, not 0 s: planning to "the clip's end" refused with "--end must be
+        # after --start". The plan ends the graphic at a stated placeholder instead
+        e = s + PENDING_PLACEHOLDER_SECONDS
+        note(f"{args.input} does not exist yet, so its length is unknown: the planned graphic ends at a placeholder "
+             f"{e:g} s; a real run ends it at the clip's end (or pass --end)")
+    else:
+        e = input_length(meta)  # no --end is the clip's end (#491)
     # the picture's own length first: sound that runs on keeps the container open past the last frame
     picture_len = meta["video"].get("duration") or dur
     if picture_len and s >= picture_len:

package/scripts/metadata.py

@@ -52,6 +52,10 @@ def parse_chapters(path: str, duration: float) -> List[Dict[str, Any]]:
         # chapter files carry no fps, so hh:mm:ss:ff needs its @fps suffix; time_arg() says so
         start = time_arg(parts[0], f"{path}:{n}")
         title = parts[1].strip() if len(parts) > 1 else f"Chapter {len(entries) + 1}"
+        if "\x00" in title:
+            # FFmpeg ends a metadata value at NUL: "A\x00B" was written as "A", verified (the
+            # sibling of A260 in render.py's inline chapters)
+            die(f"{path}:{n}: the chapter title holds a NUL character, which a chapter title cannot carry; remove it")
         if entries and start <= entries[-1]["start"]:
             die(f"{path}:{n}: chapter at {start:g}s does not come after the previous one at {entries[-1]['start']:g}s")
         if duration and start >= duration: