ffmpeg-skill 2.17.4 → 2.18.0

package/SKILL.md

@@ -150,7 +150,6 @@ Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`,
 | "where does the subject move, so I can crop it myself" | `cropdetect.py input.mp4 --motion-centre` — motion centroid per second, report-only; the calling agent picks the crop |
 | "does it look like Log / S-Log?" | `probe.py clip.mp4 --analyze` (`looks_like_log`) then `color.py --lut` |
 | "test the tool on my real files" | `verify.py ~/Footage --report verify.md` |
-| "show me progress", "quick preview first" | any encoding script with `--progress` and/or `--fast` |
 | "it's a phone video with variable frame rate" | nothing extra: re-encodes conform VFR to constant fps; `fit.py --fps 30` picks the rate |
 
 ## Audio-only files
@@ -181,7 +180,7 @@ Look: final_sheet.png（字幕はセーフエリア内、ロゴは右上）
 Notes: 元は VFR だったので 30 fps に揃えた。音声はモノラルだったのでステレオにした
 ```
 
-Keep it to those five lines plus anything the user must decide. Never describe a fix you did not run.
+Keep it to those five lines plus anything the user must decide. Never describe a fix you did not run. `verified` covers only what was measured: in `Notes:` name any `unverified` item the user would assume checked. Report a step with `attribution: unresolved`; do not re-run it.
 
 When a step fails, replace `Done:` with `Failed:` and keep the rest honest:
 
@@ -196,9 +195,7 @@ Notes: send a valid .cube, or say if you want the clip left as is
 Those filler lines are sentences, not labels: the same report for a Japanese request ends
 `Check: 検証するものなし` / `Look: 不要`.
 
-A refusal uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run, `Look: not needed`. A partial result is `Done:` with the shortfall in `Notes:`; a refusal that still delivers something is `Failed:` — never a third label like `Done (partially):`. Quote a failure's `error.hint` in `Notes:`.
-
-A failure's `--json` is `status: failed` plus `error.kind` and `error.message`; quote the message, never paraphrase it.
+A refusal uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run, `Look: not needed`. A partial result is `Done:` with the shortfall in `Notes:`; a refusal that still delivers something is `Failed:` — never a third label like `Done (partially):`. A failure's `--json` is `status: failed` plus `error.kind`, `error.message` and `error.hint`: quote the message in `Failed:`, never paraphrase it, and the hint in `Notes:`.
 
 ## Things that look right but are wrong
 

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.17.4`) | any release |
+| `skill.version` | the npm / package.json version (`2.18.0`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -131,7 +131,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [{"what": "running on Python 3.9 (the requirements.python floor)", "since": "2.10.9", "replacement": "Python 3.10 or later; ...", "removed_in": "3.0.0", "where": "behaviour"},
                  {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.17.4", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.18.0", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0 (5.x deprecated since 2.14.0, removed in 3.0.0; 6.1+ recommended)", "ffprobe": ">=5.0"},
@@ -169,6 +169,7 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:
 | `produces_artifact` | writes a file (media, PNG, HTML, EDL) |
 | `verification` | `{required, tools}`: which tools to run on the output afterwards |
 | `requires_visual_verification` | the picture changed; run `ffmpeg-skill/look` and inspect the PNG |
+| `unverified_properties` | 2.18: the output properties this tool does not measure, the same list its results carry as `unverified` (empty when the tool names none) |
 | `reencodes_video`, `reencodes_audio` | `"always"` / `"never"` / `"conditional"`, meaning *when that stream is present in the input* — not whether the tool touches the file at all. `"conditional"` tools (`cut`, `export`, `render`, `batch`, `verify`, `caption`, `color`) carry a `reencode_note` explaining what it depends on — for `caption`, `--mode burn` (default) always re-encodes both streams, `--mode mux` copies both untouched; for `color`, `--strip-dovi` and `--retag` are a stream copy of both (retag only re-encodes if the copy attempt fails or ffprobe still reads the old tags on the copy), while `--to-sdr` / `--lut` / `--correct` always re-encode both. Several visual tools (`fit`, `overlay`, `graphics`, `join`, `multicam`, `silence`) are `"always"` on audio too: this codebase never mixes `-c:v` re-encode with `-c:a copy` in one call, so a caller cannot assume the original audio codec survives just because only the picture changed |
 | `audio_only` | accepts an audio-only input (WAV, MP3, M4A, FLAC, OGG, Opus) |
 | `video_required` | refuses an input without a video stream ("input has no video stream") |
@@ -685,6 +686,19 @@ Per-tool keys added after 2.2.2, all additive:
 | `vfr_check` | `cut.py` (a video input that could still stream-copy) | the sampled frame timing, `{heuristic: true, measured, method: "sampled", guard, windows, deltas}`; `measured` is `sampled_cfr`, `vfr` or `inconclusive`. `--vfr-guard average` (the default) keeps the 2.x guard: a source whose nominal and average frame rates differ (`variable_frame_rate_suspected`) re-encodes as `--accurate` (reason `vfr`, stderr says "variable-frame-rate"), and only then is the timing sampled and reported, with a `notes` line naming `--vfr-guard sampled` when it measured `sampled_cfr`; the key is absent otherwise. `--vfr-guard sampled` samples before every copy and re-encodes on `vfr` (reason `vfr`) or `inconclusive` (fewer than 20 intervals; `vfr_inconclusive`); `--vfr-guard off` samples and keeps the copy, with a `notes` line. Absent for audio-only input or output, `--accurate`, `--codec` and a pending `--dry-run` input |
 | `join_check`, `segment_end_snap_seconds` | `cut.py --segments` | `join_check`: a video stream-copy join measured by demuxing, `{packets, expected_packets, max_step_seconds, audio_offset_ms, audio_parts_checked, ok}`. `expected_packets` counts the source's video packets from each part's start keyframe to its end (or the end of the video); `max_step_seconds` is the largest presentation step, `null` when `vfr_check` measured anything but `sampled_cfr` (a `--vfr-guard off` join of variable timing: count only), and each step at a join must be the step its parts predict within 1 ms. `audio_offset_ms`: per part, its sound's shift minus its picture's in ms (+ = sound late), from audio packets matched by CRC32 to the source stream shaped like the joined audio (FFmpeg's default selection may copy one other than `a:0`; an MPEG-TS source's AAC is hashed without its ADTS headers); `null` for a part with no unique match (digital silence, a periodic tone), and as a whole when the source has no audio or the video check failed. `audio_parts_checked` counts the measured parts. `ok` is the conjunction (count, steps, every measured part within 5 ms); `ok: false` means the join was re-cut (`concat_fallback`) and this is the failed measurement. `null` for a single segment, audio, `--dry-run`, any re-encode forced for every segment, a segment that re-encoded, or a join re-cut before a copy was tried (open GOPs, a later B-frame segment starting between keyframes, parts that differ, a concat error). `segment_end_snap_seconds`: per segment, the signed seconds its end moved to the keyframe the copied part stops at, the first at or after the requested end (`null` for a part that reaches the end of the video, a part of a source with no B-frames, cut to its requested end as in 2.5.1, or a Matroska/MPEG-TS part, which is not snapped); `null` as a whole unless the output is those copied parts |
 
+Keys added in 2.18, all additive. They make a result carry what the VDC paper
+(Verification-Driven Coding) calls the co-reported items: what was measured against what, how far,
+from where the expected value came, and what was not measured.
+
+| key | tool | what it holds |
+|---|---|---|
+| `verification[].property`, `expected`, `measured`, `delta`, `tolerance`, `provenance` | steps that measure a property (join's `duration`, loudness's `loudness`, export's `loudness`, every `streams` step) | the property measured, its expected and measured values, their difference, the tolerance applied, and where the expected value came from: `specification` (the platform table), `user_specified` (a flag), `independent_measurement`, or `input_premeasurement` (the input's own probe) |
+| `verification[]` step `streams` | `cut.py`, `join.py`, `export.py` | the output's video/audio streams against the ones the input had and the operation was not told to drop (an audio extension drops the picture, a GIF the sound). A missing stream is `ok: false` with `missing`, so the result is `verified: false` (#367: a TS cut that lost its video) |
+| `verification[].attribution` | any step with `ok: false` | `unresolved` until a tool knows whether the artifact, the reference, the measuring instrument or the expected value's provenance is at fault. A caller does not re-run on an unresolved failure: a re-run can hide which one it was |
+| `unverified` | every writing tool `UNVERIFIED` names (`_common/emit.py`) | the output's properties this tool did not measure, e.g. `caption`'s `rendered_placement`, `sync`'s `lip_sync`. `verified` is about the measured properties only; a report that passes the verdict on must pass this list with it. The contract carries the same list per tool as `unverified_properties` |
+| `audio_substituted` | `join.py` (video join) | the clips that had no audio stream, whose span of the join is generated silence; `notes` says the same |
+| loudness `tolerance.tp` | `loudness.py`, `export.py`, and `check.py`'s true-peak row | the one dBTP margin every tool applies (`_platforms.TP_TOLERANCE_DB`, 0.1 dB); before 2.18 it was 0.1, 0.05 and 0.0 in the three tools |
+
 Per-tool keys added after 2.10.11 ("nothing happens silently"), all additive:
 
 | key | tool | what it holds |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.17.4",
+  "version": "2.18.0",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/scripts/_common/emit.py

@@ -372,6 +372,45 @@ def steps_encoder_report(steps: Sequence["Tuple[str, Any]"]) -> Dict[str, Any]:
     return out
 
 
+# The properties each writing tool does NOT measure about its output, by tool name: the unverified
+# range U that every --json result reports (docs/contract.md "unverified"). A property listed here
+# is one a caller might assume was checked; naming it is the difference between "verified" meaning
+# "the listed properties were measured" and "everything is fine". Kept beside emit() so a tool
+# cannot report verified without this list travelling with it.
+UNVERIFIED: Dict[str, List[str]] = {
+    "cut": ["picture_content"],
+    "join": ["picture_content", "transition_look"],
+    "fit": ["subject_framing"],
+    "crop": ["subject_framing"],
+    "caption": ["rendered_placement", "legibility"],
+    "overlay": ["rendered_placement"],
+    "graphics": ["rendered_placement"],
+    "color": ["grade_look"],
+    "export": ["picture_content"],
+    "render": ["picture_content", "rendered_placement"],
+    "silence": ["removed_span_content"],
+    "audio": ["mix_balance"],
+    "loudness": ["perceived_loudness"],
+    "sync": ["lip_sync"],
+    "multicam": ["lip_sync", "shot_choice"],
+}
+
+
+def stream_inventory_step(meta: Dict[str, Any], expect: Dict[str, bool]) -> Dict[str, Any]:
+    """The output's stream composition checked against what the operation should have produced
+    (#367: a cut of an MPEG-TS source lost its whole video stream and still said verified: true,
+    because the only properties measured were duration and start skew). `expect` comes from the
+    input's own probe and the tool's arguments (provenance "input_premeasurement"): a stream the
+    input had and the operation was not told to drop must still be there."""
+    measured = {kind: bool(meta.get(kind)) for kind in expect}
+    missing = [k for k, want in expect.items() if want and not measured[k]]
+    step: Dict[str, Any] = {"step": "streams", "property": "stream_inventory", "expected": dict(expect),
+                            "measured": measured, "provenance": "input_premeasurement", "ok": not missing}
+    if missing:
+        step["missing"] = missing
+    return step
+
+
 def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any) -> None:
     """Final stdout line: the output path, or a JSON document with --json.
 
@@ -392,13 +431,22 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
         # only when the file was written, probed, and every self-check met its target; a dry run
         # verified nothing. Spec failures the tool cannot fix on its own (export's loudness gap)
         # keep status completed and say verified: false, so a caller keys on one field.
+        expect_streams = extra.pop("expect_streams", None)
         steps: List[Dict[str, Any]] = ([{"step": "probe", "ok": True}] if meta else []) + list(extra.pop("verification", None) or [])
+        if meta and expect_streams:
+            steps.append(stream_inventory_step(meta, expect_streams))
         # a tool that ran others (render.py) verified what its stages verified too (absorb_stage())
         steps += [s for s in ctx.stage_verification if s not in steps]
         if output and not ctx.dry_run and os.path.splitext(output)[1].lower() not in MEDIA_EXT:
             steps.insert(0, {"step": "exists", "ok": True})
         doc["verified"] = not ctx.dry_run and bool(steps) and all(s.get("ok") for s in steps)
+        # a failed check asserts that something in artifact, reference, instrument or the expected
+        # value's provenance is wrong; until a tool knows which, it says it does not know
+        steps = [dict(s, attribution=s.get("attribution") or "unresolved") if s.get("ok") is False else s for s in steps]
         doc["verification"] = steps
+        tool = os.path.splitext(os.path.basename(sys.argv[0] or ""))[0]
+        if output and not ctx.dry_run and tool in UNVERIFIED and "unverified" not in extra:
+            doc["unverified"] = list(UNVERIFIED[tool])
         doc.update(_encoder_report(ctx))
         doc.update(extra)
         hw_notes = [n for n in _hw_notes_for(ctx) if n not in (doc.get("notes") or [])]

package/scripts/_contract.py

@@ -536,7 +536,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
             "hw": {"type": "object", "description": "present when VideoToolbox was asked for (--hw, $FFMPEG_SKILL_HW, a render.py stage, a batch.py item), on export.py when $FFMPEG_SKILL_HW=1 is set but its delivery preset does not take it, and when this ffmpeg build has no libx264/libx265 and an encode ran on VideoToolbox instead: {requested: whether this run's encodes were asked onto VideoToolbox (false for that export, and for the build without libx264/libx265), source: flag|env|auto (auto: nobody asked, the build has no libx264/libx265 and this Apple Silicon machine ran VideoToolbox in its place), used: true|false whether the encoder that ran last is VideoToolbox, null under --dry-run (nothing ran) and when this process ran no encode itself (batch.py: its stages are child processes; its top-level hw gathers the items' requested/source/fallback/notes and each results row carries its item's encoder and hw), fallback: a job VideoToolbox refused (encoder open or compression session failure; nothing else is retried) was re-encoded on the CPU, notes: why an encode stayed on or fell back to the CPU, and, when $FFMPEG_SKILL_HW chose the GPU and it ran, what that costs and that --no-hw opts out}. A VideoToolbox encode also adds a top-level notes line: its quality is not CRF-equivalent. A kind: ffmpeg failure under --hw / $FFMPEG_SKILL_HW carries encoder and hw too"},
             "plan": {"type": "string", "description": "with --plan FILE: the plan document written (the run itself is a dry run)"},
             "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"}}}, "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"},
+            "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"},
             "diagnostics": DIAGNOSTICS_SCHEMA}
     extra: Dict[str, Any] = {}
     if name == "check":
@@ -683,6 +684,13 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
     return {"type": "object", "properties": props, "required": required, "additionalProperties": True}
 
 @functools.lru_cache(maxsize=1)
+def _unverified_table() -> Dict[str, List[str]]:
+    """emit()'s per-tool unverified range, read where the results are made so the two cannot differ."""
+    sys.path.insert(0, str(ROOT / "scripts"))
+    from _common.emit import UNVERIFIED
+    return UNVERIFIED
+
+
 def skill_examples() -> Dict[str, List[Dict[str, Any]]]:
     """1.20.0: per-tool `examples`, parsed from SKILL.md's "User says" / "Do" table -- the
     same facts that table already states, machine-readable instead of prose-only. A row
@@ -1547,6 +1555,8 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
         "reencodes_audio": REENCODE_META.get(name, {}).get("audio", "conditional"),
         **({"reencode_note": REENCODE_META[name]["note"]} if REENCODE_META.get(name, {}).get("note") else {}),
         "requires_visual_verification": meta["visual"],
+        # 2.18: what `verified` does not cover for this tool (the result's `unverified`)
+        "unverified_properties": list(_unverified_table().get(name, [])),
         "audio_only": meta["audio_only"],
         "video_required": meta["video_required"],
         "deterministic_inputs": meta["deterministic"],

package/scripts/_platforms.py

@@ -55,6 +55,13 @@ _NO_SAFE = {"top": 0.0, "bottom": 0.0, "left": 0.0, "right": 0.0}
 _CAP_VERTICAL = {"size": 0.0833, "position": "bottom", "box": False, "outline": 2, "animate": "pop"}
 _CAP_WIDE = {"size": 0.0694, "position": "bottom", "box": False, "outline": 2, "animate": "none"}
 
+# The one true-peak tolerance every tool applies to a dBTP ceiling, reported beside the verdict.
+# Before 2.18 loudness.py allowed +0.1 dB, check.py +0.05 and export.py 0.0, so "verified" meant a
+# different scale in each tool and export could fail a file check passed (the VDC paper's
+# sensitivity run). 0.1 dB is loudness.py's margin: two loudnorm passes on the same encode differ
+# by up to that much, so a tighter rule fails a file on measurement noise.
+TP_TOLERANCE_DB = 0.1
+
 PLATFORMS: Dict[str, Dict[str, Any]] = {
     "tiktok": {
         "title": "TikTok",

package/scripts/check.py

@@ -34,7 +34,7 @@ import sys
 from fractions import Fraction
 from typing import Any, Dict, List
 
-from _platforms import PLATFORMS, PLATFORM_CHOICES, spec_of, resolve as resolve_platform
+from _platforms import PLATFORMS, PLATFORM_CHOICES, TP_TOLERANCE_DB, spec_of, resolve as resolve_platform
 from _common.probe import SILENT_PEAK_DBFS, detect_content, measured_level_dbfs
 from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run, run_analysis, dry_run_input_pending
 
@@ -249,7 +249,7 @@ def main() -> int:
                 diff = abs(lm["lufs"] - spec["lufs"])
                 row("loudness", "PASS" if diff <= spec["lufs_tol"] else "FAIL", f"{lm['lufs']:.1f} LUFS", f"{spec['lufs']:g} ± {spec['lufs_tol']:g} LUFS", f"loudness.py -I {spec['lufs']:g} for speech or music; leave ambience/near-silence (<= -40 LUFS) alone and say so",
                     reason="the platform will auto-normalise it to its own target anyway, which can pump or duck the mix in ways you did not choose")
-                row("true peak", "PASS" if lm["tp"] <= spec["tp"] + 0.05 else "FAIL", f"{lm['tp']:.1f} dBTP", f"<= {spec['tp']:g} dBTP", f"loudness.py --tp {spec['tp']:g}")
+                row("true peak", "PASS" if lm["tp"] <= spec["tp"] + TP_TOLERANCE_DB else "FAIL", f"{lm['tp']:.1f} dBTP", f"<= {spec['tp']:g} dBTP (+{TP_TOLERANCE_DB:g} dB tolerance)", f"loudness.py --tp {spec['tp']:g}")
             else:
                 # ffmpeg's loudnorm JSON didn't parse out of stderr (unexpected/garbled output).
                 # Dropping the loudness/true-peak rows silently here would report an overall PASS

package/scripts/cut.py

@@ -1677,7 +1677,11 @@ def main() -> int:
         notes.append(skew_note)
     info(f"wrote {output} ({fmt_secs(got)}, expected ~{expected:.3f}s, "
          + ("re-encoded" if reencoded else "lossless stream copy") + f", {precision} precision)")
+    # the streams the source had and this cut was not told to drop (an audio extension drops the
+    # picture): #367, a TS cut that lost its video must not say verified
+    expect_streams = {"video": bool(meta.get("video")) and not is_audio_output(output), "audio": bool(meta.get("audio"))}
     emit(output, expected_duration=round(expected, 6), duration_error_ms=error_ms, precision=precision, reencoded=reencoded,
+         expect_streams=expect_streams,
          dropped_non_av_streams=bool(DROPPED_STREAMS),
          requested_start=round(requested[0][0], 6) if len(requested) == 1 else None,
          requested_end=round(requested[0][1], 6) if len(requested) == 1 else None,

package/scripts/export.py

@@ -40,10 +40,22 @@ from _common import STATE, add_common, apply_common, bt709_matrix_args, bt709_ta
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_skip, warn
 from check import SPECS as PLATFORMS, measure_loudness
-from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, resolve as resolve_platform
+from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, TP_TOLERANCE_DB, resolve as resolve_platform
 # Frame and duration limit come from the one platform table (scripts/_platforms.py) rather than
 # from a literal restated here: before 1.14 they were typed twice and the facebook preset had
 # already drifted (no duration cap against the table's 14400 s).
+
+def _loudness_step(ok: bool, platform: str, spec: dict, m: dict) -> dict:
+    """export's loudness verification step: the platform's targets, what was measured, the
+    difference and the tolerance each was held to (docs/contract.md, 2.18 keys)."""
+    expected = {"lufs": spec["lufs"], "tp_max": spec["tp"]}
+    measured = {"lufs": m["lufs"], "tp": m["tp"]}
+    delta = {"lufs": round(m["lufs"] - spec["lufs"], 2) if math.isfinite(m["lufs"]) else None,
+             "tp": round(m["tp"] - spec["tp"], 2) if math.isfinite(m["tp"]) else None}
+    return {"step": "loudness", "ok": ok, "platform": platform, "property": "loudness",
+            "expected": expected, "measured": measured, "delta": delta,
+            "tolerance": {"lufs": spec["lufs_tol"], "tp": TP_TOLERANCE_DB}, "provenance": "specification"}
+
 def _from_table(dest: str, **over) -> Dict:
     """A preset's w/h/max read from PLATFORMS[dest], with the encoder settings given here.
 
@@ -268,9 +280,9 @@ def main() -> int:
         if not m:
             _loudness_unmeasured(extra, notes, platform, spec)
         if m:
-            ok = abs(m["lufs"] - spec["lufs"]) <= spec["lufs_tol"] and m["tp"] <= spec["tp"]
+            ok = abs(m["lufs"] - spec["lufs"]) <= spec["lufs_tol"] and m["tp"] <= spec["tp"] + TP_TOLERANCE_DB
             extra["loudness"] = {"lufs": m["lufs"], "tp": m["tp"], "target_lufs": spec["lufs"], "target_tp": spec["tp"], "ok": ok}
-            extra["verification"] = [{"step": "loudness", "ok": ok, "platform": platform}]
+            extra["verification"] = [_loudness_step(ok, platform, spec, m)]
             if not math.isfinite(m["lufs"]):
                 # a silent output measures -inf LUFS: no gain reaches the target, so recommending
                 # (or running, under --normalize) loudness.py only returns "nothing to normalise"
@@ -305,9 +317,9 @@ def main() -> int:
                     _loudness_unmeasured(extra, notes, platform, spec, normalized=True)
                     ok = True  # nothing more to say about a level that was not measured
                 else:
-                    ok = abs(m["lufs"] - spec["lufs"]) <= spec["lufs_tol"] and m["tp"] <= spec["tp"]
+                    ok = abs(m["lufs"] - spec["lufs"]) <= spec["lufs_tol"] and m["tp"] <= spec["tp"] + TP_TOLERANCE_DB
                     extra["loudness"] = {"lufs": m["lufs"], "tp": m["tp"], "target_lufs": spec["lufs"], "target_tp": spec["tp"], "ok": ok, "normalized": True}
-                    extra["verification"] = [{"step": "loudness", "ok": ok, "platform": platform}]
+                    extra["verification"] = [_loudness_step(ok, platform, spec, m)]
                 if not ok:
                     notes.append(f"loudness is still {m['lufs']:.1f} LUFS / {m['tp']:+.1f} dBTP after loudness.py (target {spec['lufs']:g} LUFS / {spec['tp']:g} dBTP): {child.get('result', {}).get('note') or 'the encoder overshoots the ceiling'}")
                     warn(notes[-1], "loudness_outside_spec", platform=platform, lufs=m["lufs"], tp=m["tp"], normalized=True)
@@ -323,6 +335,8 @@ def main() -> int:
         notes.append(f"[dry-run] --normalize: loudness.py -I {spec['lufs']:g} --tp {spec['tp']:g} would run on the written file if it misses {platform}'s spec")
     if notes:
         extra["notes"] = notes
+    # the delivery keeps the source's picture and, except as a GIF, its sound
+    extra["expect_streams"] = {"video": bool(meta.get("video")), "audio": has_audio and args.preset != "gif"}
     emit(output, **extra)
     return 0
 

package/scripts/join.py

@@ -565,11 +565,21 @@ def main() -> int:
     verification = []
     if expected is not None and measured is not None and not STATE.dry_run:
         tol = max(1.5 / fps, 0.05)
-        verification.append({"step": "duration", "ok": abs(measured - expected) <= tol,
-                             "measured": round(measured, 3), "expected": expected, "tolerance": round(tol, 3)})
+        verification.append({"step": "duration", "property": "video_duration", "ok": abs(measured - expected) <= tol,
+                             "measured": round(measured, 3), "expected": expected,
+                             "delta": round(measured - expected, 3), "tolerance": round(tol, 3),
+                             "provenance": "input_premeasurement"})
+    # a clip with no audio stream is joined over generated silence: the join is right to do that, but
+    # the report must say which clips' sound is not theirs (the paper's join finding: absence was
+    # filled and nothing in the result showed it)
+    substituted = [p for p, m in zip(args.inputs, metas) if not m.get("audio")]
+    if substituted:
+        STATE_NOTES.append(f"{len(substituted)} clip(s) had no audio stream; their span of the join is generated "
+                           "silence: " + ", ".join(os.path.basename(p) for p in substituted))
     info(f"wrote {output} ({fmt_secs(measured)}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
     emit(output, mode="video", **reported(), clips=n, transition=args.transition, expected_duration=expected,
-         verification=verification,
+         verification=verification, expect_streams={"video": True, "audio": True},
+         audio_substituted=substituted,
          dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
     return 0
 

package/scripts/loudness.py

@@ -19,6 +19,7 @@ import os
 import re
 import sys
 
+from _platforms import TP_TOLERANCE_DB
 from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, dry_run_input_pending
 
 
@@ -128,7 +129,7 @@ def main() -> int:
     # integrated loudness -- reported, never hidden.
     ceiling, rounds = args.tp, 0
     steps = [] if bitrate_pinned or ext in AUDIO_CODECS and "aac" not in AUDIO_CODECS[ext] else [b for b in ("256k", "320k") if _kbps(b) > _kbps(bitrate)]
-    while not after.get("silent") and float(after["input_tp"]) > args.tp + 0.1 and rounds < 5:
+    while not after.get("silent") and float(after["input_tp"]) > args.tp + TP_TOLERANCE_DB and rounds < 5:
         rounds += 1
         overshoot = float(after["input_tp"]) - args.tp
         if steps:
@@ -152,7 +153,7 @@ def main() -> int:
         result["note"] = (f"integrated loudness is {float(after['input_i']) - args.lufs:+.1f} LU from the target because the "
                           f"true-peak ceiling had to absorb the encoder's overshoot; a lossless delivery (wav/flac) or a pinned "
                           f"higher --audio-bitrate keeps both")
-    if not after.get("silent") and float(after["input_tp"]) > args.tp + 0.1:
+    if not after.get("silent") and float(after["input_tp"]) > args.tp + TP_TOLERANCE_DB:
         die(f"true peak is still {float(after['input_tp']):.2f} dBTP after {rounds + 1} encodes (requested <= {args.tp:g}); "
             f"the encoder overshoots more than the loudnorm ceiling can absorb at this bitrate",
             kind="verification", output=output, result=result,
@@ -161,8 +162,12 @@ def main() -> int:
          measured={k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")},
          targets={"lufs": args.lufs, "tp": args.tp, "lra": args.lra},
          verification=[{"step": "loudness",
-                        "ok": bool(after.get("silent")) or (abs(float(after["input_i"]) - args.lufs) <= 1.0 and float(after["input_tp"]) <= args.tp + 0.1),
-                        "lufs": float(after["input_i"]), "tp": float(after["input_tp"]), "target_lufs": args.lufs, "target_tp": args.tp}])
+                        "ok": bool(after.get("silent")) or (abs(float(after["input_i"]) - args.lufs) <= 1.0 and float(after["input_tp"]) <= args.tp + TP_TOLERANCE_DB),
+                        "lufs": float(after["input_i"]), "tp": float(after["input_tp"]), "target_lufs": args.lufs, "target_tp": args.tp,
+                        "property": "loudness", "expected": {"lufs": args.lufs, "tp_max": args.tp},
+                        "measured": {"lufs": float(after["input_i"]), "tp": float(after["input_tp"])},
+                        "delta": {"lufs": round(float(after["input_i"]) - args.lufs, 2), "tp": round(float(after["input_tp"]) - args.tp, 2)},
+                        "tolerance": {"lufs": 1.0, "tp": TP_TOLERANCE_DB}, "provenance": "user_specified"}])
     return 0