ffmpeg-skill 3.8.12 → 3.8.14

package/README.md

@@ -331,6 +331,7 @@ rather than drifting silently. There is no separate `input_schema` file to forge
 ```bash
 npx ffmpeg-skill contract --json            # or: python3 scripts/_contract.py --json
 npx ffmpeg-skill contract --json --static   # without environment detection
+npx ffmpeg-skill contract --json --tool cut # one tool's entry under `tools` (repeatable): ~60 KB, not ~950 KB
 ```
 
 The contract is generated from the code that runs, not maintained beside it. For each of the 42 tools (`ffmpeg-skill/<name>`) it states:
@@ -514,7 +515,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/SKILL.md

@@ -16,7 +16,7 @@ Shared flags (the rest, codec defaults and `--hw`: `references/flags.md`):
 
 Writing tools run nothing under `--dry-run`; the measuring tools (`probe`, `check`, `sync`, `multicam`,
 `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`, `overlay`, `metadata`, `cut`, `render`,
-`batch`) may still run ffmpeg/ffprobe without writing artifacts; `verify` ignores the flag. Per tool: `contract --json` `dry_run`.
+`batch`) may still run ffmpeg/ffprobe without writing artifacts; `verify` ignores the flag. Per tool: `contract --json --tool NAME` `dry_run`.
 
 Audio-only files work in the audio tools; picture tools refuse them (`references/workflow.md#audio-only-files`).
 

package/docs/contract.md

@@ -7,6 +7,11 @@ dry-run, input preservation and repeatability. It is the interface a planning ag
 consumes instead of reading `SKILL.md`, which stays written for a coding agent that
 follows the workflow by hand.
 
+The whole document is about 950 KB, almost all of it the 42 `tools` entries. `--tool NAME`
+(repeatable; `cut` or `cut.py`) keeps only the named tools under `tools`, in the order given,
+and every other key as it is: about 55 to 85 KB for one tool. An unknown name is refused (exit
+2) with the list of tools, and `doctor` does not take the flag.
+
 The contract is derived from the code that runs, not maintained beside it:
 
 - the tool list is every script in `scripts/` that does not start with `_`;
@@ -21,7 +26,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.14`) | 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 +154,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.14", "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 +694,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 +820,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 |
 
@@ -950,7 +956,7 @@ A refusal also carries `error.reason`, a stable snake_case code for *why*
 `output_is_directory`, `output_dir_missing`, `output_dir_not_writable`, `output_locked`,
 `output_container_codecs` (a `.webm` output for an H.264/HEVC or AAC encode, which WebM cannot hold),
 `media_path_is_url` (`subfile,...:` included), `media_path_is_playlist` (an HLS, DASH, IMF or ffconcat playlist given as media, DASH and IMF told by content whatever the file is called), `media_path_has_line_break` (a path with a line break, which a concat list cannot hold),
-`output_looks_like_option` (an output starting with `-`, other than `-` for stdout), `output_path_taken` (two files one run writes share a path), `media_path_not_a_file` (a FIFO or device as input), `silence.py --timemap`'s `timemap_path_taken`, `join.py --copy`'s `join_copy_mismatch`,
+`output_looks_like_option` (an output starting with `-`, other than `-` for stdout), `output_extension_missing` (a media output with no file extension, which leaves ffmpeg no container to choose), `output_path_taken` (two files one run writes share a path), `media_path_not_a_file` (a FIFO or device as input), `silence.py --timemap`'s `timemap_path_taken`, `join.py --copy`'s `join_copy_mismatch`,
 `render.py`'s `plan_*` reasons, `--codec av1`/`prores`'s `encoder_missing` and
 `encoder_list_unreadable`, and `--transcribe`'s `asr_engine_missing`, `no_speech`, `engine_failed`
 and `english_only`), and `error.details`, the facts the message is written from, so a

package/mcp/server.py

@@ -18,7 +18,6 @@ Claude Desktop / Claude Code config example:
 """
 import json
 import os
-import subprocess
 import sys
 from pathlib import Path
 from typing import Any, Dict, List, Optional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.12",
+  "version": "3.8.14",
   "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": [
@@ -53,7 +53,10 @@
     "docs/contract.md",
     "SKILL.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "!**/__pycache__/**",
+    "!**/*.pyc",
+    "!**/*.pyo"
   ],
   "scripts": {
     "test": "python3 tests/run_parallel.py && python3 tests/test_contract.py",

package/references/flags.md

@@ -5,7 +5,7 @@ The long form of SKILL.md's Quick start. `--help` on a script is still its full
 
 ## Running the scripts
 
-Scripts live in `scripts/` next to SKILL.md; run them with `python3 <skill-dir>/scripts/<name>.py`, and delivery templates in `templates/`. SKILL.md is enough to do a job: SKILL.md's request table routes the request, and `--help` on the script about to run is the cheapest full flag list. A reference file costs as much as SKILL.md; open one only for a question you have: `references/scripts.md` (most flags; `--help` lists all), `references/devices.md` (iPhone HDR, GoPro, DJI, screen recordings, Zoom), `references/gotchas.md` (the long form of the one-line rules at the end of SKILL.md). MCP: `tools/list` shows only the core 12 by default; the other 30 (per SKILL.md's request table) stay callable by name via `tools/call`, described by `contract --json`; set `FFMPEG_SKILL_MCP_FULL=1` for all 42.
+Scripts live in `scripts/` next to SKILL.md; run them with `python3 <skill-dir>/scripts/<name>.py`, and delivery templates in `templates/`. SKILL.md is enough to do a job: SKILL.md's request table routes the request, and `--help` on the script about to run is the cheapest full flag list. A reference file costs as much as SKILL.md; open one only for a question you have: `references/scripts.md` (most flags; `--help` lists all), `references/devices.md` (iPhone HDR, GoPro, DJI, screen recordings, Zoom), `references/gotchas.md` (the long form of the one-line rules at the end of SKILL.md). MCP: `tools/list` shows only the core 12 by default; the other 30 (per SKILL.md's request table) stay callable by name via `tools/call`, described by `contract --json --tool NAME`; set `FFMPEG_SKILL_MCP_FULL=1` for all 42.
 
 ## Shared flags
 
@@ -13,4 +13,4 @@ Shared flags (every script accepts them; the exceptions are named): `--dry-run`
 
 ## What `--dry-run` runs
 
-Writing tools run no ffmpeg under `--dry-run` (ffprobe still reads an input that exists); the measuring tools (`probe` with `--analyze`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`; `overlay` for a multi-line `--text` on FFmpeg 8.0-8.1.0; `metadata` with `--auto-chapters`; `cut` with `--snap beats`) still run their ffmpeg measurements, skipping artifacts/side files (`--edl`, `--sheet`, a generated `.ass`), and `render` and `batch` run each stage or step as its own dry run; `verify` ignores the flag. Per tool: `contract --json` `dry_run`.
+Writing tools run no ffmpeg under `--dry-run` (ffprobe still reads an input that exists); the measuring tools (`probe` with `--analyze`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`; `overlay` for a multi-line `--text` on FFmpeg 8.0-8.1.0; `metadata` with `--auto-chapters`; `cut` with `--snap beats`) still run their ffmpeg measurements, skipping artifacts/side files (`--edl`, `--sheet`, a generated `.ass`), and `render` and `batch` run each stage or step as its own dry run; `verify` ignores the flag. Per tool: `contract --json --tool NAME` `dry_run`.

package/references/scripts.md

@@ -131,7 +131,10 @@ JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation
 (`hdr`, and `hdr_signal` equal to it, is true only for a PQ / HLG transfer or Dolby Vision -- since 2.0;
 `bt2020_or_hdr` also counts BT.2020 primaries on an SDR transfer, which `hdr_format` names "BT.2020 SDR"),
 `audio{codec,channels,sample_rate,start_time}` (`start_time`: where the stream starts on the file's
-own clock, `null` when unknown). `--compact` gives one line per file.
+own clock, `null` when unknown). `--compact` gives one line per file. `--field` prints one line
+per file: a string as itself and any other value as JSON (`true`, `{"codec": ...}`), an empty
+line for a field that is not there; with `--json` every line is JSON (a string quoted, a
+missing field `null`).
 
 ### cut.py — cut / join segments
 ```
@@ -147,7 +150,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.
@@ -338,7 +341,7 @@ the rectangle for you. Use this when the rectangle is already known (a
 face-detection box, a saved crop, a hand-picked region). The rectangle must
 lie entirely inside the source frame (after accounting for display rotation);
 `--width`/`--height` must be even (4:2:0 chroma) and are refused, never
-rounded, if they aren't.
+rounded, if they aren't; an odd `--x`/`--y` is taken as given.
 
 ### cropdetect.py — measure black bars, report the crop rectangle
 ```
@@ -429,7 +432,9 @@ Wraps FFmpeg's `v360` filter to bake out an ordinary flat clip pointed at a
 fixed direction — the same "look this way" operation a VR headset or a 360
 player's viewport does. `--yaw`/`--pitch`/`--roll` aim the camera (each
 -180..180, default 0); `--h-fov`/`--v-fov` set how wide the view is (each
-1..170, default 90/60). `--input-projection` must match the source's own
+1..170; `--h-fov` defaults to 90, and without `--v-fov` the vertical view is the
+one that keeps the output's pixels square, 58.7 at 90 and 1920x1080; a pair that
+is not square-pixel is drawn as given and said in `notes`). `--input-projection` must match the source's own
 projection (default `equirect`, the most common capture/export format) —
 this tool cannot detect it from the pixels, so a wrong value produces a
 distorted or garbled output, not an error. There is no subject detection or
@@ -502,7 +507,9 @@ a temporary transforms file (deleted after the run), pass 2 smooths and
 re-renders. `--shakiness` (default 5) trades analysis time for how much
 motion it looks for; `--smoothing` (default 15) is how many neighbouring
 frames the camera path is averaged over; `--zoom` crops in slightly to hide
-the black edges stabilizing can introduce. Needs an ffmpeg built with
+the black edges stabilizing can introduce, and is the only zoom applied (0, the
+default, keeps the original framing and lets the edges show: vidstab's own
+"optimal zoom" is off). Needs an ffmpeg built with
 `--enable-libvidstab`; `doctor` reports this tool `usable: no` when that's
 missing (a plain Homebrew ffmpeg build, for example) rather than failing at
 run time.
@@ -530,7 +537,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 +728,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 +777,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 +1213,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 +1632,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
@@ -1657,14 +1676,17 @@ Each step runs with `--json`, and a failed one keeps its tool's own `kind`,
 completed one carries the tool's `verified`. Steps that do not apply are listed
 under the file's `skipped` (`quick`, `no_video`, `no_audio`, `not_hdr`,
 `not_multichannel`, `input_unreadable`) and as SKIP rows in the report.
+`--overwrite` and `--fast` given to verify.py reach every step, so a rerun into the same
+`--out` replaces the earlier outputs. The outputs are kept in `--out`, or with `--keep` alone
+in a new folder; either is the result's `out_dir` (`null` when they were deleted).
 Run this first when a user hands over footage from a device you have not
 seen before, and fix or report what fails.
 
 ### look.py — see the result
 ```
-look.py INPUT [--tiles 4x3] [--width 1280] [-o sheet.png]         # contact sheet with timecodes
+look.py INPUT [--tiles 4x3] [--width 1280] [-o sheet.png]         # contact sheet with timecodes (-o basename -> basename_sheet.png)
 look.py INPUT --at 2.5 [--at 7] [-o basename]                     # single frames -> basename_2.500s.png
-look.py BEFORE --compare AFTER --at 4 [-o cmp.png]                # side-by-side frame
+look.py BEFORE --compare AFTER --at 4 [-o cmp.png]                # side-by-side frame (-o basename -> basename_vs_AFTER_0_4.000s.png)
 look.py INPUT --safe tiktok [--at 3]                              # shade what the app's UI covers
 look.py INPUT --guides title,action,4:3 [--at 3]                  # broadcast safe-area outlines
 ```
@@ -2015,7 +2037,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 +2054,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 +2195,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 +2229,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 +2290,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.
 
@@ -2336,7 +2380,8 @@ neither.
 proxy.py INPUT [--width W | --scale F] [--quality N] [--fps N] [--no-audio] [-o OUT]
 ```
 Not a delivery preset: resizes to `--width` (default 640) or by `--scale`
-factor, re-encodes at a proxy-grade `--quality` (default 30) with the fastest
+factor, never wider than the source and never under 2 px (a `notes` line says
+when either caps the width asked), re-encodes at a proxy-grade `--quality` (default 30) with the fastest
 x264/x265 preset, keeps the source's own dynamic range (HDR stays HDR;
 run `color.py --to-sdr` first if SDR is wanted) and keeps a subtitle/data
 track when the container can hold it (`dropped_non_av_streams`). Only executes the spec

package/scripts/_common/asr.py

@@ -1098,7 +1098,7 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
     _shutil = SafeShutil(_shutil)  # look engines up and launch them by full path, never from the working directory
     import subprocess as _subprocess
     import tempfile as _tempfile
-    from _common import require_tool, run_analysis, STATE
+    from _common import require_tool, STATE
     ffmpeg = require_tool("ffmpeg")
     wanted = requested_engine(engine)
     language = engine_language(language)

package/scripts/_common/color.py

@@ -395,8 +395,13 @@ def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float = 1000.0, desat: floa
     prim = v.get("color_primaries") or "bt2020"
     space = v.get("color_space") or "bt2020nc"
     source_peak = HLG_PEAK_NITS if trc == "arib-std-b67" else peak
-    # zscale needs explicit input tags when the file lacks them
-    chain: List[str] = [
+    # zscale needs explicit input tags when the file lacks them, and on 6.1 its `pin` does not
+    # reach a frame whose own primaries are unspecified ("no path between colorspaces", kind
+    # ffmpeg: --to-sdr --force on an untagged file failed through 3.8.8), so a frame missing a tag
+    # is labelled with what the chain reads it as first
+    missing = not (v.get("color_transfer") and v.get("color_primaries") and v.get("color_space"))
+    label = [f"setparams=color_primaries={prim}:color_trc={trc}:colorspace={space}"] if missing else []
+    chain: List[str] = label + [
         f"zscale=tin={trc}:pin={prim}:min={space}:rin={v.get('color_range') or 'tv'}:t=linear"
         f":npl={TONEMAP_REFERENCE_NITS:g}",
         "format=gbrpf32le",

package/scripts/_common/decision.py

@@ -695,6 +695,16 @@ def _vt_bt709(codec: str) -> List[str]:
     return ["-bsf:v", f"{codec}_metadata=colour_primaries=1:transfer_characteristics=1:matrix_coefficients=1"]
 
 
+def source_transfer(v: Dict[str, Any]) -> str:
+    """The transfer a 10-bit re-encode of a BT.2020 / HDR source is tagged with: the source's own
+    tag, or, when it has none, what probe() read it as. BT.2020 primaries with no transfer tag are
+    `hdr_format` "BT.2020 SDR" (not an HDR signal), so they are tagged bt2020-10, the SDR curve
+    BT.2020 defines; through 3.8.8 every such re-encode came out tagged HLG (audit A153). An
+    HDR signal with no transfer tag (Dolby Vision whose base layer is untagged) keeps the HLG
+    default it always had."""
+    return v.get("color_transfer") or ("arib-std-b67" if v.get("hdr_signal") else "bt2020-10")
+
+
 def _vt_args(codec: str, crf: int, meta: Optional[Dict[str, Any]], keep_bt709: bool) -> Optional[List[str]]:
     """VideoToolbox encoder options for `codec`, or None (with a note in STATE.hw_notes) when the
     request stays on the CPU: no VideoToolbox encoder for the codec, this machine cannot, or the
@@ -716,7 +726,7 @@ def _vt_args(codec: str, crf: int, meta: Optional[Dict[str, Any]], keep_bt709: b
     v = (meta or {}).get("video") or {}
     hdr = bool(v.get("bt2020_or_hdr"))
     hdr_tags = ["-colorspace", v.get("color_space") or "bt2020nc", "-color_primaries", v.get("color_primaries") or "bt2020",
-                "-color_trc", v.get("color_transfer") or "arib-std-b67"]
+                "-color_trc", source_transfer(v)]
     if codec == "prores":
         return ["-c:v", name, "-profile:v", "hq", "-pix_fmt", "p210le"] + (hdr_tags if hdr else [])
     # The HDR curve was fitted on the Main10 HEVC line; an 8-bit H.264 line (an export preset on
@@ -847,7 +857,7 @@ def _cpu_encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str
     hdr = bool(v.get("bt2020_or_hdr"))
     cs = v.get("color_space") or "bt2020nc"
     prim = v.get("color_primaries") or "bt2020"
-    trc = v.get("color_transfer") or "arib-std-b67"
+    trc = source_transfer(v)
     hdr_tags = ["-colorspace", cs, "-color_primaries", prim, "-color_trc", trc]
     if codec == "h264":
         if hdr:
@@ -1152,7 +1162,7 @@ def source_codec_video_args(meta: Optional[Dict[str, Any]], crf: int = 18, prese
 def _x265_hdr_default(v: Dict[str, Any], crf: int, preset: str) -> List[str]:
     cs = v.get("color_space") or "bt2020nc"
     prim = v.get("color_primaries") or "bt2020"
-    trc = v.get("color_transfer") or "arib-std-b67"
+    trc = source_transfer(v)
     x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1{hdr10_x265_params(v)}" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
     return ["-c:v", "libx265", "-preset", preset, "-crf", str(min(51, crf + 2)), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
             "-x265-params", x265, "-colorspace", cs, "-color_primaries", prim, "-color_trc", trc, "-movflags", "+faststart"]
@@ -1173,10 +1183,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 +1617,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 +1640,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: