ffmpeg-skill 2.10.5 → 2.10.7

package/bin/install.js

@@ -41,21 +41,39 @@ if (has('--help') || has('-h')) {
   process.exit(0);
 }
 
-// `contract` / `doctor` are answered by scripts/_contract.py; everything else installs.
-if (args[0] === 'contract' || args[0] === 'doctor') {
-  // Windows Python installers commonly expose `python`/`py`, not `python3` (only the
-  // Microsoft Store package does); try python3 first (macOS/Linux convention), then fall
-  // back so `npx ffmpeg-skill doctor` doesn't silently fail with ENOENT on Windows.
-  const candidates = process.platform === 'win32' ? ['python3', 'python', 'py'] : ['python3'];
-  let py;
+// Windows Python installers commonly expose `python`/`py`, not `python3`. The Microsoft Store
+// app-execution alias is a real python3.exe that spawns (no ENOENT) and exits non-zero, so a
+// missing `error` is not proof an interpreter ran. Probe with a version check, then fall through.
+const PYTHON_PROBE = ['-c', 'import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)'];
+
+function pythonCandidates(platform) {
+  return platform === 'win32' ? ['python3', 'python', 'py'] : ['python3'];
+}
+
+function runWithPython(scriptArgs, platform, spawn) {
+  const candidates = pythonCandidates(platform);
+  const run = spawn || spawnSync;
+  let last = null;
   for (const cmd of candidates) {
-    py = spawnSync(cmd, [path.join(ROOT, 'scripts', '_contract.py'), ...args], { stdio: 'inherit' });
-    if (!py.error) break;
+    const probe = run(cmd, PYTHON_PROBE, { stdio: 'ignore', timeout: 15000 });
+    if (probe.error || probe.status !== 0) {
+      last = probe;
+      continue;
+    }
+    return run(cmd, scriptArgs, { stdio: 'inherit' });
   }
-  if (py.error) {
-    console.error(`error: could not find a Python interpreter (tried: ${candidates.join(', ')}). Install Python 3.9+ and ensure it is on PATH.`);
+  return { missing: true, error: last && last.error, status: last && last.status, candidates };
+}
+
+function main() {
+// `contract` / `doctor` are answered by scripts/_contract.py; everything else installs.
+if (args[0] === 'contract' || args[0] === 'doctor') {
+  const py = runWithPython([path.join(ROOT, 'scripts', '_contract.py'), ...args], process.platform, spawnSync);
+  if (py.missing) {
+    console.error(`error: could not find a Python 3.9+ interpreter (tried: ${py.candidates.join(', ')}). Install Python 3.9+ and ensure it is on PATH.`);
+    process.exit(127);
   }
-  process.exit(py.error ? 127 : py.status);
+  process.exit(py.error ? 127 : (py.status == null ? 1 : py.status));
 }
 
 const home = os.homedir();
@@ -159,3 +177,10 @@ if (!has('--uninstall')) {
   console.log('\nDone. Ask your agent things like "make this video 60 seconds and add captions".');
 }
 process.exit(failed ? 1 : 0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { pythonCandidates, runWithPython };

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.10.5`) | any release |
+| `skill.version` | the npm / package.json version (`2.10.7`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.10.5", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.10.7", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -613,7 +613,7 @@ Per-tool keys added in 1.18.0, all additive:
 | `shots` | `scenes.py --shots` | `[{start, end, label, flow_magnitude}]` per detected scene, `label` one of `static`/`pan`/`motion` from a lightweight block-matching optical-flow proxy (frames decoded at 4 fps, 48x27, no external dependency). A shot too short to sample two frames is `static` with `flow_magnitude: 0` |
 | `audio_peaks_db` | `scenes.py --audio-peaks` | `[{time, level}]`, measured dBFS loudness peaks. A **new** key: the pre-existing `audio_peaks` (always reported, unrelated unitless RMS figures used for `--highlights` scoring) keeps its 1.0 meaning unchanged |
 | `speech` | `scenes.py --speech` | `[{time, speech_music_ratio}]`, a per-second zero-crossing-rate ratio against the file's own median — a measured proxy, not a speech/music classification |
-| `motion_centre` | `cropdetect.py --motion-centre` | `[{time, x, y, x_frac, y_frac, motion}]` per second, sampled over the same windows as the crop-bar detection. `x`/`y` are source pixels, `x_frac`/`y_frac` a 0..1 fraction of `source_width`/`source_height`; a window with no measured motion reports `x`/`y`/`x_frac`/`y_frac: null`. Report only — this tool never picks a reframe |
+| `motion_centre` | `cropdetect.py --motion-centre` | `[{time, x, y, x_frac, y_frac, motion}]` per second, sampled over the same windows as the crop-bar detection. `x`/`y` are source pixels, `x_frac`/`y_frac` a 0..1 fraction of `source_width`/`source_height`. Those two sizes are the displayed frame (a 90° or 270° rotation swaps the stored size), the same frame the crop rectangle and `crop.py` use. A window with no measured motion reports `x`/`y`/`x_frac`/`y_frac: null`. Report only — this tool never picks a reframe |
 | `speech_aware`, `speech_aware.breaths` | `silence.py --speech-aware` | `{min_silence, floor, breaths_kept, breaths_kept_seconds, breaths}`. `breaths` are the sub-`--min-silence` gaps kept because they sit inside a sentence; the removal list (`silences`, `keep`, `removed_seconds`) already reflects the speech-aware classification. Composes with `--filler` through the same `keep_ranges()`/`merge_spans()` pipeline, so `--speech-aware --filler` produces one removal list |
 | `sources` | `sync.py` | `[{path, offset_s, confidence, drift_ppm}]`, one entry per SOURCE. Present for every run, including the original single-SOURCE shape (where it mirrors the top-level `second`/`offset_seconds`/`confidence` additively). With 2+ SOURCEs it is the *only* per-source shape: there is no top-level `second`/`offset_seconds` because there is no single pair to put there |
 | `switch_mode`, `min_shot` | `multicam.py --switch energy` | `"energy"` and the `--min-shot` value used (default 1.5s), alongside the existing `cuts` (`[[start, end, camera], ...]`) which already carries the camera index for `--edl`'s companion cut list |

package/mcp/server.py

@@ -21,7 +21,7 @@ import os
 import subprocess
 import sys
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
 HERE = Path(__file__).resolve().parent
 SCRIPTS = HERE.parent / "scripts"
@@ -90,18 +90,66 @@ def build_argv(name: str, args: Dict[str, Any]) -> List[str]:
     return argv
 
 
+def _timeout_in_argv(argv: List[str]) -> Optional[float]:
+    """The last `--timeout` / `--timeout=N` value in a raw argv list.
+
+    None when the flag is absent or its value is not a number (the child argparse then fails,
+    and the outer ceiling stays the environment default)."""
+    found: Optional[float] = None
+    seen = False
+    i = 0
+    n = len(argv)
+    while i < n:
+        token = argv[i]
+        if token == "--":
+            break
+        if token == "--timeout":
+            if i + 1 >= n:
+                return None
+            raw = argv[i + 1]
+            i += 2
+        elif token.startswith("--timeout="):
+            raw = token.split("=", 1)[1]
+            i += 1
+        else:
+            i += 1
+            continue
+        seen = True
+        try:
+            found = float(raw)
+        except ValueError:
+            return None
+    return found if seen else None
+
+
+def timeout_from_call(args: Dict[str, Any]) -> float:
+    """Per-call seconds for the MCP outer ceiling.
+
+    Structured `timeout` is the canonical key. A raw `argv` list ignores every other key, so
+    `--timeout` has to be read from that list: `--timeout 0` otherwise left the ceiling at 4x
+    the 1800 s default while the child itself ran with no limit. A negative value is 0, matching
+    apply_common (0 means no limit)."""
+    if isinstance(args.get("argv"), list):
+        parsed = _timeout_in_argv([str(a) for a in args["argv"]])
+        if parsed is None:
+            return _common._env_timeout()
+        return max(0.0, parsed)
+    try:
+        return max(0.0, float(args.get("timeout", _common._env_timeout())))
+    except (TypeError, ValueError):
+        return _common._env_timeout()
+
+
 def call_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
     script = SCRIPTS / f"{name}.py"
     if name not in specs() or not script.exists():
         return {"isError": True, "content": [{"type": "text", "text": f"unknown tool {name}"}]}
     argv = build_argv(name, args or {})
     # The child enforces --timeout on each ffmpeg call; this outer ceiling (4x that plus 60 s)
-    # is the only thing that ends a child hung for any other reason. The caller's own `timeout`
-    # argument sets both; otherwise FFMPEG_SKILL_TIMEOUT / the 1800 s default.
-    try:
-        per_call = float((args or {}).get("timeout", _common._env_timeout()))
-    except (TypeError, ValueError):
-        per_call = _common._env_timeout()
+    # is the only thing that ends a child hung for any other reason. Structured `timeout` or
+    # `--timeout` inside a raw argv list sets both (0 = no limit); otherwise
+    # FFMPEG_SKILL_TIMEOUT / the 1800 s default.
+    per_call = timeout_from_call(args or {})
     proc = _common.run_tool([str(script)] + argv, per_call=per_call)
     stdout = proc.stdout.strip()
     text = stdout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.10.5",
+  "version": "2.10.7",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/references/gotchas.md

@@ -281,8 +281,12 @@ see what the app covers. An explicit `--margin` always wins.
 
 ### Dimensions and rotation
 `yuv420p` needs even width/height; `fit.py` and `export.py` round to even values
-automatically. Phone footage often carries a `rotation` tag; `probe.py` reports
-it and `fit.py` accounts for it when computing the output frame.
+automatically. Phone footage often carries a `rotation` tag. `probe.py` reports
+the stored width and height plus that rotation. A tool that places or measures
+a rectangle (`fit.py`, `crop.py`, `cropdetect.py`, `broll.py`, `overlay.py
+--scale-percent` / `--platform`, `look.py --safe`) uses the displayed size,
+the two swapped for 90° and 270°, because ffmpeg applies the tag before the
+filter graph.
 
 ## Planning
 

package/references/scripts.md

@@ -242,7 +242,10 @@ cropdetect.py INPUT [--seconds N] [--samples N] [--limit F] [--round N] [--motio
 Measurement only -- writes no file. Samples `--samples` windows spread
 across the file (default 5, totalling `--seconds` 10s of footage) and
 reports the crop rectangle FFmpeg's `cropdetect` filter found most often, as
-`{x, y, width, height}` ready to hand to `crop.py`. Distinct from
+`{x, y, width, height}` ready to hand to `crop.py`. `source_width` /
+`source_height` are that same displayed frame: a 90° or 270° rotation swaps
+the stored size, because the filter measures the picture after ffmpeg applies
+the tag. Distinct from
 `fit.py --fit crop`, which crops to a target aspect ratio it computes
 itself with no black-bar measurement involved. A rectangle that matches the
 full source frame means no bars were found. Does not decide whether
@@ -501,7 +504,8 @@ broll.py A.mp4 --insert B.mp4 --at T [--duration D | --end T2] [--from T3]
                [--insert ... --at ...] [--audio a|b|mix] [--pad-color black] [-o OUT]
 ```
 A plays as it is; during each window B's picture is shown instead (scaled and
-padded to A's frame, A's fps), and A resumes at its own time when the window
+padded to A's displayed frame, A's fps; a 90° or 270° rotation swaps the
+stored size), and A resumes at its own time when the window
 ends -- a cutaway, not a splice, so the output is exactly as long as A. One
 `--insert`/`--at` pair per cutaway (`--duration`, `--end`, `--from` are per
 cutaway too, or given once for all; defaults 4 s and 0); windows may not
@@ -755,10 +759,13 @@ An `overlays[]` entry draws one of `"logo": true`, `"image"`, `"text"` or
 `"video"` (#326: a picture-in-picture or green-screen layer, `overlay.py
 --video`), with `position`, `scale`, `opacity`, `start`, `end`, `margin`,
 `platform` (and `fade`, `box`, `font*` for the still/text kinds) mapping to
-overlay.py's flags. `"chromakey": "0x00ff00"`, `"chromakey_similarity"` and
-`"chromakey_blend"` key a colour out of the video layer. The stage runs after
-`fit`, so `"scale": 480` is 480 px of the delivered frame, and a template's
-safe margins apply as they do to a logo. Refused (`kind: input`) before the
+overlay.py's flags. `scale` is the layer width in px for a logo, image or
+video (`"scale": 480` is 480 px of the delivered frame, because the stage
+runs after `fit`). A text entry's size is `font_size`; `scale` on a text-only
+entry is refused (`kind: input`) rather than drawn at the default font size.
+`"chromakey": "0x00ff00"`, `"chromakey_similarity"` and
+`"chromakey_blend"` key a colour out of the video layer. A template's
+safe margins apply as they do to a logo. Also refused before the
 first stage: `video` together with `logo`/`image`/`text` in one entry (a
 logo, image and text together still draw the first of them, as before), a
 `chromakey*` key without `video`, `chromakey_similarity`/`_blend` without
@@ -1217,7 +1224,8 @@ Outputs PNG. View it with the Read tool (or any image viewer) and judge the
 frame like an editor would. Use `--compare` to show before/after to the user. `--safe NAME` (1.14) shades the zones that
 destination's own UI covers -- TikTok's description block and like column, the Reels/Shorts
 chrome -- on the sheet or the frame, so "is the caption readable" can be answered about the app
-rather than about the file.
+rather than about the file. The "wrong aspect" note compares the displayed frame, so a phone
+file stored sideways is not flagged when the picture already matches the destination.
 
 ### caption.py — subtitles (static, animated, karaoke)
 ```
@@ -1463,8 +1471,13 @@ overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--f
 `--platform NAME` (1.14) takes each edge's margin from that destination's safe zone
 (`scripts/_platforms.py`), so a template's top-left logo clears TikTok's status bar instead of
 sitting 24 px into it; an explicit `--margin` (or a brand `safe_margin`) wins.
+`--scale-percent` and those margins use the displayed frame width and height:
+a 90° or 270° rotation swaps the stored size, which is the frame the overlay
+is composited on.
 Alpha in PNGs is respected. Fades apply to the overlay only; the video keeps
-playing. `--video` composites a second video as a picture-in-picture layer
+playing. `--scale` / `--scale-percent` set the width of an image, logo or
+`--video` layer. They are refused with `--text`: text size is `--font-size`.
+`--video` composites a second video as a picture-in-picture layer
 (same position/scale/opacity/time-range knobs as `--image`); only the main
 input's audio is kept, the PiP layer's own audio is dropped. `--chromakey`
 (with `--video`) keys out that colour first for green-screen compositing.

package/scripts/_common/decision.py

@@ -244,7 +244,7 @@ def fmt_smpte_time(seconds: float, fps: float) -> str:
     return f"{h:02d}:{m:02d}:{s:02d}:{frame:02d}"
 
 
-def escape_filter_path(path: str) -> str:
+def escape_filter_path(path: str, *, bind: bool = True) -> str:
     """Escape a file path for use as a filter option value (subtitles=, ass=, lut3d=file=, fontfile=, fontsdir=).
 
     A filter option value is parsed twice: the graph parser splits filters on `,` / `;` and options
@@ -258,8 +258,11 @@ def escape_filter_path(path: str) -> str:
     token, so a single `\\'` is consumed by the first pass and "Ryo's Mac/cues.srt" reaches the
     filter as "Ryos Mac/cues.srt" (Unable to open ...). Three backslashes survive both passes
     (measured on 6.1 and 7.1 with subtitles=, ass= and lut3d=file=).
+
+    `bind=False` escapes without recording the path as a plan input. The colour-emoji probe
+    uses that: its SRT lives in a temp directory that is gone before any plan is written.
     """
-    if os.path.isfile(path) and path not in STATE.plan_inputs:
+    if bind and os.path.isfile(path) and path not in STATE.plan_inputs:
         STATE.plan_inputs.append(path)  # a plan binds subtitle/LUT/font files too (review 6)
     p = str(Path(path))
     p = p.replace("\\", "/")

package/scripts/_common/emoji.py

@@ -8,6 +8,7 @@ import os
 import shutil
 import subprocess
 from typing import Any, Dict, List, Tuple, Optional
+from _common.decision import escape_filter_path
 from _common.emit import die
 from _common.runner import ffmpeg_exe
 
@@ -165,6 +166,18 @@ EMOJI_ASSET_HINT = (
 _EMOJI_COLOR_FAMILIES = ("Noto Color Emoji", "Apple Color Emoji", "Segoe UI Emoji")
 
 
+def _fc_list_path(line: str) -> str:
+    """The file from one `fc-list ... file` line.
+
+    fontconfig prints `<file>: <families>`. The separator is a colon followed by a space.
+    A Windows drive letter is `C:` followed by a backslash, so splitting on the first colon
+    yields `C` and the font is reported missing.
+    """
+    if ": " in line:
+        return line.partition(": ")[0].strip()
+    return line.strip().rstrip(":")
+
+
 _EMOJI_SUPPORT_CACHE: "Dict[Tuple[Optional[str], bool], Dict[str, Any]]" = {}
 
 
@@ -182,7 +195,7 @@ def _emoji_color_font() -> "Tuple[Optional[str], Optional[str], bool]":
         if proc.returncode != 0:
             return None, None, False
         for line in proc.stdout.splitlines():
-            path = line.split(":", 1)[0].strip()
+            path = _fc_list_path(line)
             if path and os.path.exists(path):
                 return family, path, True
     return None, None, True
@@ -205,7 +218,7 @@ def _libass_color_probe() -> "Optional[bool]":
             proc = subprocess.run(
                 [exe, "-hide_banner", "-loglevel", "error", "-f", "lavfi",
                  "-i", "color=c=black:s=64x64:d=0.04",
-                 "-vf", "subtitles=" + srt.replace("\\", "/"), "-frames:v", "1",
+                 "-vf", "subtitles=" + escape_filter_path(srt, bind=False), "-frames:v", "1",
                  "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
                 stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=20)
         except (subprocess.TimeoutExpired, OSError):

package/scripts/broll.py

@@ -56,6 +56,9 @@ def main() -> int:
         die("A-roll has no video stream")
     dur_a = meta_a.get("duration") or 0.0
     w, h = meta_a["video"]["width"], meta_a["video"]["height"]
+    # the cutaway is scaled onto the frame ffmpeg has already rotated, not the stored one
+    if meta_a["video"].get("rotation") in (90, -90, 270, -270):
+        w, h = h, w
     fps = meta_a["video"].get("fps") or 30.0
     has_audio_a = bool(meta_a.get("audio"))
 

package/scripts/cropdetect.py

@@ -138,6 +138,11 @@ def main() -> int:
     if not meta.get("video"):
         die("input has no video stream")
     sw, sh = meta["video"]["width"], meta["video"]["height"]
+    # cropdetect and the grey decode both see the frame after ffmpeg applies rotation, so the
+    # rectangle and the motion points are in that frame. Reporting the stored size made a
+    # 176x320 crop look taller than a 320x180 source.
+    if meta["video"].get("rotation") in (90, -90, 270, -270):
+        sw, sh = sh, sw
     duration = meta.get("duration") or 0.0
 
     rects = detect(args.input, args.seconds, args.samples, args.limit, args.round_to, duration)

package/scripts/fit.py

@@ -198,7 +198,7 @@ def main() -> int:
             darken = 0.0 if meta["video"].get("bt2020_or_hdr") else BLUR_DARKEN
             if not darken:
                 info("--fit blur: HDR source, so the blurred background is not dimmed "
-                     "(an eq on PQ/HLG code values is not the -15%% dim it is on SDR); "
+                     "(an eq on PQ/HLG code values is not the -15% dim it is on SDR); "
                      "run color.py --to-sdr first for the SDR look")
             vf.append(pad_filters(out_w, out_h, "blur", args.pad_color, args.pad_blur, darken))
         else:

package/scripts/look.py

@@ -170,8 +170,11 @@ def main() -> int:
         z = PLATFORMS[args.safe]["safe"]
         frame = PLATFORMS[args.safe]["frame"]
         src = meta["video"]
-        if src.get("width") and src.get("height") and abs(src["width"] / src["height"] - frame["w"] / frame["h"]) > 0.02:
-            info(f"--safe {args.safe}: this source is {src['width']}x{src['height']}, not {args.safe}'s "
+        dw, dh = src.get("width") or 0, src.get("height") or 0
+        if src.get("rotation") in (90, -90, 270, -270):
+            dw, dh = dh, dw
+        if dw and dh and abs(dw / dh - frame["w"] / frame["h"]) > 0.02:
+            info(f"--safe {args.safe}: this source is {dw}x{dh}, not {args.safe}'s "
                  f"{frame['w']}x{frame['h']} -- the zones are drawn as fractions of the frame you gave, "
                  f"so reframe first (fit.py --aspect) to see what the app really covers")
         boxes = []

package/scripts/overlay.py

@@ -116,8 +116,10 @@ def main() -> int:
     ap.add_argument("--fade", type=float, default=0.0, help="fade-in duration in seconds (at --start or 0); the fade-out happens only at --end")
     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")
+    img.add_argument("--scale", type=int, help="width in px for an image, logo or video layer (keeps aspect); text size is --font-size")
+    img.add_argument("--scale-percent", type=float,
+                     help="width as a %% of the displayed frame for an image, logo or video layer (keeps aspect); "
+                          "a 90 or 270 degree rotation uses the stored height; text size is --font-size")
     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)")
@@ -158,6 +160,10 @@ def main() -> int:
         die("--text is blank -- give the words to draw", kind="input")
     if not (args.image or args.text or args.video):
         die("give --image, --text, --logo or --video")
+    # --scale is a layer width. On a text draw it used to be accepted and ignored (fontsize stayed
+    # at --font-size), so a project that asked for 200 px text completed with the 42 px default.
+    if args.text and not (args.image or args.video) and (args.scale is not None or args.scale_percent is not None):
+        die("--scale and --scale-percent size an image, logo or video layer; text size is --font-size", kind="input")
     if args.brand:
         if args.margin == ap.get_default("margin"):
             args.margin = int(brand.get("safe_margin", args.margin))
@@ -205,7 +211,12 @@ def main() -> int:
         die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
     if args.audio_stream and not audio_streams:
         die("--audio-stream needs an input with audio streams")
-    vw = meta["video"]["width"]
+    vw = meta["video"]["width"] or 0
+    vh = meta["video"].get("height") or 0
+    # ffmpeg applies display rotation before the filter graph, so the frame this overlay is
+    # composited on is the displayed one. A 320x180 phone file tagged 90 degrees is 180 wide here.
+    if meta["video"].get("rotation") in (90, -90, 270, -270):
+        vw, vh = vh, vw
     # --platform: the edges this destination's own UI covers, in pixels of this frame. An
     # explicit --margin (or a brand safe_margin, applied above) is the more specific statement
     # and wins; without either, the historical 24 px default is unchanged.
@@ -216,7 +227,7 @@ def main() -> int:
         # fall back to the destination's own delivery frame -- which is what the fitted
         # intermediate this stage runs on will be anyway
         frame = PLATFORMS[args.platform]["frame"]
-        pw, ph = vw or frame["w"], meta["video"].get("height") or frame["h"]
+        pw, ph = vw or frame["w"], vh or frame["h"]
         safe_margins = safe_margins_px(args.platform, pw, ph)
         info(f"--platform {args.platform}: safe margins top {safe_margins['top']} / bottom {safe_margins['bottom']} / "
              f"left {safe_margins['left']} / right {safe_margins['right']} px (clear of the app's own UI)")

package/scripts/render.py

@@ -40,7 +40,9 @@ skipped. "brand" points caption/graphics/overlay at a brand.json (fonts,
 colours, logo, safe margin); {"logo": true} in overlays places the brand logo.
 An overlay entry draws one of logo, image, text or video (a picture-in-picture
 layer, overlay.py --video; "chromakey", "chromakey_similarity" and
-"chromakey_blend" key a colour out of that video and need "video").
+"chromakey_blend" key a colour out of that video and need "video"). "scale"
+is that layer's width in px for a logo, image or video; a text entry's size
+is "font_size", and "scale" on a text entry is refused.
 
 "check" mirrors check.py's own exit code: a delivery-spec FAIL (or check.py
 itself failing to run) exits 1, same as running check.py directly would --
@@ -436,6 +438,10 @@ def check_overlay(ov: Any, label: str) -> None:
         tuned = [k for k in ("chromakey_similarity", "chromakey_blend") if ov.get(k) is not None]
         if tuned:
             die(f"{label}: {tuned[0]} tunes \"chromakey\", which this entry does not set")
+    # scale is a layer width (overlay.py --scale). A text entry that carries it used to complete
+    # with the default font size, because the text branch never reads the flag.
+    if ov.get("text") and not any(ov.get(k) for k in ("logo", "image", "video")) and ov.get("scale") is not None:
+        die(f"{label}: scale sizes an image, logo or video layer; text size is font_size", kind="input")
 
 
 def require_object(obj: Any, label: str) -> None:

package/scripts/speedramp.py

@@ -84,9 +84,14 @@ def main() -> int:
     output = args.output or default_output(args.input, "ramp")
 
     vparts, aparts, labels = [], [], []
+    # The coverage check above allows the last end to sit up to 0.5 s off the probed duration.
+    # That slack is for a caller who rounded the duration, not a reason to redraw the tail at
+    # the last factor. The end bound is omitted only when the stated end is the file's end
+    # (within 50 ms): a trim a few milliseconds short of the last packet drops that packet.
+    last_runs_to_eof = abs(segments[-1][1] - dur) <= 0.05
     for i, (start, end, factor) in enumerate(segments):
         vlabel, alabel = f"v{i}", f"a{i}"
-        end_expr = f"{end:.3f}" if i < len(segments) - 1 else None
+        end_expr = f"{end:.3f}" if not (i == len(segments) - 1 and last_runs_to_eof) else None
         trim = f"trim=start={start:.3f}" + (f":end={end_expr}" if end_expr else "")
         vparts.append(f"[0:v]{trim},setpts=(PTS-STARTPTS)/{factor:.6f}[{vlabel}]")
         labels.append(f"[{vlabel}]")

package/scripts/sync.py

@@ -36,6 +36,17 @@ from _common import video_args, add_common, apply_common, emit, aac_args, audio_
 
 SR = 8000  # decode sample rate
 
+
+def sync_meaning(offset: float) -> str:
+    """The sentence a caller reads next to offset_seconds.
+
+    A zero offset used to take the else branch of `later if offset > 0` and say the second
+    file starts earlier. Values that print as 0.000 s (under half a millisecond) say the two
+    recordings start together; anything larger keeps later/earlier."""
+    if abs(offset) < 5e-4:
+        return "second starts together with the reference"
+    return "second starts %.3fs %s than reference" % (abs(offset), "later" if offset > 0 else "earlier")
+
 # Scoring constants for coarse alignment. Both come from tests/bench_sync.py on real dialogue and
 # music with +/-30 s offsets, gain, noise and EQ (see evals/results and CHANGELOG 0.8.0):
 #
@@ -307,7 +318,7 @@ def main() -> int:
             "second": args.second,
             "offset_seconds": offset,
             "confidence": score,
-            "meaning": ("second starts %.3fs %s than reference" % (abs(offset), "later" if offset > 0 else "earlier")),
+            "meaning": sync_meaning(offset),
             "sources": sources_block,
         }
         if drift_info: