ffmpeg-skill 0.1.0

package/scripts/fit.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Fit a video to a target duration and/or aspect ratio.
+
+Duration: --duration N with --method speed (retime video+audio, pitch-preserving
+via atempo chaining) or --method trim (keep the first N seconds, or a centred
+window with --from-center). Aspect: --aspect 16:9|9:16|1:1|4:5|W:H with
+--fit pad (letterbox/pillarbox with --pad-color, default black) or --fit crop
+(centre crop). --width sets the output width; height follows the aspect.
+
+Examples:
+  python3 fit.py input.mp4 --duration 60                    # speed up/down to exactly 60s
+  python3 fit.py input.mp4 --duration 30 --method trim
+  python3 fit.py input.mp4 --aspect 9:16 --fit pad --width 1080
+  python3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15
+"""
+import argparse
+import math
+import sys
+from fractions import Fraction
+from typing import List
+
+from _common import aac_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+
+ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
+
+
+def parse_aspect(value: str) -> Fraction:
+    if value in ASPECT_PRESETS:
+        return ASPECT_PRESETS[value]
+    try:
+        w, h = value.split(":")
+        return Fraction(int(w), int(h))
+    except (ValueError, ZeroDivisionError):
+        die(f"bad aspect '{value}', use W:H like 16:9")
+    return Fraction(1)  # unreachable
+
+
+def atempo_chain(factor: float) -> str:
+    """atempo accepts 0.5..100 per instance; chain for extreme factors."""
+    parts: List[str] = []
+    remaining = factor
+    while remaining < 0.5:
+        parts.append("atempo=0.5")
+        remaining /= 0.5
+    while remaining > 100.0:
+        parts.append("atempo=100.0")
+        remaining /= 100.0
+    parts.append(f"atempo={remaining:.6f}")
+    return ",".join(parts)
+
+
+def even(n: float) -> int:
+    v = int(round(n))
+    return v if v % 2 == 0 else v + 1
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_fit.<ext>)")
+    d = ap.add_argument_group("duration")
+    d.add_argument("--duration", help="target duration (seconds or mm:ss)")
+    d.add_argument("--method", choices=["speed", "trim"], default="speed", help="how to reach the duration (default speed)")
+    d.add_argument("--from-center", action="store_true", help="with --method trim, keep the middle instead of the start")
+    d.add_argument("--max-speed", type=float, default=4.0, help="refuse speed factors above this (default 4x)")
+    a = ap.add_argument_group("aspect")
+    a.add_argument("--aspect", help="target aspect ratio, e.g. 16:9, 9:16, 1:1, 4:5")
+    a.add_argument("--fit", choices=["pad", "crop"], default="pad", help="pad (letterbox) or crop to reach the aspect (default pad)")
+    a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect)")
+    a.add_argument("--pad-color", default="black", help="pad colour, e.g. black, white, 0x101010 (default black)")
+    e = ap.add_argument_group("encoding")
+    e.add_argument("--crf", type=int, default=18)
+    e.add_argument("--preset", default="medium")
+    e.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
+    args = ap.parse_args()
+
+    if not args.duration and not args.aspect and not args.width and not args.fps:
+        die("nothing to do: give --duration, --aspect, --width and/or --fps")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    src_dur = meta["duration"] or 0.0
+    sw, sh = meta["video"]["width"], meta["video"]["height"]
+    if meta["video"].get("rotation") in (90, -90, 270, -270):
+        sw, sh = sh, sw
+    has_audio = bool(meta.get("audio"))
+
+    vf: List[str] = []
+    af: List[str] = []
+    pre_input: List[str] = []
+    post: List[str] = []
+    factor = 1.0
+
+    # ---- duration
+    if args.duration:
+        target = parse_time(args.duration)
+        if target <= 0:
+            die("target duration must be > 0")
+        if args.method == "speed":
+            factor = src_dur / target  # >1 = speed up
+            if factor > args.max_speed or factor < 1 / args.max_speed:
+                die(f"required speed factor {factor:.2f}x exceeds --max-speed {args.max_speed}x; use --method trim or raise the limit")
+            if abs(factor - 1.0) > 1e-4:
+                vf.append(f"setpts={1/factor:.8f}*PTS")
+                if has_audio:
+                    af.append(atempo_chain(factor))
+            post += ["-t", f"{target:.3f}"]
+        else:
+            if target < src_dur:
+                start = (src_dur - target) / 2 if args.from_center else 0.0
+                pre_input += ["-ss", f"{start:.3f}"]
+                post += ["-t", f"{target:.3f}"]
+            else:
+                info(f"source ({src_dur:.2f}s) is already shorter than {target:.2f}s; trim does nothing")
+
+    # ---- aspect / size
+    if args.aspect or args.width:
+        src_ratio = Fraction(sw, sh)
+        ratio = parse_aspect(args.aspect) if args.aspect else src_ratio
+        if args.width:
+            out_w = even(args.width)
+        else:
+            out_w = even(sw if ratio <= src_ratio else sh * ratio)
+        out_h = even(out_w / ratio)
+        if args.fit == "crop":
+            vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")
+            vf.append(f"crop={out_w}:{out_h}")
+        else:
+            vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease")
+            vf.append(f"pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}")
+        vf.append("setsar=1")
+
+    if args.fps:
+        vf.append(f"fps={args.fps:g}")
+
+    output = args.output or default_output(args.input, "fit")
+    cmd = ffmpeg_base() + pre_input + ["-i", args.input]
+    if vf:
+        cmd += ["-vf", ",".join(vf)]
+    if af:
+        cmd += ["-af", ",".join(af)]
+    cmd += x264_args(args.crf, args.preset)
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    cmd += post + [output]
+    run(cmd)
+
+    result = probe(output)
+    msg = f"wrote {output} ({result['duration']:.3f}s, {result['video']['width']}x{result['video']['height']})"
+    if abs(factor - 1.0) > 1e-4:
+        msg += f", speed {factor:.3f}x"
+    info(msg)
+    print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/loudness.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Two-pass EBU R128 loudness normalisation (ffmpeg loudnorm).
+
+Pass 1 measures integrated loudness, true peak, LRA and threshold; pass 2
+applies loudnorm in linear mode with those measurements so the result hits
+the target without the pumping of single-pass mode. Video is stream-copied.
+
+Common targets: -14 LUFS (YouTube/Spotify), -16 (Apple Podcasts), -23 (EBU broadcast).
+
+Examples:
+  python3 loudness.py input.mp4                       # -14 LUFS, -1 dBTP
+  python3 loudness.py podcast.wav -I -16 --tp -1.5 -o podcast_norm.wav
+  python3 loudness.py input.mp4 --measure-only
+"""
+import argparse
+import json
+import os
+import re
+import sys
+
+from _common import AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run
+
+
+
+def measure(path: str, I: float, tp: float, lra: float) -> dict:
+    ffmpeg = require_tool("ffmpeg")
+    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]
+    proc = run(cmd, check=False)
+    m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
+    if proc.returncode != 0 or not m:
+        die(f"loudness measurement failed:\n{proc.stderr.strip()[-1500:]}")
+    data = json.loads(m.group(0))
+    for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset"):
+        if data.get(k) in (None, "-inf", "inf", "nan"):
+            die(f"loudnorm returned unusable value for {k}: {data.get(k)} (silent input?)")
+    return data
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_loudnorm.<ext>)")
+    ap.add_argument("-I", "--lufs", type=float, default=-14.0, help="integrated loudness target in LUFS (default -14)")
+    ap.add_argument("--tp", type=float, default=-1.0, help="true peak ceiling in dBTP (default -1)")
+    ap.add_argument("--lra", type=float, default=11.0, help="loudness range target in LU (default 11)")
+    ap.add_argument("--measure-only", action="store_true", help="print the measured stats as JSON and exit")
+    ap.add_argument("--audio-bitrate", default="192k", help="AAC bitrate when the container is video (default 192k)")
+    ap.add_argument("--sample-rate", type=int, help="output sample rate (default: 48000; loudnorm upsamples internally to 192k)")
+    args = ap.parse_args()
+
+    meta = probe(args.input)
+    if not meta.get("audio"):
+        die("input has no audio stream")
+
+    stats = measure(args.input, args.lufs, args.tp, args.lra)
+    info(f"measured: {float(stats['input_i']):.1f} LUFS, TP {float(stats['input_tp']):.1f} dBTP, LRA {float(stats['input_lra']):.1f} LU")
+    if args.measure_only:
+        print(json.dumps({k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset")}, indent=2))
+        return 0
+
+    output = args.output or default_output(args.input, "loudnorm")
+    af = (
+        f"loudnorm=I={args.lufs}:TP={args.tp}:LRA={args.lra}"
+        f":measured_I={stats['input_i']}:measured_TP={stats['input_tp']}:measured_LRA={stats['input_lra']}"
+        f":measured_thresh={stats['input_thresh']}:offset={stats['target_offset']}:linear=true:print_format=summary"
+    )
+    sr = args.sample_rate or meta["audio"].get("sample_rate") or 48000
+    ext = os.path.splitext(output)[1].lower()
+    cmd = ffmpeg_base() + ["-i", args.input, "-af", af, "-ar", str(sr)]
+    if ext in AUDIO_CODECS or not meta.get("video"):
+        cmd += ["-vn"] + audio_codec_for(output, args.audio_bitrate)
+    else:
+        cmd += ["-map", "0:v:0", "-map", "0:a:0", "-c:v", "copy", "-c:a", "aac", "-b:a", args.audio_bitrate]
+    cmd.append(output)
+    run(cmd)
+
+    after = measure(output, args.lufs, args.tp, args.lra)
+    info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS)")
+    print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/overlay.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Composite a logo/image or a text title onto a video with position, timing,
+opacity and fade in/out.
+
+Positions: top-left, top, top-right, left, center, right, bottom-left, bottom,
+bottom-right, or explicit "X,Y" pixels (negative counts from the far edge).
+
+Examples:
+  python3 overlay.py input.mp4 --image logo.png --position top-right --scale 200 --opacity 0.8
+  python3 overlay.py input.mp4 --image lower_third.png --position bottom-left --start 2 --end 8 --fade 0.5
+  python3 overlay.py input.mp4 --text "Episode 12" --position bottom --font-size 48 --start 1 --end 5 --fade 0.3
+  python3 overlay.py input.mp4 --text "こんにちは" --font-file /path/NotoSansCJK-Bold.ttc --box
+"""
+import argparse
+import sys
+from typing import List, Optional
+
+from _common import aac_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
+
+POS = {
+    "top-left": ("{m}", "{m}"),
+    "top": ("(W-w)/2", "{m}"),
+    "top-right": ("W-w-{m}", "{m}"),
+    "left": ("{m}", "(H-h)/2"),
+    "center": ("(W-w)/2", "(H-h)/2"),
+    "right": ("W-w-{m}", "(H-h)/2"),
+    "bottom-left": ("{m}", "H-h-{m}"),
+    "bottom": ("(W-w)/2", "H-h-{m}"),
+    "bottom-right": ("W-w-{m}", "H-h-{m}"),
+}
+
+
+def position_exprs(pos: str, margin: int, text_mode: bool):
+    if pos in POS:
+        x, y = (e.format(m=margin) for e in POS[pos])
+    else:
+        try:
+            xs, ys = pos.split(",")
+            xv, yv = int(xs), int(ys)
+        except ValueError:
+            die(f"bad --position '{pos}'")
+        x = f"W-w{xv}" if xv < 0 else str(xv)
+        y = f"H-h{yv}" if yv < 0 else str(yv)
+    if text_mode:
+        # drawtext uses w/h for the text box but lower-case main dims differ: W/H -> w/h, w/h -> text_w/text_h
+        x = x.replace("W", "main_w").replace("w", "text_w").replace("H", "main_h").replace("h", "text_h")
+        y = y.replace("W", "main_w").replace("w", "text_w").replace("H", "main_h").replace("h", "text_h")
+        x = x.replace("main_text_w", "main_w").replace("main_text_h", "main_h")
+        y = y.replace("main_text_w", "main_w").replace("main_text_h", "main_h")
+    return x, y
+
+
+def enable_expr(start: Optional[float], end: Optional[float]) -> str:
+    if start is None and end is None:
+        return ""
+    s = f"{start:.3f}" if start is not None else "0"
+    if end is None:
+        return f"gte(t,{s})"
+    return f"between(t,{s},{end:.3f})"
+
+
+def alpha_expr(opacity: float, start: Optional[float], end: Optional[float], fade: float) -> str:
+    """Time-varying alpha with linear fade in/out inside [start, end]."""
+    if fade <= 0 or (start is None and end is None):
+        return f"{opacity:g}"
+    s = start if start is not None else 0.0
+    parts = [f"{opacity:g}"]
+    fin = f"min(1,(t-{s:.3f})/{fade:g})"
+    parts.append(fin)
+    if end is not None:
+        parts.append(f"min(1,({end:.3f}-t)/{fade:g})")
+    return "max(0," + "*".join(parts) + ")"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_overlay.<ext>)")
+    src = ap.add_mutually_exclusive_group(required=True)
+    src.add_argument("--image", help="PNG/JPG (alpha respected) to composite")
+    src.add_argument("--text", help="text to draw (drawtext)")
+    ap.add_argument("--position", default="top-right", help="named position or X,Y (default top-right)")
+    ap.add_argument("--margin", type=int, default=24, help="margin from the edges in px (default 24)")
+    ap.add_argument("--start", help="show from this time (default: whole video)")
+    ap.add_argument("--end", help="hide after this time")
+    ap.add_argument("--fade", type=float, default=0.0, help="fade in/out duration in seconds")
+    ap.add_argument("--opacity", type=float, default=1.0, help="0..1 (default 1)")
+    img = ap.add_argument_group("image options")
+    img.add_argument("--scale", type=int, help="scale the image to this width in px (keeps aspect)")
+    img.add_argument("--scale-percent", type=float, help="scale the image to this %% of the video width")
+    txt = ap.add_argument_group("text options")
+    txt.add_argument("--font", default="DejaVu Sans", help="fontconfig font name")
+    txt.add_argument("--font-file", help="explicit .ttf/.otf/.ttc path (use this for CJK fonts)")
+    txt.add_argument("--font-size", type=int, default=42)
+    txt.add_argument("--font-color", default="white")
+    txt.add_argument("--border", type=int, default=2, help="text outline width (default 2)")
+    txt.add_argument("--border-color", default="black")
+    txt.add_argument("--box", action="store_true", help="draw a translucent box behind the text")
+    txt.add_argument("--box-color", default="black@0.5")
+    enc = ap.add_argument_group("encoding")
+    enc.add_argument("--crf", type=int, default=18)
+    enc.add_argument("--preset", default="medium")
+    args = ap.parse_args()
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    vw = meta["video"]["width"]
+    start = parse_time(args.start) if args.start else None
+    end = parse_time(args.end) if args.end else None
+    if start is not None and end is not None and end <= start:
+        die("--end must be after --start")
+    if not 0 <= args.opacity <= 1:
+        die("--opacity must be within 0..1")
+
+    output = args.output or default_output(args.input, "overlay")
+    enable = enable_expr(start, end)
+    cmd = ffmpeg_base() + ["-i", args.input]
+
+    if args.image:
+        probe(args.image)
+        chain: List[str] = ["format=rgba"]
+        if args.scale_percent:
+            chain.append(f"scale={int(vw * args.scale_percent / 100)}:-1")
+        elif args.scale:
+            chain.append(f"scale={args.scale}:-1")
+        if args.opacity < 1:
+            chain.append(f"colorchannelmixer=aa={args.opacity:g}")
+        if args.fade > 0 and (start is not None or end is not None):
+            s = start if start is not None else 0.0
+            chain.append(f"fade=t=in:st={s:.3f}:d={args.fade:g}:alpha=1")
+            if end is not None:
+                chain.append(f"fade=t=out:st={end - args.fade:.3f}:d={args.fade:g}:alpha=1")
+        x, y = position_exprs(args.position, args.margin, text_mode=False)
+        ov = f"overlay={x}:{y}:format=auto"
+        if enable:
+            ov += f":enable='{enable}'"
+        # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
+        cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", "-i", args.image]
+        fc = f"[1:v]{','.join(chain)},setpts=PTS-STARTPTS[ov];[0:v][ov]{ov}[out]"
+        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", "0:a?", "-shortest"]
+    else:
+        x, y = position_exprs(args.position, args.margin, text_mode=True)
+        opts = [f"text='{escape_drawtext(args.text)}'", f"fontsize={args.font_size}", f"x={x}", f"y={y}",
+                f"borderw={args.border}", f"bordercolor={args.border_color}"]
+        if args.font_file:
+            opts.append(f"fontfile={escape_filter_path(args.font_file)}")
+        else:
+            opts.append(f"font='{args.font}'")
+        alpha = alpha_expr(args.opacity, start, end, args.fade)
+        opts.append(f"fontcolor={args.font_color}")
+        if alpha != "1":
+            opts.append(f"alpha='{alpha}'")
+        if args.box:
+            opts += ["box=1", f"boxcolor={args.box_color}", "boxborderw=12"]
+        if enable:
+            opts.append(f"enable='{enable}'")
+        cmd += ["-vf", "drawtext=" + ":".join(opts)]
+
+    cmd += x264_args(args.crf, args.preset)
+    cmd += aac_args() if meta.get("audio") else ["-an"]
+    cmd.append(output)
+    run(cmd)
+    result = probe(output)
+    info(f"wrote {output} ({result['duration']:.3f}s)")
+    print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/probe.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Inspect a media file and print a compact JSON summary.
+
+Reports duration, fps (and whether variable frame rate is suspected), resolution,
+codecs, pixel format / color space, audio channels and sample rate.
+
+Examples:
+  python3 probe.py input.mp4
+  python3 probe.py a.mp4 b.mov --compact
+  python3 probe.py input.mp4 --field duration
+"""
+import argparse
+import sys
+
+from _common import print_json, probe
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("inputs", nargs="+", help="media file(s) to inspect")
+    ap.add_argument("--compact", action="store_true", help="one human-readable line per file instead of JSON")
+    ap.add_argument("--field", help="print only this top-level field (e.g. duration) or dotted path (video.fps)")
+    args = ap.parse_args()
+
+    results = [probe(p) for p in args.inputs]
+
+    if args.field:
+        for r in results:
+            cur = r
+            for key in args.field.split("."):
+                cur = cur.get(key) if isinstance(cur, dict) else None
+            print(cur if cur is not None else "")
+        return 0
+
+    if args.compact:
+        for r in results:
+            v, a = r.get("video") or {}, r.get("audio") or {}
+            dur = r.get("duration")
+            line = f"{r['file']}: {dur:.3f}s" if dur is not None else f"{r['file']}: ?s"
+            if v:
+                line += f" | {v.get('width')}x{v.get('height')} @ {v.get('fps')}fps {v.get('codec')} {v.get('pix_fmt')}"
+                if v.get("variable_frame_rate_suspected"):
+                    line += " (VFR?)"
+            else:
+                line += " | no video"
+            if a:
+                line += f" | audio {a.get('codec')} {a.get('channels')}ch {a.get('sample_rate')}Hz"
+            else:
+                line += " | no audio"
+            print(line)
+        return 0
+
+    print_json(results[0] if len(results) == 1 else results)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())