ffmpeg-skill 3.8.12 → 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.12`) | 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.12", "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.12",
+  "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

@@ -1173,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:
@@ -1590,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).
@@ -1613,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:

package/scripts/_contract.py

@@ -170,7 +170,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                      required=FF + [X264, AAC], optional=[HDR_X265],
                      video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "audio": dict(role="execution", inputs=["video or audio asset", "music bed (--music) or replacement track (--replace)", "effects/atmos track (--effects)"], outputs=["artifact with the processed audio (video stream-copied, or dropped when -o has an audio extension)"],
-                  required=FF, optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaincompress", "when": "--duck"},
+                  required=FF, optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaingate", "when": "--duck"}, {"capability": "filter:dcshift", "when": "--duck"},
                                         {"capability": "filter:acompressor", "when": "--compress / --voice"}, {"capability": "filter:alimiter", "when": "--limit / --voice strong"}, {"capability": "filter:agate", "when": "--gate"},
                                         {"capability": "filter:deesser", "when": "--voice medium (the default) / --voice strong"},
                                         {"capability": "filter:extrastereo", "when": "--stereo-widen"},
@@ -872,7 +872,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "silent": {"type": "array", "description": "--on-silent warn (default), only when a track was silent: [{flag, path, peak_db}] for each --music/--replace/--effects file, or under --duck the voice (flag \"input\"), whose whole-file peak is at or below --silence-threshold (default -50 dBFS); it was mixed anyway. --on-silent fail refuses instead, reason \"silent (peak X dBFS)\" in problems"},
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "present with `silent`: which tracks were silent and how to refuse them"},
                  "timing": {"type": "object", "description": "#486: {tempo, atempo, length_samples, sample_rate}: the --tempo factor (null without it), the atempo stages (each 0.5..2.0, [] at tempo 1) whose product it is, --length-samples (null without it) and the sample rate that count is in (null when not measured yet); with --length-samples a length_samples verification step counts the written track's decoded samples (exact for PCM/FLAC/ALAC, within tolerance_samples, one codec frame, for a lossy codec)"},
-                 "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, channel (--channel N, the 0-based channel kept, else null), sample_rate (--sample-rate, else null; both are read back from the output as the channels / sample_rate verification steps), effects/effects_volume, and with --music the music_volume plus duck (null when --duck was not given, else the threshold in dB and linear, ratio, attack_ms, release_ms, amount_db actually used)"}}
+                 "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, channel (--channel N, the 0-based channel kept, else null), sample_rate (--sample-rate, else null; both are read back from the output as the channels / sample_rate verification steps), effects/effects_volume, and with --music the music_volume plus duck (null when --duck was not given, else the threshold in dB and linear, the sidechain gate's ratio, attack_ms, release_ms, and amount_db, the depth in dB the bed is lowered under speech)"}}
     for key, prop in EMITTED_KEYS.get(name, {}).items():
         extra.setdefault(key, prop)
     if name in ("overlay", "graphics", "caption", "grid"):

package/scripts/_smartcut.py

@@ -110,6 +110,21 @@ def ineligible(params: Optional[Dict[str, Any]], meta: Dict[str, Any], ext: str)
     return None
 
 
+# Matroska stores every timestamp in milliseconds (its default TimestampScale), whatever the source's
+# time base: an .mkv output's stream reads 1/1000 however it is written
+MATROSKA_TIME_BASE = "1/1000"
+
+
+def expected_time_base(params: Dict[str, Any], ext: str) -> Optional[str]:
+    """The time base the joined output's video should read: the source's for MP4/MOV, whose time
+    scale execute() sets from it (-video_track_timescale), and Matroska's own for .mkv. Comparing a
+    .mkv against an MP4 source's 1/15360 failed every such cut, and only after the whole smart cut had
+    been built and checked (#462 A45)."""
+    if ext.lower() == ".mkv":
+        return MATROSKA_TIME_BASE
+    return params.get("time_base")
+
+
 def _rate(params: Dict[str, Any]) -> Optional[Fraction]:
     try:
         q = Fraction(str(params.get("r_frame_rate") or ""))
@@ -165,8 +180,10 @@ def plan_segment(packets: List[Tuple[Any, Any, bool]], s: float, e: float, vend:
         raise SmartFallback(f"the keyframe at {packets[k1][0]:.3f}s opens its GOP (frames decoded after it are shown "
                             "before it), so a copy cannot start there", "open_gop")
     k1_pts = packets[k1][0]
-    # where the copy stops: the last keyframe presented at or before the end bound, decoded after K1
-    stops = [i for i in keyidx if packets[i][1] > packets[k1][1] + 1e-9
+    # where the copy stops: the last keyframe presented at or before the end bound, decoded after K1.
+    # A segment that runs to the end of the video has no end bound to stop before: its copy runs
+    # to the end, and the last GOP is whole, so it is copied, not re-encoded as a tail (#462 A44)
+    stops = [i for i in keyidx if not to_end and packets[i][1] > packets[k1][1] + 1e-9
              and (end_bound is None or packets[i][0] <= end_bound + 1e-6)]
     k2 = stops[-1] if stops else None
     if k2 is not None and gop_is_open(packets, k2):
@@ -422,9 +439,10 @@ def verify(src: str, dst: str, parts: List[Dict[str, Any]], params: Dict[str, An
         decoded += g
         offset += n
     out_params = stream_params(dst) or {}
-    if out_params.get("time_base") != params.get("time_base"):
-        raise SmartFallback(f"the output's time base is {out_params.get('time_base')}, the source's "
-                            f"{params.get('time_base')}", "time_base")
+    want_tb = expected_time_base(params, os.path.splitext(dst)[1])
+    if out_params.get("time_base") != want_tb:
+        raise SmartFallback(f"the output's time base is {out_params.get('time_base')}, where "
+                            f"{want_tb} was expected (the source's is {params.get('time_base')})", "time_base")
     diff = mismatches(params, out_params)
     if diff:
         raise SmartFallback("the output's stream does not match the source: " + ", ".join(diff), "params_mismatch")