ffmpeg-skill 2.21.0 → 2.21.1

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.21.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.21.1`) | 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.21.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.21.1", "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"},
@@ -679,7 +679,7 @@ Per-tool keys added after 2.2.2, all additive:
 | `encoder`, `hw`, `notes` | every re-encoding tool, `export.py`, `render.py`, `batch.py` (and its rows), `waveform.py` | `encoder`: the video encoder the last command ran (after any GPU→CPU fallback; under `--dry-run`, the planned one), `copy` for a stream copy; absent when no command encoded video. A tool that runs other tools reports its stages': `render.py` its stages and an executed plan's tool, `waveform.py` the title/caption stage that writes its file (its `commands` include that stage's). `hw` is present when VideoToolbox was asked for (`--hw`, `FFMPEG_SKILL_HW=1`, or a stage or `batch.py` item that reported it), on `export.py` when `FFMPEG_SKILL_HW=1` is set but its delivery preset does not take it, and when an encode ran on VideoToolbox because the build has no `libx264`/`libx265`: `{requested, source: flag\|env\|auto, used, fallback, notes}`. `requested` says whether this run's encodes were asked onto VideoToolbox (`false` for that export, and for `source: "auto"`, where nobody asked: `notes` names the missing CPU encoder and the one that ran, and `--no-hw` is not offered as a remedy since there is no CPU encoder to go back to; a job VideoToolbox refuses there is a plain `kind: ffmpeg` failure, not retried), `used` whether the encoder that ran last is VideoToolbox (`null` under `--dry-run`, which ran nothing, and when the tool encoded nothing itself: `batch.py`, whose top-level `hw` gathers its items' `requested`/`source`/`fallback`/`notes` while each `results` row carries the item's own `encoder`, and `hw`/`notes` when VideoToolbox was asked for), `fallback` whether a job VideoToolbox refused was re-encoded on the CPU, and `notes` why. Only a VideoToolbox failure (the encoder could not open, or its compression session failed) is retried on the CPU; any other failure is reported as it happened, once. Every VideoToolbox encode adds a top-level `notes` line: its quality is not CRF-equivalent (`--quality` / a preset's CRF maps to `-q:v` approximately), and `verified` stays what it is for every tool, the measured properties of the output. A `kind: ffmpeg` failure under `--hw` / `FFMPEG_SKILL_HW` carries `encoder` and `hw` for the command that ran last (a stage's, when `render.py`/`waveform.py` re-raise it); when the command itself failed inside the run (not a tool's own check afterwards, such as `cut.py`'s), its message also names that encoder |
 | `transcription` | `caption.py --transcribe` (every `--mode`); inside `filler` for `silence.py --filler --transcribe` | `{routing, detected_language?, engine, model, language}`: the engine and model that made the transcript; `language` is the language the engine was told -- the one named (`--language`, `--filler-lang`), else the one auto's detector named -- and, when nothing was named, the language the engine decoded where it reports one (whisper.cpp's word-timing JSON, faster-whisper, openai-whisper's word-timing JSON), else `null`; `detected_language` is present when auto's whisper.cpp detector named one; `routing` says why `--engine auto` chose the engine (`"requested"` for a named engine), ending `, no Parakeet engine transcribed it` when auto chose Parakeet and a Whisper engine made the transcript after every Parakeet engine failed |
 | `notes` | `silence.py --filler --transcribe` (new for `silence.py`; `caption.py` already had it) | present when `--engine auto` ran the English-only Parakeet model on English *assumed* (no language given or detectable, and no Whisper engine installed or none that succeeded): the transcript is wrong if the speech is not English. `caption.py --transcribe` puts the same line in its `notes` |
-| `reencode_reason`, `segment_precision`, `least_exact_precision`, `start_snapped` | `cut.py` (every run) | `reencode_reason`: why anything was re-encoded, distinct values in first-seen order, `[]` for a clean copy: `requested` (`--accurate`), `codec` (`--codec`), `vfr`, `vfr_inconclusive`, `pcm_container`, `copy_failed`, `tolerance`, `concat_fallback` (a `--segments` join that could not stay a stream copy, which now also sets `reencoded: true` and `mode: hybrid`; it reported `copy` before). `segment_precision`: each `--segments` segment's precision (`null` for one segment); `least_exact_precision`: the least exact of them, on every run. `precision` and `keyframe_snapped` keep their meaning (`keyframe_snapped` is `precision == "packet"`, a stream copy end to end); `least_exact_precision` differs from `precision` only for an audio-only join of copied and re-encoded parts. `start_snapped`: measured, `true` when a copied segment's picture starts more than one frame from its requested start (or its start could not be measured: an unknown start is never claimed exact), `false` when every start is where asked or everything re-encoded, `null` under `--dry-run`. `requested_segments`/`requested_duration` keep their meaning, the request clamped to the media's duration: a segment ended with the video (less than a frame of sound trimmed) shows in `duration_delta_seconds` and a `notes` line |
+| `reencode_reason`, `segment_precision`, `least_exact_precision`, `start_snapped` | `cut.py` (every run) | `reencode_reason`: why anything was re-encoded, distinct values in first-seen order, `[]` for a clean copy: `requested` (`--accurate`), `codec` (`--codec`), `vfr`, `vfr_inconclusive`, `pcm_container`, `copy_failed`, `stream_lost` (the copy wrote no video or no audio: an MPEG-TS copy whose window holds no video keyframe, #367), `tolerance`, `concat_fallback` (a `--segments` join that could not stay a stream copy, which now also sets `reencoded: true` and `mode: hybrid`; it reported `copy` before). `segment_precision`: each `--segments` segment's precision (`null` for one segment); `least_exact_precision`: the least exact of them, on every run. `precision` and `keyframe_snapped` keep their meaning (`keyframe_snapped` is `precision == "packet"`, a stream copy end to end); `least_exact_precision` differs from `precision` only for an audio-only join of copied and re-encoded parts. `start_snapped`: measured, `true` when a copied segment's picture starts more than one frame from its requested start (or its start could not be measured: an unknown start is never claimed exact), `false` when every start is where asked or everything re-encoded, `null` under `--dry-run`. `requested_segments`/`requested_duration` keep their meaning, the request clamped to the media's duration: a segment ended with the video (less than a frame of sound trimmed) shows in `duration_delta_seconds` and a `notes` line |
 | `edit_list`, `stored_preroll_seconds`, `av_start_skew_seconds`, `notes` | `cut.py` (every run) | `edit_list`: `true` only for a single-segment `.mp4`/`.m4v`/`.mov` stream copy run with `--edit-list`, which keeps the MP4 edit list the copy writes instead of `-avoid_negative_ts make_zero` (the default, unchanged): the keyframe's pre-roll is stored but hidden, so the picture starts at `--start`. `stored_preroll_seconds`: with `edit_list`, the seconds decoded from the keyframe the copy's seek lands on (measured with the seek ffmpeg makes) up to the first presented frame; `null` otherwise. Under `--edit-list` a copy is judged by its video's length (a `notes` line says so when the container is longer), and one that starts where asked but ends past `--tolerance` re-encodes (`tolerance`) without a `lossless_alternative`. `av_start_skew_seconds`: the output's audio start minus its video start (`null` when either is missing or under `--dry-run`); on a stream copy, when it is more than max(2 frames, 0.1 s) away from the source's own audio/video offset where the copy's picture starts (the keyframe it began from; `--start` under `--edit-list`), a `notes` line names `--accurate`, and `--edit-list` for a single `.mp4`/`.mov` copy whose start snapped. A re-encode carries no such note. The skew is reported, never repaired. `notes`: what the run did that a caller should know, in plain sentences (`[]` when nothing) |
 | `video.start_time`, `audio.start_time` | `probe.py` (and every `probe` block a tool returns) | where each stream starts, in seconds on the file's own clock (ffprobe's stream `start_time`; `null` when unknown). A video stream that starts after its audio, or the reverse, is how a lossless cut's A/V skew shows; `cut.py` reads them for `av_start_skew_seconds` |
 | `cut_reencode_reasons` | `batch.py` (and its `results` rows) | a row whose recipe ran `cut.py` lists each `reencode_reason` its `cut.py` calls named, once per call, beside `cut_reencoded`; the top level counts them across the folder (`{}` when no call re-encoded, `null` when no `cut.py` step ran) on a completed batch, as `cut_stream_copy` does: a failure document carries `results`, whose rows hold each row's reasons; a re-encoded call in a row served from a cache an earlier 2.x batch wrote, which recorded no reasons, counts as `unknown`. `cut_stream_copy` is unchanged |
@@ -709,6 +709,18 @@ silence a tool reported as fine while another measurement disagreed):
 | `inputs_duration`, `transition_shortening`; step `duration`'s `inputs_total` | `join.py` | the clips' own total and how much the transitions took out of it. `expected_duration` is derived from the transition the join applied, so it cannot show that on its own |
 | `silence_kinds`, `silence_breakdown` | `silence.py` | per detected silence, `digital` (at or below -90 dBFS) or `below_threshold` (quiet sound under `--threshold`), and the count and seconds of each with the level that defines it |
 
+Keys added after 2.21, all additive (#367 follow-up, and a report of a filename with a space that
+lost 40 s of sound with no error):
+
+| key | tool | what it holds |
+|---|---|---|
+| step `streams`'s `expected_count`, `measured_count` | `cut.py`, `join.py`, `export.py` | how many video and audio streams the output should have and has. These writers map one of each, so a count below the expected one is `missing`; `expected`/`measured` keep their booleans |
+| `verification[]` step `stream_lengths` (`property: stream_end`) | `cut.py`, `join.py`, `export.py`, when the output keeps both picture and sound | where each stream ends (`ends`: start plus its own length, the DURATION tag in Matroska/WebM) and how far before the later one (`shortfall`). The inputs' own gap is allowed (`input_shortfall`, summed over join's clips; for cut.py only the gap inside the requested ranges) plus `tolerance` (`_common.emit.STREAM_LENGTH_TOLERANCE`, 0.25 s); a stream that ends earlier is named in `short` and fails the step. Ends, not lengths: a stream that only starts late is cut's start-skew note. An output length that cannot be read fails with `reason: not_measured`, and so does an output gap when an input's own stream length could not be read (`input_shortfall: null`: the gap may be the input's) |
+| `verification[]` step `decode` (`property: decodable`) | `cut.py`, `join.py`, `export.py` | `frames`: per kept stream, how many frames ffmpeg decoded from the first `window` seconds (`_common.emit.DECODE_WINDOW_SECONDS`, 1 s) and from its last `window` before the stream's own end (the read starts `DECODE_SEEK_MARGIN_SECONDS`, 10 s, earlier so a seek past the last keyframe still decodes, but only frames still on screen in the window count; a tail with no frame is read once more from up to `DECODE_LONG_GOP_SECONDS`, 60 s, earlier, for a GOP longer than the margin). A stream with no frame at either end is named in `undecodable` and fails the step; one with no end time of its own (the container's is the longest stream's) has its tail `not_measured`, which fails the step without calling it undecodable. `join.py` runs it on an audio-only join too |
+| `probe.start_time` | `probe.py` and every output probe | where the file's timeline starts (the container's start time; MPEG-TS starts at about 1.4 s). A `-ss`, a cut's `--start` and the decode check's reads count from here |
+| `probe.stream_counts` | `probe.py` and every output probe | `{video, audio}`: how many picture streams (a cover picture is not one) and sound streams the file carries |
+| `probe.video.tagged_duration` | `probe.py` and every output probe | the video stream's DURATION tag in seconds (Matroska/WebM give no stream duration), as `audio.tagged_duration` since 2.20 |
+
 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.21.0",
+  "version": "2.21.1",
   "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/references/scripts.md

@@ -29,6 +29,8 @@ Every row names the constant or flag it comes from, and a test holds the table t
 | a levels pass keeps the sound's length to (or one AAC frame, 1024 samples, if longer) | 0.03 s | `loudness.AUDIO_LENGTH_TOLERANCE` | `loudness.py` |
 | a joined picture is as long as the clips less the transitions, to (frames) | 1.5 | `join.DURATION_TOLERANCE_FRAMES` | `join.py` |
 | ... and at least | 0.05 s | `join.DURATION_TOLERANCE_MIN` | `join.py` |
+| the picture and the sound end together, beyond the gap the inputs had, to | 0.25 s | `_common.emit.STREAM_LENGTH_TOLERANCE` | `cut.py`, `join.py`, `export.py` (`stream_lengths`) |
+| every kept stream decodes at least one frame in its first and its last | 1.0 s | `_common.emit.DECODE_WINDOW_SECONDS` | `cut.py`, `join.py`, `export.py` (`decode`) |
 | a lossless cut may land this far from the asked time before it re-encodes | 0.5 s | `cut.py --tolerance` | `cut.py` |
 | silence is sound at or below | -35 dBFS | `silence.py --threshold` | `silence.py` |
 | ... lasting at least | 0.6 s | `silence.py --min-silence` | `silence.py` |
@@ -165,7 +167,7 @@ in the length. `keyframe_snapped` is true for every stream copy (`precision`
 than a frame from `--start`, or when its start could not be measured (an unknown start is
 never claimed exact); `null` under `--dry-run`.
 `reencode_reason` lists every cause of a re-encode (`requested`, `codec`, `vfr`,
-`vfr_inconclusive`, `pcm_container`, `copy_failed`, `tolerance`, `concat_fallback`);
+`vfr_inconclusive`, `pcm_container`, `copy_failed`, `stream_lost`, `tolerance`, `concat_fallback`);
 `--segments` adds `segment_precision`, and `least_exact_precision` is the least exact one.
 A `--segments` video copy join adds `join_check` (`packets`, `expected_packets`,
 `max_step_seconds`, `audio_offset_ms` per part, `audio_parts_checked`, `ok`: the

package/scripts/_common/emit.py

@@ -396,21 +396,190 @@ UNVERIFIED: Dict[str, List[str]] = {
 }
 
 
-def stream_inventory_step(meta: Dict[str, Any], expect: Dict[str, bool]) -> Dict[str, Any]:
+# a picture and its sound may differ in length by this much more than they did in the input
+STREAM_LENGTH_TOLERANCE = 0.25
+# how many seconds at each end of every kept stream the decode check decodes
+DECODE_WINDOW_SECONDS = 1.0
+# how much earlier than its window the tail decode starts reading (a seek past the last keyframe)
+DECODE_SEEK_MARGIN_SECONDS = 10.0
+# how far back the one retry of an empty tail reads (a GOP longer than the margin)
+DECODE_LONG_GOP_SECONDS = 60.0
+
+
+def _expected_count(want: Any) -> int:
+    """`expect_streams` values: a count, or True/False for "at least one" / "none"."""
+    return int(want) if not isinstance(want, bool) else (1 if want else 0)
+
+
+def stream_inventory_step(meta: Dict[str, Any], expect: Dict[str, Any]) -> 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}
+    input had and the operation was not told to drop must still be there. A value is a count
+    (the cut, join and export writers map one stream of each kind) or a bool for "at least one";
+    fewer streams than that is `missing`."""
+    counts = meta.get("stream_counts") or {k: int(bool(meta.get(k))) for k in expect}
+    want = {k: _expected_count(v) for k, v in expect.items()}
+    got = {k: int(counts.get(k) or 0) if meta.get(k) else 0 for k in expect}
+    missing = [k for k in expect if got[k] < want[k]]
+    step: Dict[str, Any] = {"step": "streams", "property": "stream_inventory",
+                            "expected": {k: want[k] > 0 for k in expect}, "measured": {k: got[k] > 0 for k in expect},
+                            "expected_count": want, "measured_count": got,
+                            "provenance": "input_premeasurement", "ok": not missing}
     if missing:
         step["missing"] = missing
     return step
 
 
+def stream_length(meta: Dict[str, Any], kind: str) -> Optional[float]:
+    """One stream's own length: its duration, else the DURATION tag Matroska/WebM keep. A value
+    that is not a finite number is no length (a NaN compares false and would pass every check)."""
+    s = meta.get(kind) or {}
+    for v in (s.get("duration"), s.get("tagged_duration")):
+        if isinstance(v, (int, float)) and math.isfinite(v) and v > 0:
+            return float(v)
+    return None
+
+
+def stream_end(meta: Dict[str, Any], kind: str) -> Optional[float]:
+    """Where one stream ends on the file's timeline: its start plus its own length."""
+    length = stream_length(meta, kind)
+    return None if length is None else ((meta.get(kind) or {}).get("start_time") or 0.0) + length
+
+
+def file_origin(meta: Dict[str, Any]) -> float:
+    """Where the file's timeline starts: the container's start time, else its earliest stream's.
+    A -ss, a cut's --start and a window are counted from here, while stream starts and ends are
+    on the file's own timestamps."""
+    if isinstance(meta.get("start_time"), (int, float)):
+        return float(meta["start_time"])
+    starts = [(meta.get(k) or {}).get("start_time") for k in ("video", "audio")]
+    return min([s for s in starts if isinstance(s, (int, float))] or [0.0])
+
+
+def stream_lengths_step(meta: Dict[str, Any], references: Sequence[Dict[str, Any]],
+                        tolerance: float = STREAM_LENGTH_TOLERANCE,
+                        windows: Optional[Sequence[Tuple[float, float]]] = None) -> Dict[str, Any]:
+    """Where the picture and the sound of the output end, against each other, allowing the gap
+    the inputs already had. A filename with a space was reported to have lost 40 s of sound with
+    no error: the container's length is the longest stream's, so a duration check passes while
+    one stream stops early. `short` names a stream that ends more than `tolerance` (plus the
+    inputs' own shortfall, summed over the inputs) before the other one. Ends, not lengths: a
+    stream that only starts late is the start-skew check's (cut.py reports it in a note). A length
+    that cannot be read is not a pass (`not_measured`). `windows` (cut.py's requested ranges, on
+    the input's own timeline) count only the gap the input has inside them: a source whose video
+    runs 5 s past its sound allows nothing to a cut from its middle."""
+    kinds = ("video", "audio")
+    lengths = {k: stream_length(meta, k) for k in kinds}
+    step: Dict[str, Any] = {"step": "stream_lengths", "property": "stream_end", "measured": lengths,
+                            "tolerance": tolerance, "provenance": "input_premeasurement"}
+    unknown = [k for k in kinds if lengths[k] is None]
+    if unknown:
+        return dict(step, ok=False, reason="not_measured: no length for the %s stream" % " and ".join(unknown))
+    allowed: Dict[str, float] = {k: 0.0 for k in kinds}
+    unread_input = False
+    for ref in references:
+        if not all(ref.get(k) for k in kinds):
+            continue  # an input with one stream (join's silent clip) brings no gap of its own
+        ref_ends = {k: stream_end(ref, k) for k in kinds}
+        if None in ref_ends.values():
+            unread_input = True  # its gap is unknown, not zero
+            continue
+        rel = {k: ref_ends[k] - file_origin(ref) for k in kinds}  # the clock cut's ranges are on
+        for s, e in (windows or [(0.0, max(rel.values()))]):
+            inside = {k: max(s, min(e, rel[k])) for k in kinds}
+            top = max(inside.values())
+            for k in kinds:
+                allowed[k] += top - inside[k]
+    ends = {k: stream_end(meta, k) for k in kinds}
+    last = max(ends.values())
+    raw = {k: last - ends[k] for k in kinds}
+    short = [k for k in kinds if raw[k] > allowed[k] + tolerance]
+    step.update(ends={k: round(v, 3) for k, v in ends.items()}, shortfall={k: round(v, 3) for k, v in raw.items()},
+                input_shortfall={k: round(v, 3) for k, v in allowed.items()}, ok=not short)
+    if short and unread_input:
+        # a gap the output has may be one an input already had: neither a pass nor a "short"
+        step["input_shortfall"] = None
+        step["reason"] = ("not_measured: an input's stream length cannot be read, so whether the %s gap "
+                          "was already in the input is unknown" % " and ".join(short))
+    elif short:
+        step["short"] = short
+    return step
+
+
+def decode_step(path: str, meta: Dict[str, Any], kinds: Sequence[str], window: float = DECODE_WINDOW_SECONDS) -> Dict[str, Any]:
+    """Decode the first `window` seconds of every kept stream and the last `window` before that
+    stream's own end, and count the frames. A stream ffprobe lists from the container header can
+    still hold nothing a decoder accepts; the inventory and length checks read the header, this
+    one reads the payload. The tail read starts DECODE_SEEK_MARGIN_SECONDS earlier, so a seek that
+    lands past the last keyframe (MPEG-TS seeks by timestamp, not to a keyframe) still decodes,
+    but only frames in the last `window` count, and the read stops a second past the end. A
+    stream whose own end cannot be read is not decoded at its end: its tail is `not_measured`,
+    not undecodable (the container's end is the longest stream's, not this one's)."""
+    from _common.runner import require_tool, run_analysis
+    ffmpeg = require_tool("ffmpeg")
+    frames: Dict[str, Dict[str, int]] = {}
+    unmeasured: List[str] = []
+    for kind in kinds:
+        # 0:V is the motion picture only: an attached cover picture would be 0:v:0
+        sel = ["-map", "0:%s:0" % ("V" if kind == "video" else "a"), "-f", "framecrc", "-"]
+        base = [ffmpeg, "-hide_banner", "-nostdin", "-v", "error"]
+        origin = file_origin(meta)
+        # the head is the stream's own first window: sound that starts 2 s in has none in the file's
+        head_from = max(0.0, ((meta.get(kind) or {}).get("start_time") or origin) - origin)
+        head = run_analysis(base + ["-ss", "%.3f" % head_from, "-i", path, "-t", "%g" % window] + sel, check=False)
+        frames[kind] = {"head": _framecrc_frames(head) if head.returncode == 0 else 0}
+        # the stream's own end only: the container's is the longest stream's, and a shorter stream
+        # read there would decode nothing and be called undecodable when it is only unmeasured
+        end = stream_end(meta, kind)
+        if end is None:
+            frames[kind]["tail"] = 0
+            unmeasured.append(kind)
+            continue
+        tail_from = max(0.0, end - origin - window - DECODE_SEEK_MARGIN_SECONDS)  # -ss counts from the origin
+        # -copyts keeps the file's own timestamps, the timeline `end` is measured on
+        def tail_frames(start: float) -> int:
+            proc = run_analysis(base + ["-copyts", "-ss", "%.3f" % start, "-t", "%g" % (end - origin - start + 1.0), "-i", path]
+                                + sel, check=False)
+            return _framecrc_frames(proc, since=end - window) if proc.returncode == 0 else 0
+        frames[kind]["tail"] = tail_frames(tail_from)
+        if not frames[kind]["tail"] and tail_from > 0:
+            # a GOP longer than the margin (long-GOP MPEG-TS) has no keyframe after tail_from: read
+            # once more from up to DECODE_LONG_GOP_SECONDS earlier before calling it undecodable
+            # (bounded, so a failing hour-long stream is not decoded whole)
+            frames[kind]["tail"] = tail_frames(max(0.0, end - origin - window - DECODE_LONG_GOP_SECONDS))
+    bad = [k for k in kinds if not all(frames[k].values())]
+    step: Dict[str, Any] = {"step": "decode", "property": "decodable", "frames": frames, "window": window,
+                            "provenance": "measurement", "ok": not bad}
+    if bad:
+        step["undecodable"] = [k for k in bad if k not in unmeasured]
+    if unmeasured:
+        step["reason"] = "not_measured: no end time for the %s stream" % " and ".join(unmeasured)
+    return step
+
+
+def _framecrc_frames(proc: Any, since: Optional[float] = None) -> int:
+    """Frames in ffmpeg's framecrc output; with `since`, only those still on screen after that time
+    (pts plus duration past it: a last frame held for 2 s starts before the window and still
+    counts, one that ends exactly at it does not). Rows
+    are `stream, dts, pts, duration, size, crc`, timestamps in the `#tb N: num/den` time base."""
+    tb: Dict[str, float] = {}
+    n = 0
+    for line in (proc.stdout or "").splitlines():
+        if line.startswith("#tb "):
+            idx, frac = line[4:].split(":", 1)
+            num, den = frac.strip().split("/")
+            tb[idx.strip()] = float(num) / float(den)
+        elif line and not line.startswith("#"):
+            cols = [c.strip() for c in line.split(",")]
+            if since is None:
+                n += 1
+            elif len(cols) > 3 and cols[0] in tb and (float(cols[2]) + float(cols[3])) * tb[cols[0]] > since + 1e-6:
+                n += 1
+    return n
+
+
 def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any) -> None:
     """Final stdout line: the output path, or a JSON document with --json.
 
@@ -432,9 +601,17 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
         # 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)
+        stream_reference = extra.pop("stream_reference", None)
+        stream_windows = extra.pop("stream_windows", 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))
+            kept = [k for k in ("video", "audio") if _expected_count(expect_streams.get(k, 0))]
+            if stream_reference is not None and len(kept) == 2:
+                steps.append(stream_lengths_step(meta, stream_reference, windows=stream_windows))
+            present = [k for k in kept if meta.get(k)]
+            if present:
+                steps.append(decode_step(output, meta, present))
         # 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:

package/scripts/_common/probe.py

@@ -206,12 +206,21 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         "file": path,
         "format": fmt.get("format_name"),
         "duration": duration,
+        # where the file's timeline starts (MPEG-TS starts at 1.4 s, not 0): a -ss and a cut's
+        # --start count from here
+        "start_time": _to_float(fmt.get("start_time")),
         "size_bytes": _to_int(fmt.get("size")),
         "bitrate": _to_int(fmt.get("bit_rate")),
         "video": None,
         "audio": None,
         "subtitle_streams": len(subs),
         "data_streams": data_stream_count,
+        # how many picture and sound streams the file carries (a cover picture is not a video
+        # stream); the streams check compares them with what the operation should have written
+        "stream_counts": {
+            "video": sum(1 for s in streams if s.get("codec_type") == "video" and s.get("disposition", {}).get("attached_pic", 0) == 0),
+            "audio": sum(1 for s in streams if s.get("codec_type") == "audio"),
+        },
         # container-level chapter markers and the common tags, so metadata.py's result is
         # verifiable the same way every other tool's is (additive keys, 1.x-safe)
         "chapters": [{
@@ -286,6 +295,8 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "nb_frames": _to_int(video.get("nb_frames")),
             # the stream's own length (a container's also counts audio priming and a longer track)
             "duration": _to_float(video.get("duration")),
+            # Matroska/WebM keep the stream's length in a DURATION tag only, as for audio below
+            "tagged_duration": _tag_seconds((video.get("tags") or {}).get("DURATION")),
             # where the stream starts; a video stream that starts after its audio (or the reverse)
             # is how a lossless cut's A/V skew shows up
             "start_time": _to_float(video.get("start_time")),

package/scripts/_common/runner.py

@@ -1377,9 +1377,16 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
 
 
 def shell_quote(s: str) -> str:
-    if not s or any(ch in s for ch in " \t\n\r\\\"';|&<>()[]{}$*?"):
-        return "'" + s.replace("'", "'\\''") + "'"
-    return s
+    """One argument as a POSIX shell word, so a printed command can be pasted and run again.
+    Anything outside a known-safe set is single-quoted: the old deny-list left a backtick, `!`, a
+    leading `#` or `~` and non-ASCII bare, and a shell ran `x`id`.mp4`'s backtick as a command
+    and dropped `#tag.mp4` (and everything after it) as a comment."""
+    if s and _SHELL_SAFE.fullmatch(s):
+        return s
+    return "'" + s.replace("'", "'\\''") + "'"
+
+
+_SHELL_SAFE = re.compile(r"[A-Za-z0-9_@%+=:,./-]+")
 
 
 def ffmpeg_base(overwrite: bool = True) -> List[str]:

package/scripts/_contract.py

@@ -630,8 +630,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "keyframe_snapped": {"type": "boolean", "description": "precision is packet: the run is a stream copy end to end, which lands on keyframes and packets. Whether a copied start really moved is start_snapped"},
                  "start_snapped": {"type": ["boolean", "null"], "description": "measured: true when a copied segment's picture starts more than one frame from its requested start (the keyframe the copy's seek lands on, measured with the seek ffmpeg makes); false when every start is where asked (an MP4 edit list hides the pre-roll, the start is a keyframe, an audio-only copy, or everything re-encoded); null when a copied start was not measured (--dry-run)"},
                  "reencoded": {"type": "boolean"},
-                 "reencode_reason": {"type": "array", "items": {"enum": ["requested", "codec", "vfr", "vfr_inconclusive", "pcm_container", "copy_failed", "tolerance", "concat_fallback"]},
-                                     "description": "why anything was re-encoded, distinct values in first-seen order ([] when nothing was): requested (--accurate), codec (--codec), vfr (a variable-frame-rate source forced --accurate), vfr_inconclusive (its frame timing could not be measured), pcm_container (compressed audio into a .wav), copy_failed (the stream copy errored), tolerance (a keyframe snap past --tolerance), concat_fallback (--segments parts could not be joined by stream copy)"},
+                 "reencode_reason": {"type": "array", "items": {"enum": ["requested", "codec", "vfr", "vfr_inconclusive", "pcm_container", "copy_failed", "stream_lost", "tolerance", "concat_fallback"]},
+                                     "description": "why anything was re-encoded, distinct values in first-seen order ([] when nothing was): requested (--accurate), codec (--codec), vfr (a variable-frame-rate source forced --accurate), vfr_inconclusive (its frame timing could not be measured), pcm_container (compressed audio into a .wav), copy_failed (the stream copy errored), stream_lost (the copy wrote no video or no audio, as an MPEG-TS copy with no keyframe in its window does), tolerance (a keyframe snap past --tolerance), concat_fallback (--segments parts could not be joined by stream copy)"},
                  "segment_precision": {"type": ["array", "null"], "items": {"enum": ["packet", "sample", "codec_frame", "frame"]},
                                        "description": "--segments only: each segment's precision in order; least_exact_precision is the least exact of them (null for a single segment)"},
                  "edit_list": {"type": "boolean", "description": "--edit-list on a single MP4/MOV stream copy: it kept the edit list it wrote instead of -avoid_negative_ts make_zero, so the keyframe's pre-roll is stored but hidden and the picture and the sound start at the requested time (false for every other path, the default included)"},

package/scripts/cut.py

@@ -865,8 +865,17 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
             info("stream copy failed, falling back to re-encode")
             return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta, reasons + ["copy_failed"], edit_list_ok)
         die(f"ffmpeg failed:\n{proc.stderr.strip()}", kind="ffmpeg")
-    if not reencode and tolerance >= 0 and not STATE.dry_run and copy_t is None:
-        out_meta = probe(dst)
+    out_meta = probe(dst) if not reencode and not STATE.dry_run and copy_t is None else None
+    if out_meta is not None:
+        # #367: a copy from MPEG-TS whose window holds no video keyframe writes no video at all
+        # (the TS demuxer does not seek back to one, as the MP4 demuxer does), and ffmpeg exits 0
+        lost = [k for k in ("video", "audio") if meta.get(k) and not out_meta.get(k) and not (k == "video" and audio_only)]
+        if lost:
+            info(f"the stream copy wrote no {' or '.join(lost)} stream (no keyframe to start it from); "
+                 "re-encoding this segment")
+            return _with_notes(cut_one(src, start, end, dst, True, crf, preset, tolerance, meta, reasons + ["stream_lost"],
+                                       edit_list_ok), notes)
+    if out_meta is not None and tolerance >= 0:
         got = out_meta.get("duration") or 0.0
         vdur, fps = (out_meta.get("video") or {}).get("duration"), (meta.get("video") or {}).get("fps")
         if edit_list and not audio_only and vdur and fps and abs(got - vdur) > 1.0 / fps:
@@ -1678,10 +1687,12 @@ def main() -> int:
     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"))}
+    # picture): #367, a TS cut that lost its video must not say verified. ffmpeg's default stream
+    # selection writes one of each, so that is the count; the source's own picture/sound gap is
+    # the reference for the lengths check
+    expect_streams = {"video": int(bool(meta.get("video")) and not is_audio_output(output)), "audio": int(bool(meta.get("audio")))}
     emit(output, expected_duration=round(expected, 6), duration_error_ms=error_ms, precision=precision, reencoded=reencoded,
-         expect_streams=expect_streams,
+         expect_streams=expect_streams, stream_reference=[meta], stream_windows=[(s, e) for s, e in requested],
          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

@@ -350,7 +350,10 @@ def main() -> int:
     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"}
+    extra["expect_streams"] = {"video": int(bool(meta.get("video"))), "audio": int(bool(has_audio and args.preset != "gif"))}
+    extra["stream_reference"] = [meta]
+    if trimmed:  # only the kept 0..max of the source can have handed its gap to the output
+        extra["stream_windows"] = [(0.0, float(p["max"]))]
     emit(output, **extra)
     return 0
 

package/scripts/join.py

@@ -195,7 +195,7 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
          + ("crossfade" if d else "butt join") + ")")
     overlap = overlap_report(durs, expected)
     emit(output, mode="audio", **overlap, **reported(), clips=n, transition=args.transition if d else "none", expected_duration=expected,
-         sample_rate=rate, channels=channels, video=False)
+         sample_rate=rate, channels=channels, video=False, expect_streams={"audio": 1})
     return 0
 
 
@@ -598,7 +598,7 @@ def main() -> int:
     info(f"wrote {output} ({fmt_secs(measured)}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
     overlap = overlap_report(lens, expected)
     emit(output, mode="video", **overlap, **reported(), clips=n, transition=args.transition, expected_duration=expected,
-         verification=verification, expect_streams={"video": True, "audio": True},
+         verification=verification, expect_streams={"video": 1, "audio": 1}, stream_reference=metas,
          audio_substituted=substituted,
          dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
     return 0