ffmpeg-skill 2.21.1 → 2.22.1

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.1`) | any release |
+| `skill.version` | the npm / package.json version (`2.22.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.1", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.22.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"},
@@ -721,6 +721,15 @@ lost 40 s of sound with no error):
 | `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 |
@@ -797,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.1",
+  "version": "2.22.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

@@ -35,6 +35,7 @@ Every row names the constant or flag it comes from, and a test holds the table t
 | 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` |
@@ -639,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]
@@ -653,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/runner.py

@@ -553,6 +553,46 @@ def video_encoder_of(cmd: Sequence[str]) -> Optional[str]:
     return enc
 
 
+# A protocol prefix (`tcp:`, `http://`, `file:`, `concat:`, ...): ffmpeg opens such a value as a URL,
+# while every guard here reads it as a path. Two or more letters, so a Windows
+# drive letter (`C:\x.mp4`) is a path; `pipe:` is the skill's own stdout/stdin and stays allowed.
+_URL_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]+:")
+
+
+def looks_like_url(value: str) -> bool:
+    """True for a value ffmpeg would open through a protocol rather than as a local file."""
+    return bool(_URL_SCHEME.match(value)) and not value.startswith("pipe:")
+
+
+def _refuse_url_media(cmd: Sequence[str]) -> None:
+    """Refuse an ffmpeg/ffprobe command that names a URL as an input or as its output, before it
+    runs or is recorded. This skill reads and writes local files only, and the path guards below
+    (output-is-input, existing output, output directory) only mean something for a local path. A
+    `-f lavfi` input is a filtergraph, not a location, and is left alone; a local name that
+    contains a colon still works written as `./name`."""
+    base = os.path.basename(cmd[0])
+    if not (base.startswith("ffmpeg") or base.startswith("ffprobe")):
+        return
+    fmt = None
+    values = []
+    for i, a in enumerate(cmd[1:-1], start=1):
+        if a == "-f":
+            fmt = cmd[i + 1]
+        elif a == "-i":
+            if fmt != "lavfi":
+                values.append(cmd[i + 1])
+            fmt = None
+    last = cmd[-1]
+    if not last.startswith("-"):
+        values.append(last)
+    for value in values:
+        if looks_like_url(value):
+            refuse("input", "media_path_is_url",
+                   f"{value!r} would be opened by ffmpeg as a URL ({value.split(':', 1)[0]}:), not as a local file; "
+                   "this skill reads and writes local files only. Pass a plain path (a local name containing "
+                   "a colon works as ./name)", path=value, scheme=value.split(":", 1)[0].lower())
+
+
 def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
     """Refuse an ffmpeg command whose output path resolves to the same file as one of its
     inputs. ffmpeg's own "Output same as Input" guard only catches byte-identical path
@@ -615,6 +655,10 @@ def _check_output_path(cmd: Sequence[str]) -> None:
     output = cmd[-1]
     if output == "-" or output.startswith("pipe:") or output.startswith("-"):
         return
+    if looks_like_url(output):
+        refuse("input", "media_path_is_url",
+               f"output {output!r} would be opened by ffmpeg as a URL, not as a local file; pass a plain path "
+               "(a local name containing a colon works as ./name)", path=output, scheme=output.split(":", 1)[0].lower())
     if os.path.isdir(output):
         refuse("input", "output_is_directory",
                f"output {output!r} is a directory; pass a file path (e.g. {os.path.join(output, 'result.mp4')!r})", output=output)
@@ -1042,6 +1086,7 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
         # or runs the command (color.py imports this module, hence the late import)
         from _common.color import fold_bt709_matrix
         cmd = fold_bt709_matrix(cmd)
+        _refuse_url_media(cmd)
         _check_no_overwrite_input(cmd)
         _check_output_path(cmd)
         _check_existing_output(cmd)
@@ -1144,6 +1189,7 @@ def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, r
     wall-clock limit as any other ffmpeg invocation and, with check=True, the same `kind: ffmpeg`
     failure instead of an exit-0 "0 scenes found" over a file ffmpeg could not read. record=True
     lists the command in the --json `commands` like run() does."""
+    _refuse_url_media(cmd)
     if record:
         STATE.commands.append(_cmdline(cmd))
     limit = _limit_for(cmd)

package/scripts/_contract.py

@@ -415,8 +415,10 @@ ERROR_REASONS = {
     "output_exists": "an output already exists and --overwrite was not given; details.outputs: [{path, resolved, size, mtime_ns}]",
     "output_is_input": "the output resolves to the same file as an input; details: {output, input, resolved}",
     "output_is_directory": "the output path is a directory; details: {output}",
+    "media_path_is_url": "an input or output has a protocol prefix (tcp:, http://, file:, ...) that ffmpeg would open as a URL; the skill reads and writes local files only; details: {path, scheme}",
     "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 +474,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}"),

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