ffmpeg-skill 3.2.1 → 3.2.2

package/README.md

@@ -292,7 +292,7 @@ WAV, FLAC, MP3, M4A/AAC, OGG and Opus go through `probe`, `cut`, `join`, `silenc
 - **Typed dynamics.** `audio.py --compress --comp-threshold -20 --comp-ratio 4`, `--limit --limit-ceiling -1`, `--gate --gate-threshold -45`. Each flag is one documented option of FFmpeg's `acompressor`, `alimiter` or `agate`, range-checked before ffmpeg runs; no filter string is accepted from the caller.
 - **Loudness.** `loudness.py talk.wav -I -16 --tp -1.5 -o talk.m4a` for podcast levels; `check.py talk.m4a --platform podcast` measures LUFS and true peak and reports the chapter markers and channel count.
 
-Picture tools (`fit`, `caption`, `overlay`, `graphics`, `color`, `export`, `scenes`, `look`) refuse an audio file with "input has no video stream" instead of inventing a picture.
+Picture tools (`fit`, `caption`, `overlay`, `graphics`, `color`, `export`, `look`) refuse an audio file with "input has no video stream" instead of inventing a picture. `scenes.py` measures an audio file (`audio_only: true`, one scene): `--beats`, `--audio-peaks`, `--speech` and `--highlights` run on the sound, and `--sheet` / `--shots` are refused.
 
 ## Built for agents
 
@@ -390,7 +390,7 @@ The short list for humans. The agent-facing version, with the reasoning, is the
 - **Cropping 16:9 to 9:16 discards 70 % of the width.** `fit.py --fit crop` centres by default; pass `--crop-x`/`--crop-y` toward the subject, or pad with `--fit pad --pad-fill blur`. Look at the contact sheet before deciding.
 - **Phrase-aware caption breaking (1.16).** `caption.py`/`graphics.py --wrap phrase` (the default) never breaks inside a word or on the wrong side of a hyphen, never leaves a lone digit, kana or punctuation pair on a line, prefers Japanese sentence ends and particles over a mid-word break, and never ends a line on an article or preposition. All four are penalties over break positions that already fit, so no line is widened and the line count never changes; `--wrap measured` restores 1.15's width-only wrap. The text itself is never rewritten or shortened. Since 1.16.1 a Thai run and a katakana word are never broken inside (Thai writes no space inside a phrase and there is no dictionary: the break goes where you put a space or `|`), and a line wider than the safe width is reported as `overlong` with the fix named.
 - **Caption size fitted to the cue (1.17, reachable from the templates since 1.17.1).** At a platform caption size a line holds about six em, so an ordinary sentence needs four lines and `--max-lines 2` used to cut it into consecutive cues — half the sentence arriving late. `caption.py --fit-size` (default `auto`) walks the size down until every cue fits, *before* laying the cues out, with a legibility floor of 4.5 % of the frame height (`--min-size`, default 13 ASS units). An explicit `--size` or a `brand.json` size is a statement about the look and is never overridden — which in 1.17.0 also silenced the fitter on every `render.py --template` run, since a template fills the size from the platform table; 1.17.1 marks that size as the default it is (`"fit_size": "on"` in the filled project), so the type shrinks and no cue is split. `--fit-size off` restores that earlier behaviour byte for byte, and the caption text is still never rewritten to make it fit.
-- **Beat-synced cuts (1.17).** `scenes.py --beats` reports the measured grid — tempo, beat times, and a confidence built from how far the winning autocorrelation lag stands above the others and how many onsets land on it. `cut.py --snap beats` (and a `"snap"` block in a `render.py` project) moves in/out points to the nearest beat within `--snap-tolerance` — and only onto the grid points a measured onset actually marks, never onto the regular grid's continuation through a passage with no music in it. Below `--min-confidence` it **refuses**: a cut point may move to a measured beat and may not appear from one, so speech and ambience get an honest "no steady pulse here" instead of an invented grid.
+- **Beat-synced cuts (1.17).** `scenes.py --beats` reports the measured grid — tempo, beat times, and a confidence built from how far the winning autocorrelation lag stands above the others and how many onsets land on it. `cut.py --snap beats` (and a `"snap"` block in a `render.py` project) moves in/out points to the nearest beat within `--snap-tolerance` — and only onto the grid points a measured onset actually marks, never onto the regular grid's continuation through a passage with no music in it. Below `--min-confidence` it **refuses**: a cut point may move to a measured beat and may not appear from one, so speech and ambience get an honest "no steady pulse here" instead of an invented grid. A music bed is measured as it is delivered, WAV/FLAC/MP3 with no picture; on a synthetic click track at 90 and 120 BPM every beat is within 1 ms (WAV/FLAC) or 9 ms (MP3) of its click, `tests/test_analysis.py` holds it to 20 ms.
 - **Filler words (1.17).** `silence.py --filler --words transcript.json` removes "um" and "uh" through the same cut graph the silences use. Never without measured word timings — there is no heuristic that finds an "um" without them that would not also cut real speech — and `like`, `tipo` and `cioè` are deliberately not in the built-in lists, because a discourse marker is a content word. Built-in lists since 2.19: English, Japanese, Korean, Chinese, Spanish, German, French, Portuguese, Italian, Dutch, Polish, Russian and Turkish; any other language takes `--filler-words FILE`. Whisper stays optional: `--transcribe` with no engine installed refuses and names the five installs.
 - **Throughput (1.17).** `batch.py --jobs N` runs several files at once, capped at `min(N, cpu_count, 8)` and sharing one `--timeout` budget rather than one per item; the per-item table keeps its order. `render.py --cache DIR` reuses stages whose inputs and arguments did not change, so swapping an export preset re-runs export only. The cache is opt-in with no default directory, and the ffmpeg, skill and contract versions are part of every key, so a cache is never reused across them.
 - **Audiogram (1.16).** `waveform.py --image cover.png` (or `render.py --template audiogram`) puts the waveform over a still plate for an episode that has no picture, with `--platform` for the frame, `--title` and burnt-in captions. The image is a local file you give: nothing is fetched and no cover art is ever invented.

package/SKILL.md

@@ -102,7 +102,7 @@ Variants, caveats and extra flags per row: `references/requests.md`.
 | "cut the ums and uhs" | `silence.py in.mp4 --filler --words words.json` |
 | "just the real pauses, not inside a sentence" | `silence.py in.mp4 --speech-aware` |
 | "a 60 s highlight from this hour" | `scenes.py long.mp4 --highlights 6 --target 60 --edl picks.txt` (then `cut.py --segments` with picks.txt's lines joined by commas) |
-| "cut on the beat" | `cut.py in.mp4 --segments ... --snap beats --snap-source beats.json` (`scenes.py --beats`) |
+| "cut on the beat" | `cut.py in.mp4 --segments ... --snap beats --snap-source beats.json` (`scenes.py --beats`; a WAV/MP3 music bed too) |
 | "speed up here, slow-mo there" | `speedramp.py in.mp4 --segment 0-3:1.0 --segment 3-4:0.25` |
 | "freeze the last frame" | `freeze.py clip.mp4 --hold 2` |
 | "smooth slow motion" | `fit.py in.mp4 --duration 2x --smooth interpolate` |

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.2.1`) | any release |
+| `skill.version` | the npm / package.json version (`3.2.2`) | 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.2.1", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.2.2", "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"},
@@ -191,7 +191,7 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:
 | `reencodes_video`, `reencodes_audio` | `"always"` / `"never"` / `"conditional"`, meaning *when that stream is present in the input* — not whether the tool touches the file at all. `"conditional"` tools (`cut`, `export`, `render`, `batch`, `verify`, `caption`, `color`, `join`) carry a `reencode_note` explaining what it depends on — for `caption`, `--mode burn` (default) always re-encodes both streams, `--mode mux` copies both untouched; for `color`, `--strip-dovi` and `--retag` are a stream copy of both (retag only re-encodes if the copy attempt fails or ffprobe still reads the old tags on the copy), while `--to-sdr` / `--lut` / `--correct` always re-encode both; for `join`, `--copy --transition none` copies both, every other join re-encodes both. Several visual tools (`fit`, `overlay`, `graphics`, `multicam`, `silence`) are `"always"` on audio too: this codebase never mixes `-c:v` re-encode with `-c:a copy` in one call, so a caller cannot assume the original audio codec survives just because only the picture changed |
 | `audio_only` | accepts an audio-only input (WAV, MP3, M4A, FLAC, OGG, Opus) |
 | `video_required` | refuses an input without a video stream ("input has no video stream") |
-| | `render` has `audio_only: true` and `video_required: false` since 2.17.4: `--template podcast` and `--template audiogram` take an audio file. `join` has them since 0.9.1: audio-only inputs are joined as audio (no `look` needed then); mixing audio and video inputs is refused |
+| | `scenes` has `audio_only: true` and `video_required: false` after 3.2.0: an audio-only file is one scene, measured by `--beats`, `--audio-peaks`, `--speech` and `--highlights` (result key `audio_only: true`); `--sheet` and `--shots` refuse it. `render` has `audio_only: true` and `video_required: false` since 2.17.4: `--template podcast` and `--template audiogram` take an audio file. `join` has them since 0.9.1: audio-only inputs are joined as audio (no `look` needed then); mixing audio and video inputs is refused |
 | `deterministic_inputs`, `idempotency_hint` | see Repeatability |
 | `mcp` | the MCP tool name and its positional arguments |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/references/scripts.md

@@ -1072,7 +1072,7 @@ already has a picture.
 ### scenes.py — scene changes and highlight candidates
 ```
 scenes.py INPUT [--threshold 10] [--min-scene 1] [--highlights N [--target SECONDS] [--max-scene 15]] [--edl picks.txt] [--sheet scenes.png] [--json]
-scenes.py INPUT --beats [--beat-step 0.01] [--beat-range 60-200] [--min-confidence 0.5] [--json]
+scenes.py INPUT --beats [--beat-step 0.01] [--beat-range 60-200] [--min-confidence 0.5] [--json]   # INPUT may be audio-only
 scenes.py INPUT [--shots] [--audio-peaks] [--speech] [--json]
 ```
 Lists scenes with audio energy, the loudest moments, and (with
@@ -1106,6 +1106,23 @@ on the grid. With `--beats` the file is decoded once, at 22050 Hz, and the
 `supported + unsupported == len(beats)` always, and `supported_beats` is that
 supported subset — the list `cut.py --snap beats` moves onto.
 
+**Audio-only input and timing (after 3.2.0).** INPUT may be a WAV, FLAC, MP3 or any
+file with no video stream: no scene detection runs, the file is one scene from 0 to
+its duration, and the document carries `"audio_only": true`. `--beats`,
+`--audio-peaks`, `--speech` and `--highlights` measure the sound; `--sheet` and
+`--shots` need a picture and are refused (`kind: input`). Three things set how close
+the grid is to the music, each of which was off by tens of ms before:
+`beat_grid.step_s` is the envelope's real step (220 samples at 22050 Hz = 9.977 ms
+for `--beat-step 0.01`; timing it as 10 ms stretched every time by 0.23 %, 68 ms over
+30 s); the tempo and phase are refitted by weighted least squares to the strongest
+onset at each grid point, so a tempo between two envelope steps (90 BPM = 0.6667 s)
+is not rounded to one (0.67 s, 3.3 ms a beat); and each onset is placed on the
+decoded samples (`onset_refinement: "pcm-window-ratio"`) instead of at the start of
+its 10 ms block. A grid point within 10 ms before 0 s is the beat at `0.0`; one further before is not reported (it would make `0.0` a snap target the grid does not mark). Measured on
+synthetic click tracks at 90 and 120 BPM (first click at 0, 0.137 and 0.25 s): every
+beat within 1 ms on WAV/FLAC, 9 ms on MP3 (the encoder's pre-echo), 6 ms through AAC;
+the test holds every click to 20 ms.
+
 With `--beats` the file is decoded once, at 22050 Hz, and the 0.5 s scene
 envelope is derived from that same pass rather than from a second 8 kHz decode.
 One consequence worth knowing: `scenes.py X --json` and `scenes.py X --beats

package/scripts/_common/decision.py

@@ -1220,25 +1220,128 @@ def _grid_score(onset_times: "Sequence[float]", strength_at: "Dict[int, float]",
     return total
 
 
+BEAT_ZERO_TOL_S = 0.01      # a fitted grid point this little before 0 s is the beat at 0.0
+BEAT_REFINE_TOL_NATS = 1.0  # onset refinement: the latest time within this of the best log ratio
+
+
+def refine_onset_times(onset_times: "Sequence[float]", step_s: float, pcm: "Sequence[float]",
+                       rate: int) -> "List[float]":
+    """Each envelope-step onset time placed at the sample where the sound starts. Pure.
+
+    An onset picked on the step_s envelope is only known to the step: it is the start of the block
+    the level rose in, so a click is reported up to one step early (5 ms on average at 10 ms).
+    Around each one, over [t - step, t + 2 step], every candidate time c is scored by
+    log(energy of [c, c + step]) - log(energy of [c - step, c]) -- the rise from the step before c
+    to the step after it, which is largest where the sound starts. Ahead of a hit out of digital
+    silence that score is flat (the window before is silent wherever it ends), so the LATEST
+    candidate within BEAT_REFINE_TOL_NATS of the best is taken: past the start, the window before
+    fills with the hit's own attack and the score falls off at once. Candidates are 0.25 ms apart.
+    A time the PCM does not cover is returned unchanged.
+    """
+    rate = int(rate)
+    w = max(1, int(round(step_s * rate)))
+    hop = max(1, int(round(rate * 0.00025)))
+    n = len(pcm)
+    out: "List[float]" = []
+    for t in onset_times:
+        centre = int(round(t * rate))
+        lo, hi = centre - w, centre + 2 * w
+        if lo - w < 0 or hi + w > n:
+            out.append(t)
+            continue
+        base = lo - w
+        prefix = [0.0]
+        acc = 0.0
+        for x in pcm[base:hi + w + 1]:
+            acc += x * x
+            prefix.append(acc)
+        scored = []
+        for c in range(lo, hi + 1, hop):
+            k = c - base
+            before = (prefix[k] - prefix[k - w]) / w
+            after = (prefix[k + w] - prefix[k]) / w
+            scored.append((math.log(after + 1e-12) - math.log(before + 1e-12), c))
+        best = max(sc for sc, _ in scored)
+        c_best = max(c for sc, c in scored if sc >= best - BEAT_REFINE_TOL_NATS)
+        out.append(c_best / rate)
+    return out
+
+
+def _refine_grid(onset_times: "Sequence[float]", strengths: "Sequence[float]", interval: float,
+                 phase: float, lo_bpm: float, hi_bpm: float) -> "tuple":
+    """(interval, phase) refitted by weighted least squares to the onsets that land on the grid.
+
+    Each grid point k is paired with the STRONGEST onset within interval/BEAT_ALIGN_DIVISOR of it
+    (one per point: the weak onsets noise and a hit's own decay leave around a beat must not pull
+    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
+    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).
+    """
+    iv, ph = float(interval), float(phase)
+    for _ in range(3):
+        tol = iv / BEAT_ALIGN_DIVISOR
+        best: "Dict[int, tuple]" = {}
+        for t, st in zip(onset_times, strengths):
+            k = round((t - ph) / iv)
+            if abs(t - (ph + k * iv)) <= tol and (k not in best or st > best[k][1]):
+                best[k] = (t, st)
+        pairs = [(k, t, max(st, 1e-9) ** 2) for k, (t, st) in best.items()]
+        if len(pairs) < 4:
+            break
+        sw = sum(w for _, _, w in pairs)
+        mk = sum(w * k for k, _, w in pairs) / sw
+        mt = sum(w * t for _, t, w in pairs) / sw
+        sxx = sum(w * (k - mk) ** 2 for k, _, w in pairs)
+        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:
+            break
+        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
+        if moved:
+            break
+    return iv, ph % iv
+
+
 def beat_grid(envelope: "Sequence[float]", step_s: float, *,
               bpm_range: "Sequence[float]" = (60, 200),
               min_confidence: float = BEAT_MIN_CONFIDENCE,
-              duration: "Optional[float]" = None) -> "Dict[str, Any]":
+              duration: "Optional[float]" = None,
+              pcm: "Optional[Sequence[float]]" = None,
+              pcm_rate: "Optional[int]" = None) -> "Dict[str, Any]":
     """A beat grid from an RMS envelope. Pure: numbers in, a dict out -- no ffmpeg, no I/O.
 
     Returns {"beats": [t, ...], "tempo_bpm": float|None, "interval": float|None,
              "confidence": 0..1, "onsets": [t, ...], "phase": float,
              "supported": int, "unsupported": int, "usable": bool,
-             "method": "rms-flux-autocorrelation", "step_s": step_s, "range_bpm": [lo, hi]}
+             "method": "rms-flux-autocorrelation", "step_s": step_s, "range_bpm": [lo, hi],
+             "onset_refinement": "pcm-window-ratio" | None}
+
+    `step_s` must be the envelope's real step (block samples / rate), not the one asked for:
+    every time below is index * step_s. `pcm` and `pcm_rate`, when given, are the samples the
+    envelope was built from; each onset is then placed on them (refine_onset_times) instead of at
+    the start of its envelope block.
 
     The method, in full, so a report can quote it:
       1. onset strength = half-wave-rectified first difference of log(env + 1e-9);
-      2. onsets = local maxima above median + 1.5 * MAD over a +/-1 s window, 60 ms refractory;
+      2. onsets = local maxima above median + 1.5 * MAD over a +/-1 s window, 60 ms refractory,
+         each placed to 0.25 ms on `pcm` when it is given;
       3. tempo = the best autocorrelation lag of the onset signal inside `bpm_range`, with its
          half and double checked and the one whose onsets align better preferred (octave
          disambiguation: 60, 120 and 240 BPM all autocorrelate on a 120 BPM track);
       4. phase = the offset in [0, interval) at which the grid catches the most onset strength;
-      5. beats = phase + n * interval across the duration. A grid must be regular, so a grid
+         then interval and phase are refitted by least squares to the onsets within interval/8 of
+         the grid (_refine_grid), so the tempo is not rounded to a whole number of envelope steps
+         (until 3.2.0, at 10 ms, 90 BPM was measured as 0.67 s and the grid drifted 40-90 ms off the
+         music over 30 s);
+      5. beats = phase + n * interval across the duration (a point within BEAT_ZERO_TOL_S, 10 ms,
+         before 0 s is reported at 0.0; one further before is not reported). A grid must be regular, so a grid
          point with no measured onset within interval/4 is still reported -- and counted in
          `unsupported`, so a caller can see how much of the grid the audio actually supports.
          `supported_beats` is the subset that a measured onset does support: it is what a tool
@@ -1262,6 +1365,7 @@ def beat_grid(envelope: "Sequence[float]", step_s: float, *,
         "confidence": 0.0, "onsets": [],
         "phase": 0.0, "supported": 0, "unsupported": 0, "usable": False,
         "method": "rms-flux-autocorrelation", "step_s": step_s, "range_bpm": [lo_bpm, hi_bpm],
+        "onset_refinement": None,
     }
     if len(env) < 4 or step_s <= 0:
         return out
@@ -1272,6 +1376,10 @@ def beat_grid(envelope: "Sequence[float]", step_s: float, *,
         return out
     idx = _pick_onsets(strength, step_s)
     onset_times = [i * step_s for i in idx]
+    if pcm and pcm_rate:
+        # the PCM the envelope came from places each onset to the sample (refine_onset_times)
+        onset_times = refine_onset_times(onset_times, step_s, pcm, int(pcm_rate))
+        out["onset_refinement"] = "pcm-window-ratio"
     out["onsets"] = [round(t, 4) for t in onset_times]
     if len(idx) < 2:
         return out
@@ -1312,11 +1420,29 @@ def beat_grid(envelope: "Sequence[float]", step_s: float, *,
         if alt_score > base_score * BEAT_OCTAVE_MARGIN:
             interval, phase, base_score = alt, alt_phase, alt_score
 
+    # The autocorrelation lag is a whole number of envelope steps, so the interval it gives is the
+    # true one rounded to step_s: 90 BPM (0.6667 s) comes out as 0.67 s at 10 ms, 3.3 ms per beat
+    # that a phase+n*interval grid accumulates to tens of ms within a bar or two of either end
+    # (40-90 ms over 30 s). Refit interval and phase to the onsets themselves (_refine_grid).
+    interval, phase = _refine_grid(onset_times, [strength[j] for j in idx], interval, phase,
+                                   lo_bpm, hi_bpm)
+
     beats = []
-    t = phase
-    while t <= total_s + 1e-9:
-        beats.append(round(t, 4))
-        t += interval
+    # The first grid point at or after 0, where "at" allows BEAT_ZERO_TOL_S (one 10 ms envelope
+    # step, the accuracy the grid had before the refit): a track that starts on the beat has no
+    # measurable onset at 0 (there is no step before it), so its phase is fitted from the later
+    # beats and lands a few ms either side of 0 -- that is the beat at 0.0, not a dropped one. A
+    # point further before 0 is not moved there: 0.0 would then be a time the grid does not mark
+    # (a 120 BPM grid with phase 0.46 has its point at -0.04 s), and an onset at 0.08 s would make
+    # it a "supported" snap target. Indexing by n instead of adding the interval up keeps the
+    # float error of a long file out of the last beats.
+    n = -1 if phase - interval >= -BEAT_ZERO_TOL_S else 0
+    while True:
+        t = phase + n * interval
+        if t > total_s + 1e-9:
+            break
+        beats.append(round(max(0.0, t), 4))
+        n += 1
     support_tol = interval / BEAT_SUPPORT_DIVISOR
     supported_beats = [b for b in beats
                        if any(abs(b - o) <= support_tol for o in onset_times)]

package/scripts/_contract.py

@@ -208,10 +208,10 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                                                   {"capability": "filter:blackdetect", "when": "--content (black row)"}, {"capability": "filter:freezedetect", "when": "--content (frozen row)"},
                                                   {"capability": "filter:silencedetect", "when": "--content (silence row)"}],
                   video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=False, idempotency="bit_exact", deterministic=True),
-    "scenes": dict(role="analysis", inputs=["video asset"], outputs=["scene / audio-peak / highlight JSON on stdout", "EDL text (--edl)", "per-scene contact sheet PNG (--sheet)"],
+    "scenes": dict(role="analysis", inputs=["video asset", "audio asset (after 3.2.0: one scene; --beats, --audio-peaks, --speech, --highlights; --sheet and --shots need a picture)"], outputs=["scene / audio-peak / highlight JSON on stdout", "EDL text (--edl)", "per-scene contact sheet PNG (--sheet)"],
                    required=FF + ["filter:scdet"], optional=[{"capability": "filter:drawtext", "when": "--sheet"}, {"capability": "filter:tile", "when": "--sheet"},
                                                             {"capability": "ffmpeg", "when": "--beats (one audio decode for the onset pass)"}],
-                   video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=True, idempotency="bit_exact", deterministic=True),
+                   video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=True, idempotency="bit_exact", deterministic=True),
     "look": dict(role="verification", inputs=["video artifact"], outputs=["PNG contact sheet / frames / side-by-side"],
                  required=FF + ["filter:tile"], optional=[{"capability": "filter:drawtext", "when": "timecode stamps (default; without drawtext the sheet is drawn without them, fallback look_no_drawtext)"},
                                                           {"capability": "filter:drawbox", "when": "--safe NAME (the platform's occluded zones)"}, {"capability": "filter:zscale", "when": "HDR source"}, {"capability": "filter:tonemap", "when": "HDR source"}],
@@ -604,7 +604,10 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
         extra = {"file": {"type": "string"}, "duration": {"type": "number"}, "scene_count": {"type": "integer"}, "scenes": {"type": "array"}, "audio_peaks": {"type": "array"},
                  "shots": {"type": "array", "description": "--shots (1.18): [{start, end, label, flow_magnitude}]"},
                  "audio_peaks_db": {"type": "array", "description": "--audio-peaks (1.18): [{time, level}] measured dBFS, distinct from audio_peaks above"},
-                 "speech": {"type": "array", "description": "--speech (1.18): [{time, speech_music_ratio}]"}}
+                 "speech": {"type": "array", "description": "--speech (1.18): [{time, speech_music_ratio}]"},
+                 "audio_only": {"type": "boolean", "description": "After 3.2.0: present (true) when the input has no video stream: no scene detection ran and the file is one scene, 0 to its duration"},
+                 "beats": {"type": "array", "description": "--beats (1.17): the regular beat grid, seconds"},
+                 "beat_grid": {"type": "object", "description": "--beats (1.17): {supported_beats, tempo_bpm, interval, confidence, phase, onsets, supported, unsupported, method, step_s (the envelope's real step: 220/22050 s for --beat-step 0.01, after 3.2.0), range_bpm, usable, onset_refinement (after 3.2.0: pcm-window-ratio when each onset was placed on the decoded samples, else null)}"}}
     elif name == "silence":
         extra = {"silences": {"type": "array"}, "keep": {"type": "array"}, "input_duration": {"type": "number"}, "kept_duration": {"type": "number"}, "removed_seconds": {"type": "number"},
                  "removed_seconds_total": {"type": "number", "description": "--filler: seconds removed in all, silence plus filler words (removed_seconds stays the silence alone)"},

package/scripts/cut.py

@@ -1204,8 +1204,11 @@ def _grid_from_source(path: str, min_confidence: float) -> "dict":
         die(f"--snap-source {path}: this JSON has no beat_grid -- produce one with "
             "`scenes.py MUSIC --beats --json`", kind="input")
     samples = decode_pcm_mono(path, BEAT_RATE, check=False)
-    env = rms_envelope(samples, max(1, int(round(BEAT_RATE * 0.01))))
-    return beat_grid(env, 0.01, min_confidence=min_confidence)
+    block = max(1, int(round(BEAT_RATE * 0.01)))
+    env = rms_envelope(samples, block)
+    # the envelope's real step is block / rate (220 / 22050 = 9.977 ms), not the 10 ms asked for:
+    # timing the onsets at 10 ms stretched the grid 0.23 % (68 ms over 30 s) -- see scenes.py
+    return beat_grid(env, block / BEAT_RATE, min_confidence=min_confidence)
 
 
 def snap_segments(args, segments, meta, total):

package/scripts/scenes.py

@@ -31,6 +31,7 @@ from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
 from _common.emit import note, record_fallback  # noqa: E402
 from _common.color import bt709_label_filter  # noqa: E402
 from _common.probe import square_pixels  # noqa: E402
+from _common import dry_run_input_pending  # noqa: E402
 
 SHOT_FPS = 4.0          # frames/second sampled for --shots' flow estimate
 SHOT_W, SHOT_H = 48, 27  # decode size for --shots (16:9-ish; enough blocks, still a few KB/shot)
@@ -148,8 +149,25 @@ def main() -> int:
         guard_sidecar(args.edl, args.input, siblings=(args.sheet,))
 
     meta = probe(args.input)
-    if not meta.get("video"):
-        die("input has no video stream")
+    # Under --dry-run in a render.py/batch.py plan the input may be an earlier stage's output that
+    # was never written: every measurement is skipped (diagnostics.skipped measurement_input_pending)
+    # and the document keeps its shape with nothing measured, as loudness.py/cut.py do -- not an
+    # ffmpeg failure that stops the plan from being written.
+    pending = dry_run_input_pending(args.input)
+    # An audio-only file (WAV/FLAC/MP3 ...) is measured too (after 3.2.0): the beat grid, the loudness
+    # peaks and the speech ratio are measurements of the sound, and a music bed is usually
+    # delivered without a picture. It has no picture to cut, so it is one scene from 0 to its
+    # duration -- the same answer a video with no cut in it gets -- and the result says
+    # audio_only: true. What needs a picture (--sheet, --shots) is refused, not skipped.
+    audio_only = not meta.get("video")
+    if audio_only:
+        if not meta.get("audio"):
+            die("input has no video or audio stream")
+        picture_flags = [f for f, on in (("--sheet", args.sheet), ("--shots", args.shots)) if on]
+        if picture_flags:
+            die(f"{' and '.join(picture_flags)} need{'s' if len(picture_flags) == 1 else ''} a video stream; "
+                "this file is audio-only (input has no video stream). --beats, --audio-peaks, --speech "
+                "and --highlights measure the sound alone.", kind="input")
     # Only parsed when it is going to be used: --beat-range is a --beats flag, and a run that
     # never asked for beats should not be able to die on one.
     beat_range = parse_beat_range(args.beat_range) if args.beats else (60.0, 200.0)
@@ -159,18 +177,22 @@ def main() -> int:
         if args.beat_step <= 0:
             die("--beat-step must be greater than 0", kind="input")
     dur = meta.get("duration") or 0.0
-    cuts = detect_scenes(args.input, args.threshold, args.min_scene, dur, args.ratio)
+    cuts = [0.0] if (audio_only or pending) else detect_scenes(args.input, args.threshold, args.min_scene, dur, args.ratio)
+    has_audio = bool(meta.get("audio")) and not pending
     bounds = cuts + [dur]
     step_s = 0.5
     # With --beats the file is decoded once, at the finer rate, and both envelopes come from that
     # one pass: the 0.5 s scene blocks are an exact multiple of the 10 ms onset blocks.
     beat_rate = 22050
     need_fine = args.beats or args.audio_peaks or args.speech
-    fine_samples = decode_pcm_mono(args.input, beat_rate, check=False) if (need_fine and meta.get("audio")) else None
+    # --beats decodes with check=True: a decode that fails is an ffmpeg failure, not an empty
+    # envelope reported as "no steady pulse in this audio" (the scene scoring alone tolerates it
+    # and runs on the picture)
+    fine_samples = decode_pcm_mono(args.input, beat_rate, check=bool(args.beats)) if (need_fine and has_audio) else None
     if fine_samples is not None:
         env = audio_envelope(args.input, step_s, rate=beat_rate, samples=fine_samples)
     else:
-        env = audio_envelope(args.input, step_s) if meta.get("audio") else []
+        env = audio_envelope(args.input, step_s) if has_audio else []
 
     scenes = []
     for i in range(len(bounds) - 1):
@@ -192,6 +214,8 @@ def main() -> int:
         peaks.sort(key=lambda p: p["time"])
 
     result: Dict = {"file": args.input, "duration": round(dur, 3), "scene_count": len(scenes), "scenes": scenes, "audio_peaks": peaks}
+    if audio_only:
+        result["audio_only"] = True
     info(f"{len(scenes)} scenes, {len(peaks)} audio peaks over {dur:.1f}s")
 
     if args.shots:
@@ -203,7 +227,7 @@ def main() -> int:
         info(f"--shots: {len(shots)} shots (" + ", ".join(f"{v} {k}" for k, v in sorted(counts.items())) + ")")
 
     if args.audio_peaks:
-        if not meta.get("audio"):
+        if not has_audio:
             result["audio_peaks_db"] = []
             info("--audio-peaks: no audio stream, nothing to measure")
         else:
@@ -212,7 +236,7 @@ def main() -> int:
             info(f"--audio-peaks: {len(result['audio_peaks_db'])} peaks")
 
     if args.speech:
-        if not meta.get("audio"):
+        if not has_audio:
             result["speech"] = []
             info("--speech: no audio stream, nothing to measure")
         else:
@@ -224,9 +248,15 @@ def main() -> int:
         # A beat grid is a measurement of the music's periodicity, not a statement about where a
         # cut belongs. scenes.py reports what it measured, including a low confidence: reporting a
         # weak measurement is honest, and only a tool that CHANGES a file refuses to act on one.
-        fine = rms_envelope(fine_samples or [], max(1, int(round(beat_rate * args.beat_step))))
-        grid = beat_grid(fine, args.beat_step, bpm_range=beat_range,
-                         min_confidence=args.min_confidence, duration=dur)
+        # The envelope's real step is a whole number of samples: 220 / 22050 = 9.977 ms for the
+        # default 10 ms. Timing the onsets as if it were 10 ms stretched every measured time by
+        # 0.23 % -- 68 ms by the end of a 30 s track, the "40-60 ms off" a click track showed --
+        # so the grid is timed (and step_s reported) at the step the envelope actually has.
+        beat_block = max(1, round(beat_rate * args.beat_step))
+        fine = rms_envelope(fine_samples or [], beat_block)
+        grid = beat_grid(fine, beat_block / beat_rate, bpm_range=beat_range,
+                         min_confidence=args.min_confidence, duration=dur,
+                         pcm=fine_samples, pcm_rate=beat_rate)
         result["beats"] = grid["beats"]
         result["beat_grid"] = {
             # The regular grid AND the subset a measured onset supports. A tool that MOVES
@@ -238,8 +268,13 @@ def main() -> int:
             "onsets": len(grid["onsets"]), "supported": grid["supported"],
             "unsupported": grid["unsupported"], "method": grid["method"],
             "step_s": grid["step_s"], "range_bpm": grid["range_bpm"], "usable": grid["usable"],
+            # after 3.2.0, additive: how each onset was timed below the envelope step
+            # ("pcm-window-ratio": placed on the decoded samples; null: at the step)
+            "onset_refinement": grid["onset_refinement"],
         }
-        if grid["tempo_bpm"] is None:
+        if pending:
+            info("--beats: [dry-run] the input does not exist yet, nothing measured")
+        elif grid["tempo_bpm"] is None:
             info(f"--beats: no steady pulse in this audio (confidence {grid['confidence']:.2f}) -- "
                  "speech, ambience or rubato has no tempo to measure")
         else: