ffmpeg-skill 1.11.1 → 1.13.0

package/scripts/_contract.py

@@ -157,9 +157,11 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "multicam": dict(role="execution", inputs=["reference camera", "other cameras / recorders"], outputs=["switched multicam video artifact"],
                      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)"], outputs=["artifact with the processed audio (video stream-copied, or dropped when -o has an audio extension)"],
+    "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"},
-                                        {"capability": "filter:acompressor", "when": "--compress / --voice"}, {"capability": "filter:alimiter", "when": "--limit"}, {"capability": "filter:agate", "when": "--gate"},
+                                        {"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": 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)"],
@@ -411,7 +413,9 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
         extra = {"loudness": {"type": "object", "description": "platform presets with audio: the written file's lufs/tp against the platform's target_lufs/target_tp, ok true when inside the spec; normalized true when --normalize ran loudness.py on the file"},
                  "notes": {"type": "array", "items": {"type": "string"}}}
     elif name == "loudness":
-        extra = {"measured": {"type": "object", "description": "--measure-only prints the loudnorm measurement instead (input_i, input_tp, input_lra, input_thresh, target_offset)"}}
+        extra = {"measured": {"type": "object", "description": "the loudnorm measurement of the input (input_i, input_tp, input_lra, input_thresh, target_offset); with --measure-only it is the whole result"},
+                 "targets": {"type": "object", "description": "the requested lufs / tp / lra"},
+                 "result": {"type": "object", "description": "the written file measured again (input_i, input_tp, input_lra, ...), plus tp_ceiling_used, audio_bitrate_used and encodes"}}
     elif name == "cut":
         extra = {"expected_duration": {"type": "number", "description": "seconds requested"},
                  "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},
@@ -426,7 +430,8 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
     elif name == "audio":
         extra = {"video": {"type": "boolean", "description": "true when the input's video stream was copied; false for an audio output extension (extraction)"},
                  "audio_stream": {"type": "integer", "description": "which input audio stream was processed (--audio-stream)"},
-                 "dynamics": {"type": "array", "items": {"enum": ["agate", "acompressor", "alimiter"]}, "description": "typed dynamics filters applied, in graph order"}}
+                 "dynamics": {"type": "array", "items": {"enum": ["agate", "acompressor", "alimiter"]}, "description": "typed dynamics filters applied, in graph order"},
+                 "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)"}}
     props = dict(base)
     props.update(extra)
     required = ["status", "output", "dry_run", "commands"]
@@ -765,9 +770,53 @@ def doctor() -> Dict[str, Any]:
 
 
 def _fonts_capability() -> Dict[str, Any]:
+    """The default drawtext family (issue #66) plus, since 1.12, one entry per script the tools
+    can detect: which languages this machine can actually RENDER, not just which filters exist.
+
+    Per script: available (a font file covers it, path in `file`), missing (fontconfig knows none),
+    unknown (no fontconfig to ask -- the same "unknown is not missing" rule every other capability
+    here follows). Informational like the default font and gpu_encoders: a machine with no Thai
+    font is not a broken install, it is a machine that must not be asked to burn Thai captions.
+    """
+    from _common import SCRIPTS, font_for_script, script_font_status
+
     font = _default_font()
     result = _font_available(font)
-    return {"default_font": font, "status": result["status"], "detail": result["detail"]}
+    scripts: Dict[str, Any] = {}
+    for script in SCRIPTS:
+        if script == "latin":
+            continue
+        # script_font_status() is the one place that tells "fontconfig answered, nothing covers
+        # this" (missing) apart from "there is no working fontconfig to ask" (unknown) -- the same
+        # distinction the tools refuse or continue on.
+        status = script_font_status(script)
+        scripts[script] = {"status": status, "file": font_for_script(script) if status == "available" else None}
+    return {"default_font": font, "status": result["status"], "detail": result["detail"], "scripts": scripts}
+
+
+def _fonts_summary_line(fonts: Dict[str, Any]) -> str:
+    """One line for the plain-text doctor: which scripts render here, which do not."""
+    scripts = fonts.get("scripts") or {}
+    by_state: Dict[str, List[str]] = {"available": [], "missing": [], "unknown": []}
+    for name, entry in scripts.items():
+        by_state.setdefault(entry["status"], []).append(name)
+    # the default font's `detail` (which family fontconfig substituted, or why it is unknown) is
+    # the actionable half of a non-available status, and the line has room for it
+    head = f"fonts: '{fonts['default_font']}' {fonts['status']}"
+    detail = fonts.get("detail") or ""
+    # The substituted family is the actionable half of a non-available status, so it goes on the
+    # plain line -- but only while it stays short enough to keep doctor's one-line-per-capability
+    # shape (the longest other line is ~85 chars). A long explanation is --json only.
+    if detail and fonts["status"] != "available" and len(detail) <= 60:
+        head += f" ({detail})"
+    parts = [head]
+    if by_state["available"]:
+        parts.append("renders " + " ".join(by_state["available"]))
+    if by_state["missing"]:
+        parts.append("no font for " + " ".join(by_state["missing"]))
+    if by_state["unknown"]:
+        parts.append("unknown (no fontconfig) " + " ".join(by_state["unknown"]))
+    return "; ".join(parts)
 
 
 def _capability_fix_hint(cap: str) -> str:
@@ -795,6 +844,11 @@ def _capability_fix_hint(cap: str) -> str:
         return f"this ffmpeg build has no {cap[7:]} filter; {full_hint}"
     if cap.startswith("bsf:"):
         return f"this ffmpeg build has no {cap[4:]} bitstream filter; {full_hint}"
+    if cap.startswith("font:"):
+        from _common import LANGUAGE_NAMES, FONT_INSTALL_HINT
+        script = cap[5:]
+        return (f"no installed font covers {LANGUAGE_NAMES.get(script, script)} text on this machine; "
+                f"{FONT_INSTALL_HINT} (doctor --json .fonts.scripts lists every script)")
     if cap == "external:whisper":
         return "install a local whisper (whisper-cli, whisper-cpp, faster-whisper or openai-whisper) for --transcribe"
     return f"'{cap}' is not available; see docs/contract.md"
@@ -1152,9 +1206,7 @@ def main() -> int:
             gpu = d["gpu_encoders"]
             if gpu["status"] == "parsed":
                 print(f"GPU-backed encoders in this build: {len(gpu['present'])} (no tool here uses one; names in doctor --json)")
-            fonts = d["fonts"]
-            print(f"default drawtext font '{fonts['default_font']}': {fonts['status']}"
-                  + (f" ({fonts['detail']})" if fonts["status"] != "available" else ""))
+            print(_fonts_summary_line(d["fonts"]))
             print("full detail: doctor --json (capability lists, per-tool `usable`, fix hints)")
             for err in d["errors"]:
                 print(f"detection error: {err}", file=sys.stderr)

package/scripts/audio.py

@@ -7,9 +7,12 @@ drops the picture, so `audio.py talk.mp4 -o talk.wav` is an extraction.
 Examples:
   python3 audio.py interview.mp4 --denoise                      # FFT noise reduction
   python3 audio.py interview.mp4 --voice                        # highpass + de-esser + compressor + denoise
+  python3 audio.py interview.mp4 --voice light                  # highpass + gentle compression only (light|medium|strong)
   python3 audio.py talk.mp4 --music bed.mp3 --duck              # music under speech, auto-ducked
   python3 audio.py talk.mp4 --music bed.mp3 --music-volume -18 --music-fade-out 3   # bed fades, voice does not
   python3 audio.py clip.mp4 --fade-in 0.5 --fade-out 1 --stereo
+  python3 audio.py talk.mp4 --music bed.mp3 --duck --duck-threshold -30 --duck-release 250   # ducks earlier and recovers faster
+  python3 audio.py band.wav --stereo-widen 0.5 -o wide.wav      # wider stereo image (a real stereo source; mono is refused)
   python3 audio.py surround.mov --downmix                       # 5.1 -> stereo with proper centre/LFE weights
   python3 audio.py clip.mp4 --replace narration.wav             # swap the audio track entirely
   python3 audio.py interview.mp4 -o interview.wav               # extract the audio (no video in the output)
@@ -18,12 +21,29 @@ Examples:
 """
 import argparse
 import sys
-from typing import List
+from typing import Any, Dict, List
 
 from _common import STATE, add_common, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, run_keeping_subtitles, fmt_secs
 
 VOICE_CHAIN = "highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2"
 
+# --voice [light|medium|strong] (1.13). "medium" is the chain --voice has always produced, so a
+# bare --voice (and every existing call and MCP request) is byte-identical to before. "light"
+# leaves the noise floor and the sibilance alone -- it only removes rumble and evens the level,
+# 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_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",
+}
+
+# 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.
+DUCK_THRESHOLD_DB = -26.0206
+
 # 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.
@@ -79,13 +99,23 @@ def main() -> int:
     clean = ap.add_argument_group("clean-up")
     clean.add_argument("--denoise", action="store_true", help="FFT noise reduction (afftdn, adaptive)")
     clean.add_argument("--denoise-strength", type=float, default=25.0, help="noise floor in dB to remove, 10..60 (default 25)")
-    clean.add_argument("--voice", action="store_true", help="speech preset: highpass 80 Hz, de-esser, denoise, gentle compression")
+    clean.add_argument("--voice", nargs="?", const="medium", choices=["light", "medium", "strong"], default=None,
+                       help="speech preset (default medium when the flag is given bare): light = highpass 80 Hz + gentle compression; "
+                            "medium = highpass, de-esser, denoise, gentle compression; strong = medium plus a harder de-esser, a second "
+                            "compressor and a soft limiter at -1 dBFS. MCP/JSON callers may still send the 1.12 boolean true, "
+                            "which is the bare flag and so means medium")
     clean.add_argument("--gain", type=float, help="gain in dB applied to the main track")
     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-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)")
+    music.add_argument("--duck-release", type=float, default=400.0, help="ms the bed takes to come back up after speech (default 400)")
+    music.add_argument("--effects", help="a third track (sound effects/atmos) mixed in at --effects-volume; never ducked")
+    music.add_argument("--effects-volume", type=float, default=-14.0, help="effects level in dB relative to full scale (default -14)")
     music.add_argument("--music-loop", action="store_true", help="loop the music if shorter than the video")
     fades = ap.add_argument_group("fades / layout")
     fades.add_argument("--fade-in", type=float, default=0.0, help="seconds")
@@ -94,6 +124,10 @@ def main() -> int:
     channels = fades.add_mutually_exclusive_group()
     channels.add_argument("--stereo", action="store_true", help="force 2-channel output (mono is duplicated to both sides)")
     channels.add_argument("--mono", action="store_true", help="force 1-channel output")
+    fades.add_argument("--stereo-widen", type=float, default=None, metavar="AMOUNT",
+                       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("--downmix", action="store_true", help="downmix 5.1/7.1 to stereo using standard weights")
     fades.add_argument("--replace", help="replace the audio with this file (trimmed/padded to the video)")
     dyn = ap.add_argument_group("dynamics (typed; each flag is one option of ffmpeg's acompressor / alimiter / agate)")
@@ -124,6 +158,26 @@ def main() -> int:
         if not getattr(args, switch) and any(getattr(args, f) is not None for f in DYNAMICS[flag_group]):
             die(f"--{switch} is off but one of its parameters was given; add --{switch}")
 
+    # Same rule as the typed dynamics above, for the ducking knobs: a parameter for a switch that
+    # is off does nothing, and a caller who says --duck-release 250 and gets the default 400 ms has
+    # no way to notice. --duck itself needs a bed to duck.
+    duck_params = [f"--duck-{name}" for name in ("threshold", "attack", "release")
+                   if getattr(args, f"duck_{name}") != ap.get_default(f"duck_{name}")] + \
+                  (["--duck-amount"] if args.duck_amount != ap.get_default("duck_amount") else [])
+    if not args.duck and duck_params:
+        die(f"--duck is off but {duck_params[0]} was given; add --duck")
+    if args.duck and not args.music:
+        die("--duck ducks the music bed under the main track, but no --music was given; add --music FILE")
+
+    for flag, value, lo, hi in (("--duck-amount", args.duck_amount, 0.0, 60.0),
+                                ("--duck-threshold", args.duck_threshold, -60.0, 0.0),
+                                ("--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)")
+    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}")
+
     meta = probe(args.input)
     dur = meta.get("duration") or 0.0
     has_video = bool(meta.get("video"))
@@ -136,6 +190,19 @@ def main() -> int:
         die(f"--audio-stream {args.audio_stream}: input has {len(streams)} audio stream(s), 0..{len(streams) - 1}")
     if args.audio_stream and not streams and not STATE.dry_run:
         die("--audio-stream needs an input with audio streams")
+    in_channels = (meta.get("audio") or {}).get("channels") or 0
+    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")
+        # Widening scales the side signal (L-R). Duplicating a mono track to two channels leaves
+        # L == R, so the side signal is exactly zero and scaling it changes nothing: --stereo is
+        # not a way in, it is a way to a file that measures mono no matter the amount asked for.
+        if in_channels == 1:
+            die("--stereo-widen needs a real stereo source: mono has no stereo image to widen; keep it mono or "
+                "use --stereo to duplicate it, but widening needs a real stereo source")
+        if in_channels > 2 and not args.downmix:
+            die(f"--stereo-widen needs a stereo track; this input has {in_channels} channels. Add --downmix to fold it "
+                "to stereo first (the widening then happens after the downmix), or leave the channels alone.")
 
     inputs: List[str] = ["-i", args.input]
     main_src = f"0:a:{args.audio_stream}"
@@ -150,7 +217,7 @@ def main() -> int:
     if args.downmix:
         fx.append("pan=stereo|FL=0.707*FC+FL+0.5*BL+0.5*SL+0.5*LFE|FR=0.707*FC+FR+0.5*BR+0.5*SR+0.5*LFE")
     if args.voice:
-        fx.append(VOICE_CHAIN)
+        fx.append(VOICE_LEVELS[args.voice])
     elif args.denoise:
         if not 10 <= args.denoise_strength <= 60:
             die(f"--denoise-strength must be 10..60 (dB of noise floor to remove), got {args.denoise_strength:g}")
@@ -172,6 +239,11 @@ def main() -> int:
         # 1 channel: already mono; the stereo pan used to halve it (-6 dB) because c1 was silence
     elif args.stereo:
         fx.append("aformat=channel_layouts=stereo")
+    if args.stereo_widen is not None:
+        # extrastereo widens by scaling the side (L-R) signal: m=1 is the input, m=3 is as wide
+        # 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}")
 
     graph: List[str] = []
     graph.append(f"[{main_src}]{','.join(fx) if fx else 'anull'}[main]")
@@ -192,13 +264,26 @@ def main() -> int:
         if args.duck:
             graph.append("[main]asplit=2[mainA][sc]")
             graph.append(
-                f"[music][sc]sidechaincompress=threshold=0.05:ratio={max(2.0, args.duck_amount / 3):.1f}:attack=20:release=400:makeup=1[ducked]"
+                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.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]")
         last = "mix"
 
+    if args.effects:
+        # A third bed, mixed in at its own level and deliberately never ducked: effects are cut
+        # to the picture, so dipping them under speech would move them off their own frames.
+        probe(args.effects)
+        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"]
+        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"
+
     post: List[str] = []
     if args.fade_in:
         post.append(f"afade=t=in:st=0:d={args.fade_in:g}")
@@ -237,7 +322,16 @@ def main() -> int:
         die(f"{output} unexpectedly contains a video stream")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz"
          + (", video stream-copied" if has_video and not audio_out else ", video dropped" if has_video else "") + ")")
-    emit(output, video=bool(has_video and not audio_out), audio_stream=args.audio_stream,
+    audio_block: Dict[str, Any] = {"voice": args.voice, "stereo_widen": args.stereo_widen,
+                                   "effects": bool(args.effects), "effects_volume": args.effects_volume if args.effects else None}
+    if args.music:
+        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),
+                                "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,
          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)
     return 0