ffmpeg-skill 0.1.0 → 0.3.0

package/scripts/caption.py

@@ -11,6 +11,7 @@ Text-to-SRT input format (one cue per line, blank lines ignored):
 
 Examples:
   python3 caption.py input.mp4 --srt subs.srt
+  python3 caption.py input.mp4 --text cues.txt --animate pop --karaoke        # word-by-word highlight, TikTok style
   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
@@ -21,7 +22,7 @@ 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
+from _common import add_common, apply_common, emit, aac_args, cfr_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}
 
@@ -58,12 +59,84 @@ def parse_text_cues(path: str, auto_seconds: float, gap: float) -> List[Tuple[fl
     return cues
 
 
+def parse_srt(path: str) -> List[Tuple[float, float, str]]:
+    cues: List[Tuple[float, float, str]] = []
+    block: List[str] = []
+    with open(path, encoding="utf-8-sig") as fh:
+        content = fh.read().replace("\r\n", "\n") + "\n\n"
+    for line in content.split("\n"):
+        if line.strip():
+            block.append(line)
+            continue
+        if block:
+            times = next((b for b in block if "-->" in b), None)
+            if times:
+                a, b = times.split("-->")
+                text = "\n".join(block[block.index(times) + 1:]).strip()
+                cues.append((parse_time(a), parse_time(b), text))
+            block = []
+    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 write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int, play_h: int) -> None:
+    """Write a styled ASS file with optional animation and word-by-word highlight."""
+    def t(sec: float) -> str:
+        cs = int(round(sec * 100))
+        h, rem = divmod(cs, 360000)
+        m, rem = divmod(rem, 6000)
+        s_, cs = divmod(rem, 100)
+        return f"{h}:{m:02d}:{s_:02d}.{cs:02d}"
+
+    scale = play_h / 288.0  # our --size is relative to a 288-line script like force_style
+    size = int(round(args.size * scale))
+    margin = int(round(args.margin * scale))
+    # karaoke: PrimaryColour is the "sung" colour, SecondaryColour the "not yet sung" one
+    primary = ass_color(args.highlight_color if args.karaoke else args.color)
+    secondary = ass_color(args.color)
+    outline = ass_color(args.outline_color)
+    back = ass_color(args.outline_color, 0x80)
+    header = [
+        "[Script Info]", "ScriptType: v4.00+", f"PlayResX: {play_w}", f"PlayResY: {play_h}", "WrapStyle: 0", "ScaledBorderAndShadow: yes", "",
+        "[V4+ Styles]",
+        "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
+        f"Style: Default,{args.font},{size},{primary},{secondary},{outline},{back},{-1 if args.bold else 0},0,0,0,100,100,0,0,{3 if args.box else 1},{args.outline * scale:.1f},{args.shadow * scale:.1f},{ALIGN[args.position]},{margin},{margin},{margin},1",
+        "", "[Events]", "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
+    ]
+    lines = []
+    for start, end, text in cues:
+        text = text.replace("\n", "\\N")
+        fx = ""
+        if args.animate == "fade":
+            fx = "{\\fad(200,200)}"
+        elif args.animate == "pop":
+            fx = "{\\fad(80,120)\\fscx60\\fscy60\\t(0,120,\\fscx110\\fscy110)\\t(120,200,\\fscx100\\fscy100)}"
+        elif args.animate == "slide":
+            fx = "{\\fad(150,150)\\move(%d,%d,%d,%d,0,250)}" % (play_w // 2, play_h - margin + int(30 * scale), play_w // 2, play_h - margin)
+        body = text
+        if args.karaoke:
+            # split each line into words and give every word an equal share of the cue (\k is in centiseconds)
+            dur_cs = max(1, int(round((end - start) * 100)))
+            segments = body.split("\\N")
+            words = [w for seg in segments for w in seg.split(" ") if w]
+            per = max(1, dur_cs // max(1, len(words)))
+            out_segments = []
+            for seg in segments:
+                ws = [w for w in seg.split(" ") if w]
+                out_segments.append(" ".join(f"{{\\kf{per}}}{w}" for w in ws))
+            body = "\\N".join(out_segments)
+        lines.append(f"Dialogue: 0,{t(start)},{t(end)},Default,,0,0,0,,{fx}{body}")
+    with open(path, "w", encoding="utf-8-sig") as fh:
+        fh.write("\n".join(header + lines) + "\n")
+
+
 def ass_color(hex_rgb: str, alpha: int = 0) -> str:
     h = hex_rgb.lstrip("#")
     if len(h) != 6:
@@ -95,10 +168,17 @@ def main() -> int:
     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")
+    anim = ap.add_argument_group("animation (generates ASS; needs --text or --srt input)")
+    anim.add_argument("--animate", choices=["none", "fade", "pop", "slide"], default="none", help="per-cue entrance animation")
+    anim.add_argument("--karaoke", action="store_true", help="word-by-word highlight (fills from --color to --highlight-color across each cue)")
+    anim.add_argument("--highlight-color", default="FFD200", help="karaoke fill colour RRGGBB (default FFD200)")
+    anim.add_argument("--write-ass", help="where to save the generated ASS (default: next to the output)")
     enc = ap.add_argument_group("encoding")
     enc.add_argument("--crf", type=int, default=18)
     enc.add_argument("--preset", default="medium")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     if not (args.srt or args.ass or args.text):
         die("give one of --srt, --ass or --text")
@@ -115,7 +195,20 @@ def main() -> int:
 
     if not args.input:
         die("input video is required unless you only use --text/--write-srt")
-    probe(args.input)
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+
+    output = args.output or default_output(args.input, "captioned")
+    if (args.animate != "none" or args.karaoke) and not args.ass:
+        cues_for_ass = cues if args.text else parse_srt(srt_path)
+        ass_path = args.write_ass or os.path.splitext(output)[0] + ".ass"
+        w, h = meta["video"]["width"], meta["video"]["height"]
+        if meta["video"].get("rotation") in (90, -90, 270, -270):
+            w, h = h, w
+        write_ass(cues_for_ass, ass_path, args, w, h)
+        info(f"wrote {ass_path} ({len(cues_for_ass)} cues, animate={args.animate}, karaoke={args.karaoke})")
+        args.ass = ass_path
 
     if args.ass:
         if not os.path.exists(args.ass):
@@ -144,12 +237,12 @@ def main() -> int:
         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]
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf] + x264_args(args.crf, args.preset) + cfr_args(meta)
+    cmd += (aac_args() if meta.get("audio") else ["-an"]) + [output]
     run(cmd)
     result = probe(output)
     info(f"wrote {output} ({result.get('duration'):.3f}s)")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/color.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Colour management: convert HDR (HDR10/PQ, HLG, BT.2020) to SDR BT.709 with
+real tone mapping, apply a .cube LUT (Log footage, creative grades), or fix
+wrong colour tags without re-encoding.
+
+Examples:
+  python3 color.py iphone_hdr.mov --to-sdr                       # PQ/HLG -> BT.709 SDR, hable tonemap
+  python3 color.py iphone_hdr.mov --to-sdr --tonemap mobius --peak 1000
+  python3 color.py slog3.mp4 --lut SLog3_to_Rec709.cube            # apply LUT (any Log -> 709 or a look)
+  python3 color.py clip.mp4 --lut look.cube --lut-strength 0.6
+  python3 color.py wrongly_tagged.mp4 --retag bt709                # metadata only, stream copy
+"""
+import argparse
+import os
+import sys
+from typing import List
+
+from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, x264_args
+
+TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
+
+
+def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str:
+    v = meta["video"]
+    trc = v.get("color_transfer") or "smpte2084"
+    prim = v.get("color_primaries") or "bt2020"
+    space = v.get("color_space") or "bt2020nc"
+    # zscale needs explicit input tags when the file lacks them
+    chain: List[str] = [
+        f"zscale=tin={trc}:pin={prim}:min={space}:rin={v.get('color_range') or 'tv'}:t=linear:npl={peak:g}",
+        "format=gbrpf32le",
+        "zscale=p=bt709",
+        f"tonemap=tonemap={tonemap}:desat={desat:g}" + (":peak=%g" % (peak / 100.0) if tonemap in ("bt2390",) else ""),
+        "zscale=t=bt709:m=bt709:r=tv",
+        "format=yuv420p",
+    ]
+    return ",".join(chain)
+
+
+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>_sdr / _lut / _retag)")
+    mode = ap.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--to-sdr", action="store_true", help="tone-map HDR (PQ/HLG/BT.2020) to SDR BT.709")
+    mode.add_argument("--lut", help=".cube LUT to apply (3D)")
+    mode.add_argument("--retag", choices=["bt709", "bt2020-pq", "bt2020-hlg", "bt601"], help="rewrite colour tags only (no re-encode)")
+    ap.add_argument("--tonemap", choices=TONEMAPS, default="hable", help="tone-mapping curve (default hable)")
+    ap.add_argument("--peak", type=float, default=1000.0, help="source peak brightness in nits used for PQ (default 1000)")
+    ap.add_argument("--desat", type=float, default=0.0, help="tonemap desaturation strength (default 0)")
+    ap.add_argument("--lut-strength", type=float, default=1.0, help="blend LUT result with the original, 0..1 (default 1)")
+    ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is not tagged as HDR (treat as PQ)")
+    ap.add_argument("--crf", type=int, default=18)
+    ap.add_argument("--preset", default="medium")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    v = meta["video"]
+    has_audio = bool(meta.get("audio"))
+
+    if args.retag:
+        tags = {
+            "bt709": ["bt709", "bt709", "bt709"],
+            "bt2020-pq": ["bt2020nc", "bt2020", "smpte2084"],
+            "bt2020-hlg": ["bt2020nc", "bt2020", "arib-std-b67"],
+            "bt601": ["smpte170m", "smpte170m", "smpte170m"],
+        }[args.retag]
+        output = args.output or default_output(args.input, "retag")
+        ext = os.path.splitext(output)[1].lower()
+        cmd = ffmpeg_base() + ["-i", args.input, "-map", "0", "-c", "copy",
+               "-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]]
+        if ext in (".mp4", ".mov", ".m4v"):
+            cmd += ["-movflags", "+faststart"]
+        cmd.append(output)
+        proc = run(cmd, check=False)
+        if proc.returncode != 0:
+            # some codecs cannot carry retagged colour info without a bitstream filter; fall back to re-encode
+            info("stream copy could not rewrite tags, re-encoding")
+            cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", "0:a?"] + x264_args(args.crf, args.preset, keep_bt709=False)
+            cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]] + (aac_args() if has_audio else []) + [output]
+            run(cmd)
+        info(f"wrote {output} (tags -> {args.retag})")
+        emit(output)
+        return 0
+
+    if args.to_sdr:
+        if not v.get("hdr") and not args.force:
+            die(f"{args.input} is not tagged as HDR (transfer={v.get('color_transfer')}, primaries={v.get('color_primaries')}). Use --force to tone-map anyway.")
+        vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
+        output = args.output or default_output(args.input, "sdr")
+        tag = "sdr"
+    else:
+        if not os.path.exists(args.lut):
+            die(f"LUT not found: {args.lut}")
+        lut = f"lut3d=file={escape_filter_path(args.lut)}:interp=tetrahedral"
+        if 0 < args.lut_strength < 1:
+            # blend graded and original
+            vf = f"split[o][g];[g]{lut}[g2];[o][g2]blend=all_mode=normal:all_opacity={args.lut_strength:g},format=yuv420p"
+        else:
+            vf = f"{lut},format=yuv420p"
+        output = args.output or default_output(args.input, "lut")
+        tag = "lut"
+
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", "0:a?"]
+    cmd += x264_args(args.crf, args.preset) + cfr_args(meta) + (aac_args() if has_audio else []) + [output]
+    run(cmd)
+    r = probe(output)
+    info(f"wrote {output} ({r['duration']:.3f}s, {r['video']['width']}x{r['video']['height']}, "
+         f"{r['video']['color_transfer']}/{r['video']['color_primaries']}, {tag})")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/cut.py

@@ -16,7 +16,7 @@ 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
+from _common import STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
 
 
 def parse_segments(spec: str) -> List[Tuple[float, float]]:
@@ -37,26 +37,27 @@ def parse_segments(spec: str) -> List[Tuple[float, float]]:
     return segs
 
 
-def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: int, preset: str, tolerance: float = 0.5) -> bool:
+def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: int, preset: str, tolerance: float = 0.5, meta: dict = None) -> bool:
     """Cut one segment. Returns True if the result was re-encoded."""
     dur = end - start
+    meta = meta or probe(src)
     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]
+        cmd += x264_args(crf, preset) + cfr_args(meta) + 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)
+            return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta)
         die(f"ffmpeg failed:\n{proc.stderr.strip()}")
-    if not reencode and tolerance >= 0:
+    if not reencode and tolerance >= 0 and not STATE["dry_run"]:
         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 cut_one(src, start, end, dst, True, crf, preset, tolerance, meta)
     return reencode
 
 
@@ -73,10 +74,15 @@ def main() -> int:
     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")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     meta = probe(args.input)
     total = meta.get("duration") or 0.0
+    if meta.get("video", {}) and meta["video"].get("variable_frame_rate_suspected") and not args.accurate:
+        info("source looks variable-frame-rate; lossless cuts on VFR are unreliable, switching to --accurate")
+        args.accurate = True
 
     if args.segments:
         segments = parse_segments(args.segments)
@@ -104,13 +110,13 @@ def main() -> int:
 
     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)
+        reencoded = cut_one(args.input, segments[0][0], segments[0][1], output, args.accurate, args.crf, args.preset, args.tolerance, meta)
     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)
+                reencoded |= cut_one(args.input, s, e, part, args.accurate, args.crf, args.preset, args.tolerance, meta)
                 parts.append(part)
             listfile = os.path.join(tmp, "list.txt")
             with open(listfile, "w", encoding="utf-8") as fh:
@@ -120,14 +126,14 @@ def main() -> int:
             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]
+                cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile] + x264_args(args.crf, args.preset) + cfr_args(meta) + 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)
+    emit(output)
     return 0
 
 

package/scripts/export.py

@@ -22,7 +22,7 @@ import argparse
 import sys
 from typing import Dict, List
 
-from _common import default_output, die, ffmpeg_base, info, probe, run
+from _common import add_common, apply_common, emit, cfr_args, 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"},
@@ -48,7 +48,9 @@ def main() -> int:
     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")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(args)
 
     if args.list:
         for name, p in PRESETS.items():
@@ -61,6 +63,8 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
+    if meta["video"].get("hdr") and args.preset != "prores":
+        info("warning: source is HDR (%s). This preset outputs SDR BT.709 tags without tone mapping; run color.py --to-sdr first for correct colours." % meta["video"].get("hdr_format"))
     has_audio = bool(meta.get("audio"))
     output = args.output or default_output(args.input, args.preset, p["ext"])
 
@@ -82,7 +86,7 @@ def main() -> int:
         cmd += ["-filter_complex", fc, "-loop", "0", output]
         run(cmd)
         info(f"wrote {output}")
-        print(output)
+        emit(output)
         return 0
 
     if vf:
@@ -91,6 +95,8 @@ def main() -> int:
     if args.crf is not None and "-crf" in video:
         video[video.index("-crf") + 1] = str(args.crf)
     cmd += video
+    if "-r" not in video:
+        cmd += cfr_args(meta)
     if args.preset not in ("prores",):
         cmd += BT709
     if p["ext"] == "mp4":
@@ -104,7 +110,7 @@ def main() -> int:
     result = probe(output)
     v = result["video"]
     info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['codec']})")
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/fit.py

@@ -19,7 +19,7 @@ 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
+from _common import add_common, apply_common, emit, aac_args, cfr_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)}
 
@@ -63,6 +63,8 @@ def main() -> int:
     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)")
+    d.add_argument("--smooth", choices=["none", "blend", "interpolate"], default="none",
+                   help="slow-motion quality: blend (frame blending) or interpolate (motion-compensated, slow but fluid). default none = duplicate frames")
     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)")
@@ -72,7 +74,9 @@ def main() -> int:
     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)")
+    add_common(ap)
     args = ap.parse_args()
+    apply_common(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")
@@ -103,6 +107,12 @@ def main() -> int:
                 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")
+                src_fps = meta["video"].get("fps") or 30.0
+                if factor < 1.0 and args.smooth == "interpolate":
+                    vf.append(f"minterpolate=fps={src_fps:g}:mi_mode=mci:mc_mode=aobmc:me_mode=bidir:vsbmc=1")
+                elif factor < 1.0 and args.smooth == "blend":
+                    vf.append(f"fps={src_fps:g}")
+                    vf.append("tblend=all_mode=average")
                 if has_audio:
                     af.append(atempo_chain(factor))
             post += ["-t", f"{target:.3f}"]
@@ -133,6 +143,8 @@ def main() -> int:
 
     if args.fps:
         vf.append(f"fps={args.fps:g}")
+    elif meta["video"].get("variable_frame_rate_suspected"):
+        info("source looks variable-frame-rate; conforming to constant fps automatically")
 
     output = args.output or default_output(args.input, "fit")
     cmd = ffmpeg_base() + pre_input + ["-i", args.input]
@@ -141,6 +153,7 @@ def main() -> int:
     if af:
         cmd += ["-af", ",".join(af)]
     cmd += x264_args(args.crf, args.preset)
+    cmd += cfr_args(meta, args.fps) if not args.fps else []
     if has_audio:
         cmd += aac_args()
     else:
@@ -153,7 +166,7 @@ def main() -> int:
     if abs(factor - 1.0) > 1e-4:
         msg += f", speed {factor:.3f}x"
     info(msg)
-    print(output)
+    emit(output)
     return 0
 
 

package/scripts/join.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Join clips with transitions, normalising resolution, frame rate and audio
+layout so mismatched sources (phone + camera + screen recording) cut together.
+
+Transitions (xfade): fade, dissolve, wipeleft, wiperight, wipeup, wipedown,
+slideleft, slideright, circleopen, fadeblack, fadewhite, smoothleft, none.
+
+Examples:
+  python3 join.py a.mp4 b.mp4 c.mp4 -o final.mp4                      # 0.5 s crossfade, size/fps from the first clip
+  python3 join.py *.mp4 --transition fadeblack --duration 1 -o reel.mp4
+  python3 join.py a.mov b.mp4 --transition none --width 1920 --height 1080 --fps 30
+"""
+import argparse
+import sys
+from typing import List
+
+from _common import aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, x264_args
+
+TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
+               "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("inputs", nargs="+", help="two or more clips in order")
+    ap.add_argument("-o", "--output", help="output file (default: <first>_joined.mp4)")
+    ap.add_argument("--transition", choices=TRANSITIONS, default="fade", help="transition between clips (default fade)")
+    ap.add_argument("--duration", type=float, default=0.5, help="transition length in seconds (default 0.5)")
+    ap.add_argument("--width", type=int, help="output width (default: first clip)")
+    ap.add_argument("--height", type=int, help="output height (default: first clip)")
+    ap.add_argument("--fps", type=float, help="output frame rate (default: first clip)")
+    ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how clips of another aspect reach the frame (default pad)")
+    ap.add_argument("--pad-color", default="black")
+    ap.add_argument("--crf", type=int, default=18)
+    ap.add_argument("--preset", default="medium")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if len(args.inputs) < 2:
+        die("give at least two clips")
+    metas = [probe(p) for p in args.inputs]
+    for p, m in zip(args.inputs, metas):
+        if not m.get("video"):
+            die(f"{p} has no video stream")
+    first = metas[0]["video"]
+    w = args.width or first["width"]
+    h = args.height or first["height"]
+    if first.get("rotation") in (90, -90, 270, -270) and not (args.width or args.height):
+        w, h = h, w
+    fps = args.fps or first.get("fps") or 30.0
+    fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
+    w, h = w - (w % 2), h - (h % 2)
+    durs = [m.get("duration") or 0.0 for m in metas]
+    d = args.duration if args.transition != "none" else 0.0
+    for p, dur in zip(args.inputs, durs):
+        if d and dur <= d * 2:
+            die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
+
+    cmd = ffmpeg_base()
+    extra_inputs: List[str] = []
+    parts: List[str] = []
+    n = len(args.inputs)
+    for i, (p, m) in enumerate(zip(args.inputs, metas)):
+        cmd += ["-i", p]
+    # silent audio for clips without an audio track
+    audio_src: List[str] = []
+    for i, m in enumerate(metas):
+        if m.get("audio"):
+            audio_src.append(f"{i}:a:0")
+        else:
+            idx = n + len(extra_inputs)
+            extra_inputs += ["-f", "lavfi", "-t", f"{durs[i]:.3f}", "-i", "anullsrc=r=48000:cl=stereo"]
+            audio_src.append(f"{idx}:a:0")
+    cmd += extra_inputs
+
+    if args.fit == "crop":
+        geo = f"scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h}"
+    else:
+        geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
+    for i in range(n):
+        parts.append(f"[{i}:v]{geo},setsar=1,fps={fps:g},format=yuv420p,settb=AVTB[v{i}]")
+        parts.append(f"[{audio_src[i]}]aformat=sample_rates=48000:channel_layouts=stereo,asetpts=PTS-STARTPTS[a{i}]")
+
+    if args.transition == "none":
+        chain = "".join(f"[v{i}][a{i}]" for i in range(n))
+        parts.append(f"{chain}concat=n={n}:v=1:a=1[vout][aout]")
+    else:
+        vprev, aprev = "v0", "a0"
+        offset = 0.0
+        for i in range(1, n):
+            offset += durs[i - 1] - d
+            vout = f"vx{i}" if i < n - 1 else "vout"
+            aout = f"ax{i}" if i < n - 1 else "aout"
+            parts.append(f"[{vprev}][v{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
+            parts.append(f"[{aprev}][a{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
+            vprev, aprev = vout, aout
+
+    output = args.output or default_output(args.inputs[0], "joined", "mp4")
+    cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
+    cmd += x264_args(args.crf, args.preset) + aac_args() + [output]
+    run(cmd)
+    expected = sum(durs) - d * (n - 1)
+    r = probe(output)
+    info(f"wrote {output} ({r['duration']:.3f}s, expected ~{expected:.3f}s, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
+    emit(output, clips=n, transition=args.transition, expected_duration=round(expected, 3))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())