ffmpeg-skill 3.8.12 → 3.8.14

package/scripts/_common/probe.py

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

package/scripts/_common/runner.py

@@ -511,6 +511,11 @@ def apply_common(args: "argparse.Namespace") -> None:
     # --json-brief is a shorter --json, not a second output mode: it implies it, so a caller that
     # passes only --json-brief still gets a JSON document (and --json --json-brief is the brief one).
     STATE.json = bool(getattr(args, "json", False)) or STATE.json_brief
+    if hasattr(args, "json"):
+        # and a tool that branches on args.json reads the same mode: through 3.8.13, probe --field,
+        # check, cropdetect, silence --list, report and verify printed text (or a bare document,
+        # or a document and then a path) under --json-brief alone (review of #521)
+        args.json = STATE.json
     STATE.progress = bool(getattr(args, "progress", False))
     STATE.fast = bool(getattr(args, "fast", False))
     STATE.overwrite = bool(getattr(args, "overwrite", False))
@@ -991,7 +996,7 @@ def _refuse_output_is_input(output: str, inp: str, real: str, why: str) -> None:
            **details)
 
 
-def refuse_output_is_input(output: str, *inputs: str) -> None:
+def refuse_output_is_input(output: str, *inputs: str, why: str = "the result would replace the source") -> None:
     """Tool-level twin of the run() guard, for tools whose final ffmpeg command does not name
     the user's input at all. `cut.py --segments` cuts each part into a temp dir and then concats
     a list file: the last command's only `-i` is that list, so `-o` equal to the input sailed
@@ -1009,7 +1014,7 @@ def refuse_output_is_input(output: str, *inputs: str) -> None:
         except OSError:
             continue
         if same:
-            _refuse_output_is_input(output, inp, out_real, "the result would replace the source")
+            _refuse_output_is_input(output, inp, out_real, why)
 
 
 def _check_output_path(cmd: Sequence[str]) -> None:
@@ -1040,6 +1045,24 @@ 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)
 
 
+def _check_output_extension(cmd: Sequence[str]) -> None:
+    """An ffmpeg output with no file extension and no `-f` after its last input leaves the muxer
+    nothing to choose a container by: refused as `kind: input` before anything runs, dry runs
+    included. Through 3.8.8 every tool that writes media handed it on and failed as `kind: ffmpeg`
+    ("Unable to choose an output format", audit A159's sweep). Only the ffmpeg commands run()
+    executes are checked: a sidecar (a report, an SRT) is a plain file and needs no extension,
+    and look.py takes an -o without an image extension as a stem (docs/design-decisions.md)."""
+    output = cmd[-1]
+    if output == "-" or output.startswith("pipe:") or len(os.path.splitext(output)[1]) > 1:
+        return
+    last_input = max((i for i, tok in enumerate(cmd[:-1]) if tok == "-i"), default=-1)
+    if "-f" in cmd[last_input + 2:-1]:
+        return
+    refuse("input", "output_extension_missing",
+           f"output {output!r} has no file extension, so ffmpeg cannot tell which container to write; "
+           f"name it with one (for example {output + '.mp4'!r})", output=output)
+
+
 # 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+)$")
@@ -2017,6 +2040,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_output_extension(cmd)
         _check_container_codecs(cmd)
         _check_build_components(cmd)
         _check_existing_output(cmd)
@@ -2109,11 +2133,56 @@ def _set_refusal_note(ctx: "Context", reason: str, outcome: str) -> None:
     ctx.hw_notes.append(reason + outcome)
 
 
+# A filter graph longer than this is handed to ffmpeg in a file (A138). Linux refuses any single
+# argument over 128 KiB (MAX_ARG_STRLEN) and Windows a whole command line over 32767 characters, and
+# a graph grows with the items it is built from: scenes.py --sheet's select expression is ~56
+# characters a scene, so ~2,340 scenes raised OSError E2BIG before ffmpeg ran, with a traceback and
+# no JSON. A graph under the limit is passed as it always was.
+LONG_FILTER_CHARS = 8000 if os.name == "nt" else 100_000
+_FILTER_OPTION_RE = re.compile(r"^-(?:filter_complex|lavfi|vf|af|filter(?::[^\s]+)?)$")
+
+
+def _filter_file_option(option: str) -> str:
+    """The option that reads `option`'s value from a file: `-/OPTION` from FFmpeg 7.0, which
+    deprecated the `_script` spellings, and `-filter_complex_script` / `-filter_script[:spec]`
+    before it (6.x, the oldest CI runs)."""
+    complex_graph = option in ("-filter_complex", "-lavfi")
+    spec = {"-vf": ":v", "-af": ":a"}.get(option, option[len("-filter"):] if option.startswith("-filter:") else "")
+    if ffmpeg_version() >= (7, 0):
+        return "-/filter_complex" if complex_graph else "-/filter" + spec
+    return "-filter_complex_script" if complex_graph else "-filter_script" + spec
+
+
+@contextlib.contextmanager
+def long_filters_in_files(cmd: Sequence[str]) -> "Any":
+    """`cmd` with every filter graph longer than LONG_FILTER_CHARS moved into a temp file read by
+    ffmpeg's file form of the same option; the files are removed when the block ends. The command a
+    run records and prints is the caller's own, with the graph inline."""
+    import tempfile
+    out = list(cmd)
+    made: List[str] = []
+    try:
+        if _is_ffmpeg(out):
+            for i in range(1, len(out) - 1):
+                if _FILTER_OPTION_RE.match(out[i]) and len(out[i + 1]) > LONG_FILTER_CHARS:
+                    fd, path = tempfile.mkstemp(prefix="ffmpeg-skill-graph-", suffix=".txt")
+                    made.append(path)
+                    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                        fh.write(out[i + 1])
+                    out[i], out[i + 1] = _filter_file_option(out[i]), path
+        yield out
+    finally:
+        for path in made:
+            with contextlib.suppress(OSError):
+                os.remove(path)
+
+
 def _execute(exec_cmd: List[str]) -> subprocess.CompletedProcess:
     """One attempt, never exiting on failure (run() decides after its retries)."""
-    if STATE.progress and _is_ffmpeg(exec_cmd) and exec_cmd[-1] != "-":
-        return _run_with_progress(exec_cmd, False)
-    return _run_captured(exec_cmd, False)
+    with long_filters_in_files(exec_cmd) as cmd:
+        if STATE.progress and _is_ffmpeg(cmd) and cmd[-1] != "-":
+            return _run_with_progress(cmd, False)
+        return _run_captured(cmd, False)
 
 
 def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, record: bool = False) -> subprocess.CompletedProcess:
@@ -2134,7 +2203,8 @@ def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, r
         # input filename on stderr, and loudness/check parse the loudnorm JSON out of it. The
         # encoding kwargs are rejected with text=False, so they are only passed for text mode.
         text_kw = {"encoding": "utf-8", "errors": "replace"} if text else {}
-        proc = subprocess.run(list(cmd), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=text, **text_kw, timeout=limit)
+        with long_filters_in_files(cmd) as exec_cmd:
+            proc = subprocess.run(exec_cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=text, **text_kw, timeout=limit)
     except subprocess.TimeoutExpired:
         _timed_out(cmd, limit or 0)
     if check and proc.returncode != 0:
@@ -2569,7 +2639,6 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
     with os.replace() under the lock instead of copied -- a checked `cut.py --segments` join was
     copied whole, about 2 s for 240 MB. A rename that fails (another filesystem) falls back to
     the copy."""
-    import shutil
     cmd = ["ffmpeg", dst]
     _check_output_path(cmd)
     _check_existing_output(cmd)

package/scripts/_contract.py

@@ -3,6 +3,7 @@
 
     python3 scripts/_contract.py --json              # the contract, with detected capabilities
     python3 scripts/_contract.py --json --static     # same, without environment detection
+    python3 scripts/_contract.py --json --tool cut   # only cut under `tools` (repeatable)
     python3 scripts/_contract.py doctor [--json]     # which required capabilities this machine has
     ffmpeg-skill contract --json                     # the same through the npm entry point
 
@@ -21,7 +22,6 @@ import argparse
 import functools
 import importlib.util
 import json
-import os
 import platform
 import re
 import shutil
@@ -170,7 +170,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                      required=FF + [X264, AAC], optional=[HDR_X265],
                      video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "audio": dict(role="execution", inputs=["video or audio asset", "music bed (--music) or replacement track (--replace)", "effects/atmos track (--effects)"], outputs=["artifact with the processed audio (video stream-copied, or dropped when -o has an audio extension)"],
-                  required=FF, optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaincompress", "when": "--duck"},
+                  required=FF, optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaingate", "when": "--duck"}, {"capability": "filter:dcshift", "when": "--duck"},
                                         {"capability": "filter:acompressor", "when": "--compress / --voice"}, {"capability": "filter:alimiter", "when": "--limit / --voice strong"}, {"capability": "filter:agate", "when": "--gate"},
                                         {"capability": "filter:deesser", "when": "--voice medium (the default) / --voice strong"},
                                         {"capability": "filter:extrastereo", "when": "--stereo-widen"},
@@ -442,6 +442,7 @@ ERROR_REASONS = {
     "output_looks_like_option": "the output starts with '-' (other than '-' for stdout), which ffmpeg would read as an option; ./name writes a file of that name; details: {output}",
     "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_extension_missing": "a media output with no file extension (and no -f naming its format), so ffmpeg could not choose a container; refused before ffmpeg runs, dry runs included; details: {output}",
     "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}",
@@ -775,7 +776,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
     elif name == "verify":
         extra = {"report": {"type": ["string", "null"]},
                  "files": {"type": "array", "description": "one entry per file: {file, probe, steps, skipped}. A step is {step, ok, seconds, error (one line, for the table)}, plus the tool's verified when it completed, and on a failure its own kind, reason, message, details and exit_code (reason step_timeout or step_output_unparsed when the tool printed no failure document); skipped lists the steps that do not apply as {step, reason: quick|no_video|no_audio|not_hdr|not_multichannel|input_unreadable, message}"},
-                 "failed": {"type": "integer"}, "total": {"type": "integer"}}
+                 "failed": {"type": "integer"}, "total": {"type": "integer"},
+                 "out_dir": {"type": ["string", "null"], "description": "the folder the steps' outputs are in when they are kept: --out, or with --keep alone a new folder that outlives the run; null when they were written to a temporary folder and deleted"}}
     elif name == "batch":
         extra = {"results": {"type": "array", "description": "one row per input, every input (an interrupted batch included): ok (every step completed), verified (every step also verified what it wrote; false under --dry-run) and unverified ([{step, tool, failed}] naming the steps that did not); a failed row's error {step, tool, kind, message, code, reason, details, hint, exit_code} from the failing step's own document; diagnostics from its steps (tagged with step); cache_miss {reason: output_missing|output_changed|entry_unverifiable, ...} when a cache entry was not served; skipped \"timeout\" or \"interrupted\" for an item that never started and interrupted true for one stopped while running; under --watch, skipped \"settling\" (ok false, not cached) for a source that changed since the previous poll, or, first seen, was modified within one poll interval: it is processed on a later pass. A row whose recipe ran cut.py carries cut_reencoded (each cut.py call's reencoded) and cut_reencode_reasons (each reason those calls named, once per call)"},
                  "processed": {"type": "integer"}, "total": {"type": "integer"},
@@ -872,7 +874,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "silent": {"type": "array", "description": "--on-silent warn (default), only when a track was silent: [{flag, path, peak_db}] for each --music/--replace/--effects file, or under --duck the voice (flag \"input\"), whose whole-file peak is at or below --silence-threshold (default -50 dBFS); it was mixed anyway. --on-silent fail refuses instead, reason \"silent (peak X dBFS)\" in problems"},
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "present with `silent`: which tracks were silent and how to refuse them"},
                  "timing": {"type": "object", "description": "#486: {tempo, atempo, length_samples, sample_rate}: the --tempo factor (null without it), the atempo stages (each 0.5..2.0, [] at tempo 1) whose product it is, --length-samples (null without it) and the sample rate that count is in (null when not measured yet); with --length-samples a length_samples verification step counts the written track's decoded samples (exact for PCM/FLAC/ALAC, within tolerance_samples, one codec frame, for a lossy codec)"},
-                 "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, channel (--channel N, the 0-based channel kept, else null), sample_rate (--sample-rate, else null; both are read back from the output as the channels / sample_rate verification steps), effects/effects_volume, and with --music the music_volume plus duck (null when --duck was not given, else the threshold in dB and linear, ratio, attack_ms, release_ms, amount_db actually used)"}}
+                 "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, channel (--channel N, the 0-based channel kept, else null), sample_rate (--sample-rate, else null; both are read back from the output as the channels / sample_rate verification steps), effects/effects_volume, and with --music the music_volume plus duck (null when --duck was not given, else the threshold in dB and linear, the sidechain gate's ratio, attack_ms, release_ms, and amount_db, the depth in dB the bed is lowered under speech)"}}
     for key, prop in EMITTED_KEYS.get(name, {}).items():
         extra.setdefault(key, prop)
     if name in ("overlay", "graphics", "caption", "grid"):
@@ -1039,11 +1041,6 @@ def _ff_listing(binary: str, flag: str) -> Dict[str, Any]:
     return {"names": names, "status": "parsed", "detail": f"{len(names)} entries"}
 
 
-def _ff_list(binary: str, flag: str) -> List[str]:
-    """Names from `ffmpeg -encoders` / `-filters` / `-bsfs` (empty list when ffmpeg is missing or unparsed)."""
-    return _ff_listing(binary, flag)["names"]
-
-
 # GPU-backed encoders are named `<codec>_<backend>` by every ffmpeg build (h264_nvenc,
 # hevc_videotoolbox, av1_qsv, h264_vaapi, hevc_amf, ...); recognised by the backend suffix so a
 # new codec in a future ffmpeg build needs no change here.
@@ -2179,7 +2176,19 @@ def main() -> int:
     ap.add_argument("command", nargs="?", choices=["contract", "doctor"], default="contract")
     ap.add_argument("--json", action="store_true", help="JSON on stdout (the contract is always JSON)")
     ap.add_argument("--static", action="store_true", help="omit environment detection (available / missing capabilities)")
+    ap.add_argument("--tool", action="append", metavar="NAME",
+                    help="only this tool's entry under `tools` (repeatable; `cut` or `cut.py`); every other key is "
+                         "unchanged. The whole contract is about 950 KB; with one tool, 55-85 KB")
     args = ap.parse_args()
+    wanted: List[str] = []
+    for name in args.tool or []:
+        name = name[:-3] if name.endswith(".py") else name
+        if name not in public_tools():
+            ap.error(f"--tool {name}: no such tool (one of: {', '.join(public_tools())})")
+        if name not in wanted:
+            wanted.append(name)
+    if wanted and args.command == "doctor":
+        ap.error("--tool selects from the contract; doctor --json lists every tool under `tools`")
     if args.command == "doctor":
         d = doctor()
         # On stderr in both modes, so `doctor --json`'s stdout stays one JSON document: an
@@ -2225,7 +2234,12 @@ def main() -> int:
         # 1: something required is missing; 2: nothing proven missing but a required capability is unknown
         # an unsupported Python/FFmpeg is a known failure, like a missing capability (not "unknown")
         return 1 if d["missing"] or d.get("unsupported") else 2
-    print(json.dumps(build(detect=not args.static), indent=2, sort_keys=True, ensure_ascii=False))
+    doc = build(detect=not args.static)
+    if wanted:
+        # in the order asked; `provides` and `capability_map` stay whole (a few KB): they map ids
+        # to tools across the skill, which one tool's entry does not change (#467 A220)
+        doc["tools"] = sorted((t for t in doc["tools"] if t["name"] in wanted), key=lambda t: wanted.index(t["name"]))
+    print(json.dumps(doc, indent=2, sort_keys=True, ensure_ascii=False))
     return 0
 
 

package/scripts/_platforms.py

@@ -230,11 +230,6 @@ ALIASES: Dict[str, str] = {"youtube-shorts": "shorts", "yt-shorts": "shorts", "y
 PLATFORM_CHOICES: List[str] = sorted({n for n in PLATFORMS if PLATFORMS[n]["check"] == n} | set(ALIASES))
 
 
-def has_frame(name: str) -> bool:
-    """True when this destination has a frame, and therefore a safe zone to place text inside."""
-    return bool(PLATFORMS.get(resolve(name) or "", {}).get("frame"))
-
-
 def spec_of(name: str) -> Dict[str, Any]:
     """check.py's compliance row values for a destination."""
     return dict(PLATFORMS[name]["spec"])

package/scripts/_smartcut.py

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

package/scripts/audio.py

@@ -29,8 +29,8 @@ from typing import Any, Dict, List
 
 from _common.probe import SILENT_PEAK_DBFS
 from _common import STATE, add_common, dry_run_input_pending, require_tool, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, measured_level_dbfs, probe, run, run_keeping_subtitles, fmt_secs
-from _common.emit import warn
-from _common.decision import conform_filter, conform_to_length
+from _common.emit import file_origin, stream_end, warn
+from _common.decision import LOSSLESS_AUDIO_EXT, conform_filter, conform_to_length
 
 # --downmix: ITU-R BS.775 fold-down, renormalised by pan's '<' (see main()).
 DOWNMIX_PAN = "pan=stereo|FL<FL+0.707*FC+0.707*BL+0.707*SL|FR<FR+0.707*FC+0.707*BR+0.707*SR"
@@ -43,10 +43,11 @@ VOICE_CHAIN = f"highpass=f=80,deesser=i=0.4,{VOICE_DENOISE},acompressor=threshol
 # which is what a good room recording needs; "strong" is for phone/laptop audio: a harder
 # de-esser, a second compression stage and a soft limiter at -1 dBFS so the peaks stop there
 # instead of at whatever the make-up gain produced.
+VOICE_LIMITER = "alimiter=limit=0.891251:level=disabled:latency=1"  # --voice strong's -1 dBFS ceiling
 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:latency=1",
+    "strong": VOICE_CHAIN + ",deesser=i=0.6,acompressor=threshold=-24dB:ratio=4:attack=5:release=120:makeup=3," + VOICE_LIMITER,
 }
 
 
@@ -66,11 +67,40 @@ def voice_chain(level: str, denoise_strength: "float | None") -> str:
     return chain.replace("highpass=f=80,", f"highpass=f=80,{stage},", 1)
 
 
-# The sidechain threshold the music bed has used since 1.4 is the linear 0.05 that ffmpeg's
-# sidechaincompress takes; -26.0206 dBFS is that same number in the unit the flag speaks, so the
-# default command line is unchanged to the byte while the value is now sayable.
+# The sidechain threshold the music bed has used since 1.4 is the linear 0.05 the filter takes;
+# -26.0206 dBFS is that same number in the unit the flag speaks.
 DUCK_THRESHOLD_DB = -26.0206
 
+# the knee the filters take is a linear 1..8 (default 2.82843): in the dB the flag speaks that is
+# 0..18.06 dB, default 9.03 dB. The flag used to accept 1..8 *dB* (linear 1.12..2.51), so no knee
+# from 2.51 up to ffmpeg's own default could be asked for, and the help gave the default as 2.83 dB
+KNEE_MAX_DB = 18.06  # 20*log10(8) = 18.0618, rounded down so the linear value stays inside 1..8
+
+# --duck (A134): the bed is lowered by exactly --duck-amount dB while the speech is above the
+# threshold. A sidechain gate keyed by the speech passes the bed where there is speech and nothing
+# elsewhere; that part, scaled by -(1 - 10^(-amount/20)), is added back to the bed, which leaves
+# 10^(-amount/20) of it under speech and all of it in the pauses. The sidechain compressor used
+# through 3.8.8 took the amount as ratio = max(2, amount/3), and a compressor's depth is how far
+# the speech rises over its threshold: on the test's speech 0 and 3 ducked the same 9.7 dB, 60 ducked 18.
+# The key gets a DC offset far below any threshold (-120 dBFS) because agate's detector leaves the
+# gate open on a key that is exact zeros from its first sample. The knee is hard (knee=1): agate's
+# default soft knee (2.82843) opened the gate only about 2 dB over the threshold, so a key just
+# over it left the bed at its level (measured: a sine 1.5 dB over -7.5 dBFS ducked 0 dB of 12).
+DUCK_GATE_RATIO = 9000.0  # agate's largest: closed below the threshold
+DUCK_KEY_DC = "dcshift=shift=0.000001"
+
+
+def duck_graph(threshold_db: float, amount_db: float, attack: float, release: float) -> List[str]:
+    """The filter-graph lines that turn `[music]` and the speech key `[sc]` into `[ducked]`."""
+    cut = 1.0 - 10 ** (-amount_db / 20.0)
+    return ["[music]asplit=2[mdry][mwet]",
+            f"[sc]{DUCK_KEY_DC}[key]",
+            f"[mwet][key]sidechaingate=threshold={db_to_linear(threshold_db):.6g}:ratio={DUCK_GATE_RATIO:g}:range=0:knee=1"
+            f":attack={attack:g}:release={release:g}[mspeech]",
+            f"[mspeech]volume={-cut:.6g}[mcut]",
+            "[mdry][mcut]amix=inputs=2:normalize=0[ducked]"]
+
+
 # Typed dynamics: every flag maps to one real option of one ffmpeg filter, validated against the
 # range that filter documents (ffmpeg -h filter=acompressor / alimiter / agate). dB flags are
 # converted to the linear value the filter takes, so no string reaches the graph unchecked.
@@ -81,7 +111,7 @@ DYNAMICS = {
         "comp_attack": ("attack", "ms", 0.01, 2000.0),
         "comp_release": ("release", "ms", 0.01, 9000.0),
         "comp_makeup": ("makeup", "dB", 0.0, 36.0),               # 1..64 linear
-        "comp_knee": ("knee", "dB", 1.0, 8.0),
+        "comp_knee": ("knee", "dB", 0.0, KNEE_MAX_DB),         # 1..8 linear (A135: was 1..8 dB, linear 1.12..2.51)
     },
     "alimiter": {
         "limit_ceiling": ("limit", "dB", -24.0, 0.0),             # 0.0625..1 linear
@@ -94,7 +124,7 @@ DYNAMICS = {
         "gate_attack": ("attack", "ms", 0.01, 9000.0),
         "gate_release": ("release", "ms", 0.01, 9000.0),
         "gate_range": ("range", "dB", -90.0, 0.0),                # 0..1 linear: how far the gate closes
-        "gate_knee": ("knee", "dB", 1.0, 8.0),
+        "gate_knee": ("knee", "dB", 0.0, KNEE_MAX_DB),         # 1..8 linear
     },
 }
 
@@ -289,8 +319,8 @@ def main() -> int:
     music = ap.add_argument_group("music")
     music.add_argument("--music", help="music file to mix underneath")
     music.add_argument("--music-volume", type=float, default=-14.0, help="music level in dB relative to full scale (default -14)")
-    music.add_argument("--duck", action="store_true", help="auto-duck the music when the main track has speech (sidechain compressor)")
-    music.add_argument("--duck-amount", type=float, default=12.0, help="how many dB to duck (default 12)")
+    music.add_argument("--duck", action="store_true", help="auto-duck the music by --duck-amount dB while the main track has speech (a sidechain gate keyed by it)")
+    music.add_argument("--duck-amount", type=float, default=12.0, help="how many dB the music is lowered under speech, 0..60 (default 12)")
     music.add_argument("--duck-threshold", type=float, default=DUCK_THRESHOLD_DB,
                        help="sidechain threshold in dBFS: the main track is heard as speech above this (default -26.02, the 0.05 linear used since 1.4)")
     music.add_argument("--duck-attack", type=float, default=20.0, help="ms the bed takes to duck once speech starts (default 20)")
@@ -326,25 +356,27 @@ def main() -> int:
                              "(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)")
+    dyn.add_argument("--comp-threshold", type=float, help="dBFS above which gain is reduced, -60..0 (ffmpeg default -18.06, its linear 0.125)")
     dyn.add_argument("--comp-ratio", type=float, help="ratio 1..20 (default 2)")
     dyn.add_argument("--comp-attack", type=float, help="ms 0.01..2000 (default 20)")
     dyn.add_argument("--comp-release", type=float, help="ms 0.01..9000 (default 250)")
     dyn.add_argument("--comp-makeup", type=float, help="make-up gain dB 0..36 (default 0)")
-    dyn.add_argument("--comp-knee", type=float, help="knee dB 1..8 (default 2.83)")
+    dyn.add_argument("--comp-knee", type=float, help="knee width dB 0..18.06 (ffmpeg's linear 1..8; default 9.03, its 2.82843)")
     dyn.add_argument("--limit", action="store_true", help="look-ahead limiter (alimiter), level left as is")
     dyn.add_argument("--limit-ceiling", type=float, help="ceiling dBFS -24..0 (default 0)")
     dyn.add_argument("--limit-attack", type=float, help="ms 0.1..80 (default 5)")
     dyn.add_argument("--limit-release", type=float, help="ms 1..8000 (default 50)")
     dyn.add_argument("--gate", action="store_true", help="noise gate (agate)")
-    dyn.add_argument("--gate-threshold", type=float, help="dBFS below which the gate closes, -60..0 (default -18.1)")
+    dyn.add_argument("--gate-threshold", type=float, help="dBFS below which the gate closes, -60..0 (default -18.06, ffmpeg's linear 0.125)")
     dyn.add_argument("--gate-ratio", type=float, help="ratio 1..9000 (default 2)")
     dyn.add_argument("--gate-attack", type=float, help="ms 0.01..9000 (default 20)")
     dyn.add_argument("--gate-release", type=float, help="ms 0.01..9000 (default 250)")
-    dyn.add_argument("--gate-range", type=float, help="attenuation when closed, dB -90..0 (default -6.1)")
-    dyn.add_argument("--gate-knee", type=float, help="knee dB 1..8 (default 2.83)")
+    dyn.add_argument("--gate-range", type=float, help="attenuation when closed, dB -90..0 (default -24.26, ffmpeg's linear 0.06125)")
+    dyn.add_argument("--gate-knee", type=float, help="knee width dB 0..18.06 (ffmpeg's linear 1..8; default 9.03, its 2.82843)")
     ap.add_argument("--audio-stream", type=int, default=0, help="which audio stream of the input to process, 0-based in file order (probe lists them under audio_streams)")
-    ap.add_argument("--bitrate", default="192k")
+    ap.add_argument("--bitrate", default=None,
+                    help="audio bitrate: AAC's beside a picture (default 192k), and the codec's of a lossy audio output "
+                         "(.m4a/.aac default 256k, .mp3 -q:a 0, .ogg -q:a 6, .opus 128k); refused for .wav/.flac")
     ap.add_argument("--on-silent", choices=["warn", "fail"], default="warn",
                     help="a --music/--replace/--effects file (or, under --duck, the voice) whose peak is at or below "
                          "--silence-threshold: warn (default: mix it, report it under `silent`) or fail (refuse before ffmpeg runs)")
@@ -391,7 +423,7 @@ def main() -> int:
                                 ("--duck-attack", args.duck_attack, 0.01, 2000.0),
                                 ("--duck-release", args.duck_release, 0.01, 9000.0)):
         if not (lo <= value <= hi):
-            die(f"{flag} {value:g} is outside {lo:g}..{hi:g} (the range ffmpeg's sidechaincompress accepts)")
+            die(f"{flag} {value:g} is outside {lo:g}..{hi:g}")
     if args.stereo_widen is not None and not (0.0 <= args.stereo_widen <= 1.0):
         die(f"--stereo-widen must be 0..1 (0 = untouched, 1 = maximum), got {args.stereo_widen:g}")
 
@@ -421,6 +453,9 @@ def main() -> int:
         die("input has no audio stream (use --replace to add one)")
     output = args.output or default_output(args.input, "audio")
     audio_out = is_audio_output(output)
+    if args.bitrate is not None and Path(output).suffix.lower() in LOSSLESS_AUDIO_EXT:
+        # A143: the rate used to be dropped without a word for every audio extension
+        die(f"--bitrate has no effect on a lossless {Path(output).suffix.lower()} output; drop it, or write a lossy one (.m4a, .mp3, ...)")
     streams = meta.get("audio_streams") or []
     if streams and not (0 <= args.audio_stream < len(streams)) and not STATE.dry_run:
         die(f"--audio-stream {args.audio_stream}: input has {len(streams)} audio stream(s), 0..{len(streams) - 1}")
@@ -486,8 +521,17 @@ def main() -> int:
         # 7.1), so in-phase channels at full scale cannot clip; '=' summed 2.7x and clipped a loud
         # 5.1 while the run said verified.
         fx.append(DOWNMIX_PAN)
+    # A129: a limiter is the ceiling of what is delivered, so with a bed mixed in it runs after the
+    # mix: on the voice alone, the music and effects added on top of it peaked over the ceiling
+    # (--limit-ceiling -6 delivered 0 dBFS, --voice strong's -1 dBFS -0.2)
+    limit_after_mix = bool(args.music or args.effects)
+    post_limit: List[str] = []
     if args.voice:
-        fx.append(voice_chain(args.voice, args.denoise_strength if args.denoise else None))
+        chain = voice_chain(args.voice, args.denoise_strength if args.denoise else None)
+        if limit_after_mix and chain.endswith("," + VOICE_LIMITER):
+            chain = chain[: -len("," + VOICE_LIMITER)]
+            post_limit.append(VOICE_LIMITER)
+        fx.append(chain)
     elif args.denoise:
         fx.append(f"afftdn=nf=-{args.denoise_strength:g}:tn=1")
     if args.gain:
@@ -497,7 +541,7 @@ def main() -> int:
     if args.compress:
         fx.append(dynamics_filter("acompressor", args))
     if args.limit:
-        fx.append(dynamics_filter("alimiter", args))
+        (post_limit if limit_after_mix else fx).append(dynamics_filter("alimiter", args))
     if args.mono:
         # after --downmix the track is the stereo fold-down, whatever the source had
         in_ch = 2 if args.downmix else (in_channels or 2)
@@ -542,15 +586,28 @@ def main() -> int:
         m = f"{idx}:a:0"
         idx += 1
         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}")
+        # A142: a bed shorter than the output (and not looped) stops at its own end, so its fade
+        # ends there: timed on the output's end it started after the bed had stopped at full level
+        # ... and at the main track's end when the output runs past it (--length-samples): the
+        # atrim above has cut the bed there. All three are timestamps, which is what afade reads:
+        # a bed whose sound starts late in its file (2 to 5 s) keeps those, so its fade ends at 5,
+        # not at its 3 s length (that fade ran over the bed's first second)
+        ends = [t for t in (end_dur, main_dur) if t]
+        if args.music_fade_out and not args.music_loop and not dry_run_input_pending(args.music):
+            bed_meta = probe(args.music)
+            bed_stop = stream_end(bed_meta, "audio")
+            if bed_stop is not None and bed_stop - file_origin(bed_meta) > 0:
+                ends.append(bed_stop - file_origin(bed_meta))
+        bed_end = min(ends) if ends else None
+        if args.music_fade_out and bed_end:
+            # a fade longer than the bed is cut to it, so the bed still ends silent (a 5 s fade on
+            # a 2 s bed started at 0 and stopped at 60% gain)
+            m_fade = min(args.music_fade_out, bed_end)
+            mfx.append(f"afade=t=out:st={bed_end - m_fade:.3f}:d={m_fade:g}")
         graph.append(f"[{m}]{','.join(mfx)}[music]")
         if args.duck:
             graph.append("[main]asplit=2[mainA][sc]")
-            graph.append(
-                f"[music][sc]sidechaincompress=threshold={db_to_linear(args.duck_threshold):.6g}"
-                f":ratio={max(2.0, args.duck_amount / 3):.1f}:attack={args.duck_attack:g}:release={args.duck_release:g}:makeup=1[ducked]"
-            )
+            graph += duck_graph(args.duck_threshold, args.duck_amount, args.duck_attack, args.duck_release)
             graph.append("[mainA][ducked]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mix]")
         else:
             graph.append("[main][music]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mix]")
@@ -567,11 +624,12 @@ def main() -> int:
         graph.append(f"[{last}][effects]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mixfx]")
         last = "mixfx"
 
-    post: List[str] = []
+    post: List[str] = list(post_limit)
     if args.fade_in:
         post.append(f"afade=t=in:st=0:d={args.fade_in: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}")
+        fade_out = min(args.fade_out, end_dur)  # cut to the output, so it still ends silent
+        post.append(f"afade=t=out:st={end_dur - fade_out:.3f}:d={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
@@ -628,7 +686,7 @@ def main() -> int:
         audio_block["music_volume"] = args.music_volume
         audio_block["duck"] = ({"amount_db": args.duck_amount, "threshold_db": round(args.duck_threshold, 4),
                                 "threshold_linear": float(f"{db_to_linear(args.duck_threshold):.6g}"),
-                                "ratio": round(max(2.0, args.duck_amount / 3), 1),
+                                "ratio": DUCK_GATE_RATIO,
                                 "attack_ms": args.duck_attack, "release_ms": args.duck_release}
                                if args.duck else None)
     verification: List[Dict[str, Any]] = []

package/scripts/background.py

@@ -19,7 +19,7 @@ import sys
 
 from _common.alpha import add_alpha_args, check_alpha_args, finish_chain, report as alpha_report, video_line
 from _common.emit import note
-from _common import STATE,  add_common, apply_common, die, draws_chroma, emit, ffmpeg_base, info, parse_time, probe, rgb_chain_to_bt709, run, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs
+from _common import STATE,  add_common, apply_common, die, draws_chroma, emit, ffmpeg_base, info, probe, rgb_chain_to_bt709, run, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs
 
 
 def gradient_source(w: int, h: int, fps: float, c0: str, c1: str, angle: float) -> str: