ffmpeg-skill 3.6.7 → 3.7.0

package/README.md

@@ -250,7 +250,7 @@ These are the rules the skill file gives the agent and the code enforces.
 
 | Tool | What it does |
 |---|---|
-| `audio.py` | Voice clean-up chain at three strengths (`--voice light\|medium\|strong`), FFT denoise, typed compressor / limiter / gate, music bed with sidechain ducking (`--duck-amount/-threshold/-attack/-release`), a never-ducked effects bed (`--effects`), `--stereo-widen`, fades, 5.1 → stereo, track replacement, extraction (`-o out.wav`), `--audio-stream N` |
+| `audio.py` | Voice clean-up chain at three strengths (`--voice light\|medium\|strong`), FFT denoise, typed compressor / limiter / gate, music bed with sidechain ducking (`--duck-amount/-threshold/-attack/-release`), a never-ducked effects bed (`--effects`), `--stereo-widen`, fades, 5.1 → stereo, track replacement, extraction (`-o out.wav`), `--audio-stream N`, a tempo change that keeps the pitch (`--tempo`, atempo stages in 0.5–2.0) and an exact length in samples (`--length-samples`), resampling (`--sample-rate`) and one channel by index (`--channel N`), each read back from the output |
 | `sync.py` | Offset between two recordings by audio cross-correlation (1 ms, pure Python), clock-drift correction; aligned video or audio out (audio-to-audio only — no lip-sync/face detection); a third or later camera is an additional `more_sources` positional (`sync.py REF A B ...`), the `second` positional itself keeps its name |
 | `loudness.py` | Two-pass EBU R128 `loudnorm` to −14 LUFS / −1 dBTP or any target (`--lra` for the range), video stream-copied; the written file is measured again and re-encoded until it meets `--tp` (lossy encoders overshoot); `--measure-only`; `--versions streaming,ebu-r128,broadcast-jp` (or `LUFS/TP` pairs) writes one file per target from one master, each measured after and listed in `versions` (`output` is null), `verified` only when every version met its own target |
 

package/SKILL.md

@@ -146,6 +146,8 @@ Variants, caveats and extra flags per row: `references/requests.md`.
 | "wider stereo" | `audio.py band.wav --stereo-widen 0.5` |
 | "swap in the narration track" | `audio.py in.mp4 --replace narration.wav` |
 | "give me the sound as WAV" | `audio.py in.mp4 -o in.wav` |
+| "speed the line up, same pitch", "exactly 96000 samples long" | `audio.py line.wav --tempo 1.2 --length-samples 96000 -o fit.wav` |
+| "just the third mic", "resample to 48 kHz" | `audio.py room.wav --channel 2 --sample-rate 48000 -o mic3.wav` |
 | "compress the voice", "limit the peaks", "gate the noise" | `audio.py in.mp4 --compress` (or `--limit`, `--gate`) |
 | "audiogram", "turn this podcast into a video" | `render.py --template audiogram ep.m4a --image cover.png` |
 | "make this a Reel / TikTok / Short / YouTube" | `render.py --template reels in.mp4 --cues cues.txt` |

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.6.7`) | any release |
+| `skill.version` | the npm / package.json version (`3.7.0`) | 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.6.7", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.7.0", "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"},
@@ -675,7 +675,18 @@ Per-tool keys added in 1.13: `audio` (`audio.py`) reports the mix it built — t
 `--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
-given. `loudness.py` reports `measured` (the input's loudnorm measurement,
+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
+`--length-samples` a `length_samples` verification step decodes the written track and counts its
+samples (`expected`, `measured`, `tolerance_samples`: 0 for PCM/FLAC/ALAC, one codec frame for a
+lossy codec; `reason: not_measured` and `ok: false` when the count cannot be read).
+Since #487 `audio.py --sample-rate HZ` resamples the output and `--channel N` keeps one channel by
+index (0-based); the `audio` block reports `channel` and `sample_rate` (`null` when not asked), and
+each is read back from the output by probe as a verification step, `sample_rate` and `channels`
+(`{expected, measured}`; 1 channel, or 2 with `--stereo`; `reason: not_measured` when probe cannot
+read it).
+`loudness.py` reports `measured` (the input's loudnorm measurement,
 including `input_lra`) and `targets` (the requested lufs / tp / lra).
 `check.py --platform podcast` adds two informational rows to `checks`,
 `channels` and `chapters`.
@@ -910,6 +921,7 @@ here claims otherwise until real exit-code/stderr sniffing exists to back that u
 A refusal also carries `error.reason`, a stable snake_case code for *why*
 (`contract --json` → `json_output.error_reasons` lists them: `output_exists`, `output_is_input`,
 `output_is_directory`, `output_dir_missing`, `output_dir_not_writable`, `output_locked`,
+`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`,
 `render.py`'s `plan_*` reasons, `--codec av1`/`prores`'s `encoder_missing` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.6.7",
+  "version": "3.7.0",
   "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

@@ -2029,7 +2029,8 @@ it) or the copy fails, the video is re-encoded with the tags on its frames
 `verification`'s `color_tags` step. Tags that are still wrong after the
 re-encode fail the run with `kind: verification`. The re-encode is H.264
 unless `--codec` says otherwise, so an output container that cannot hold it
-(`.webm`) fails with `kind: ffmpeg` instead of completing with the old tags.
+(`.webm`) is refused before it runs (`kind: input`, reason `output_container_codecs`) instead of
+completing with the old tags.
 
 ### audio.py — clean-up, music, ducking, layout
 ```
@@ -2037,7 +2038,8 @@ audio.py INPUT [--voice [light|medium|strong] | --denoise [--denoise-strength 25
          [--music FILE [--music-volume -14] [--duck [--duck-amount 12] [--duck-threshold -26.02]
           [--duck-attack 20] [--duck-release 400]] [--music-loop]]
          [--effects FILE [--effects-volume -14]] [--stereo-widen 0..1]
-         [--fade-in S] [--fade-out S] [--stereo | --mono | --downmix] [--replace FILE] [-o OUT]
+         [--fade-in S] [--fade-out S] [--stereo | --mono | --downmix] [--replace FILE]
+         [--tempo FACTOR] [--length-samples N] [--channel N] [--sample-rate HZ] [-o OUT]
 ```
 `--denoise` is `afftdn=nf=-N:tn=1`, where N is `--denoise-strength`, the noise
 floor in dB below full scale (20..60, default 25). It is the starting floor that
@@ -2051,7 +2053,7 @@ produced. The exact filter chains:
 | --- | --- |
 | `light` | `highpass=f=80,acompressor=threshold=-18dB:ratio=2:attack=5:release=80:makeup=1` |
 | `medium` | `highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2` |
-| `strong` | the `medium` chain, then `deesser=i=0.6,acompressor=threshold=-24dB:ratio=4:attack=5:release=120:makeup=3,alimiter=limit=0.891251:level=disabled` |
+| `strong` | the `medium` chain, then `deesser=i=0.6,acompressor=threshold=-24dB:ratio=4:attack=5:release=120:makeup=3,alimiter=limit=0.891251:level=disabled:latency=1` |
 
 `light` for a good room (rumble and level only, noise floor and sibilance left
 alone), `medium` for a normal talking head, `strong` for phone/laptop audio.
@@ -2088,6 +2090,29 @@ alone comes out 7.7 dB lower than it went in (9.9 dB on 7.1; follow with `loudne
 leaves a 1-channel input untouched and downmixes >2 channels through
 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).
+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
+keeps its start and still ends with the picture (a trim on the timestamp follows the count).
+A fade-out ends where the output ends, which is `--length-samples` when that is given.
+`--tempo FACTOR` (0.1..10) changes the main track's tempo and keeps its pitch: `atempo` stages of
+0.5..2.0 whose product is the factor (3 is `atempo=2,atempo=1.5`, 0.3 is `atempo=0.5,atempo=0.6`).
+atempo's own output length is close to, not exactly, the input's divided by the factor, so
+`--length-samples N` pads with silence or trims the output to exactly N samples per channel at the
+track's rate; the result's `length_samples` verification step decodes the written track and counts
+them (exact for PCM/FLAC/ALAC, within one codec frame for a lossy codec). Both need an audio output,
+or for `--tempo` a `--replace` track beside the picture: the input's own sound beside its
+stream-copied picture would drift from it (`fit.py --method speed` retimes both). `timing` reports
+`{tempo, atempo, length_samples, sample_rate}`.
+`--channel N` keeps channel N of the track (0-based, `pan=mono|c0=cN`, first in the chain) as a
+1-channel output, or both sides of a stereo one with `--stereo`; an index past the track's channels
+and `--downmix` are refused. `--sample-rate HZ` (1000..768000) resamples the output (`aresample`,
+after the mix and the fades; `--length-samples` counts in this rate). Each is read back from the
+output by probe as a verification step, `channels` and `sample_rate` (`expected`, `measured`), and
+the `audio` block reports `channel` and `sample_rate`.
 Run `loudness.py` after this for final levels.
 
 ### loudness.py — EBU R128 normalisation

package/scripts/_common/alpha.py

@@ -25,6 +25,7 @@ import threading
 from typing import Any, Dict, List, Optional
 
 from _common import runner as _runner
+from _common.color import carried_tag
 from _common.runner import STATE, ffmpeg_encoders, require_tool, run
 
 # A pixel format that carries an alpha plane (yuva*, rgba, argb, gbrap, ya8/ya16, ...).
@@ -284,10 +285,12 @@ _TAG_KEYS = (("colorspace", "color_space", "-colorspace"), ("color_primaries", "
              ("color_trc", "color_transfer", "-color_trc"))
 
 
-def _source_tags(meta: Optional[Dict[str, Any]]) -> List[tuple]:
+def _source_tags(meta: Optional[Dict[str, Any]], dest: str = "option") -> List[tuple]:
+    """(setparams name, value, output option) per source tag that is passed on, the value spelled
+    for `dest` (carried_tag: an RGB source's `gbr` is left out, #454)."""
     v = (meta or {}).get("video") or {}
-    return [(param, v.get(key), flag) for param, key, flag in _TAG_KEYS
-            if v.get(key) and v.get(key) not in ("unknown", "reserved", "unspecified")]
+    tags = [(param, carried_tag(param, v.get(key), dest), flag) for param, key, flag in _TAG_KEYS]
+    return [t for t in tags if t[1]]
 
 
 def finish_chain(codec: str, mode: Optional[str], meta: Optional[Dict[str, Any]] = None) -> str:
@@ -295,7 +298,7 @@ def finish_chain(codec: str, mode: Optional[str], meta: Optional[Dict[str, Any]]
     when asked, the source's colour tags put back on the frames (`setparams`: a grade's RGB legs
     and an RGB layer's conversion relabel them, BT.601 or unknown), then the line's own pixel
     format (so no later conversion can drop the plane)."""
-    tags = _source_tags(meta)
+    tags = _source_tags(meta, "setparams")
     label = ("setparams=" + ":".join(f"{p}={val}" for p, val, _ in tags) + ",") if tags else ""
     # premultiplied colour is colour x alpha in RGB: multiplied there (a YUV premultiply scales the
     # limited-range offsets too), after the tags are back so both conversions use the same matrix

package/scripts/_common/color.py

@@ -57,6 +57,36 @@ NON_BT709_MATRICES = ("smpte170m", "bt470bg", "fcc", "smpte240m")
 _RGB_PIX_FMT_RE = re.compile(r"^(?:rgb|bgr|argb|abgr|0rgb|0bgr|gbr|x2rgb|x2bgr|pal8)")
 
 
+# A probed colour tag passed back to FFmpeg (#454). ffprobe prints av_color_*_name(), which is
+# also the setparams filter's table; the output options -colorspace/-color_primaries/-color_trc
+# parse an older one that differs on three names (6.1, measured): -colorspace refuses `gbr` (its
+# name is `rgb`) and -color_trc refuses `bt470m` and `bt470bg` (its names: `gamma22`, `gamma28`).
+# `gbr` is not carried over at all: it says the stored samples are RGB, which is the pixel
+# format's to say (the PNG encoder tags it itself), and a tool that converts the picture to YUV on
+# the way (a grade's legs, a 4:4:4 alpha line) would label YUV samples as RGB with it.
+_TAG_KIND = {"-colorspace": "colorspace", "-color_primaries": "color_primaries", "-color_trc": "color_trc"}
+_OPTION_NAMES = {"color_trc": {"bt470m": "gamma22", "bt470bg": "gamma28"}}
+
+
+def carried_tag(kind: str, name: Optional[str], dest: str = "option") -> Optional[str]:
+    """The probed tag `name` of `kind` (colorspace, color_primaries, color_trc) spelled the way
+    `dest` ("option": -colorspace & co; "setparams") accepts it, or None when it is not to be
+    passed on: unknown, unspecified, reserved, or the RGB `gbr`/`rgb`."""
+    if not name or name in ("unknown", "unspecified", "reserved") or (kind == "colorspace" and name in ("gbr", "rgb")):
+        return None
+    return _OPTION_NAMES.get(kind, {}).get(name, name) if dest == "option" else name
+
+
+def carried_tag_args(pairs: Sequence[Tuple[str, Optional[str]]]) -> List[str]:
+    """[flag, value, ...] for each (flag, probed name) whose tag carried_tag() passes on."""
+    out: List[str] = []
+    for flag, name in pairs:
+        value = carried_tag(_TAG_KIND.get(flag, flag.lstrip("-")), name)
+        if value:
+            out += [flag, value]
+    return out
+
+
 def rgb_to_bt709_filter(pix_fmt: str = "yuv444p") -> str:
     """An RGB picture converted to BT.709 limited-range YUV right here, in `pix_fmt`, so no later
     conversion (an auto-inserted one, with FFmpeg's BT.601 default) decides the matrix. 4:4:4 by

package/scripts/_common/runner.py

@@ -1004,6 +1004,76 @@ def _check_output_path(cmd: Sequence[str]) -> None:
         refuse("input", "output_dir_not_writable", f"output directory {parent!r} is not writable", output=output, directory=parent)
 
 
+# What the WebM muxer takes (6.1: "Only VP8 or VP9 or AV1 video and Vorbis or Opus audio and
+# WebVTT subtitles are supported for WebM"), by the encoder a command names (#488).
+_WEBM_VIDEO_ENCODER_RE = re.compile(r"^(?:libvpx(?:-vp9)?|vp8|vp9|libaom-av1|libsvtav1|librav1e|av1|vp8_\w+|vp9_\w+|av1_\w+)$")
+_WEBM_AUDIO_ENCODER_RE = re.compile(r"^(?:libopus|opus|libvorbis|vorbis)$")
+_CODEC_OPTION_RE = re.compile(r"^-(?:c|codec)(?::([va])(?::\d+)?)?$|^-(v|a)codec$")
+
+
+def _an_input_has(cmd: Sequence[str], kind: str) -> bool:
+    """False only when every input of `cmd` is a file that was read and holds no `kind` ("v"/"a")
+    stream, and no filter graph could make one. An encoder option for a stream the output will
+    not have selects nothing (FFmpeg applies -c:a after stream selection), so it is not a reason
+    to refuse: cut.py names -c:a aac for a silent source too. Anything not known counts as present."""
+    if any(tok in ("-filter_complex", "-lavfi", "-filter_complex_script") for tok in cmd):
+        return True
+    paths = [cmd[i + 1] for i, tok in enumerate(cmd[:-1]) if tok == "-i"]
+    if not paths:
+        return True
+    for i, tok in enumerate(cmd[:-1]):
+        if tok == "-f" and cmd[i + 1] in ("lavfi", "concat"):
+            return True
+    for path in paths:
+        if not os.path.isfile(path):
+            return True
+        probe_cmd = [shutil.which("ffprobe") or "ffprobe", "-v", "error", "-select_streams", kind,
+                     "-show_entries", "stream=index", "-of", "csv=p=0", path]
+        limit = _probe_limit()  # PROBE_TIMEOUT, or --timeout when that is lower; never unlimited (--timeout 0)
+        try:
+            proc = subprocess.run(probe_cmd, capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=limit)
+        except subprocess.TimeoutExpired:
+            # a stalled read is reported as what it is, not turned into "the stream is there"
+            die(f"ffprobe did not finish reading {path} within {limit:g} s and was killed; nothing was written",
+                code=124, kind="timeout", output=cmd[-1])
+        except OSError:
+            return True
+        if proc.returncode != 0 or proc.stdout.strip():
+            return True
+    return False
+
+
+def _check_container_codecs(cmd: Sequence[str]) -> None:
+    """A `.webm` output whose command encodes a picture or a sound WebM cannot hold (the tools'
+    H.264/HEVC and AAC lines) is refused before anything runs, dry runs included: the muxer
+    refused it only after the encode had started, as `kind: ffmpeg` with "Nothing was written
+    into output file", and a dry run said completed (#488). A stream copy is left to the muxer:
+    what it copies is not named in the command."""
+    output = cmd[-1]
+    if os.path.splitext(output)[1].lower() != ".webm":
+        return
+    refused: List[Any] = []
+    for i, tok in enumerate(cmd[:-2]):
+        m = _CODEC_OPTION_RE.match(tok)
+        if not m:
+            continue
+        stream, value = m.group(1) or m.group(2), cmd[i + 1]
+        if value == "copy" or stream is None:
+            continue
+        allowed = _WEBM_VIDEO_ENCODER_RE if stream == "v" else _WEBM_AUDIO_ENCODER_RE
+        if not allowed.match(value):
+            refused.append((stream, value))
+    # only for a stream the output will have: asked last, and only when something would be refused
+    refused = [value for stream, value in dict.fromkeys(refused) if _an_input_has(cmd, stream)]
+    if refused:
+        refuse("input", "output_container_codecs",
+               f"output {output!r} is WebM, which holds only VP8/VP9/AV1 video and Opus/Vorbis sound; this tool "
+               f"encodes {' and '.join(refused)} for it",
+               hint="name a .mp4, .mov or .mkv output (Matroska holds what WebM refuses); "
+                    "a transparent VP9 WebM is --keep-alpha --alpha-codec vp9 or export.py --preset vp9-alpha",
+               output=output, container="webm", encoders=refused)
+
+
 EVEN_SCALE = "scale=trunc(iw/2)*2:trunc(ih/2)*2"
 
 
@@ -1797,6 +1867,7 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
         _refuse_url_media(cmd)
         _check_no_overwrite_input(cmd)
         _check_output_path(cmd)
+        _check_container_codecs(cmd)
         _check_existing_output(cmd)
         ctx.commands.append(_cmdline(cmd))
     if not quiet:

package/scripts/_contract.py

@@ -171,6 +171,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                                         {"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"},
+                                        {"capability": "filter:atempo", "when": "--tempo"},
                                         {"capability": AAC, "when": "output extension isn't .mp3/.opus/.ogg/.flac (audio_codec_for()'s default)"}] + AUDIO_OUT,
                   video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "loudness": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["loudness measurement JSON (--measure-only)", "normalised artifact (video stream-copied)"],
@@ -438,6 +439,7 @@ ERROR_REASONS = {
     "media_path_is_url": "an input or output has a protocol prefix (tcp:, http://, file:, ...) that ffmpeg would open as a URL; the skill reads and writes local files only; details: {path, scheme}",
     "output_dir_missing": "the output's directory does not exist; details: {output, directory}",
     "output_dir_not_writable": "the output's directory is not writable; details: {output, directory}",
+    "output_container_codecs": "a .webm output whose command encodes video or sound WebM cannot hold (H.264/HEVC, AAC; WebM takes VP8/VP9/AV1 and Opus/Vorbis), refused before ffmpeg runs; details: {output, container, encoders}",
     "timemap_path_taken": "silence.py --timemap names the same file as -o, --edl or --plan; details: {timemap, flag, path}",
     "output_locked": "another run holds the output's lock; details: {lock, output, pid, pid_alive, deadline, why}",
     "plan_inputs_changed": "render.py PLAN: a fingerprinted input is missing or changed; details: {plan, plan_sha256, checked_at, "
@@ -797,7 +799,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "dynamics": {"type": "array", "items": {"enum": ["agate", "acompressor", "alimiter"]}, "description": "typed dynamics filters applied, in graph order"},
                  "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"},
-                 "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, 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)"}}
+                 "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)"}}
     if name in ("overlay", "graphics", "caption", "grid"):
         extra["font_used"] = FONT_USED_SCHEMA
     if name in ALPHA_LINE_TOOLS:

package/scripts/_smartcut.py

@@ -34,6 +34,7 @@ from fractions import Fraction
 from typing import Any, Dict, List, Optional, Tuple
 
 from _common import STATE, aac_args, concat_list_line, ffmpeg_base, require_tool, run
+from _common.color import carried_tag_args
 from _common.runner import fail_if_classified
 
 # the stream parameters a re-encoded part must share with the source (ffprobe -show_streams)
@@ -129,11 +130,12 @@ def x264_line(params: Dict[str, Any], crf: int, preset: str) -> List[str]:
             "-x264-params", f"{b}:open-gop=0"]
     if level:
         args += ["-level:v", f"{level // 10}.{level % 10}"]
-    for flag, field in (("-colorspace", "color_space"), ("-color_primaries", "color_primaries"),
-                        ("-color_trc", "color_transfer"), ("-color_range", "color_range")):
-        value = params.get(field)
-        if value and value != "unknown":
-            args += [flag, str(value)]
+    # spelled the way the output options take them (#454: ffprobe's bt470m/bt470bg transfer and
+    # gbr space are not their names)
+    args += carried_tag_args([("-colorspace", params.get("color_space")), ("-color_primaries", params.get("color_primaries")),
+                              ("-color_trc", params.get("color_transfer"))])
+    if params.get("color_range") and params.get("color_range") != "unknown":
+        args += ["-color_range", str(params["color_range"])]
     return args
 
 

package/scripts/audio.py

@@ -18,6 +18,8 @@ Examples:
   python3 audio.py interview.mp4 -o interview.wav               # extract the audio (no video in the output)
   python3 audio.py multi.mkv --audio-stream 1 --voice -o lav.m4a # pick the second audio track, clean it, write M4A
   python3 audio.py talk.wav --compress --comp-threshold -20 --comp-ratio 4 --limit --limit-ceiling -1 -o talk_dyn.wav
+  python3 audio.py line.wav --tempo 1.25 --length-samples 96000 -o line_fit.wav   # faster, same pitch, exactly 2 s at 48 kHz
+  python3 audio.py room.wav --channel 2 --sample-rate 48000 -o mic3.wav   # the third microphone alone, resampled to 48 kHz
 """
 import argparse
 import os
@@ -42,7 +44,7 @@ VOICE_CHAIN = "highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=thresh
 VOICE_LEVELS = {
     "light": "highpass=f=80,acompressor=threshold=-18dB:ratio=2:attack=5:release=80:makeup=1",
     "medium": VOICE_CHAIN,
-    "strong": VOICE_CHAIN + ",deesser=i=0.6,acompressor=threshold=-24dB:ratio=4:attack=5:release=120:makeup=3,alimiter=limit=0.891251:level=disabled",
+    "strong": VOICE_CHAIN + ",deesser=i=0.6,acompressor=threshold=-24dB:ratio=4:attack=5:release=120:makeup=3,alimiter=limit=0.891251:level=disabled:latency=1",
 }
 
 # The sidechain threshold the music bed has used since 1.4 is the linear 0.05 that ffmpeg's
@@ -95,6 +97,9 @@ def dynamics_filter(name: str, args: argparse.Namespace) -> str:
             opts.append(f"{opt}={value:g}")
     if name == "alimiter":
         opts.append("level=disabled")  # keep the level: a limiter must not normalise the whole track upwards
+        # latency compensation: without it the output is the input delayed by the look-ahead
+        # (--limit-attack, 5 ms by default: 240 samples at 48 kHz) and drifts off the picture (#476)
+        opts.append("latency=1")
     return name + ("=" + ":".join(opts) if opts else "")
 
 
@@ -173,6 +178,90 @@ def main_track_channels(args: argparse.Namespace, meta: Dict[str, Any]) -> int:
     return (meta.get("audio") or {}).get("channels") or 0
 
 
+def main_track_rate(args: argparse.Namespace, meta: Dict[str, Any]) -> int:
+    """Sample rate of the track audio.py processes (as main_track_channels() picks it); 0 when it
+    is not known (a dry run's pending input)."""
+    if args.replace:
+        if dry_run_input_pending(args.replace) or not os.path.isfile(args.replace):
+            return 0
+        proc = run([require_tool("ffprobe"), "-v", "error", "-select_streams", "a:0", "-show_entries",
+                    "stream=sample_rate", "-of", "csv=p=0", args.replace], quiet=True, check=False)
+        first = (proc.stdout or "").strip().splitlines()[:1]
+        return int(first[0]) if first and first[0].strip().isdigit() else 0
+    streams = meta.get("audio_streams") or []
+    track = streams[args.audio_stream] if 0 <= args.audio_stream < len(streams) else (meta.get("audio") or {})
+    try:
+        return int(track.get("sample_rate") or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+# --tempo: atempo keeps the pitch; one stage is kept within 0.5..2.0 (above 2 it drops whole
+# blocks of samples), so a factor outside that range is a chain of stages whose product is it (#486)
+TEMPO_RANGE = (0.1, 10.0)
+LOSSLESS_AUDIO = ("pcm_", "flac", "alac", "wavpack", "tta")
+# samples per frame of the lossy encoders audio_codec_for() picks: a decoded length can differ from
+# the samples written by the encoder's own padding, by at most one frame
+CODEC_FRAME_SAMPLES = {"aac": 1024, "mp3": 1152, "opus": 960, "vorbis": 2048, "ac3": 1536, "eac3": 1536}
+
+
+def atempo_steps(factor: float) -> List[float]:
+    """atempo stages, each in 0.5..2.0, whose product is `factor`."""
+    steps: List[float] = []
+    while factor > 2.0:
+        steps.append(2.0)
+        factor /= 2.0
+    while factor < 0.5:
+        steps.append(0.5)
+        factor /= 0.5
+    return steps + [factor]
+
+
+def decoded_samples(path: str) -> "int | None":
+    """Samples per channel of the first audio track, counted by decoding it (astats); None when
+    the count could not be read."""
+    proc = run([require_tool("ffmpeg"), "-hide_banner", "-nostats", "-i", path, "-map", "0:a:0", "-af",
+                "astats=measure_perchannel=none:measure_overall=Number_of_samples", "-f", "null", "-"],
+               quiet=True, check=False)
+    found = [line.rsplit(":", 1)[-1].strip() for line in (proc.stderr or "").splitlines() if "Number of samples:" in line]
+    return int(found[-1]) if proc.returncode == 0 and found and found[-1].isdigit() else None
+
+
+def length_step(path: str, codec: str, expected: int) -> Dict[str, Any]:
+    """The `length_samples` verification step: the written track's decoded length against
+    --length-samples, exact for a lossless codec, within one codec frame for a lossy one."""
+    measured = decoded_samples(path)
+    lossless = codec.startswith(LOSSLESS_AUDIO)
+    tolerance = 0 if lossless else CODEC_FRAME_SAMPLES.get(codec, 2048)
+    step: Dict[str, Any] = {"step": "length_samples", "expected": expected, "measured": measured,
+                            "tolerance_samples": tolerance, "codec": codec}
+    if measured is None:
+        return dict(step, ok=False, reason="not_measured")
+    return dict(step, ok=abs(measured - expected) <= tolerance)
+
+
+SAMPLE_RATE_RANGE = (1000, 768000)
+OPUS_DECODED_RATE = 48000  # what an Opus stream decodes at, whatever rate was encoded (measured: 16 kHz in, 48 kHz out)
+
+
+def property_step(name: str, expected: int, measured: Any) -> Dict[str, Any]:
+    """A verification step comparing one probed property of the written track with the request
+    (#487: `sample_rate`, `channels`); `reason: not_measured` when probe could not read it."""
+    try:
+        value = int(measured)
+    except (TypeError, ValueError):
+        return {"step": name, "expected": expected, "measured": None, "ok": False, "reason": "not_measured"}
+    return {"step": name, "expected": expected, "measured": value, "ok": value == expected}
+
+
+def conform_filter(samples: int, rate: int) -> str:
+    """Pad with silence or trim to exactly `samples` at `rate` (#478): counted in samples, not in
+    seconds written to the millisecond, which left a result up to 24 samples (48 kHz) off. The
+    aformat pins the rate the count is in, so a resampler FFmpeg inserts sits ahead of the count."""
+    head = f"aformat=sample_rates={rate}," if rate else ""
+    return f"{head}apad=whole_len={samples},atrim=end_sample={samples}"
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -209,8 +298,21 @@ def main() -> int:
                        help="widen the stereo image, 0..1 (0 = untouched, 1 = maximum); needs a real stereo source: a mono input is "
                             "refused (duplicating it leaves both channels identical, so there is nothing to widen) and more than two "
                             "channels are refused unless --downmix folds them to stereo first")
+    fades.add_argument("--channel", type=int, default=None, metavar="N",
+                       help="keep only channel N of the track (0-based, in the track's own order), as a 1-channel output "
+                            "(--stereo duplicates it to both sides); checked on the output by probe")
+    fades.add_argument("--sample-rate", type=int, default=None, metavar="HZ",
+                       help="resample the output to HZ (aresample); checked on the output by probe. Default: the track's own rate")
     fades.add_argument("--downmix", action="store_true", help="downmix 5.1/7.1 to stereo with the ITU-R BS.775 weights (centre and surrounds -3 dB, LFE dropped), scaled so the fold-down cannot clip")
     fades.add_argument("--replace", help="replace the audio with this file (trimmed/padded to the video)")
+    timing = ap.add_argument_group("timing (an audio output, or --replace beside a kept picture)")
+    timing.add_argument("--tempo", type=float, default=None, metavar="FACTOR",
+                        help="change the tempo of the main track keeping its pitch (atempo; 2 = twice as fast, half as long), "
+                             f"{TEMPO_RANGE[0]:g}..{TEMPO_RANGE[1]:g}; outside 0.5..2.0 it is a chain of atempo stages. "
+                             "Refused on the input's own sound while its picture is stream-copied (use fit.py --method speed)")
+    timing.add_argument("--length-samples", type=int, default=None, metavar="N",
+                        help="pad with silence or trim the output to exactly N samples per channel at the output rate "
+                             "(an audio output only: beside a picture the sound is conformed to the picture)")
     dyn = ap.add_argument_group("dynamics (typed; each flag is one option of ffmpeg's acompressor / alimiter / agate)")
     dyn.add_argument("--compress", action="store_true", help="compressor (acompressor); order: gate -> compressor -> limiter")
     dyn.add_argument("--comp-threshold", type=float, help="dBFS above which gain is reduced, -60..0 (ffmpeg default -12.4)")
@@ -299,6 +401,31 @@ def main() -> int:
     # or --replace's first track. meta["audio"] is the input's first track, so a mono a:0 left a
     # stereo --audio-stream 1 unfolded by --mono, and a stereo a:0 halved a mono one (A128)
     in_channels = main_track_channels(args, meta)
+    keep_video = has_video and not audio_out
+    if args.tempo is not None:
+        if not (TEMPO_RANGE[0] <= args.tempo <= TEMPO_RANGE[1]):
+            die(f"--tempo must be {TEMPO_RANGE[0]:g}..{TEMPO_RANGE[1]:g}, got {args.tempo:g}")
+        if keep_video and not args.replace:
+            die("--tempo changes the length of the input's own sound, and its picture is stream-copied, so the two "
+                "would drift apart; write an audio output (-o NAME.wav), or retime both with fit.py --method speed",
+                kind="input")
+    if args.length_samples is not None:
+        if args.length_samples < 1:
+            die(f"--length-samples must be a positive number of samples, got {args.length_samples}")
+        if keep_video:
+            die("--length-samples needs an audio output: beside a stream-copied picture the sound is conformed to "
+                "the picture's length; write -o NAME.wav (or .flac, .m4a, ...)", kind="input")
+    if args.sample_rate is not None and not (SAMPLE_RATE_RANGE[0] <= args.sample_rate <= SAMPLE_RATE_RANGE[1]):
+        die(f"--sample-rate must be {SAMPLE_RATE_RANGE[0]}..{SAMPLE_RATE_RANGE[1]} Hz, got {args.sample_rate}")
+    if args.channel is not None:
+        if args.channel < 0:
+            die(f"--channel is a 0-based channel index, got {args.channel}")
+        if args.downmix:
+            die("--channel and --downmix contradict each other: --channel keeps one channel, --downmix folds them all to stereo")
+        if in_channels and args.channel >= in_channels:
+            die(f"--channel {args.channel}: the track has {in_channels} channel(s), 0..{in_channels - 1}",
+                kind="input", channels=in_channels)
+        in_channels = 1  # what every later stage sees: the one channel kept
     if args.stereo_widen is not None:
         if args.mono:
             die("--stereo-widen and --mono contradict each other: there is no stereo image in a 1-channel output")
@@ -321,6 +448,9 @@ def main() -> int:
         idx += 1
 
     fx: List[str] = []
+    if args.channel is not None:
+        # #487: one channel by index, first, so every later stage works on it alone
+        fx.append(f"pan=mono|c0=c{args.channel}")
     if args.downmix:
         # ITU-R BS.775: centre and surrounds at -3 dB (0.707), LFE dropped. pan's '<' scales each
         # output so its gains sum to 1 over the channels the input has (1/2.414 on 5.1, 1/3.121 on
@@ -357,6 +487,22 @@ def main() -> int:
         # as it goes before the centre collapses. It runs after the channel layout is settled, so
         # a --downmix 5.1 source is widened on the stereo fold-down rather than on six channels.
         fx.append(f"extrastereo=m={1 + 2 * args.stereo_widen:g}")
+    tempo_steps = atempo_steps(args.tempo) if args.tempo is not None and args.tempo != 1.0 else []
+    if tempo_steps:
+        fx.append(",".join(f"atempo={f:.10g}" for f in tempo_steps))
+    # the main track's length in the output: the source's, or the source's / --tempo on an audio
+    # output of the input's own sound (beside a picture, or for --replace, it is the picture's)
+    main_dur = dur / args.tempo if dur and tempo_steps and not (keep_video or args.replace) else dur
+    rate = args.sample_rate or main_track_rate(args, meta)
+    # where the output ends, which is where a fade-out has to end: --length-samples when it is
+    # given (a fade timed on the source's length sat past the trim and was never heard)
+    end_dur = args.length_samples / rate if args.length_samples is not None and rate else main_dur
+    if args.length_samples is not None and rate and rate != OPUS_DECODED_RATE and "libopus" in audio_codec_for(output, args.bitrate):
+        # An Opus stream decodes at 48 kHz whatever rate went in (a 16 kHz track too), so the
+        # decoded track has N * 48000 / rate samples and the count asked for is not the file's
+        die(f"--length-samples counts at {rate} Hz, and an Opus output decodes at {OPUS_DECODED_RATE} Hz: "
+            f"the file would not hold {args.length_samples} samples",
+            kind="input", hint="add --sample-rate 48000 and give the length in 48 kHz samples, or write .wav/.flac")
 
     graph: List[str] = []
     graph.append(f"[{main_src}]{','.join(fx) if fx else 'anull'}[main]")
@@ -369,9 +515,9 @@ def main() -> int:
             inputs += ["-i", args.music]
         m = f"{idx}:a:0"
         idx += 1
-        mfx = [f"volume={args.music_volume:g}dB", f"atrim=0:{dur:.3f}" if dur else "anull"]
-        if args.music_fade_out and dur:
-            mfx.append(f"afade=t=out:st={max(0.0, dur - args.music_fade_out):.3f}:d={args.music_fade_out:g}")
+        mfx = [f"volume={args.music_volume:g}dB", f"atrim=0:{main_dur:.6f}" if main_dur else "anull"]
+        if args.music_fade_out and end_dur:
+            mfx.append(f"afade=t=out:st={max(0.0, end_dur - args.music_fade_out):.3f}:d={args.music_fade_out:g}")
         graph.append(f"[{m}]{','.join(mfx)}[music]")
         if args.duck:
             graph.append("[main]asplit=2[mainA][sc]")
@@ -390,7 +536,7 @@ def main() -> int:
         inputs += ["-i", args.effects]
         e = f"{idx}:a:0"
         idx += 1
-        efx = [f"volume={args.effects_volume:g}dB", f"atrim=0:{dur:.3f}" if dur else "anull"]
+        efx = [f"volume={args.effects_volume:g}dB", f"atrim=0:{main_dur:.6f}" if main_dur else "anull"]
         graph.append(f"[{e}]{','.join(efx)}[effects]")
         graph.append(f"[{last}][effects]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mixfx]")
         last = "mixfx"
@@ -398,17 +544,35 @@ def main() -> int:
     post: List[str] = []
     if args.fade_in:
         post.append(f"afade=t=in:st=0:d={args.fade_in:g}")
-    if args.fade_out and dur:
-        post.append(f"afade=t=out:st={max(0.0, dur - args.fade_out):.3f}:d={args.fade_out:g}")
+    if args.fade_out and end_dur:
+        post.append(f"afade=t=out:st={max(0.0, end_dur - args.fade_out):.3f}:d={args.fade_out:g}")
     # The audio track is conformed to the source duration whenever it is known: padded with
     # silence if the graph came out short, trimmed if long. A mixed track can come out a few
     # hundredths short (amix's dropout_transition, a looped bed's atrim boundary), and with
     # -shortest below that used to shorten the *video* to match: 12.00 s in, 11.925 s out, four
     # frames of a stream-copied picture gone (#164). Padding the audio, not cutting the picture,
     # is the only correct answer for a tool whose contract says the video is never touched.
-    keep_video = has_video and not audio_out
-    if dur and (args.replace or args.music or keep_video):
-        post.append(f"apad,atrim=0:{dur:.3f}")
+    if args.sample_rate:
+        # #487: resampled after the mix and the fades, ahead of the sample count, which is in this rate
+        post.append(f"aresample={args.sample_rate}")
+    conform_samples = None
+    if args.length_samples is not None:
+        # #486: an exact length asked for, counted at the track's rate (unknown only for a dry
+        # run's pending input, whose real run pins it)
+        conform_samples = args.length_samples
+        post.append(conform_filter(conform_samples, rate))
+    elif main_dur and (args.replace or args.music or keep_video):
+        if rate:
+            conform_samples = round(main_dur * rate)
+            # The count is of samples, and sound that starts after the picture keeps its start
+            # (apad and atrim=end_sample do not move timestamps): N samples from 0.3 s end 0.3 s
+            # past the picture. The trim on the timestamp, which is what this was before #478,
+            # ends it with the picture; half a sample of slack keeps the Nth sample of a track
+            # that starts at 0.
+            post.append(conform_filter(conform_samples, rate) + f",atrim=end={main_dur + 0.5 / rate:.6f}")
+        else:
+            # a dry run's pending input: no rate to count in yet; the real run counts samples
+            post.append(f"apad,atrim=0:{main_dur:.6f}")
     if post:
         graph.append(f"[{last}]{','.join(post)}[out]")
         last = "out"
@@ -444,7 +608,18 @@ def main() -> int:
                                 "ratio": round(max(2.0, args.duck_amount / 3), 1),
                                 "attack_ms": args.duck_attack, "release_ms": args.duck_release}
                                if args.duck else None)
-    emit(output, audio=audio_block, video=bool(has_video and not audio_out), audio_stream=args.audio_stream,
+    verification: List[Dict[str, Any]] = []
+    if args.length_samples is not None and not STATE.dry_run:
+        verification.append(length_step(output, str(a.get("codec") or ""), args.length_samples))
+    if args.sample_rate is not None and not STATE.dry_run:
+        verification.append(property_step("sample_rate", args.sample_rate, a.get("sample_rate")))
+    if args.channel is not None and not STATE.dry_run:
+        verification.append(property_step("channels", 2 if args.stereo else 1, a.get("channels")))
+    audio_block["channel"] = args.channel
+    audio_block["sample_rate"] = args.sample_rate
+    timing_block = {"tempo": args.tempo, "atempo": tempo_steps, "length_samples": args.length_samples,
+                    "sample_rate": rate or None}
+    emit(output, audio=audio_block, timing=timing_block, **({"verification": verification} if verification else {}), video=bool(has_video and not audio_out), audio_stream=args.audio_stream,
          dynamics=[f for f in (args.gate and "agate", args.compress and "acompressor", args.limit and "alimiter") if f],
          dropped_non_av_streams=dropped_streams,
          **({"silent": silent, "notes": notes} if silent else {}))