ffmpeg-skill 0.1.0

package/scripts/_common.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""Shared helpers for ffmpeg-skill scripts.
+
+Standard library only. Locates ffmpeg/ffprobe on PATH, runs them with clear
+error reporting, and provides a compact media probe used by every script.
+"""
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from fractions import Fraction
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+INSTALL_HINTS = {
+    "Darwin": "  brew install ffmpeg",
+    "Linux": (
+        "  Debian/Ubuntu: sudo apt install ffmpeg\n"
+        "  Fedora:        sudo dnf install ffmpeg\n"
+        "  Arch:          sudo pacman -S ffmpeg"
+    ),
+    "Windows": (
+        "  winget install Gyan.FFmpeg\n"
+        "  or: choco install ffmpeg\n"
+        "  or download a build from https://ffmpeg.org/download.html and add it to PATH"
+    ),
+}
+
+
+def die(msg: str, code: int = 1) -> "None":
+    sys.stderr.write(f"error: {msg}\n")
+    sys.exit(code)
+
+
+def info(msg: str) -> None:
+    sys.stderr.write(f"{msg}\n")
+
+
+def require_tool(name: str) -> str:
+    """Return the absolute path of ffmpeg/ffprobe or exit with install steps."""
+    path = shutil.which(name)
+    if path:
+        return path
+    system = platform.system()
+    hint = INSTALL_HINTS.get(system, "  See https://ffmpeg.org/download.html")
+    die(
+        f"'{name}' was not found on PATH.\n"
+        f"Install FFmpeg (which includes ffprobe) for {system}:\n{hint}",
+        code=127,
+    )
+    return ""  # unreachable
+
+
+def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:
+    """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True."""
+    if not quiet:
+        info("$ " + " ".join(shell_quote(c) for c in cmd))
+    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    if check and proc.returncode != 0:
+        tail = "\n".join(proc.stderr.strip().splitlines()[-15:])
+        die(f"command failed ({proc.returncode}): {cmd[0]}\n{tail}", code=proc.returncode or 1)
+    return proc
+
+
+def shell_quote(s: str) -> str:
+    if not s or any(ch in s for ch in " \t\"'\;|&<>()[]{}$*?"):
+        return "'" + s.replace("'", "'\\''") + "'"
+    return s
+
+
+def ffmpeg_base(overwrite: bool = True) -> List[str]:
+    cmd = [require_tool("ffmpeg"), "-hide_banner", "-loglevel", "error", "-nostdin"]
+    cmd.append("-y" if overwrite else "-n")
+    return cmd
+
+
+def probe(path: str) -> Dict[str, Any]:
+    """Return a compact, script-friendly description of a media file."""
+    if not os.path.exists(path):
+        die(f"input not found: {path}")
+    ffprobe = require_tool("ffprobe")
+    proc = run(
+        [ffprobe, "-v", "error", "-print_format", "json", "-show_format", "-show_streams", path],
+        quiet=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        die(f"ffprobe failed on {path}:\n{proc.stderr.strip()}")
+    raw = json.loads(proc.stdout or "{}")
+    fmt = raw.get("format", {})
+    streams = raw.get("streams", [])
+    video = next((s for s in streams if s.get("codec_type") == "video" and s.get("disposition", {}).get("attached_pic", 0) == 0), None)
+    audio = next((s for s in streams if s.get("codec_type") == "audio"), None)
+    subs = [s for s in streams if s.get("codec_type") == "subtitle"]
+
+    duration = _to_float(fmt.get("duration"))
+    if duration is None and video:
+        duration = _to_float(video.get("duration"))
+    if duration is None and audio:
+        duration = _to_float(audio.get("duration"))
+
+    out: Dict[str, Any] = {
+        "file": path,
+        "format": fmt.get("format_name"),
+        "duration": duration,
+        "size_bytes": _to_int(fmt.get("size")),
+        "bitrate": _to_int(fmt.get("bit_rate")),
+        "video": None,
+        "audio": None,
+        "subtitle_streams": len(subs),
+    }
+    if video:
+        r_rate = _fraction(video.get("r_frame_rate"))
+        avg_rate = _fraction(video.get("avg_frame_rate"))
+        fps = float(avg_rate) if avg_rate else (float(r_rate) if r_rate else None)
+        vfr = bool(r_rate and avg_rate and abs(float(r_rate) - float(avg_rate)) > 0.01)
+        w, h = _to_int(video.get("width")), _to_int(video.get("height"))
+        rotation = 0
+        for sd in video.get("side_data_list", []) or []:
+            if "rotation" in sd:
+                rotation = int(round(float(sd["rotation"])))
+        if "rotate" in (video.get("tags") or {}):
+            try:
+                rotation = int(video["tags"]["rotate"])
+            except ValueError:
+                pass
+        out["video"] = {
+            "codec": video.get("codec_name"),
+            "profile": video.get("profile"),
+            "width": w,
+            "height": h,
+            "display_aspect": video.get("display_aspect_ratio") or _aspect_string(w, h),
+            "fps": round(fps, 3) if fps else None,
+            "r_frame_rate": video.get("r_frame_rate"),
+            "avg_frame_rate": video.get("avg_frame_rate"),
+            "variable_frame_rate_suspected": vfr,
+            "pix_fmt": video.get("pix_fmt"),
+            "color_space": video.get("color_space"),
+            "color_primaries": video.get("color_primaries"),
+            "color_transfer": video.get("color_transfer"),
+            "color_range": video.get("color_range"),
+            "rotation": rotation,
+            "nb_frames": _to_int(video.get("nb_frames")),
+            "bitrate": _to_int(video.get("bit_rate")),
+        }
+    if audio:
+        out["audio"] = {
+            "codec": audio.get("codec_name"),
+            "channels": _to_int(audio.get("channels")),
+            "channel_layout": audio.get("channel_layout"),
+            "sample_rate": _to_int(audio.get("sample_rate")),
+            "bitrate": _to_int(audio.get("bit_rate")),
+        }
+    return out
+
+
+def default_output(input_path: str, suffix: str, ext: Optional[str] = None) -> str:
+    p = Path(input_path)
+    new_ext = ext if ext else p.suffix.lstrip(".") or "mp4"
+    return str(p.with_name(f"{p.stem}_{suffix}.{new_ext}"))
+
+
+def parse_time(value: str) -> float:
+    """Accept seconds ('12.5'), mm:ss ('1:30'), hh:mm:ss(.ms) ('00:01:30.250') or SRT '00:01:30,250'."""
+    v = value.strip().replace(",", ".")
+    if not v:
+        raise ValueError("empty time")
+    parts = v.split(":")
+    if len(parts) > 3:
+        raise ValueError(f"bad time: {value}")
+    total = 0.0
+    for part in parts:
+        total = total * 60 + float(part)
+    return total
+
+
+def fmt_srt_time(seconds: float) -> str:
+    if seconds < 0:
+        seconds = 0.0
+    ms = int(round(seconds * 1000))
+    h, rem = divmod(ms, 3_600_000)
+    m, rem = divmod(rem, 60_000)
+    s, ms = divmod(rem, 1000)
+    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def escape_filter_path(path: str) -> str:
+    """Escape a path for use inside an ffmpeg filter graph option value."""
+    p = str(Path(path))
+    p = p.replace("\\", "/")
+    p = p.replace(":", "\\:").replace("'", "\\'").replace(",", "\\,").replace("[", "\\[").replace("]", "\\]")
+    return p
+
+
+def escape_drawtext(text: str) -> str:
+    return (
+        text.replace("\\", "\\\\")
+        .replace(":", "\\:")
+        .replace("'", "\\\\\\'")
+        .replace("%", "\\%")
+        .replace(",", "\\,")
+        .replace("[", "\\[")
+        .replace("]", "\\]")
+    )
+
+
+def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) -> List[str]:
+    args = ["-c:v", "libx264", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
+    if keep_bt709:
+        args += ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
+    return args
+
+
+def aac_args(bitrate: str = "192k") -> List[str]:
+    return ["-c:a", "aac", "-b:a", bitrate]
+
+
+AUDIO_CODECS = {
+    ".wav": ["-c:a", "pcm_s16le"],
+    ".flac": ["-c:a", "flac"],
+    ".mp3": ["-c:a", "libmp3lame", "-q:a", "0"],
+    ".m4a": ["-c:a", "aac", "-b:a", "256k"],
+    ".aac": ["-c:a", "aac", "-b:a", "256k"],
+    ".ogg": ["-c:a", "libvorbis", "-q:a", "6"],
+    ".opus": ["-c:a", "libopus", "-b:a", "128k"],
+}
+
+
+def audio_codec_for(output_path: str, default_bitrate: str = "192k") -> List[str]:
+    """Pick an audio codec that the output container can actually hold."""
+    ext = os.path.splitext(output_path)[1].lower()
+    return list(AUDIO_CODECS.get(ext, ["-c:a", "aac", "-b:a", default_bitrate]))
+
+
+def print_json(obj: Any) -> None:
+    sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
+
+
+def _to_float(v: Any) -> Optional[float]:
+    try:
+        return float(v) if v is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _to_int(v: Any) -> Optional[int]:
+    try:
+        return int(v) if v is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _fraction(v: Optional[str]) -> Optional[Fraction]:
+    if not v or v in ("0/0", "0"):
+        return None
+    try:
+        f = Fraction(v)
+        return f if f > 0 else None
+    except (ValueError, ZeroDivisionError):
+        return None
+
+
+def _aspect_string(w: Optional[int], h: Optional[int]) -> Optional[str]:
+    if not w or not h:
+        return None
+    f = Fraction(w, h)
+    return f"{f.numerator}:{f.denominator}"

package/scripts/caption.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Burn SRT/ASS subtitles into a video, or generate an SRT from plain text.
+
+Styling (font, size, colour, outline, position) applies to SRT input via
+libass force_style. ASS files carry their own styles and are rendered as-is.
+
+Text-to-SRT input format (one cue per line, blank lines ignored):
+  0:00-0:03 Hello and welcome
+  00:00:03.500 --> 00:00:06 Second line | with a manual line break
+  Text without a time is auto-timed after the previous cue (--auto-seconds)
+
+Examples:
+  python3 caption.py input.mp4 --srt subs.srt
+  python3 caption.py input.mp4 --srt subs.srt --font "Noto Sans CJK JP" --size 28 --position top
+  python3 caption.py --text cues.txt --write-srt cues.srt          # only produce the SRT
+  python3 caption.py input.mp4 --text cues.txt                     # generate + burn in one go
+"""
+import argparse
+import os
+import re
+import sys
+from typing import List, Tuple
+
+from _common import aac_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
+
+ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
+
+TIME_RE = re.compile(
+    r"^\s*(?P<a>[\d:.,]+)\s*(?:-->|-|–|to)\s*(?P<b>[\d:.,]+)\s+(?P<text>.+)$"
+)
+
+
+def parse_text_cues(path: str, auto_seconds: float, gap: float) -> List[Tuple[float, float, str]]:
+    cues: List[Tuple[float, float, str]] = []
+    cursor = 0.0
+    with open(path, encoding="utf-8") as fh:
+        for raw in fh:
+            line = raw.rstrip("\n")
+            if not line.strip():
+                continue
+            m = TIME_RE.match(line)
+            if m:
+                try:
+                    start, end = parse_time(m.group("a")), parse_time(m.group("b"))
+                except ValueError:
+                    start, end, text = cursor, cursor + auto_seconds, line.strip()
+                else:
+                    text = m.group("text").strip()
+            else:
+                start, end, text = cursor, cursor + auto_seconds, line.strip()
+            if end <= start:
+                die(f"cue '{line}': end must be after start")
+            text = text.replace(" | ", "\n").replace("|", "\n")
+            cues.append((start, end, text))
+            cursor = end + gap
+    if not cues:
+        die(f"no cues found in {path}")
+    return cues
+
+
+def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
+    with open(path, "w", encoding="utf-8") as fh:
+        for i, (s, e, t) in enumerate(cues, 1):
+            fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
+
+
+def ass_color(hex_rgb: str, alpha: int = 0) -> str:
+    h = hex_rgb.lstrip("#")
+    if len(h) != 6:
+        die(f"colour must be RRGGBB hex, got '{hex_rgb}'")
+    r, g, b = h[0:2], h[2:4], h[4:6]
+    return f"&H{alpha:02X}{b}{g}{r}".upper()
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input", nargs="?", help="video to burn captions into (omit with --write-srt to only generate)")
+    ap.add_argument("-o", "--output", help="output video (default: <name>_captioned.<ext>)")
+    src = ap.add_argument_group("subtitle source")
+    src.add_argument("--srt", help="SRT file to burn")
+    src.add_argument("--ass", help="ASS file to burn (styles inside the file are used)")
+    src.add_argument("--text", help="plain text cue file to convert into SRT (see format above)")
+    src.add_argument("--write-srt", help="where to save the generated SRT (default: <text>.srt)")
+    src.add_argument("--auto-seconds", type=float, default=3.0, help="duration for cues without timing (default 3)")
+    src.add_argument("--gap", type=float, default=0.0, help="gap after auto-timed cues in seconds")
+    sty = ap.add_argument_group("style (SRT only)")
+    sty.add_argument("--font", default="DejaVu Sans", help="font family, e.g. 'Noto Sans CJK JP' for Japanese")
+    sty.add_argument("--fonts-dir", help="directory with extra .ttf/.otf files")
+    sty.add_argument("--size", type=int, default=24, help="font size in ASS points (relative to a 288p script height, scales automatically)")
+    sty.add_argument("--color", default="FFFFFF", help="text colour RRGGBB (default FFFFFF)")
+    sty.add_argument("--outline-color", default="000000", help="outline colour RRGGBB")
+    sty.add_argument("--outline", type=float, default=2.0, help="outline width (default 2)")
+    sty.add_argument("--shadow", type=float, default=0.0, help="shadow depth (default 0)")
+    sty.add_argument("--bold", action="store_true")
+    sty.add_argument("--position", choices=sorted(ALIGN), default="bottom", help="on-screen placement (default bottom)")
+    sty.add_argument("--margin", type=int, default=30, help="vertical margin from the edge (default 30)")
+    sty.add_argument("--box", action="store_true", help="draw an opaque box behind text instead of an outline")
+    enc = ap.add_argument_group("encoding")
+    enc.add_argument("--crf", type=int, default=18)
+    enc.add_argument("--preset", default="medium")
+    args = ap.parse_args()
+
+    if not (args.srt or args.ass or args.text):
+        die("give one of --srt, --ass or --text")
+
+    srt_path = args.srt
+    if args.text:
+        cues = parse_text_cues(args.text, args.auto_seconds, args.gap)
+        srt_path = args.write_srt or os.path.splitext(args.text)[0] + ".srt"
+        write_srt(cues, srt_path)
+        info(f"wrote {srt_path} ({len(cues)} cues)")
+        if not args.input:
+            print(srt_path)
+            return 0
+
+    if not args.input:
+        die("input video is required unless you only use --text/--write-srt")
+    probe(args.input)
+
+    if args.ass:
+        if not os.path.exists(args.ass):
+            die(f"ASS file not found: {args.ass}")
+        vf = f"ass={escape_filter_path(args.ass)}"
+        if args.fonts_dir:
+            vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
+    else:
+        if not srt_path or not os.path.exists(srt_path):
+            die(f"SRT file not found: {srt_path}")
+        style = [
+            f"FontName={args.font}",
+            f"FontSize={args.size}",
+            f"PrimaryColour={ass_color(args.color)}",
+            f"OutlineColour={ass_color(args.outline_color)}",
+            f"BackColour={ass_color(args.outline_color, 0x80)}",
+            f"BorderStyle={3 if args.box else 1}",
+            f"Outline={args.outline:g}",
+            f"Shadow={args.shadow:g}",
+            f"Bold={-1 if args.bold else 0}",
+            f"Alignment={ALIGN[args.position]}",
+            f"MarginV={args.margin}",
+        ]
+        force = ",".join(style).replace("\\", "\\\\").replace("'", "\\'")
+        vf = f"subtitles={escape_filter_path(srt_path)}:force_style='{force}'"
+        if args.fonts_dir:
+            vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
+
+    output = args.output or default_output(args.input, "captioned")
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf] + x264_args(args.crf, args.preset) + aac_args() + [output]
+    run(cmd)
+    result = probe(output)
+    info(f"wrote {output} ({result.get('duration'):.3f}s)")
+    print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/cut.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Cut a clip or several segments out of a video and (optionally) join them.
+
+Lossless stream copy (-c copy) is preferred. Cuts snap to keyframes in that
+mode, so if frame accuracy matters pass --accurate to re-encode. Multiple
+segments are cut individually and concatenated with the concat demuxer.
+
+Examples:
+  python3 cut.py input.mp4 --start 00:00:10 --end 00:00:25
+  python3 cut.py input.mp4 --segments 0:05-0:12,1:00-1:20 -o highlights.mp4
+  python3 cut.py input.mp4 --start 3.5 --duration 10 --accurate
+"""
+import argparse
+import os
+import sys
+import tempfile
+from typing import List, Tuple
+
+from _common import aac_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+
+
+def parse_segments(spec: str) -> List[Tuple[float, float]]:
+    segs = []
+    for raw in spec.split(","):
+        raw = raw.strip()
+        if not raw:
+            continue
+        if "-" not in raw:
+            die(f"segment '{raw}' must look like START-END (e.g. 0:05-0:12)")
+        a, b = raw.rsplit("-", 1)
+        start, end = parse_time(a), parse_time(b)
+        if end <= start:
+            die(f"segment '{raw}': end must be after start")
+        segs.append((start, end))
+    if not segs:
+        die("no segments given")
+    return segs
+
+
+def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: int, preset: str, tolerance: float = 0.5) -> bool:
+    """Cut one segment. Returns True if the result was re-encoded."""
+    dur = end - start
+    if reencode:
+        cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}"]
+        cmd += x264_args(crf, preset) + aac_args() + ["-avoid_negative_ts", "make_zero", dst]
+    else:
+        cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}", "-c", "copy", "-avoid_negative_ts", "make_zero", dst]
+    proc = run(cmd, check=False)
+    if proc.returncode != 0:
+        if not reencode:
+            info("stream copy failed, falling back to re-encode")
+            return cut_one(src, start, end, dst, True, crf, preset, tolerance)
+        die(f"ffmpeg failed:\n{proc.stderr.strip()}")
+    if not reencode and tolerance >= 0:
+        got = probe(dst).get("duration") or 0.0
+        if abs(got - dur) > tolerance:
+            info(f"stream copy landed on a keyframe {abs(got - dur):.2f}s away from the requested cut "
+                 f"(> {tolerance:.2f}s tolerance); re-encoding this segment for accuracy")
+            return cut_one(src, start, end, dst, True, crf, preset, tolerance)
+    return reencode
+
+
+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>_cut.<ext>)")
+    g = ap.add_argument_group("range (single segment)")
+    g.add_argument("--start", default="0", help="start time (seconds, mm:ss or hh:mm:ss.ms). default 0")
+    g.add_argument("--end", help="end time")
+    g.add_argument("--duration", help="duration instead of --end")
+    ap.add_argument("--segments", help="comma separated START-END list, e.g. '0:05-0:12,1:00-1:20' (joined in order)")
+    ap.add_argument("--accurate", action="store_true", help="always re-encode for frame-accurate cuts (default: lossless -c copy, re-encoding only when the keyframe snap exceeds --tolerance)")
+    ap.add_argument("--tolerance", type=float, default=0.5, help="max seconds a lossless cut may deviate before re-encoding kicks in (default 0.5, -1 = never)")
+    ap.add_argument("--crf", type=int, default=18, help="x264 CRF when re-encoding (default 18)")
+    ap.add_argument("--preset", default="medium", help="x264 preset when re-encoding")
+    args = ap.parse_args()
+
+    meta = probe(args.input)
+    total = meta.get("duration") or 0.0
+
+    if args.segments:
+        segments = parse_segments(args.segments)
+    else:
+        start = parse_time(args.start)
+        if args.end and args.duration:
+            die("use --end or --duration, not both")
+        if args.end:
+            end = parse_time(args.end)
+        elif args.duration:
+            end = start + parse_time(args.duration)
+        else:
+            end = total
+        if end <= start:
+            die("end must be after start")
+        segments = [(start, end)]
+
+    for s, e in segments:
+        if total and s >= total:
+            die(f"segment start {s:.3f}s is beyond the media duration {total:.3f}s")
+    segments = [(s, min(e, total) if total else e) for s, e in segments]
+
+    output = args.output or default_output(args.input, "cut")
+    ext = os.path.splitext(output)[1] or ".mp4"
+
+    reencoded = False
+    if len(segments) == 1:
+        reencoded = cut_one(args.input, segments[0][0], segments[0][1], output, args.accurate, args.crf, args.preset, args.tolerance)
+    else:
+        with tempfile.TemporaryDirectory(prefix="ffskill_cut_") as tmp:
+            parts = []
+            for i, (s, e) in enumerate(segments):
+                part = os.path.join(tmp, f"part{i:03d}{ext}")
+                reencoded |= cut_one(args.input, s, e, part, args.accurate, args.crf, args.preset, args.tolerance)
+                parts.append(part)
+            listfile = os.path.join(tmp, "list.txt")
+            with open(listfile, "w", encoding="utf-8") as fh:
+                for p in parts:
+                    fh.write("file '" + p.replace("'", "'\\''") + "'\n")
+            cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile, "-c", "copy", output]
+            proc = run(cmd, check=False)
+            if proc.returncode != 0:
+                info("concat with stream copy failed, re-encoding the join")
+                cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile] + x264_args(args.crf, args.preset) + aac_args() + [output]
+                run(cmd)
+
+    result = probe(output)
+    expected = sum(e - s for s, e in segments)
+    info(f"wrote {output} ({result.get('duration'):.3f}s, expected ~{expected:.3f}s, "
+         + ("re-encoded" if reencoded else "lossless stream copy") + ")")
+    print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/export.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Export with delivery presets. Scales/pads to the preset's frame (keeping
+the source aspect inside it), constrains duration where the platform does,
+sets BT.709 tags, and picks sensible codecs/bitrates.
+
+Presets:
+  youtube   1920x1080 H.264 CRF 18 high profile, AAC 192k, 48 kHz, faststart
+  youtube4k 3840x2160 H.264 CRF 18, AAC 192k
+  reels     1080x1920 9:16 H.264 CRF 20, AAC 128k, max 90 s (also Shorts/TikTok)
+  x         1280x720 H.264 CRF 22, AAC 128k, max 140 s (Twitter/X)
+  prores    ProRes 422 HQ .mov, PCM 16-bit audio (editing master)
+  h265      HEVC CRF 24 (libx265) with hvc1 tag for Apple compatibility
+  gif       480px wide palette-optimised GIF at 12 fps (short previews)
+
+Examples:
+  python3 export.py final.mp4 --preset youtube
+  python3 export.py final.mp4 --preset reels --fit crop
+  python3 export.py final.mp4 --preset prores -o master.mov
+  python3 export.py --list
+"""
+import argparse
+import sys
+from typing import Dict, List
+
+from _common import default_output, die, ffmpeg_base, info, probe, run
+
+PRESETS: Dict[str, Dict] = {
+    "youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},
+    "youtube4k": {"w": 3840, "h": 2160, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "2160p H.264, AAC 192k"},
+    "reels": {"w": 1080, "h": 1920, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "medium", "-crf", "20", "-profile:v", "high", "-pix_fmt", "yuv420p", "-r", "30"], "audio": ["-c:a", "aac", "-b:a", "128k", "-ar", "48000"], "max": 90.0, "desc": "9:16 1080x1920, 30fps, max 90s (Reels/Shorts/TikTok)"},
+    "x": {"w": 1280, "h": 720, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "medium", "-crf", "22", "-profile:v", "high", "-pix_fmt", "yuv420p", "-r", "30"], "audio": ["-c:a", "aac", "-b:a", "128k", "-ar", "44100"], "max": 140.0, "desc": "720p H.264, max 140s (Twitter/X)"},
+    "prores": {"w": None, "h": None, "ext": "mov", "video": ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"], "audio": ["-c:a", "pcm_s16le"], "max": None, "desc": "ProRes 422 HQ master, PCM audio, source resolution"},
+    "h265": {"w": None, "h": None, "ext": "mp4", "video": ["-c:v", "libx265", "-preset", "medium", "-crf", "24", "-pix_fmt", "yuv420p", "-tag:v", "hvc1"], "audio": ["-c:a", "aac", "-b:a", "160k"], "max": None, "desc": "HEVC CRF 24, hvc1 tag, source resolution"},
+    "gif": {"w": 480, "h": None, "ext": "gif", "video": [], "audio": [], "max": None, "desc": "480px palette GIF, 12fps"},
+}
+
+BT709 = ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input", nargs="?")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_<preset>.<ext>)")
+    ap.add_argument("--preset", choices=sorted(PRESETS), help="delivery preset")
+    ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how to reach the preset frame when aspect differs (default pad)")
+    ap.add_argument("--pad-color", default="black")
+    ap.add_argument("--no-scale", action="store_true", help="keep source resolution even for platform presets")
+    ap.add_argument("--allow-long", action="store_true", help="do not trim to the platform's max duration")
+    ap.add_argument("--crf", type=int, help="override CRF")
+    ap.add_argument("--list", action="store_true", help="list presets and exit")
+    args = ap.parse_args()
+
+    if args.list:
+        for name, p in PRESETS.items():
+            print(f"{name:10s} {p['desc']}")
+        return 0
+    if not args.input or not args.preset:
+        die("input and --preset are required (or use --list)")
+
+    p = PRESETS[args.preset]
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    has_audio = bool(meta.get("audio"))
+    output = args.output or default_output(args.input, args.preset, p["ext"])
+
+    vf: List[str] = []
+    if p["w"] and not args.no_scale:
+        if p["h"]:
+            if args.fit == "crop":
+                vf += [f"scale={p['w']}:{p['h']}:force_original_aspect_ratio=increase", f"crop={p['w']}:{p['h']}"]
+            else:
+                vf += [f"scale={p['w']}:{p['h']}:force_original_aspect_ratio=decrease", f"pad={p['w']}:{p['h']}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"]
+            vf.append("setsar=1")
+        else:
+            vf.append(f"scale={p['w']}:-2")
+    cmd = ffmpeg_base() + ["-i", args.input]
+
+    if args.preset == "gif":
+        chain = ",".join(["fps=12"] + vf) if vf else "fps=12"
+        fc = f"[0:v]{chain},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle"
+        cmd += ["-filter_complex", fc, "-loop", "0", output]
+        run(cmd)
+        info(f"wrote {output}")
+        print(output)
+        return 0
+
+    if vf:
+        cmd += ["-vf", ",".join(vf)]
+    video = list(p["video"])
+    if args.crf is not None and "-crf" in video:
+        video[video.index("-crf") + 1] = str(args.crf)
+    cmd += video
+    if args.preset not in ("prores",):
+        cmd += BT709
+    if p["ext"] == "mp4":
+        cmd += ["-movflags", "+faststart"]
+    cmd += (p["audio"] if has_audio else ["-an"])
+    if p["max"] and not args.allow_long and (meta.get("duration") or 0) > p["max"]:
+        info(f"trimming to the platform maximum of {p['max']:.0f}s (use --allow-long to keep full length)")
+        cmd += ["-t", f"{p['max']:.3f}"]
+    cmd.append(output)
+    run(cmd)
+    result = probe(output)
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['codec']})")
+    print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())