ffmpeg-skill 1.11.1 → 1.13.0

package/scripts/graphics.py

@@ -15,13 +15,14 @@ Examples:
   python3 graphics.py talk.mp4 --template title --title "Episode 12" --subtitle "The math of video" --start 0 --end 4
   python3 graphics.py talk.mp4 --template progress --brand brand.json
   python3 graphics.py intro.mp4 --template countdown --from 5 --start 1 --end 6
+  python3 graphics.py talk.mp4 --template lower-third --name "김민준" --title "감독" --lang ko
   python3 graphics.py clip.mp4 --template chapter --title "Part 2 — Setup" --position top-left --start 0 --end 5
 """
 import argparse
 import sys
 from typing import List, Optional
 
-from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderw, X264_PRESETS, time_arg, fmt_secs
+from _common import aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderw, X264_PRESETS, time_arg, fmt_secs
 
 TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug"]
 
@@ -30,9 +31,11 @@ def ff_color(hex_rgb: str, alpha: float = 1.0) -> str:
     return f"0x{color_hex(hex_rgb)}@{alpha:g}"
 
 
-def font_opts(brand: dict, font: Optional[str], font_file: Optional[str]) -> str:
+def font_opts(brand: dict, font: Optional[str], font_file: Optional[str], script_file: Optional[str] = None) -> str:
     if font_file or brand.get("font_file"):
         return f"fontfile={escape_filter_path(font_file or brand['font_file'])}"
+    if script_file:  # a font picked by the script of the text itself (1.12)
+        return f"fontfile={escape_filter_path(script_file)}"
     resolved = default_font_file(font or brand.get("font", "DejaVu Sans"))
     if resolved:
         return f"fontfile={escape_filter_path(resolved)}"
@@ -60,6 +63,8 @@ def main() -> int:
     ap.add_argument("--text-color", help="override text colour RRGGBB")
     ap.add_argument("--font")
     ap.add_argument("--font-file")
+    ap.add_argument("--lang", help="language code of the text (e.g. ja, zh, ko): the hint that says whether Han-only "
+                                   "text is Chinese, Japanese or Korean when a font is picked by script")
     ap.add_argument("--scale", type=float, default=1.0, help="size multiplier (default 1)")
     ap.add_argument("--crf", type=int, default=18)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
@@ -72,7 +77,17 @@ def main() -> int:
     text_c = color_hex(args.text_color or brand["colors"]["text"])
     bg = color_hex(brand["colors"].get("background", "101418"))
     margin = int(brand.get("safe_margin", 48))
-    fo = font_opts(brand, args.font, args.font_file)
+    style = brand_caption_style(brand)  # styles.caption is shared with caption.py
+    if args.brand and style.get("font") and not args.font:
+        args.font = style["font"]
+    if args.brand and style.get("color") and not args.text_color:
+        text_c = color_hex(style["color"])
+    args.lang = args.lang or (brand.get("lang") if args.brand else None)
+    # a font that covers the text before drawtext renders boxes instead of glyphs (1.12)
+    _script, script_file, _family = script_font_for_text(
+        " ".join(t for t in (args.name, args.title, args.subtitle) if t),
+        lang=args.lang, font=args.font, font_explicit=bool(args.font), font_file=args.font_file or brand.get("font_file"))
+    fo = font_opts(brand, args.font, args.font_file, script_file)
 
     meta = probe(args.input)
     if not meta.get("video"):

package/scripts/loudness.py

@@ -11,6 +11,7 @@ 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
+  python3 loudness.py music.wav --lra 7                 # tighter loudness range target
 """
 import argparse
 import json
@@ -155,6 +156,8 @@ def main() -> int:
             kind="verification", output=output, result=result,
             hint="raise --audio-bitrate (e.g. 256k) or deliver a lossless format (wav/flac) and let the platform encode")
     emit(output, result=result, dropped_non_av_streams=dropped_streams,
+         measured={k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")},
+         targets={"lufs": args.lufs, "tp": args.tp, "lra": args.lra},
          verification=[{"step": "loudness",
                         "ok": bool(after.get("silent")) or (abs(float(after["input_i"]) - args.lufs) <= 1.0 and float(after["input_tp"]) <= args.tp + 0.1),
                         "lufs": float(after["input_i"]), "tp": float(after["input_tp"]), "target_lufs": args.lufs, "target_tp": args.tp}])

package/scripts/overlay.py

@@ -24,7 +24,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
+from _common import STATE, script_font_for_text, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -144,6 +144,14 @@ def main() -> int:
             args.font = brand.get("font", args.font)
         if not args.font_file and brand.get("font_file"):
             args.font_file = brand["font_file"]
+    if args.text and not args.font_file:
+        # 1.12: non-Latin overlay text picks a font by script, so a title in Japanese, Korean,
+        # Arabic ... draws glyphs instead of boxes. drawtext does not shape or reorder RTL text --
+        # see references/gotchas.md#fonts-by-script.
+        _script, script_file, _family = script_font_for_text(
+            args.text, font=args.font, font_explicit=args.font != ap.get_default("font"), font_file=args.font_file)
+        if script_file:
+            args.font_file = script_file
     if not args.font_file:
         args.font_file = default_font_file(args.font)
     meta = probe(args.input)

package/scripts/render.py

@@ -24,15 +24,17 @@ Project format (all keys optional except clips):
     {"logo": true},
     {"text": "Episode 12", "position": "bottom", "start": 1, "end": 5, "fade": 0.3, "box": true}
   ],
-  "audio": {"voice": true, "music": "bed.mp3", "music_volume": -16, "duck": true, "music_fade_out": 2},
+  "audio": {"voice": "medium", "music": "bed.mp3", "music_volume": -16, "duck": true, "music_fade_out": 2,
+            "effects": "sfx.wav", "stems": {"dialogue": 0, "music": -18, "effects": -22}},
   "loudness": {"lufs": -14, "tp": -1},
   "fit": {"duration": 60},
   "export": {"preset": "reels", "normalize": true},   (default for platform presets; false opts out)
-  "check": {"platform": "reels"}
+  "check": {"platform": "reels"},
+  "chapters": "chapters.txt"            (or [{"at": "0:00", "title": "Intro"}, ...])
 }
 
 Stages run in this order: clips (cut) → join → silence → fit → captions →
-graphics → overlays → audio → loudness → export → check. Missing stages are
+graphics → overlays → audio → loudness → export → chapters → check. Missing stages are
 skipped. "brand" points caption/graphics/overlay at a brand.json (fonts,
 colours, logo, safe margin); {"logo": true} in overlays places the brand logo.
 
@@ -76,6 +78,7 @@ TEMPLATE = {
     "loudness": {"lufs": -14, "tp": -1},
     "fit": None,
     "export": {"preset": "youtube", "normalize": True},
+    "chapters": None,
     "check": {"platform": "youtube"},
 }
 
@@ -85,27 +88,33 @@ TEMPLATE = {
 # untrimmed, and a mistyped stage name dropped the stage -- both reported as a success (review 9).
 OBJECT_KEYS: Dict[str, frozenset] = {
     "project": frozenset({"output", "frame", "clips", "transition", "silence", "brand", "captions",
-                          "graphics", "overlays", "audio", "loudness", "fit", "export", "check"}),
+                          "graphics", "overlays", "audio", "loudness", "fit", "export", "check", "chapters"}),
     "clips[]": frozenset({"src", "in", "out", "speed"}),
     "frame": frozenset({"aspect", "width", "height", "fps"}),
     "transition": frozenset({"type", "duration"}),
     "silence": frozenset({"threshold", "min_silence", "margin"}),
     "captions": frozenset({"text", "srt", "ass", "font", "size", "color", "position", "margin",
-                           "animate", "highlight_color", "outline", "karaoke", "bold", "box"}),
+                           "animate", "highlight_color", "outline", "karaoke", "bold", "box",
+                           "lang", "offset", "max_lines", "min_duration"}),
     "graphics[]": frozenset({"template", "name", "title", "subtitle", "start", "end", "position",
-                             "from", "scale", "primary", "text_color"}),
+                             "from", "scale", "primary", "text_color", "lang"}),
     "overlays[]": frozenset({"logo", "image", "text", "position", "start", "end", "fade", "opacity",
                              "scale", "font_size", "font", "font_file", "margin", "box"}),
     "audio": frozenset({"music", "replace", "music_volume", "fade_in", "fade_out", "music_fade_out",
-                        "gain", "duck_amount", "voice", "denoise", "duck", "music_loop", "stereo",
-                        "mono", "downmix"}),
+                        "gain", "duck_amount", "duck_threshold", "duck_attack", "duck_release",
+                        "voice", "denoise", "duck", "music_loop", "stereo", "mono", "downmix",
+                        "stereo_widen", "effects", "effects_volume", "stems"}),
+    "audio.stems": frozenset({"dialogue", "music", "effects"}),
+    "chapters[]": frozenset({"at", "title"}),
     "loudness": frozenset({"lufs", "tp"}),
     "fit": frozenset({"duration", "method", "aspect", "fit", "width", "height", "fps", "smooth"}),
     "export": frozenset({"preset", "fit", "crf", "normalize"}),
     "check": frozenset({"platform"}),
 }
 # Typos difflib cannot see: a clip is trimmed with in/out, not the start/end that time a title.
-NEAR_KEYS: Dict[str, Dict[str, str]] = {"clips[]": {"start": "in", "end": "out", "from": "in", "to": "out"}}
+NEAR_KEYS: Dict[str, Dict[str, str]] = {"clips[]": {"start": "in", "end": "out", "from": "in", "to": "out"},
+                                        "audio.stems": {"voice": "dialogue", "speech": "dialogue", "sfx": "effects", "bed": "music"},
+                                        "chapters[]": {"start": "at", "time": "at", "name": "title"}}
 
 
 def check_keys(obj: Any, schema: str, label: str) -> None:
@@ -125,6 +134,14 @@ def validate_project(proj: Dict[str, Any]) -> None:
     check_keys(proj, "project", "project")
     for name in ("frame", "transition", "silence", "captions", "audio", "loudness", "fit", "export", "check"):
         check_keys(proj.get(name), name, name)
+    check_keys((proj.get("audio") or {}).get("stems"), "audio.stems", "audio.stems")
+    if isinstance(proj.get("chapters"), list):
+        # Every other project error is raised here, before the first ffmpeg call; a chapter typo
+        # found inside the last stage costs a whole render and leaves an unchaptered file behind.
+        for i, item in enumerate(proj["chapters"]):
+            check_keys(item, "chapters[]", f"chapters[{i}]")
+            if not isinstance(item, dict) or item.get("at") is None or not str(item.get("title") or "").strip():
+                die(f'chapters[{i}]: needs {{"at": TIME, "title": STR}}')
     for name in ("clips", "graphics", "overlays"):
         items = proj.get(name)
         if isinstance(items, list):
@@ -286,6 +303,9 @@ def main() -> int:
         p = str(p)
         return p if os.path.isabs(p) else str(base / p)
 
+    if isinstance(proj.get("chapters"), str) and not os.path.exists(rel(proj["chapters"])):
+        die(f"chapters file not found: {rel(proj['chapters'])}")
+
     clips = proj.get("clips") or []
     if not clips:
         die("project.clips is empty")
@@ -418,7 +438,7 @@ def main() -> int:
             argv += ["--ass", rel(cap["ass"])]
         else:
             die("captions needs text, srt or ass")
-        for k, flag in (("font", "--font"), ("size", "--size"), ("color", "--color"), ("position", "--position"), ("margin", "--margin"), ("animate", "--animate"), ("highlight_color", "--highlight-color"), ("outline", "--outline")):
+        for k, flag in (("font", "--font"), ("size", "--size"), ("color", "--color"), ("position", "--position"), ("margin", "--margin"), ("animate", "--animate"), ("highlight_color", "--highlight-color"), ("outline", "--outline"), ("lang", "--lang"), ("offset", "--offset"), ("max_lines", "--max-lines"), ("min_duration", "--min-duration")):
             if cap.get(k) is not None:
                 argv += [flag, str(cap[k])]
         for k, flag in (("karaoke", "--karaoke"), ("bold", "--bold"), ("box", "--box")):
@@ -437,7 +457,7 @@ def main() -> int:
         if not g.get("template"):
             die(f"graphics[{i}] needs a template")
         argv = [current, "-o", nxt, "--template", g["template"]]
-        for k, flag in (("name", "--name"), ("title", "--title"), ("subtitle", "--subtitle"), ("start", "--start"), ("end", "--end"), ("position", "--position"), ("from", "--from"), ("scale", "--scale"), ("primary", "--primary"), ("text_color", "--text-color")):
+        for k, flag in (("name", "--name"), ("title", "--title"), ("subtitle", "--subtitle"), ("start", "--start"), ("end", "--end"), ("position", "--position"), ("from", "--from"), ("scale", "--scale"), ("primary", "--primary"), ("text_color", "--text-color"), ("lang", "--lang")):
             if g.get(k) is not None:
                 argv += [flag, str(g[k])]
         sh("graphics.py", *(argv + brand_args))
@@ -474,17 +494,33 @@ def main() -> int:
         return 0
 
     # ---- audio
-    au = proj.get("audio")
+    au = dict(proj.get("audio") or {})
     if au:
+        # "stems": one level per element of the mix, the way a mixing desk names them. Each maps
+        # to the flag that already exists (dialogue = the main track's gain, music = the bed's
+        # level, effects = the third file's level), so a stems block is a vocabulary, not a
+        # second code path -- and an explicit flag next to it wins, since it is the more specific
+        # statement of the same thing.
+        stems = au.pop("stems", None) or {}
+        if stems.get("effects") is not None and not au.get("effects"):
+            die('audio.stems.effects sets the level of "audio": {"effects": "sfx.wav"}, which this project does not have')
+        if stems.get("music") is not None and not au.get("music"):
+            die('audio.stems.music sets the level of "audio": {"music": "bed.mp3"}, which this project does not have')
+        for stem, key in (("dialogue", "gain"), ("music", "music_volume"), ("effects", "effects_volume")):
+            if stems.get(stem) is not None:
+                au.setdefault(key, stems[stem])
         nxt = str(work / "audio.mp4")
         argv = [current, "-o", nxt]
-        for k, flag in (("music", "--music"), ("replace", "--replace")):
+        for k, flag in (("music", "--music"), ("replace", "--replace"), ("effects", "--effects")):
             if au.get(k):
                 argv += [flag, rel(au[k])]
-        for k, flag in (("music_volume", "--music-volume"), ("fade_in", "--fade-in"), ("fade_out", "--fade-out"), ("music_fade_out", "--music-fade-out"), ("gain", "--gain"), ("duck_amount", "--duck-amount")):
+        for k, flag in (("music_volume", "--music-volume"), ("effects_volume", "--effects-volume"), ("fade_in", "--fade-in"), ("fade_out", "--fade-out"), ("music_fade_out", "--music-fade-out"), ("gain", "--gain"), ("duck_amount", "--duck-amount"), ("duck_threshold", "--duck-threshold"), ("duck_attack", "--duck-attack"), ("duck_release", "--duck-release"), ("stereo_widen", "--stereo-widen")):
             if au.get(k) is not None:
                 argv += [flag, str(au[k])]
-        for k, flag in (("voice", "--voice"), ("denoise", "--denoise"), ("duck", "--duck"), ("music_loop", "--music-loop"), ("stereo", "--stereo"), ("mono", "--mono"), ("downmix", "--downmix")):
+        # "voice": true is the medium chain; "voice": "light"|"medium"|"strong" names one
+        if au.get("voice") is not None and au.get("voice") is not False:
+            argv += ["--voice"] + ([] if au["voice"] is True else [str(au["voice"])])
+        for k, flag in (("denoise", "--denoise"), ("duck", "--duck"), ("music_loop", "--music-loop"), ("stereo", "--stereo"), ("mono", "--mono"), ("downmix", "--downmix")):
             if au.get(k):
                 argv.append(flag)
         sh("audio.py", *argv)
@@ -535,6 +571,24 @@ def main() -> int:
         info(("[dry-run] would copy" if STATE.dry_run else "copied") + f" final stage to {output}")
     current = output
 
+    # ---- chapters (metadata.py on the delivered file: streams copied, markers written)
+    ch = proj.get("chapters")
+    if ch:
+        # Planned exactly like the audio stage: the metadata.py command names the export's output,
+        # which a dry run has not written either. The plan is the run, so --dry-run shows the
+        # command and lists the stage (the child's own --dry-run prints rather than writes).
+        if isinstance(ch, list):
+            chapter_file = str(work / "chapters.txt")
+            lines = [f"{entry['at']} {entry['title']}" for entry in ch]
+            Path(chapter_file).write_text("\n".join(lines) + "\n", encoding="utf-8")
+        else:
+            chapter_file = rel(ch)
+        tagged = str(work / ("chapters" + Path(output).suffix))
+        sh("metadata.py", output, "--chapters", chapter_file, "-o", tagged)
+        if not STATE.dry_run:
+            place_output(tagged, output)
+        stages_done.append("chapters")
+
     # ---- check
     ck = proj.get("check")
     check_result = None