ffmpeg-skill 2.21.0 → 2.22.0

package/README.md

@@ -224,7 +224,7 @@ These are the rules the skill file gives the agent and the code enforces.
 |---|---|
 | `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact video and sample-exact audio, `--keep-hevc` to re-encode an HEVC source as HEVC, `--edit-list` to keep an `.mp4` copy's start exact, `--vfr-guard` to choose the VFR check; reports `precision`; `--snap beats` moves the in/out points onto a measured beat, or refuses when there is no measurable pulse |
 | `join.py` | Concatenate clips with xfade transitions, normalising size, fps, sample rate and channel layout (the widest clip's, or `--channels`); audio-only inputs are joined as audio; `--list parts.txt` reads generated segments (TTS lines) and checks every one first — missing, empty or unreadable parts are all named in one refusal, or skipped and reported with `--on-missing skip` |
-| `silence.py` | Detect and remove dead air (jump cuts) with a margin around speech; list or export the cut list; `--filler` also removes filler words, but only where a speech engine timed them; `--speech-aware` keeps a breath inside a sentence and cuts only at sentence-boundary pauses, composing with `--filler` through the same `keep_ranges()` |
+| `silence.py` | Detect and remove dead air (jump cuts) with a margin around speech (`--margin`, 0.2 s each side); list or export the cut list, or a source-to-output time map (`--timemap`, JSON or CSV); reports the level at every cut and warns where one may land in a breath or a word's tail; `--filler` also removes filler words, but only where a speech engine timed them; `--speech-aware` keeps a breath inside a sentence and cuts only at sentence-boundary pauses, composing with `--filler` through the same `keep_ranges()` |
 | `fit.py` | Fit to a duration (pitch-preserving speed change or trim, smooth slow-mo) and/or aspect ratio (pad, crop or `--fit blur`'s blurred, darkened fill, with `--crop-x`/`--crop-y` to keep an off-centre subject) and/or exact `--width`/`--height`; rotate 90/180/270, flip h/v; force constant fps |
 | `crop.py` | Crop to an exact pixel rectangle (`--x --y --width --height`) — distinct from `fit.py --fit crop`, which crops to an aspect ratio it computes itself |
 | `cropdetect.py` | Measure existing black letterbox/pillarbox bars and report the `crop.py`-ready rectangle that removes them — analysis only, writes no file; `--motion-centre` reports the per-second motion centroid instead, for a 9:16 reframe — report only, the calling agent picks the crop, no auto-reframing |
@@ -439,6 +439,27 @@ Without the other 30, an agent writes raw ffmpeg for those jobs, and a mistake t
 
 Every command a tool ran is in its `--json` `commands`, shell-quoted so it can be pasted and run again, and `--dry-run` prints the commands without running anything. In the 100-prompt agent eval (1.17.0, [Tested on real footage](#tested-on-real-footage)) the agent made no raw ffmpeg calls and reported no false successes.
 
+### What does `verified` check, and what can it not tell me?
+
+`verified` covers what can be measured from the file. Each tool measures its output again: the probe (the file opens, its duration, codecs, size and frame rate) and the tool's own promise. For example, loudness and true peak after `loudness.py` or `export.py`, the length against the asked one, and for `cut.py`, `join.py` and `export.py` the stream count, where picture and sound end, and whether both ends of every stream decode. `check.py` grades a file against a platform's limits. A value that cannot be read fails its step as `not_measured`; it does not pass.
+
+It cannot tell you whether the result looks or sounds right, and the result says so: every writing tool lists the properties it did not measure in `unverified`. Examples are `picture_content` (what is in the frame), `subject_framing` after a reframe, `rendered_placement` and `legibility` of captions and titles, `grade_look` after a colour conversion, `removed_span_content` after a silence cut (whether a removed span held speech), `mix_balance` and `lip_sync`. For those, look at frames with `look.py` (a contact sheet, or `--safe` for a platform's UI zones) and listen where the result points you. `silence.py` lists the level at every cut, and `cut_warnings` names the cuts that may have landed in a breath or a word's tail.
+
+### Are silence removal and captions stable?
+
+They are the most used tools here, and they are tested on every push on Linux, macOS and Windows, with FFmpeg 5.1 to 9. On 20 test files with known gaps, `silence.py` missed none and left at most 1 ms of silence (see [Tested on real footage](#tested-on-real-footage)). A cut keeps `--margin` seconds of air on each side, 0.2 s by default; raise it to 0.3 s for a speaker who trails off. `--speech-aware` keeps the short breaths inside a sentence. Filler words are removed only from measured word timings (`--words` or a local `--transcribe`), never guessed. `--timemap` writes where each kept and removed range sits in the source and the output, for re-timing subtitles. If `--threshold` is set high enough to cut into a breath or a weak word ending, the result warns at that cut.
+
+`caption.py` burns SRT/ASS or muxes them as soft tracks, fits the size to the platform's safe area, and picks a font that covers the script (Japanese, Chinese, Korean, Arabic, Thai, Hindi and others). It needs FFmpeg's `subtitles` filter (libass); `doctor` reports whether this build has it. Placement and legibility are listed as `unverified`, so look at a contact sheet before delivering. Speech-to-text runs on a local engine you install; its first run may download a model.
+
+### How well does HDR to SDR work, and what should I watch for?
+
+`color.py --to-sdr` converts PQ (HDR10), HLG and iPhone Dolby Vision 8.4 to SDR BT.709 with real tone mapping (`zscale` and `tonemap`, `hable` by default; `mobius`, `reinhard`, `bt2390` and others with `--tonemap`). BT.2020 footage on an SDR transfer gets a gamut conversion only. Watch for four things:
+
+- It needs `zscale` (libzimg). The plain Homebrew `ffmpeg` lacks it, so use `ffmpeg-full`; `doctor` reports whether it is there.
+- `--peak` (default 1000 nits) should match how bright the source was mastered. A wrong value makes highlights dull or clipped.
+- Tone mapping is a judgement, and the result says so (`grade_look` in `unverified`). Compare frames with `look.py`, and try another `--tonemap` if skin or skies look off.
+- An HDR source that only needs to play everywhere may not need converting at all. `--strip-dovi` removes the Dolby Vision layer from an iPhone clip, keeping its HLG picture, with a stream copy.
+
 ### How does ffmpeg-skill compare with Remotion?
 
 ffmpeg-skill edits footage you already have, on this machine, with FFmpeg tools whose flags are a machine-readable contract (`contract --json`). Remotion renders a video from React components. They complement each other: this repository does not call Remotion, and a file Remotion writes is an ordinary input (`probe.py`, `cut.py`, `fit.py`, `export.py`, `check.py`). [`remotion-ffmpeg-skill`](https://github.com/kajisho5/remotion-ffmpeg-skill) joins the two. It measures the footage with this repo, draws the graphics in Remotion from those measurements, and checks and delivers the result with this repo again. Install both (`npx ffmpeg-skill`, then `npx remotion-ffmpeg-skill`). As with the other skills, the dependency runs one way: it calls these tools, and nothing here calls it. HyperFrames renders a video from HTML and is the same kind of neighbour: a file it writes is an ordinary input too.

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.22.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.21.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.22.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"},
@@ -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,27 @@ 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 |
+
+Keys added after 2.21.1, all additive (requests on X: a map of what a silence cut removed, and a
+pointer to cuts that may sit in a breath):
+
+| key | tool | what it holds |
+|---|---|---|
+| `timemap` | `silence.py --timemap FILE` | the path the time map was written to (`.json`: `{kept: [{source_start, source_end, output_start, output_end}], removed: [{source_start, source_end, output_time}]}`; `.csv`: `type,source_start,source_end,output_start,output_end` rows, a removed row's output columns both its cut point). Output times are computed from the millisecond-rounded cut bounds, not measured on the written file: the render keeps whole video frames and audio blocks, so each kept range can differ by up to one frame (about 20-40 ms) and the difference can add up over many cuts. Nothing is written under `--dry-run` |
+| `cut_points` | `silence.py` (every run that cuts) | per cut, `{source_time, output_time, edge, rms_dbfs}`: the RMS level 50 ms either side of the cut on the source, the loudest channel (`null` for digital silence), `edge` `out` where the source is left and `in` where it is picked up; `filler: true` on an edge that sits on a removed filler word. The whole key is `null` when the source could not be decoded for the measurement (`cut_levels_unmeasured` warning): unmeasured, not silent |
+| `cut_warnings` | `silence.py` | the `cut_points` (not filler cuts) whose level is within `silence.CUT_SOUND_MARGIN_DB` (10 dB) of `--threshold`: a breath or a word's weak tail may be cut there. A `cut_near_sound` warning names them. `verified` is unchanged: this is where to listen, not a measured failure |
+
 Per-tool keys added after 2.10.11 ("nothing happens silently"), all additive:
 
 | key | tool | what it holds |
@@ -785,6 +806,7 @@ here claims otherwise until real exit-code/stderr sniffing exists to back that u
 A refusal also carries `error.reason`, a stable snake_case code for *why*
 (`contract --json` → `json_output.error_reasons` lists them: `output_exists`, `output_is_input`,
 `output_is_directory`, `output_dir_missing`, `output_dir_not_writable`, `output_locked`,
+`silence.py --timemap`'s `timemap_path_taken`,
 `render.py`'s `plan_*` reasons, and `--codec av1`/`prores`'s `encoder_missing` and
 `encoder_list_unreadable`), and `error.details`, the facts the message is written from, so a
 caller never parses the prose:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.21.0",
+  "version": "2.22.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/references/scripts.md

@@ -29,10 +29,13 @@ 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` |
 | a removed silence is digital silence when 99% of it sits at or below | -90 dBFS | `silence.DIGITAL_SILENCE_DB` | `silence.py` (`silence_kinds`) |
+| a cut is flagged when the level around it is within this much of `--threshold` | 10 dB | `silence.CUT_SOUND_MARGIN_DB` | `silence.py` (`cut_warnings`) |
 | a track is silent when its peak is at or below | -50 dBFS | `_common.probe.SILENT_PEAK_DBFS` | `check.py`; the `--silence-threshold` default of `join.py`, `audio.py`, `waveform.py` |
 | a filler word longer than this is a held vowel, kept | 1.2 s | `_common.decision.FILLER_MAX_WORD` | `silence.py --filler` |
 | a pause this long between two tokens of an unspaced script is a word boundary | 0.1 s | `_common.decision.FILLER_BOUNDARY_GAP` | `silence.py --filler` |
@@ -165,7 +168,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
@@ -637,7 +640,7 @@ each shorter clip's last frame (with silence) out to the longest.
 
 ### silence.py — remove dead air / jump cuts
 ```
-silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.15] [--min-keep 0.2] [--list] [--edl keep.txt] [--speech-aware] [-o OUT]
+silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.2] [--min-keep 0.2] [--list] [--edl keep.txt] [--timemap map.json|map.csv] [--speech-aware] [-o OUT]
 silence.py INPUT --filler --words transcript.json [--filler-lang auto|en|ja|ko|zh|es|de|fr|pt|it|nl|pl|ru|tr]
            [--filler-words FILE] [--filler-extra W,W] [--filler-keep W,W] [--filler-pad 0.02]
            [--transcribe] [--engine auto|parakeet-mlx|parakeet.cpp|whisper.cpp|faster-whisper|openai-whisper]
@@ -651,6 +654,30 @@ without rendering; `--edl` saves the kept ranges in `cut.py --segments` format
 so the user can edit the list by hand. Quiet rooms need `--threshold -40`
 to `-45`; noisy ones `-30`. Always tell the user how many seconds were removed.
 
+**Breaths and weak word endings.** `--margin` is the padding kept on each side of every cut
+(default 0.2 s since 2.22, 0.15 s before; 0.3 s for a speaker who trails off). `--speech-aware` keeps the short
+breaths inside a sentence and cuts only at sentence-boundary pauses. A `--threshold` set too high
+(-25, say) counts a weak word ending as silence: the result then warns.
+
+**Cut levels (2.22).** Every run measures the RMS level 50 ms either side of each cut on the
+source (`cut_points`: `source_time`, `output_time`, `edge` out/in, `rms_dbfs` of the loudest
+channel, `null` for digital silence; the whole key is `null`, with a `cut_levels_unmeasured`
+warning, when the source could not be decoded for it) and lists in `cut_warnings` the cuts whose level is within 10 dB of `--threshold`,
+with a `cut_near_sound` warning. Room tone sits well below the threshold; a breath or a word's
+weak tail sits just under it. This is a pointer for listening, not a verdict: `verified` is
+unchanged, and filler-word cuts (which sit in sound by design) are measured but not flagged.
+
+**`--timemap FILE` (2.22)** writes the source-to-output time map: every kept range with its
+source and output times, and every removed range with the output time it was cut at. `.csv`
+gives `type,source_start,source_end,output_start,output_end` rows (a removed row's two output
+columns are its cut point); any other path must end in `.json`. Use it to re-time subtitles
+made on the source, or to find a removed sentence again. Its times advance by the
+millisecond-rounded ranges the render cuts on; they are computed, not measured on the written
+file, so each kept range can be off by up to one video frame or audio block. An existing map is refused without `--overwrite`,
+and a missing directory or a directory at the path as `kind: input`, before anything runs (a dry
+run predicts both); the map is written only after the cut is, so a failed or refused encode
+leaves none. A dry run writes nothing.
+
 **`--filler` (1.17)** removes filler words as well, through the same
 `keep_ranges()` graph with more, shorter ranges. It is **never**
 applied without measured word timings: pass `--words` (a whisper JSON carrying

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

@@ -417,6 +417,7 @@ ERROR_REASONS = {
     "output_is_directory": "the output path is a directory; details: {output}",
     "output_dir_missing": "the output's directory does not exist; details: {output, directory}",
     "output_dir_not_writable": "the output's directory is not writable; details: {output, directory}",
+    "timemap_path_taken": "silence.py --timemap names the same file as -o, --edl or --plan; details: {timemap, flag, path}",
     "output_locked": "another run holds the output's lock; details: {lock, output, pid, pid_alive, deadline, why}",
     "plan_inputs_changed": "render.py PLAN: a fingerprinted input is missing or changed; details: {plan, plan_sha256, checked_at, "
                            "inputs: [{path, status: unchanged|changed|missing, expected: {size, sha256_head_tail}, actual: {size, "
@@ -472,6 +473,8 @@ DIAGNOSTIC_CODES = {
     "sync_low_confidence": ("warnings", "sync.py / multicam.py: a source's offset has a correlation confidence below 0.1; {path, confidence}"),
     "cropdetect_windows_failed": ("warnings", "cropdetect.py: sampled windows ffmpeg could not decode (windows_failed); {failed, windows, starts}"),
     "filler_words_untimed": ("warnings", "silence.py --filler: listed words in the transcript with no usable timing were not removed (filler.matched_untimed); {count}"),
+    "cut_near_sound": ("warnings", "silence.py: a cut point's level is within CUT_SOUND_MARGIN_DB of --threshold, so it may land in a breath or a word's weak tail (cut_warnings lists them)"),
+    "cut_levels_unmeasured": ("warnings", "silence.py: the source could not be decoded to measure the level at each cut; cut_points and cut_warnings are null (unmeasured, not silent)"),
     "filler_removal_caution": ("warnings", "silence.py --filler: a removed word that is often an ordinary word, or a discourse marker added with --filler-extra (also in filler.warnings)"),
     # media and defaults
     "silent_track_mixed": ("warnings", "audio.py --on-silent warn: a silent track was mixed anyway; {tracks}"),
@@ -630,8 +633,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

package/scripts/silence.py

@@ -6,7 +6,7 @@ side so words are not clipped, drops gaps shorter than --min-silence, and
 writes a frame-accurate re-encode in one pass (select, and ametadata for the sound).
 
 Examples:
-  python3 silence.py talk.mp4                                 # -35 dB, gaps >= 0.6 s, 0.15 s margin
+  python3 silence.py talk.mp4                                 # -35 dB, gaps >= 0.6 s, 0.2 s margin
   python3 silence.py talk.mp4 --threshold -40 --min-silence 1 --margin 0.25
   python3 silence.py talk.mp4 --list                          # print the silences and the resulting cut list, no output
   python3 silence.py talk.mp4 --edl keep.txt                  # also save the kept ranges (START-END per line, cut.py --segments format)
@@ -15,7 +15,7 @@ import argparse
 import json
 import os
 import sys
-from typing import Any, Dict, List, Tuple
+from typing import Any, Dict, List, Optional, Tuple
 
 # `detect` moved into _common/probe.py in 1.16.0 so metadata.py --auto-chapters can measure the
 # same silences without importing this tool; the body is unchanged and the name still lives here.
@@ -23,6 +23,8 @@ from _common import (filler_spans, FILLER_WORDS, FILLER_AMBIGUOUS, FILLER_DISCOU
                      FILLER_PAD, read_text_or_die)
 from _common import asr as _asr
 from _common.emit import warn
+from _common import refuse_existing_outputs, refuse_output_is_input, _check_output_path
+from _common.emit import refuse
 from _common import detect_silences as detect, STATE, video_args, add_common, apply_common, audio_codec_for, cfr_args, default_output, die, emit, ffmpeg_base, info, is_audio_output, print_json, probe, run, X264_PRESETS, measured_level_dbfs, fmt_secs
 
 
@@ -44,6 +46,13 @@ def merge_spans(spans: List[Tuple[float, float]]) -> List[Tuple[float, float]]:
     return out
 
 
+# around each cut, how many seconds on either side the level is measured over, and how close to
+# --threshold (in dB) that level may come before the cut is flagged: room tone sits far below the
+# threshold, a breath or a word's weak tail just under it
+CUT_LEVEL_WINDOW = 0.05
+CUT_SOUND_MARGIN_DB = 10.0
+CUT_LEVEL_RATE = 8000
+CUT_LEVEL_CHANNELS = 2  # measured one by one; a surround source is folded to two first
 DIGITAL_SILENCE_DB = -90.0  # 2.20: at or below this a span is digital silence (16-bit dither sits near -96)
 BREATH_FLOOR = 0.12  # shortest gap silencedetect is asked for under --speech-aware
 
@@ -88,6 +97,114 @@ def keep_ranges(silences: List[Tuple[float, float]], duration: float, margin: fl
     return keeps
 
 
+def time_map(keeps: List[Tuple[float, float]], duration: float) -> Dict[str, Any]:
+    """Each kept range with its time in the source and in the output, and each removed range with
+    the output time it was cut at: re-timing subtitles, or finding a removed sentence again."""
+    kept: List[Dict[str, float]] = []
+    removed: List[Dict[str, float]] = []
+    out, prev = 0.0, 0.0
+    for s, e in keeps:
+        # the render cuts on bounds rounded to the millisecond (between(t,s,e) below): advance by
+        # that rounded length, or every off-grid range adds its own error to every later time
+        s, e = round(s, 3), round(e, 3)
+        if s - prev > 0.0005:
+            removed.append({"source_start": round(prev, 3), "source_end": round(s, 3), "output_time": round(out, 3)})
+        kept.append({"source_start": round(s, 3), "source_end": round(e, 3),
+                     "output_start": round(out, 3), "output_end": round(out + (e - s), 3)})
+        out += e - s
+        prev = e
+    if duration - prev > 0.0005:
+        removed.append({"source_start": round(prev, 3), "source_end": round(duration, 3), "output_time": round(out, 3)})
+    return {"kept": kept, "removed": removed}
+
+
+def write_time_map(path: str, tm: Dict[str, Any]) -> None:
+    """--timemap: JSON, or CSV for a .csv path (one row per kept and removed range)."""
+    if os.path.splitext(path)[1].lower() == ".csv":
+        rows = ["type,source_start,source_end,output_start,output_end"]
+        rows += [f"kept,{k['source_start']:.3f},{k['source_end']:.3f},{k['output_start']:.3f},{k['output_end']:.3f}" for k in tm["kept"]]
+        rows += [f"removed,{r['source_start']:.3f},{r['source_end']:.3f},{r['output_time']:.3f},{r['output_time']:.3f}" for r in tm["removed"]]
+        text = "\n".join(rows) + "\n"
+    else:
+        text = json.dumps(tm, indent=2) + "\n"
+    # staged and swapped in, so a full disk or an interrupted write leaves the previous map whole;
+    # the staging name is short and unique, so it neither outgrows the name limit nor truncates a
+    # sibling that happens to exist
+    import tempfile
+    fd, tmp = tempfile.mkstemp(prefix=".tm", suffix=".tmp", dir=os.path.dirname(os.path.abspath(path)))
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(text)
+        mask = os.umask(0)  # mkstemp makes the file 0600; give the map the mode open() would have
+        os.umask(mask)
+        os.chmod(tmp, 0o666 & ~mask)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def cut_levels(path: str, tm: Dict[str, Any], duration: float,
+               filler_spans_: List[Tuple[float, float]]) -> Optional[List[Dict[str, Any]]]:
+    """The RMS level just around every cut, in dBFS (None for digital silence), measured on the
+    source: one decode at CUT_LEVEL_RATE, CUT_LEVEL_WINDOW on each side of the cut point. A probe
+    of the output can say its length and streams are right, not whether a cut landed in a breath
+    or a word's weak tail; the level there is the measurable part of that question. `edge` is
+    `out` where the source is left, `in` where it is picked up again; `filler` marks an edge that
+    sits on a removed word (it is meant to sit in sound). Each channel is measured on its own and
+    the loudest is reported: a mono mix reads antiphase stereo as silence. The PCM goes to a temp
+    file and only the windows are read back, so an hour of audio is not held in memory. None when
+    the decode fails: an unmeasured cut is not a silent one."""
+    import array
+    import math
+    import tempfile
+    from _common import require_tool, run_analysis
+    points = []
+    for r in tm["removed"]:
+        for t, edge in ((r["source_start"], "out"), (r["source_end"], "in")):
+            if (edge == "out" and t <= 0.0005) or (edge == "in" and t >= duration - 0.0005):
+                continue
+            # this edge, not the whole removed range: a filler merged into a silence leaves the
+            # silence's own edge next to speech, and that one still gets checked
+            on_word = any(fs - CUT_LEVEL_WINDOW <= t <= fe + CUT_LEVEL_WINDOW for fs, fe in filler_spans_)
+            points.append((t, r["output_time"], edge, on_word))
+    if not points:
+        return []
+    channels = CUT_LEVEL_CHANNELS
+    half = int(CUT_LEVEL_WINDOW * CUT_LEVEL_RATE)
+    frame = 2 * channels
+    out = []
+    with tempfile.TemporaryDirectory(prefix="silence-levels-") as tmp:
+        raw = os.path.join(tmp, "pcm.s16le")
+        proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-loglevel", "error", "-nostdin", "-i", path, "-vn",
+                             "-ac", str(channels), "-ar", str(CUT_LEVEL_RATE), "-f", "s16le", "-y", raw],
+                            check=False, text=False)
+        if proc.returncode != 0 or not os.path.isfile(raw) or not os.path.getsize(raw):
+            return None
+        with open(raw, "rb") as fh:
+            for t, ot, edge, on_word in points:
+                first = max(0, int(round(t * CUT_LEVEL_RATE)) - half)
+                fh.seek(first * frame)
+                data = fh.read(2 * half * frame)
+                block = array.array("h")
+                block.frombytes(data[: len(data) // frame * frame])
+                if sys.byteorder == "big":
+                    block.byteswap()
+                level = None
+                if block:
+                    n = len(block) // channels
+                    peak = max(math.sqrt(sum(x * x for x in block[c::channels]) / n) for c in range(channels)) / 32768.0
+                    level = round(20 * math.log10(peak), 1) if peak > 0 else None
+                entry = {"source_time": round(t, 3), "output_time": round(ot, 3), "edge": edge, "rms_dbfs": level}
+                if on_word:
+                    entry["filler"] = True
+                out.append(entry)
+    return out
+
+
 def _word_list(text: "str") -> "list":
     return [w.strip() for w in str(text or "").replace(",", "\n").splitlines() if w.strip()]
 
@@ -289,7 +406,7 @@ def main() -> int:
     ap.add_argument("-o", "--output", help="output file (default: <name>_tight.<ext>)")
     ap.add_argument("--threshold", type=float, default=-35.0, help="silence level in dBFS (default -35; use -40..-45 for quiet rooms)")
     ap.add_argument("--min-silence", type=float, default=0.6, help="only remove gaps at least this long in seconds (default 0.6)")
-    ap.add_argument("--margin", type=float, default=0.15, help="seconds of silence to keep on each side of speech (default 0.15)")
+    ap.add_argument("--margin", type=float, default=0.2, help="seconds of silence to keep on each side of speech (default 0.2; 0.15 before 2.22)")
     ap.add_argument("--min-keep", type=float, default=0.2, help="drop kept pieces shorter than this (default 0.2)")
     ap.add_argument("--speech-aware", action="store_true",
                     help="keep breaths shorter than --min-silence when they sit inside a sentence "
@@ -298,6 +415,10 @@ def main() -> int:
                          "with --filler through the same keep_ranges() removal list.")
     ap.add_argument("--list", action="store_true", help="only print silences and the kept ranges")
     ap.add_argument("--edl", help="write the kept ranges to this file, one START-END per line")
+    ap.add_argument("--timemap", metavar="FILE",
+                    help="write the source-to-output time map: every kept range with its source and output "
+                         "times and every removed range with the output time it was cut at; .csv for CSV, "
+                         "otherwise JSON (re-time subtitles, find a removed sentence again)")
     fil = ap.add_argument_group("filler words (1.17)")
     fil.add_argument("--filler", action="store_true",
                      help="also remove filler words. Needs measured word timings: pass --words or "
@@ -336,6 +457,20 @@ def main() -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    if args.timemap:
+        if os.path.splitext(args.timemap)[1].lower() not in (".json", ".csv"):
+            die(f"--timemap must end in .json or .csv: {args.timemap}", kind="input")
+        # before any decode or write, so a dry run predicts it too: a missing directory or a
+        # directory at the path is a `kind: input` refusal, not a traceback from open()
+        _check_output_path([args.timemap])
+        # --overwrite allows replacing an old map, never the source, the cut or the EDL
+        refuse_output_is_input(args.timemap, *[p for p in (args.input, args.words) if p])
+        for flag, other in (("-o", args.output), ("--edl", args.edl), ("--plan", getattr(args, "plan", None))):
+            if other and os.path.realpath(other) == os.path.realpath(args.timemap):
+                refuse("input", "timemap_path_taken",
+                       f"--timemap {args.timemap} is the same file as {flag}; give the map its own path",
+                       timemap=args.timemap, flag=flag, path=other)
+        refuse_existing_outputs([args.timemap])
 
     if args.filler_pad < 0:
         die("--filler-pad cannot be negative: a negative pad turns each word's span inside out "
@@ -431,6 +566,35 @@ def main() -> int:
             summary["hint"] = f"no passage sits below {args.threshold:g} dBFS for {args.min_silence:g}s; try a higher --threshold (e.g. -25) or a shorter --min-silence"
         info("hint: " + summary["hint"])
 
+    tm = time_map(keeps, duration)
+    points: Any = False  # False: not measured (a dry run over a pending input); None: the decode failed
+    if not (STATE.dry_run and not os.path.exists(args.input)):
+        points = cut_levels(args.input, tm, duration, list(filler_ranges))
+    if points is None:
+        warn("could not decode the source to measure the level at each cut; cut_points and cut_warnings are null "
+             "(unmeasured, not silent): listen at the cuts", "cut_levels_unmeasured")
+        summary["cut_points"] = summary["cut_warnings"] = None
+    elif points is not False:
+        near = [{k: v for k, v in c.items() if k != "filler"} for c in points
+                if not c.get("filler") and c["rms_dbfs"] is not None and c["rms_dbfs"] > args.threshold - CUT_SOUND_MARGIN_DB]
+        summary["cut_points"] = points
+        summary["cut_warnings"] = near
+        if near:
+            where = ", ".join("%.2fs" % c["source_time"] for c in near[:5]) + (", ..." if len(near) > 5 else "")
+            warn(f"{len(near)} cut point(s) sit within {CUT_SOUND_MARGIN_DB:g} dB of --threshold ({where}): "
+                 "a breath or a word's weak tail may be cut; listen there, or lower --threshold / raise --margin",
+                 "cut_near_sound", cuts=len(near))
+
+    def finish_time_map() -> None:
+        """Written last, once the cut it describes exists (or under --list, where the map is the
+        result): a map left beside a failed or refused encode would describe media never made."""
+        if not args.timemap:
+            return
+        if not STATE.dry_run:  # an artifact like the EDL: a plan writes nothing
+            write_time_map(args.timemap, tm)
+            info(f"wrote {args.timemap}")
+        summary["timemap"] = args.timemap
+
     if args.edl:
         if not STATE.dry_run:  # the EDL is an artifact like the cut itself: a plan writes nothing
             with open(args.edl, "w", encoding="utf-8") as fh:
@@ -439,6 +603,7 @@ def main() -> int:
         info(f"wrote {args.edl}")
 
     if args.list or args.filler_list:
+        finish_time_map()
         if args.json:
             emit(None, **summary)
         else:
@@ -469,6 +634,7 @@ def main() -> int:
     run(cmd)
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, expected ~{kept:.3f}s)")
+    finish_time_map()
     emit(output, **summary)
     return 0