ffmpeg-skill 3.8.11 → 3.8.13

package/README.md

@@ -514,7 +514,7 @@ type on every OS.
 | Result | Measurement |
 |---|---|
 | **92 / 92** | verification steps on a 10-file real-device corpus (GoPro, DJI, iPhone incl. Dolby Vision, Android screen recordings, HDR10, 24p, Tears of Steel), 0.8.0, local ffmpeg 6.1 |
-| **40 / 40 within 10 ms** | `sync.py` offset detection, ±30 s offsets with gain, noise and EQ changes on real dialogue and music, 120 s windows (max error 1.1 ms); 60 s stress windows 95 % within 10 ms, 4 of 5 misses flagged by confidence |
+| **40 / 40 within 10 ms** | `sync.py` offset detection, ±30 s offsets with gain, noise and EQ changes on real dialogue and music, 120 s windows (max error 1.1 ms); 60 s stress windows 95 % within 10 ms, 4 of 5 misses flagged by confidence (the confidence of 3.8.8 and earlier; not re-run since its runner-up changed) |
 | **0 missed gaps** | `silence.py`, 20 cases with known gaps, ≤ 1 ms leftover silence |
 | **F1 0.97** | `scenes.py`, 53 hard cuts between single takes, precision 0.95, recall 1.00 at the default threshold |
 | **exact to the sample** | `cut.py --accurate` on WAV, FLAC (44.1 kHz) and AAC → WAV; WAV stream copy within 2 ms; AAC output +21 ms of encoder priming, reported as `codec_frame` (0.9.1) |

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.8.11`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.13`) | 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`
@@ -149,7 +149,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | 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"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.8.11", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.13", "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.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},
@@ -689,7 +689,8 @@ says "output audio is silent" instead of recommending `loudness.py`.
 Per-tool keys added in 1.13: `audio` (`audio.py`) reports the mix it built — the
 `--voice` level, `stereo_widen`, whether an `--effects` bed was mixed, and with
 `--music` the `music_volume` plus a `duck` object naming the threshold (dB and
-linear), ratio, attack and release actually used, or `null` when `--duck` was not
+linear), ratio (the sidechain gate's 9000 since A134), attack, release and `amount_db`
+(the depth in dB the bed is lowered under speech) actually used, or `null` when `--duck` was not
 given. Since #486 `audio.py` also reports `timing`, `{tempo, atempo, length_samples, sample_rate}`:
 the `--tempo` factor and the atempo stages (each 0.5..2.0) it was built from, `--length-samples`,
 and the rate that count is in (`null` before a pending input is measured); with
@@ -814,7 +815,7 @@ 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` |
+| `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 the sums of the ranges the render cuts on (with a picture each bound moved to its nearest frame time, never before 0; with sound alone the range as asked), unrounded until they are written to the millisecond, so no error adds up over many cuts. They are computed, not measured on the written file. 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 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.11",
+  "version": "3.8.13",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "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": [

package/references/scripts.md

@@ -147,7 +147,7 @@ by default since 3.0.0 (`--keep-hevc`; `--no-keep-hevc` uses x264 as 2.x did);
 `--codec` overrides all of them). `--accurate` always re-encodes; `--tolerance -1` never does for a keyframe snap
 (a `--segments` join of open-GOP video, one whose later B-frame `.mp4`/`.mov` segment starts
 between keyframes, or one that fails its check, still re-cuts).
-Multiple segments are concatenated in the order given. `--remove A-B,...` (2.24) is the inverse: the ranges are dropped (overlaps merged, clamped to the file) and what is left is cut as `--segments` would cut it; a leftover shorter than one frame is not kept, and a removal that leaves nothing is refused. It does not combine with `--segments`, `--start` (even `--start 0`), `--end`, `--duration` or `--snap beats` (a snapped edge could move into a dropped range). Since 2.17.2 every join the re-encode makes fades the sound for `--declick-ms` (20 ms) on each side, so butted cuts do not click; `--no-declick` butts them as before, and a stream-copy join (sound copied) is not faded. The result reports `declick_ms` (null when there was no re-encoded join). stderr reports whether
+Multiple segments are concatenated in the order given. `--remove A-B,...` (2.24) is the inverse: the ranges are dropped (overlaps merged, clamped to the file) and what is left is cut as `--segments` would cut it; a leftover shorter than one frame is not kept, nor (to a video output) one that holds less than one frame of picture, such as sound that runs past the last frame (a note names it), and a removal that leaves nothing is refused. It does not combine with `--segments`, `--start` (even `--start 0`), `--end`, `--duration` or `--snap beats` (a snapped edge could move into a dropped range). Since 2.17.2 every join the re-encode makes fades the sound for `--declick-ms` (20 ms) on each side, so butted cuts do not click; `--no-declick` butts them as before, and a stream-copy join (sound copied) is not faded. The result reports `declick_ms` (null when there was no re-encoded join). stderr reports whether
 the result was "lossless stream copy" or "re-encoded"; when the snap forced a
 re-encode, the result's `lossless_alternative` names the nearest keyframe
 `--start` that would stream-copy instead, so the trade can be offered.
@@ -530,7 +530,9 @@ Renders the input's audio as a video: `--style waveform` (default, FFmpeg's
 `showwaves`) draws amplitude over time; `--style spectrum` (`showspectrum`)
 draws a frequency-over-time heatmap instead, reading more out of dense
 mixes at the cost of being less immediately readable. The output always
-carries the audio it visualizes. For an audio-only input (no video stream
+carries the audio it visualizes. The default output of an audio input is
+`<name>_waveform.mp4` (an audio extension cannot hold the picture), and `-o` with an audio
+extension is refused. For an audio-only input (no video stream
 needed) or any file with an audio track worth visualizing.
 
 **Audiogram (1.16).** `--image PATH` puts a local still behind the
@@ -719,12 +721,14 @@ silence.py INPUT --filler --words transcript.json [--filler-lang auto|en|ja|ko|z
            [--transcribe] [--engine auto|parakeet-mlx|parakeet.cpp|whisper.cpp|faster-whisper|openai-whisper]
            [--model MODEL] [--filler-list] [--max-cuts 400]
 ```
-Runs `silencedetect`, keeps `--margin` seconds of air around speech, drops
+Runs `silencedetect`, keeps `--margin` seconds of air around speech (none at the start or the
+end of the sound, where there is no speech to keep it for), drops
 gaps shorter than `--min-silence`, and re-encodes the kept ranges the way `cut.py --segments
 --accurate` does: both streams cut on the same frame times, so the sound never drifts from the
 picture at the cuts, and a sound that starts late keeps its offset. `--list` prints silences, kept ranges and seconds removed
 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`
+so the user can edit the list by hand (written once the cut is, as `--timemap` is). `--max-cuts N`
+(400) refuses to render more than N removal ranges; `--list` reports them whatever their number. 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
@@ -766,9 +770,10 @@ unchanged, and filler-word cuts (which sit in sound by design) are measured but
 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`,
+made on the source, or to find a removed sentence again. Its times advance by the exact
+lengths of the ranges the render cuts on (with a picture, each bound on its nearest frame time;
+with sound alone, as asked), rounded only when written, so nothing adds up over many cuts; they
+are computed, not measured on the written file. 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.
@@ -1201,7 +1206,8 @@ scenes.py INPUT [--shots] [--audio-peaks] [--speech] [--json]
 ```
 Lists scenes with audio energy, the loudest moments, and (with
 `--highlights`) proposes N ranges that add up to `--target` seconds, biased to
-the loudest window of each scene. Review the sheet + JSON, adjust the EDL, then
+the loudest window of each scene; each range lies inside its scene (it starts at the cut or on
+the 0.5 s grid after it, to the hundredth rounded inward). Review the sheet + JSON, adjust the EDL, then
 `cut.py --segments`. Cut detection is a one-frame spike test (benchmark on
 hard cuts between real single takes: precision 0.95, recall 1.00 at the default
 threshold; raise `--threshold` to 12 for 0.98 precision at 0.94 recall).
@@ -1619,8 +1625,14 @@ multicam.py REF CAM2 [CAM3 ...] [--switch "START-END:CAM,..."|energy [--min-shot
 ```
 All inputs are aligned to the first one by audio (same engine as `sync.py`,
 `--fix-drift` for long takes). `--switch` names which camera is on screen for
-each range of the reference timeline (gaps fall back to camera 0), `--auto N`
-simply alternates every N seconds. Audio comes from the reference unless
+each range of the reference timeline (gaps fall back to camera 0; ranges that overlap are
+refused, `kind: input`, since each moment has one camera), `--auto N`
+simply alternates every N seconds. Under `--fix-drift` a drifting camera's picture is retimed
+with its sound (`setpts=(PTS-STARTPTS)/ratio`), so a range lasts its reference length on both;
+`--write-project`'s clips name that camera's own in/out, with the ratio as the clip's `speed`
+(render.py plays it at that rate, so it lasts its reference length there too), and the project states
+`"transition": {"type": "none"}`: a switch is a cut, and render.py's default 0.5 s crossfade at every join
+would run the timeline 0.5 s a switch short and move each later switch. Audio comes from the reference unless
 `--audio` picks another input, e.g. an external recorder that has no video.
 `--offsets-only` reports offsets and confidence without rendering. `cuts` names
 the camera actually rendered: a range whose camera has not started yet plays
@@ -2015,7 +2027,8 @@ sync.py REFERENCE SOURCE [SOURCE ...] [--json] [--max-offset 30] [--analyze-seco
 ```
 Cross-correlates loudness envelopes: coarse FFT search (20 ms), then a direct
 1 ms refinement (pure Python, a 2-minute window takes ~1-3 s). Positive offset
-= the source recording started later. `--replace-audio` writes the reference
+= the source recording started later, so `--trim-second`/`--replace-audio` delay it by that
+much (a negative one drops its first -offset seconds). `--replace-audio` writes the reference
 video with the source file's audio aligned (video stream copied); the output
 keeps the reference's full length -- a shorter or head-trimmed source file is
 padded with silence, never allowed to cut the picture.
@@ -2031,8 +2044,11 @@ could not be measured is skipped and says why: `drift_skipped_reason` is
 `too_short` (no tail window far enough from the head) or `low_confidence`
 (top level for one source, and in each `sources` entry; null when applied).
 Check `confidence`
-(0–1, normalised correlation with a runner-up penalty); below 0.3 the match is
-doubtful. Benchmark on real dialogue/music (±30 s offsets, gain, noise, EQ):
+(0–1, normalised correlation with a runner-up penalty: the best other peak more than five
+steps from the winner); below 0.3 the match is doubtful. Since A126 the runner-up is never the
+winner's own neighbour, which held an exact match at 0.59, so a clean match can read near 1.0 and a
+tie between two offsets reads at most 0.5. The benchmark below was measured with the earlier runner-up and has
+not been re-run since; on real dialogue/music (±30 s offsets, gain, noise, EQ):
 with the default 120 s window 40/40 within 10 ms (max 1.1 ms); with a 60 s
 window 95 %, misses flagged below 0.3. Keep `--analyze-seconds` at least 4×
 `--max-offset` (default 120 s vs 30 s): lags with under 35 % overlap are
@@ -2169,10 +2185,13 @@ highpass, and `medium`/`strong` run their own denoise stage at that strength
 that is off is refused, as the `--duck-*` flags are: `--denoise-strength` without
 `--denoise`, `--music-volume`, `--music-fade-out` or `--music-loop` without `--music`,
 `--effects-volume` without `--effects` (a value equal to the default is not seen as given).
-`--duck` uses a sidechain compressor keyed by the speech so music dips under
-dialogue and swells in pauses:
-`sidechaincompress=threshold=0.05:ratio=<amount/3, min 2>:attack=20:release=400:makeup=1`
-by default. `--duck-threshold DB` (default −26.02 dBFS, i.e. the 0.05 linear),
+`--duck` lowers the music by `--duck-amount` dB (0..60, default 12) while the speech is above
+`--duck-threshold`, and leaves it at its level in the pauses: a sidechain gate keyed by the
+speech passes the bed under speech, and that part, scaled by `-(1 - 10^(-amount/20))`, is added
+back to the bed (`sidechaingate=threshold=0.05:ratio=9000:range=0:knee=1:attack=20:release=400`, then
+`volume=-0.748811` for 12 dB, by default). Through 3.8.8 it was a sidechain compressor whose
+ratio was `amount/3` (at least 2), so the depth followed the speech's level, not the flag
+(audit A134). `--duck-threshold DB` (default −26.02 dBFS, i.e. the 0.05 linear),
 `--duck-attack MS` (20) and `--duck-release MS` (400) move each one; a lower
 threshold ducks on quieter speech, a shorter release brings the bed back faster.
 `--json`'s `audio` block reports the settings the run actually used.
@@ -2200,7 +2219,19 @@ swresample. Video is always stream-copied, and so is a subtitle/data track
 when the container can hold it (`dropped_non_av_streams` says when it could not).
 `--limit` (and `--voice strong`'s limiter) is `alimiter` with `level=disabled:latency=1`: the
 look-ahead is compensated, so the limited sound starts on the input's own sample instead of
-`--limit-attack` (5 ms, 240 samples at 48 kHz) late against the picture (#476).
+`--limit-attack` (5 ms, 240 samples at 48 kHz) late against the picture (#476). With `--music`
+or `--effects` both limiters run on the mix, after the beds are added: the combined mix is
+limited before it is encoded (A129). A lossy output (`.m4a`, `.mp3`, `.opus`, AAC beside a
+picture) can then peak over the ceiling, since the encoder works after the limiter; use
+`loudness.py` for final levels, which measures the written file. Without a bed they run on the
+main track, where they always ran.
+The typed dynamics flags speak dB where the filter takes a linear value: a knee
+(`--comp-knee`, `--gate-knee`) is 0..18.06 dB, the filters' linear 1..8, default 9.03 dB
+(2.82843); the defaults `--help` gives are ffmpeg's own, in the flag's unit (A135).
+`--bitrate` is the AAC rate beside a picture (192k) and the rate of a lossy audio output's
+codec (`.m4a`/`.aac` 256k, `.mp3` `-q:a 0`, `.ogg` `-q:a 6`, `.opus` 128k when it is not given);
+`.wav` and `.flac` refuse it (A143). A `--music-fade-out` on a bed shorter than the output (and
+not `--music-loop`ed) ends where the bed ends (A142).
 With `--replace`, `--music` or a kept picture the sound is padded with silence or trimmed to the
 source's length counted in samples at the track's rate (`apad=whole_len=N,atrim=end_sample=N`),
 so it is exact to the sample, not to the millisecond (#478). Sound that starts after the picture
@@ -2249,8 +2280,11 @@ video containers or the codec matching the extension (.wav → PCM, .flac, .mp3)
 The written file is measured again: a lossy encoder can push peaks past the
 ceiling loudnorm held (ffmpeg's AAC at 192k turned one transient from -2.4 to
 +3.7 dBFS). When it does, the tool re-encodes -- first at 256k then 320k if you
-did not pass `--audio-bitrate`, then with the loudnorm ceiling lowered by the
-overshoot -- until the file itself meets `--tp`. `result` reports
+did not pass `--audio-bitrate` (an `.m4a`/`.aac` output starts at its 256k, so only 320k is
+left), then with the loudnorm ceiling lowered by the overshoot -- until the file itself meets
+`--tp`. A pinned `--audio-bitrate` reaches an audio output's codec as well as a video
+container's AAC (through 3.8.8 an `.m4a` was 256k whatever was asked, and its retries too);
+`.wav`/`.flac` refuse it. `result` reports
 `tp_ceiling_used`, `audio_bitrate_used`, `encodes`, and a `note` when the
 integrated loudness ended more than 1 LU from the target because of it.
 

package/scripts/_common/decision.py

@@ -176,6 +176,16 @@ def fmt_secs(value: Optional[float]) -> str:
     return "?s" if value is None else f"{value:.3f}s"
 
 
+def ntsc_rate(fps: float) -> float:
+    """`fps` as the rate it is a rounding of: 23.976, 29.97, 47.952, 59.94 and 119.88 (what
+    probe() reports, and what a caller types after `@`) are N * 1000 / 1001. Any other rate is
+    returned as it is. timeline.exact_rate() reads the same five rates the same way."""
+    whole = round(fps * 1.001)
+    if whole in (24, 30, 48, 60, 120) and abs(fps - whole / 1.001) < 0.01 and abs(fps - whole) > 0.01:
+        return whole * 1000 / 1001
+    return fps
+
+
 def parse_time(value: str, fps: Optional[float] = None) -> float:
     """Accept seconds ('12.5'), mm:ss ('1:30'), hh:mm:ss(.ms) ('00:01:30.250'), SRT '00:01:30,250',
     or -- when `fps` is given -- SMPTE non-drop-frame timecode 'hh:mm:ss:ff' ('00:01:30:15')."""
@@ -212,7 +222,10 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
         # 3596.4 s of video). This is exactly what fmt_smpte_time() inverts; before, the two
         # disagreed by ~0.1 % on the fractional NTSC rates and drifted apart over long files.
         total_frames = (int(h) * 3600 + int(m) * 60 + int(s)) * whole_fps + frame
-        return total_frames / fps
+        # at the picture's exact rate: probe()'s `fps` is rounded to three decimals, and frame 37
+        # counted at 29.97 is 1.2345679 s, 1.2 microseconds past the frame at 37 * 1001 / 30000,
+        # so a start read from 00:00:01:07 was the frame after it (ntsc_rate)
+        return total_frames / ntsc_rate(fps)
     if len(parts) > 3:
         raise ValueError(f"bad time: {value}")
     total = 0.0
@@ -315,7 +328,9 @@ def fmt_smpte_time(seconds: float, fps: float) -> str:
     if seconds < 0:
         seconds = 0.0
     whole_fps = int(round(fps))
-    total_frames = int(round(seconds * fps))
+    # the frames are counted at the rate parse_time() reads the same text at (29.97 as
+    # 30000/1001): at 29.97 itself 06:00:00:00 came back as 05:59:59:29
+    total_frames = int(round(seconds * ntsc_rate(fps)))
     frame = total_frames % whole_fps
     secs_total = total_frames // whole_fps
     h, rem = divmod(secs_total, 3600)
@@ -440,6 +455,56 @@ def grid_at_or_after(t: float, v0: float, rate: float) -> float:
     return v0 + math.ceil((t - v0) * rate - 1e-6) / rate
 
 
+def frame_window(start: Optional[float], end: Optional[float], meta: Optional[Dict[str, Any]],
+                 half_open: bool = False) -> Optional[Tuple[Optional[float], Optional[float]]]:
+    """The two times a filter compares a frame's `t` with so that a window from `start` to `end`
+    seconds of `meta`'s picture holds the frames asked: half a frame before the first frame at or
+    after `start`, and half a frame after the last frame at or before `end` (`half_open`: half a
+    frame before the first frame at or after `end`, which is then outside). A bound written as
+    the time itself is compared with `t` on the frame it names: `{:.3f}` put frame 37 of a
+    30000/1001 picture (1.234567 s) after a start of "1.235", and `t` is a double (pts x time
+    base) that is not always the number the text reads as (the frame at 1.4 s of a 25 fps MP4 is
+    not `<= 1.400`; FFmpeg 6.1.1). The grid is the one grid_at_or_after() counts on. None when
+    there is no grid to count on (no rate: a dry run's pending input; a picture probe() suspects
+    of a variable rate): the caller keeps the text it had. A bound of None stays None."""
+    v = (meta or {}).get("video") or {}
+    rate = frame_rate(meta)
+    if not rate or v.get("variable_frame_rate_suspected"):
+        return None
+    v0, half = stream_starts(meta)[0], 0.5 / rate
+    lo = None if start is None else grid_at_or_after(start, v0, rate) - half
+    if end is None:
+        hi = None
+    elif half_open:
+        hi = grid_at_or_after(end, v0, rate) - half
+    else:
+        hi = v0 + math.floor((end - v0) * rate + 1e-6) / rate + half
+    return lo, hi
+
+
+def window_expr(start: Optional[float], end: Optional[float], meta: Optional[Dict[str, Any]],
+                half_open: bool = False) -> str:
+    """The expression that is true on the frames of frame_window(): `between(t,LO,HI)`, or
+    `gte(t,LO)` with no end. With no start the window opens at 0, as it always did. Without a
+    grid it is the millisecond text the tools wrote before."""
+    bounds = frame_window(start, end, meta, half_open)
+    if bounds is None:
+        lo = f"{start:.3f}" if start is not None else "0"
+        return f"gte(t,{lo})" if end is None else f"between(t,{lo},{end:.3f})"
+    lo = f"{bounds[0]:.6f}" if bounds[0] is not None else "0"
+    return f"gte(t,{lo})" if bounds[1] is None else f"between(t,{lo},{bounds[1]:.6f})"
+
+
+def windowed_overlay_x(x: Any, window: str) -> str:
+    """An `overlay` x that puts the layer at `x` on the frames `window` is true on and off the
+    picture on every other frame. overlay's `enable` is not the main picture's alone: FFmpeg
+    evaluates it on each frame either input hands over, the layer's next one included, so a still
+    looped at 25 fps over a 30000/1001 picture was drawn from the frame before the window's
+    first to the frame before its last (36-66 for 37-67; FFmpeg 6.1.1). The position is
+    evaluated once per output frame with the main picture's `t`."""
+    return f"'if({window},{x},-w)'"
+
+
 def av_trim(start: float, end: Optional[float], rate: float = 0.0, fill_gaps: bool = False) -> Tuple[str, str]:
     """The video and the audio filters that cut one segment [start, end) of the graph clock out of
     both streams and shift both by the same constant, so an offset between them survives; `end`
@@ -536,6 +601,28 @@ def silence_filter(rate: Optional[int], lead: Optional[float] = None, tail: Opti
     return ",".join(parts)
 
 
+def tpad_length(seconds: float, meta: Optional[Dict[str, Any]]) -> float:
+    """How long the picture `tpad=start_duration={seconds:.3f}` puts ahead of `meta`'s clip is:
+    tpad adds whole frames, the nearest count to the text it is given (0.23425 s at 25 fps is
+    written "0.234" and becomes 6 frames, 0.240 s). A sound delayed by `seconds` itself would
+    start up to half a frame before or after the picture it belongs to; delayed by this length it
+    moves with it (both streams of a clip shift by one constant: #409). `seconds` as it is when
+    there is no rate to count frames at (a dry run's pending input) or probe() suspects a
+    variable one."""
+    v = (meta or {}).get("video") or {}
+    rate = frame_rate(meta)
+    if not rate or v.get("variable_frame_rate_suspected"):
+        return seconds
+    try:
+        exact = Fraction(str(v.get("r_frame_rate") or ""))
+    except (ValueError, ZeroDivisionError):
+        exact = None
+    if exact is None or abs(float(exact) - rate) > 1e-6:
+        exact = Fraction(rate).limit_denominator(1001)
+    frames = math.floor(Fraction(f"{seconds:.3f}") * exact + Fraction(1, 2))  # a half rounds up, as av_rescale does
+    return float(frames / exact)
+
+
 def av_clip_length(meta: Optional[Dict[str, Any]], fps: float) -> float:
     """The one length a clip holds once both streams start at its first frame (av_trim from the
     video's start): the video's, or where the sound ends when it runs more than a frame past the
@@ -1086,10 +1173,27 @@ AUDIO_CODECS = {
 }
 
 
-def audio_codec_for(output_path: str, default_bitrate: str = "192k") -> List[str]:
-    """Pick an audio codec that the output container can actually hold."""
+LOSSLESS_AUDIO_EXT = {".wav", ".flac"}  # the AUDIO_CODECS whose codec takes no bitrate
+
+
+def audio_codec_for(output_path: str, bitrate: Optional[str] = None) -> List[str]:
+    """Pick an audio codec that the output container can actually hold.
+
+    `bitrate` is one the caller asked for: it replaces the rate or quality an audio extension
+    names (`-q:a 0` for .mp3, 256k for .m4a), which through 3.8.8 it never reached (A143), and is
+    the AAC rate of any other container (192k when it is None). A lossless extension takes none;
+    the caller refuses a bitrate for it."""
     ext = os.path.splitext(output_path)[1].lower()
-    return list(AUDIO_CODECS.get(ext, ["-c:a", "aac", "-b:a", default_bitrate]))
+    if ext not in AUDIO_CODECS:
+        return ["-c:a", "aac", "-b:a", bitrate or "192k"]
+    args = list(AUDIO_CODECS[ext])
+    if bitrate is None or ext in LOSSLESS_AUDIO_EXT:
+        return args
+    for flag in ("-b:a", "-q:a"):
+        if flag in args:
+            i = args.index(flag)
+            del args[i:i + 2]
+    return args + ["-b:a", bitrate]
 
 
 def is_audio_output(output_path: str) -> bool:
@@ -1503,7 +1607,7 @@ def _refine_grid(onset_times: "Sequence[float]", strengths: "Sequence[float]", i
     it), and onset_time = phase + k * interval is solved for both unknowns with each pair weighted
     by its onset strength squared; the pairing is then redone against the refitted grid, until it
     stops moving (three passes at most). This only sharpens the grid the autocorrelation chose --
-    the tempo cannot leave `bpm_range`, an octave cannot flip (a refit that moves the interval by
+    the tempo cannot leave `bpm_range` (a fit beyond a bound is held on it), an octave cannot flip (a refit that moves the interval by
     more than interval/BEAT_ALIGN_DIVISOR is discarded), and fewer than four paired grid points
     keep the original: the fit needs evidence, and an onset-free stretch gives it none.
     Returns phase in [0, interval).
@@ -1526,8 +1630,13 @@ def _refine_grid(onset_times: "Sequence[float]", strengths: "Sequence[float]", i
         if sxx <= 0:
             break
         new_iv = sum(w * (k - mk) * (t - mt) for k, t, w in pairs) / sxx
-        if not (60.0 / hi_bpm <= new_iv <= 60.0 / lo_bpm) or abs(new_iv - interval) > interval / BEAT_ALIGN_DIVISOR:
+        if abs(new_iv - interval) > interval / BEAT_ALIGN_DIVISOR:
             break
+        # A146: a fit just outside `bpm_range` is held on its bound, not discarded. A tempo that
+        # sits on the bound (90 BPM under --beat-range 60-90) fits a hair beyond it as often as
+        # inside, and discarding the fit kept the step-rounded interval (89.76 BPM), whose grid
+        # was 80 ms off a 30 s click track by its end
+        new_iv = min(max(new_iv, 60.0 / hi_bpm), 60.0 / lo_bpm)
         new_ph = mt - new_iv * mk
         moved = abs(new_iv - iv) < 1e-9 and abs(new_ph - ph) < 1e-7
         iv, ph = new_iv, new_ph

package/scripts/_common/emit.py

@@ -640,14 +640,43 @@ def stream_inventory_step(meta: Dict[str, Any], expect: Dict[str, Any]) -> Dict[
     return step
 
 
+def _finite(v: Any) -> Optional[float]:
+    return float(v) if isinstance(v, (int, float)) and math.isfinite(v) else None
+
+
+def own_length(s: Optional[Dict[str, Any]]) -> Optional[float]:
+    """The length of one probed stream (`meta["video"]`, `meta["audio"]`): its duration, else the
+    DURATION tag Matroska/WebM keep, which is where the stream ENDS on the file's clock (the
+    muxer's last timestamp plus its packet's duration), not how long it lasts: a sound from 1 s
+    to 6 s is tagged 6. The tag less the stream's start (from 0 when the start is a priming
+    frame before 0). A value that is not a finite number is no length (a NaN compares false and
+    would pass every check)."""
+    s = s or {}
+    duration = _finite(s.get("duration"))
+    if duration is not None and duration > 0:
+        return duration
+    tagged = _finite(s.get("tagged_duration"))
+    if tagged is None:
+        return None
+    length = tagged - max(_finite(s.get("start_time")) or 0.0, 0.0)
+    return length if length > 0 else None
+
+
+def own_end(s: Optional[Dict[str, Any]]) -> Optional[float]:
+    """Where one probed stream ends on the file's own timestamps: its start plus its duration,
+    else the Matroska/WebM DURATION tag, which is already that end."""
+    s = s or {}
+    duration = _finite(s.get("duration"))
+    if duration is not None and duration > 0:
+        return (_finite(s.get("start_time")) or 0.0) + duration
+    if own_length(s) is None:
+        return None
+    return _finite(s.get("tagged_duration"))
+
+
 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
+    """One stream's own length (own_length())."""
+    return own_length(meta.get(kind))
 
 
 LENGTH_UNREAD_HINT = ("remux the file so its container states a length (export.py INPUT --preset copy -o remuxed.mkv), "
@@ -674,9 +703,8 @@ def input_length(meta: Optional[Dict[str, Any]], path: Optional[str] = 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
+    """Where one stream ends on the file's timeline (own_end())."""
+    return own_end(meta.get(kind))
 
 
 def file_origin(meta: Dict[str, Any]) -> float:

package/scripts/_common/probe.py

@@ -43,11 +43,16 @@ def fingerprint(path: str) -> Dict[str, Any]:
 
 
 def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None, start: float = 0.0,
-                    *, check: bool = True) -> List[float]:
+                    *, check: bool = True) -> "Sequence[float]":
     """Decode (part of) a file's audio to mono float samples in [-1, 1) at `sample_rate` via a
     single ffmpeg pass under --timeout. Shared by scenes.py (audio envelope for cut scoring) and
     sync.py (cross-correlation); an undecodable input is kind ffmpeg when check=True, else [].
-    The samples are on the file's clock: a sound that starts late is padded at its head."""
+    The samples are on the file's clock: a sound that starts late is padded at its head.
+
+    The samples are an array('f'), 4 bytes each: a list of Python floats took about 32 (24 for the
+    float, 8 for the slot), so scenes.py held ~2.3 GB per hour of audio at 8 kHz + 22.05 kHz and
+    multicam --switch energy one such list per camera (A140). An s16 sample divided by 32768 is
+    exact in a float32, so every value read back is the double the list held."""
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin"]
     if start:
@@ -65,9 +70,15 @@ def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None
         if check:
             die(f"could not decode audio from {path}:\n{proc.stderr.decode(errors='replace').strip()}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr.decode(errors="replace")))
         return []
-    n = len(proc.stdout) // 2
-    import struct
-    return [v / 32768.0 for v in struct.unpack(f"<{n}h", proc.stdout[: n * 2])]
+    import array
+    import sys
+    data, proc = proc.stdout, None
+    pcm = array.array("h")
+    pcm.frombytes(memoryview(data)[: len(data) // 2 * 2])
+    del data
+    if sys.byteorder == "big":
+        pcm.byteswap()  # s16le on the pipe
+    return array.array("f", (v / 32768.0 for v in pcm))
 
 
 def rms_envelope(samples: Sequence[float], step: int, *, full_blocks_only: bool = False, remove_mean: bool = False) -> List[float]:
@@ -203,6 +214,23 @@ def shorter_than_a_loudness_block(length: "Optional[float]") -> bool:
     return length is not None and 0 < length < LOUDNESS_BLOCK_SECONDS
 
 
+def riff_wave_args(path: str) -> List[str]:
+    """`-f wav` for a file that opens with a RIFF/WAVE header. FFmpeg 9.0.2 scores its MPEG-TS
+    probe above the WAV one when the PCM happens to hold 0x47 at a transport packet's spacing (a
+    steady tone can): ffprobe then reads a file this skill has just written as a broken transport
+    stream and fails with "End of file". The header says what the file is, so the probe is told.
+    Measured on 9.0.2 (CI): the same file fails unforced and reads with `-f wav`; 6.1 to 8.0 read
+    it either way."""
+    if not os.path.isfile(path):  # a pipe or a device is never opened here: the open would block
+        return []
+    try:
+        with open(path, "rb") as fh:
+            head = fh.read(12)
+    except OSError:
+        return []
+    return ["-f", "wav"] if head[:4] == b"RIFF" and head[8:12] == b"WAVE" else []
+
+
 def probe(path: str, role: str = "input") -> Dict[str, Any]:
     """Return a compact, script-friendly description of a media file.
 
@@ -229,7 +257,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         die(f"input not found: {path}")
     ffprobe = require_tool("ffprobe")
     proc = run(
-        [ffprobe, "-v", "error", *still_input_args(path),
+        [ffprobe, "-v", "error", *still_input_args(path), *riff_wave_args(path),
          "-print_format", "json", "-show_format", "-show_streams", "-show_chapters", path],
         quiet=True,
         check=False,

package/scripts/_common/runner.py

@@ -2109,11 +2109,56 @@ def _set_refusal_note(ctx: "Context", reason: str, outcome: str) -> None:
     ctx.hw_notes.append(reason + outcome)
 
 
+# A filter graph longer than this is handed to ffmpeg in a file (A138). Linux refuses any single
+# argument over 128 KiB (MAX_ARG_STRLEN) and Windows a whole command line over 32767 characters, and
+# a graph grows with the items it is built from: scenes.py --sheet's select expression is ~56
+# characters a scene, so ~2,340 scenes raised OSError E2BIG before ffmpeg ran, with a traceback and
+# no JSON. A graph under the limit is passed as it always was.
+LONG_FILTER_CHARS = 8000 if os.name == "nt" else 100_000
+_FILTER_OPTION_RE = re.compile(r"^-(?:filter_complex|lavfi|vf|af|filter(?::[^\s]+)?)$")
+
+
+def _filter_file_option(option: str) -> str:
+    """The option that reads `option`'s value from a file: `-/OPTION` from FFmpeg 7.0, which
+    deprecated the `_script` spellings, and `-filter_complex_script` / `-filter_script[:spec]`
+    before it (6.x, the oldest CI runs)."""
+    complex_graph = option in ("-filter_complex", "-lavfi")
+    spec = {"-vf": ":v", "-af": ":a"}.get(option, option[len("-filter"):] if option.startswith("-filter:") else "")
+    if ffmpeg_version() >= (7, 0):
+        return "-/filter_complex" if complex_graph else "-/filter" + spec
+    return "-filter_complex_script" if complex_graph else "-filter_script" + spec
+
+
+@contextlib.contextmanager
+def long_filters_in_files(cmd: Sequence[str]) -> "Any":
+    """`cmd` with every filter graph longer than LONG_FILTER_CHARS moved into a temp file read by
+    ffmpeg's file form of the same option; the files are removed when the block ends. The command a
+    run records and prints is the caller's own, with the graph inline."""
+    import tempfile
+    out = list(cmd)
+    made: List[str] = []
+    try:
+        if _is_ffmpeg(out):
+            for i in range(1, len(out) - 1):
+                if _FILTER_OPTION_RE.match(out[i]) and len(out[i + 1]) > LONG_FILTER_CHARS:
+                    fd, path = tempfile.mkstemp(prefix="ffmpeg-skill-graph-", suffix=".txt")
+                    made.append(path)
+                    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                        fh.write(out[i + 1])
+                    out[i], out[i + 1] = _filter_file_option(out[i]), path
+        yield out
+    finally:
+        for path in made:
+            with contextlib.suppress(OSError):
+                os.remove(path)
+
+
 def _execute(exec_cmd: List[str]) -> subprocess.CompletedProcess:
     """One attempt, never exiting on failure (run() decides after its retries)."""
-    if STATE.progress and _is_ffmpeg(exec_cmd) and exec_cmd[-1] != "-":
-        return _run_with_progress(exec_cmd, False)
-    return _run_captured(exec_cmd, False)
+    with long_filters_in_files(exec_cmd) as cmd:
+        if STATE.progress and _is_ffmpeg(cmd) and cmd[-1] != "-":
+            return _run_with_progress(cmd, False)
+        return _run_captured(cmd, False)
 
 
 def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, record: bool = False) -> subprocess.CompletedProcess:
@@ -2134,7 +2179,8 @@ def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, r
         # input filename on stderr, and loudness/check parse the loudnorm JSON out of it. The
         # encoding kwargs are rejected with text=False, so they are only passed for text mode.
         text_kw = {"encoding": "utf-8", "errors": "replace"} if text else {}
-        proc = subprocess.run(list(cmd), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=text, **text_kw, timeout=limit)
+        with long_filters_in_files(cmd) as exec_cmd:
+            proc = subprocess.run(exec_cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=text, **text_kw, timeout=limit)
     except subprocess.TimeoutExpired:
         _timed_out(cmd, limit or 0)
     if check and proc.returncode != 0: