Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

refactor: split _common.py into a package and tests by tool group (no behaviour change) (#230)

claude[bot]bb02ad83ac4f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index da8af1a..976d226 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,35 @@
## Unreleased
-(nothing yet)
+### Changed
+
+- **refactor: `scripts/_common.py` is a package, and `tests/test_all.py` splits by tool group.
+ No behaviour change.** A release of its own so that "nothing changed for a caller" is checkable
+ in one diff (roadmap, "Refactor release after 1.15.0"). The 3072-line helper module is now
+ `scripts/_common/` with one module per responsibility — `runner.py` (process execution,
+ timeouts, signals, the output lock and staging, `run_tool`, the drawtext text-file spool),
+ `probe.py` (ffprobe and the measured facts: `probe()`, `verify_output()`, the level and
+ envelope measurements), `decision.py` (the pure choices: encoder and codec arguments, times,
+ paths, brand defaults — nothing here starts a subprocess), `emit.py` (`emit()`, `die()`,
+ `info()`, the brief and 2.0 shapes, the plan file), `color.py` (bt709 tagging, the HDR-to-SDR
+ path, colour-token validation) and `text.py` (fonts per script, emoji clusters and assets,
+ drawtext escaping and options, the advance table the caption wrap measures with).
+ `scripts/_common/__init__.py` is a facade re-exporting all **184** names the single file
+ defined — public and underscore alike — so every `from _common import ...` and every
+ `_common.<name>` in the tools, the MCP server, the demos, the evals and the tests keeps
+ working unchanged; rebinding a name on the facade (`_common._FFMPEG_VERSION = (7, 1)`, a
+ `mock.patch("_common.<name>")`) rebinds it on the module that defines it, so the test seams
+ that reached into the module still hold. Function bodies were moved, not edited.
+ `tests/test_all.py` is a `load_tests` aggregator over `tests/test_analysis.py`,
+ `test_editing.py`, `test_audio.py`, `test_picture.py`, `test_delivery.py` and
+ `test_orchestration.py` with the shared footage in `tests/_fixtures.py` (built once per
+ process, not once per group); each group module also runs on its own. `npm test` and every CI
+ job are unchanged and run the same 323 cases under the same names.
+ Proof of no behaviour change: `scripts/_contract.py --json`, the MCP `tools/list` response and
+ `--help` for all 42 tools are **byte-identical** to 1.15.0. The tool count stays 42 — a package
+ directory is not a tool, and every `scripts/*.py` enumeration (the contract, the MCP server,
+ `demos/build.py`, the every-script tests) skips it unchanged; the source *scans* that must not
+ stop covering the helpers (`shell=True` and friends) now read `scripts/_common/*.py` too.
## 1.15.0
diff --git a/README.md b/README.md
index 45146d6..cdf777b 100644
--- a/README.md
+++ b/README.md
@@ -386,8 +386,11 @@ FFmpeg 8 shortened the flag column of `ffmpeg -filters`. A parser anchored on th
## Tested on real footage
**What is tested where.** The contract and the test suite (`tests/test_contract.py`,
-`tests/test_all.py`) run on Linux, macOS and Windows on every pull request, minus the handful of
-POSIX-shim tests listed under [Development](#development). The real-device media corpus
+`tests/test_all.py`, which aggregates one module per tool group — `test_analysis.py`,
+`test_editing.py`, `test_audio.py`, `test_picture.py`, `test_delivery.py`,
+`test_orchestration.py` — over the shared footage in `tests/_fixtures.py`) run on Linux, macOS
+and Windows on every pull request, minus the handful of POSIX-shim tests listed under
+[Development](#development). The real-device media corpus
(`tests/corpus.py`) has been run on Linux and macOS; the full corpus has **not** been run on
Windows yet, and neither has an install by someone other than the maintainer been reproduced
there — [issue #143](https://github.com/kajisho5/ffmpeg-skill/issues/143) tracks both. Treat the
@@ -478,6 +481,7 @@ FFmpeg itself:
```bash
npm test # tests/test_all.py (end-to-end incl. VFR, rotated, 5.1, HDR10, drifting sources) + tests/test_contract.py
+python3 tests/test_picture.py # one tool group on its own (analysis, editing, audio, picture, delivery, orchestration)
npm run release-check # pack, install, contract from the installed copy, MCP == contract, doctor, tests, contract evals
npm run demo # python3 demos/build.py: synthetic footage -> every before/after demo + docs/demos/*.gif
npm run demo:pipeline # examples/make_demo.sh: the older single end-to-end run of every script
diff --git a/demos/CI.md b/demos/CI.md
index f6a57ab..b5e39dd 100644
--- a/demos/CI.md
+++ b/demos/CI.md
@@ -19,7 +19,7 @@ demos skip themselves and the job silently proves less than it looks like it doe
```yaml
# Renders the whole before/after gallery from synthetic footage on every PR. This is a real
# end-to-end test of every script under scripts/ except the four inspection-only ones
- # (probe, verify, batch, report), which print a table rather than a picture -- tests/test_all.py
+ # (probe, verify, batch, report), which print a table rather than a picture -- tests/test_orchestration.py
# pins that split, so a new tool cannot land without either a demo or an entry on that list.
# It is also the gate on
# what lands in docs/demos/: build.py fails when a committed preview goes over 500 KB, so a
diff --git a/demos/build.py b/demos/build.py
index 89ef4bb..22c5a51 100644
--- a/demos/build.py
+++ b/demos/build.py
@@ -1260,7 +1260,7 @@ BY_NAME = {d.name: d for d in DEMOS}
# Tools whose whole output is a table, a JSON document or an HTML file: there is no before/after
# picture to render, so they are listed in the gallery's Inspection section with the command
-# instead. tests/test_all.py reads this list -- every other script under scripts/ must appear in
+# instead. tests/test_orchestration.py reads this list -- every other script under scripts/ must appear in
# at least one demo's command, so a tool cannot quietly arrive with nothing to look at.
INSPECTION = [
("probe.py", "python3 scripts/probe.py demos/out/render_project_after.mp4 --compact",
diff --git a/docs/contract.md b/docs/contract.md
index 7f68efb..f752581 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -450,7 +450,8 @@ measurement dicts flattened, plus any numeric top-level key such as `expected_du
1.x keys are not moved; the environment variable only adds the key, and its absence is the
default until 2.0.
-Success is decided by `verify_output` in `_common.py`, not by the ffmpeg exit code alone:
+Success is decided by `verify_output` in `_common` (`scripts/_common/probe.py`), not by the
+ffmpeg exit code alone:
the file must exist, be non-empty and give ffprobe at least one stream. A tool that ran
ffmpeg successfully but has no usable artifact fails with `kind: output` (a 0-byte file is
removed so a later step cannot mistake it for a result).
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index f438dba..f10ec1b 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -167,12 +167,16 @@ exists. When a decision changes, edit the entry in the same PR.
An outside review of the repository at 1.13.0 (eval 14). What it raised, and what was decided.
Each item is recorded here so it is not re-proposed from scratch.
-- **`scripts/_common.py` is too large to review in one pass.** Accepted, with the split deferred
- to a **behaviour-free refactor release after 1.15.0**, not folded into a feature minor: the
- module becomes a package (`runner`, `probe`, `decision`, `emit`, `color`) and
- `scripts/_common/__init__.py` stays a facade re-exporting today's names, so every
- `from _common import ...` in the tools and tests keeps working and the diff is checkable as
- "no caller changed". `tests/test_all.py` splits by tool group in the same release. Two things
+- **`scripts/_common.py` is too large to review in one pass.** Accepted, and **done** in the
+ behaviour-free refactor release after 1.15.0, not folded into a feature minor: the module is a
+ package of six -- `runner` (process execution and timeouts), `probe` (ffprobe and the measured
+ facts), `decision` (the pure copy-vs-re-encode and capability choices), `emit` (result
+ documents, `die()`, `info()`), `color` (colour tags and the HDR paths) and `text` (fonts,
+ scripts, emoji, drawtext) -- and `scripts/_common/__init__.py` is a facade re-exporting all 184
+ of their names, so every `from _common import ...` and every `_common.<name>` in the tools and
+ tests keeps working and the diff is checkable as "no caller changed": the contract snapshot,
+ the MCP tool surface and every `--help` came out byte-identical. `tests/test_all.py` split by
+ tool group in the same release. Two things
the review suggested alongside it were **rejected**: a `MediaInfo` dataclass in place of the
probe dicts (the dicts are the `--json` payload and the contract's `output_schema`; a
dataclass would add a conversion layer on the hot path and a second shape to keep in sync),
diff --git a/docs/roadmap.md b/docs/roadmap.md
index f7c973d..e4b778a 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -19,7 +19,8 @@ minor and `fix` PRs into a patch, so each block below is one or two `feat` PRs p
The released version today is **1.15.0**, shipped and evaluated: **eval 16**
(`evals/results/iteration-16.json`) graded it on the 82-prompt set, the 76 plus the six
-emoji/shaping prompts. Everything after 1.15.0 is planned.
+emoji/shaping prompts. After it comes the behaviour-free refactor release below; everything
+after that is planned.
| version | state | evidence |
|---|---|---|
@@ -31,6 +32,7 @@ emoji/shaping prompts. Everything after 1.15.0 is planned.
| 1.13.0 | shipped + evaluated | eval 14 at 1.13.0 (`iteration-14.json`) |
| 1.14.0 | shipped + evaluated | eval 15 at 1.14.0 (`iteration-15.json`) |
| 1.15.0 | shipped + evaluated | eval 16 at 1.15.0 (`iteration-16.json`) |
+| refactor after 1.15.0 | shipped, eval pending | contract + MCP snapshots and every `--help` byte-identical; 323/323 cases |
| 1.16.0 → 1.21.0, 2.0.0 | planned | — |
## 1.8.0 — one-call delivery, quieter checks, encoder flags (shipped + evaluated, eval 8)
@@ -238,19 +240,25 @@ keys, one new private module, one new doctor row.
one-character ban removed the `th1`/`dl3` orphans but not the cause. A phrase-aware breaker is
the first item of 1.16.0.
-## Refactor release after 1.15.0 — no behaviour change (planned)
+## Refactor release after 1.15.0 — no behaviour change (shipped, eval pending)
A release of its own so that "nothing changed for a caller" is checkable in one diff: no flag,
no JSON key, no exit code, no contract field moves. The contract snapshot and the MCP snapshot
-must come out byte-identical.
+came out byte-identical, as did `--help` for all 42 tools.
-- **`scripts/_common.py` becomes a package**: `runner` (process execution and timeouts),
+- **`scripts/_common.py` is a package**: `runner` (process execution and timeouts),
`probe` (ffprobe and the measured facts), `decision` (the copy-vs-re-encode and capability
- choices), `emit` (result documents, `die()`, `info()`) and `color` (colour tags, HDR paths).
- `scripts/_common/__init__.py` is a facade that re-exports today's names, so every
- `from _common import ...` in every tool and test keeps working unchanged.
-- **`tests/test_all.py` splits by tool group** (analysis, editing, audio, picture, delivery,
- orchestration) with the shared fixtures in one place; `npm test` still runs the same set.
+ choices), `emit` (result documents, `die()`, `info()`), `color` (colour tags, HDR paths) and
+ `text` (fonts, script detection, emoji, drawtext), which the plan did not name separately and
+ which is the second-largest of the six.
+ `scripts/_common/__init__.py` is a facade that re-exports all 184 names the single file
+ defined, so every `from _common import ...` and every `_common.<name>` in every tool and test
+ keeps working unchanged — including the ones tests rebind (`_common._FFMPEG_VERSION`), which
+ the facade mirrors onto the module that defines them.
+- **`tests/test_all.py` split by tool group** (analysis, editing, audio, picture, delivery,
+ orchestration) with the shared fixtures in `tests/_fixtures.py`; `test_all.py` is now a
+ `load_tests` aggregator over the six, so `npm test` runs the same 323 cases under the same
+ names. The footage is built once per process, not once per group.
- No eval iteration of its own: the release is proved by the existing suite plus the two
snapshots, and the next themed eval runs on top of it.
diff --git a/references/ci-platform-pitfalls.md b/references/ci-platform-pitfalls.md
index bfd8eb5..0adf5d0 100644
--- a/references/ci-platform-pitfalls.md
+++ b/references/ci-platform-pitfalls.md
@@ -124,7 +124,12 @@ these had ever shown up before.
- **`drawtext` `boxborderw=v|h` (and the four-value form) is 6.1+.** 5.x and 6.0 fail the whole
filter with "Error setting option boxborderw to value 9|16". `_common.drawtext_boxborderw()`
emits the larger single value on older builds (`_common.ffmpeg_version()` parses
- `ffmpeg -version` once; it is the only place the tools branch on a version string).
+ `ffmpeg -version` once; it is the only place the tools branch on a version string). Both names
+ are still spelled exactly that way: `_common` is a package since the refactor release after
+ 1.15.0, and its `__init__.py` re-exports every name the single module defined, so
+ `_common.drawtext_boxborderw()`, `_common.ffmpeg_version()` and `_common.bt709_tag_args()`
+ below resolve through the facade unchanged. The definitions are in `_common/text.py`,
+ `_common/runner.py` and `_common/color.py` respectively.
- **`showwaves` keeps emitting frames after the audio ends, `-shortest` notwithstanding.** A
12 s source came out 14.08 s on 5.1.1. `waveform.py` now also passes `-t <source duration>`.
- **`-display_rotation` is 6.0+.** Only the test fixture builder used it (to make a rotated
diff --git a/scripts/_common.py b/scripts/_common.py
deleted file mode 100755
index 3f8129c..0000000
--- a/scripts/_common.py
+++ /dev/null
@@ -1,3072 +0,0 @@
-#!/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 math
-import os
-import platform
-import argparse
-import re
-import shutil
-import subprocess
-import sys
-import unicodedata
-from fractions import Fraction
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Sequence, Tuple
-
-# Every script prints paths, help text and reports that may contain non-ASCII (Japanese examples,
-# arrows). On Windows the console streams default to a legacy code page and raise
-# UnicodeEncodeError; make them UTF-8 with replacement so a --help never crashes on encoding.
-for _stream in (sys.stdout, sys.stderr):
- try:
- if getattr(_stream, "encoding", "").lower().replace("-", "") != "utf8":
- _stream.reconfigure(encoding="utf-8", errors="replace")
- except (AttributeError, ValueError):
- pass
-
-INSTALL_HINTS = {
- "Darwin": " brew install ffmpeg-full (the plain ffmpeg formula lacks subtitles/drawtext/zscale)",
- "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"
- ),
-}
-
-
-# `kind` (below) is the machine-readable failure axis: input / missing_tool / ffmpeg / output
-# since 0.1, plus timeout (1.3), verification (1.4.3) and interrupted (1.4.10). `ERROR_CODE` is an
-# additive, purely informational refinement layered on top for agents that want a stable enum to
-# switch on instead of pattern-matching `kind` strings -- a static 1:1 relabelling of the same
-# buckets, not a new taxonomy. It intentionally does NOT introduce categories this codebase cannot actually
-# distinguish today (e.g. a separate ffprobe-vs-ffmpeg code, or an environment-vs-content-cause
-# split of ffmpeg failures): every ffmpeg subprocess failure is currently one undifferentiated
-# bucket regardless of whether ffmpeg rejected a bad filter argument or died from a full disk,
-# and every "kind": "input" failure covers both a missing file and a bad flag value alike. Adding
-# codes for distinctions the code can't actually make would be guessing, not reporting -- if a
-# future call site can genuinely tell capability-missing apart from bad-argument (see doctor()'s
-# available/missing/unknown states, which already model this for detection but aren't wired into
-# any die() call), split ERROR_CODE then, with evidence, not speculatively now.
-ERROR_CODE = {
- "input": "INPUT_INVALID",
- "missing_tool": "DEPENDENCY_MISSING",
- "ffmpeg": "FFMPEG_EXECUTION_FAILED",
- "output": "OUTPUT_INVALID",
- "timeout": "TIMEOUT",
- "verification": "VERIFICATION_FAILED",
- "interrupted": "INTERRUPTED",
-}
-
-# Wall-clock ceiling for one ffmpeg/ffprobe invocation, in seconds. A hung ffmpeg (a build
-# that deadlocks on a filter combination, a stalled network mount, an input that never ends)
-# used to hang the calling agent with it, with no error document and no way out short of
-# killing the process by hand. The ceiling is generous on purpose: it exists to turn a hang
-# into a reported failure, not to police slow encodes. --timeout and FFMPEG_SKILL_TIMEOUT
-# override it; 0 disables it.
-DEFAULT_TIMEOUT = 1800.0
-PROBE_TIMEOUT = 120.0
-
-
-def _env_timeout() -> float:
- try:
- return max(0.0, float(os.environ.get("FFMPEG_SKILL_TIMEOUT", DEFAULT_TIMEOUT)))
- except ValueError:
- return DEFAULT_TIMEOUT
-
-# None of the four kinds above are retryable in practice: an "input"/"missing_tool" failure is
-# always deterministic (the same bad path or absent binary fails identically every time), and a
-# "ffmpeg"/"output" failure -- while it COULD in principle be caused by a transient environment
-# condition (full disk, OOM) rather than a bad command -- is never distinguishable from a
-# deterministic content-cause failure without exit-code/stderr sniffing this codebase does not do.
-# Reporting retryable=True for a code we can't actually back up would invite an agent into a blind
-# retry loop against a command that will fail the same way every time; false-for-everything is the
-# honest answer until real sniffing exists to justify anything else.
-ERROR_RETRYABLE = False
-
-
-_FFMPEG_VERSION: "Optional[Tuple[int, int]]" = None
-
-
-def ffmpeg_version() -> "Tuple[int, int]":
- """(major, minor) of the FFmpeg build on PATH, parsed once from `ffprobe -version`; (0, 0)
- when it cannot be read. ffprobe rather than ffmpeg because --dry-run promises never to run
- ffmpeg (docs/contract.md: ffmpeg_execution "none") while ffprobe always may, and the two
- ship from the same build. Used only to pick between two spellings of an option where FFmpeg
- changed behaviour between releases (the tools otherwise never branch on the version: doctor's
- capability listing is the source of truth for what a build can do)."""
- global _FFMPEG_VERSION
- if _FFMPEG_VERSION is None:
- _FFMPEG_VERSION = (0, 0)
- try:
- out = subprocess.run(["ffprobe", "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
- timeout=PROBE_TIMEOUT).stdout
- m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)", out)
- if m:
- _FFMPEG_VERSION = (int(m.group(1)), int(m.group(2)))
- else:
- # git / vendor builds print "N-115000-g..." or a date, never major.minor; the
- # libavutil major is still there and maps one-to-one onto the FFmpeg major
- # (56=4, 57=5, 58=6, 59=7, 60=8). Without this every version branch took the
- # oldest spelling on such builds: on 7.1 that skipped bt709_tag_args()'s
- # workaround and an untagged source got a real matrix conversion.
- m = re.search(r"^libavutil\s+(\d+)\.", out, re.M)
- if m:
- major = int(m.group(1)) - 52
- if major >= 4:
- _FFMPEG_VERSION = (major, 0)
- except (OSError, subprocess.TimeoutExpired):
- # (0, 0) = unknown: every version branch then takes the older, universally accepted
- # spelling, the same "unknown is not missing" stance doctor takes.
- pass
- return _FFMPEG_VERSION
-
-
-def drawtext_boxborderw(vertical: int, horizontal: int) -> str:
- """drawtext's per-side `boxborderw=top|right|bottom|left` (and the two-value `v|h` form)
- arrived in FFmpeg 6.1; 5.x and 6.0 reject the `|` with "Error setting option boxborderw"
- (found by the FFmpeg 5.1.1 CI job, #146). Older builds get the larger single value."""
- if ffmpeg_version() >= (6, 1):
- return f"{vertical}|{horizontal}"
- return str(max(vertical, horizontal))
-
-
-def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken: float = 0.0) -> str:
- """The letterbox/pillarbox step shared by fit.py and export.py, as one -vf segment.
-
- fill="color": scale to fit, then pad with a solid colour (the historical behaviour).
- fill="blur": the bars are a blurred, scaled-to-cover copy of the same frame -- what every
- phone editor's "make it vertical" does with landscape footage (#139). Built as a small
- graph inside the -vf chain: split, one branch scaled to cover and cropped to the frame
- then boxblur'ed, the other scaled to fit, overlaid centred. Only `filter:boxblur` is
- needed beyond the usual scale/pad set, and that is already required by redact.py.
- `darken` > 0 also dims that background copy by that much brightness (eq), so the picture in
- front reads as the subject instead of competing with a bright blurred copy of itself --
- what `fit.py --fit blur` uses (1.14)."""
- if fill == "blur":
- # boxblur rejects a radius larger than half the smaller dimension ("radius 20, must be
- # <= 8" on a 16 px target); clamp instead of failing an otherwise valid request
- radius = max(1, min(int(blur), max(1, min(out_w, out_h) // 2 - 1)))
- return (f"split[__fitfg][__fitbg];"
- f"[__fitbg]scale={out_w}:{out_h}:force_original_aspect_ratio=increase,crop={out_w}:{out_h},"
- f"boxblur={radius}:2" + (f",eq=brightness=-{darken:g}" if darken else "") + "[__fitbgb];"
- f"[__fitfg]scale={out_w}:{out_h}:force_original_aspect_ratio=decrease[__fitfgs];"
- f"[__fitbgb][__fitfgs]overlay=(W-w)/2:(H-h)/2:format=auto")
- return f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease,pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={color}"
-
-
-def add_pad_fill_args(parser: "argparse.ArgumentParser") -> None:
- parser.add_argument("--pad-fill", choices=["color", "blur"], default="color",
- help="what fills the letterbox/pillarbox bars under --fit pad: a solid --pad-color (default) or a blurred, scaled-up copy of the frame")
- parser.add_argument("--pad-blur", type=int, default=20, help="blur radius in pixels for --pad-fill blur (default 20)")
-
-
-def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]" = None, **extra: Any) -> "None":
- """Exit with a message. Under --json also print a machine-readable failure document
- (status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged.
-
- `extra` fields are added to the failure document: a tool whose *result* failed (check.py's
- platform rows, render.py's check stage, batch.py's per-item results, verify.py's steps) keeps
- reporting that detail while the top-level status says failed. Before 1.4.3 those four printed
- `status: "completed"` next to a non-zero exit code, so a caller keying on the status alone
- read a failed delivery as a success."""
- hint = extra.pop("hint", None)
- ctx = ctx or STATE # 1.10: the optional per-request Context (2.0 makes it required); STATE is the default instance
- _set_current_ctx(ctx) # the atexit hook has no argument: it reads the ctx emit()/die() last used
- ctx.plan = None # a failed run plans nothing (the exit hook must not write a plan for it)
- STATE.plan = None # the hook falls back to STATE when nothing passed a ctx; a failed run plans nothing there either
- sys.stderr.write(f"error: {msg}\n" + (f"hint: {hint}\n" if hint else ""))
- if ctx.json:
- doc: Dict[str, Any] = {
- "status": "failed", "exit_code": code,
- "error": {
- "kind": kind, "message": msg,
- "code": ERROR_CODE.get(kind, "INTERNAL_ERROR"),
- "retryable": ERROR_RETRYABLE,
- },
- "commands": list(ctx.commands),
- }
- if hint:
- doc["error"]["hint"] = hint
- doc.update(extra)
- print_json(doc)
- sys.exit(code)
-
-
-def info(msg: str, ctx: "Optional[Context]" = None) -> None:
- # under --dry-run nothing is written; do not let scripts claim otherwise
- ctx = ctx or STATE
- if msg.startswith("wrote ") and ctx.dry_run:
- msg = "[dry-run] would write " + msg[len("wrote "):]
- 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, kind="missing_tool",
- )
- return "" # unreachable
-
-
-X264_PRESETS = ("ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow", "placebo")
-CODECS = ("h264", "hevc", "av1", "prores")
-# x264 preset names mapped onto SVT-AV1's 0-13 speed scale (lower = slower / better)
-SVT_PRESET = {"ultrafast": 12, "superfast": 11, "veryfast": 10, "faster": 9, "fast": 8, "medium": 6, "slow": 4, "slower": 3, "veryslow": 2, "placebo": 1}
-_ENCODERS: Optional[set] = None
-
-
-class Context:
- """Per-process settings that the shared flags (--dry-run, --json, --progress, --fast) set once.
-
- Scripts read it as attributes (``STATE.dry_run``); the dict-style shims that once served
- older call sites are gone. Keeping it a single explicit object rather than module globals
- makes it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
- """
-
- __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec")
-
- def __init__(self) -> None:
- self.reset()
-
- def reset(self) -> None:
- self.dry_run = False # print ffmpeg commands, run nothing (ffprobe still runs)
- self.json = False # emit() prints a JSON document instead of the output path
- self.json_brief = False # --json-brief: the same document trimmed to the fields a caller acts on
- self.progress = False # run() streams percent / ETA to stderr for ffmpeg
- self.fast = False # x264 preset forced to veryfast
- self.duration_hint: Optional[float] = None # expected output length, for the progress percent
- self.commands: List[str] = [] # every ffmpeg command line, for --json and --dry-run
- self.timeout: float = _env_timeout() # seconds per ffmpeg invocation, 0 = none
- self.overwrite = False # --overwrite: an existing output may be replaced
- self.written: set = set() # output paths this process has written itself
- self.preexisting: dict = {} # output path -> (size, mtime_ns) of a file that was there before we ran
- self.plan: Optional[str] = None # --plan FILE: write the dry-run as a plan document (implies --dry-run)
- self.plan_written = False # write_plan() ran (emit or the exit hook), so the hook does not write twice
- self.plan_inputs: List[str] = [] # side inputs (srt/ass/lut/font files) a tool named through escape_filter_path
- self.codec: Optional[str] = None # --codec: encoder for the re-encode (None = x264 for SDR, x265 for HDR)
-
-
-
-STATE = Context()
-
-# The atexit plan hook takes no arguments, so emit()/die() record the Context they were given
-# here; nothing passed a ctx = it stays None and the hook falls back to STATE, as before (1.10).
-_CURRENT_CTX: "Optional[Context]" = None
-
-
-def _set_current_ctx(ctx: "Context") -> None:
- global _CURRENT_CTX
- _CURRENT_CTX = ctx
-
-
-def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
- """Add the flags every script shares. `codec=False` is for a tool that re-encodes but whose
- preset decides the encoder (export.py): it must not advertise --codec/--quality in its schema."""
- g = ap.add_argument_group("agent options")
- g.add_argument("--dry-run", action="store_true", help="print the ffmpeg commands that would run, run nothing")
- g.add_argument("--json", action="store_true", help="print a JSON result (output, probe, commands) on stdout instead of the path")
- g.add_argument("--json-brief", action="store_true",
- help="like --json but trimmed: status, output, dry_run, verified, a compact summary of the output probe, this tool's own keys, and the command count instead of the command lines (failures print the full failure document, unchanged)")
- g.add_argument("--progress", action="store_true", help="show percent / ETA on stderr while ffmpeg encodes")
- g.add_argument("--fast", action="store_true", help="preview quality: x264 preset veryfast (overrides --preset) for quick iterations")
- if "--timeout" not in ap._option_string_actions: # verify.py defines its own per-step --timeout; apply_common reads either
- g.add_argument("--timeout", type=float, default=None, metavar="SECONDS",
- help=f"kill an ffmpeg run past this many seconds, kind=timeout (default {DEFAULT_TIMEOUT:.0f}; 0 = no limit)")
- g.add_argument("--overwrite", action="store_true",
- help="allow replacing an existing output (warned today, refused from 2.0)")
- g.add_argument("--plan", metavar="FILE",
- help="write the dry run as a plan (inputs fingerprinted, commands, expected output, verify steps) that render.py FILE executes later; implies --dry-run")
- if codec and "--crf" in ap._option_string_actions:
- # --crf became an alias of --quality in 1.8; 1.10 deprecates it (removed in 2.0, see the
- # `deprecated` list in `contract --json` and docs/contract.md "What 2.0 changes"). Marked
- # here, once, rather than in each re-encoding tool's own parser.
- crf = ap._option_string_actions["--crf"]
- # The flag's own default moves aside so apply_common() can tell an explicit --crf (in any
- # spelling argparse accepts, including the --cr / --c abbreviations) from the default;
- # apply_common() puts _CRF_DEFAULT back when the flag was absent.
- global _CRF_DEFAULT
- _CRF_DEFAULT = crf.default
- crf.deprecated_default = crf.default # the schema still advertises it (_contract._json_type)
- crf.default = None
- if "deprecated" not in (crf.help or ""):
- # the nine tools that declare --crf with no help string used to fall through this and
- # never show the mark at all (review 9)
- crf.help = (crf.help or "x264 CRF when re-encoding (default 18)") + " (deprecated: use --quality)"
- # only the tools that re-encode (they declare --crf before add_common): one encoder choice
- # resolved in video_args(), the 2.0 encoder abstraction pre-shipped in 1.8 (docs/roadmap.md)
- g.add_argument("--codec", choices=CODECS, default=None,
- help="video encoder for the re-encode: h264 (x264, the default for SDR), hevc (x265, the default for HDR), av1 (SVT-AV1 or libaom), prores (422 HQ, needs a .mov/.mkv output); HDR sources keep their colour on hevc/av1/prores")
- g.add_argument("--quality", type=int, default=None, metavar="N",
- help="encoder quality on the CRF scale (lower = better; 18 visually lossless for x264/x265, up to 63 for av1); overrides --crf, ignored by prores")
-
-
-# The declared default of a deprecated --crf, parked by add_common() (one parser per process).
-_CRF_DEFAULT: Optional[int] = None
-
-
-def apply_common(args: "argparse.Namespace") -> None:
- # Was --crf typed? add_common() parked the flag's default (None in its place) on every tool
- # whose --crf is deprecated, i.e. the ones that also have --quality; export.py's --crf is not
- # an alias and keeps its own default. Scanning sys.argv for "--crf" instead missed the unique
- # prefixes argparse accepts (--cr, --c) and never ran for batch.py's recipe steps (review 9).
- crf_explicit = hasattr(args, "quality") and getattr(args, "crf", None) is not None
- if hasattr(args, "quality") and hasattr(args, "crf") and args.crf is None:
- args.crf = _CRF_DEFAULT
- STATE.plan = getattr(args, "plan", None) or None
- STATE.dry_run = bool(getattr(args, "dry_run", False)) or bool(STATE.plan)
- if STATE.plan:
- # tools that print their document instead of calling emit() (probe, and the analysis
- # tools without --json) still get their plan written, at exit, unless die() ran (review 6)
- import atexit
- atexit.register(_plan_at_exit)
- STATE.json_brief = bool(getattr(args, "json_brief", False))
- # --json-brief is a shorter --json, not a second output mode: it implies it, so a caller that
- # passes only --json-brief still gets a JSON document (and --json --json-brief is the brief one).
- STATE.json = bool(getattr(args, "json", False)) or STATE.json_brief
- STATE.progress = bool(getattr(args, "progress", False))
- STATE.fast = bool(getattr(args, "fast", False))
- STATE.overwrite = bool(getattr(args, "overwrite", False))
- if getattr(args, "timeout", None) is not None:
- STATE.timeout = max(0.0, float(args.timeout))
- if STATE.fast and getattr(args, "preset", None) in X264_PRESETS:
- args.preset = "veryfast"
- STATE.codec = getattr(args, "codec", None) or None
- quality = getattr(args, "quality", None)
- if quality is not None:
- top = 63 if STATE.codec == "av1" else 51
- if not 0 <= int(quality) <= top:
- die(f"--quality must be between 0 and {top} for {STATE.codec or 'h264'} (CRF scale; 18 is visually lossless), got {quality}")
- args.crf = int(quality) # every tool reads args.crf; --quality is the codec-neutral spelling of it
- if STATE.codec == "prores" and hasattr(args, "output"):
- out = getattr(args, "output", None)
- if not out:
- # every tool defaults its output to the source's extension (or .mp4): ProRes in an .mp4
- # fails inside ffmpeg with "codec not currently supported in container" (review 7)
- die("--codec prores needs an explicit -o NAME.mov (or .mkv): the default output name keeps the source's container, which cannot hold ProRes",
- hint="give -o NAME.mov")
- if os.path.splitext(str(out))[1].lower() not in (".mov", ".mkv"):
- die(f"--codec prores needs a .mov (or .mkv) output; {os.path.basename(str(out))} cannot hold ProRes",
- hint="give -o NAME.mov")
- crf = getattr(args, "crf", None)
- # The warning the deprecation policy asks for, only when the caller typed the flag (see
- # crf_explicit above). export.py has no --quality (its preset chooses the encoder), so its
- # --crf is not an alias and is not deprecated: warn only where --quality exists.
- if crf is not None and crf_explicit:
- info("warning: --crf is deprecated since 1.10.0; use --quality N (the same CRF scale, codec-neutral). --crf is removed in 2.0.")
- top = 63 if STATE.codec == "av1" else 51
- if crf is not None and not 0 <= int(crf) <= top:
- die(f"--crf must be between 0 and {top} ({'SVT-AV1' if STATE.codec == 'av1' else 'x264/x265'} scale; 18 is visually lossless), got {crf}")
- install_signal_handlers()
-
-
-# The child processes this tool is waiting on right now (an ffmpeg, or a sibling script under
-# run_tool), with the command whose partial output would need removing. A signal handler
-# reads it; the runners keep it current. Before 1.4.9 a SIGTERM to the tool (a cancelled MCP
-# call, a supervisor's stop, a closed terminal) killed only the Python parent: ffmpeg carried on
-# as an orphan, finished a file nobody verified, and the caller got no JSON at all; SIGINT was a
-# KeyboardInterrupt traceback with the partial left on disk.
-_CHILDREN: List[Tuple[subprocess.Popen, Sequence[str]]] = []
-_SIGNALS_INSTALLED = False
-
-
-def _on_signal(signum: int, frame: Any) -> None:
- import signal as _signal
- name = {getattr(_signal, "SIGINT", None): "SIGINT", getattr(_signal, "SIGTERM", None): "SIGTERM"}.get(signum, str(signum))
- for proc, cmd in list(_CHILDREN):
- try:
- proc.terminate() # ffmpeg exits promptly on SIGTERM; a sibling script runs this same handler
- try:
- proc.wait(timeout=5)
- except subprocess.TimeoutExpired:
- proc.kill()
- proc.wait()
- except OSError:
- pass
- if cmd:
- _cleanup_partial_output(cmd)
- _CHILDREN.clear()
- die(f"interrupted by {name}: the running command was stopped and its partial output removed; nothing was written",
- code=128 + signum, kind="interrupted")
-
-
-def install_signal_handlers() -> None:
- """SIGINT/SIGTERM stop the child, remove its partial output and exit with a failure document
- (kind: interrupted, exit 130/143). Main thread only; on Windows SIGTERM is never delivered,
- SIGINT (Ctrl-C) is."""
- global _SIGNALS_INSTALLED
- if _SIGNALS_INSTALLED:
- return
- import signal as _signal
- import threading
- if threading.current_thread() is not threading.main_thread():
- return
- for sig in (getattr(_signal, "SIGINT", None), getattr(_signal, "SIGTERM", None)):
- if sig is None:
- continue
- try:
- _signal.signal(sig, _on_signal)
- except (ValueError, OSError):
- pass
- _SIGNALS_INSTALLED = True
-
-
-def _watch(proc: subprocess.Popen, cmd: Sequence[str]) -> None:
- _CHILDREN.append((proc, cmd))
-
-
-def _unwatch(proc: subprocess.Popen) -> None:
- _CHILDREN[:] = [(p, c) for p, c in _CHILDREN if p is not proc]
-
-
-def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any) -> None:
- """Final stdout line: the output path, or a JSON document with --json.
-
- `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
- omitted, every read falls back to the process-global STATE as before."""
- ctx = ctx or STATE
- _set_current_ctx(ctx) # so the atexit hook writes (or skips) this ctx's plan, not STATE's
- meta: Dict[str, Any] = {}
- if output and not ctx.dry_run:
- meta = verify_output(output) # dies (status: failed, kind: output) if the artifact is unusable
- if ctx.json:
- doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": ctx.dry_run, "commands": list(ctx.commands)}
- if meta:
- doc["probe"] = meta
- # What this tool itself verified about its artifact (issue #189 C, "verify as part of the
- # contract"): the probe every writing tool runs, plus the measurements a tool adds
- # (`verification` extra: loudness after the write, a platform check). `verified` is true
- # only when the file was written, probed, and every self-check met its target; a dry run
- # verified nothing. Spec failures the tool cannot fix on its own (export's loudness gap)
- # keep status completed and say verified: false, so a caller keys on one field.
- steps: List[Dict[str, Any]] = ([{"step": "probe", "ok": True}] if meta else []) + list(extra.pop("verification", None) or [])
- if output and not ctx.dry_run and os.path.splitext(output)[1].lower() not in MEDIA_EXT:
- steps.insert(0, {"step": "exists", "ok": True})
- doc["verified"] = not ctx.dry_run and bool(steps) and all(s.get("ok") for s in steps)
- doc["verification"] = steps
- doc.update(extra)
- if os.environ.get("FFMPEG_SKILL_RESULT_V2", "") not in ("", "0"):
- doc["result_v2"] = _result_v2(output, meta, dict(extra, verified=doc["verified"], verification=steps))
- if ctx.plan:
- doc["plan"] = write_plan(ctx.plan, output, extra, ctx=ctx)
- print_json(_brief(doc, meta) if ctx.json_brief else doc)
- elif ctx.plan:
- print(write_plan(ctx.plan, output, extra, ctx=ctx))
- elif output:
- print(output)
-
-
-# Keys the brief document replaces or drops: the full probe (summarised), the command lines
-# (counted), the per-step verification list (its verdict stays as `verified`) and the 2.0 preview.
-_BRIEF_DROP = ("probe", "commands", "verification", "result_v2")
-
-
-def _brief_summary(meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
- """The handful of output facts a caller reports or branches on, from the probe this tool
- already ran -- plus the measured loudness when the tool measured one. Keys whose value is
- unknown are left out rather than emitted as null."""
- video = (meta or {}).get("video") or {}
- audio = (meta or {}).get("audio") or {}
- summary: Dict[str, Any] = {}
- duration = (meta or {}).get("duration")
- if duration is not None:
- summary["duration_s"] = round(float(duration), 3)
- for key, value in (("width", video.get("width")), ("height", video.get("height")), ("fps", video.get("fps")),
- ("vcodec", video.get("codec")), ("acodec", audio.get("codec")), ("channels", audio.get("channels"))):
- if value is not None:
- summary[key] = value
- lufs = None
- for source, key in ((extra.get("result"), "input_i"), (extra.get("measured"), "input_i")):
- if lufs is None and isinstance(source, dict):
- lufs = _to_float(source.get(key))
- for step in extra.get("verification") or []:
- if lufs is None and isinstance(step, dict):
- lufs = _to_float(step.get("lufs"))
- # a silent file measures -inf, which json.dumps writes as the non-standard -Infinity: the
- # brief document stays valid JSON by leaving the key out instead (the full document's own
- # `measured`/`result` still carries whatever the tool reported).
- if lufs is not None and math.isfinite(lufs):
- summary["lufs"] = round(lufs, 2)
- return summary
-
-
-def _brief(doc: Dict[str, Any], meta: Dict[str, Any]) -> Dict[str, Any]:
- """--json-brief: the same success document with the bulky parts replaced by what a caller
- acts on. Same keys, same meanings -- `commands` becomes the count of the command lines,
- `probe` becomes `summary` -- plus every tool-specific key the tool itself passed to emit().
- Failures are untouched: die() prints the full failure document either way."""
- brief: Dict[str, Any] = {"status": doc["status"], "output": doc["output"], "dry_run": doc["dry_run"],
- "verified": doc.get("verified", False)}
- summary = _brief_summary(meta, doc)
- if summary:
- brief["summary"] = summary
- brief["commands"] = len(doc.get("commands") or [])
- for key, value in doc.items():
- if key not in brief and key not in _BRIEF_DROP:
- brief[key] = value
- # the emoji report is a full inventory in the long document; brief keeps the two fields a
- # caller branches on (did colour happen, and how many)
- if isinstance(brief.get("emoji"), dict):
- brief["emoji"] = {k: v for k, v in brief["emoji"].items() if k in ("mode", "count")}
- return brief
-
-
-PLAN_VERSION = 1
-_PLAN_STRIP = ("--plan", "--dry-run", "--json")
-
-
-def _plan_at_exit() -> None:
- ctx = _CURRENT_CTX or STATE
- if ctx.plan and not ctx.plan_written:
- try:
- write_plan(ctx.plan, None, {}, ctx=ctx)
- except SystemExit:
- pass
-
-
-def fingerprint(path: str) -> Dict[str, Any]:
- """Size plus a sha256 over the first and last 8 MiB: enough to notice a re-export, a re-trim
- or a swapped file, cheap enough for a multi-GB source (hashing a whole master would make
- planning slower than the edit)."""
- import hashlib
- st = os.stat(path)
- h = hashlib.sha256()
- chunk = 8 * 1024 * 1024
- with open(path, "rb") as f:
- h.update(f.read(chunk))
- if st.st_size > 2 * chunk:
- f.seek(-chunk, os.SEEK_END)
- h.update(f.read(chunk))
- elif st.st_size > chunk:
- h.update(f.read())
- return {"path": os.path.abspath(path), "size": st.st_size, "sha256_head_tail": h.hexdigest()}
-
-
-def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = (), ctx: "Optional[Context]" = None) -> List[str]:
- """Every existing file the plan depends on: the `-i` inputs of the planned commands, any
- existing file named in argv (a recipe, a project, an SRT, a LUT, a still), and the side
- inputs tools register through escape_filter_path() (review 6: only `-i` files were bound)."""
- import shlex
- seen: List[str] = []
- for a in list(argv) + list((ctx or STATE).plan_inputs):
- if a and not a.startswith("-") and os.path.isfile(a) and a not in seen:
- seen.append(a)
- for line in commands:
- try:
- toks = shlex.split(line.split("] ", 1)[1] if line.startswith("[dry-run] ") else line)
- except ValueError:
- continue
- for i, tok in enumerate(toks[:-1]):
- if tok == "-i" and os.path.isfile(toks[i + 1]) and toks[i + 1] not in seen:
- seen.append(toks[i + 1])
- return seen
-
-
-def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Optional[Context]" = None) -> str:
- """The dry run as an artifact: what will run, on which exact inputs, producing what, checked
- how. `render.py PLAN` executes it after re-fingerprinting the inputs (issue #189 C).
-
- `ctx` is the Context whose commands and inputs the plan describes (emit()/die() pass the one
- they were given); omitted, it is the process-global STATE as before."""
- import datetime
- ctx = ctx or STATE
- argv = [a for a in sys.argv[1:]]
- cleaned: List[str] = []
- skip = False
- for a in argv:
- if skip:
- skip = False
- continue
- if a in _PLAN_STRIP:
- skip = a == "--plan"
- continue
- if a.startswith("--plan="):
- continue
- cleaned.append(a)
- tool = os.path.splitext(os.path.basename(sys.argv[0]))[0]
- verify: List[Dict[str, Any]] = [{"tool": "probe"}] if output else []
- platform = None
- if "--platform" in cleaned:
- platform = cleaned[cleaned.index("--platform") + 1]
- elif tool == "export" and "--preset" in cleaned:
- platform = {"youtube": "youtube", "youtube4k": "youtube", "reels": "reels", "x": "x"}.get(cleaned[cleaned.index("--preset") + 1])
- if platform and output and tool != "check":
- verify.append({"tool": "check", "platform": platform})
- doc = {
- "plan_version": PLAN_VERSION,
- "created": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
- "tool": tool,
- "argv": cleaned,
- "cwd": os.getcwd(),
- "inputs": [fingerprint(p) for p in _plan_inputs(ctx.commands, cleaned, ctx)],
- "commands": list(ctx.commands),
- "output": os.path.abspath(output) if output else None,
- "verify": verify,
- "notes": list(extra.get("notes") or []),
- }
- try:
- tmp = f"{path}.tmp{os.getpid()}"
- with open(tmp, "w", encoding="utf-8") as f:
- json.dump(doc, f, indent=2, ensure_ascii=False)
- f.write("\n")
- os.replace(tmp, path)
- except OSError as exc:
- die(f"cannot write plan {path}: {exc}", kind="output")
- ctx.plan_written = True
- info(f"plan written: {path} ({len(doc['commands'])} command(s), {len(doc['inputs'])} input(s)); run it with render.py {path}", ctx)
- return path
-
-
-_V2_HANDLED = ("result", "measured", "notes", "dropped_non_av_streams", "verified", "verification")
-
-
-def _result_v2(output: Optional[str], meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
- """The 2.0 success-document shape, previewed in 1.x as a parallel `result_v2` key when
- FFMPEG_SKILL_RESULT_V2=1 (issue #189 B). Every tool gets the same six slots: `output`,
- `probe`, `commands`, `metrics` (numbers a caller keys on: loudness's `result`/`measured`
- dicts flattened, plus every top-level numeric extra such as `expected_duration` or
- `offset_seconds`), `notes` (free text), `dropped` (what did not make it into the output),
- and `details` (the tool's remaining extras, unchanged). The 1.x keys stay where they are;
- this key is additive and its shape is what 2.0 promotes to the top level."""
- metrics: Dict[str, Any] = {}
- for key in ("measured", "result"):
- if isinstance(extra.get(key), dict):
- metrics.update(extra[key])
- for key, value in extra.items():
- if key not in _V2_HANDLED and isinstance(value, (int, float)) and not isinstance(value, bool):
- metrics[key] = value
- notes = extra.get("notes")
- return {
- "schema": 2,
- "output": output,
- "probe": meta or None,
- "commands": list(STATE.commands),
- "metrics": metrics,
- "notes": list(notes) if isinstance(notes, (list, tuple)) else ([notes] if notes else []),
- "dropped": {"non_av_streams": bool(extra.get("dropped_non_av_streams", False))},
- "verified": bool(extra.get("verified", False)),
- "verification": list(extra.get("verification") or []),
- "details": {k: v for k, v in extra.items() if k not in _V2_HANDLED and k not in metrics},
- }
-
-
-def _cmdline(cmd: Sequence[str]) -> str:
- return " ".join(shell_quote(c) for c in cmd)
-
-
-def _is_ffmpeg(cmd: Sequence[str]) -> bool:
- return os.path.basename(cmd[0]).startswith("ffmpeg")
-
-
-def _cleanup_partial_output(cmd: Sequence[str]) -> None:
- """A failed ffmpeg command can still have opened its output container (muxer header
- written) before erroring out mid-stream -- unlike a failure that happens before ffmpeg ever
- touches the output path (a bad filter argument, a missing input), which never creates the
- file at all. Both are reported the same way (status: failed), but only the first case used
- to leave a stray, usually-0-byte file behind: verify_output()'s cleanup only runs on the
- success path, so a failed run() call never routed through it. Remove whatever ffmpeg managed
- to write so a caller scanning the output directory after a failure never mistakes a partial
- artifact for a real (if unverified) one."""
- # run() also executes ffprobe, whose last argument is an INPUT. Never
- # interpret a read-only tool's failure as permission to remove that file.
- if not _is_ffmpeg(cmd):
- return
- output = cmd[-1]
- if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):
- return
- try:
- if not os.path.exists(output):
- return
- # A file that was already there before this command ran is someone's deliverable, not
- # our partial. If ffmpeg died before opening it (bad filter argument, unreadable input:
- # the common case) it is byte-for-byte what it was, so leave it alone. Only when ffmpeg
- # did open and truncate it (size or mtime changed) is what remains a partial of ours,
- # and the original is already gone either way; then removing it is still right.
- before = STATE.preexisting.get(os.path.realpath(output))
- if before is not None:
- st = os.stat(output)
- if (st.st_size, st.st_mtime_ns) == before:
- return
- os.remove(output)
- except OSError:
- pass
-
-
-def _fail(cmd: Sequence[str], returncode: int, stderr: str) -> None:
- # Partial-output cleanup already ran in the caller (_run_captured/_run_with_progress) for
- # every failed ffmpeg invocation, not just this check=True path -- see _cleanup_partial_output.
- # The process exit code is always 1 for an ffmpeg failure: ffmpeg's own code (1, 69, 218, 234,
- # a negative signal number...) varies by build and by the failing stage, and 124/127/130/143
- # are reserved for timeout, missing tool and interrupts. The raw code is kept in the JSON
- # document as `ffmpeg_returncode` for a caller that wants it. docs/design-decisions.md.
- tail = "\n".join(stderr.strip().splitlines()[-15:])
- die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=1, kind="ffmpeg", ffmpeg_returncode=returncode)
-
-
-def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
- """Refuse an ffmpeg command whose output path resolves to the same file as one of its
- inputs. ffmpeg's own "Output same as Input" guard only catches byte-identical path
- strings; a relative/absolute pair, a leading "./", a redundant ".." segment, or a symlink
- all resolve to the same file but pass that check, so "-o ./same.mp4" on an input opened as
- "same.mp4" would otherwise silently let ffmpeg's -y clobber the source mid-encode. Every
- write-side script routes through this one run() choke point rather than each computing its
- own output path defensively, so the guard lives here once instead of at 25+ call sites."""
- output = cmd[-1]
- if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):
- return
- try:
- out_real = os.path.realpath(output)
- except OSError:
- return
- for i, a in enumerate(cmd):
- if a == "-i" and i + 1 < len(cmd):
- inp = cmd[i + 1]
- try:
- if os.path.realpath(inp) == out_real:
- die(f"refusing to run: output {output!r} is the same file as input {inp!r} "
- f"(would overwrite it while ffmpeg is still reading it) -- choose a different --output/-o path",
- kind="input")
- except OSError:
- continue
-
-
-def refuse_output_is_input(output: str, *inputs: str) -> None:
- """Tool-level twin of the run() guard, for tools whose final ffmpeg command does not name
- the user's input at all. `cut.py --segments` cuts each part into a temp dir and then concats
- a list file: the last command's only `-i` is that list, so `-o` equal to the input sailed
- through _check_no_overwrite_input() and replaced the source with the join (fourth audit,
- P0). Call it once the output path is known, before any part of the input is consumed."""
- try:
- out_real = os.path.realpath(output)
- except OSError:
- return
- for inp in inputs:
- try:
- same = os.path.realpath(inp) == out_real
- except OSError:
- continue
- if same:
- die(f"refusing to run: output {output!r} is the same file as input {inp!r} "
- f"(the result would replace the source) -- choose a different --output/-o path", kind="input")
-
-
-def _check_output_path(cmd: Sequence[str]) -> None:
- """An output whose directory does not exist, or that names a directory, is a caller mistake:
- say so as `kind: input` before ffmpeg runs, instead of the muxer's "No such file or directory"
- as `kind: ffmpeg` (which reads as an encoder failure) or an `OUTPUT_INVALID` after the fact."""
- output = cmd[-1]
- if output == "-" or output.startswith("pipe:") or output.startswith("-"):
- return
- if os.path.isdir(output):
- die(f"output {output!r} is a directory; pass a file path (e.g. {os.path.join(output, 'result.mp4')!r})")
- parent = os.path.dirname(os.path.abspath(output))
- if not os.path.isdir(parent):
- die(f"output directory {parent!r} does not exist; create it first (this tool never creates directories)")
- if not os.access(parent, os.W_OK):
- die(f"output directory {parent!r} is not writable")
-
-
-EVEN_SCALE = "scale=trunc(iw/2)*2:trunc(ih/2)*2"
-
-
-def _pid_dead(pid: int) -> bool:
- """True only when the process is known not to exist. POSIX: signal 0. Windows: OpenProcess
- fails with ERROR_INVALID_PARAMETER (87) for a pid that is not in use; any other outcome
- (a handle, or access denied) means it is live. Unknown is treated as live."""
- if os.name != "nt":
- try:
- os.kill(pid, 0)
- except ProcessLookupError:
- return True
- except OSError:
- pass
- return False
- try:
- import ctypes
- k32 = ctypes.windll.kernel32 # type: ignore[attr-defined]
- handle = k32.OpenProcess(0x1000, False, pid) # PROCESS_QUERY_LIMITED_INFORMATION
- if handle:
- k32.CloseHandle(handle)
- return False
- return k32.GetLastError() == 87
- except Exception:
- return False
-
-
-class _OutputLock:
- """Two runs writing the same output at once used to both report `completed` while one of
- them described the other's file (sweep F1). A lock file next to the output, created with
- O_EXCL and holding the writer's pid, makes the second run refuse as `kind: input`. A lock
- whose pid is dead (POSIX) or older than an hour is stale and taken over."""
- def __init__(self, output: str) -> None:
- self.path: Optional[str] = None
- self.fd: Optional[int] = None
- if output == "-" or output.startswith("pipe:") or output.startswith("-"):
- return
- d, base = os.path.split(os.path.abspath(output))
- self.path = os.path.join(d, f".{base}.ffskill-lock")
-
- def __enter__(self) -> "_OutputLock":
- if not self.path:
- return self
- for attempt in (0, 1):
- try:
- self.fd = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
- os.write(self.fd, str(os.getpid()).encode())
- return self
- except FileExistsError:
- if attempt == 0 and self._stale():
- try:
- os.remove(self.path)
- except OSError:
- pass
- continue
- die(f"another run is writing {os.path.basename(self.path)[1:-len('.ffskill-lock')]!r} right now "
- f"(lock {self.path}); wait for it or choose a different --output/-o path")
- except OSError:
- return self # unlockable location (read-only dir surfaces elsewhere): proceed without a lock
- return self
-
- def _stale(self) -> bool:
- try:
- pid = int(open(self.path).read().strip() or "0")
- if pid > 0 and _pid_dead(pid):
- return True
- import time
- return time.time() - os.path.getmtime(self.path) > 3600
- except (OSError, ValueError):
- return True
-
- def __exit__(self, *exc: Any) -> None:
- if self.fd is not None:
- try:
- os.close(self.fd)
- except OSError:
- pass
- if self.path:
- try:
- os.remove(self.path)
- except OSError:
- pass
-
-
-def _odd_dimension_retry(cmd: List[str], stderr: str) -> Optional[List[str]]:
- """An odd-sized source (641x359 screen captures, some 4:4:4 masters) fails every yuv420p
- encode with "width/height not divisible by 2" (sweep F8, 15 tools). Return the same command
- with an even-dimension scale prepended to its -vf chain (or a new -vf when the command had
- none); None when the failure is something else or the graph is a -filter_complex the
- caller has to fix itself."""
- if "not divisible by 2" not in stderr or EVEN_SCALE in cmd or any(EVEN_SCALE in a for a in cmd):
- return None
- if "-filter_complex" in cmd:
- return None
- new = list(cmd)
- if "-vf" in new:
- i = new.index("-vf") + 1
- new[i] = EVEN_SCALE + "," + new[i]
- return new
- if "-c:v" in new and new[new.index("-c:v") + 1] == "copy":
- return None
- return new[:-1] + ["-vf", EVEN_SCALE, new[-1]]
-
-
-def _check_existing_output(cmd: Sequence[str]) -> None:
- """An output path that already exists is someone's file: a previous result, a source the
- agent mis-named, a deliverable from another run. ffmpeg's -y (which every command carries so
- a run never blocks on a y/N prompt) would replace it without a word. Until 2.0 this only
- warns, per docs/contract.md's deprecation policy; FFMPEG_SKILL_NO_OVERWRITE=1 opts into the
- 2.0 behaviour (refuse) today, and --overwrite is the explicit consent either way. Paths this
- process wrote itself (a two-pass tool, a copy-then-re-encode fallback) are never in question."""
- output = cmd[-1]
- if output in ("-",) or output.startswith("pipe:") or output.startswith("-"):
- return
- try:
- exists = os.path.isfile(output)
- real = os.path.realpath(output)
- except OSError:
- return
- if not exists or real in STATE.written:
- return
- try:
- st = os.stat(output)
- STATE.preexisting[real] = (st.st_size, st.st_mtime_ns)
- except OSError:
- pass
- if STATE.overwrite:
- return
- if os.environ.get("FFMPEG_SKILL_NO_OVERWRITE", "") not in ("", "0"):
- die(f"refusing to overwrite existing output {output!r}: pass --overwrite to replace it, or choose another -o path", kind="input")
- info(f"warning: {output} already exists and will be overwritten (pass --overwrite to confirm; "
- f"from 2.0 an existing output is refused without it, FFMPEG_SKILL_NO_OVERWRITE=1 enables that now)")
-
-
-def _remember_output(cmd: Sequence[str]) -> None:
- output = cmd[-1]
- if output == "-" or output.startswith("pipe:") or output.startswith("-"):
- return
- try:
- STATE.written.add(os.path.realpath(output))
- except OSError:
- pass
-
-
-def _timed_out(cmd: Sequence[str], seconds: float) -> "None":
- _cleanup_partial_output(cmd)
- die(f"{os.path.basename(cmd[0])} exceeded the {seconds:.0f} s time limit and was killed; nothing was written. "
- f"Raise --timeout (or FFMPEG_SKILL_TIMEOUT) if the job is genuinely that long, or check the input for a stall",
- code=124, kind="timeout")
-
-
-def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str], Optional[str]]:
- """When the output path already holds someone's file, run ffmpeg against a hidden sibling
- temp path and move it over the original only on success.
-
- ffmpeg's -y truncates the output the moment it opens it, and *when* it opens it depends on
- the version: 6.1+ initialises the filter graph first (a bad LUT fails before the file is
- touched), 5.x opens the output during option parsing, before any filter runs, so the same
- bad LUT leaves a 0-byte file where the deliverable was. No amount of post-failure cleanup
- can undo that; the only way to keep an existing file safe across a failed run is for ffmpeg
- never to write to it. Same directory, same extension (the muxer is chosen by it), hidden
- name, so nothing else changes for the encoder. Returns (command to execute, final path,
- temp path); (cmd, None, None) when no staging is needed."""
- output = cmd[-1]
- if output == "-" or output.startswith("pipe:") or output.startswith("-"):
- return list(cmd), None, None
- try:
- if not os.path.isfile(output) or os.path.realpath(output) in STATE.written:
- return list(cmd), None, None
- except OSError:
- return list(cmd), None, None
- d, base = os.path.split(output)
- stem, ext = os.path.splitext(base)
- tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
- return list(cmd[:-1]) + [tmp], output, tmp
-
-
-def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Optional[Context]" = None) -> subprocess.CompletedProcess:
- """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.
-
- ffmpeg invocations are recorded in STATE.commands (for --json), skipped under --dry-run
- (a fake successful CompletedProcess is returned so scripts can keep planning), and run
- with a progress readout under --progress. ffprobe and other tools always run. An output
- path that already exists is written through a temp file and replaced only on success
- (see _stage_existing_output), so a failed run never costs the caller the file that was there.
-
- `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
- omitted, the commands and flags are read from the process-global STATE as before.
- """
- ctx = ctx or STATE
- is_ffmpeg = _is_ffmpeg(cmd)
- if is_ffmpeg:
- _check_no_overwrite_input(cmd)
- _check_output_path(cmd)
- _check_existing_output(cmd)
- ctx.commands.append(_cmdline(cmd))
- if not quiet:
- info(("[dry-run] $ " if ctx.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd), ctx=ctx)
- if ctx.dry_run and is_ffmpeg:
- return subprocess.CompletedProcess(list(cmd), 0, "", "")
- if is_ffmpeg:
- flush_drawtext_textfiles(cmd)
- with _OutputLock(cmd[-1] if is_ffmpeg else "-"):
- exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
- proc = _execute(exec_cmd)
- if proc.returncode != 0 and is_ffmpeg:
- retry = _odd_dimension_retry(exec_cmd, proc.stderr or "")
- if retry is not None:
- info("source has odd dimensions; scaling to even before encoding (yuv420p needs it)")
- ctx.commands[-1] = _cmdline(retry[:-1] + [cmd[-1]])
- proc = _execute(retry)
- elif "not divisible by 2" in (proc.stderr or ""):
- die("the source has odd dimensions (width or height not divisible by 2) and this tool's filter graph "
- "cannot pad them itself; make them even first, e.g. fit.py --width/--height, then retry",
- kind="input")
- if proc.returncode != 0 and check:
- _fail(exec_cmd, proc.returncode, proc.stderr or "")
- if final and tmp:
- if proc.returncode == 0:
- try:
- os.replace(tmp, final)
- except OSError as e:
- _cleanup_partial_output(exec_cmd)
- die(f"could not replace {final} with the new output: {e}", kind="output")
- _remember_output(cmd)
- else:
- _cleanup_partial_output(exec_cmd)
- return proc
-
-
-def _execute(exec_cmd: List[str]) -> subprocess.CompletedProcess:
- """One attempt, never exiting on failure (run() decides after its retries)."""
- if STATE.progress and _is_ffmpeg(exec_cmd) and exec_cmd[-1] != "-":
- return _run_with_progress(exec_cmd, False)
- return _run_captured(exec_cmd, False)
-
-
-def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, record: bool = False) -> subprocess.CompletedProcess:
- """Run an ffmpeg *measurement* (scene scores, crop rectangles, decoded PCM, signal stats,
- silence detection, loudness, stabilisation pass 1): output to `-f null`, a pipe or a temp
- file, no deliverable written. These are not run() calls -- they run under --dry-run too,
- since a plan built on a fake measurement is not a plan (silence.py used to report "0
- silences" and loudness.py a made-up -20 LUFS under --dry-run) -- but they get the same
- wall-clock limit as any other ffmpeg invocation and, with check=True, the same `kind: ffmpeg`
- failure instead of an exit-0 "0 scenes found" over a file ffmpeg could not read. record=True
- lists the command in the --json `commands` like run() does."""
- if record:
- STATE.commands.append(_cmdline(cmd))
- limit = _limit_for(cmd)
- try:
- proc = subprocess.run(list(cmd), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=text, timeout=limit)
- except subprocess.TimeoutExpired:
- _timed_out(cmd, limit or 0)
- if check and proc.returncode != 0:
- err = proc.stderr if text else proc.stderr.decode(errors="replace")
- _fail(cmd, proc.returncode, err)
- return proc
-
-
-def dry_run_input_pending(path: str) -> bool:
- """True when a measurement cannot run because its input does not exist yet under --dry-run:
- in a render.py/batch.py plan each stage's input is the previous stage's output, which a dry
- run never wrote. The measurement is then skipped (with a note) rather than failing the plan;
- on a real file the measurement runs even under --dry-run."""
- if STATE.dry_run and not os.path.exists(path):
- info(f"[dry-run] {path} does not exist yet (an earlier dry-run stage would write it); measurement skipped")
- return True
- return False
-
-
-def child_limit(per_call: Optional[float] = None) -> Optional[float]:
- """Wall-clock ceiling for running one sibling script as a subprocess (render/batch/report
- stages, the MCP server's dispatch). A tool runs a handful of ffmpeg/ffprobe calls, each
- under its own --timeout, so the outer ceiling is a multiple of that plus a margin: it never
- fires first on a healthy run, and it is the only thing that ends a child hung for a reason
- that is not ffmpeg (a stuck import, a wedged pipe). None when the per-call limit is 0."""
- limit = STATE.timeout if per_call is None else per_call
- return (limit * 4 + 60) if limit else None
-
-
-def run_tool(argv: Sequence[str], *, per_call: Optional[float] = None) -> subprocess.CompletedProcess:
- """Run a sibling script (`argv[0]` is the script path) under child_limit(). On overrun the
- child is killed and a CompletedProcess is returned whose stdout is this skill's own failure
- document (kind timeout, exit 124), so callers that parse the child's --json see a timeout
- exactly as they would from the child itself."""
- limit = child_limit(per_call)
- child = subprocess.Popen([sys.executable] + list(argv), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
- _watch(child, []) # a sibling script removes its own partial output; there is none of ours to clean
- try:
- out, err = child.communicate(timeout=limit)
- _unwatch(child)
- return subprocess.CompletedProcess(child.args, child.returncode, out, err)
- except subprocess.TimeoutExpired as e:
- child.kill()
- child.communicate()
- _unwatch(child)
- name = os.path.basename(str(argv[0]))
- msg = f"{name} did not finish within {limit:.0f} s (4x the per-ffmpeg --timeout plus 60 s) and was killed"
- doc = {"status": "failed", "exit_code": 124,
- "error": {"kind": "timeout", "message": msg, "code": ERROR_CODE["timeout"], "retryable": ERROR_RETRYABLE},
- "commands": []}
- partial = e.stderr.decode(errors="replace") if isinstance(e.stderr, bytes) else (e.stderr or "")
- return subprocess.CompletedProcess(list(argv), 124, json.dumps(doc), partial + f"\nerror: {msg}\n")
-
-
-def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None, start: float = 0.0,
- *, check: bool = True) -> List[float]:
- """Decode (part of) a file's audio to mono float samples in [-1, 1) at `sample_rate` via a
- single ffmpeg pass under --timeout. Shared by scenes.py (audio envelope for cut scoring) and
- sync.py (cross-correlation); an undecodable input is kind ffmpeg when check=True, else []."""
- ffmpeg = require_tool("ffmpeg")
- cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin"]
- if start:
- cmd += ["-ss", f"{start:.3f}"]
- cmd += ["-i", path]
- if seconds is not None:
- cmd += ["-t", f"{seconds:.3f}"]
- cmd += ["-vn", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
- proc = run_analysis(cmd, check=False, text=False)
- if proc.returncode != 0 or not proc.stdout:
- if check:
- die(f"could not decode audio from {path}:\n{proc.stderr.decode(errors='replace').strip()}", kind="ffmpeg")
- return []
- n = len(proc.stdout) // 2
- import struct
- return [v / 32768.0 for v in struct.unpack(f"<{n}h", proc.stdout[: n * 2])]
-
-
-def rms_envelope(samples: Sequence[float], step: int, *, full_blocks_only: bool = False, remove_mean: bool = False) -> List[float]:
- """RMS per block of `step` samples. full_blocks_only drops a short tail block (sync.py: every
- block must be the same length for the correlation); remove_mean subtracts the envelope's mean
- (sync.py: so silence does not correlate). scenes.py keeps the tail and the absolute level."""
- step = max(1, int(step))
- n = len(samples)
- stop = n - step + 1 if full_blocks_only else n
- env: List[float] = []
- for i in range(0, max(0, stop), step):
- block = samples[i:i + step]
- env.append(math.sqrt(sum(x * x for x in block) / len(block)))
- if remove_mean and env:
- mean = sum(env) / len(env)
- env = [e - mean for e in env]
- return env
-
-
-def child_args() -> List[str]:
- """The shared flags a tool that runs sibling scripts (render.py, batch.py) forwards to them,
- so one `--timeout`/`--overwrite`/`--fast`/`--dry-run` on the outer command governs every
- stage. Before 1.4.3 only --fast and --dry-run were forwarded; a --timeout given to render.py
- stopped at render.py."""
- args: List[str] = []
- if STATE.fast:
- args.append("--fast")
- if STATE.dry_run:
- args.append("--dry-run")
- if STATE.overwrite:
- args.append("--overwrite")
- args += ["--timeout", f"{STATE.timeout:g}"]
- return args
-
-
-def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
- """Run an ffmpeg command that already maps its video/audio, trying first to also
- stream-copy any subtitle/data streams the source has (`-map 0:s?`/`0:d?` are no-ops when
- there are none). A source whose subtitle codec cannot be copied into the target container
- (e.g. a container change) makes that first attempt fail; retry the same command without the
- extra maps rather than let a tool that never touched subtitles start hard-failing because of
- them. `cmd` is the full argv *without* the output path. Returns True only when the
- retry-without-subtitles path was actually needed (i.e. subtitle/data streams were dropped)."""
- if run(cmd + ["-map", "0:s?", "-map", "0:d?", "-c:s", "copy", "-c:d", "copy", output], check=False).returncode == 0:
- return False
- run(cmd + [output])
- return True
-
-
-def _limit_for(cmd: Sequence[str]) -> Optional[float]:
- """The wall-clock ceiling for this command: ffprobe (and other read-only probes) get a fixed
- short one, ffmpeg the configured one; None means unlimited."""
- if not _is_ffmpeg(cmd):
- return PROBE_TIMEOUT if STATE.timeout else None
- return STATE.timeout or None
-
-
-def _run_captured(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
- """Plain run with stdout/stderr captured."""
- limit = _limit_for(cmd)
- child = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
- _watch(child, cmd)
- try:
- out, err = child.communicate(timeout=limit)
- except subprocess.TimeoutExpired:
- child.kill()
- child.communicate()
- _unwatch(child)
- _timed_out(cmd, limit or 0)
- finally:
- _unwatch(child)
- proc = subprocess.CompletedProcess(list(cmd), child.returncode, out, err)
- if proc.returncode == 0 and _is_ffmpeg(cmd):
- _remember_output(cmd)
- if proc.returncode != 0:
- # Cleanup happens for every failed ffmpeg invocation, not just the check=True/_fail()
- # path: a handful of scripts (cut.py, loudness.py, silence.py, sync.py) call run() with
- # check=False so they can compose their own die() message from proc.stderr, but the
- # partial-output risk is identical either way -- and for a script that retries into the
- # same output path after a check=False failure (e.g. color.py's --retag copy-then-
- # reencode fallback), removing the stale partial first is strictly safer than leaving it
- # for -y to overwrite.
- _cleanup_partial_output(cmd)
- if check:
- _fail(cmd, proc.returncode, proc.stderr)
- return proc
-
-
-def _progress_line(done: float, total: float, elapsed: float) -> str:
- if total > 0:
- pct = min(99.9, done / total * 100)
- eta = (elapsed / pct * (100 - pct)) if pct > 0.5 else 0
- return f"\r {pct:5.1f}% {done:7.1f}s / {total:.1f}s ETA {eta:4.0f}s"
- return f"\r {done:7.1f}s encoded"
-
-
-def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
- """Run ffmpeg with -progress on a pipe and print percent/ETA to stderr.
-
- The time limit is checked on a clock, not per progress line: a deadlocked ffmpeg (the very
- case --timeout exists for) prints nothing, so a loop that only looked at the deadline when a
- line arrived waited on it forever. Reader threads drain both pipes; the main loop wakes at
- least twice a second to compare the clock against the limit."""
- import queue
- import threading
- import time
- total = STATE.duration_hint or 0.0
- full = cmd[:1] + ["-progress", "pipe:1", "-nostats"] + cmd[1:]
- t0 = time.time()
- limit = _limit_for(cmd)
- proc = subprocess.Popen(full, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
- _watch(proc, cmd)
- assert proc.stdout is not None and proc.stderr is not None
- lines: "queue.Queue[Optional[str]]" = queue.Queue()
- err_chunks: List[str] = []
-
- def pump_out() -> None:
- for line in proc.stdout: # type: ignore[union-attr]
- lines.put(line)
- lines.put(None)
-
- def pump_err() -> None:
- err_chunks.append(proc.stderr.read()) # type: ignore[union-attr]
-
- threading.Thread(target=pump_out, daemon=True).start()
- err_thread = threading.Thread(target=pump_err, daemon=True)
- err_thread.start()
- last = ""
-
- def clear_line() -> None:
- if last:
- sys.stderr.write("\r" + " " * len(last) + "\r")
-
- def timed_out() -> None:
- proc.kill()
- proc.wait()
- clear_line()
- _timed_out(cmd, limit or 0)
-
- while True:
- remaining = (limit - (time.time() - t0)) if limit else None
- if remaining is not None and remaining <= 0:
- timed_out()
- try:
- line = lines.get(timeout=min(0.5, remaining) if remaining is not None else 0.5)
- except queue.Empty:
- continue
- if line is None:
- break
- if line.startswith("out_time_us=") or line.startswith("out_time_ms="):
- try:
- done = int(line.split("=")[1]) / 1_000_000
- except ValueError:
- continue
- msg = _progress_line(done, total, time.time() - t0)
- if msg != last:
- sys.stderr.write(msg)
- sys.stderr.flush()
- last = msg
- try:
- proc.wait(timeout=(max(5.0, limit - (time.time() - t0)) if limit else None))
- except subprocess.TimeoutExpired:
- timed_out()
- _unwatch(proc)
- err_thread.join()
- err = "".join(err_chunks)
- clear_line()
- if proc.returncode == 0:
- _remember_output(cmd)
- if proc.returncode != 0:
- _cleanup_partial_output(cmd)
- if check:
- _fail(cmd, proc.returncode, err)
- return subprocess.CompletedProcess(full, proc.returncode, "", err)
-
-
-def shell_quote(s: str) -> str:
- if not s or any(ch in s for ch in " \t\n\r\\\"';|&<>()[]{}$*?"):
- 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
-
-
-MEDIA_EXT = {".mp4", ".mov", ".mkv", ".webm", ".m4v", ".avi", ".ts", ".mts", ".m2ts", ".mxf", ".3gp", ".wmv", ".gif",
- ".wav", ".flac", ".mp3", ".m4a", ".aac", ".ogg", ".opus", ".aif", ".aiff", ".caf", ".wma", ".png", ".jpg", ".jpeg", ".webp"}
-
-
-def _output_failed(path: str, why: str) -> "None":
- """An ffmpeg run reported success but the artifact is not usable: say so, and do not leave a
- 0-byte file behind that a later step could mistake for a result."""
- try:
- if os.path.exists(path) and os.path.getsize(path) == 0:
- os.remove(path)
- why += " (empty file removed)"
- except OSError:
- pass
- die(f"output verification failed: {path}: {why}", kind="output")
-
-
-def verify_output(path: str) -> Dict[str, Any]:
- """The success criterion for every writing tool: the file exists, is not empty and ffprobe
- can read at least one stream from it. Non-media artifacts (srt, edl, html, md) only need to
- exist and be non-empty. Returns the probe (empty dict for non-media)."""
- if not os.path.exists(path):
- _output_failed(path, "not written")
- if os.path.getsize(path) == 0:
- _output_failed(path, "0 bytes")
- if os.path.splitext(path)[1].lower() not in MEDIA_EXT:
- return {}
- meta = probe(path, role="output")
- if not meta.get("video") and not meta.get("audio"):
- _output_failed(path, "no video or audio stream")
- return meta
-
-
-def probe(path: str, role: str = "input") -> Dict[str, Any]:
- """Return a compact, script-friendly description of a media file.
-
- role="output" marks a file this tool just wrote: a read failure is then reported as an
- output-verification failure (kind "output") instead of an input problem."""
- if not os.path.exists(path):
- if role == "output" and not STATE.dry_run:
- _output_failed(path, "not written")
- if STATE.dry_run:
- # width/height/fps are honestly 0/0/0.0 -- "not measured", matching duration/size_bytes
- # below -- because this is a dry run: the file doesn't exist yet, so there is nothing to
- # probe. Earlier this stub used plausible-looking placeholders (1920x1080x30.0) instead,
- # which some tools' dry-run summary line echoed verbatim as if it were a real computed
- # preview (#77). That was reverted once, because a couple of call sites divided by these
- # values for aspect-ratio math and crashed on a real 0 (join.py, fit.py); those call
- # sites are now guarded to treat 0 as "unknown" and fall back sanely instead of dividing
- # by it, so the stub can finally report the honest, unknown value.
- return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,
- "video": {"codec": None, "width": 0, "height": 0, "fps": 0.0, "pix_fmt": None, "hdr": False,
- "color_transfer": None, "color_primaries": None, "rotation": 0, "variable_frame_rate_suspected": False},
- "audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0, "data_streams": 0}
- die(f"input not found: {path}")
- ffprobe = require_tool("ffprobe")
- proc = run(
- [ffprobe, "-v", "error", "-print_format", "json", "-show_format", "-show_streams", "-show_chapters", path],
- quiet=True,
- check=False,
- )
- if proc.returncode != 0:
- if role == "output":
- _output_failed(path, f"ffprobe cannot read it:\n{proc.stderr.strip()}")
- die(f"ffprobe failed on {path}:\n{proc.stderr.strip()}")
- try:
- raw = json.loads(proc.stdout or "{}")
- except ValueError as e:
- if role == "output":
- _output_failed(path, f"ffprobe printed unreadable JSON: {e}")
- die(f"ffprobe printed unreadable JSON for {path}: {e}", kind="ffmpeg")
- 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"]
- data_stream_count = sum(1 for s in streams if s.get("codec_type") in ("data", "attachment"))
-
- 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"))
- if duration and STATE.duration_hint is None:
- STATE.duration_hint = 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),
- "data_streams": data_stream_count,
- # container-level chapter markers and the common tags, so metadata.py's result is
- # verifiable the same way every other tool's is (additive keys, 1.x-safe)
- "chapters": [{
- "index": n,
- "start": _to_float(ch.get("start_time")),
- "end": _to_float(ch.get("end_time")),
- "title": (ch.get("tags") or {}).get("title"),
- } for n, ch in enumerate(raw.get("chapters") or [])],
- "tags": {k.lower(): v for k, v in (fmt.get("tags") or {}).items() if k.lower() in ("title", "artist", "album", "comment", "date", "genre")},
- # every subtitle stream in file order: index n here is `-map 0:s:n`
- "subtitle_stream_details": [{
- "index": n,
- "codec": s.get("codec_name"),
- "language": (s.get("tags") or {}).get("language"),
- "title": (s.get("tags") or {}).get("title"),
- } for n, s in enumerate(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
- pix = video.get("pix_fmt") or ""
- trc = video.get("color_transfer") or ""
- prim = video.get("color_primaries") or ""
- hdr = trc in ("smpte2084", "arib-std-b67") or prim == "bt2020"
- dovi = None
- for sd in video.get("side_data_list", []) or []:
- if "dv_profile" in sd or "DOVI" in str(sd.get("side_data_type", "")):
- dovi = {"profile": sd.get("dv_profile"), "level": sd.get("dv_level"), "bl_compatibility_id": sd.get("dv_bl_signal_compatibility_id")}
- if dovi: # a Dolby Vision stream is HDR even when its base layer tags are missing
- hdr = True
- 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"),
- "bit_depth": _bit_depth(pix),
- "hdr": hdr,
- # 1.9 (2.0 A1 pre-shipped as a parallel key): true only for a PQ / HLG transfer or Dolby
- # Vision, i.e. a genuinely HDR signal. `hdr` also counts BT.2020 primaries on an SDR
- # transfer ("BT.2020 SDR" in hdr_format) and keeps that meaning until 2.0 renames it.
- "hdr_signal": trc in ("smpte2084", "arib-std-b67") or bool(dovi),
- "hdr_format": (("Dolby Vision %s" % (("profile %s" % dovi["profile"]) if dovi and dovi.get("profile") is not None else "")).strip() if dovi else
- "HDR10/PQ" if trc == "smpte2084" else "HLG" if trc == "arib-std-b67" else "BT.2020 SDR" if hdr else None),
- "dolby_vision": dovi,
- "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")),
- }
- # every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)
- out["audio_streams"] = [{
- "index": n,
- "codec": a.get("codec_name"),
- "channels": _to_int(a.get("channels")),
- "channel_layout": a.get("channel_layout"),
- "sample_rate": _to_int(a.get("sample_rate")),
- "language": (a.get("tags") or {}).get("language"),
- "title": (a.get("tags") or {}).get("title"),
- } for n, a in enumerate(s for s in streams if s.get("codec_type") == "audio")]
- 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}"))
-
-
-class MissingFpsError(ValueError):
- """parse_time() saw an hh:mm:ss:ff SMPTE timecode but no fps was given to convert it -- distinct
- from a plain ValueError so a caller that falls back to treating unparseable text as a literal
- line (e.g. caption.py's free-text cue format) can still fail loudly on this one, instead of
- silently swallowing a mistyped/missing --fps as an auto-timed line of digits."""
-
-
-def concat_list_line(path: str) -> str:
- """One `file '...'` line for the concat demuxer. The demuxer reads backslash as an escape
- inside the quoted form, so a Windows path (C:\\Users\\...\\part000.mp4) must be written
- with forward slashes -- ffmpeg opens either spelling on Windows -- and a single quote in the
- name is closed, escaped and reopened. Shared by cut.py (multi-segment) and sequence.py."""
- escaped = str(path).replace("\\", "/").replace("'", "'\\''")
- return f"file '{escaped}'"
-
-
-def _bit_depth(pix_fmt: Optional[str]) -> int:
- """Bits per component from a pixel format name. `"10" in pix` used to read yuv410p (4:1:0
- chroma) as 10-bit; the depth is the number that ends the name (before an le/be suffix):
- yuv420p10le -> 10, gbrp12be -> 12, gray16le -> 16, yuv410p / yuv420p / rgb24 -> 8."""
- m = re.search(r"(\d{1,2})(?:le|be)?$", pix_fmt or "")
- if not m:
- return 8
- n = int(m.group(1))
- if n in (24, 32): # packed 8-bit rgb24/bgr32/rgb0 etc.
- return 8
- if n in (48, 64): # packed 16-bit rgb48/rgba64
- return 16
- return n if 8 <= n <= 16 else 8
-
-
-def fmt_secs(value: Optional[float]) -> str:
- """`12.345s`, or `?s` when the probe had no duration (MPEG-TS without a duration tag, a
- stream whose container and streams all omit it). Every writing tool prints the duration
- of what it wrote; formatting None with :.3f used to raise TypeError after a successful
- encode, in 25+ scripts."""
- return "?s" if value is None else f"{value:.3f}s"
-
-
-def place_output(src: str, dst: str) -> None:
- """Deliver an already-rendered file to `dst` under the same rules as an ffmpeg output:
- the path is checked, an existing file is only replaced through a sibling temp so a
- failed copy never costs the caller what was there, and the result is remembered as ours.
- render.py's final `copyfile()` used to bypass all three."""
- import shutil
- cmd = ["ffmpeg", dst]
- _check_output_path(cmd)
- _check_existing_output(cmd)
- d, base = os.path.split(dst)
- stem, ext = os.path.splitext(base)
- tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
- try:
- shutil.copyfile(src, tmp)
- os.replace(tmp, dst)
- except OSError as e:
- try:
- os.remove(tmp)
- except OSError:
- pass
- die(f"could not place {dst}: {e}", kind="output")
- _remember_output(cmd)
-
-
-def parse_time(value: str, fps: Optional[float] = None) -> float:
- """Accept seconds ('12.5'), mm:ss ('1:30'), hh:mm:ss(.ms) ('00:01:30.250'), SRT '00:01:30,250',
- or -- when `fps` is given -- SMPTE non-drop-frame timecode 'hh:mm:ss:ff' ('00:01:30:15')."""
- v = value.strip().replace(",", ".")
- if not v:
- raise ValueError("empty time")
- if "@" in v:
- # 1.9: 'hh:mm:ss:[email protected]' names the timecode's rate explicitly (docs/design-decisions.md,
- # time grammar); it overrides the source fps a tool passed in, and is meaningless without
- # the four-part form
- v, _, rate = v.rpartition("@")
- if "@" in v:
- raise ValueError(f"'{value}': only one @fps suffix is allowed")
- try:
- fps = float(rate)
- except ValueError:
- raise ValueError(f"bad @fps suffix in '{value}' (expected a number such as @29.97)")
- if fps <= 0:
- raise ValueError(f"bad @fps suffix in '{value}': the rate must be positive")
- if len(v.split(":")) != 4:
- raise ValueError(f"'{value}': the @fps suffix belongs to an hh:mm:ss:ff timecode, not to seconds or mm:ss")
- parts = v.split(":")
- if len(parts) == 4:
- if fps is None or fps <= 0:
- raise MissingFpsError(f"'{value}' looks like an hh:mm:ss:ff SMPTE timecode, but no fps was given to convert its frame count to seconds (append @fps, e.g. {value}@29.97, or use seconds / mm:ss / hh:mm:ss.ms)")
- h, m, s, f = parts
- if "." in f:
- raise ValueError(f"bad SMPTE timecode: {value}")
- frame, whole_fps = int(f), int(round(fps))
- if not (0 <= frame < whole_fps):
- raise ValueError(f"bad SMPTE timecode '{value}': frame {frame} is out of range for {fps:g} fps (0-{whole_fps - 1})")
- # Non-drop-frame: the timecode counts whole_fps frames per timecode-second, so the real
- # time is the total frame count over the true rate (at 29.97 an hour of timecode is
- # 3596.4 s of video). This is exactly what fmt_smpte_time() inverts; before, the two
- # disagreed by ~0.1 % on the fractional NTSC rates and drifted apart over long files.
- total_frames = (int(h) * 3600 + int(m) * 60 + int(s)) * whole_fps + frame
- return total_frames / fps
- if len(parts) > 3:
- raise ValueError(f"bad time: {value}")
- total = 0.0
- for part in parts:
- try:
- total = total * 60 + float(part)
- except ValueError:
- # not the interpreter's "could not convert string to float: 'zz'" (review 9)
- raise ValueError(f"'{value}': not a time")
- return total
-
-
-def time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
- """parse_time() for a command-line flag: SMPTE hh:mm:ss:ff resolves with the input's fps when
- the caller has one, and every parse failure is a `kind: input` refusal naming the flag (so
- `--json` callers get a failure document, never a traceback)."""
- try:
- return parse_time(value, fps)
- except MissingFpsError as e:
- die(f"{flag} {value!r}: {e}")
- except ValueError as e:
- die(f"{flag} {value!r}: {e} (use seconds, mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff at the source's fps or with an explicit @fps suffix)")
- return 0.0 # unreachable
-
-
-def signed_time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
- """time_arg() for a flag that may also be negative (an offset, not a point in time): a single
- leading '-'/'+' is taken as the sign and the rest goes through the ordinary time grammar, so
- `--offset -00:00:02`, `--offset -1.5` and `--offset 0:02` all mean what they read as."""
- text = (value or "").strip()
- sign = 1.0
- if text[:1] in "+-":
- sign = -1.0 if text[0] == "-" else 1.0
- text = text[1:].strip()
- if not text:
- die(f"{flag} {value!r}: not a time (use seconds, mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff)")
- return sign * time_arg(text, flag, fps)
-
-
-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 fmt_smpte_time(seconds: float, fps: float) -> str:
- """SMPTE non-drop-frame timecode 'hh:mm:ss:ff' for a real fps (not the fractional NTSC rates
- -- 29.97/59.94 need drop-frame counting to stay wall-clock accurate, which this does not do)."""
- if seconds < 0:
- seconds = 0.0
- whole_fps = int(round(fps))
- total_frames = int(round(seconds * fps))
- frame = total_frames % whole_fps
- secs_total = total_frames // whole_fps
- h, rem = divmod(secs_total, 3600)
- m, s = divmod(rem, 60)
- return f"{h:02d}:{m:02d}:{s:02d}:{frame:02d}"
-
-
-def escape_filter_path(path: str) -> 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
- on `:`, then the filter's own option parser splits key=value pairs on `:` again. A character that
- must survive both passes needs two levels of escaping, so a Windows drive letter `D:/x.srt` is
- written `D\\\\:/x.srt`; with a single backslash the second pass still splits at the colon and
- ffmpeg reads `/x.srt` as the next option (`Unable to parse "original_size" option value`).
- Backslashes are turned into forward slashes first (ffmpeg accepts them on Windows), so a backslash
- never has to be escaped itself; `,`, `;`, `[` and `]` are graph-level characters and survive with
- one backslash. `'` is special: the graph parser also treats a quote as the start of a quoted
- 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=).
- """
- if 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("\\", "/")
- p = p.replace(":", "\\\\:")
- p = p.replace("'", "\\\\\\'")
- for ch in (",", ";", "[", "]"):
- p = p.replace(ch, "\\" + ch)
- return p
-
-
-def default_font_file(font_name: str) -> Optional[str]:
- """Resolve `font_name` to a concrete on-disk font file, so a caller can tell drawtext
- `fontfile=<path>` instead of `font=<name>`, when possible.
-
- On some real Windows ffmpeg builds (winget's gyan.dev 9.x), drawtext's own fontconfig
- resolution crashes with an access violation whenever it has to resolve a font by family name
- -- with or without a valid fonts.conf on FONTCONFIG_FILE. `fontfile=` is the only form
- confirmed not to crash (#100), since it never touches fontconfig at all. `font_name` itself is
- ignored on Windows for that reason: a fixed, near-universally-present system font is used
- instead of trying to resolve the requested family (which would crash the same way).
-
- On Linux/macOS this is best-effort and uses the real requested family: `fc-match` reports the
- same file fontconfig would resolve `font_name` to anyway, so a caller gets the identical font,
- just already resolved to a path -- fontfile= skips a redundant fontconfig lookup and equally
- sidesteps the same class of crash if it exists on some build there too, but the fallback below
- (returning None) is exercised routinely there, not just on failure.
-
- Returns None when nothing could be resolved (fc-match missing/unavailable, or no well-known
- Windows font file present); the caller falls back to font=<font_name>, the prior behaviour.
- """
- if platform.system() == "Windows":
- windir = os.environ.get("WINDIR", "C:\\Windows")
- fonts = Path(windir) / "Fonts"
- # The requested family first: a file whose name starts with the family name with spaces
- # removed (Noto Sans CJK JP -> NotoSansCJKjp-Regular.otf, Meiryo -> meiryo.ttc), then the
- # common CJK system fonts when the request looks CJK (so Japanese text does not render as
- # boxes in Arial), and Arial only as the last resort.
- wanted = re.sub(r"[^a-z0-9]", "", (font_name or "").lower())
- try:
- files = sorted(fonts.iterdir()) if fonts.is_dir() else []
- except OSError:
- files = []
- if wanted:
- for f in files:
- stem = re.sub(r"[^a-z0-9]", "", f.stem.lower())
- if f.suffix.lower() in (".ttf", ".otf", ".ttc") and stem.startswith(wanted):
- return str(f)
- if any(k in wanted for k in ("cjk", "gothic", "mincho", "meiryo", "yugoth", "msgothic", "malgun", "simhei", "simsun", "jp", "kr", "sc", "tc")):
- for name in ("NotoSansCJKjp-Regular.otf", "NotoSansCJK-Regular.ttc", "meiryo.ttc", "YuGothM.ttc", "msgothic.ttc", "malgun.ttf", "msyh.ttc"):
- if (fonts / name).exists():
- return str(fonts / name)
- candidate = fonts / "arial.ttf"
- return str(candidate) if candidate.exists() else None
- exe = shutil.which("fc-match")
- if not exe:
- return None
- try:
- proc = subprocess.run([exe, "--format=%{file}\n", font_name], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=5)
- except (subprocess.TimeoutExpired, OSError):
- return None
- if proc.returncode != 0:
- return None
- path = proc.stdout.splitlines()[0].strip() if proc.stdout.strip() else ""
- return path if path and os.path.exists(path) else None
-
-
-# --------------------------------------------------------------------------- script detection
-# 1.12: non-Latin caption/overlay text used to render as tofu (empty boxes) whenever the default
-# family carried no glyphs for it -- silently, because fontconfig substitutes SOMETHING for every
-# request and ffmpeg exits 0 either way. The tools now detect the script of the text they are about
-# to draw and resolve a font file that actually covers it; nothing found is a failed job, not a
-# warning (a video full of boxes is not a delivery).
-SCRIPTS = ("ja", "zh", "ko", "ar", "he", "hi", "bn", "ta", "th", "lo", "ru", "el", "latin")
-
-LANGUAGE_NAMES = {
- "ja": "Japanese", "zh": "Chinese", "ko": "Korean", "ar": "Arabic", "he": "Hebrew",
- "hi": "Devanagari (Hindi/Marathi/Nepali)", "th": "Thai", "ru": "Cyrillic (Russian and others)",
- "el": "Greek", "latin": "Latin", "bn": "Bengali", "ta": "Tamil", "lo": "Lao",
-}
-
-# fontconfig's own :lang= codes for each script we detect (zh uses zh-cn, the Simplified subset
-# every CJK font that claims zh carries; the rest are the plain two-letter codes).
-FC_LANG = {"ja": "ja", "zh": "zh-cn", "ko": "ko", "ar": "ar", "he": "he", "hi": "hi", "th": "th", "ru": "ru", "el": "el",
- "bn": "bn", "ta": "ta", "lo": "lo"}
-
-# Families tried in order, best first. The names are matched case-insensitively against the start
-# of any family fontconfig reports for a file, so "Noto Sans CJK JP" also matches
-# "Noto Sans CJK JP Black". Anything not listed still qualifies -- it just sorts after these.
-PREFERRED_FAMILIES = {
- "ja": ["Noto Sans CJK JP", "Noto Serif CJK JP", "Noto Sans JP", "Source Han Sans", "IPAPGothic", "IPAGothic", "IPA", "VL Gothic", "TakaoGothic", "WenQuanYi Zen Hei"],
- "zh": ["Noto Sans CJK SC", "Noto Serif CJK SC", "Noto Sans SC", "Source Han Sans", "WenQuanYi Zen Hei", "WenQuanYi Micro Hei", "Droid Sans Fallback"],
- "ko": ["Noto Sans CJK KR", "Noto Serif CJK KR", "Noto Sans KR", "Source Han Sans K", "NanumGothic", "Nanum Gothic", "Malgun Gothic", "WenQuanYi Zen Hei"],
- "ar": ["Noto Sans Arabic", "Noto Naskh Arabic", "Amiri", "Scheherazade", "DejaVu Sans", "FreeSans", "FreeSerif"],
- "he": ["Noto Sans Hebrew", "Noto Serif Hebrew", "DejaVu Sans", "FreeSans", "FreeSerif"],
- "hi": ["Noto Sans Devanagari", "Noto Serif Devanagari", "Lohit Devanagari", "Mangal", "Nirmala UI", "Samyak Devanagari", "FreeSans", "FreeSerif"],
- "th": ["Noto Sans Thai", "Noto Serif Thai", "Loma", "Garuda", "Waree", "Umpush", "Norasi", "Sarabun", "Leelawadee UI", "FreeSerif"],
- "bn": ["Noto Sans Bengali", "Noto Serif Bengali", "Lohit Bengali", "Mukti Narrow", "Vrinda", "Nirmala UI", "FreeSerif"],
- "ta": ["Noto Sans Tamil", "Noto Serif Tamil", "Lohit Tamil", "Latha", "Nirmala UI", "FreeSerif"],
- "lo": ["Noto Sans Lao", "Noto Serif Lao", "Phetsarath OT", "Souliyo Unicode", "Saysettha OT", "DokChampa", "Leelawadee UI"],
- "ru": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
- "el": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
-}
-
-# Windows has no fontconfig: the system fonts are looked up by file name instead, best first.
-WINDOWS_FONTS = {
- "ko": [("malgun.ttf", "Malgun Gothic"), ("gulim.ttc", "Gulim"), ("batang.ttc", "Batang")],
- "zh": [("msyh.ttc", "Microsoft YaHei"), ("simhei.ttf", "SimHei"), ("simsun.ttc", "SimSun")],
- "ja": [("meiryo.ttc", "Meiryo"), ("YuGothM.ttc", "Yu Gothic Medium"), ("YuGothR.ttc", "Yu Gothic"), ("msgothic.ttc", "MS Gothic")],
- "ar": [("tahoma.ttf", "Tahoma"), ("arial.ttf", "Arial")],
- "he": [("tahoma.ttf", "Tahoma"), ("arial.ttf", "Arial")],
- "hi": [("mangal.ttf", "Mangal"), ("Nirmala.ttf", "Nirmala UI"), ("NirmalaB.ttf", "Nirmala UI")],
- "th": [("leelawui.ttf", "Leelawadee UI"), ("leelawad.ttf", "Leelawadee"), ("tahoma.ttf", "Tahoma")],
- "bn": [("Nirmala.ttf", "Nirmala UI"), ("vrinda.ttf", "Vrinda")],
- "ta": [("Nirmala.ttf", "Nirmala UI"), ("latha.ttf", "Latha")],
- "lo": [("leelawui.ttf", "Leelawadee UI"), ("DokChamp.ttf", "DokChampa")],
- "ru": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
- "el": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
-}
-
-_SCRIPT_RANGES = (
- ("ko", ((0x1100, 0x11FF), (0x3130, 0x318F), (0xA960, 0xA97F), (0xAC00, 0xD7FF))), # Hangul syllables + Jamo
- ("kana", ((0x3040, 0x309F), (0x30A0, 0x30FF), (0x31F0, 0x31FF), (0xFF66, 0xFF9F))), # hiragana/katakana
- ("han", ((0x3400, 0x4DBF), (0x4E00, 0x9FFF), (0xF900, 0xFAFF), (0x20000, 0x2A6DF))),
- ("ar", ((0x0600, 0x06FF), (0x0750, 0x077F), (0x08A0, 0x08FF), (0xFB50, 0xFDFF), (0xFE70, 0xFEFF))),
- ("he", ((0x0590, 0x05FF), (0xFB1D, 0xFB4F))),
- ("hi", ((0x0900, 0x097F), (0xA8E0, 0xA8FF))),
- ("bn", ((0x0980, 0x09FF),)),
- ("ta", ((0x0B80, 0x0BFF),)),
- ("th", ((0x0E00, 0x0E7F),)),
- ("lo", ((0x0E80, 0x0EFF),)),
- ("ru", ((0x0400, 0x04FF), (0x0500, 0x052F), (0x2DE0, 0x2DFF))),
- ("el", ((0x0370, 0x03FF), (0x1F00, 0x1FFF))),
-)
-
-
-# --------------------------------------------------------------------------- emoji (1.15)
-# Emoji are orthogonal to the writing system: "やった 🎉" is Japanese AND emoji. They are detected
-# separately from detect_script() so a cue's font resolution is still decided by its letters.
-EMOJI_RANGES = (
- (0x1F300, 0x1FAFF), # symbols & pictographs, supplemental, extended-A
- (0x1F000, 0x1F0FF), # mahjong/domino/playing cards
- (0x2600, 0x27BF), # misc symbols + dingbats
- (0x2B00, 0x2BFF), # misc symbols and arrows
- (0xFE0F, 0xFE0F), # VS16 (emoji presentation selector)
- (0x1F1E6, 0x1F1FF), # regional indicators (flags)
- (0x20E3, 0x20E3), # combining enclosing keycap
- (0x1F3FB, 0x1F3FF), # skin-tone modifiers
-)
-# U+200D ZWJ is deliberately NOT in EMOJI_RANGES: it is ordinary Indic/Persian orthography
-# (क्‍ष is ka + virama + ZWJ + ssa) and only becomes emoji glue *between two emoji bases*.
-# Characters that never START a cluster: they bind to whatever stands before them.
-_EMOJI_TAIL = frozenset({0x200D, 0xFE0F, 0x20E3} | set(range(0x1F3FB, 0x1F400)))
-_EMOJI_REGIONAL = range(0x1F1E6, 0x1F200)
-_ZWJ = 0x200D
-_VS15 = 0xFE0E # text-presentation selector: "draw this as a character, not as an emoji"
-_VS16 = 0xFE0F
-_KEYCAP = 0x20E3
-_KEYCAP_BASES = frozenset("0123456789#*")
-
-
-def _is_emoji_char(ch: str) -> bool:
- cp = ord(ch)
- return any(lo <= cp <= hi for lo, hi in EMOJI_RANGES)
-
-
-def _is_emoji_base(ch: str) -> bool:
- """Can this character START an emoji cluster? Pictographs and regional indicators can;
- the joiners and modifiers (ZWJ, VS16, keycap, skin tone) never can -- they only bind to an
- emoji base that already stands before them. Without this, a ZWJ or a VS16 sitting after an
- ordinary letter turned that letter into "an emoji" and the PNG route replaced it with a gap."""
- return ord(ch) not in _EMOJI_TAIL and _is_emoji_char(ch)
-
-
-def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
- """(index in `text`, cluster) for every emoji in it, ZWJ sequences, VS16, keycaps, flag pairs
- and skin-tone modifiers kept together -- 👩‍💻 is one cluster, not three, and 1️⃣ starts at the
- digit even though the digit is not itself an emoji character.
-
- A cluster can only START at an emoji base (a pictograph, a regional indicator) or at a keycap
- base (`0-9 # *`) that is actually followed by U+20E3. A ZWJ is glue *inside* a cluster, never
- a starter and never a tail on its own: `क्‍ष` (Hindi ka + virama + ZWJ + ssa) and `abc‍def`
- contain no emoji. A base explicitly marked with U+FE0E (VS15, text presentation) is likewise
- not an emoji -- the author asked for the character, not the picture.
- """
- out: "List[Tuple[int, str]]" = []
- i = 0
- n = len(text or "")
- while i < n:
- ch = text[i]
- start = i
- if _is_emoji_base(ch):
- j = i + 1
- if j < n and ord(text[j]) == _VS15: # text presentation requested: not an emoji
- i = j + 1
- continue
- elif ch in _KEYCAP_BASES:
- j = i + 1
- if j < n and ord(text[j]) == _VS16:
- j += 1
- if not (j < n and ord(text[j]) == _KEYCAP):
- i += 1
- continue
- j += 1
- else:
- i += 1
- continue
- # extend: modifiers bind rightwards, a ZWJ only when a real emoji base follows it
- while j < n:
- cp = ord(text[j])
- if cp in (_VS16, _KEYCAP) or 0x1F3FB <= cp <= 0x1F3FF:
- j += 1
- continue
- if cp == _ZWJ and j + 1 < n and _is_emoji_base(text[j + 1]):
- j += 2
- continue
- if (j == start + 1 and ord(ch) in _EMOJI_REGIONAL and cp in _EMOJI_REGIONAL):
- j += 1
- continue
- break
- out.append((start, text[start:j]))
- i = j
- return out
-
-
-def has_emoji(text: str) -> bool:
- return bool(emoji_clusters(text or ""))
-
-
-def emoji_codepoint_name(cluster: str) -> str:
- """The asset filename stem for a cluster: lowercase hex code points joined by '-', the
- Twemoji/Noto convention (1f389, 1f469-200d-1f4bb, 1f1ef-1f1f5)."""
- return "-".join(f"{ord(c):x}" for c in cluster)
-
-
-def _emoji_name_candidates(cluster: str) -> "List[str]":
- """Asset stems to try, most specific first: exact, without VS16, without skin tone, the ZWJ
- sequence reduced to its first code point, the bare base."""
- cps = [ord(c) for c in cluster]
- names = [emoji_codepoint_name(cluster)]
-
- def add(seq):
- name = "-".join(f"{c:x}" for c in seq)
- if name and name not in names:
- names.append(name)
- add([c for c in cps if c != 0xFE0F])
- add([c for c in cps if c != 0xFE0F and not (0x1F3FB <= c <= 0x1F3FF)])
- if 0x200D in cps:
- add([cps[0]])
- add([cps[0]])
- return names
-
-
-def emoji_asset_for(cluster: str, assets_dir: "Optional[str]") -> "Optional[str]":
- """The PNG for `cluster` under `assets_dir`, or None when nothing matches."""
- if not assets_dir or not os.path.isdir(assets_dir):
- return None
- for name in _emoji_name_candidates(cluster):
- for ext in (".png", ".PNG"):
- candidate = os.path.join(assets_dir, name + ext)
- if os.path.isfile(candidate):
- return candidate
- return None
-
-
-EMOJI_ASSET_HINT = (
- "point --emoji-assets at a directory of PNGs named by code point (1f389.png): "
- "twemoji/assets/72x72 (Twemoji, CC-BY 4.0) or noto-emoji/png/128 (Noto Emoji, OFL/Apache-2.0) "
- "are the two people already have. The skill has no network at runtime, so the assets must "
- "already exist on this machine -- nothing is ever downloaded")
-
-_EMOJI_COLOR_FAMILIES = ("Noto Color Emoji", "Apple Color Emoji", "Segoe UI Emoji")
-_EMOJI_SUPPORT_CACHE: "Dict[Tuple[Optional[str], bool], Dict[str, Any]]" = {}
-
-
-def _emoji_color_font() -> "Tuple[Optional[str], Optional[str], bool]":
- """(family, file, fontconfig_answered) for the first installed colour emoji family."""
- exe = shutil.which("fc-list")
- if not exe:
- return None, None, False
- for family in _EMOJI_COLOR_FAMILIES:
- try:
- proc = subprocess.run([exe, f":family={family}", "file"], stdout=subprocess.PIPE,
- stderr=subprocess.DEVNULL, text=True, timeout=10)
- except (subprocess.TimeoutExpired, OSError):
- return None, None, False
- if proc.returncode != 0:
- return None, None, False
- for line in proc.stdout.splitlines():
- path = line.split(":", 1)[0].strip()
- if path and os.path.exists(path):
- return family, path, True
- return None, None, True
-
-
-def _libass_color_probe() -> "Optional[bool]":
- """Does THIS ffmpeg render an emoji in colour through libass? Answered by a render, never by
- the font listing: Noto Color Emoji installs happily on builds whose freetype/libass has no
- colour-bitmap path at all, and those render a monochrome outline instead (measured). ~80 ms.
- None means the probe could not be run (no ffmpeg, a failure) -- unknown, not false."""
- exe = shutil.which("ffmpeg")
- if not exe:
- return None
- import tempfile
- with tempfile.TemporaryDirectory() as td:
- srt = os.path.join(td, "e.srt")
- with open(srt, "w", encoding="utf-8") as fh:
- fh.write("1\n00:00:00,000 --> 00:00:01,000\n\U0001F389\n")
- try:
- 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",
- "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
- stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=20)
- except (subprocess.TimeoutExpired, OSError):
- return None
- if proc.returncode != 0 or len(proc.stdout) < 64 * 64 * 3:
- return None
- data = proc.stdout
- for i in range(0, 64 * 64 * 3, 3):
- r, g, b = data[i], data[i + 1], data[i + 2]
- if max(r, g, b) - min(r, g, b) > 40:
- return True
- return False
-
-
-def emoji_support(assets: "Optional[str]" = None, probe: bool = True) -> "Dict[str, Any]":
- """What this machine can actually do with emoji, cached per process.
-
- `mode` is `color` when a render probe proves libass draws colour, else `png` when an assets
- directory resolves, else `mono` when some installed face has a glyph at all, else `none`.
- An installed colour emoji font proves nothing on its own -- that is why `libass_color` comes
- from a render (see references/gotchas.md#emoji). `probe=False` (`contract --json --static`, and every
- static/JSON-only path) skips the render entirely and leaves `libass_color` unknown.
- """
- key = (assets or None, bool(probe))
- if key in _EMOJI_SUPPORT_CACHE:
- return dict(_EMOJI_SUPPORT_CACHE[key])
- family, file, fc_answered = _emoji_color_font()
- libass_color = _libass_color_probe() if probe else None
- assets_dir = assets if (assets and os.path.isdir(assets)) else None
- if libass_color:
- mode = "color"
- elif assets_dir:
- mode = "png"
- elif family:
- mode = "mono"
- elif not fc_answered:
- # No fontconfig to ask (a static ffmpeg build, a bare container): the PNG path needs none,
- # so the honest answer is png-or-none, never "none because fc-list is missing".
- mode = "none"
- else:
- mode = "none"
- if not fc_answered:
- detail = "no fontconfig on this machine; the PNG overlay path needs none"
- elif libass_color:
- detail = f"{family or 'an installed face'} renders in colour through libass on this ffmpeg"
- elif family and libass_color is False:
- detail = f"{family} installed but libass renders it monochrome on this build"
- elif family and libass_color is None:
- detail = f"{family} installed; the colour render probe was not run"
- elif assets_dir:
- detail = "no colour emoji family installed; using the PNG assets directory"
- else:
- detail = "no colour emoji family installed and no --emoji-assets directory"
- result = {"mode": mode, "color_font": family, "color_font_file": file,
- "libass_color": libass_color, "assets": assets_dir,
- "detail": detail, "fix": EMOJI_ASSET_HINT}
- _EMOJI_SUPPORT_CACHE[key] = result
- return dict(result)
-
-
-def resolve_emoji_assets(flag: "Optional[str]" = None, project: "Optional[str]" = None,
- brand: "Optional[dict]" = None) -> "Optional[str]":
- """--emoji-assets DIR, else the project key, else brand.json, else FFMPEG_SKILL_EMOJI_ASSETS.
- A directory that was named but does not exist is a failed job, never a silent downgrade."""
- brand = brand or {}
- styles = (brand.get("styles") or {}).get("caption") or {}
- for value, where in ((flag, "--emoji-assets"), (project, "the project's text.emoji_assets"),
- (styles.get("emoji_assets"), "brand.json styles.caption.emoji_assets"),
- (brand.get("emoji_assets"), "brand.json emoji_assets"),
- (os.environ.get("FFMPEG_SKILL_EMOJI_ASSETS"), "FFMPEG_SKILL_EMOJI_ASSETS")):
- if not value:
- continue
- if not os.path.isdir(str(value)):
- die(f"{where}: {value} is not a readable directory -- {EMOJI_ASSET_HINT}", kind="input")
- return str(value)
- return None
-
-
-# --------------------------------------------------------------------------- text measurement (1.12)
-# Moved here in 1.15 so graphics.py's ASS route and the emoji placement share caption.py's table.
-# Average advance width per character, in em (a fraction of the font size). Proportional Latin text
-# averages a bit over half an em; CJK and Thai are drawn on a full-width grid; Arabic/Hebrew and
-# Devanagari sit in between. These are deliberately averages, not per-glyph metrics: measuring the
-# real advance needs a font parser (no stdlib one) and would still be wrong for libass's own
-# shaping, while a cue wrapped from an average is right to within a character on every line.
-# (Latin is measured per character from LATIN_EM below, not from this average.)
-ADVANCE_EM = {"ja": 1.0, "zh": 1.0, "ko": 1.0, "th": 1.0, "hi": 0.7, "ar": 0.6, "he": 0.6,
- "ru": 0.55, "el": 0.55, "latin": 0.55}
-# Scripts written without spaces: a line breaks between any two characters.
-NO_SPACE_SCRIPTS = ("ja", "zh", "ko", "th")
-# Per-character Latin advances in em, read off DejaVu Sans (the default caption family, and close
-# enough to any other proportional sans for a wrap) and rounded UP: a capital runs 0.56-0.99 em
-# against the single 0.55 average that used to stand for all of Latin, so an all-caps caption --
-# the style most burn-ins use -- overflowed the safe area and was silently re-wrapped by libass
-# past --max-lines. Rounding up is the safe direction: libass re-wraps a too-long line, it never
-# un-wraps a short one. Characters outside the table fall back by class (0.7 uppercase/digit,
-# 0.57 lowercase and anything else Latin-ish).
-LATIN_EM = {
- ' ': 0.32, '!': 0.41, '"': 0.46, '#': 0.84, '$': 0.64, '%': 0.96, '&': 0.78, "'": 0.28,
- '(': 0.4, ')': 0.4, '*': 0.5, '+': 0.84, ',': 0.32, '-': 0.37, '.': 0.32, '/': 0.34, '0': 0.64,
- '1': 0.64, '2': 0.64, '3': 0.64, '4': 0.64, '5': 0.64, '6': 0.64, '7': 0.64, '8': 0.64,
- '9': 0.64, ':': 0.34, ';': 0.34, '<': 0.84, '=': 0.84, '>': 0.84, '?': 0.54, '@': 1.0,
- 'A': 0.69, 'B': 0.69, 'C': 0.7, 'D': 0.78, 'E': 0.64, 'F': 0.58, 'G': 0.78, 'H': 0.76,
- 'I': 0.3, 'J': 0.3, 'K': 0.66, 'L': 0.56, 'M': 0.87, 'N': 0.75, 'O': 0.79, 'P': 0.61,
- 'Q': 0.79, 'R': 0.7, 'S': 0.64, 'T': 0.62, 'U': 0.74, 'V': 0.69, 'W': 0.99, 'X': 0.69,
- 'Y': 0.62, 'Z': 0.69, '[': 0.4, '\\': 0.34, ']': 0.4, '^': 0.84, '_': 0.5, '`': 0.5, 'a': 0.62,
- 'b': 0.64, 'c': 0.55, 'd': 0.64, 'e': 0.62, 'f': 0.36, 'g': 0.64, 'h': 0.64, 'i': 0.28,
- 'j': 0.28, 'k': 0.58, 'l': 0.28, 'm': 0.98, 'n': 0.64, 'o': 0.62, 'p': 0.64, 'q': 0.64,
- 'r': 0.42, 's': 0.53, 't': 0.4, 'u': 0.64, 'v': 0.6, 'w': 0.82, 'x': 0.6, 'y': 0.6, 'z': 0.53,
- '{': 0.64, '|': 0.34, '}': 0.64, '~': 0.84
-}
-# Thai and Lao write some vowels BEFORE the consonant they belong to: the break must not land
-# between them and the base that follows.
-LEADING_VOWELS = set(range(0x0E40, 0x0E45)) | set(range(0x0EC0, 0x0EC5))
-
-
-def _is_mark(ch: str) -> bool:
- """A character that hangs off the one before it: a combining mark (any script) or one of the
- Thai/Lao vowel signs and tone marks, which are Mn/Mc but carry no combining class."""
- return unicodedata.combining(ch) != 0 or unicodedata.category(ch) in ("Mn", "Mc")
-
-
-def _char_em(ch: str) -> float:
- # CJK punctuation and the fullwidth forms (、。,!? and U+FF01-FF60) are drawn on the same
- # full-width grid as the ideographs they sit between, even though they are not "Han" to a
- # script detector -- measuring them as Latin under-counts a wrapped CJK line by a character.
- cp = ord(ch)
- # A combining mark is drawn on top of (or under) its base and advances the pen by nothing:
- # charging it a full em wrapped Thai and Devanagari lines far shorter than they needed to be.
- if unicodedata.combining(ch) != 0 or unicodedata.category(ch) in ("Mn", "Cf"):
- # "Cf" catches ZWJ/ZWNJ: an Indic joiner is orthography, and it advances the pen by
- # nothing -- charging it a full em (it used to count as "emoji") shrank a Hindi line.
- return 0.0
- if 0x3000 <= cp <= 0x303F or 0xFF01 <= cp <= 0xFF60 or 0xFFE0 <= cp <= 0xFFE6:
- return 1.0
- script = char_script(ch)
- if script == "emoji":
- # 1.15: an emoji is drawn (or reserved) at a full em box, not at Latin's 0.57 -- counting
- # it as Latin overflowed the safe area on an emoji-heavy line.
- return 1.0
- if script == "latin":
- if ch in LATIN_EM:
- return LATIN_EM[ch]
- if ch.isupper() or ch.isdigit():
- return 0.7
- return 0.57
- return ADVANCE_EM.get(script, 0.55)
-
-
-def text_width_em(text: str, emoji_em: float = 1.0) -> float:
- """Width of `text` in em, from the per-script average advance table. `emoji_em` is what one
- emoji cluster costs (--emoji-scale), so a wrap counts the box that will actually be drawn."""
- total = 0.0
- spans = {i: len(c) for i, c in emoji_clusters(text)}
- i = 0
- while i < len(text):
- if i in spans:
- total += emoji_em
- i += spans[i]
- continue
- total += _char_em(text[i])
- i += 1
- return total
-
-
-def emoji_filter_chain(plan, base_label, out_label, first_input=1):
- """(chains, inputs) that composite the planned PNGs on top of `base_label`.
-
- `inputs` is a list of argv fragments, each ending in the asset path, to be appended to the
- ffmpeg command in order (an overlay that fades needs `-loop 1` on its input so the still has
- a timeline the fade filter can move along; one that does not is a plain `-i`).
- """
- overlays = plan.get("overlays") or []
- if not overlays:
- return [], []
- # Group by everything that makes two uses of the same PNG a different STREAM: the fade is
- # expressed in the cue's own timeline, so two cues cannot share one faded input.
- def _key(o):
- fades = (round(float(o.get("fade_in") or 0.0), 3), round(float(o.get("fade_out") or 0.0), 3))
- window = (round(float(o["start"]), 3), round(float(o["end"]), 3)) if any(fades) else (None, None)
- return (o["asset"], o["box"]) + fades + window
-
- groups: "List[Tuple]" = []
- for o in overlays:
- if _key(o) not in groups:
- groups.append(_key(o))
- chains: List[str] = []
- inputs: "List[List[str]]" = []
- pads: "Dict[Tuple, List[str]]" = {}
- for k, key in enumerate(groups):
- asset, box, fin, fout, gstart, gend = key
- uses = [o for o in overlays if _key(o) == key]
- idx = first_input + k
- labels = [f"e{k}_{j}" for j in range(len(uses))]
- chain = f"[{idx}:v]format=rgba,scale={box}:{box}"
- if fin or fout:
- # -loop 1 gives the still an advancing timeline on the SAME clock as the main video,
- # so the fade times below are the cue's own seconds. The emoji then appears and
- # leaves with the text instead of popping in against a fading line.
- # -t bounds the loop at the cue's end: an unbounded looped still never EOFs and the
- # whole encode hangs (overlay keeps pulling from it after the main video is done).
- inputs.append(["-loop", "1", "-t", f"{gend:.3f}", "-i", asset])
- if fin:
- chain += f",fade=t=in:st={gstart:.3f}:d={fin:.3f}:alpha=1"
- if fout:
- chain += f",fade=t=out:st={max(gstart, gend - fout):.3f}:d={fout:.3f}:alpha=1"
- else:
- inputs.append(["-i", asset])
- if len(labels) > 1:
- chain += f",split={len(labels)}"
- chains.append(chain + "".join(f"[{l}]" for l in labels))
- pads[key] = labels
- cur = base_label
- remaining = {key: list(v) for key, v in pads.items()}
- for j, o in enumerate(overlays):
- label = remaining[_key(o)].pop(0)
- nxt = out_label if j == len(overlays) - 1 else f"eov{j}"
- x = o["x"]
- x = f"'{x}'" if isinstance(x, str) else x
- # No eof_action=pass here: a PNG input is a SINGLE frame at pts 0, and eof_action=pass
- # switches off overlay's default "hold the last frame of the secondary input", so the
- # asset would be composited on frame 0 only and vanish for the rest of the cue (that is
- # exactly what shipped first). eof_action=repeat (the default) holds the still for the
- # whole timeline; enable= is what confines it to the cue's window.
- chains.append(f"[{cur}][{label}]overlay=x={x}:y={o['y']}:"
- f"enable='between(t,{o['start']:.3f},{o['end']:.3f})'[{nxt}]")
- cur = nxt
- return chains, inputs
-
-
-# --------------------------------------------------------------------------- shaping (1.15)
-# Scripts whose correct rendering needs harfbuzz-class reordering and re-clustering (Indic matras,
-# Thai/Lao mark stacking). drawtext does NOT use harfbuzz even in an --enable-libharfbuzz build, so
-# these come out wrong through drawtext on every build and must go through libass. Arabic and
-# Hebrew are NOT here: drawtext's text_shaping uses fribidi, which does bidi and Arabic joining
-# correctly -- they only join this set on a build compiled without fribidi.
-SHAPING_SCRIPTS = frozenset({"hi", "bn", "ta", "te", "kn", "ml", "gu", "pa", "si", "th", "lo", "km", "my"})
-BIDI_SCRIPTS = frozenset({"ar", "he"})
-_SHAPING_BUILD_CACHE: "Dict[str, bool]" = {}
-
-
-def drawtext_shaping() -> "Dict[str, bool]":
- """Which shaping libraries THIS ffmpeg was built with, from -buildconf (falling back to the
- `configuration:` line of -version). Cached per process."""
- if _SHAPING_BUILD_CACHE:
- return dict(_SHAPING_BUILD_CACHE)
- text = ""
- exe = shutil.which("ffmpeg")
- if exe:
- for flag in ("-buildconf", "-version"):
- try:
- proc = subprocess.run([exe, "-hide_banner", flag], stdout=subprocess.PIPE,
- stderr=subprocess.STDOUT, text=True, timeout=10)
- except (subprocess.TimeoutExpired, OSError):
- break
- if proc.returncode == 0 and proc.stdout.strip():
- text = proc.stdout
- break
- _SHAPING_BUILD_CACHE.update({"fribidi": "--enable-libfribidi" in text,
- "harfbuzz": "--enable-libharfbuzz" in text})
- return dict(_SHAPING_BUILD_CACHE)
-
-
-def needs_shaping(script: str) -> bool:
- """Whether drawtext would render `script` wrongly on this build."""
- if script in SHAPING_SCRIPTS:
- return True
- return script in BIDI_SCRIPTS and not drawtext_shaping()["fribidi"]
-
-
-def font_family_of_file(path: str) -> "Optional[str]":
- """The family name of a font FILE -- what libass wants, given a --font-file. `fc-scan` reads
- the file directly; without fontconfig the file stem is the honest best guess."""
- if not path or not os.path.isfile(path):
- return None
- exe = shutil.which("fc-scan")
- if exe:
- try:
- proc = subprocess.run([exe, "--format", "%{family[0]}", path], stdout=subprocess.PIPE,
- stderr=subprocess.DEVNULL, text=True, timeout=10)
- if proc.returncode == 0 and proc.stdout.strip():
- return proc.stdout.strip().splitlines()[0].strip()
- except (subprocess.TimeoutExpired, OSError):
- pass
- return Path(path).stem
-
-
-def char_script(ch: str) -> str:
- """The script of one character: one of SCRIPTS, or "latin" for anything else (including
- digits, punctuation and spaces -- they are measured and wrapped like Latin)."""
- cp = ord(ch)
- # 1.15: an emoji cluster is not Latin. detect_script() skips "emoji" the way it skips "latin",
- # so font resolution still follows the letters around it.
- if _is_emoji_char(ch):
- return "emoji"
- for name, ranges in _SCRIPT_RANGES:
- for lo, hi in ranges:
- if lo <= cp <= hi:
- return "ja" if name == "kana" else ("zh" if name == "han" else name)
- return "latin"
-
-
-def detect_script(text: str, lang: "Optional[str]" = None) -> str:
- """Which script `text` is written in, as one of SCRIPTS.
-
- Hangul wins for Korean, any kana makes the whole string Japanese (Japanese mixes kana and
- Han), Han alone is Chinese. Mixed text is decided by character count: the non-Latin script
- with the most characters wins, ties going to whichever appeared first, and text with no
- non-Latin characters at all is "latin". `lang` (a --lang/--language hint, or brand.json's
- `lang`) only resolves the one ambiguity the characters genuinely cannot: Han with no kana
- is Chinese by default but Japanese (or Korean hanja) when the caller says so.
- """
- counts: "Dict[str, int]" = {}
- order: "List[str]" = []
- kana = 0
- for ch in text or "":
- s = char_script(ch)
- if s in ("latin", "emoji"):
- continue
- if ord(ch) in range(0x3040, 0x3100) or ord(ch) in range(0x31F0, 0x3200) or ord(ch) in range(0xFF66, 0xFFA0):
- kana += 1
- if s not in counts:
- order.append(s)
- counts[s] = counts.get(s, 0) + 1
- if kana: # Japanese: the Han characters in the same string are Japanese too
- counts["ja"] = counts.pop("ja", 0) + counts.pop("zh", 0)
- order = [s for s in order if s != "zh"]
- if not counts:
- return "latin"
- best = max(counts, key=lambda s: (counts[s], -order.index(s)))
- hint = (lang or "").strip().lower().replace("_", "-").split("-")[0]
- if not kana and best == "zh" and hint in ("ja", "zh", "ko"):
- return hint # Han-only text: only the caller knows whether it is Chinese, Japanese or hanja
- return best
-
-
-_SCRIPT_FONT_CACHE: "Dict[Tuple[str, Optional[str]], Optional[Tuple[str, str]]]" = {}
-
-
-def _fc_list_fonts(fc_lang: str) -> "Optional[List[Tuple[str, List[str]]]]":
- """(file, families) for every font fontconfig says covers `fc_lang`.
-
- `[]` means fontconfig answered and nothing covers the language; `None` means it could not be
- asked at all (no `fc-list` on PATH, or it failed/timed out) -- the difference between
- "missing" and "unknown", which the caller must not collapse: unknown is not a refusal.
- """
- exe = shutil.which("fc-list")
- if not exe:
- return None
- try:
- proc = subprocess.run([exe, f":lang={fc_lang}", "file", "family"],
- stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
- except (subprocess.TimeoutExpired, OSError):
- return None
- if proc.returncode != 0:
- return None
- out = []
- for line in proc.stdout.splitlines():
- if ": " not in line:
- continue
- path, _, families = line.partition(": ")
- path = path.strip()
- if not path or not os.path.exists(path):
- continue
- names = [f.replace("\\-", "-").strip() for f in families.split(",") if f.strip()]
- out.append((path, names or [Path(path).stem]))
- return out
-
-
-def _family_rank(families: "Sequence[str]", preferred: "Sequence[str]") -> int:
- for i, want in enumerate(preferred):
- w = want.lower()
- if any(f.lower().startswith(w) for f in families):
- return i
- return len(preferred)
-
-
-def _script_font_entry(script: str, family_hint: "Optional[str]" = None) -> "Optional[Tuple[str, str]]":
- key = (script, family_hint)
- if key in _SCRIPT_FONT_CACHE:
- return _SCRIPT_FONT_CACHE[key]
- _SCRIPT_FONT_CACHE[key] = result = _script_font_uncached(script, family_hint)
- return result
-
-
-FC_UNKNOWN = "unknown" # sentinel: fontconfig could not be asked (absent or failing), not "no font"
-
-
-def _script_font_uncached(script: str, family_hint: "Optional[str]" = None):
- """(file, family), None when nothing covers `script`, or FC_UNKNOWN when it cannot be asked."""
- if script not in FC_LANG:
- return None
- if platform.system() == "Windows":
- fonts = Path(os.environ.get("WINDIR", "C:\\Windows")) / "Fonts"
- for name, family in WINDOWS_FONTS.get(script, []):
- if (fonts / name).exists():
- return str(fonts / name), family
- return None
- preferred = list(PREFERRED_FAMILIES.get(script, []))
- if family_hint:
- preferred.insert(0, family_hint)
- candidates = _fc_list_fonts(FC_LANG[script])
- if candidates is None:
- return FC_UNKNOWN
- if not candidates:
- return None
- scored = []
- for path, families in candidates:
- joined = " ".join(families).lower()
- stem = Path(path).stem.lower()
- # "Unifont Sample" is fontconfig's tofu-with-hex-digits fallback: it "covers" every script
- # by drawing the code point, which is exactly the unreadable result this feature exists to
- # avoid -- it is only ever chosen when nothing else covers the script at all. A *Mono* face
- # is legible but wrong for a caption band, so it sorts after every proportional one.
- last_resort = 1 if "unifont" in joined else 0
- mono = 1 if "mono" in joined else 0
- # regular weights before Bold/Italic/Oblique cuts, so a default caption is not bold by accident
- styled = 1 if any(k in stem for k in ("bold", "italic", "oblique", "light", "thin", "black")) else 0
- scored.append((last_resort, _family_rank(families, preferred), mono, styled, path, families[0]))
- scored.sort(key=lambda row: (row[0], row[1], row[2], row[3], row[4]))
- best = scored[0]
- return best[4], best[5]
-
-
-def font_for_script(script: str, family_hint: "Optional[str]" = None) -> "Optional[str]":
- """A font FILE path that covers `script`, or None when this machine has none.
-
- Linux/macOS ask fontconfig (`fc-list :lang=xx file family`) and rank what it reports by the
- PREFERRED_FAMILIES table; Windows has no fontconfig, so the known system files are probed by
- name. Cached per process: a caption job resolves the same script for every cue.
- """
- entry = _script_font_entry(script, family_hint)
- return entry[0] if entry and entry is not FC_UNKNOWN else None
-
-
-def font_family_for_script(script: str, family_hint: "Optional[str]" = None) -> "Optional[str]":
- """The family NAME of font_for_script()'s file -- what libass wants in an ASS Fontname."""
- entry = _script_font_entry(script, family_hint)
- return entry[1] if entry and entry is not FC_UNKNOWN else None
-
-
-def script_font_status(script: str) -> str:
- """"available" (a font file covers `script`), "missing" (fontconfig answered, none does) or
- "unknown" (there is no working fontconfig to ask). Only "missing" is a refusal."""
- entry = _script_font_entry(script)
- if entry is FC_UNKNOWN:
- return "unknown"
- return "available" if entry else "missing"
-
-
-def font_covers_script(font_name: str, script: str) -> bool:
- """Whether the installed family `font_name` actually carries glyphs for `script`.
-
- `fc-match` cannot answer this: given a family that IS installed it returns that family
- whatever `:lang=` asks for (verified -- `fc-match "DejaVu Sans:lang=zh-cn"` answers
- "DejaVu Sans", which has no Han glyphs at all). `fc-list :lang=xx:family=<name>` does: it
- lists only files that satisfy BOTH, so an empty listing is the proof of no coverage. Unknown
- (no fontconfig at all) counts as covering: a warning nobody can verify is worse than none.
- """
- if script not in FC_LANG or not font_name:
- return True
- exe = shutil.which("fc-list")
- if not exe:
- return True
- try:
- proc = subprocess.run([exe, f":lang={FC_LANG[script]}:family={font_name}", "file"],
- stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
- except (subprocess.TimeoutExpired, OSError):
- return True
- if proc.returncode != 0:
- return True
- return bool(proc.stdout.strip())
-
-
-# Named flags differ per tool: overlay.py and graphics.py take a font FILE, caption.py takes a
-# directory of faces plus the family name -- naming a flag the tool does not have is worse than
-# naming none, so the hint says both (review 10).
-FONT_FLAG_HINT = "pass a font file (--font-file on overlay.py/graphics.py, --fonts-dir with --font on caption.py)"
-FONT_INSTALL_HINT = ("install fonts-noto-cjk / fonts-noto-core (apt), "
- "brew install --cask font-noto-sans-cjk / font-noto-sans-arabic (mac), or "
- + FONT_FLAG_HINT)
-
-
-def fonts_dir_covers_script(fonts_dir: str, script: str) -> "Optional[bool]":
- """Does any font under `fonts_dir` cover `script`? None when it cannot be checked.
-
- `--fonts-dir` says "also look here", not "this exact face", so it must not switch the
- coverage guarantee off. fontconfig's `fc-scan` reads the files directly (no cache, no
- installed-font database), which is exactly the question: `%{lang}` lists the languages each
- face claims.
- """
- if script not in FC_LANG or not fonts_dir or not os.path.isdir(fonts_dir):
- return None
- exe = shutil.which("fc-scan")
- if not exe:
- return None
- try:
- proc = subprocess.run([exe, "--format", "%{lang}\n", fonts_dir],
- stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
- except (subprocess.TimeoutExpired, OSError):
- return None
- if proc.returncode != 0:
- return None
- want = FC_LANG[script].lower()
- for line in proc.stdout.splitlines():
- if want in [tag.strip().lower() for tag in line.split("|")]:
- return True
- return False
-
-
-def script_font_for_text(text: str, *, lang: "Optional[str]" = None, font: "Optional[str]" = None,
- font_explicit: bool = False, font_file: "Optional[str]" = None,
- fonts_dir: "Optional[str]" = None
- ) -> "Tuple[str, Optional[str], Optional[str]]":
- """(script, font file, family) to draw `text` with, resolving by script when nothing explicit
- was asked for.
-
- Returns (script, None, None) when the caller's own choice stands: Latin text, an explicit
- --font-file, an explicit --font (which is kept even when fontconfig says it does not cover
- the script -- with one info line saying so, because overriding a user's stated font silently
- is worse than a warning), or a --fonts-dir that does carry the script. Otherwise the resolved
- file is returned with ONE info line naming it.
-
- A script fontconfig says nothing covers is a failed job (tofu is not a delivery). A machine
- with no working fontconfig at all answers "unknown", not "missing": the job continues with
- the caller's font -- libass and drawtext still have their own font backends -- and one info
- line says the coverage could not be verified.
- """
- script = detect_script(text or "", lang)
- if script == "latin":
- return script, None, None
- if font_file:
- return script, None, None
- if font_explicit and font:
- if not font_covers_script(font, script):
- info(f"font: '{font}' does not cover {LANGUAGE_NAMES[script]} text on this machine; keeping it as asked "
- f"(drop --font, or {FONT_FLAG_HINT}, to pick one by script automatically)")
- return script, None, None
- if fonts_dir:
- covered = fonts_dir_covers_script(fonts_dir, script)
- if covered:
- return script, None, None
- if covered is None:
- info(f"font: could not verify that {fonts_dir} covers {LANGUAGE_NAMES[script]} text "
- "(no fc-scan on this machine); using it as given")
- return script, None, None
- info(f"font: no face in {fonts_dir} covers {LANGUAGE_NAMES[script]} text; "
- "picking one by script instead (the directory is still searched first)")
- entry = _script_font_entry(script)
- if entry is FC_UNKNOWN:
- info(f"font: could not verify that this machine can render {LANGUAGE_NAMES[script]} text "
- "(no working fontconfig); rendering with the font as given -- "
- "doctor --json .fonts.scripts reports what is known")
- return script, None, None
- if not entry:
- die(f"no installed font covers {LANGUAGE_NAMES[script]} text on this machine — {FONT_INSTALL_HINT}", kind="input")
- info(f"font: {entry[0]} (covers {script})")
- return script, entry[0], entry[1]
-
-
-def escape_drawtext(text: str) -> str:
- """Escape a FONT NAME for a single-quoted drawtext option value (`font='<this>'`).
-
- Since 1.15 this is no longer the route for drawn TEXT -- use drawtext_text_opts(), which puts
- the text in a file and keeps `\'` and `%` verbatim. It remains the escape for the font-name
- fallback, where the value is a family name that never legitimately contains a quote or a
- percent sign.
-
- Every ffmpeg filter-graph special character (`\\ : % , [ ] ;`) needs a backslash escape
- regardless of the surrounding quotes -- the graph parser still splits on an unescaped `,`/`;`
- or ends an option list on an unescaped `:`/`[`/`]` even while "inside" a quoted value. The
- quote character itself has no reliable backslash escape at all: `\\'` and the POSIX shell
- close-insert-reopen trick both parse fine in a simple `-vf` chain but silently corrupt a
- `-filter_complex` chain that uses explicit `[label]` pads (confirmed by rendering the result:
- trailing option names leak into the picture as literal text). `%` has the same problem as far
- as drawtext's own expansion scanner is concerned. Both are therefore dropped here rather than
- escaped -- which is exactly why drawn text no longer comes through this function.
- """
- text = re.sub(r"[\x00-\x1f\x7f]", "", text)
- return (
- text.replace("'", "")
- .replace("%", "")
- .replace("\\", "\\\\")
- .replace(":", "\\:")
- .replace(",", "\\,")
- .replace("[", "\\[")
- .replace("]", "\\]")
- .replace(";", "\\;")
- )
-
-
-_DRAWTEXT_TMPDIR: "Optional[str]" = None
-_DRAWTEXT_PENDING: "Dict[str, str]" = {}
-
-
-def _drawtext_tmpdir(create: bool = True) -> str:
- """The private, per-run directory drawn-text files live in.
-
- tempfile.mkdtemp() creates it 0700 under a name nobody can guess, which is the whole point:
- the 1.15.0 shape (a fixed, world-writable `/tmp/ffmpeg-skill-text` entered with
- makedirs(exist_ok=True) and content-addressed filenames) let any other user on the machine
- pre-create the directory or plant a symlink at a predictable name, and handed the second
- user of a shared box a PermissionError out of filter construction instead of a `kind: input`
- refusal. The directory is removed when the process ends, whether it succeeded or failed.
- """
- global _DRAWTEXT_TMPDIR
- import tempfile
- if _DRAWTEXT_TMPDIR and os.path.isdir(_DRAWTEXT_TMPDIR):
- return _DRAWTEXT_TMPDIR
- if not create:
- # --dry-run names the path it WOULD use and creates nothing (a dry run writes nothing).
- return os.path.join(tempfile.gettempdir(), "ffmpeg-skill-text-%d" % os.getpid())
- import atexit
- _DRAWTEXT_TMPDIR = tempfile.mkdtemp(prefix="ffmpeg-skill-text-")
- atexit.register(shutil.rmtree, _DRAWTEXT_TMPDIR, True)
- return _DRAWTEXT_TMPDIR
-
-
-def flush_drawtext_textfiles(cmd: "Sequence[str]") -> "List[str]":
- """Write the drawn-text files this command actually names, and return their paths.
-
- The text is registered when the filter STRING is built, but a filter string is not a run:
- graphics.py builds the drawtext graph even on a job that is finally rendered through libass,
- and every tool builds one under --dry-run. Writing here -- from run(), past the dry-run
- return, against the command that is about to be executed -- is what keeps both of those from
- leaving a file behind.
- """
- if not _DRAWTEXT_PENDING:
- return []
- joined = " ".join(str(a) for a in cmd)
- written = []
- for path, body in list(_DRAWTEXT_PENDING.items()):
- # match on the unique file name, not the full path: inside a filter string the path is
- # escaped (a Windows drive colon becomes `C\\:`, and the separators are forward slashes),
- # so the registered spelling never appears verbatim in the command
- if os.path.basename(path) not in joined or os.path.exists(path):
- continue
- # O_NOFOLLOW exists on POSIX only; the directory is private (mkdtemp, 0700) so the
- # symlink guard is belt and braces there and unavailable on Windows
- flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_NOFOLLOW", 0)
- fd = os.open(path, flags, 0o600)
- with os.fdopen(fd, "w", encoding="utf-8") as fh:
- fh.write(body)
- written.append(path)
- return written
-
-
-def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
- """`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for
- every character on every build shape this repo uses.
-
- The filter-graph parser never sees the text at all: only the PATH is parsed, and
- escape_filter_path() already handles that. `expansion=none` switches off drawtext's own
- `%{...}` scanner, which is the reason `%` was unsafe (a bare `\%` logs "Stray %" on one build
- and fails the whole filter chain on another). With the scanner off, `'`, `%`, `:`, `,`, `[`,
- `]`, `;` and `\` all reach the picture verbatim -- 1.15 fixes `overlay.py --text "it's 100%
- done"` losing both characters. Control characters are still stripped: a one-line burnt-in
- label has no use for them.
-
- The file is UTF-8, mode 0600, in a private per-run directory (see _drawtext_tmpdir) that is
- removed when the process ends. It is *registered* here and written by run() only if the
- command about to run actually names it, so --dry-run and the ASS route write nothing; a
- printed plan therefore names a path that no longer exists once the run is over, which is the
- same promise every other temp file in this skill makes.
- """
- cleaned = re.sub(r"[\x00-\x1f\x7f]", "", text or "")
- import hashlib
- name = "t_" + hashlib.sha256(cleaned.encode("utf-8")).hexdigest()[:16] + ".txt"
- if tmpdir is None:
- tmpdir = _drawtext_tmpdir(create=not STATE.dry_run)
- path = os.path.join(tmpdir, name)
- _DRAWTEXT_PENDING[path] = cleaned
- return f"textfile={escape_filter_path(path)}:expansion=none"
-
-
-def cfr_args(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> List[str]:
- """Force a constant frame rate on output when the source looks VFR (or fps is given).
-
- VFR sources (phone/screen recordings) drift against audio after cuts and joins,
- so every re-encoding script passes this to conform them automatically.
- """
- v = (meta or {}).get("video") or {}
- if fps is None and not v.get("variable_frame_rate_suspected"):
- return []
- rate = fps or v.get("fps") or 30.0
- rate = round(rate) if abs(rate - round(rate)) < 0.02 else rate
- return ["-fps_mode", "cfr", "-r", f"{rate:g}"]
-
-
-def bt709_tag_args(encoder: str = "libx264") -> List[str]:
- """Tag an SDR output as BT.709 without touching its pixels.
-
- Up to FFmpeg 7.0 the output options -colorspace/-color_primaries/-color_trc were tags only.
- 7.1 added colourspace negotiation to libavfilter and feeds those options into the graph's
- output constraints, so on a source whose bitstream carries no colour tags (test sources,
- screen recordings, many cameras) the CLI now auto-inserts a *real* matrix conversion (its
- guess for "unknown" is bt601) into every SDR re-encode: a --lut-strength 0 no-op grade
- came back ~24 dB PSNR from its source on 7.1. From 7.1 on, the tags therefore go through
- the encoder's own VUI parameters instead, which libavfilter never sees; a source that is
- genuinely tagged bt601/bt2020 is left alone either way (it keeps its own tags on the old
- path, and the encoder VUI is a label, not a conversion, on the new one).
- """
- if ffmpeg_version() < (7, 1):
- return ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
- if encoder == "libx265":
- return ["-x265-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]
- return ["-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]
-
-
-def ffmpeg_encoders() -> set:
- """Names from `ffmpeg -encoders`, read once; empty when ffmpeg is missing. Used only to pick
- an AV1 encoder and to refuse --codec av1 / prores before ffmpeg would."""
- global _ENCODERS
- if _ENCODERS is None:
- _ENCODERS = set()
- try:
- out = subprocess.run([shutil.which("ffmpeg") or "ffmpeg", "-hide_banner", "-encoders"], stdout=subprocess.PIPE,
- stderr=subprocess.DEVNULL, text=True, timeout=PROBE_TIMEOUT).stdout
- _ENCODERS = set(re.findall(r"^\s*[VAS][.\w]{5}\s+(\S+)", out, re.M))
- except (OSError, subprocess.SubprocessError):
- pass
- return _ENCODERS
-
-
-def _sdr_bt709(encoder: str) -> "Tuple[str, List[str]]":
- """BT.709 SDR tags for `encoder` as (encoder-params string, extra output options): the two
- spellings bt709_tag_args() picks between, split so a caller that already builds an encoder
- params string can merge them (the option given twice keeps only the last)."""
- if ffmpeg_version() < (7, 1):
- return "", ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
- if encoder == "libsvtav1":
- return "color-primaries=1:transfer-characteristics=1:matrix-coefficients=1", []
- if encoder == "libaom-av1":
- return "", [] # no VUI params option; an untagged 8-bit stream reads as BT.709 everywhere
- return "colorprim=bt709:transfer=bt709:colormatrix=bt709", []
-
-
-def encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str, Any]] = None, keep_bt709: bool = True) -> List[str]:
- """The one place that turns (--codec, --quality, --preset, source) into encoder options.
-
- h264 -> x264 8-bit BT.709 (refuses HDR: 8-bit H.264 cannot carry it); hevc -> x265, Main10
- with the source's tags for HDR, 8-bit BT.709 otherwise; av1 -> SVT-AV1 (libaom fallback),
- 10-bit for HDR; prores -> ProRes 422 HQ, source tags kept. 1.8: chosen by --codec; without
- it video_args() does what it always did (x264 for SDR, x265 Main10 for HDR).
- """
- v = (meta or {}).get("video") or {}
- hdr = bool(v.get("hdr"))
- cs = v.get("color_space") or "bt2020nc"
- prim = v.get("color_primaries") or "bt2020"
- trc = v.get("color_transfer") or "arib-std-b67"
- hdr_tags = ["-colorspace", cs, "-color_primaries", prim, "-color_trc", trc]
- if codec == "h264":
- if hdr:
- die(f"--codec h264 cannot carry HDR ({v.get('hdr_format') or 'BT.2020'}): 8-bit H.264 is SDR only",
- hint="run color.py --to-sdr first, or use --codec hevc / av1 / prores, which keep the source's HDR")
- return _x264_raw(crf, preset, keep_bt709)
- if codec == "hevc":
- if hdr:
- x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
- return ["-c:v", "libx265", "-preset", preset, "-crf", str(min(51, crf + 2)), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
- "-x265-params", x265] + hdr_tags + ["-movflags", "+faststart"]
- params, extra = _sdr_bt709("libx265") if keep_bt709 else ("", [])
- return ["-c:v", "libx265", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-tag:v", "hvc1",
- "-x265-params", "log-level=error" + (":" + params if params else "")] + extra + ["-movflags", "+faststart"]
- if codec == "av1":
- pix = "yuv420p10le" if hdr else "yuv420p"
- if "libsvtav1" in ffmpeg_encoders():
- args = ["-c:v", "libsvtav1", "-preset", str(SVT_PRESET.get(preset, 6)), "-crf", str(min(63, crf)), "-pix_fmt", pix]
- if hdr:
- args += hdr_tags
- elif keep_bt709:
- params, extra = _sdr_bt709("libsvtav1")
- args += (["-svtav1-params", params] if params else []) + extra
- elif "libaom-av1" in ffmpeg_encoders():
- args = ["-c:v", "libaom-av1", "-crf", str(min(63, crf)), "-b:v", "0", "-cpu-used", "6", "-row-mt", "1", "-pix_fmt", pix]
- args += hdr_tags if hdr else (_sdr_bt709("libaom-av1")[1] if keep_bt709 else [])
- else:
- die("--codec av1 needs an AV1 encoder (libsvtav1 or libaom-av1) and this ffmpeg build has neither", kind="missing_tool",
- hint="install an ffmpeg built with SVT-AV1 (most distribution builds are), or use --codec hevc")
- return args + ["-movflags", "+faststart"]
- if codec == "prores":
- if "prores_ks" not in ffmpeg_encoders():
- die("--codec prores needs the prores_ks encoder and this ffmpeg build lacks it", kind="missing_tool")
- return ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"] + (hdr_tags if hdr else [])
- die(f"unknown --codec {codec!r} (one of {', '.join(CODECS)})")
- return []
-
-
-def _x264_raw(crf: int, preset: str, keep_bt709: bool = True) -> List[str]:
- args = ["-c:v", "libx264", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
- if keep_bt709:
- args += bt709_tag_args("libx264")
- return args
-
-
-def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) -> List[str]:
- """SDR H.264 encoder args -- or, when --codec named another encoder, that encoder's SDR args
- (color.py's --to-sdr path builds its own H.264 line; the flag still has to reach it)."""
- if STATE.codec and STATE.codec != "h264":
- return encoder_args(STATE.codec, crf, preset, None, keep_bt709)
- return _x264_raw(crf, preset, keep_bt709)
-
-
-def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium") -> List[str]:
- """Encoder args that preserve what the source is.
-
- SDR sources -> H.264 8-bit tagged BT.709 (x264_args). HDR sources (HDR10/PQ, HLG,
- Dolby Vision base layer, BT.2020) -> HEVC Main10 with the source's own colour tags,
- so cutting/captioning/fitting an iPhone HDR clip stays HDR instead of becoming a
- washed-out file mislabelled as BT.709. Use color.py --to-sdr when SDR is wanted.
- """
- if STATE.codec:
- return encoder_args(STATE.codec, crf, preset, meta)
- v = (meta or {}).get("video") or {}
- if not v.get("hdr"):
- return x264_args(crf, preset)
- cs = v.get("color_space") or "bt2020nc"
- prim = v.get("color_primaries") or "bt2020"
- trc = v.get("color_transfer") or "arib-std-b67"
- x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
- return ["-c:v", "libx265", "-preset", preset, "-crf", str(min(51, crf + 2)), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
- "-x265-params", x265, "-colorspace", cs, "-color_primaries", prim, "-color_trc", trc, "-movflags", "+faststart"]
-
-
-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 is_audio_output(output_path: str) -> bool:
- """True when the output extension is an audio-only container (.wav, .flac, .mp3, .m4a, .aac, .ogg, .opus).
-
- Such a file cannot hold a video stream and, for .wav, cannot hold compressed audio: scripts use
- this to drop the picture (-vn) and to pick the codec from the extension instead of AAC.
- """
- return os.path.splitext(output_path)[1].lower() in AUDIO_CODECS
-
-
-def db_to_linear(db: float) -> float:
- return 10 ** (db / 20.0)
-
-
-def read_text_or_die(path: str, flag: str) -> str:
- """Read a caller-supplied UTF-8 text file (a cue list, chapters, notes) or fail as kind input
- with the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback."""
- if os.path.isdir(path):
- # checked first: Windows raises PermissionError, not IsADirectoryError, for a directory
- die(f"{flag}: {path} is a directory, not a text file")
- try:
- with open(path, "r", encoding="utf-8") as fh:
- return fh.read()
- except FileNotFoundError:
- die(f"{flag}: {path} does not exist")
- except IsADirectoryError:
- die(f"{flag}: {path} is a directory, not a text file")
- except UnicodeDecodeError as e:
- die(f"{flag}: {path} is not UTF-8 text ({e.reason} at byte {e.start}); save it as UTF-8")
- except OSError as e:
- die(f"{flag}: cannot read {path}: {e.strerror}")
- return "" # unreachable
-
-
-def keyframes_near(path: str, t: float, window: float = 5.0) -> List[float]:
- """Video keyframe timestamps within +-window seconds of t, ascending. Read with
- -read_intervals so a long file is not scanned end to end; empty when ffprobe cannot say."""
- ffprobe = require_tool("ffprobe")
- lo = max(0.0, t - window)
- proc = run([ffprobe, "-v", "error", "-select_streams", "v:0", "-skip_frame", "nokey",
- "-read_intervals", f"{lo:.3f}%{t + window:.3f}", "-show_entries", "frame=pts_time",
- "-of", "csv=p=0", path], quiet=True, check=False)
- if proc.returncode != 0:
- return []
- out: List[float] = []
- for line in proc.stdout.splitlines():
- try:
- out.append(round(float(line.strip().rstrip(",")), 3))
- except ValueError:
- continue
- return sorted(set(out))
-
-
-def measured_level_dbfs(path: str, seconds: float = 120.0) -> Optional[Dict[str, float]]:
- """Mean and peak level of the first `seconds` of audio (volumedetect), in dBFS; None if unmeasurable.
- Cheap enough to run once as a hint when a threshold-based tool found nothing."""
- ffmpeg = require_tool("ffmpeg")
- proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.0f}", "-i", path, "-vn",
- "-af", "volumedetect", "-f", "null", "-"], check=False)
- m_mean = re.search(r"mean_volume:\s*(-?[0-9.]+) dB", proc.stderr)
- m_max = re.search(r"max_volume:\s*(-?[0-9.]+) dB", proc.stderr)
- if not (m_mean and m_max):
- return None
- return {"mean_dbfs": float(m_mean.group(1)), "peak_dbfs": float(m_max.group(1))}
-
-
-def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
- """Sample luma/saturation statistics (signalstats) and guess whether the picture is Log-encoded.
-
- Log gammas (S-Log3, V-Log, C-Log, HLG-looking flat profiles) put black around 90-95/255 and
- white below ~235 with low saturation: the image looks grey and flat but is tagged as plain SDR.
- """
- ffmpeg = require_tool("ffmpeg")
- cmd = [ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.1f}", "-i", path, "-an",
- "-vf", "fps=2,signalstats,metadata=print:file=-", "-f", "null", "-"]
- proc = run_analysis(cmd, check=False)
- vals: Dict[str, List[float]] = {}
- for line in proc.stdout.splitlines():
- if "lavfi.signalstats." in line and "=" in line:
- key, val = line.split("lavfi.signalstats.", 1)[1].split("=", 1)
- try:
- vals.setdefault(key, []).append(float(val))
- except ValueError:
- pass
- if not vals.get("YAVG"):
- return {"error": "no frames analysed"}
- def mean(k: str) -> float:
- v = vals.get(k) or [0.0]
- return sum(v) / len(v)
- ymin, ymax, yavg, sat = min(vals.get("YMIN") or [0]), max(vals.get("YMAX") or [255]), mean("YAVG"), mean("SATAVG")
- # signalstats reports in the source bit depth; normalise everything to an 8-bit scale
- scale = 1.0
- if ymax > 255 or yavg > 255:
- scale = 1 / 4.0 if ymax <= 1023 else (1 / 16.0 if ymax <= 4095 else 1 / 256.0) # 10 / 12 / 16-bit
- ymin, ymax, yavg, sat = ymin * scale, ymax * scale, yavg * scale, sat * scale
- # 5th/95th percentile of per-frame lows/highs is more robust than the absolute min/max
- lows = sorted(x * scale for x in (vals.get("YLOW") or vals.get("YMIN") or [0]))
- highs = sorted(x * scale for x in (vals.get("YHIGH") or vals.get("YMAX") or [255]))
- p_low = lows[len(lows) // 20]
- p_high = highs[-1 - len(highs) // 20]
- looks_log = p_low >= 64 and p_high <= 235 and sat < 40
- return {
- "scale": "8-bit equivalent",
- "y_min": round(ymin, 1), "y_max": round(ymax, 1), "y_avg": round(yavg, 1), "y_low_p5": round(p_low, 1), "y_high_p95": round(p_high, 1),
- "saturation_avg": round(sat, 1),
- "looks_like_log": looks_log,
- "note": ("flat, low-contrast, desaturated picture tagged as SDR: probably a Log profile (S-Log/V-Log/C-Log). "
- "Apply the camera's conversion LUT with color.py --lut" if looks_log else "contrast and saturation look like normal display-referred SDR"),
- }
-
-
-BRAND_DEFAULTS: Dict[str, Any] = {
- "font": "DejaVu Sans",
- "font_file": None,
- "colors": {"primary": "FFD200", "text": "FFFFFF", "outline": "000000", "background": "101418", "accent": "1E6F8E"},
- "logo": None,
- "logo_position": "top-right",
- "logo_scale": 160,
- "logo_opacity": 0.9,
- "safe_margin": 48,
- "caption": {"size": 26, "position": "bottom", "animate": "pop", "karaoke": False, "bold": True, "outline": 2},
- # 1.12: one place for the caption look every project shares. `styles.caption` is the documented
- # spelling (`{font, size, colour, box, position}`, British or American "colour"); the older
- # top-level `caption` block still works and `styles.caption` wins where both name the same key.
- "styles": {},
- "lang": None,
- "loudness": {"lufs": -14, "tp": -1},
-}
-
-
-def load_brand(path: Optional[str]) -> Dict[str, Any]:
- """Load brand.json (fonts, colours, logo, safe margins, caption defaults); missing keys fall back to defaults."""
- import copy
- brand = copy.deepcopy(BRAND_DEFAULTS)
- brand["_stated"] = {}
- if not path:
- return brand
- if not os.path.exists(path):
- die(f"brand file not found: {path}")
- try:
- data = json.loads(Path(path).read_text(encoding="utf-8"))
- except ValueError as exc:
- die(f"brand file is not valid JSON: {exc}")
- base = Path(path).resolve().parent
- for k, v in data.items():
- if isinstance(v, dict) and isinstance(brand.get(k), dict):
- brand[k].update(v)
- else:
- brand[k] = v
- for key in ("logo", "font_file"):
- if brand.get(key) and not os.path.isabs(brand[key]):
- brand[key] = str(base / brand[key])
- brand["_path"] = str(path)
- # What the FILE said, separate from BRAND_DEFAULTS' filler: a brand.json that never mentions
- # a font must not read as "the caller chose a font" (which would switch font-by-script off).
- brand["_stated"] = data
- return brand
-
-
-
-def brand_states_font(brand: Dict[str, Any]) -> bool:
- """Did the brand FILE actually name a font (top-level `font`, `caption.font` or
- `styles.caption.font`)? BRAND_DEFAULTS always supplies one, so the merged document can never
- answer this -- and treating the default filler as the caller's choice switched font-by-script
- off for every branded job (review 10)."""
- stated = brand.get("_stated") or {}
- if stated.get("font"):
- return True
- for block in (stated.get("caption"), (stated.get("styles") or {}).get("caption")):
- if isinstance(block, dict) and block.get("font"):
- return True
- return False
-
-
-def brand_caption_style(brand: Dict[str, Any]) -> Dict[str, Any]:
- """The effective caption style of a brand file: the top-level `caption` block updated with
- `styles.caption`, with `colour` normalised to `color`. Explicit flags still beat both."""
- style: Dict[str, Any] = dict(brand.get("caption") or {})
- extra = (brand.get("styles") or {}).get("caption") or {}
- style.update(extra)
- if "colour" in style and "color" not in style:
- style["color"] = style.pop("colour")
- style.pop("colour", None)
- return style
-
-
-def color_hex(value: str) -> str:
- """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'."""
- v = str(value).strip().lstrip("#")
- if v.lower().startswith("0x"):
- v = v[2:]
- if len(v) != 6:
- die(f"colour must be RRGGBB, got '{value}'")
- return v.upper()
-
-
-_COLOR_TOKEN_RE = re.compile(r"^(0[xX][0-9A-Fa-f]{6,8}|#[0-9A-Fa-f]{6,8}|[A-Za-z][A-Za-z0-9]*)(@(?:0(?:\.\d+)?|1(?:\.0+)?|\.\d+))?$") # alpha is 0..1; "red@2" used to reach ffmpeg
-
-
-def validate_color(value: str, flag: str = "--color") -> str:
- """Refuse a colour argument that isn't a plain ffmpeg colour token (named colour, 0xRRGGBB[AA],
- #RRGGBB[AA], optionally with an @alpha suffix). Every caller that string-formats a colour flag
- straight into a filter graph (color=c=..., tpad=...:color=..., rotate=...:fillcolor=...) must
- validate it first -- ffmpeg filter options are comma/colon-delimited, so an unvalidated value
- containing those characters lets a caller splice in an entirely different filter (a real,
- demonstrated filter-graph injection: --color "black,drawtext=text=..." renders arbitrary burnt-in
- text), not just an odd colour. This is the same "no filter graph accepted from the caller"
- invariant every other typed flag in this codebase already holds to."""
- if not _COLOR_TOKEN_RE.match(value):
- die(f"{flag} must be a plain colour (a name, 0xRRGGBB[AA], or #RRGGBB[AA], optionally @alpha), got '{value}'")
- return value
-
-
-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}"
diff --git a/scripts/_common/__init__.py b/scripts/_common/__init__.py
new file mode 100644
index 0000000..2f59ed6
--- /dev/null
+++ b/scripts/_common/__init__.py
@@ -0,0 +1,187 @@
+#!/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.
+
+Since the refactor release after 1.15.0 the helpers live in one module per responsibility --
+runner (process execution and timeouts), probe (ffprobe and the measured facts), decision (the
+pure copy-vs-re-encode and capability choices), emit (result documents, die(), info()), color
+(colour tags and the HDR paths) and text (fonts, scripts, emoji, drawtext) -- and this file is a
+facade that re-exports every name they define. `import _common` and `from _common import x` mean
+exactly what they meant when this was one 3072-line module; nothing else about the package is
+part of the contract.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import types as _types
+import unicodedata
+from fractions import Fraction
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+# The standard-library modules above were module-level names of the old single-file _common and
+# stay reachable as `_common.<mod>`: a test that stands `shutil.which` up differently reaches for
+# `_common.shutil`, and it has to be the one module object every submodule calls through -- which
+# it is, since an `import` binds the same object everywhere.
+
+# Every script prints paths, help text and reports that may contain non-ASCII (Japanese examples,
+# arrows). On Windows the console streams default to a legacy code page and raise
+# UnicodeEncodeError; make them UTF-8 with replacement so a --help never crashes on encoding.
+# (First thing the package does, before any submodule can print.)
+for _stream in (sys.stdout, sys.stderr):
+ try:
+ if getattr(_stream, "encoding", "").lower().replace("-", "") != "utf8":
+ _stream.reconfigure(encoding="utf-8", errors="replace")
+ except (AttributeError, ValueError):
+ pass
+
+# The submodules import each other; importing runner first pulls the whole graph in (see the
+# deferred imports at the foot of runner.py and emit.py). The `from ... import ...` lines below
+# are the facade proper: every public and underscore name any caller in scripts/, mcp/, tests/,
+# demos/ or evals/ has ever reached for through `_common`.
+
+from _common.runner import (
+ add_common, apply_common, _check_existing_output, _check_no_overwrite_input, _check_output_path, child_args,
+ child_limit, _CHILDREN, _cleanup_partial_output, _cmdline, CODECS, Context, _CRF_DEFAULT, DEFAULT_TIMEOUT,
+ _DRAWTEXT_PENDING, _DRAWTEXT_TMPDIR, _drawtext_tmpdir, dry_run_input_pending, _ENCODERS, _env_timeout,
+ ERROR_CODE, ERROR_RETRYABLE, EVEN_SCALE, _execute, _fail, ffmpeg_base, ffmpeg_encoders, _FFMPEG_VERSION,
+ ffmpeg_version, flush_drawtext_textfiles, INSTALL_HINTS, install_signal_handlers, _is_ffmpeg, _limit_for,
+ _odd_dimension_retry, _on_signal, _OutputLock, _pid_dead, place_output, PROBE_TIMEOUT, _progress_line,
+ read_text_or_die, refuse_output_is_input, _remember_output, require_tool, run, run_analysis, _run_captured,
+ run_keeping_subtitles, run_tool, _run_with_progress, shell_quote, _SIGNALS_INSTALLED, _stage_existing_output,
+ STATE, _timed_out, _unwatch, _watch, X264_PRESETS
+)
+from _common.emit import (
+ _brief, _BRIEF_DROP, _brief_summary, _CURRENT_CTX, die, emit, info, _plan_at_exit, _plan_inputs, _PLAN_STRIP,
+ PLAN_VERSION, print_json, _result_v2, _set_current_ctx, _V2_HANDLED, write_plan
+)
+from _common.probe import (
+ analyze_levels, _aspect_string, _bit_depth, decode_pcm_mono, fingerprint, _fraction, keyframes_near,
+ measured_level_dbfs, MEDIA_EXT, _output_failed, probe, rms_envelope, _to_float, _to_int, verify_output
+)
+from _common.decision import (
+ aac_args, add_pad_fill_args, audio_codec_for, AUDIO_CODECS, brand_caption_style, BRAND_DEFAULTS,
+ brand_states_font, cfr_args, concat_list_line, db_to_linear, default_output, encoder_args, escape_filter_path,
+ fmt_secs, fmt_smpte_time, fmt_srt_time, is_audio_output, load_brand, MissingFpsError, pad_filters, parse_time,
+ signed_time_arg, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw
+)
+from _common.color import (
+ bt709_tag_args, color_hex, _COLOR_TOKEN_RE, _sdr_bt709, validate_color
+)
+from _common.text import (
+ ADVANCE_EM, BIDI_SCRIPTS, _char_em, char_script, default_font_file, detect_script, drawtext_boxborderw,
+ drawtext_shaping, drawtext_text_opts, emoji_asset_for, EMOJI_ASSET_HINT, emoji_clusters, emoji_codepoint_name,
+ _EMOJI_COLOR_FAMILIES, _emoji_color_font, emoji_filter_chain, _emoji_name_candidates, EMOJI_RANGES,
+ _EMOJI_REGIONAL, emoji_support, _EMOJI_SUPPORT_CACHE, _EMOJI_TAIL, escape_drawtext, _family_rank, FC_LANG,
+ _fc_list_fonts, FC_UNKNOWN, font_covers_script, font_family_for_script, font_family_of_file, FONT_FLAG_HINT,
+ font_for_script, FONT_INSTALL_HINT, fonts_dir_covers_script, has_emoji, _is_emoji_base, _is_emoji_char,
+ _is_mark, _KEYCAP, _KEYCAP_BASES, LANGUAGE_NAMES, LATIN_EM, LEADING_VOWELS, _libass_color_probe, needs_shaping,
+ NO_SPACE_SCRIPTS, PREFERRED_FAMILIES, resolve_emoji_assets, _SCRIPT_FONT_CACHE, _script_font_entry,
+ script_font_for_text, script_font_status, _script_font_uncached, _SCRIPT_RANGES, SCRIPTS, _SHAPING_BUILD_CACHE,
+ SHAPING_SCRIPTS, text_width_em, _VS15, _VS16, WINDOWS_FONTS, _ZWJ
+)
+
+from _common import color, decision, runner, text # noqa: F401,E402
+
+# `_common.emit` and `_common.probe` are the FUNCTIONS, as they have always been -- the
+# from-imports above rebound the package attribute the submodule import had set. The two modules
+# that share a name with a helper are reached through sys.modules instead; nothing outside this
+# package refers to them. Consequently `import _common.emit` / `import _common.probe` bind the
+# function, not the module: reach the modules as `from _common import emit as _` never, use
+# `sys.modules["_common.emit"]` or `importlib.import_module("_common.emit")` instead.
+_emit_module = sys.modules["_common.emit"]
+_probe_module = sys.modules["_common.probe"]
+
+_MODULES = (runner, _emit_module, _probe_module, decision, color, text)
+
+
+class _Facade(_types.ModuleType):
+ """The package module's own type, so that rebinding a name on the facade rebinds it on the
+ module that defines it.
+
+ Tests reach into `_common` to stand a name up differently for one case -- `_common._FFMPEG_VERSION
+ = (7, 1)`, `mock.patch("_common.<name>")`. While this was one module that simply worked; against
+ a package, a plain re-export is a second binding and the defining module goes on calling its
+ own. Mirroring the assignment keeps those call sites honest without asking every helper to look
+ itself up through the facade. Names mutated in place (STATE, the caches) need none of this --
+ the facade re-exports the same object.
+ """
+
+ # The globals a helper REBINDS (`global x; x = ...`) live in their submodule; the facade's
+ # own copy is the import-time binding and would read stale. Reads of these names go to the
+ # defining module (audit 14, P1-1); every other name is a plain re-export of the same object.
+ _LIVE = {
+ "_FFMPEG_VERSION": "runner", "_CRF_DEFAULT": "runner", "_SIGNALS_INSTALLED": "runner",
+ "_DRAWTEXT_TMPDIR": "runner", "_ENCODERS": "runner", "_CURRENT_CTX": "emit",
+ }
+
+ def __getattribute__(self, name):
+ live = _types.ModuleType.__getattribute__(self, "_LIVE")
+ if name in live:
+ return getattr(sys.modules["_common." + live[name]], name)
+ return _types.ModuleType.__getattribute__(self, name)
+
+ def __setattr__(self, name, value):
+ _types.ModuleType.__setattr__(self, name, value)
+ if name.startswith("__") and name.endswith("__"):
+ return # importlib.reload() rewrites __file__/__spec__: those stay per module (P1-2)
+ for _m in _MODULES:
+ if name in _m.__dict__:
+ _types.ModuleType.__setattr__(_m, name, value)
+
+ def __delattr__(self, name):
+ _types.ModuleType.__delattr__(self, name)
+ if name.startswith("__") and name.endswith("__"):
+ return
+ for _m in _MODULES:
+ if name in _m.__dict__:
+ _types.ModuleType.__delattr__(_m, name)
+
+
+sys.modules[__name__].__class__ = _Facade
+
+__all__ = [
+ "Any", "Dict", "Fraction", "List", "Optional", "Path", "Sequence", "Tuple", "argparse", "json", "math", "os",
+ "platform", "re", "shutil", "subprocess", "sys", "unicodedata",
+ "aac_args", "add_common", "add_pad_fill_args", "ADVANCE_EM", "analyze_levels", "apply_common", "_aspect_string",
+ "audio_codec_for", "AUDIO_CODECS", "BIDI_SCRIPTS", "_bit_depth", "brand_caption_style", "BRAND_DEFAULTS",
+ "brand_states_font", "_brief", "_BRIEF_DROP", "_brief_summary", "bt709_tag_args", "cfr_args", "_char_em",
+ "char_script", "_check_existing_output", "_check_no_overwrite_input", "_check_output_path", "child_args",
+ "child_limit", "_CHILDREN", "_cleanup_partial_output", "_cmdline", "CODECS", "color_hex", "_COLOR_TOKEN_RE",
+ "concat_list_line", "Context", "_CRF_DEFAULT", "_CURRENT_CTX", "db_to_linear", "decode_pcm_mono",
+ "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw",
+ "_DRAWTEXT_PENDING", "drawtext_shaping", "drawtext_text_opts", "_DRAWTEXT_TMPDIR", "_drawtext_tmpdir",
+ "dry_run_input_pending", "emit", "emoji_asset_for", "EMOJI_ASSET_HINT", "emoji_clusters",
+ "emoji_codepoint_name", "_EMOJI_COLOR_FAMILIES", "_emoji_color_font", "emoji_filter_chain",
+ "_emoji_name_candidates", "EMOJI_RANGES", "_EMOJI_REGIONAL", "emoji_support", "_EMOJI_SUPPORT_CACHE",
+ "_EMOJI_TAIL", "encoder_args", "_ENCODERS", "_env_timeout", "ERROR_CODE", "ERROR_RETRYABLE", "escape_drawtext",
+ "escape_filter_path", "EVEN_SCALE", "_execute", "_fail", "_family_rank", "FC_LANG", "_fc_list_fonts",
+ "FC_UNKNOWN", "ffmpeg_base", "ffmpeg_encoders", "_FFMPEG_VERSION", "ffmpeg_version", "fingerprint",
+ "flush_drawtext_textfiles", "fmt_secs", "fmt_smpte_time", "fmt_srt_time", "font_covers_script",
+ "font_family_for_script", "font_family_of_file", "FONT_FLAG_HINT", "font_for_script", "FONT_INSTALL_HINT",
+ "fonts_dir_covers_script", "_fraction", "has_emoji", "info", "INSTALL_HINTS", "install_signal_handlers",
+ "is_audio_output", "_is_emoji_base", "_is_emoji_char", "_is_ffmpeg", "_is_mark", "_KEYCAP", "_KEYCAP_BASES",
+ "keyframes_near", "LANGUAGE_NAMES", "LATIN_EM", "LEADING_VOWELS", "_libass_color_probe", "_limit_for",
+ "load_brand", "measured_level_dbfs", "MEDIA_EXT", "MissingFpsError", "needs_shaping", "NO_SPACE_SCRIPTS",
+ "_odd_dimension_retry", "_on_signal", "_output_failed", "_OutputLock", "pad_filters", "parse_time", "_pid_dead",
+ "place_output", "_plan_at_exit", "_plan_inputs", "_PLAN_STRIP", "PLAN_VERSION", "PREFERRED_FAMILIES",
+ "print_json", "probe", "PROBE_TIMEOUT", "_progress_line", "read_text_or_die", "refuse_output_is_input",
+ "_remember_output", "require_tool", "resolve_emoji_assets", "_result_v2", "rms_envelope", "run", "run_analysis",
+ "_run_captured", "run_keeping_subtitles", "run_tool", "_run_with_progress", "_SCRIPT_FONT_CACHE",
+ "_script_font_entry", "script_font_for_text", "script_font_status", "_script_font_uncached", "_SCRIPT_RANGES",
+ "SCRIPTS", "_sdr_bt709", "_set_current_ctx", "_SHAPING_BUILD_CACHE", "SHAPING_SCRIPTS", "shell_quote",
+ "_SIGNALS_INSTALLED", "signed_time_arg", "_stage_existing_output", "STATE", "SVT_PRESET", "text_width_em",
+ "time_arg", "_timed_out", "_to_float", "_to_int", "_unwatch", "_V2_HANDLED", "validate_color", "verify_output",
+ "video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS",
+ "_x264_raw", "_ZWJ"
+]
diff --git a/scripts/_common/color.py b/scripts/_common/color.py
new file mode 100644
index 0000000..7f408cd
--- /dev/null
+++ b/scripts/_common/color.py
@@ -0,0 +1,69 @@
+"""Colour: the bt709 tagging arguments and the HDR-to-SDR conversion path, plus colour-token
+validation for the tools that take a `--color`.
+"""
+from __future__ import annotations
+
+import re
+from typing import List, Tuple
+from _common.emit import die
+from _common.runner import ffmpeg_version
+
+
+def bt709_tag_args(encoder: str = "libx264") -> List[str]:
+ """Tag an SDR output as BT.709 without touching its pixels.
+
+ Up to FFmpeg 7.0 the output options -colorspace/-color_primaries/-color_trc were tags only.
+ 7.1 added colourspace negotiation to libavfilter and feeds those options into the graph's
+ output constraints, so on a source whose bitstream carries no colour tags (test sources,
+ screen recordings, many cameras) the CLI now auto-inserts a *real* matrix conversion (its
+ guess for "unknown" is bt601) into every SDR re-encode: a --lut-strength 0 no-op grade
+ came back ~24 dB PSNR from its source on 7.1. From 7.1 on, the tags therefore go through
+ the encoder's own VUI parameters instead, which libavfilter never sees; a source that is
+ genuinely tagged bt601/bt2020 is left alone either way (it keeps its own tags on the old
+ path, and the encoder VUI is a label, not a conversion, on the new one).
+ """
+ if ffmpeg_version() < (7, 1):
+ return ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
+ if encoder == "libx265":
+ return ["-x265-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]
+ return ["-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]
+
+
+def _sdr_bt709(encoder: str) -> "Tuple[str, List[str]]":
+ """BT.709 SDR tags for `encoder` as (encoder-params string, extra output options): the two
+ spellings bt709_tag_args() picks between, split so a caller that already builds an encoder
+ params string can merge them (the option given twice keeps only the last)."""
+ if ffmpeg_version() < (7, 1):
+ return "", ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
+ if encoder == "libsvtav1":
+ return "color-primaries=1:transfer-characteristics=1:matrix-coefficients=1", []
+ if encoder == "libaom-av1":
+ return "", [] # no VUI params option; an untagged 8-bit stream reads as BT.709 everywhere
+ return "colorprim=bt709:transfer=bt709:colormatrix=bt709", []
+
+
+def color_hex(value: str) -> str:
+ """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'."""
+ v = str(value).strip().lstrip("#")
+ if v.lower().startswith("0x"):
+ v = v[2:]
+ if len(v) != 6:
+ die(f"colour must be RRGGBB, got '{value}'")
+ return v.upper()
+
+
+_COLOR_TOKEN_RE = re.compile(r"^(0[xX][0-9A-Fa-f]{6,8}|#[0-9A-Fa-f]{6,8}|[A-Za-z][A-Za-z0-9]*)(@(?:0(?:\.\d+)?|1(?:\.0+)?|\.\d+))?$") # alpha is 0..1; "red@2" used to reach ffmpeg
+
+
+def validate_color(value: str, flag: str = "--color") -> str:
+ """Refuse a colour argument that isn't a plain ffmpeg colour token (named colour, 0xRRGGBB[AA],
+ #RRGGBB[AA], optionally with an @alpha suffix). Every caller that string-formats a colour flag
+ straight into a filter graph (color=c=..., tpad=...:color=..., rotate=...:fillcolor=...) must
+ validate it first -- ffmpeg filter options are comma/colon-delimited, so an unvalidated value
+ containing those characters lets a caller splice in an entirely different filter (a real,
+ demonstrated filter-graph injection: --color "black,drawtext=text=..." renders arbitrary burnt-in
+ text), not just an odd colour. This is the same "no filter graph accepted from the caller"
+ invariant every other typed flag in this codebase already holds to."""
+ if not _COLOR_TOKEN_RE.match(value):
+ die(f"{flag} must be a plain colour (a name, 0xRRGGBB[AA], or #RRGGBB[AA], optionally @alpha), got '{value}'")
+ return value
diff --git a/scripts/_common/decision.py b/scripts/_common/decision.py
new file mode 100644
index 0000000..90dae5c
--- /dev/null
+++ b/scripts/_common/decision.py
@@ -0,0 +1,415 @@
+"""Pure choices: given facts (a probe document, a codec name, a path, a flag value), return the
+arguments or the value that follows from them.
+
+Nothing here starts a subprocess or touches a media file, which is what makes the copy-vs-re-encode
+and encoder-selection rules testable on their own.
+"""
+from __future__ import annotations
+
+import json
+import os
+import argparse
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from _common.color import bt709_tag_args, _sdr_bt709
+from _common.emit import die
+from _common.runner import CODECS, STATE, ffmpeg_encoders
+
+
+def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken: float = 0.0) -> str:
+ """The letterbox/pillarbox step shared by fit.py and export.py, as one -vf segment.
+
+ fill="color": scale to fit, then pad with a solid colour (the historical behaviour).
+ fill="blur": the bars are a blurred, scaled-to-cover copy of the same frame -- what every
+ phone editor's "make it vertical" does with landscape footage (#139). Built as a small
+ graph inside the -vf chain: split, one branch scaled to cover and cropped to the frame
+ then boxblur'ed, the other scaled to fit, overlaid centred. Only `filter:boxblur` is
+ needed beyond the usual scale/pad set, and that is already required by redact.py.
+ `darken` > 0 also dims that background copy by that much brightness (eq), so the picture in
+ front reads as the subject instead of competing with a bright blurred copy of itself --
+ what `fit.py --fit blur` uses (1.14)."""
+ if fill == "blur":
+ # boxblur rejects a radius larger than half the smaller dimension ("radius 20, must be
+ # <= 8" on a 16 px target); clamp instead of failing an otherwise valid request
+ radius = max(1, min(int(blur), max(1, min(out_w, out_h) // 2 - 1)))
+ return (f"split[__fitfg][__fitbg];"
+ f"[__fitbg]scale={out_w}:{out_h}:force_original_aspect_ratio=increase,crop={out_w}:{out_h},"
+ f"boxblur={radius}:2" + (f",eq=brightness=-{darken:g}" if darken else "") + "[__fitbgb];"
+ f"[__fitfg]scale={out_w}:{out_h}:force_original_aspect_ratio=decrease[__fitfgs];"
+ f"[__fitbgb][__fitfgs]overlay=(W-w)/2:(H-h)/2:format=auto")
+ return f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease,pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={color}"
+
+
+def add_pad_fill_args(parser: "argparse.ArgumentParser") -> None:
+ parser.add_argument("--pad-fill", choices=["color", "blur"], default="color",
+ help="what fills the letterbox/pillarbox bars under --fit pad: a solid --pad-color (default) or a blurred, scaled-up copy of the frame")
+ parser.add_argument("--pad-blur", type=int, default=20, help="blur radius in pixels for --pad-fill blur (default 20)")
+
+
+# x264 preset names mapped onto SVT-AV1's 0-13 speed scale (lower = slower / better)
+SVT_PRESET = {"ultrafast": 12, "superfast": 11, "veryfast": 10, "faster": 9, "fast": 8, "medium": 6, "slow": 4, "slower": 3, "veryslow": 2, "placebo": 1}
+
+
+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}"))
+
+
+class MissingFpsError(ValueError):
+ """parse_time() saw an hh:mm:ss:ff SMPTE timecode but no fps was given to convert it -- distinct
+ from a plain ValueError so a caller that falls back to treating unparseable text as a literal
+ line (e.g. caption.py's free-text cue format) can still fail loudly on this one, instead of
+ silently swallowing a mistyped/missing --fps as an auto-timed line of digits."""
+
+
+def concat_list_line(path: str) -> str:
+ """One `file '...'` line for the concat demuxer. The demuxer reads backslash as an escape
+ inside the quoted form, so a Windows path (C:\\Users\\...\\part000.mp4) must be written
+ with forward slashes -- ffmpeg opens either spelling on Windows -- and a single quote in the
+ name is closed, escaped and reopened. Shared by cut.py (multi-segment) and sequence.py."""
+ escaped = str(path).replace("\\", "/").replace("'", "'\\''")
+ return f"file '{escaped}'"
+
+
+def fmt_secs(value: Optional[float]) -> str:
+ """`12.345s`, or `?s` when the probe had no duration (MPEG-TS without a duration tag, a
+ stream whose container and streams all omit it). Every writing tool prints the duration
+ of what it wrote; formatting None with :.3f used to raise TypeError after a successful
+ encode, in 25+ scripts."""
+ return "?s" if value is None else f"{value:.3f}s"
+
+
+def parse_time(value: str, fps: Optional[float] = None) -> float:
+ """Accept seconds ('12.5'), mm:ss ('1:30'), hh:mm:ss(.ms) ('00:01:30.250'), SRT '00:01:30,250',
+ or -- when `fps` is given -- SMPTE non-drop-frame timecode 'hh:mm:ss:ff' ('00:01:30:15')."""
+ v = value.strip().replace(",", ".")
+ if not v:
+ raise ValueError("empty time")
+ if "@" in v:
+ # 1.9: 'hh:mm:ss:[email protected]' names the timecode's rate explicitly (docs/design-decisions.md,
+ # time grammar); it overrides the source fps a tool passed in, and is meaningless without
+ # the four-part form
+ v, _, rate = v.rpartition("@")
+ if "@" in v:
+ raise ValueError(f"'{value}': only one @fps suffix is allowed")
+ try:
+ fps = float(rate)
+ except ValueError:
+ raise ValueError(f"bad @fps suffix in '{value}' (expected a number such as @29.97)")
+ if fps <= 0:
+ raise ValueError(f"bad @fps suffix in '{value}': the rate must be positive")
+ if len(v.split(":")) != 4:
+ raise ValueError(f"'{value}': the @fps suffix belongs to an hh:mm:ss:ff timecode, not to seconds or mm:ss")
+ parts = v.split(":")
+ if len(parts) == 4:
+ if fps is None or fps <= 0:
+ raise MissingFpsError(f"'{value}' looks like an hh:mm:ss:ff SMPTE timecode, but no fps was given to convert its frame count to seconds (append @fps, e.g. {value}@29.97, or use seconds / mm:ss / hh:mm:ss.ms)")
+ h, m, s, f = parts
+ if "." in f:
+ raise ValueError(f"bad SMPTE timecode: {value}")
+ frame, whole_fps = int(f), int(round(fps))
+ if not (0 <= frame < whole_fps):
+ raise ValueError(f"bad SMPTE timecode '{value}': frame {frame} is out of range for {fps:g} fps (0-{whole_fps - 1})")
+ # Non-drop-frame: the timecode counts whole_fps frames per timecode-second, so the real
+ # time is the total frame count over the true rate (at 29.97 an hour of timecode is
+ # 3596.4 s of video). This is exactly what fmt_smpte_time() inverts; before, the two
+ # disagreed by ~0.1 % on the fractional NTSC rates and drifted apart over long files.
+ total_frames = (int(h) * 3600 + int(m) * 60 + int(s)) * whole_fps + frame
+ return total_frames / fps
+ if len(parts) > 3:
+ raise ValueError(f"bad time: {value}")
+ total = 0.0
+ for part in parts:
+ try:
+ total = total * 60 + float(part)
+ except ValueError:
+ # not the interpreter's "could not convert string to float: 'zz'" (review 9)
+ raise ValueError(f"'{value}': not a time")
+ return total
+
+
+def time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
+ """parse_time() for a command-line flag: SMPTE hh:mm:ss:ff resolves with the input's fps when
+ the caller has one, and every parse failure is a `kind: input` refusal naming the flag (so
+ `--json` callers get a failure document, never a traceback)."""
+ try:
+ return parse_time(value, fps)
+ except MissingFpsError as e:
+ die(f"{flag} {value!r}: {e}")
+ except ValueError as e:
+ die(f"{flag} {value!r}: {e} (use seconds, mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff at the source's fps or with an explicit @fps suffix)")
+ return 0.0 # unreachable
+
+
+def signed_time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
+ """time_arg() for a flag that may also be negative (an offset, not a point in time): a single
+ leading '-'/'+' is taken as the sign and the rest goes through the ordinary time grammar, so
+ `--offset -00:00:02`, `--offset -1.5` and `--offset 0:02` all mean what they read as."""
+ text = (value or "").strip()
+ sign = 1.0
+ if text[:1] in "+-":
+ sign = -1.0 if text[0] == "-" else 1.0
+ text = text[1:].strip()
+ if not text:
+ die(f"{flag} {value!r}: not a time (use seconds, mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff)")
+ return sign * time_arg(text, flag, fps)
+
+
+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 fmt_smpte_time(seconds: float, fps: float) -> str:
+ """SMPTE non-drop-frame timecode 'hh:mm:ss:ff' for a real fps (not the fractional NTSC rates
+ -- 29.97/59.94 need drop-frame counting to stay wall-clock accurate, which this does not do)."""
+ if seconds < 0:
+ seconds = 0.0
+ whole_fps = int(round(fps))
+ total_frames = int(round(seconds * fps))
+ frame = total_frames % whole_fps
+ secs_total = total_frames // whole_fps
+ h, rem = divmod(secs_total, 3600)
+ m, s = divmod(rem, 60)
+ return f"{h:02d}:{m:02d}:{s:02d}:{frame:02d}"
+
+
+def escape_filter_path(path: str) -> 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
+ on `:`, then the filter's own option parser splits key=value pairs on `:` again. A character that
+ must survive both passes needs two levels of escaping, so a Windows drive letter `D:/x.srt` is
+ written `D\\\\:/x.srt`; with a single backslash the second pass still splits at the colon and
+ ffmpeg reads `/x.srt` as the next option (`Unable to parse "original_size" option value`).
+ Backslashes are turned into forward slashes first (ffmpeg accepts them on Windows), so a backslash
+ never has to be escaped itself; `,`, `;`, `[` and `]` are graph-level characters and survive with
+ one backslash. `'` is special: the graph parser also treats a quote as the start of a quoted
+ 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=).
+ """
+ if 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("\\", "/")
+ p = p.replace(":", "\\\\:")
+ p = p.replace("'", "\\\\\\'")
+ for ch in (",", ";", "[", "]"):
+ p = p.replace(ch, "\\" + ch)
+ return p
+
+
+def cfr_args(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> List[str]:
+ """Force a constant frame rate on output when the source looks VFR (or fps is given).
+
+ VFR sources (phone/screen recordings) drift against audio after cuts and joins,
+ so every re-encoding script passes this to conform them automatically.
+ """
+ v = (meta or {}).get("video") or {}
+ if fps is None and not v.get("variable_frame_rate_suspected"):
+ return []
+ rate = fps or v.get("fps") or 30.0
+ rate = round(rate) if abs(rate - round(rate)) < 0.02 else rate
+ return ["-fps_mode", "cfr", "-r", f"{rate:g}"]
+
+
+def encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str, Any]] = None, keep_bt709: bool = True) -> List[str]:
+ """The one place that turns (--codec, --quality, --preset, source) into encoder options.
+
+ h264 -> x264 8-bit BT.709 (refuses HDR: 8-bit H.264 cannot carry it); hevc -> x265, Main10
+ with the source's tags for HDR, 8-bit BT.709 otherwise; av1 -> SVT-AV1 (libaom fallback),
+ 10-bit for HDR; prores -> ProRes 422 HQ, source tags kept. 1.8: chosen by --codec; without
+ it video_args() does what it always did (x264 for SDR, x265 Main10 for HDR).
+ """
+ v = (meta or {}).get("video") or {}
+ hdr = bool(v.get("hdr"))
+ cs = v.get("color_space") or "bt2020nc"
+ prim = v.get("color_primaries") or "bt2020"
+ trc = v.get("color_transfer") or "arib-std-b67"
+ hdr_tags = ["-colorspace", cs, "-color_primaries", prim, "-color_trc", trc]
+ if codec == "h264":
+ if hdr:
+ die(f"--codec h264 cannot carry HDR ({v.get('hdr_format') or 'BT.2020'}): 8-bit H.264 is SDR only",
+ hint="run color.py --to-sdr first, or use --codec hevc / av1 / prores, which keep the source's HDR")
+ return _x264_raw(crf, preset, keep_bt709)
+ if codec == "hevc":
+ if hdr:
+ x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
+ return ["-c:v", "libx265", "-preset", preset, "-crf", str(min(51, crf + 2)), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
+ "-x265-params", x265] + hdr_tags + ["-movflags", "+faststart"]
+ params, extra = _sdr_bt709("libx265") if keep_bt709 else ("", [])
+ return ["-c:v", "libx265", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-tag:v", "hvc1",
+ "-x265-params", "log-level=error" + (":" + params if params else "")] + extra + ["-movflags", "+faststart"]
+ if codec == "av1":
+ pix = "yuv420p10le" if hdr else "yuv420p"
+ if "libsvtav1" in ffmpeg_encoders():
+ args = ["-c:v", "libsvtav1", "-preset", str(SVT_PRESET.get(preset, 6)), "-crf", str(min(63, crf)), "-pix_fmt", pix]
+ if hdr:
+ args += hdr_tags
+ elif keep_bt709:
+ params, extra = _sdr_bt709("libsvtav1")
+ args += (["-svtav1-params", params] if params else []) + extra
+ elif "libaom-av1" in ffmpeg_encoders():
+ args = ["-c:v", "libaom-av1", "-crf", str(min(63, crf)), "-b:v", "0", "-cpu-used", "6", "-row-mt", "1", "-pix_fmt", pix]
+ args += hdr_tags if hdr else (_sdr_bt709("libaom-av1")[1] if keep_bt709 else [])
+ else:
+ die("--codec av1 needs an AV1 encoder (libsvtav1 or libaom-av1) and this ffmpeg build has neither", kind="missing_tool",
+ hint="install an ffmpeg built with SVT-AV1 (most distribution builds are), or use --codec hevc")
+ return args + ["-movflags", "+faststart"]
+ if codec == "prores":
+ if "prores_ks" not in ffmpeg_encoders():
+ die("--codec prores needs the prores_ks encoder and this ffmpeg build lacks it", kind="missing_tool")
+ return ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"] + (hdr_tags if hdr else [])
+ die(f"unknown --codec {codec!r} (one of {', '.join(CODECS)})")
+ return []
+
+
+def _x264_raw(crf: int, preset: str, keep_bt709: bool = True) -> List[str]:
+ args = ["-c:v", "libx264", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
+ if keep_bt709:
+ args += bt709_tag_args("libx264")
+ return args
+
+
+def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) -> List[str]:
+ """SDR H.264 encoder args -- or, when --codec named another encoder, that encoder's SDR args
+ (color.py's --to-sdr path builds its own H.264 line; the flag still has to reach it)."""
+ if STATE.codec and STATE.codec != "h264":
+ return encoder_args(STATE.codec, crf, preset, None, keep_bt709)
+ return _x264_raw(crf, preset, keep_bt709)
+
+
+def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium") -> List[str]:
+ """Encoder args that preserve what the source is.
+
+ SDR sources -> H.264 8-bit tagged BT.709 (x264_args). HDR sources (HDR10/PQ, HLG,
+ Dolby Vision base layer, BT.2020) -> HEVC Main10 with the source's own colour tags,
+ so cutting/captioning/fitting an iPhone HDR clip stays HDR instead of becoming a
+ washed-out file mislabelled as BT.709. Use color.py --to-sdr when SDR is wanted.
+ """
+ if STATE.codec:
+ return encoder_args(STATE.codec, crf, preset, meta)
+ v = (meta or {}).get("video") or {}
+ if not v.get("hdr"):
+ return x264_args(crf, preset)
+ cs = v.get("color_space") or "bt2020nc"
+ prim = v.get("color_primaries") or "bt2020"
+ trc = v.get("color_transfer") or "arib-std-b67"
+ x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
+ return ["-c:v", "libx265", "-preset", preset, "-crf", str(min(51, crf + 2)), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
+ "-x265-params", x265, "-colorspace", cs, "-color_primaries", prim, "-color_trc", trc, "-movflags", "+faststart"]
+
+
+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 is_audio_output(output_path: str) -> bool:
+ """True when the output extension is an audio-only container (.wav, .flac, .mp3, .m4a, .aac, .ogg, .opus).
+
+ Such a file cannot hold a video stream and, for .wav, cannot hold compressed audio: scripts use
+ this to drop the picture (-vn) and to pick the codec from the extension instead of AAC.
+ """
+ return os.path.splitext(output_path)[1].lower() in AUDIO_CODECS
+
+
+def db_to_linear(db: float) -> float:
+ return 10 ** (db / 20.0)
+
+
+BRAND_DEFAULTS: Dict[str, Any] = {
+ "font": "DejaVu Sans",
+ "font_file": None,
+ "colors": {"primary": "FFD200", "text": "FFFFFF", "outline": "000000", "background": "101418", "accent": "1E6F8E"},
+ "logo": None,
+ "logo_position": "top-right",
+ "logo_scale": 160,
+ "logo_opacity": 0.9,
+ "safe_margin": 48,
+ "caption": {"size": 26, "position": "bottom", "animate": "pop", "karaoke": False, "bold": True, "outline": 2},
+ # 1.12: one place for the caption look every project shares. `styles.caption` is the documented
+ # spelling (`{font, size, colour, box, position}`, British or American "colour"); the older
+ # top-level `caption` block still works and `styles.caption` wins where both name the same key.
+ "styles": {},
+ "lang": None,
+ "loudness": {"lufs": -14, "tp": -1},
+}
+
+
+def load_brand(path: Optional[str]) -> Dict[str, Any]:
+ """Load brand.json (fonts, colours, logo, safe margins, caption defaults); missing keys fall back to defaults."""
+ import copy
+ brand = copy.deepcopy(BRAND_DEFAULTS)
+ brand["_stated"] = {}
+ if not path:
+ return brand
+ if not os.path.exists(path):
+ die(f"brand file not found: {path}")
+ try:
+ data = json.loads(Path(path).read_text(encoding="utf-8"))
+ except ValueError as exc:
+ die(f"brand file is not valid JSON: {exc}")
+ base = Path(path).resolve().parent
+ for k, v in data.items():
+ if isinstance(v, dict) and isinstance(brand.get(k), dict):
+ brand[k].update(v)
+ else:
+ brand[k] = v
+ for key in ("logo", "font_file"):
+ if brand.get(key) and not os.path.isabs(brand[key]):
+ brand[key] = str(base / brand[key])
+ brand["_path"] = str(path)
+ # What the FILE said, separate from BRAND_DEFAULTS' filler: a brand.json that never mentions
+ # a font must not read as "the caller chose a font" (which would switch font-by-script off).
+ brand["_stated"] = data
+ return brand
+
+
+def brand_states_font(brand: Dict[str, Any]) -> bool:
+ """Did the brand FILE actually name a font (top-level `font`, `caption.font` or
+ `styles.caption.font`)? BRAND_DEFAULTS always supplies one, so the merged document can never
+ answer this -- and treating the default filler as the caller's choice switched font-by-script
+ off for every branded job (review 10)."""
+ stated = brand.get("_stated") or {}
+ if stated.get("font"):
+ return True
+ for block in (stated.get("caption"), (stated.get("styles") or {}).get("caption")):
+ if isinstance(block, dict) and block.get("font"):
+ return True
+ return False
+
+
+def brand_caption_style(brand: Dict[str, Any]) -> Dict[str, Any]:
+ """The effective caption style of a brand file: the top-level `caption` block updated with
+ `styles.caption`, with `colour` normalised to `color`. Explicit flags still beat both."""
+ style: Dict[str, Any] = dict(brand.get("caption") or {})
+ extra = (brand.get("styles") or {}).get("caption") or {}
+ style.update(extra)
+ if "colour" in style and "color" not in style:
+ style["color"] = style.pop("colour")
+ style.pop("colour", None)
+ return style
diff --git a/scripts/_common/emit.py b/scripts/_common/emit.py
new file mode 100644
index 0000000..892a9fc
--- /dev/null
+++ b/scripts/_common/emit.py
@@ -0,0 +1,287 @@
+"""Result documents: die(), info(), emit(), the brief and 2.0 shapes, and the plan file.
+
+Every script ends in exactly one of these: emit() on success, die() on failure. Both print a
+single JSON document when --json is on and record the Context the caller passed.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import sys
+from typing import Any, Dict, List, Optional, Sequence
+from _common.runner import Context, ERROR_CODE, ERROR_RETRYABLE, STATE
+
+
+def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]" = None, **extra: Any) -> "None":
+ """Exit with a message. Under --json also print a machine-readable failure document
+ (status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged.
+
+ `extra` fields are added to the failure document: a tool whose *result* failed (check.py's
+ platform rows, render.py's check stage, batch.py's per-item results, verify.py's steps) keeps
+ reporting that detail while the top-level status says failed. Before 1.4.3 those four printed
+ `status: "completed"` next to a non-zero exit code, so a caller keying on the status alone
+ read a failed delivery as a success."""
+ hint = extra.pop("hint", None)
+ ctx = ctx or STATE # 1.10: the optional per-request Context (2.0 makes it required); STATE is the default instance
+ _set_current_ctx(ctx) # the atexit hook has no argument: it reads the ctx emit()/die() last used
+ ctx.plan = None # a failed run plans nothing (the exit hook must not write a plan for it)
+ STATE.plan = None # the hook falls back to STATE when nothing passed a ctx; a failed run plans nothing there either
+ sys.stderr.write(f"error: {msg}\n" + (f"hint: {hint}\n" if hint else ""))
+ if ctx.json:
+ doc: Dict[str, Any] = {
+ "status": "failed", "exit_code": code,
+ "error": {
+ "kind": kind, "message": msg,
+ "code": ERROR_CODE.get(kind, "INTERNAL_ERROR"),
+ "retryable": ERROR_RETRYABLE,
+ },
+ "commands": list(ctx.commands),
+ }
+ if hint:
+ doc["error"]["hint"] = hint
+ doc.update(extra)
+ print_json(doc)
+ sys.exit(code)
+
+
+def info(msg: str, ctx: "Optional[Context]" = None) -> None:
+ # under --dry-run nothing is written; do not let scripts claim otherwise
+ ctx = ctx or STATE
+ if msg.startswith("wrote ") and ctx.dry_run:
+ msg = "[dry-run] would write " + msg[len("wrote "):]
+ sys.stderr.write(f"{msg}\n")
+
+
+# The atexit plan hook takes no arguments, so emit()/die() record the Context they were given
+# here; nothing passed a ctx = it stays None and the hook falls back to STATE, as before (1.10).
+_CURRENT_CTX: "Optional[Context]" = None
+
+
+def _set_current_ctx(ctx: "Context") -> None:
+ global _CURRENT_CTX
+ _CURRENT_CTX = ctx
+
+
+def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any) -> None:
+ """Final stdout line: the output path, or a JSON document with --json.
+
+ `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
+ omitted, every read falls back to the process-global STATE as before."""
+ ctx = ctx or STATE
+ _set_current_ctx(ctx) # so the atexit hook writes (or skips) this ctx's plan, not STATE's
+ meta: Dict[str, Any] = {}
+ if output and not ctx.dry_run:
+ meta = verify_output(output) # dies (status: failed, kind: output) if the artifact is unusable
+ if ctx.json:
+ doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": ctx.dry_run, "commands": list(ctx.commands)}
+ if meta:
+ doc["probe"] = meta
+ # What this tool itself verified about its artifact (issue #189 C, "verify as part of the
+ # contract"): the probe every writing tool runs, plus the measurements a tool adds
+ # (`verification` extra: loudness after the write, a platform check). `verified` is true
+ # only when the file was written, probed, and every self-check met its target; a dry run
+ # verified nothing. Spec failures the tool cannot fix on its own (export's loudness gap)
+ # keep status completed and say verified: false, so a caller keys on one field.
+ steps: List[Dict[str, Any]] = ([{"step": "probe", "ok": True}] if meta else []) + list(extra.pop("verification", None) or [])
+ if output and not ctx.dry_run and os.path.splitext(output)[1].lower() not in MEDIA_EXT:
+ steps.insert(0, {"step": "exists", "ok": True})
+ doc["verified"] = not ctx.dry_run and bool(steps) and all(s.get("ok") for s in steps)
+ doc["verification"] = steps
+ doc.update(extra)
+ if os.environ.get("FFMPEG_SKILL_RESULT_V2", "") not in ("", "0"):
+ doc["result_v2"] = _result_v2(output, meta, dict(extra, verified=doc["verified"], verification=steps))
+ if ctx.plan:
+ doc["plan"] = write_plan(ctx.plan, output, extra, ctx=ctx)
+ print_json(_brief(doc, meta) if ctx.json_brief else doc)
+ elif ctx.plan:
+ print(write_plan(ctx.plan, output, extra, ctx=ctx))
+ elif output:
+ print(output)
+
+
+# Keys the brief document replaces or drops: the full probe (summarised), the command lines
+# (counted), the per-step verification list (its verdict stays as `verified`) and the 2.0 preview.
+_BRIEF_DROP = ("probe", "commands", "verification", "result_v2")
+
+
+def _brief_summary(meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
+ """The handful of output facts a caller reports or branches on, from the probe this tool
+ already ran -- plus the measured loudness when the tool measured one. Keys whose value is
+ unknown are left out rather than emitted as null."""
+ video = (meta or {}).get("video") or {}
+ audio = (meta or {}).get("audio") or {}
+ summary: Dict[str, Any] = {}
+ duration = (meta or {}).get("duration")
+ if duration is not None:
+ summary["duration_s"] = round(float(duration), 3)
+ for key, value in (("width", video.get("width")), ("height", video.get("height")), ("fps", video.get("fps")),
+ ("vcodec", video.get("codec")), ("acodec", audio.get("codec")), ("channels", audio.get("channels"))):
+ if value is not None:
+ summary[key] = value
+ lufs = None
+ for source, key in ((extra.get("result"), "input_i"), (extra.get("measured"), "input_i")):
+ if lufs is None and isinstance(source, dict):
+ lufs = _to_float(source.get(key))
+ for step in extra.get("verification") or []:
+ if lufs is None and isinstance(step, dict):
+ lufs = _to_float(step.get("lufs"))
+ # a silent file measures -inf, which json.dumps writes as the non-standard -Infinity: the
+ # brief document stays valid JSON by leaving the key out instead (the full document's own
+ # `measured`/`result` still carries whatever the tool reported).
+ if lufs is not None and math.isfinite(lufs):
+ summary["lufs"] = round(lufs, 2)
+ return summary
+
+
+def _brief(doc: Dict[str, Any], meta: Dict[str, Any]) -> Dict[str, Any]:
+ """--json-brief: the same success document with the bulky parts replaced by what a caller
+ acts on. Same keys, same meanings -- `commands` becomes the count of the command lines,
+ `probe` becomes `summary` -- plus every tool-specific key the tool itself passed to emit().
+ Failures are untouched: die() prints the full failure document either way."""
+ brief: Dict[str, Any] = {"status": doc["status"], "output": doc["output"], "dry_run": doc["dry_run"],
+ "verified": doc.get("verified", False)}
+ summary = _brief_summary(meta, doc)
+ if summary:
+ brief["summary"] = summary
+ brief["commands"] = len(doc.get("commands") or [])
+ for key, value in doc.items():
+ if key not in brief and key not in _BRIEF_DROP:
+ brief[key] = value
+ # the emoji report is a full inventory in the long document; brief keeps the two fields a
+ # caller branches on (did colour happen, and how many)
+ if isinstance(brief.get("emoji"), dict):
+ brief["emoji"] = {k: v for k, v in brief["emoji"].items() if k in ("mode", "count")}
+ return brief
+
+
+PLAN_VERSION = 1
+
+
+_PLAN_STRIP = ("--plan", "--dry-run", "--json")
+
+
+def _plan_at_exit() -> None:
+ ctx = _CURRENT_CTX or STATE
+ if ctx.plan and not ctx.plan_written:
+ try:
+ write_plan(ctx.plan, None, {}, ctx=ctx)
+ except SystemExit:
+ pass
+
+
+def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = (), ctx: "Optional[Context]" = None) -> List[str]:
+ """Every existing file the plan depends on: the `-i` inputs of the planned commands, any
+ existing file named in argv (a recipe, a project, an SRT, a LUT, a still), and the side
+ inputs tools register through escape_filter_path() (review 6: only `-i` files were bound)."""
+ import shlex
+ seen: List[str] = []
+ for a in list(argv) + list((ctx or STATE).plan_inputs):
+ if a and not a.startswith("-") and os.path.isfile(a) and a not in seen:
+ seen.append(a)
+ for line in commands:
+ try:
+ toks = shlex.split(line.split("] ", 1)[1] if line.startswith("[dry-run] ") else line)
+ except ValueError:
+ continue
+ for i, tok in enumerate(toks[:-1]):
+ if tok == "-i" and os.path.isfile(toks[i + 1]) and toks[i + 1] not in seen:
+ seen.append(toks[i + 1])
+ return seen
+
+
+def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Optional[Context]" = None) -> str:
+ """The dry run as an artifact: what will run, on which exact inputs, producing what, checked
+ how. `render.py PLAN` executes it after re-fingerprinting the inputs (issue #189 C).
+
+ `ctx` is the Context whose commands and inputs the plan describes (emit()/die() pass the one
+ they were given); omitted, it is the process-global STATE as before."""
+ import datetime
+ ctx = ctx or STATE
+ argv = [a for a in sys.argv[1:]]
+ cleaned: List[str] = []
+ skip = False
+ for a in argv:
+ if skip:
+ skip = False
+ continue
+ if a in _PLAN_STRIP:
+ skip = a == "--plan"
+ continue
+ if a.startswith("--plan="):
+ continue
+ cleaned.append(a)
+ tool = os.path.splitext(os.path.basename(sys.argv[0]))[0]
+ verify: List[Dict[str, Any]] = [{"tool": "probe"}] if output else []
+ platform = None
+ if "--platform" in cleaned:
+ platform = cleaned[cleaned.index("--platform") + 1]
+ elif tool == "export" and "--preset" in cleaned:
+ platform = {"youtube": "youtube", "youtube4k": "youtube", "reels": "reels", "x": "x"}.get(cleaned[cleaned.index("--preset") + 1])
+ if platform and output and tool != "check":
+ verify.append({"tool": "check", "platform": platform})
+ doc = {
+ "plan_version": PLAN_VERSION,
+ "created": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+ "tool": tool,
+ "argv": cleaned,
+ "cwd": os.getcwd(),
+ "inputs": [fingerprint(p) for p in _plan_inputs(ctx.commands, cleaned, ctx)],
+ "commands": list(ctx.commands),
+ "output": os.path.abspath(output) if output else None,
+ "verify": verify,
+ "notes": list(extra.get("notes") or []),
+ }
+ try:
+ tmp = f"{path}.tmp{os.getpid()}"
+ with open(tmp, "w", encoding="utf-8") as f:
+ json.dump(doc, f, indent=2, ensure_ascii=False)
+ f.write("\n")
+ os.replace(tmp, path)
+ except OSError as exc:
+ die(f"cannot write plan {path}: {exc}", kind="output")
+ ctx.plan_written = True
+ info(f"plan written: {path} ({len(doc['commands'])} command(s), {len(doc['inputs'])} input(s)); run it with render.py {path}", ctx)
+ return path
+
+
+_V2_HANDLED = ("result", "measured", "notes", "dropped_non_av_streams", "verified", "verification")
+
+
+def _result_v2(output: Optional[str], meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
+ """The 2.0 success-document shape, previewed in 1.x as a parallel `result_v2` key when
+ FFMPEG_SKILL_RESULT_V2=1 (issue #189 B). Every tool gets the same six slots: `output`,
+ `probe`, `commands`, `metrics` (numbers a caller keys on: loudness's `result`/`measured`
+ dicts flattened, plus every top-level numeric extra such as `expected_duration` or
+ `offset_seconds`), `notes` (free text), `dropped` (what did not make it into the output),
+ and `details` (the tool's remaining extras, unchanged). The 1.x keys stay where they are;
+ this key is additive and its shape is what 2.0 promotes to the top level."""
+ metrics: Dict[str, Any] = {}
+ for key in ("measured", "result"):
+ if isinstance(extra.get(key), dict):
+ metrics.update(extra[key])
+ for key, value in extra.items():
+ if key not in _V2_HANDLED and isinstance(value, (int, float)) and not isinstance(value, bool):
+ metrics[key] = value
+ notes = extra.get("notes")
+ return {
+ "schema": 2,
+ "output": output,
+ "probe": meta or None,
+ "commands": list(STATE.commands),
+ "metrics": metrics,
+ "notes": list(notes) if isinstance(notes, (list, tuple)) else ([notes] if notes else []),
+ "dropped": {"non_av_streams": bool(extra.get("dropped_non_av_streams", False))},
+ "verified": bool(extra.get("verified", False)),
+ "verification": list(extra.get("verification") or []),
+ "details": {k: v for k, v in extra.items() if k not in _V2_HANDLED and k not in metrics},
+ }
+
+
+def print_json(obj: Any) -> None:
+ sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
+
+
+# Deferred for the same reason as runner's import of this module: probe needs die() from here, and
+# emit() needs verify_output() from there, but only ever at call time.
+from _common.probe import MEDIA_EXT, _to_float, fingerprint, verify_output # noqa: E402
diff --git a/scripts/_common/probe.py b/scripts/_common/probe.py
new file mode 100644
index 0000000..54cc2a5
--- /dev/null
+++ b/scripts/_common/probe.py
@@ -0,0 +1,382 @@
+"""ffprobe and the measured facts read back off a file: the probe document every script starts
+from, the verification every script ends with, and the level/waveform measurements.
+
+Reading only -- the choices made from these facts live in decision.py.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+from fractions import Fraction
+from typing import Any, Dict, List, Optional, Sequence
+from _common.emit import die
+from _common.runner import STATE, require_tool, run, run_analysis
+
+
+def fingerprint(path: str) -> Dict[str, Any]:
+ """Size plus a sha256 over the first and last 8 MiB: enough to notice a re-export, a re-trim
+ or a swapped file, cheap enough for a multi-GB source (hashing a whole master would make
+ planning slower than the edit)."""
+ import hashlib
+ st = os.stat(path)
+ h = hashlib.sha256()
+ chunk = 8 * 1024 * 1024
+ with open(path, "rb") as f:
+ h.update(f.read(chunk))
+ if st.st_size > 2 * chunk:
+ f.seek(-chunk, os.SEEK_END)
+ h.update(f.read(chunk))
+ elif st.st_size > chunk:
+ h.update(f.read())
+ return {"path": os.path.abspath(path), "size": st.st_size, "sha256_head_tail": h.hexdigest()}
+
+
+def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None, start: float = 0.0,
+ *, check: bool = True) -> List[float]:
+ """Decode (part of) a file's audio to mono float samples in [-1, 1) at `sample_rate` via a
+ single ffmpeg pass under --timeout. Shared by scenes.py (audio envelope for cut scoring) and
+ sync.py (cross-correlation); an undecodable input is kind ffmpeg when check=True, else []."""
+ ffmpeg = require_tool("ffmpeg")
+ cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin"]
+ if start:
+ cmd += ["-ss", f"{start:.3f}"]
+ cmd += ["-i", path]
+ if seconds is not None:
+ cmd += ["-t", f"{seconds:.3f}"]
+ cmd += ["-vn", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
+ proc = run_analysis(cmd, check=False, text=False)
+ if proc.returncode != 0 or not proc.stdout:
+ if check:
+ die(f"could not decode audio from {path}:\n{proc.stderr.decode(errors='replace').strip()}", kind="ffmpeg")
+ return []
+ n = len(proc.stdout) // 2
+ import struct
+ return [v / 32768.0 for v in struct.unpack(f"<{n}h", proc.stdout[: n * 2])]
+
+
+def rms_envelope(samples: Sequence[float], step: int, *, full_blocks_only: bool = False, remove_mean: bool = False) -> List[float]:
+ """RMS per block of `step` samples. full_blocks_only drops a short tail block (sync.py: every
+ block must be the same length for the correlation); remove_mean subtracts the envelope's mean
+ (sync.py: so silence does not correlate). scenes.py keeps the tail and the absolute level."""
+ step = max(1, int(step))
+ n = len(samples)
+ stop = n - step + 1 if full_blocks_only else n
+ env: List[float] = []
+ for i in range(0, max(0, stop), step):
+ block = samples[i:i + step]
+ env.append(math.sqrt(sum(x * x for x in block) / len(block)))
+ if remove_mean and env:
+ mean = sum(env) / len(env)
+ env = [e - mean for e in env]
+ return env
+
+
+MEDIA_EXT = {".mp4", ".mov", ".mkv", ".webm", ".m4v", ".avi", ".ts", ".mts", ".m2ts", ".mxf", ".3gp", ".wmv", ".gif",
+ ".wav", ".flac", ".mp3", ".m4a", ".aac", ".ogg", ".opus", ".aif", ".aiff", ".caf", ".wma", ".png", ".jpg", ".jpeg", ".webp"}
+
+
+def _output_failed(path: str, why: str) -> "None":
+ """An ffmpeg run reported success but the artifact is not usable: say so, and do not leave a
+ 0-byte file behind that a later step could mistake for a result."""
+ try:
+ if os.path.exists(path) and os.path.getsize(path) == 0:
+ os.remove(path)
+ why += " (empty file removed)"
+ except OSError:
+ pass
+ die(f"output verification failed: {path}: {why}", kind="output")
+
+
+def verify_output(path: str) -> Dict[str, Any]:
+ """The success criterion for every writing tool: the file exists, is not empty and ffprobe
+ can read at least one stream from it. Non-media artifacts (srt, edl, html, md) only need to
+ exist and be non-empty. Returns the probe (empty dict for non-media)."""
+ if not os.path.exists(path):
+ _output_failed(path, "not written")
+ if os.path.getsize(path) == 0:
+ _output_failed(path, "0 bytes")
+ if os.path.splitext(path)[1].lower() not in MEDIA_EXT:
+ return {}
+ meta = probe(path, role="output")
+ if not meta.get("video") and not meta.get("audio"):
+ _output_failed(path, "no video or audio stream")
+ return meta
+
+
+def probe(path: str, role: str = "input") -> Dict[str, Any]:
+ """Return a compact, script-friendly description of a media file.
+
+ role="output" marks a file this tool just wrote: a read failure is then reported as an
+ output-verification failure (kind "output") instead of an input problem."""
+ if not os.path.exists(path):
+ if role == "output" and not STATE.dry_run:
+ _output_failed(path, "not written")
+ if STATE.dry_run:
+ # width/height/fps are honestly 0/0/0.0 -- "not measured", matching duration/size_bytes
+ # below -- because this is a dry run: the file doesn't exist yet, so there is nothing to
+ # probe. Earlier this stub used plausible-looking placeholders (1920x1080x30.0) instead,
+ # which some tools' dry-run summary line echoed verbatim as if it were a real computed
+ # preview (#77). That was reverted once, because a couple of call sites divided by these
+ # values for aspect-ratio math and crashed on a real 0 (join.py, fit.py); those call
+ # sites are now guarded to treat 0 as "unknown" and fall back sanely instead of dividing
+ # by it, so the stub can finally report the honest, unknown value.
+ return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,
+ "video": {"codec": None, "width": 0, "height": 0, "fps": 0.0, "pix_fmt": None, "hdr": False,
+ "color_transfer": None, "color_primaries": None, "rotation": 0, "variable_frame_rate_suspected": False},
+ "audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0, "data_streams": 0}
+ die(f"input not found: {path}")
+ ffprobe = require_tool("ffprobe")
+ proc = run(
+ [ffprobe, "-v", "error", "-print_format", "json", "-show_format", "-show_streams", "-show_chapters", path],
+ quiet=True,
+ check=False,
+ )
+ if proc.returncode != 0:
+ if role == "output":
+ _output_failed(path, f"ffprobe cannot read it:\n{proc.stderr.strip()}")
+ die(f"ffprobe failed on {path}:\n{proc.stderr.strip()}")
+ try:
+ raw = json.loads(proc.stdout or "{}")
+ except ValueError as e:
+ if role == "output":
+ _output_failed(path, f"ffprobe printed unreadable JSON: {e}")
+ die(f"ffprobe printed unreadable JSON for {path}: {e}", kind="ffmpeg")
+ 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"]
+ data_stream_count = sum(1 for s in streams if s.get("codec_type") in ("data", "attachment"))
+
+ 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"))
+ if duration and STATE.duration_hint is None:
+ STATE.duration_hint = 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),
+ "data_streams": data_stream_count,
+ # container-level chapter markers and the common tags, so metadata.py's result is
+ # verifiable the same way every other tool's is (additive keys, 1.x-safe)
+ "chapters": [{
+ "index": n,
+ "start": _to_float(ch.get("start_time")),
+ "end": _to_float(ch.get("end_time")),
+ "title": (ch.get("tags") or {}).get("title"),
+ } for n, ch in enumerate(raw.get("chapters") or [])],
+ "tags": {k.lower(): v for k, v in (fmt.get("tags") or {}).items() if k.lower() in ("title", "artist", "album", "comment", "date", "genre")},
+ # every subtitle stream in file order: index n here is `-map 0:s:n`
+ "subtitle_stream_details": [{
+ "index": n,
+ "codec": s.get("codec_name"),
+ "language": (s.get("tags") or {}).get("language"),
+ "title": (s.get("tags") or {}).get("title"),
+ } for n, s in enumerate(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
+ pix = video.get("pix_fmt") or ""
+ trc = video.get("color_transfer") or ""
+ prim = video.get("color_primaries") or ""
+ hdr = trc in ("smpte2084", "arib-std-b67") or prim == "bt2020"
+ dovi = None
+ for sd in video.get("side_data_list", []) or []:
+ if "dv_profile" in sd or "DOVI" in str(sd.get("side_data_type", "")):
+ dovi = {"profile": sd.get("dv_profile"), "level": sd.get("dv_level"), "bl_compatibility_id": sd.get("dv_bl_signal_compatibility_id")}
+ if dovi: # a Dolby Vision stream is HDR even when its base layer tags are missing
+ hdr = True
+ 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"),
+ "bit_depth": _bit_depth(pix),
+ "hdr": hdr,
+ # 1.9 (2.0 A1 pre-shipped as a parallel key): true only for a PQ / HLG transfer or Dolby
+ # Vision, i.e. a genuinely HDR signal. `hdr` also counts BT.2020 primaries on an SDR
+ # transfer ("BT.2020 SDR" in hdr_format) and keeps that meaning until 2.0 renames it.
+ "hdr_signal": trc in ("smpte2084", "arib-std-b67") or bool(dovi),
+ "hdr_format": (("Dolby Vision %s" % (("profile %s" % dovi["profile"]) if dovi and dovi.get("profile") is not None else "")).strip() if dovi else
+ "HDR10/PQ" if trc == "smpte2084" else "HLG" if trc == "arib-std-b67" else "BT.2020 SDR" if hdr else None),
+ "dolby_vision": dovi,
+ "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")),
+ }
+ # every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)
+ out["audio_streams"] = [{
+ "index": n,
+ "codec": a.get("codec_name"),
+ "channels": _to_int(a.get("channels")),
+ "channel_layout": a.get("channel_layout"),
+ "sample_rate": _to_int(a.get("sample_rate")),
+ "language": (a.get("tags") or {}).get("language"),
+ "title": (a.get("tags") or {}).get("title"),
+ } for n, a in enumerate(s for s in streams if s.get("codec_type") == "audio")]
+ return out
+
+
+def _bit_depth(pix_fmt: Optional[str]) -> int:
+ """Bits per component from a pixel format name. `"10" in pix` used to read yuv410p (4:1:0
+ chroma) as 10-bit; the depth is the number that ends the name (before an le/be suffix):
+ yuv420p10le -> 10, gbrp12be -> 12, gray16le -> 16, yuv410p / yuv420p / rgb24 -> 8."""
+ m = re.search(r"(\d{1,2})(?:le|be)?$", pix_fmt or "")
+ if not m:
+ return 8
+ n = int(m.group(1))
+ if n in (24, 32): # packed 8-bit rgb24/bgr32/rgb0 etc.
+ return 8
+ if n in (48, 64): # packed 16-bit rgb48/rgba64
+ return 16
+ return n if 8 <= n <= 16 else 8
+
+
+def keyframes_near(path: str, t: float, window: float = 5.0) -> List[float]:
+ """Video keyframe timestamps within +-window seconds of t, ascending. Read with
+ -read_intervals so a long file is not scanned end to end; empty when ffprobe cannot say."""
+ ffprobe = require_tool("ffprobe")
+ lo = max(0.0, t - window)
+ proc = run([ffprobe, "-v", "error", "-select_streams", "v:0", "-skip_frame", "nokey",
+ "-read_intervals", f"{lo:.3f}%{t + window:.3f}", "-show_entries", "frame=pts_time",
+ "-of", "csv=p=0", path], quiet=True, check=False)
+ if proc.returncode != 0:
+ return []
+ out: List[float] = []
+ for line in proc.stdout.splitlines():
+ try:
+ out.append(round(float(line.strip().rstrip(",")), 3))
+ except ValueError:
+ continue
+ return sorted(set(out))
+
+
+def measured_level_dbfs(path: str, seconds: float = 120.0) -> Optional[Dict[str, float]]:
+ """Mean and peak level of the first `seconds` of audio (volumedetect), in dBFS; None if unmeasurable.
+ Cheap enough to run once as a hint when a threshold-based tool found nothing."""
+ ffmpeg = require_tool("ffmpeg")
+ proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.0f}", "-i", path, "-vn",
+ "-af", "volumedetect", "-f", "null", "-"], check=False)
+ m_mean = re.search(r"mean_volume:\s*(-?[0-9.]+) dB", proc.stderr)
+ m_max = re.search(r"max_volume:\s*(-?[0-9.]+) dB", proc.stderr)
+ if not (m_mean and m_max):
+ return None
+ return {"mean_dbfs": float(m_mean.group(1)), "peak_dbfs": float(m_max.group(1))}
+
+
+def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
+ """Sample luma/saturation statistics (signalstats) and guess whether the picture is Log-encoded.
+
+ Log gammas (S-Log3, V-Log, C-Log, HLG-looking flat profiles) put black around 90-95/255 and
+ white below ~235 with low saturation: the image looks grey and flat but is tagged as plain SDR.
+ """
+ ffmpeg = require_tool("ffmpeg")
+ cmd = [ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.1f}", "-i", path, "-an",
+ "-vf", "fps=2,signalstats,metadata=print:file=-", "-f", "null", "-"]
+ proc = run_analysis(cmd, check=False)
+ vals: Dict[str, List[float]] = {}
+ for line in proc.stdout.splitlines():
+ if "lavfi.signalstats." in line and "=" in line:
+ key, val = line.split("lavfi.signalstats.", 1)[1].split("=", 1)
+ try:
+ vals.setdefault(key, []).append(float(val))
+ except ValueError:
+ pass
+ if not vals.get("YAVG"):
+ return {"error": "no frames analysed"}
+ def mean(k: str) -> float:
+ v = vals.get(k) or [0.0]
+ return sum(v) / len(v)
+ ymin, ymax, yavg, sat = min(vals.get("YMIN") or [0]), max(vals.get("YMAX") or [255]), mean("YAVG"), mean("SATAVG")
+ # signalstats reports in the source bit depth; normalise everything to an 8-bit scale
+ scale = 1.0
+ if ymax > 255 or yavg > 255:
+ scale = 1 / 4.0 if ymax <= 1023 else (1 / 16.0 if ymax <= 4095 else 1 / 256.0) # 10 / 12 / 16-bit
+ ymin, ymax, yavg, sat = ymin * scale, ymax * scale, yavg * scale, sat * scale
+ # 5th/95th percentile of per-frame lows/highs is more robust than the absolute min/max
+ lows = sorted(x * scale for x in (vals.get("YLOW") or vals.get("YMIN") or [0]))
+ highs = sorted(x * scale for x in (vals.get("YHIGH") or vals.get("YMAX") or [255]))
+ p_low = lows[len(lows) // 20]
+ p_high = highs[-1 - len(highs) // 20]
+ looks_log = p_low >= 64 and p_high <= 235 and sat < 40
+ return {
+ "scale": "8-bit equivalent",
+ "y_min": round(ymin, 1), "y_max": round(ymax, 1), "y_avg": round(yavg, 1), "y_low_p5": round(p_low, 1), "y_high_p95": round(p_high, 1),
+ "saturation_avg": round(sat, 1),
+ "looks_like_log": looks_log,
+ "note": ("flat, low-contrast, desaturated picture tagged as SDR: probably a Log profile (S-Log/V-Log/C-Log). "
+ "Apply the camera's conversion LUT with color.py --lut" if looks_log else "contrast and saturation look like normal display-referred SDR"),
+ }
+
+
+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}"
diff --git a/scripts/_common/runner.py b/scripts/_common/runner.py
new file mode 100644
index 0000000..bf38bbc
--- /dev/null
+++ b/scripts/_common/runner.py
@@ -0,0 +1,1056 @@
+"""Process execution for ffmpeg-skill: locating the tools, running them under a wall-clock
+ceiling, signal handling, output locking and staging, and the drawtext text-file spool.
+
+Nothing here decides *what* to encode -- that is decision.py -- and nothing here formats a result
+document -- that is emit.py. Imported through the `_common` facade by every script.
+"""
+from __future__ import annotations
+
+import json
+import os
+import platform
+import argparse
+import re
+import shutil
+import subprocess
+import sys
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+
+INSTALL_HINTS = {
+ "Darwin": " brew install ffmpeg-full (the plain ffmpeg formula lacks subtitles/drawtext/zscale)",
+ "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"
+ ),
+}
+
+
+# `kind` (below) is the machine-readable failure axis: input / missing_tool / ffmpeg / output
+# since 0.1, plus timeout (1.3), verification (1.4.3) and interrupted (1.4.10). `ERROR_CODE` is an
+# additive, purely informational refinement layered on top for agents that want a stable enum to
+# switch on instead of pattern-matching `kind` strings -- a static 1:1 relabelling of the same
+# buckets, not a new taxonomy. It intentionally does NOT introduce categories this codebase cannot actually
+# distinguish today (e.g. a separate ffprobe-vs-ffmpeg code, or an environment-vs-content-cause
+# split of ffmpeg failures): every ffmpeg subprocess failure is currently one undifferentiated
+# bucket regardless of whether ffmpeg rejected a bad filter argument or died from a full disk,
+# and every "kind": "input" failure covers both a missing file and a bad flag value alike. Adding
+# codes for distinctions the code can't actually make would be guessing, not reporting -- if a
+# future call site can genuinely tell capability-missing apart from bad-argument (see doctor()'s
+# available/missing/unknown states, which already model this for detection but aren't wired into
+# any die() call), split ERROR_CODE then, with evidence, not speculatively now.
+ERROR_CODE = {
+ "input": "INPUT_INVALID",
+ "missing_tool": "DEPENDENCY_MISSING",
+ "ffmpeg": "FFMPEG_EXECUTION_FAILED",
+ "output": "OUTPUT_INVALID",
+ "timeout": "TIMEOUT",
+ "verification": "VERIFICATION_FAILED",
+ "interrupted": "INTERRUPTED",
+}
+
+
+# Wall-clock ceiling for one ffmpeg/ffprobe invocation, in seconds. A hung ffmpeg (a build
+# that deadlocks on a filter combination, a stalled network mount, an input that never ends)
+# used to hang the calling agent with it, with no error document and no way out short of
+# killing the process by hand. The ceiling is generous on purpose: it exists to turn a hang
+# into a reported failure, not to police slow encodes. --timeout and FFMPEG_SKILL_TIMEOUT
+# override it; 0 disables it.
+DEFAULT_TIMEOUT = 1800.0
+
+
+PROBE_TIMEOUT = 120.0
+
+
+def _env_timeout() -> float:
+ try:
+ return max(0.0, float(os.environ.get("FFMPEG_SKILL_TIMEOUT", DEFAULT_TIMEOUT)))
+ except ValueError:
+ return DEFAULT_TIMEOUT
+
+
+# None of the four kinds above are retryable in practice: an "input"/"missing_tool" failure is
+# always deterministic (the same bad path or absent binary fails identically every time), and a
+# "ffmpeg"/"output" failure -- while it COULD in principle be caused by a transient environment
+# condition (full disk, OOM) rather than a bad command -- is never distinguishable from a
+# deterministic content-cause failure without exit-code/stderr sniffing this codebase does not do.
+# Reporting retryable=True for a code we can't actually back up would invite an agent into a blind
+# retry loop against a command that will fail the same way every time; false-for-everything is the
+# honest answer until real sniffing exists to justify anything else.
+ERROR_RETRYABLE = False
+
+
+_FFMPEG_VERSION: "Optional[Tuple[int, int]]" = None
+
+
+def ffmpeg_version() -> "Tuple[int, int]":
+ """(major, minor) of the FFmpeg build on PATH, parsed once from `ffprobe -version`; (0, 0)
+ when it cannot be read. ffprobe rather than ffmpeg because --dry-run promises never to run
+ ffmpeg (docs/contract.md: ffmpeg_execution "none") while ffprobe always may, and the two
+ ship from the same build. Used only to pick between two spellings of an option where FFmpeg
+ changed behaviour between releases (the tools otherwise never branch on the version: doctor's
+ capability listing is the source of truth for what a build can do)."""
+ global _FFMPEG_VERSION
+ if _FFMPEG_VERSION is None:
+ _FFMPEG_VERSION = (0, 0)
+ try:
+ out = subprocess.run(["ffprobe", "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
+ timeout=PROBE_TIMEOUT).stdout
+ m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)", out)
+ if m:
+ _FFMPEG_VERSION = (int(m.group(1)), int(m.group(2)))
+ else:
+ # git / vendor builds print "N-115000-g..." or a date, never major.minor; the
+ # libavutil major is still there and maps one-to-one onto the FFmpeg major
+ # (56=4, 57=5, 58=6, 59=7, 60=8). Without this every version branch took the
+ # oldest spelling on such builds: on 7.1 that skipped bt709_tag_args()'s
+ # workaround and an untagged source got a real matrix conversion.
+ m = re.search(r"^libavutil\s+(\d+)\.", out, re.M)
+ if m:
+ major = int(m.group(1)) - 52
+ if major >= 4:
+ _FFMPEG_VERSION = (major, 0)
+ except (OSError, subprocess.TimeoutExpired):
+ # (0, 0) = unknown: every version branch then takes the older, universally accepted
+ # spelling, the same "unknown is not missing" stance doctor takes.
+ pass
+ return _FFMPEG_VERSION
+
+
+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, kind="missing_tool",
+ )
+ return "" # unreachable
+
+
+X264_PRESETS = ("ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow", "placebo")
+
+
+CODECS = ("h264", "hevc", "av1", "prores")
+
+
+_ENCODERS: Optional[set] = None
+
+
+class Context:
+ """Per-process settings that the shared flags (--dry-run, --json, --progress, --fast) set once.
+
+ Scripts read it as attributes (``STATE.dry_run``); the dict-style shims that once served
+ older call sites are gone. Keeping it a single explicit object rather than module globals
+ makes it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
+ """
+
+ __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec")
+
+ def __init__(self) -> None:
+ self.reset()
+
+ def reset(self) -> None:
+ self.dry_run = False # print ffmpeg commands, run nothing (ffprobe still runs)
+ self.json = False # emit() prints a JSON document instead of the output path
+ self.json_brief = False # --json-brief: the same document trimmed to the fields a caller acts on
+ self.progress = False # run() streams percent / ETA to stderr for ffmpeg
+ self.fast = False # x264 preset forced to veryfast
+ self.duration_hint: Optional[float] = None # expected output length, for the progress percent
+ self.commands: List[str] = [] # every ffmpeg command line, for --json and --dry-run
+ self.timeout: float = _env_timeout() # seconds per ffmpeg invocation, 0 = none
+ self.overwrite = False # --overwrite: an existing output may be replaced
+ self.written: set = set() # output paths this process has written itself
+ self.preexisting: dict = {} # output path -> (size, mtime_ns) of a file that was there before we ran
+ self.plan: Optional[str] = None # --plan FILE: write the dry-run as a plan document (implies --dry-run)
+ self.plan_written = False # write_plan() ran (emit or the exit hook), so the hook does not write twice
+ self.plan_inputs: List[str] = [] # side inputs (srt/ass/lut/font files) a tool named through escape_filter_path
+ self.codec: Optional[str] = None # --codec: encoder for the re-encode (None = x264 for SDR, x265 for HDR)
+
+
+STATE = Context()
+
+
+def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
+ """Add the flags every script shares. `codec=False` is for a tool that re-encodes but whose
+ preset decides the encoder (export.py): it must not advertise --codec/--quality in its schema."""
+ g = ap.add_argument_group("agent options")
+ g.add_argument("--dry-run", action="store_true", help="print the ffmpeg commands that would run, run nothing")
+ g.add_argument("--json", action="store_true", help="print a JSON result (output, probe, commands) on stdout instead of the path")
+ g.add_argument("--json-brief", action="store_true",
+ help="like --json but trimmed: status, output, dry_run, verified, a compact summary of the output probe, this tool's own keys, and the command count instead of the command lines (failures print the full failure document, unchanged)")
+ g.add_argument("--progress", action="store_true", help="show percent / ETA on stderr while ffmpeg encodes")
+ g.add_argument("--fast", action="store_true", help="preview quality: x264 preset veryfast (overrides --preset) for quick iterations")
+ if "--timeout" not in ap._option_string_actions: # verify.py defines its own per-step --timeout; apply_common reads either
+ g.add_argument("--timeout", type=float, default=None, metavar="SECONDS",
+ help=f"kill an ffmpeg run past this many seconds, kind=timeout (default {DEFAULT_TIMEOUT:.0f}; 0 = no limit)")
+ g.add_argument("--overwrite", action="store_true",
+ help="allow replacing an existing output (warned today, refused from 2.0)")
+ g.add_argument("--plan", metavar="FILE",
+ help="write the dry run as a plan (inputs fingerprinted, commands, expected output, verify steps) that render.py FILE executes later; implies --dry-run")
+ if codec and "--crf" in ap._option_string_actions:
+ # --crf became an alias of --quality in 1.8; 1.10 deprecates it (removed in 2.0, see the
+ # `deprecated` list in `contract --json` and docs/contract.md "What 2.0 changes"). Marked
+ # here, once, rather than in each re-encoding tool's own parser.
+ crf = ap._option_string_actions["--crf"]
+ # The flag's own default moves aside so apply_common() can tell an explicit --crf (in any
+ # spelling argparse accepts, including the --cr / --c abbreviations) from the default;
+ # apply_common() puts _CRF_DEFAULT back when the flag was absent.
+ global _CRF_DEFAULT
+ _CRF_DEFAULT = crf.default
+ crf.deprecated_default = crf.default # the schema still advertises it (_contract._json_type)
+ crf.default = None
+ if "deprecated" not in (crf.help or ""):
+ # the nine tools that declare --crf with no help string used to fall through this and
+ # never show the mark at all (review 9)
+ crf.help = (crf.help or "x264 CRF when re-encoding (default 18)") + " (deprecated: use --quality)"
+ # only the tools that re-encode (they declare --crf before add_common): one encoder choice
+ # resolved in video_args(), the 2.0 encoder abstraction pre-shipped in 1.8 (docs/roadmap.md)
+ g.add_argument("--codec", choices=CODECS, default=None,
+ help="video encoder for the re-encode: h264 (x264, the default for SDR), hevc (x265, the default for HDR), av1 (SVT-AV1 or libaom), prores (422 HQ, needs a .mov/.mkv output); HDR sources keep their colour on hevc/av1/prores")
+ g.add_argument("--quality", type=int, default=None, metavar="N",
+ help="encoder quality on the CRF scale (lower = better; 18 visually lossless for x264/x265, up to 63 for av1); overrides --crf, ignored by prores")
+
+
+# The declared default of a deprecated --crf, parked by add_common() (one parser per process).
+_CRF_DEFAULT: Optional[int] = None
+
+
+def apply_common(args: "argparse.Namespace") -> None:
+ # Was --crf typed? add_common() parked the flag's default (None in its place) on every tool
+ # whose --crf is deprecated, i.e. the ones that also have --quality; export.py's --crf is not
+ # an alias and keeps its own default. Scanning sys.argv for "--crf" instead missed the unique
+ # prefixes argparse accepts (--cr, --c) and never ran for batch.py's recipe steps (review 9).
+ crf_explicit = hasattr(args, "quality") and getattr(args, "crf", None) is not None
+ if hasattr(args, "quality") and hasattr(args, "crf") and args.crf is None:
+ args.crf = _CRF_DEFAULT
+ STATE.plan = getattr(args, "plan", None) or None
+ STATE.dry_run = bool(getattr(args, "dry_run", False)) or bool(STATE.plan)
+ if STATE.plan:
+ # tools that print their document instead of calling emit() (probe, and the analysis
+ # tools without --json) still get their plan written, at exit, unless die() ran (review 6)
+ import atexit
+ atexit.register(_plan_at_exit)
+ STATE.json_brief = bool(getattr(args, "json_brief", False))
+ # --json-brief is a shorter --json, not a second output mode: it implies it, so a caller that
+ # passes only --json-brief still gets a JSON document (and --json --json-brief is the brief one).
+ STATE.json = bool(getattr(args, "json", False)) or STATE.json_brief
+ STATE.progress = bool(getattr(args, "progress", False))
+ STATE.fast = bool(getattr(args, "fast", False))
+ STATE.overwrite = bool(getattr(args, "overwrite", False))
+ if getattr(args, "timeout", None) is not None:
+ STATE.timeout = max(0.0, float(args.timeout))
+ if STATE.fast and getattr(args, "preset", None) in X264_PRESETS:
+ args.preset = "veryfast"
+ STATE.codec = getattr(args, "codec", None) or None
+ quality = getattr(args, "quality", None)
+ if quality is not None:
+ top = 63 if STATE.codec == "av1" else 51
+ if not 0 <= int(quality) <= top:
+ die(f"--quality must be between 0 and {top} for {STATE.codec or 'h264'} (CRF scale; 18 is visually lossless), got {quality}")
+ args.crf = int(quality) # every tool reads args.crf; --quality is the codec-neutral spelling of it
+ if STATE.codec == "prores" and hasattr(args, "output"):
+ out = getattr(args, "output", None)
+ if not out:
+ # every tool defaults its output to the source's extension (or .mp4): ProRes in an .mp4
+ # fails inside ffmpeg with "codec not currently supported in container" (review 7)
+ die("--codec prores needs an explicit -o NAME.mov (or .mkv): the default output name keeps the source's container, which cannot hold ProRes",
+ hint="give -o NAME.mov")
+ if os.path.splitext(str(out))[1].lower() not in (".mov", ".mkv"):
+ die(f"--codec prores needs a .mov (or .mkv) output; {os.path.basename(str(out))} cannot hold ProRes",
+ hint="give -o NAME.mov")
+ crf = getattr(args, "crf", None)
+ # The warning the deprecation policy asks for, only when the caller typed the flag (see
+ # crf_explicit above). export.py has no --quality (its preset chooses the encoder), so its
+ # --crf is not an alias and is not deprecated: warn only where --quality exists.
+ if crf is not None and crf_explicit:
+ info("warning: --crf is deprecated since 1.10.0; use --quality N (the same CRF scale, codec-neutral). --crf is removed in 2.0.")
+ top = 63 if STATE.codec == "av1" else 51
+ if crf is not None and not 0 <= int(crf) <= top:
+ die(f"--crf must be between 0 and {top} ({'SVT-AV1' if STATE.codec == 'av1' else 'x264/x265'} scale; 18 is visually lossless), got {crf}")
+ install_signal_handlers()
+
+
+# The child processes this tool is waiting on right now (an ffmpeg, or a sibling script under
+# run_tool), with the command whose partial output would need removing. A signal handler
+# reads it; the runners keep it current. Before 1.4.9 a SIGTERM to the tool (a cancelled MCP
+# call, a supervisor's stop, a closed terminal) killed only the Python parent: ffmpeg carried on
+# as an orphan, finished a file nobody verified, and the caller got no JSON at all; SIGINT was a
+# KeyboardInterrupt traceback with the partial left on disk.
+_CHILDREN: List[Tuple[subprocess.Popen, Sequence[str]]] = []
+
+
+_SIGNALS_INSTALLED = False
+
+
+def _on_signal(signum: int, frame: Any) -> None:
+ import signal as _signal
+ name = {getattr(_signal, "SIGINT", None): "SIGINT", getattr(_signal, "SIGTERM", None): "SIGTERM"}.get(signum, str(signum))
+ for proc, cmd in list(_CHILDREN):
+ try:
+ proc.terminate() # ffmpeg exits promptly on SIGTERM; a sibling script runs this same handler
+ try:
+ proc.wait(timeout=5)
+ except subprocess.TimeoutExpired:
+ proc.kill()
+ proc.wait()
+ except OSError:
+ pass
+ if cmd:
+ _cleanup_partial_output(cmd)
+ _CHILDREN.clear()
+ die(f"interrupted by {name}: the running command was stopped and its partial output removed; nothing was written",
+ code=128 + signum, kind="interrupted")
+
+
+def install_signal_handlers() -> None:
+ """SIGINT/SIGTERM stop the child, remove its partial output and exit with a failure document
+ (kind: interrupted, exit 130/143). Main thread only; on Windows SIGTERM is never delivered,
+ SIGINT (Ctrl-C) is."""
+ global _SIGNALS_INSTALLED
+ if _SIGNALS_INSTALLED:
+ return
+ import signal as _signal
+ import threading
+ if threading.current_thread() is not threading.main_thread():
+ return
+ for sig in (getattr(_signal, "SIGINT", None), getattr(_signal, "SIGTERM", None)):
+ if sig is None:
+ continue
+ try:
+ _signal.signal(sig, _on_signal)
+ except (ValueError, OSError):
+ pass
+ _SIGNALS_INSTALLED = True
+
+
+def _watch(proc: subprocess.Popen, cmd: Sequence[str]) -> None:
+ _CHILDREN.append((proc, cmd))
+
+
+def _unwatch(proc: subprocess.Popen) -> None:
+ _CHILDREN[:] = [(p, c) for p, c in _CHILDREN if p is not proc]
+
+
+def _cmdline(cmd: Sequence[str]) -> str:
+ return " ".join(shell_quote(c) for c in cmd)
+
+
+def _is_ffmpeg(cmd: Sequence[str]) -> bool:
+ return os.path.basename(cmd[0]).startswith("ffmpeg")
+
+
+def _cleanup_partial_output(cmd: Sequence[str]) -> None:
+ """A failed ffmpeg command can still have opened its output container (muxer header
+ written) before erroring out mid-stream -- unlike a failure that happens before ffmpeg ever
+ touches the output path (a bad filter argument, a missing input), which never creates the
+ file at all. Both are reported the same way (status: failed), but only the first case used
+ to leave a stray, usually-0-byte file behind: verify_output()'s cleanup only runs on the
+ success path, so a failed run() call never routed through it. Remove whatever ffmpeg managed
+ to write so a caller scanning the output directory after a failure never mistakes a partial
+ artifact for a real (if unverified) one."""
+ # run() also executes ffprobe, whose last argument is an INPUT. Never
+ # interpret a read-only tool's failure as permission to remove that file.
+ if not _is_ffmpeg(cmd):
+ return
+ output = cmd[-1]
+ if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):
+ return
+ try:
+ if not os.path.exists(output):
+ return
+ # A file that was already there before this command ran is someone's deliverable, not
+ # our partial. If ffmpeg died before opening it (bad filter argument, unreadable input:
+ # the common case) it is byte-for-byte what it was, so leave it alone. Only when ffmpeg
+ # did open and truncate it (size or mtime changed) is what remains a partial of ours,
+ # and the original is already gone either way; then removing it is still right.
+ before = STATE.preexisting.get(os.path.realpath(output))
+ if before is not None:
+ st = os.stat(output)
+ if (st.st_size, st.st_mtime_ns) == before:
+ return
+ os.remove(output)
+ except OSError:
+ pass
+
+
+def _fail(cmd: Sequence[str], returncode: int, stderr: str) -> None:
+ # Partial-output cleanup already ran in the caller (_run_captured/_run_with_progress) for
+ # every failed ffmpeg invocation, not just this check=True path -- see _cleanup_partial_output.
+ # The process exit code is always 1 for an ffmpeg failure: ffmpeg's own code (1, 69, 218, 234,
+ # a negative signal number...) varies by build and by the failing stage, and 124/127/130/143
+ # are reserved for timeout, missing tool and interrupts. The raw code is kept in the JSON
+ # document as `ffmpeg_returncode` for a caller that wants it. docs/design-decisions.md.
+ tail = "\n".join(stderr.strip().splitlines()[-15:])
+ die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=1, kind="ffmpeg", ffmpeg_returncode=returncode)
+
+
+def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
+ """Refuse an ffmpeg command whose output path resolves to the same file as one of its
+ inputs. ffmpeg's own "Output same as Input" guard only catches byte-identical path
+ strings; a relative/absolute pair, a leading "./", a redundant ".." segment, or a symlink
+ all resolve to the same file but pass that check, so "-o ./same.mp4" on an input opened as
+ "same.mp4" would otherwise silently let ffmpeg's -y clobber the source mid-encode. Every
+ write-side script routes through this one run() choke point rather than each computing its
+ own output path defensively, so the guard lives here once instead of at 25+ call sites."""
+ output = cmd[-1]
+ if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):
+ return
+ try:
+ out_real = os.path.realpath(output)
+ except OSError:
+ return
+ for i, a in enumerate(cmd):
+ if a == "-i" and i + 1 < len(cmd):
+ inp = cmd[i + 1]
+ try:
+ if os.path.realpath(inp) == out_real:
+ die(f"refusing to run: output {output!r} is the same file as input {inp!r} "
+ f"(would overwrite it while ffmpeg is still reading it) -- choose a different --output/-o path",
+ kind="input")
+ except OSError:
+ continue
+
+
+def refuse_output_is_input(output: str, *inputs: str) -> None:
+ """Tool-level twin of the run() guard, for tools whose final ffmpeg command does not name
+ the user's input at all. `cut.py --segments` cuts each part into a temp dir and then concats
+ a list file: the last command's only `-i` is that list, so `-o` equal to the input sailed
+ through _check_no_overwrite_input() and replaced the source with the join (fourth audit,
+ P0). Call it once the output path is known, before any part of the input is consumed."""
+ try:
+ out_real = os.path.realpath(output)
+ except OSError:
+ return
+ for inp in inputs:
+ try:
+ same = os.path.realpath(inp) == out_real
+ except OSError:
+ continue
+ if same:
+ die(f"refusing to run: output {output!r} is the same file as input {inp!r} "
+ f"(the result would replace the source) -- choose a different --output/-o path", kind="input")
+
+
+def _check_output_path(cmd: Sequence[str]) -> None:
+ """An output whose directory does not exist, or that names a directory, is a caller mistake:
+ say so as `kind: input` before ffmpeg runs, instead of the muxer's "No such file or directory"
+ as `kind: ffmpeg` (which reads as an encoder failure) or an `OUTPUT_INVALID` after the fact."""
+ output = cmd[-1]
+ if output == "-" or output.startswith("pipe:") or output.startswith("-"):
+ return
+ if os.path.isdir(output):
+ die(f"output {output!r} is a directory; pass a file path (e.g. {os.path.join(output, 'result.mp4')!r})")
+ parent = os.path.dirname(os.path.abspath(output))
+ if not os.path.isdir(parent):
+ die(f"output directory {parent!r} does not exist; create it first (this tool never creates directories)")
+ if not os.access(parent, os.W_OK):
+ die(f"output directory {parent!r} is not writable")
+
+
+EVEN_SCALE = "scale=trunc(iw/2)*2:trunc(ih/2)*2"
+
+
+def _pid_dead(pid: int) -> bool:
+ """True only when the process is known not to exist. POSIX: signal 0. Windows: OpenProcess
+ fails with ERROR_INVALID_PARAMETER (87) for a pid that is not in use; any other outcome
+ (a handle, or access denied) means it is live. Unknown is treated as live."""
+ if os.name != "nt":
+ try:
+ os.kill(pid, 0)
+ except ProcessLookupError:
+ return True
+ except OSError:
+ pass
+ return False
+ try:
+ import ctypes
+ k32 = ctypes.windll.kernel32 # type: ignore[attr-defined]
+ handle = k32.OpenProcess(0x1000, False, pid) # PROCESS_QUERY_LIMITED_INFORMATION
+ if handle:
+ k32.CloseHandle(handle)
+ return False
+ return k32.GetLastError() == 87
+ except Exception:
+ return False
+
+
+class _OutputLock:
+ """Two runs writing the same output at once used to both report `completed` while one of
+ them described the other's file (sweep F1). A lock file next to the output, created with
+ O_EXCL and holding the writer's pid, makes the second run refuse as `kind: input`. A lock
+ whose pid is dead (POSIX) or older than an hour is stale and taken over."""
+ def __init__(self, output: str) -> None:
+ self.path: Optional[str] = None
+ self.fd: Optional[int] = None
+ if output == "-" or output.startswith("pipe:") or output.startswith("-"):
+ return
+ d, base = os.path.split(os.path.abspath(output))
+ self.path = os.path.join(d, f".{base}.ffskill-lock")
+
+ def __enter__(self) -> "_OutputLock":
+ if not self.path:
+ return self
+ for attempt in (0, 1):
+ try:
+ self.fd = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+ os.write(self.fd, str(os.getpid()).encode())
+ return self
+ except FileExistsError:
+ if attempt == 0 and self._stale():
+ try:
+ os.remove(self.path)
+ except OSError:
+ pass
+ continue
+ die(f"another run is writing {os.path.basename(self.path)[1:-len('.ffskill-lock')]!r} right now "
+ f"(lock {self.path}); wait for it or choose a different --output/-o path")
+ except OSError:
+ return self # unlockable location (read-only dir surfaces elsewhere): proceed without a lock
+ return self
+
+ def _stale(self) -> bool:
+ try:
+ pid = int(open(self.path).read().strip() or "0")
+ if pid > 0 and _pid_dead(pid):
+ return True
+ import time
+ return time.time() - os.path.getmtime(self.path) > 3600
+ except (OSError, ValueError):
+ return True
+
+ def __exit__(self, *exc: Any) -> None:
+ if self.fd is not None:
+ try:
+ os.close(self.fd)
+ except OSError:
+ pass
+ if self.path:
+ try:
+ os.remove(self.path)
+ except OSError:
+ pass
+
+
+def _odd_dimension_retry(cmd: List[str], stderr: str) -> Optional[List[str]]:
+ """An odd-sized source (641x359 screen captures, some 4:4:4 masters) fails every yuv420p
+ encode with "width/height not divisible by 2" (sweep F8, 15 tools). Return the same command
+ with an even-dimension scale prepended to its -vf chain (or a new -vf when the command had
+ none); None when the failure is something else or the graph is a -filter_complex the
+ caller has to fix itself."""
+ if "not divisible by 2" not in stderr or EVEN_SCALE in cmd or any(EVEN_SCALE in a for a in cmd):
+ return None
+ if "-filter_complex" in cmd:
+ return None
+ new = list(cmd)
+ if "-vf" in new:
+ i = new.index("-vf") + 1
+ new[i] = EVEN_SCALE + "," + new[i]
+ return new
+ if "-c:v" in new and new[new.index("-c:v") + 1] == "copy":
+ return None
+ return new[:-1] + ["-vf", EVEN_SCALE, new[-1]]
+
+
+def _check_existing_output(cmd: Sequence[str]) -> None:
+ """An output path that already exists is someone's file: a previous result, a source the
+ agent mis-named, a deliverable from another run. ffmpeg's -y (which every command carries so
+ a run never blocks on a y/N prompt) would replace it without a word. Until 2.0 this only
+ warns, per docs/contract.md's deprecation policy; FFMPEG_SKILL_NO_OVERWRITE=1 opts into the
+ 2.0 behaviour (refuse) today, and --overwrite is the explicit consent either way. Paths this
+ process wrote itself (a two-pass tool, a copy-then-re-encode fallback) are never in question."""
+ output = cmd[-1]
+ if output in ("-",) or output.startswith("pipe:") or output.startswith("-"):
+ return
+ try:
+ exists = os.path.isfile(output)
+ real = os.path.realpath(output)
+ except OSError:
+ return
+ if not exists or real in STATE.written:
+ return
+ try:
+ st = os.stat(output)
+ STATE.preexisting[real] = (st.st_size, st.st_mtime_ns)
+ except OSError:
+ pass
+ if STATE.overwrite:
+ return
+ if os.environ.get("FFMPEG_SKILL_NO_OVERWRITE", "") not in ("", "0"):
+ die(f"refusing to overwrite existing output {output!r}: pass --overwrite to replace it, or choose another -o path", kind="input")
+ info(f"warning: {output} already exists and will be overwritten (pass --overwrite to confirm; "
+ f"from 2.0 an existing output is refused without it, FFMPEG_SKILL_NO_OVERWRITE=1 enables that now)")
+
+
+def _remember_output(cmd: Sequence[str]) -> None:
+ output = cmd[-1]
+ if output == "-" or output.startswith("pipe:") or output.startswith("-"):
+ return
+ try:
+ STATE.written.add(os.path.realpath(output))
+ except OSError:
+ pass
+
+
+def _timed_out(cmd: Sequence[str], seconds: float) -> "None":
+ _cleanup_partial_output(cmd)
+ die(f"{os.path.basename(cmd[0])} exceeded the {seconds:.0f} s time limit and was killed; nothing was written. "
+ f"Raise --timeout (or FFMPEG_SKILL_TIMEOUT) if the job is genuinely that long, or check the input for a stall",
+ code=124, kind="timeout")
+
+
+def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str], Optional[str]]:
+ """When the output path already holds someone's file, run ffmpeg against a hidden sibling
+ temp path and move it over the original only on success.
+
+ ffmpeg's -y truncates the output the moment it opens it, and *when* it opens it depends on
+ the version: 6.1+ initialises the filter graph first (a bad LUT fails before the file is
+ touched), 5.x opens the output during option parsing, before any filter runs, so the same
+ bad LUT leaves a 0-byte file where the deliverable was. No amount of post-failure cleanup
+ can undo that; the only way to keep an existing file safe across a failed run is for ffmpeg
+ never to write to it. Same directory, same extension (the muxer is chosen by it), hidden
+ name, so nothing else changes for the encoder. Returns (command to execute, final path,
+ temp path); (cmd, None, None) when no staging is needed."""
+ output = cmd[-1]
+ if output == "-" or output.startswith("pipe:") or output.startswith("-"):
+ return list(cmd), None, None
+ try:
+ if not os.path.isfile(output) or os.path.realpath(output) in STATE.written:
+ return list(cmd), None, None
+ except OSError:
+ return list(cmd), None, None
+ d, base = os.path.split(output)
+ stem, ext = os.path.splitext(base)
+ tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
+ return list(cmd[:-1]) + [tmp], output, tmp
+
+
+def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Optional[Context]" = None) -> subprocess.CompletedProcess:
+ """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.
+
+ ffmpeg invocations are recorded in STATE.commands (for --json), skipped under --dry-run
+ (a fake successful CompletedProcess is returned so scripts can keep planning), and run
+ with a progress readout under --progress. ffprobe and other tools always run. An output
+ path that already exists is written through a temp file and replaced only on success
+ (see _stage_existing_output), so a failed run never costs the caller the file that was there.
+
+ `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
+ omitted, the commands and flags are read from the process-global STATE as before.
+ """
+ ctx = ctx or STATE
+ is_ffmpeg = _is_ffmpeg(cmd)
+ if is_ffmpeg:
+ _check_no_overwrite_input(cmd)
+ _check_output_path(cmd)
+ _check_existing_output(cmd)
+ ctx.commands.append(_cmdline(cmd))
+ if not quiet:
+ info(("[dry-run] $ " if ctx.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd), ctx=ctx)
+ if ctx.dry_run and is_ffmpeg:
+ return subprocess.CompletedProcess(list(cmd), 0, "", "")
+ if is_ffmpeg:
+ flush_drawtext_textfiles(cmd)
+ with _OutputLock(cmd[-1] if is_ffmpeg else "-"):
+ exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
+ proc = _execute(exec_cmd)
+ if proc.returncode != 0 and is_ffmpeg:
+ retry = _odd_dimension_retry(exec_cmd, proc.stderr or "")
+ if retry is not None:
+ info("source has odd dimensions; scaling to even before encoding (yuv420p needs it)")
+ ctx.commands[-1] = _cmdline(retry[:-1] + [cmd[-1]])
+ proc = _execute(retry)
+ elif "not divisible by 2" in (proc.stderr or ""):
+ die("the source has odd dimensions (width or height not divisible by 2) and this tool's filter graph "
+ "cannot pad them itself; make them even first, e.g. fit.py --width/--height, then retry",
+ kind="input")
+ if proc.returncode != 0 and check:
+ _fail(exec_cmd, proc.returncode, proc.stderr or "")
+ if final and tmp:
+ if proc.returncode == 0:
+ try:
+ os.replace(tmp, final)
+ except OSError as e:
+ _cleanup_partial_output(exec_cmd)
+ die(f"could not replace {final} with the new output: {e}", kind="output")
+ _remember_output(cmd)
+ else:
+ _cleanup_partial_output(exec_cmd)
+ return proc
+
+
+def _execute(exec_cmd: List[str]) -> subprocess.CompletedProcess:
+ """One attempt, never exiting on failure (run() decides after its retries)."""
+ if STATE.progress and _is_ffmpeg(exec_cmd) and exec_cmd[-1] != "-":
+ return _run_with_progress(exec_cmd, False)
+ return _run_captured(exec_cmd, False)
+
+
+def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, record: bool = False) -> subprocess.CompletedProcess:
+ """Run an ffmpeg *measurement* (scene scores, crop rectangles, decoded PCM, signal stats,
+ silence detection, loudness, stabilisation pass 1): output to `-f null`, a pipe or a temp
+ file, no deliverable written. These are not run() calls -- they run under --dry-run too,
+ since a plan built on a fake measurement is not a plan (silence.py used to report "0
+ silences" and loudness.py a made-up -20 LUFS under --dry-run) -- but they get the same
+ wall-clock limit as any other ffmpeg invocation and, with check=True, the same `kind: ffmpeg`
+ failure instead of an exit-0 "0 scenes found" over a file ffmpeg could not read. record=True
+ lists the command in the --json `commands` like run() does."""
+ if record:
+ STATE.commands.append(_cmdline(cmd))
+ limit = _limit_for(cmd)
+ try:
+ proc = subprocess.run(list(cmd), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=text, timeout=limit)
+ except subprocess.TimeoutExpired:
+ _timed_out(cmd, limit or 0)
+ if check and proc.returncode != 0:
+ err = proc.stderr if text else proc.stderr.decode(errors="replace")
+ _fail(cmd, proc.returncode, err)
+ return proc
+
+
+def dry_run_input_pending(path: str) -> bool:
+ """True when a measurement cannot run because its input does not exist yet under --dry-run:
+ in a render.py/batch.py plan each stage's input is the previous stage's output, which a dry
+ run never wrote. The measurement is then skipped (with a note) rather than failing the plan;
+ on a real file the measurement runs even under --dry-run."""
+ if STATE.dry_run and not os.path.exists(path):
+ info(f"[dry-run] {path} does not exist yet (an earlier dry-run stage would write it); measurement skipped")
+ return True
+ return False
+
+
+def child_limit(per_call: Optional[float] = None) -> Optional[float]:
+ """Wall-clock ceiling for running one sibling script as a subprocess (render/batch/report
+ stages, the MCP server's dispatch). A tool runs a handful of ffmpeg/ffprobe calls, each
+ under its own --timeout, so the outer ceiling is a multiple of that plus a margin: it never
+ fires first on a healthy run, and it is the only thing that ends a child hung for a reason
+ that is not ffmpeg (a stuck import, a wedged pipe). None when the per-call limit is 0."""
+ limit = STATE.timeout if per_call is None else per_call
+ return (limit * 4 + 60) if limit else None
+
+
+def run_tool(argv: Sequence[str], *, per_call: Optional[float] = None) -> subprocess.CompletedProcess:
+ """Run a sibling script (`argv[0]` is the script path) under child_limit(). On overrun the
+ child is killed and a CompletedProcess is returned whose stdout is this skill's own failure
+ document (kind timeout, exit 124), so callers that parse the child's --json see a timeout
+ exactly as they would from the child itself."""
+ limit = child_limit(per_call)
+ child = subprocess.Popen([sys.executable] + list(argv), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ _watch(child, []) # a sibling script removes its own partial output; there is none of ours to clean
+ try:
+ out, err = child.communicate(timeout=limit)
+ _unwatch(child)
+ return subprocess.CompletedProcess(child.args, child.returncode, out, err)
+ except subprocess.TimeoutExpired as e:
+ child.kill()
+ child.communicate()
+ _unwatch(child)
+ name = os.path.basename(str(argv[0]))
+ msg = f"{name} did not finish within {limit:.0f} s (4x the per-ffmpeg --timeout plus 60 s) and was killed"
+ doc = {"status": "failed", "exit_code": 124,
+ "error": {"kind": "timeout", "message": msg, "code": ERROR_CODE["timeout"], "retryable": ERROR_RETRYABLE},
+ "commands": []}
+ partial = e.stderr.decode(errors="replace") if isinstance(e.stderr, bytes) else (e.stderr or "")
+ return subprocess.CompletedProcess(list(argv), 124, json.dumps(doc), partial + f"\nerror: {msg}\n")
+
+
+def child_args() -> List[str]:
+ """The shared flags a tool that runs sibling scripts (render.py, batch.py) forwards to them,
+ so one `--timeout`/`--overwrite`/`--fast`/`--dry-run` on the outer command governs every
+ stage. Before 1.4.3 only --fast and --dry-run were forwarded; a --timeout given to render.py
+ stopped at render.py."""
+ args: List[str] = []
+ if STATE.fast:
+ args.append("--fast")
+ if STATE.dry_run:
+ args.append("--dry-run")
+ if STATE.overwrite:
+ args.append("--overwrite")
+ args += ["--timeout", f"{STATE.timeout:g}"]
+ return args
+
+
+def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
+ """Run an ffmpeg command that already maps its video/audio, trying first to also
+ stream-copy any subtitle/data streams the source has (`-map 0:s?`/`0:d?` are no-ops when
+ there are none). A source whose subtitle codec cannot be copied into the target container
+ (e.g. a container change) makes that first attempt fail; retry the same command without the
+ extra maps rather than let a tool that never touched subtitles start hard-failing because of
+ them. `cmd` is the full argv *without* the output path. Returns True only when the
+ retry-without-subtitles path was actually needed (i.e. subtitle/data streams were dropped)."""
+ if run(cmd + ["-map", "0:s?", "-map", "0:d?", "-c:s", "copy", "-c:d", "copy", output], check=False).returncode == 0:
+ return False
+ run(cmd + [output])
+ return True
+
+
+def _limit_for(cmd: Sequence[str]) -> Optional[float]:
+ """The wall-clock ceiling for this command: ffprobe (and other read-only probes) get a fixed
+ short one, ffmpeg the configured one; None means unlimited."""
+ if not _is_ffmpeg(cmd):
+ return PROBE_TIMEOUT if STATE.timeout else None
+ return STATE.timeout or None
+
+
+def _run_captured(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
+ """Plain run with stdout/stderr captured."""
+ limit = _limit_for(cmd)
+ child = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ _watch(child, cmd)
+ try:
+ out, err = child.communicate(timeout=limit)
+ except subprocess.TimeoutExpired:
+ child.kill()
+ child.communicate()
+ _unwatch(child)
+ _timed_out(cmd, limit or 0)
+ finally:
+ _unwatch(child)
+ proc = subprocess.CompletedProcess(list(cmd), child.returncode, out, err)
+ if proc.returncode == 0 and _is_ffmpeg(cmd):
+ _remember_output(cmd)
+ if proc.returncode != 0:
+ # Cleanup happens for every failed ffmpeg invocation, not just the check=True/_fail()
+ # path: a handful of scripts (cut.py, loudness.py, silence.py, sync.py) call run() with
+ # check=False so they can compose their own die() message from proc.stderr, but the
+ # partial-output risk is identical either way -- and for a script that retries into the
+ # same output path after a check=False failure (e.g. color.py's --retag copy-then-
+ # reencode fallback), removing the stale partial first is strictly safer than leaving it
+ # for -y to overwrite.
+ _cleanup_partial_output(cmd)
+ if check:
+ _fail(cmd, proc.returncode, proc.stderr)
+ return proc
+
+
+def _progress_line(done: float, total: float, elapsed: float) -> str:
+ if total > 0:
+ pct = min(99.9, done / total * 100)
+ eta = (elapsed / pct * (100 - pct)) if pct > 0.5 else 0
+ return f"\r {pct:5.1f}% {done:7.1f}s / {total:.1f}s ETA {eta:4.0f}s"
+ return f"\r {done:7.1f}s encoded"
+
+
+def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
+ """Run ffmpeg with -progress on a pipe and print percent/ETA to stderr.
+
+ The time limit is checked on a clock, not per progress line: a deadlocked ffmpeg (the very
+ case --timeout exists for) prints nothing, so a loop that only looked at the deadline when a
+ line arrived waited on it forever. Reader threads drain both pipes; the main loop wakes at
+ least twice a second to compare the clock against the limit."""
+ import queue
+ import threading
+ import time
+ total = STATE.duration_hint or 0.0
+ full = cmd[:1] + ["-progress", "pipe:1", "-nostats"] + cmd[1:]
+ t0 = time.time()
+ limit = _limit_for(cmd)
+ proc = subprocess.Popen(full, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ _watch(proc, cmd)
+ assert proc.stdout is not None and proc.stderr is not None
+ lines: "queue.Queue[Optional[str]]" = queue.Queue()
+ err_chunks: List[str] = []
+
+ def pump_out() -> None:
+ for line in proc.stdout: # type: ignore[union-attr]
+ lines.put(line)
+ lines.put(None)
+
+ def pump_err() -> None:
+ err_chunks.append(proc.stderr.read()) # type: ignore[union-attr]
+
+ threading.Thread(target=pump_out, daemon=True).start()
+ err_thread = threading.Thread(target=pump_err, daemon=True)
+ err_thread.start()
+ last = ""
+
+ def clear_line() -> None:
+ if last:
+ sys.stderr.write("\r" + " " * len(last) + "\r")
+
+ def timed_out() -> None:
+ proc.kill()
+ proc.wait()
+ clear_line()
+ _timed_out(cmd, limit or 0)
+
+ while True:
+ remaining = (limit - (time.time() - t0)) if limit else None
+ if remaining is not None and remaining <= 0:
+ timed_out()
+ try:
+ line = lines.get(timeout=min(0.5, remaining) if remaining is not None else 0.5)
+ except queue.Empty:
+ continue
+ if line is None:
+ break
+ if line.startswith("out_time_us=") or line.startswith("out_time_ms="):
+ try:
+ done = int(line.split("=")[1]) / 1_000_000
+ except ValueError:
+ continue
+ msg = _progress_line(done, total, time.time() - t0)
+ if msg != last:
+ sys.stderr.write(msg)
+ sys.stderr.flush()
+ last = msg
+ try:
+ proc.wait(timeout=(max(5.0, limit - (time.time() - t0)) if limit else None))
+ except subprocess.TimeoutExpired:
+ timed_out()
+ _unwatch(proc)
+ err_thread.join()
+ err = "".join(err_chunks)
+ clear_line()
+ if proc.returncode == 0:
+ _remember_output(cmd)
+ if proc.returncode != 0:
+ _cleanup_partial_output(cmd)
+ if check:
+ _fail(cmd, proc.returncode, err)
+ return subprocess.CompletedProcess(full, proc.returncode, "", err)
+
+
+def shell_quote(s: str) -> str:
+ if not s or any(ch in s for ch in " \t\n\r\\\"';|&<>()[]{}$*?"):
+ 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 place_output(src: str, dst: str) -> None:
+ """Deliver an already-rendered file to `dst` under the same rules as an ffmpeg output:
+ the path is checked, an existing file is only replaced through a sibling temp so a
+ failed copy never costs the caller what was there, and the result is remembered as ours.
+ render.py's final `copyfile()` used to bypass all three."""
+ import shutil
+ cmd = ["ffmpeg", dst]
+ _check_output_path(cmd)
+ _check_existing_output(cmd)
+ d, base = os.path.split(dst)
+ stem, ext = os.path.splitext(base)
+ tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
+ try:
+ shutil.copyfile(src, tmp)
+ os.replace(tmp, dst)
+ except OSError as e:
+ try:
+ os.remove(tmp)
+ except OSError:
+ pass
+ die(f"could not place {dst}: {e}", kind="output")
+ _remember_output(cmd)
+
+
+_DRAWTEXT_TMPDIR: "Optional[str]" = None
+
+
+_DRAWTEXT_PENDING: "Dict[str, str]" = {}
+
+
+def _drawtext_tmpdir(create: bool = True) -> str:
+ """The private, per-run directory drawn-text files live in.
+
+ tempfile.mkdtemp() creates it 0700 under a name nobody can guess, which is the whole point:
+ the 1.15.0 shape (a fixed, world-writable `/tmp/ffmpeg-skill-text` entered with
+ makedirs(exist_ok=True) and content-addressed filenames) let any other user on the machine
+ pre-create the directory or plant a symlink at a predictable name, and handed the second
+ user of a shared box a PermissionError out of filter construction instead of a `kind: input`
+ refusal. The directory is removed when the process ends, whether it succeeded or failed.
+ """
+ global _DRAWTEXT_TMPDIR
+ import tempfile
+ if _DRAWTEXT_TMPDIR and os.path.isdir(_DRAWTEXT_TMPDIR):
+ return _DRAWTEXT_TMPDIR
+ if not create:
+ # --dry-run names the path it WOULD use and creates nothing (a dry run writes nothing).
+ return os.path.join(tempfile.gettempdir(), "ffmpeg-skill-text-%d" % os.getpid())
+ import atexit
+ _DRAWTEXT_TMPDIR = tempfile.mkdtemp(prefix="ffmpeg-skill-text-")
+ atexit.register(shutil.rmtree, _DRAWTEXT_TMPDIR, True)
+ return _DRAWTEXT_TMPDIR
+
+
+def flush_drawtext_textfiles(cmd: "Sequence[str]") -> "List[str]":
+ """Write the drawn-text files this command actually names, and return their paths.
+
+ The text is registered when the filter STRING is built, but a filter string is not a run:
+ graphics.py builds the drawtext graph even on a job that is finally rendered through libass,
+ and every tool builds one under --dry-run. Writing here -- from run(), past the dry-run
+ return, against the command that is about to be executed -- is what keeps both of those from
+ leaving a file behind.
+ """
+ if not _DRAWTEXT_PENDING:
+ return []
+ joined = " ".join(str(a) for a in cmd)
+ written = []
+ for path, body in list(_DRAWTEXT_PENDING.items()):
+ # match on the unique file name, not the full path: inside a filter string the path is
+ # escaped (a Windows drive colon becomes `C\\:`, and the separators are forward slashes),
+ # so the registered spelling never appears verbatim in the command
+ if os.path.basename(path) not in joined or os.path.exists(path):
+ continue
+ # O_NOFOLLOW exists on POSIX only; the directory is private (mkdtemp, 0700) so the
+ # symlink guard is belt and braces there and unavailable on Windows
+ flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_NOFOLLOW", 0)
+ fd = os.open(path, flags, 0o600)
+ with os.fdopen(fd, "w", encoding="utf-8") as fh:
+ fh.write(body)
+ written.append(path)
+ return written
+
+
+def ffmpeg_encoders() -> set:
+ """Names from `ffmpeg -encoders`, read once; empty when ffmpeg is missing. Used only to pick
+ an AV1 encoder and to refuse --codec av1 / prores before ffmpeg would."""
+ global _ENCODERS
+ if _ENCODERS is None:
+ _ENCODERS = set()
+ try:
+ out = subprocess.run([shutil.which("ffmpeg") or "ffmpeg", "-hide_banner", "-encoders"], stdout=subprocess.PIPE,
+ stderr=subprocess.DEVNULL, text=True, timeout=PROBE_TIMEOUT).stdout
+ _ENCODERS = set(re.findall(r"^\s*[VAS][.\w]{5}\s+(\S+)", out, re.M))
+ except (OSError, subprocess.SubprocessError):
+ pass
+ return _ENCODERS
+
+
+def read_text_or_die(path: str, flag: str) -> str:
+ """Read a caller-supplied UTF-8 text file (a cue list, chapters, notes) or fail as kind input
+ with the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback."""
+ if os.path.isdir(path):
+ # checked first: Windows raises PermissionError, not IsADirectoryError, for a directory
+ die(f"{flag}: {path} is a directory, not a text file")
+ try:
+ with open(path, "r", encoding="utf-8") as fh:
+ return fh.read()
+ except FileNotFoundError:
+ die(f"{flag}: {path} does not exist")
+ except IsADirectoryError:
+ die(f"{flag}: {path} is a directory, not a text file")
+ except UnicodeDecodeError as e:
+ die(f"{flag}: {path} is not UTF-8 text ({e.reason} at byte {e.start}); save it as UTF-8")
+ except OSError as e:
+ die(f"{flag}: cannot read {path}: {e.strerror}")
+ return "" # unreachable
+
+
+# Deferred to the foot of the module on purpose. runner is the first module the package loads and
+# emit needs runner's Context/STATE/ERROR_CODE, so the two form a cycle that has to be cut
+# somewhere: by the time this line runs every name emit reads from runner above is defined, and
+# every name runner reads from emit is only ever read inside a function body, never at import.
+from _common.emit import _plan_at_exit, die, info # noqa: E402
diff --git a/scripts/_common/text.py b/scripts/_common/text.py
new file mode 100644
index 0000000..aeda971
--- /dev/null
+++ b/scripts/_common/text.py
@@ -0,0 +1,980 @@
+"""Text people can see: font resolution per script, emoji clusters and their assets, drawtext
+escaping and option building, and the per-character advance table the caption wrap measures with.
+"""
+from __future__ import annotations
+
+import os
+import platform
+import re
+import shutil
+import subprocess
+import unicodedata
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+from _common.decision import escape_filter_path
+from _common.emit import die, info
+from _common.runner import STATE, _DRAWTEXT_PENDING, _drawtext_tmpdir, ffmpeg_version
+
+
+def drawtext_boxborderw(vertical: int, horizontal: int) -> str:
+ """drawtext's per-side `boxborderw=top|right|bottom|left` (and the two-value `v|h` form)
+ arrived in FFmpeg 6.1; 5.x and 6.0 reject the `|` with "Error setting option boxborderw"
+ (found by the FFmpeg 5.1.1 CI job, #146). Older builds get the larger single value."""
+ if ffmpeg_version() >= (6, 1):
+ return f"{vertical}|{horizontal}"
+ return str(max(vertical, horizontal))
+
+
+def default_font_file(font_name: str) -> Optional[str]:
+ """Resolve `font_name` to a concrete on-disk font file, so a caller can tell drawtext
+ `fontfile=<path>` instead of `font=<name>`, when possible.
+
+ On some real Windows ffmpeg builds (winget's gyan.dev 9.x), drawtext's own fontconfig
+ resolution crashes with an access violation whenever it has to resolve a font by family name
+ -- with or without a valid fonts.conf on FONTCONFIG_FILE. `fontfile=` is the only form
+ confirmed not to crash (#100), since it never touches fontconfig at all. `font_name` itself is
+ ignored on Windows for that reason: a fixed, near-universally-present system font is used
+ instead of trying to resolve the requested family (which would crash the same way).
+
+ On Linux/macOS this is best-effort and uses the real requested family: `fc-match` reports the
+ same file fontconfig would resolve `font_name` to anyway, so a caller gets the identical font,
+ just already resolved to a path -- fontfile= skips a redundant fontconfig lookup and equally
+ sidesteps the same class of crash if it exists on some build there too, but the fallback below
+ (returning None) is exercised routinely there, not just on failure.
+
+ Returns None when nothing could be resolved (fc-match missing/unavailable, or no well-known
+ Windows font file present); the caller falls back to font=<font_name>, the prior behaviour.
+ """
+ if platform.system() == "Windows":
+ windir = os.environ.get("WINDIR", "C:\\Windows")
+ fonts = Path(windir) / "Fonts"
+ # The requested family first: a file whose name starts with the family name with spaces
+ # removed (Noto Sans CJK JP -> NotoSansCJKjp-Regular.otf, Meiryo -> meiryo.ttc), then the
+ # common CJK system fonts when the request looks CJK (so Japanese text does not render as
+ # boxes in Arial), and Arial only as the last resort.
+ wanted = re.sub(r"[^a-z0-9]", "", (font_name or "").lower())
+ try:
+ files = sorted(fonts.iterdir()) if fonts.is_dir() else []
+ except OSError:
+ files = []
+ if wanted:
+ for f in files:
+ stem = re.sub(r"[^a-z0-9]", "", f.stem.lower())
+ if f.suffix.lower() in (".ttf", ".otf", ".ttc") and stem.startswith(wanted):
+ return str(f)
+ if any(k in wanted for k in ("cjk", "gothic", "mincho", "meiryo", "yugoth", "msgothic", "malgun", "simhei", "simsun", "jp", "kr", "sc", "tc")):
+ for name in ("NotoSansCJKjp-Regular.otf", "NotoSansCJK-Regular.ttc", "meiryo.ttc", "YuGothM.ttc", "msgothic.ttc", "malgun.ttf", "msyh.ttc"):
+ if (fonts / name).exists():
+ return str(fonts / name)
+ candidate = fonts / "arial.ttf"
+ return str(candidate) if candidate.exists() else None
+ exe = shutil.which("fc-match")
+ if not exe:
+ return None
+ try:
+ proc = subprocess.run([exe, "--format=%{file}\n", font_name], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=5)
+ except (subprocess.TimeoutExpired, OSError):
+ return None
+ if proc.returncode != 0:
+ return None
+ path = proc.stdout.splitlines()[0].strip() if proc.stdout.strip() else ""
+ return path if path and os.path.exists(path) else None
+
+
+# --------------------------------------------------------------------------- script detection
+# 1.12: non-Latin caption/overlay text used to render as tofu (empty boxes) whenever the default
+# family carried no glyphs for it -- silently, because fontconfig substitutes SOMETHING for every
+# request and ffmpeg exits 0 either way. The tools now detect the script of the text they are about
+# to draw and resolve a font file that actually covers it; nothing found is a failed job, not a
+# warning (a video full of boxes is not a delivery).
+SCRIPTS = ("ja", "zh", "ko", "ar", "he", "hi", "bn", "ta", "th", "lo", "ru", "el", "latin")
+
+
+LANGUAGE_NAMES = {
+ "ja": "Japanese", "zh": "Chinese", "ko": "Korean", "ar": "Arabic", "he": "Hebrew",
+ "hi": "Devanagari (Hindi/Marathi/Nepali)", "th": "Thai", "ru": "Cyrillic (Russian and others)",
+ "el": "Greek", "latin": "Latin", "bn": "Bengali", "ta": "Tamil", "lo": "Lao",
+}
+
+
+# fontconfig's own :lang= codes for each script we detect (zh uses zh-cn, the Simplified subset
+# every CJK font that claims zh carries; the rest are the plain two-letter codes).
+FC_LANG = {"ja": "ja", "zh": "zh-cn", "ko": "ko", "ar": "ar", "he": "he", "hi": "hi", "th": "th", "ru": "ru", "el": "el",
+ "bn": "bn", "ta": "ta", "lo": "lo"}
+
+
+# Families tried in order, best first. The names are matched case-insensitively against the start
+# of any family fontconfig reports for a file, so "Noto Sans CJK JP" also matches
+# "Noto Sans CJK JP Black". Anything not listed still qualifies -- it just sorts after these.
+PREFERRED_FAMILIES = {
+ "ja": ["Noto Sans CJK JP", "Noto Serif CJK JP", "Noto Sans JP", "Source Han Sans", "IPAPGothic", "IPAGothic", "IPA", "VL Gothic", "TakaoGothic", "WenQuanYi Zen Hei"],
+ "zh": ["Noto Sans CJK SC", "Noto Serif CJK SC", "Noto Sans SC", "Source Han Sans", "WenQuanYi Zen Hei", "WenQuanYi Micro Hei", "Droid Sans Fallback"],
+ "ko": ["Noto Sans CJK KR", "Noto Serif CJK KR", "Noto Sans KR", "Source Han Sans K", "NanumGothic", "Nanum Gothic", "Malgun Gothic", "WenQuanYi Zen Hei"],
+ "ar": ["Noto Sans Arabic", "Noto Naskh Arabic", "Amiri", "Scheherazade", "DejaVu Sans", "FreeSans", "FreeSerif"],
+ "he": ["Noto Sans Hebrew", "Noto Serif Hebrew", "DejaVu Sans", "FreeSans", "FreeSerif"],
+ "hi": ["Noto Sans Devanagari", "Noto Serif Devanagari", "Lohit Devanagari", "Mangal", "Nirmala UI", "Samyak Devanagari", "FreeSans", "FreeSerif"],
+ "th": ["Noto Sans Thai", "Noto Serif Thai", "Loma", "Garuda", "Waree", "Umpush", "Norasi", "Sarabun", "Leelawadee UI", "FreeSerif"],
+ "bn": ["Noto Sans Bengali", "Noto Serif Bengali", "Lohit Bengali", "Mukti Narrow", "Vrinda", "Nirmala UI", "FreeSerif"],
+ "ta": ["Noto Sans Tamil", "Noto Serif Tamil", "Lohit Tamil", "Latha", "Nirmala UI", "FreeSerif"],
+ "lo": ["Noto Sans Lao", "Noto Serif Lao", "Phetsarath OT", "Souliyo Unicode", "Saysettha OT", "DokChampa", "Leelawadee UI"],
+ "ru": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
+ "el": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
+}
+
+
+# Windows has no fontconfig: the system fonts are looked up by file name instead, best first.
+WINDOWS_FONTS = {
+ "ko": [("malgun.ttf", "Malgun Gothic"), ("gulim.ttc", "Gulim"), ("batang.ttc", "Batang")],
+ "zh": [("msyh.ttc", "Microsoft YaHei"), ("simhei.ttf", "SimHei"), ("simsun.ttc", "SimSun")],
+ "ja": [("meiryo.ttc", "Meiryo"), ("YuGothM.ttc", "Yu Gothic Medium"), ("YuGothR.ttc", "Yu Gothic"), ("msgothic.ttc", "MS Gothic")],
+ "ar": [("tahoma.ttf", "Tahoma"), ("arial.ttf", "Arial")],
+ "he": [("tahoma.ttf", "Tahoma"), ("arial.ttf", "Arial")],
+ "hi": [("mangal.ttf", "Mangal"), ("Nirmala.ttf", "Nirmala UI"), ("NirmalaB.ttf", "Nirmala UI")],
+ "th": [("leelawui.ttf", "Leelawadee UI"), ("leelawad.ttf", "Leelawadee"), ("tahoma.ttf", "Tahoma")],
+ "bn": [("Nirmala.ttf", "Nirmala UI"), ("vrinda.ttf", "Vrinda")],
+ "ta": [("Nirmala.ttf", "Nirmala UI"), ("latha.ttf", "Latha")],
+ "lo": [("leelawui.ttf", "Leelawadee UI"), ("DokChamp.ttf", "DokChampa")],
+ "ru": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
+ "el": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
+}
+
+
+_SCRIPT_RANGES = (
+ ("ko", ((0x1100, 0x11FF), (0x3130, 0x318F), (0xA960, 0xA97F), (0xAC00, 0xD7FF))), # Hangul syllables + Jamo
+ ("kana", ((0x3040, 0x309F), (0x30A0, 0x30FF), (0x31F0, 0x31FF), (0xFF66, 0xFF9F))), # hiragana/katakana
+ ("han", ((0x3400, 0x4DBF), (0x4E00, 0x9FFF), (0xF900, 0xFAFF), (0x20000, 0x2A6DF))),
+ ("ar", ((0x0600, 0x06FF), (0x0750, 0x077F), (0x08A0, 0x08FF), (0xFB50, 0xFDFF), (0xFE70, 0xFEFF))),
+ ("he", ((0x0590, 0x05FF), (0xFB1D, 0xFB4F))),
+ ("hi", ((0x0900, 0x097F), (0xA8E0, 0xA8FF))),
+ ("bn", ((0x0980, 0x09FF),)),
+ ("ta", ((0x0B80, 0x0BFF),)),
+ ("th", ((0x0E00, 0x0E7F),)),
+ ("lo", ((0x0E80, 0x0EFF),)),
+ ("ru", ((0x0400, 0x04FF), (0x0500, 0x052F), (0x2DE0, 0x2DFF))),
+ ("el", ((0x0370, 0x03FF), (0x1F00, 0x1FFF))),
+)
+
+
+# --------------------------------------------------------------------------- emoji (1.15)
+# Emoji are orthogonal to the writing system: "やった 🎉" is Japanese AND emoji. They are detected
+# separately from detect_script() so a cue's font resolution is still decided by its letters.
+EMOJI_RANGES = (
+ (0x1F300, 0x1FAFF), # symbols & pictographs, supplemental, extended-A
+ (0x1F000, 0x1F0FF), # mahjong/domino/playing cards
+ (0x2600, 0x27BF), # misc symbols + dingbats
+ (0x2B00, 0x2BFF), # misc symbols and arrows
+ (0xFE0F, 0xFE0F), # VS16 (emoji presentation selector)
+ (0x1F1E6, 0x1F1FF), # regional indicators (flags)
+ (0x20E3, 0x20E3), # combining enclosing keycap
+ (0x1F3FB, 0x1F3FF), # skin-tone modifiers
+)
+
+
+# U+200D ZWJ is deliberately NOT in EMOJI_RANGES: it is ordinary Indic/Persian orthography
+# (क्‍ष is ka + virama + ZWJ + ssa) and only becomes emoji glue *between two emoji bases*.
+# Characters that never START a cluster: they bind to whatever stands before them.
+_EMOJI_TAIL = frozenset({0x200D, 0xFE0F, 0x20E3} | set(range(0x1F3FB, 0x1F400)))
+
+
+_EMOJI_REGIONAL = range(0x1F1E6, 0x1F200)
+
+
+_ZWJ = 0x200D
+
+
+_VS15 = 0xFE0E # text-presentation selector: "draw this as a character, not as an emoji"
+
+
+_VS16 = 0xFE0F
+
+
+_KEYCAP = 0x20E3
+
+
+_KEYCAP_BASES = frozenset("0123456789#*")
+
+
+def _is_emoji_char(ch: str) -> bool:
+ cp = ord(ch)
+ return any(lo <= cp <= hi for lo, hi in EMOJI_RANGES)
+
+
+def _is_emoji_base(ch: str) -> bool:
+ """Can this character START an emoji cluster? Pictographs and regional indicators can;
+ the joiners and modifiers (ZWJ, VS16, keycap, skin tone) never can -- they only bind to an
+ emoji base that already stands before them. Without this, a ZWJ or a VS16 sitting after an
+ ordinary letter turned that letter into "an emoji" and the PNG route replaced it with a gap."""
+ return ord(ch) not in _EMOJI_TAIL and _is_emoji_char(ch)
+
+
+def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
+ """(index in `text`, cluster) for every emoji in it, ZWJ sequences, VS16, keycaps, flag pairs
+ and skin-tone modifiers kept together -- 👩‍💻 is one cluster, not three, and 1️⃣ starts at the
+ digit even though the digit is not itself an emoji character.
+
+ A cluster can only START at an emoji base (a pictograph, a regional indicator) or at a keycap
+ base (`0-9 # *`) that is actually followed by U+20E3. A ZWJ is glue *inside* a cluster, never
+ a starter and never a tail on its own: `क्‍ष` (Hindi ka + virama + ZWJ + ssa) and `abc‍def`
+ contain no emoji. A base explicitly marked with U+FE0E (VS15, text presentation) is likewise
+ not an emoji -- the author asked for the character, not the picture.
+ """
+ out: "List[Tuple[int, str]]" = []
+ i = 0
+ n = len(text or "")
+ while i < n:
+ ch = text[i]
+ start = i
+ if _is_emoji_base(ch):
+ j = i + 1
+ if j < n and ord(text[j]) == _VS15: # text presentation requested: not an emoji
+ i = j + 1
+ continue
+ elif ch in _KEYCAP_BASES:
+ j = i + 1
+ if j < n and ord(text[j]) == _VS16:
+ j += 1
+ if not (j < n and ord(text[j]) == _KEYCAP):
+ i += 1
+ continue
+ j += 1
+ else:
+ i += 1
+ continue
+ # extend: modifiers bind rightwards, a ZWJ only when a real emoji base follows it
+ while j < n:
+ cp = ord(text[j])
+ if cp in (_VS16, _KEYCAP) or 0x1F3FB <= cp <= 0x1F3FF:
+ j += 1
+ continue
+ if cp == _ZWJ and j + 1 < n and _is_emoji_base(text[j + 1]):
+ j += 2
+ continue
+ if (j == start + 1 and ord(ch) in _EMOJI_REGIONAL and cp in _EMOJI_REGIONAL):
+ j += 1
+ continue
+ break
+ out.append((start, text[start:j]))
+ i = j
+ return out
+
+
+def has_emoji(text: str) -> bool:
+ return bool(emoji_clusters(text or ""))
+
+
+def emoji_codepoint_name(cluster: str) -> str:
+ """The asset filename stem for a cluster: lowercase hex code points joined by '-', the
+ Twemoji/Noto convention (1f389, 1f469-200d-1f4bb, 1f1ef-1f1f5)."""
+ return "-".join(f"{ord(c):x}" for c in cluster)
+
+
+def _emoji_name_candidates(cluster: str) -> "List[str]":
+ """Asset stems to try, most specific first: exact, without VS16, without skin tone, the ZWJ
+ sequence reduced to its first code point, the bare base."""
+ cps = [ord(c) for c in cluster]
+ names = [emoji_codepoint_name(cluster)]
+
+ def add(seq):
+ name = "-".join(f"{c:x}" for c in seq)
+ if name and name not in names:
+ names.append(name)
+ add([c for c in cps if c != 0xFE0F])
+ add([c for c in cps if c != 0xFE0F and not (0x1F3FB <= c <= 0x1F3FF)])
+ if 0x200D in cps:
+ add([cps[0]])
+ add([cps[0]])
+ return names
+
+
+def emoji_asset_for(cluster: str, assets_dir: "Optional[str]") -> "Optional[str]":
+ """The PNG for `cluster` under `assets_dir`, or None when nothing matches."""
+ if not assets_dir or not os.path.isdir(assets_dir):
+ return None
+ for name in _emoji_name_candidates(cluster):
+ for ext in (".png", ".PNG"):
+ candidate = os.path.join(assets_dir, name + ext)
+ if os.path.isfile(candidate):
+ return candidate
+ return None
+
+
+EMOJI_ASSET_HINT = (
+ "point --emoji-assets at a directory of PNGs named by code point (1f389.png): "
+ "twemoji/assets/72x72 (Twemoji, CC-BY 4.0) or noto-emoji/png/128 (Noto Emoji, OFL/Apache-2.0) "
+ "are the two people already have. The skill has no network at runtime, so the assets must "
+ "already exist on this machine -- nothing is ever downloaded")
+
+
+_EMOJI_COLOR_FAMILIES = ("Noto Color Emoji", "Apple Color Emoji", "Segoe UI Emoji")
+
+
+_EMOJI_SUPPORT_CACHE: "Dict[Tuple[Optional[str], bool], Dict[str, Any]]" = {}
+
+
+def _emoji_color_font() -> "Tuple[Optional[str], Optional[str], bool]":
+ """(family, file, fontconfig_answered) for the first installed colour emoji family."""
+ exe = shutil.which("fc-list")
+ if not exe:
+ return None, None, False
+ for family in _EMOJI_COLOR_FAMILIES:
+ try:
+ proc = subprocess.run([exe, f":family={family}", "file"], stdout=subprocess.PIPE,
+ stderr=subprocess.DEVNULL, text=True, timeout=10)
+ except (subprocess.TimeoutExpired, OSError):
+ return None, None, False
+ if proc.returncode != 0:
+ return None, None, False
+ for line in proc.stdout.splitlines():
+ path = line.split(":", 1)[0].strip()
+ if path and os.path.exists(path):
+ return family, path, True
+ return None, None, True
+
+
+def _libass_color_probe() -> "Optional[bool]":
+ """Does THIS ffmpeg render an emoji in colour through libass? Answered by a render, never by
+ the font listing: Noto Color Emoji installs happily on builds whose freetype/libass has no
+ colour-bitmap path at all, and those render a monochrome outline instead (measured). ~80 ms.
+ None means the probe could not be run (no ffmpeg, a failure) -- unknown, not false."""
+ exe = shutil.which("ffmpeg")
+ if not exe:
+ return None
+ import tempfile
+ with tempfile.TemporaryDirectory() as td:
+ srt = os.path.join(td, "e.srt")
+ with open(srt, "w", encoding="utf-8") as fh:
+ fh.write("1\n00:00:00,000 --> 00:00:01,000\n\U0001F389\n")
+ try:
+ 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",
+ "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+ stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=20)
+ except (subprocess.TimeoutExpired, OSError):
+ return None
+ if proc.returncode != 0 or len(proc.stdout) < 64 * 64 * 3:
+ return None
+ data = proc.stdout
+ for i in range(0, 64 * 64 * 3, 3):
+ r, g, b = data[i], data[i + 1], data[i + 2]
+ if max(r, g, b) - min(r, g, b) > 40:
+ return True
+ return False
+
+
+def emoji_support(assets: "Optional[str]" = None, probe: bool = True) -> "Dict[str, Any]":
+ """What this machine can actually do with emoji, cached per process.
+
+ `mode` is `color` when a render probe proves libass draws colour, else `png` when an assets
+ directory resolves, else `mono` when some installed face has a glyph at all, else `none`.
+ An installed colour emoji font proves nothing on its own -- that is why `libass_color` comes
+ from a render (see references/gotchas.md#emoji). `probe=False` (`contract --json --static`, and every
+ static/JSON-only path) skips the render entirely and leaves `libass_color` unknown.
+ """
+ key = (assets or None, bool(probe))
+ if key in _EMOJI_SUPPORT_CACHE:
+ return dict(_EMOJI_SUPPORT_CACHE[key])
+ family, file, fc_answered = _emoji_color_font()
+ libass_color = _libass_color_probe() if probe else None
+ assets_dir = assets if (assets and os.path.isdir(assets)) else None
+ if libass_color:
+ mode = "color"
+ elif assets_dir:
+ mode = "png"
+ elif family:
+ mode = "mono"
+ elif not fc_answered:
+ # No fontconfig to ask (a static ffmpeg build, a bare container): the PNG path needs none,
+ # so the honest answer is png-or-none, never "none because fc-list is missing".
+ mode = "none"
+ else:
+ mode = "none"
+ if not fc_answered:
+ detail = "no fontconfig on this machine; the PNG overlay path needs none"
+ elif libass_color:
+ detail = f"{family or 'an installed face'} renders in colour through libass on this ffmpeg"
+ elif family and libass_color is False:
+ detail = f"{family} installed but libass renders it monochrome on this build"
+ elif family and libass_color is None:
+ detail = f"{family} installed; the colour render probe was not run"
+ elif assets_dir:
+ detail = "no colour emoji family installed; using the PNG assets directory"
+ else:
+ detail = "no colour emoji family installed and no --emoji-assets directory"
+ result = {"mode": mode, "color_font": family, "color_font_file": file,
+ "libass_color": libass_color, "assets": assets_dir,
+ "detail": detail, "fix": EMOJI_ASSET_HINT}
+ _EMOJI_SUPPORT_CACHE[key] = result
+ return dict(result)
+
+
+def resolve_emoji_assets(flag: "Optional[str]" = None, project: "Optional[str]" = None,
+ brand: "Optional[dict]" = None) -> "Optional[str]":
+ """--emoji-assets DIR, else the project key, else brand.json, else FFMPEG_SKILL_EMOJI_ASSETS.
+ A directory that was named but does not exist is a failed job, never a silent downgrade."""
+ brand = brand or {}
+ styles = (brand.get("styles") or {}).get("caption") or {}
+ for value, where in ((flag, "--emoji-assets"), (project, "the project's text.emoji_assets"),
+ (styles.get("emoji_assets"), "brand.json styles.caption.emoji_assets"),
+ (brand.get("emoji_assets"), "brand.json emoji_assets"),
+ (os.environ.get("FFMPEG_SKILL_EMOJI_ASSETS"), "FFMPEG_SKILL_EMOJI_ASSETS")):
+ if not value:
+ continue
+ if not os.path.isdir(str(value)):
+ die(f"{where}: {value} is not a readable directory -- {EMOJI_ASSET_HINT}", kind="input")
+ return str(value)
+ return None
+
+
+# --------------------------------------------------------------------------- text measurement (1.12)
+# Moved here in 1.15 so graphics.py's ASS route and the emoji placement share caption.py's table.
+# Average advance width per character, in em (a fraction of the font size). Proportional Latin text
+# averages a bit over half an em; CJK and Thai are drawn on a full-width grid; Arabic/Hebrew and
+# Devanagari sit in between. These are deliberately averages, not per-glyph metrics: measuring the
+# real advance needs a font parser (no stdlib one) and would still be wrong for libass's own
+# shaping, while a cue wrapped from an average is right to within a character on every line.
+# (Latin is measured per character from LATIN_EM below, not from this average.)
+ADVANCE_EM = {"ja": 1.0, "zh": 1.0, "ko": 1.0, "th": 1.0, "hi": 0.7, "ar": 0.6, "he": 0.6,
+ "ru": 0.55, "el": 0.55, "latin": 0.55}
+
+
+# Scripts written without spaces: a line breaks between any two characters.
+NO_SPACE_SCRIPTS = ("ja", "zh", "ko", "th")
+
+
+# Per-character Latin advances in em, read off DejaVu Sans (the default caption family, and close
+# enough to any other proportional sans for a wrap) and rounded UP: a capital runs 0.56-0.99 em
+# against the single 0.55 average that used to stand for all of Latin, so an all-caps caption --
+# the style most burn-ins use -- overflowed the safe area and was silently re-wrapped by libass
+# past --max-lines. Rounding up is the safe direction: libass re-wraps a too-long line, it never
+# un-wraps a short one. Characters outside the table fall back by class (0.7 uppercase/digit,
+# 0.57 lowercase and anything else Latin-ish).
+LATIN_EM = {
+ ' ': 0.32, '!': 0.41, '"': 0.46, '#': 0.84, '$': 0.64, '%': 0.96, '&': 0.78, "'": 0.28,
+ '(': 0.4, ')': 0.4, '*': 0.5, '+': 0.84, ',': 0.32, '-': 0.37, '.': 0.32, '/': 0.34, '0': 0.64,
+ '1': 0.64, '2': 0.64, '3': 0.64, '4': 0.64, '5': 0.64, '6': 0.64, '7': 0.64, '8': 0.64,
+ '9': 0.64, ':': 0.34, ';': 0.34, '<': 0.84, '=': 0.84, '>': 0.84, '?': 0.54, '@': 1.0,
+ 'A': 0.69, 'B': 0.69, 'C': 0.7, 'D': 0.78, 'E': 0.64, 'F': 0.58, 'G': 0.78, 'H': 0.76,
+ 'I': 0.3, 'J': 0.3, 'K': 0.66, 'L': 0.56, 'M': 0.87, 'N': 0.75, 'O': 0.79, 'P': 0.61,
+ 'Q': 0.79, 'R': 0.7, 'S': 0.64, 'T': 0.62, 'U': 0.74, 'V': 0.69, 'W': 0.99, 'X': 0.69,
+ 'Y': 0.62, 'Z': 0.69, '[': 0.4, '\\': 0.34, ']': 0.4, '^': 0.84, '_': 0.5, '`': 0.5, 'a': 0.62,
+ 'b': 0.64, 'c': 0.55, 'd': 0.64, 'e': 0.62, 'f': 0.36, 'g': 0.64, 'h': 0.64, 'i': 0.28,
+ 'j': 0.28, 'k': 0.58, 'l': 0.28, 'm': 0.98, 'n': 0.64, 'o': 0.62, 'p': 0.64, 'q': 0.64,
+ 'r': 0.42, 's': 0.53, 't': 0.4, 'u': 0.64, 'v': 0.6, 'w': 0.82, 'x': 0.6, 'y': 0.6, 'z': 0.53,
+ '{': 0.64, '|': 0.34, '}': 0.64, '~': 0.84
+}
+
+
+# Thai and Lao write some vowels BEFORE the consonant they belong to: the break must not land
+# between them and the base that follows.
+LEADING_VOWELS = set(range(0x0E40, 0x0E45)) | set(range(0x0EC0, 0x0EC5))
+
+
+def _is_mark(ch: str) -> bool:
+ """A character that hangs off the one before it: a combining mark (any script) or one of the
+ Thai/Lao vowel signs and tone marks, which are Mn/Mc but carry no combining class."""
+ return unicodedata.combining(ch) != 0 or unicodedata.category(ch) in ("Mn", "Mc")
+
+
+def _char_em(ch: str) -> float:
+ # CJK punctuation and the fullwidth forms (、。,!? and U+FF01-FF60) are drawn on the same
+ # full-width grid as the ideographs they sit between, even though they are not "Han" to a
+ # script detector -- measuring them as Latin under-counts a wrapped CJK line by a character.
+ cp = ord(ch)
+ # A combining mark is drawn on top of (or under) its base and advances the pen by nothing:
+ # charging it a full em wrapped Thai and Devanagari lines far shorter than they needed to be.
+ if unicodedata.combining(ch) != 0 or unicodedata.category(ch) in ("Mn", "Cf"):
+ # "Cf" catches ZWJ/ZWNJ: an Indic joiner is orthography, and it advances the pen by
+ # nothing -- charging it a full em (it used to count as "emoji") shrank a Hindi line.
+ return 0.0
+ if 0x3000 <= cp <= 0x303F or 0xFF01 <= cp <= 0xFF60 or 0xFFE0 <= cp <= 0xFFE6:
+ return 1.0
+ script = char_script(ch)
+ if script == "emoji":
+ # 1.15: an emoji is drawn (or reserved) at a full em box, not at Latin's 0.57 -- counting
+ # it as Latin overflowed the safe area on an emoji-heavy line.
+ return 1.0
+ if script == "latin":
+ if ch in LATIN_EM:
+ return LATIN_EM[ch]
+ if ch.isupper() or ch.isdigit():
+ return 0.7
+ return 0.57
+ return ADVANCE_EM.get(script, 0.55)
+
+
+def text_width_em(text: str, emoji_em: float = 1.0) -> float:
+ """Width of `text` in em, from the per-script average advance table. `emoji_em` is what one
+ emoji cluster costs (--emoji-scale), so a wrap counts the box that will actually be drawn."""
+ total = 0.0
+ spans = {i: len(c) for i, c in emoji_clusters(text)}
+ i = 0
+ while i < len(text):
+ if i in spans:
+ total += emoji_em
+ i += spans[i]
+ continue
+ total += _char_em(text[i])
+ i += 1
+ return total
+
+
+def emoji_filter_chain(plan, base_label, out_label, first_input=1):
+ """(chains, inputs) that composite the planned PNGs on top of `base_label`.
+
+ `inputs` is a list of argv fragments, each ending in the asset path, to be appended to the
+ ffmpeg command in order (an overlay that fades needs `-loop 1` on its input so the still has
+ a timeline the fade filter can move along; one that does not is a plain `-i`).
+ """
+ overlays = plan.get("overlays") or []
+ if not overlays:
+ return [], []
+ # Group by everything that makes two uses of the same PNG a different STREAM: the fade is
+ # expressed in the cue's own timeline, so two cues cannot share one faded input.
+ def _key(o):
+ fades = (round(float(o.get("fade_in") or 0.0), 3), round(float(o.get("fade_out") or 0.0), 3))
+ window = (round(float(o["start"]), 3), round(float(o["end"]), 3)) if any(fades) else (None, None)
+ return (o["asset"], o["box"]) + fades + window
+
+ groups: "List[Tuple]" = []
+ for o in overlays:
+ if _key(o) not in groups:
+ groups.append(_key(o))
+ chains: List[str] = []
+ inputs: "List[List[str]]" = []
+ pads: "Dict[Tuple, List[str]]" = {}
+ for k, key in enumerate(groups):
+ asset, box, fin, fout, gstart, gend = key
+ uses = [o for o in overlays if _key(o) == key]
+ idx = first_input + k
+ labels = [f"e{k}_{j}" for j in range(len(uses))]
+ chain = f"[{idx}:v]format=rgba,scale={box}:{box}"
+ if fin or fout:
+ # -loop 1 gives the still an advancing timeline on the SAME clock as the main video,
+ # so the fade times below are the cue's own seconds. The emoji then appears and
+ # leaves with the text instead of popping in against a fading line.
+ # -t bounds the loop at the cue's end: an unbounded looped still never EOFs and the
+ # whole encode hangs (overlay keeps pulling from it after the main video is done).
+ inputs.append(["-loop", "1", "-t", f"{gend:.3f}", "-i", asset])
+ if fin:
+ chain += f",fade=t=in:st={gstart:.3f}:d={fin:.3f}:alpha=1"
+ if fout:
+ chain += f",fade=t=out:st={max(gstart, gend - fout):.3f}:d={fout:.3f}:alpha=1"
+ else:
+ inputs.append(["-i", asset])
+ if len(labels) > 1:
+ chain += f",split={len(labels)}"
+ chains.append(chain + "".join(f"[{l}]" for l in labels))
+ pads[key] = labels
+ cur = base_label
+ remaining = {key: list(v) for key, v in pads.items()}
+ for j, o in enumerate(overlays):
+ label = remaining[_key(o)].pop(0)
+ nxt = out_label if j == len(overlays) - 1 else f"eov{j}"
+ x = o["x"]
+ x = f"'{x}'" if isinstance(x, str) else x
+ # No eof_action=pass here: a PNG input is a SINGLE frame at pts 0, and eof_action=pass
+ # switches off overlay's default "hold the last frame of the secondary input", so the
+ # asset would be composited on frame 0 only and vanish for the rest of the cue (that is
+ # exactly what shipped first). eof_action=repeat (the default) holds the still for the
+ # whole timeline; enable= is what confines it to the cue's window.
+ chains.append(f"[{cur}][{label}]overlay=x={x}:y={o['y']}:"
+ f"enable='between(t,{o['start']:.3f},{o['end']:.3f})'[{nxt}]")
+ cur = nxt
+ return chains, inputs
+
+
+# --------------------------------------------------------------------------- shaping (1.15)
+# Scripts whose correct rendering needs harfbuzz-class reordering and re-clustering (Indic matras,
+# Thai/Lao mark stacking). drawtext does NOT use harfbuzz even in an --enable-libharfbuzz build, so
+# these come out wrong through drawtext on every build and must go through libass. Arabic and
+# Hebrew are NOT here: drawtext's text_shaping uses fribidi, which does bidi and Arabic joining
+# correctly -- they only join this set on a build compiled without fribidi.
+SHAPING_SCRIPTS = frozenset({"hi", "bn", "ta", "te", "kn", "ml", "gu", "pa", "si", "th", "lo", "km", "my"})
+
+
+BIDI_SCRIPTS = frozenset({"ar", "he"})
+
+
+_SHAPING_BUILD_CACHE: "Dict[str, bool]" = {}
+
+
+def drawtext_shaping() -> "Dict[str, bool]":
+ """Which shaping libraries THIS ffmpeg was built with, from -buildconf (falling back to the
+ `configuration:` line of -version). Cached per process."""
+ if _SHAPING_BUILD_CACHE:
+ return dict(_SHAPING_BUILD_CACHE)
+ text = ""
+ exe = shutil.which("ffmpeg")
+ if exe:
+ for flag in ("-buildconf", "-version"):
+ try:
+ proc = subprocess.run([exe, "-hide_banner", flag], stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT, text=True, timeout=10)
+ except (subprocess.TimeoutExpired, OSError):
+ break
+ if proc.returncode == 0 and proc.stdout.strip():
+ text = proc.stdout
+ break
+ _SHAPING_BUILD_CACHE.update({"fribidi": "--enable-libfribidi" in text,
+ "harfbuzz": "--enable-libharfbuzz" in text})
+ return dict(_SHAPING_BUILD_CACHE)
+
+
+def needs_shaping(script: str) -> bool:
+ """Whether drawtext would render `script` wrongly on this build."""
+ if script in SHAPING_SCRIPTS:
+ return True
+ return script in BIDI_SCRIPTS and not drawtext_shaping()["fribidi"]
+
+
+def font_family_of_file(path: str) -> "Optional[str]":
+ """The family name of a font FILE -- what libass wants, given a --font-file. `fc-scan` reads
+ the file directly; without fontconfig the file stem is the honest best guess."""
+ if not path or not os.path.isfile(path):
+ return None
+ exe = shutil.which("fc-scan")
+ if exe:
+ try:
+ proc = subprocess.run([exe, "--format", "%{family[0]}", path], stdout=subprocess.PIPE,
+ stderr=subprocess.DEVNULL, text=True, timeout=10)
+ if proc.returncode == 0 and proc.stdout.strip():
+ return proc.stdout.strip().splitlines()[0].strip()
+ except (subprocess.TimeoutExpired, OSError):
+ pass
+ return Path(path).stem
+
+
+def char_script(ch: str) -> str:
+ """The script of one character: one of SCRIPTS, or "latin" for anything else (including
+ digits, punctuation and spaces -- they are measured and wrapped like Latin)."""
+ cp = ord(ch)
+ # 1.15: an emoji cluster is not Latin. detect_script() skips "emoji" the way it skips "latin",
+ # so font resolution still follows the letters around it.
+ if _is_emoji_char(ch):
+ return "emoji"
+ for name, ranges in _SCRIPT_RANGES:
+ for lo, hi in ranges:
+ if lo <= cp <= hi:
+ return "ja" if name == "kana" else ("zh" if name == "han" else name)
+ return "latin"
+
+
+def detect_script(text: str, lang: "Optional[str]" = None) -> str:
+ """Which script `text` is written in, as one of SCRIPTS.
+
+ Hangul wins for Korean, any kana makes the whole string Japanese (Japanese mixes kana and
+ Han), Han alone is Chinese. Mixed text is decided by character count: the non-Latin script
+ with the most characters wins, ties going to whichever appeared first, and text with no
+ non-Latin characters at all is "latin". `lang` (a --lang/--language hint, or brand.json's
+ `lang`) only resolves the one ambiguity the characters genuinely cannot: Han with no kana
+ is Chinese by default but Japanese (or Korean hanja) when the caller says so.
+ """
+ counts: "Dict[str, int]" = {}
+ order: "List[str]" = []
+ kana = 0
+ for ch in text or "":
+ s = char_script(ch)
+ if s in ("latin", "emoji"):
+ continue
+ if ord(ch) in range(0x3040, 0x3100) or ord(ch) in range(0x31F0, 0x3200) or ord(ch) in range(0xFF66, 0xFFA0):
+ kana += 1
+ if s not in counts:
+ order.append(s)
+ counts[s] = counts.get(s, 0) + 1
+ if kana: # Japanese: the Han characters in the same string are Japanese too
+ counts["ja"] = counts.pop("ja", 0) + counts.pop("zh", 0)
+ order = [s for s in order if s != "zh"]
+ if not counts:
+ return "latin"
+ best = max(counts, key=lambda s: (counts[s], -order.index(s)))
+ hint = (lang or "").strip().lower().replace("_", "-").split("-")[0]
+ if not kana and best == "zh" and hint in ("ja", "zh", "ko"):
+ return hint # Han-only text: only the caller knows whether it is Chinese, Japanese or hanja
+ return best
+
+
+_SCRIPT_FONT_CACHE: "Dict[Tuple[str, Optional[str]], Optional[Tuple[str, str]]]" = {}
+
+
+def _fc_list_fonts(fc_lang: str) -> "Optional[List[Tuple[str, List[str]]]]":
+ """(file, families) for every font fontconfig says covers `fc_lang`.
+
+ `[]` means fontconfig answered and nothing covers the language; `None` means it could not be
+ asked at all (no `fc-list` on PATH, or it failed/timed out) -- the difference between
+ "missing" and "unknown", which the caller must not collapse: unknown is not a refusal.
+ """
+ exe = shutil.which("fc-list")
+ if not exe:
+ return None
+ try:
+ proc = subprocess.run([exe, f":lang={fc_lang}", "file", "family"],
+ stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
+ except (subprocess.TimeoutExpired, OSError):
+ return None
+ if proc.returncode != 0:
+ return None
+ out = []
+ for line in proc.stdout.splitlines():
+ if ": " not in line:
+ continue
+ path, _, families = line.partition(": ")
+ path = path.strip()
+ if not path or not os.path.exists(path):
+ continue
+ names = [f.replace("\\-", "-").strip() for f in families.split(",") if f.strip()]
+ out.append((path, names or [Path(path).stem]))
+ return out
+
+
+def _family_rank(families: "Sequence[str]", preferred: "Sequence[str]") -> int:
+ for i, want in enumerate(preferred):
+ w = want.lower()
+ if any(f.lower().startswith(w) for f in families):
+ return i
+ return len(preferred)
+
+
+def _script_font_entry(script: str, family_hint: "Optional[str]" = None) -> "Optional[Tuple[str, str]]":
+ key = (script, family_hint)
+ if key in _SCRIPT_FONT_CACHE:
+ return _SCRIPT_FONT_CACHE[key]
+ _SCRIPT_FONT_CACHE[key] = result = _script_font_uncached(script, family_hint)
+ return result
+
+
+FC_UNKNOWN = "unknown" # sentinel: fontconfig could not be asked (absent or failing), not "no font"
+
+
+def _script_font_uncached(script: str, family_hint: "Optional[str]" = None):
+ """(file, family), None when nothing covers `script`, or FC_UNKNOWN when it cannot be asked."""
+ if script not in FC_LANG:
+ return None
+ if platform.system() == "Windows":
+ fonts = Path(os.environ.get("WINDIR", "C:\\Windows")) / "Fonts"
+ for name, family in WINDOWS_FONTS.get(script, []):
+ if (fonts / name).exists():
+ return str(fonts / name), family
+ return None
+ preferred = list(PREFERRED_FAMILIES.get(script, []))
+ if family_hint:
+ preferred.insert(0, family_hint)
+ candidates = _fc_list_fonts(FC_LANG[script])
+ if candidates is None:
+ return FC_UNKNOWN
+ if not candidates:
+ return None
+ scored = []
+ for path, families in candidates:
+ joined = " ".join(families).lower()
+ stem = Path(path).stem.lower()
+ # "Unifont Sample" is fontconfig's tofu-with-hex-digits fallback: it "covers" every script
+ # by drawing the code point, which is exactly the unreadable result this feature exists to
+ # avoid -- it is only ever chosen when nothing else covers the script at all. A *Mono* face
+ # is legible but wrong for a caption band, so it sorts after every proportional one.
+ last_resort = 1 if "unifont" in joined else 0
+ mono = 1 if "mono" in joined else 0
+ # regular weights before Bold/Italic/Oblique cuts, so a default caption is not bold by accident
+ styled = 1 if any(k in stem for k in ("bold", "italic", "oblique", "light", "thin", "black")) else 0
+ scored.append((last_resort, _family_rank(families, preferred), mono, styled, path, families[0]))
+ scored.sort(key=lambda row: (row[0], row[1], row[2], row[3], row[4]))
+ best = scored[0]
+ return best[4], best[5]
+
+
+def font_for_script(script: str, family_hint: "Optional[str]" = None) -> "Optional[str]":
+ """A font FILE path that covers `script`, or None when this machine has none.
+
+ Linux/macOS ask fontconfig (`fc-list :lang=xx file family`) and rank what it reports by the
+ PREFERRED_FAMILIES table; Windows has no fontconfig, so the known system files are probed by
+ name. Cached per process: a caption job resolves the same script for every cue.
+ """
+ entry = _script_font_entry(script, family_hint)
+ return entry[0] if entry and entry is not FC_UNKNOWN else None
+
+
+def font_family_for_script(script: str, family_hint: "Optional[str]" = None) -> "Optional[str]":
+ """The family NAME of font_for_script()'s file -- what libass wants in an ASS Fontname."""
+ entry = _script_font_entry(script, family_hint)
+ return entry[1] if entry and entry is not FC_UNKNOWN else None
+
+
+def script_font_status(script: str) -> str:
+ """"available" (a font file covers `script`), "missing" (fontconfig answered, none does) or
+ "unknown" (there is no working fontconfig to ask). Only "missing" is a refusal."""
+ entry = _script_font_entry(script)
+ if entry is FC_UNKNOWN:
+ return "unknown"
+ return "available" if entry else "missing"
+
+
+def font_covers_script(font_name: str, script: str) -> bool:
+ """Whether the installed family `font_name` actually carries glyphs for `script`.
+
+ `fc-match` cannot answer this: given a family that IS installed it returns that family
+ whatever `:lang=` asks for (verified -- `fc-match "DejaVu Sans:lang=zh-cn"` answers
+ "DejaVu Sans", which has no Han glyphs at all). `fc-list :lang=xx:family=<name>` does: it
+ lists only files that satisfy BOTH, so an empty listing is the proof of no coverage. Unknown
+ (no fontconfig at all) counts as covering: a warning nobody can verify is worse than none.
+ """
+ if script not in FC_LANG or not font_name:
+ return True
+ exe = shutil.which("fc-list")
+ if not exe:
+ return True
+ try:
+ proc = subprocess.run([exe, f":lang={FC_LANG[script]}:family={font_name}", "file"],
+ stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
+ except (subprocess.TimeoutExpired, OSError):
+ return True
+ if proc.returncode != 0:
+ return True
+ return bool(proc.stdout.strip())
+
+
+# Named flags differ per tool: overlay.py and graphics.py take a font FILE, caption.py takes a
+# directory of faces plus the family name -- naming a flag the tool does not have is worse than
+# naming none, so the hint says both (review 10).
+FONT_FLAG_HINT = "pass a font file (--font-file on overlay.py/graphics.py, --fonts-dir with --font on caption.py)"
+
+
+FONT_INSTALL_HINT = ("install fonts-noto-cjk / fonts-noto-core (apt), "
+ "brew install --cask font-noto-sans-cjk / font-noto-sans-arabic (mac), or "
+ + FONT_FLAG_HINT)
+
+
+def fonts_dir_covers_script(fonts_dir: str, script: str) -> "Optional[bool]":
+ """Does any font under `fonts_dir` cover `script`? None when it cannot be checked.
+
+ `--fonts-dir` says "also look here", not "this exact face", so it must not switch the
+ coverage guarantee off. fontconfig's `fc-scan` reads the files directly (no cache, no
+ installed-font database), which is exactly the question: `%{lang}` lists the languages each
+ face claims.
+ """
+ if script not in FC_LANG or not fonts_dir or not os.path.isdir(fonts_dir):
+ return None
+ exe = shutil.which("fc-scan")
+ if not exe:
+ return None
+ try:
+ proc = subprocess.run([exe, "--format", "%{lang}\n", fonts_dir],
+ stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, timeout=10)
+ except (subprocess.TimeoutExpired, OSError):
+ return None
+ if proc.returncode != 0:
+ return None
+ want = FC_LANG[script].lower()
+ for line in proc.stdout.splitlines():
+ if want in [tag.strip().lower() for tag in line.split("|")]:
+ return True
+ return False
+
+
+def script_font_for_text(text: str, *, lang: "Optional[str]" = None, font: "Optional[str]" = None,
+ font_explicit: bool = False, font_file: "Optional[str]" = None,
+ fonts_dir: "Optional[str]" = None
+ ) -> "Tuple[str, Optional[str], Optional[str]]":
+ """(script, font file, family) to draw `text` with, resolving by script when nothing explicit
+ was asked for.
+
+ Returns (script, None, None) when the caller's own choice stands: Latin text, an explicit
+ --font-file, an explicit --font (which is kept even when fontconfig says it does not cover
+ the script -- with one info line saying so, because overriding a user's stated font silently
+ is worse than a warning), or a --fonts-dir that does carry the script. Otherwise the resolved
+ file is returned with ONE info line naming it.
+
+ A script fontconfig says nothing covers is a failed job (tofu is not a delivery). A machine
+ with no working fontconfig at all answers "unknown", not "missing": the job continues with
+ the caller's font -- libass and drawtext still have their own font backends -- and one info
+ line says the coverage could not be verified.
+ """
+ script = detect_script(text or "", lang)
+ if script == "latin":
+ return script, None, None
+ if font_file:
+ return script, None, None
+ if font_explicit and font:
+ if not font_covers_script(font, script):
+ info(f"font: '{font}' does not cover {LANGUAGE_NAMES[script]} text on this machine; keeping it as asked "
+ f"(drop --font, or {FONT_FLAG_HINT}, to pick one by script automatically)")
+ return script, None, None
+ if fonts_dir:
+ covered = fonts_dir_covers_script(fonts_dir, script)
+ if covered:
+ return script, None, None
+ if covered is None:
+ info(f"font: could not verify that {fonts_dir} covers {LANGUAGE_NAMES[script]} text "
+ "(no fc-scan on this machine); using it as given")
+ return script, None, None
+ info(f"font: no face in {fonts_dir} covers {LANGUAGE_NAMES[script]} text; "
+ "picking one by script instead (the directory is still searched first)")
+ entry = _script_font_entry(script)
+ if entry is FC_UNKNOWN:
+ info(f"font: could not verify that this machine can render {LANGUAGE_NAMES[script]} text "
+ "(no working fontconfig); rendering with the font as given -- "
+ "doctor --json .fonts.scripts reports what is known")
+ return script, None, None
+ if not entry:
+ die(f"no installed font covers {LANGUAGE_NAMES[script]} text on this machine — {FONT_INSTALL_HINT}", kind="input")
+ info(f"font: {entry[0]} (covers {script})")
+ return script, entry[0], entry[1]
+
+
+def escape_drawtext(text: str) -> str:
+ """Escape a FONT NAME for a single-quoted drawtext option value (`font='<this>'`).
+
+ Since 1.15 this is no longer the route for drawn TEXT -- use drawtext_text_opts(), which puts
+ the text in a file and keeps `\'` and `%` verbatim. It remains the escape for the font-name
+ fallback, where the value is a family name that never legitimately contains a quote or a
+ percent sign.
+
+ Every ffmpeg filter-graph special character (`\\ : % , [ ] ;`) needs a backslash escape
+ regardless of the surrounding quotes -- the graph parser still splits on an unescaped `,`/`;`
+ or ends an option list on an unescaped `:`/`[`/`]` even while "inside" a quoted value. The
+ quote character itself has no reliable backslash escape at all: `\\'` and the POSIX shell
+ close-insert-reopen trick both parse fine in a simple `-vf` chain but silently corrupt a
+ `-filter_complex` chain that uses explicit `[label]` pads (confirmed by rendering the result:
+ trailing option names leak into the picture as literal text). `%` has the same problem as far
+ as drawtext's own expansion scanner is concerned. Both are therefore dropped here rather than
+ escaped -- which is exactly why drawn text no longer comes through this function.
+ """
+ text = re.sub(r"[\x00-\x1f\x7f]", "", text)
+ return (
+ text.replace("'", "")
+ .replace("%", "")
+ .replace("\\", "\\\\")
+ .replace(":", "\\:")
+ .replace(",", "\\,")
+ .replace("[", "\\[")
+ .replace("]", "\\]")
+ .replace(";", "\\;")
+ )
+
+
+def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
+ """`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for
+ every character on every build shape this repo uses.
+
+ The filter-graph parser never sees the text at all: only the PATH is parsed, and
+ escape_filter_path() already handles that. `expansion=none` switches off drawtext's own
+ `%{...}` scanner, which is the reason `%` was unsafe (a bare `\%` logs "Stray %" on one build
+ and fails the whole filter chain on another). With the scanner off, `'`, `%`, `:`, `,`, `[`,
+ `]`, `;` and `\` all reach the picture verbatim -- 1.15 fixes `overlay.py --text "it's 100%
+ done"` losing both characters. Control characters are still stripped: a one-line burnt-in
+ label has no use for them.
+
+ The file is UTF-8, mode 0600, in a private per-run directory (see _drawtext_tmpdir) that is
+ removed when the process ends. It is *registered* here and written by run() only if the
+ command about to run actually names it, so --dry-run and the ASS route write nothing; a
+ printed plan therefore names a path that no longer exists once the run is over, which is the
+ same promise every other temp file in this skill makes.
+ """
+ cleaned = re.sub(r"[\x00-\x1f\x7f]", "", text or "")
+ import hashlib
+ name = "t_" + hashlib.sha256(cleaned.encode("utf-8")).hexdigest()[:16] + ".txt"
+ if tmpdir is None:
+ tmpdir = _drawtext_tmpdir(create=not STATE.dry_run)
+ path = os.path.join(tmpdir, name)
+ _DRAWTEXT_PENDING[path] = cleaned
+ return f"textfile={escape_filter_path(path)}:expansion=none"
diff --git a/tests/_fixtures.py b/tests/_fixtures.py
new file mode 100644
index 0000000..36bf7df
--- /dev/null
+++ b/tests/_fixtures.py
@@ -0,0 +1,324 @@
+#!/usr/bin/env python3
+"""Fixtures and helpers shared by the end-to-end test modules.
+
+The synthetic footage every tool is run against -- 12 s of testsrc2 + tones, a VFR clip, a rotated
+phone clip, 5.1 audio, 10-bit HDR10 HEVC, a drifting pair -- is expensive to build and identical
+for every group, so MediaFixtures builds it once per process and hands the same paths to each
+group's class. Import this module, not one of the test modules, from a new test file.
+"""
+import json
+import platform
+import re
+import os
+import shutil
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPTS = ROOT / "scripts"
+HERE = Path(__file__).resolve().parent
+OUT = Path(os.environ.get("OUT", ROOT / "tests" / "out"))
+sys.path.insert(0, str(SCRIPTS))
+sys.path.insert(0, str(HERE))
+
+TONES = ("0.6*sin(2*PI*440*t)*gt(sin(2*PI*0.37*t)\\,0.3)+0.4*sin(2*PI*880*t)*gt(sin(2*PI*0.53*t+1)\\,0.6)"
+ "+0.3*sin(2*PI*220*t)*gt(sin(2*PI*0.21*t+2)\\,0.7)")
+
+
+def sh(*cmd, expect_fail=False, env=None):
+ proc = subprocess.run([str(c) for c in cmd], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", env=env)
+ if expect_fail:
+ assert proc.returncode != 0, f"expected failure but succeeded: {cmd}"
+ return proc
+ assert proc.returncode == 0, f"{cmd}\nSTDOUT:\n{proc.stdout}\nSTDERR:\n{proc.stderr}"
+ return proc
+
+
+def png_size(path) -> tuple:
+ with open(path, "rb") as fh:
+ head = fh.read(24)
+ return int.from_bytes(head[16:20], "big"), int.from_bytes(head[20:24], "big")
+
+
+def script(name, *args, **kw):
+ return sh(sys.executable, SCRIPTS / name, *args, **kw)
+
+# ---------------------------------------------------------------------------- fonts by script (1.12)
+
+
+def _no_fontconfig():
+ """fc-list absent (a bare container, Windows) -- the script->font resolution cannot be
+ exercised, and skipping says so rather than failing on an environment gap."""
+ return shutil.which("fc-list") is None and platform.system() != "Windows"
+
+# ---------------------------------------------------------------------------- emoji + shaping (1.15)
+
+
+def _emoji_assets(names=("1f389", "1f44d", "1f1ef-1f1f5", "1f469-200d-1f4bb")):
+ """A directory of placeholder emoji PNGs drawn by ffmpeg at run time.
+
+ The package ships no emoji art on purpose: Twemoji is CC-BY 4.0 and Noto Emoji OFL/Apache-2.0,
+ and a test does not need to redistribute either. What --emoji-assets actually requires is the
+ NAMING (lowercase hex code points joined by '-'), which a coloured square proves exactly as
+ well as a real glyph.
+ """
+ d = OUT / "emoji_assets"
+ d.mkdir(parents=True, exist_ok=True)
+ for i, name in enumerate(names):
+ path = d / (name + ".png")
+ if not path.exists():
+ colour = ("orange", "gold", "tomato", "limegreen")[i % 4]
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi",
+ "-i", "color=c=%s:s=72x72:d=0.04" % colour, "-vf", "format=rgba",
+ "-frames:v", "1", str(path))
+ return d
+
+
+def _pixel_at(video, t, x, y):
+ """The RGB triple at (x, y) of the frame at `t` seconds of `video`."""
+ proc = subprocess.run(["ffmpeg", "-v", "error", "-ss", str(t), "-i", str(video), "-frames:v", "1",
+ "-f", "rawvideo", "-pix_fmt", "rgb24", "-"], stdout=subprocess.PIPE)
+ w = int(subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
+ "stream=width", "-of", "csv=p=0", str(video)],
+ stdout=subprocess.PIPE, text=True).stdout.strip())
+ off = (y * w + x) * 3
+ return tuple(proc.stdout[off:off + 3])
+
+
+def _ass_ink_columns(ass_path, w, h, threshold=60):
+ """The set of x columns that carry ink when `ass_path` is rendered over black at w x h."""
+ proc = subprocess.run(
+ ["ffmpeg", "-v", "error", "-f", "lavfi", "-i", "color=c=black:s=%dx%d:d=0.04" % (w, h),
+ "-vf", "ass=%s" % str(ass_path).replace("\\", "/"), "-frames:v", "1",
+ "-f", "rawvideo", "-pix_fmt", "gray", "-"], stdout=subprocess.PIPE)
+ data = proc.stdout
+ if len(data) < w * h:
+ return set()
+ return {x for x in range(w) if any(data[y * w + x] > threshold for y in range(h))}
+
+
+def _family_installed(family):
+ if not shutil.which("fc-list"):
+ return False
+ proc = subprocess.run(["fc-list", ":family=%s" % family, "file"], stdout=subprocess.PIPE, text=True)
+ return bool(proc.stdout.strip())
+
+
+def _ass_advance(family, body):
+ """x of the rightmost lit pixel of a left-anchored one-line ASS render, or None."""
+ W, H, FS = 900, 140, 60
+ path = OUT / "advance.ass"
+ path.write_text(
+ "[Script Info]\nScriptType: v4.00+\nPlayResX: %d\nPlayResY: %d\nWrapStyle: 2\n\n"
+ "[V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, "
+ "OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, "
+ "Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding\n"
+ "Style: D,%s,%d,&H00FFFFFF,&H00FFFFFF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,0,0,7,0,0,0,1\n\n"
+ "[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\n"
+ "Dialogue: 0,0:00:00.00,0:00:05.00,D,,0,0,0,,{\\pos(0,0)}%s\n" % (W, H, family, FS, body),
+ encoding="utf-8-sig")
+ proc = subprocess.run(
+ ["ffmpeg", "-v", "error", "-f", "lavfi", "-i", "color=c=black:s=%dx%d:d=0.04" % (W, H),
+ "-vf", "ass=%s" % str(path).replace("\\", "/"), "-frames:v", "1",
+ "-f", "rawvideo", "-pix_fmt", "gray", "-"], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ data = proc.stdout
+ if proc.returncode != 0 or len(data) < W * H:
+ return None
+ for x in range(W - 1, -1, -1):
+ if any(data[y * W + x] > 60 for y in range(H)):
+ return x
+ return None
+
+
+def _frame_ink(path):
+ proc = subprocess.run(["ffmpeg", "-v", "error", "-i", str(path), "-ss", "1", "-frames:v", "1",
+ "-f", "rawvideo", "-pix_fmt", "gray", "-"], stdout=subprocess.PIPE)
+ return sum(proc.stdout)
+
+
+def _families_for(script):
+ """Families fontconfig lists for `script`, or [] where there is no fontconfig to ask (Windows
+ resolves fonts by file name, so font_for_script() answers there without an fc-list on PATH --
+ shelling out unconditionally raised FileNotFoundError in CI)."""
+ from _common import FC_LANG
+ if not shutil.which("fc-list"):
+ return []
+ proc = subprocess.run(["fc-list", f":lang={FC_LANG[script]}", "family"], stdout=subprocess.PIPE, text=True)
+ return [f for line in proc.stdout.splitlines() for f in line.split(",")]
+# One build per process, not one per group: setUpClass runs for each of the six group classes and
+# the footage below takes the best part of a minute to encode. The first class through builds it
+# and records every attribute it set; the rest are handed the same paths.
+_BUILT = {}
+
+
+class MediaFixtures(unittest.TestCase):
+ """Base class for the end-to-end group tests: the shared footage and the shared assertions."""
+
+ @classmethod
+ def setUpClass(cls):
+ if not shutil.which("ffmpeg"):
+ # Locally a skip; in CI (GitHub sets CI=true) a missing ffmpeg is a broken install
+ # step and must fail, or a job with zero real tests reports green -- see
+ # test_contract.py's require_ffmpeg_or_skip for the incident this guards against.
+ if os.environ.get("CI"):
+ raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step, not a reason to skip")
+ raise unittest.SkipTest("ffmpeg not on PATH")
+ OUT.mkdir(parents=True, exist_ok=True)
+ if _BUILT:
+ for _name, _value in _BUILT.items():
+ setattr(cls, _name, _value)
+ return
+ _before = set(vars(cls))
+ cls.src = OUT / "source.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30",
+ "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000",
+ "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p",
+ "-c:a", "aac", "-b:a", "128k", cls.src)
+ cls.mic = OUT / "lavmic.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "2.5", "-i", cls.src, "-vn", "-c:a", "pcm_s16le", cls.mic)
+ cls.logo = OUT / "logo.png"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "[email protected]:s=240x90,format=rgba", "-frames:v", "1", cls.logo)
+ cls.cues = OUT / "cues.txt"
+ cls.cues.write_text("0:00-0:03 Hello world\n0:03-0:06 Second | line\nAuto timed cue\n", encoding="utf-8")
+
+ # --- "real world" material: VFR, rotated phone clip, 5.1 audio, 10-bit HDR10 HEVC, long drifting pair
+ cls.vfr = OUT / "vfr.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000",
+ "-t", "12", "-vf", "select='gt(random(1)\\,0.3)'", "-fps_mode", "vfr",
+ "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", cls.vfr)
+ cls.rot = OUT / "rot.mp4"
+ # -display_rotation arrived in FFmpeg 6.0; on 5.x the rotation is written the old way,
+ # as the stream's rotate tag, which every probe here reads the same. Only the fixture
+ # builder cares -- the tools under test never emit either.
+ if subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-display_rotation", "90", "-f", "lavfi", "-i", "color=c=black:s=16x16:d=0.1", "-f", "null", "-"],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE).returncode == 0:
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-display_rotation", "90", "-i", cls.src, "-t", "6", "-c", "copy", cls.rot)
+ else:
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", cls.src, "-t", "6", "-c", "copy", "-metadata:s:v:0", "rotate=90", cls.rot)
+ cls.surround = OUT / "surround.mov"
+ six = "|".join([TONES, TONES, "0.5*" + TONES, "0.2*sin(2*PI*60*t)", "0.3*" + TONES, "0.3*" + TONES])
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-f", "lavfi", "-i", f"aevalsrc='{six}':s=48000:c=5.1",
+ "-t", "6", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", "-ac", "6", cls.surround)
+ cls.hdr = OUT / "hdr10.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=1920x1080:rate=30", "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000",
+ "-t", "4", "-vf", "format=yuv420p10le", "-c:v", "libx265", "-preset", "ultrafast",
+ "-x265-params", "colorprim=bt2020:transfer=smpte2084:colormatrix=bt2020nc:log-level=error",
+ "-tag:v", "hvc1", "-c:a", "aac", cls.hdr)
+ cls.long_ref = OUT / "long_ref.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000", "-t", "200", "-c:a", "pcm_s16le", cls.long_ref)
+ cls.long_drift = OUT / "long_drift.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1.2", "-i", cls.long_ref,
+ "-af", "asetrate=48000*0.9995,aresample=48000", "-c:a", "pcm_s16le", cls.long_drift)
+ _BUILT.update({_name: getattr(cls, _name) for _name in set(vars(cls)) - _before})
+
+ def assertClose(self, a, b, tol, msg=""):
+ self.assertIsNotNone(a, msg)
+ self.assertLessEqual(abs(a - b), tol, f"{msg}: {a} vs {b} (tol {tol})")
+ # ------------------------------------------------- captions people can read (1.12)
+ def _small(self):
+ """A 640x360 clip: the wrap is computed from the real frame geometry, and a small frame
+ makes the safe-area limit bite at an ordinary caption size."""
+ small = OUT / "cap_small.mp4"
+ if not small.exists():
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi",
+ "-i", "testsrc2=size=640x360:rate=30", "-f", "lavfi", "-i", "sine=f=440",
+ "-t", "6", "-c:v", "libx264", "-preset", "veryfast", "-crf", "24",
+ "-pix_fmt", "yuv420p", "-c:a", "aac", small)
+ return small
+ @staticmethod
+ def _srt_cues(path):
+ blocks = [b for b in Path(path).read_text(encoding="utf-8").strip().split("\n\n") if b.strip()]
+ out = []
+ for b in blocks:
+ lines = b.splitlines()
+ out.append((lines[1], lines[2:]))
+ return out
+ def _band_luma(self, video, png):
+ """Mean luminance of the bottom quarter of a frame -- the caption band."""
+ script("look.py", video, "--at", "1", "-o", png, "--no-timecode")
+ raw = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(png),
+ "-vf", "crop=iw:ih/4:0:ih*3/4", "-f", "rawvideo", "-pix_fmt", "gray", "-"],
+ stdout=subprocess.PIPE).stdout
+ self.assertTrue(raw)
+ return sum(raw) / len(raw)
+ # ------------------------------------------------------------------ 1.13: the audio bed
+ def _audio_filters(self, *args):
+ """The filter graph audio.py plans, from --dry-run --json (no encode)."""
+ data = json.loads(script("audio.py", *args, "--dry-run", "--json").stdout)
+ cmd = next(c for c in data["commands"] if "-filter_complex" in c)
+ return cmd.split("-filter_complex ", 1)[1].split(" -map", 1)[0].strip("'"), data
+ def _side_peak_db(self, path):
+ """Peak level of the side signal (L-R) in dBFS; -inf (returned as -120) means the two
+ channels are identical, i.e. the file has no stereo image at all."""
+ proc = sh("ffmpeg", "-hide_banner", "-nostdin", "-i", str(path), "-af",
+ "pan=mono|c0=c0-c1,astats=measure_overall=Peak_level:measure_perchannel=none", "-f", "null", "-")
+ peak = re.search(r"Peak level dB: (-?[0-9.]+|-inf)", proc.stderr)
+ self.assertIsNotNone(peak, proc.stderr[-400:])
+ return -120.0 if peak.group(1) == "-inf" else float(peak.group(1))
+ def _proj(self, name, body):
+ p = OUT / name
+ p.write_text(json.dumps(dict({"output": name.replace(".json", ".mp4")}, **body)), encoding="utf-8")
+ return p
+ # ------------------------------------------------------- delivery templates (1.14)
+ def _region_stats(self, path, crop, at=1.0):
+ """Mean luma and spread of one region of a frame, as signalstats reports them."""
+ proc = sh("ffmpeg", "-hide_banner", "-loglevel", "error", "-ss", str(at), "-i", str(path), "-frames:v", "1",
+ "-vf", f"crop={crop},signalstats,metadata=print:file=-", "-f", "null", "-")
+ vals = {k: float(v) for k, v in re.findall(r"lavfi\.signalstats\.(YAVG|YMIN|YMAX)=([0-9.]+)", proc.stdout)}
+ return vals["YAVG"], vals["YMAX"] - vals["YMIN"]
+ # ---------------------------------------------------------------- help
+
+ # ------------------------------------------------------------------ audio: extraction, concat, precision, dynamics
+ @staticmethod
+ def _samples(path):
+ """(codec, sample_rate, duration_ts) of the first audio stream as ffprobe sees it."""
+ out = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "a:0", "-show_entries", "stream=codec_name,sample_rate,duration_ts",
+ "-of", "csv=p=0", str(path)], stdout=subprocess.PIPE, text=True, check=True).stdout.strip().split(",")
+ return out[0], int(out[1]), int(out[2])
+ @staticmethod
+ def _peak_rms(path):
+ proc = subprocess.run(["ffmpeg", "-hide_banner", "-i", str(path), "-af", "astats=measure_overall=Peak_level+RMS_level:measure_perchannel=none",
+ "-f", "null", "-"], stderr=subprocess.PIPE, text=True)
+ vals = dict(re.findall(r"(Peak level|RMS level) dB: (-?[\d.]+)", proc.stderr))
+ return float(vals["Peak level"]), float(vals["RMS level"])
+ # ------------------------------------------------------------------ FFmpeg 8+ / Windows compatibility
+ @staticmethod
+ def _frame_count(path):
+ proc = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-count_packets", "-show_entries", "stream=nb_read_packets", "-of", "csv=p=0", str(path)],
+ stdout=subprocess.PIPE, text=True)
+ return int(proc.stdout.strip())
+ @staticmethod
+ def _psnr(a, b):
+ """Average PSNR of b against a (dB); lower means the picture changed more. inf when identical."""
+ # Two things make this compare pixels and nothing else. (1) Both inputs are re-stamped by
+ # frame *number*, so the psnr filter (which pairs frames by timestamp) never compares a
+ # frame with its neighbour; frame *count* equality is asserted separately by the callers
+ # that care, so a genuinely dropped frame still fails. (2) Both inputs get the *same*
+ # colour tags before psnr. From FFmpeg 7.1 libavfilter negotiates colourspace, and psnr
+ # on an untagged source vs a bt709-tagged output auto-inserts a real bt709->bt601
+ # conversion on one side (8.x: 26 dB for a byte-identical picture) -- and, worse, hides
+ # an encode-time conversion by undoing it (8.x reported 40 dB for an output whose pixels
+ # had been re-matrixed, which is how the 7.1+ -colorspace bug in #156 went unnoticed on
+ # macOS). With the tags pinned identical, every build from 5.1 to 8.1 reports the same
+ # number for the same two files.
+ same = "setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv"
+ proc = subprocess.run(["ffmpeg", "-hide_banner", "-i", str(a), "-i", str(b), "-lavfi",
+ f"[0:v]setpts=N/FRAME_RATE/TB,{same}[a];[1:v]setpts=N/FRAME_RATE/TB,{same}[b];[a][b]psnr", "-f", "null", "-"],
+ stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace")
+ m = re.search(r"average:(inf|[\d.]+)", proc.stderr)
+ assert m, proc.stderr[-400:]
+ return float("inf") if m.group(1) == "inf" else float(m.group(1))
+ @staticmethod
+ def _any_ttf():
+ for root in ("/usr/share/fonts", "/usr/local/share/fonts", "/Library/Fonts", "/System/Library/Fonts", "C:/Windows/Fonts"):
+ for pat in ("**/DejaVuSans.ttf", "**/Arial.ttf", "**/arial.ttf", "**/*.ttf"):
+ hits = list(Path(root).glob(pat)) if Path(root).exists() else []
+ if hits:
+ return hits[0]
+ return None
diff --git a/tests/release_check.sh b/tests/release_check.sh
index 883d7d3..e538a2a 100755
--- a/tests/release_check.sh
+++ b/tests/release_check.sh
@@ -18,7 +18,7 @@ echo "== 1. pack contents"
npm pack --pack-destination "$TMP" >/dev/null 2>&1
TGZ="$(ls "$TMP"/*.tgz)"
LIST="$(tar -tzf "$TGZ")"
-for need in package/SKILL.md package/scripts/_common.py package/scripts/_contract.py package/scripts/probe.py package/references/scripts.md package/references/devices.md package/mcp/server.py package/bin/install.js; do
+for need in package/SKILL.md package/scripts/_common/__init__.py package/scripts/_contract.py package/scripts/probe.py package/references/scripts.md package/references/devices.md package/mcp/server.py package/bin/install.js; do
echo "$LIST" | grep -qx "$need" || { echo "FAIL: $need missing from the package"; exit 1; }
done
echo " ok ($(echo "$LIST" | wc -l | tr -d ' ') files)"
@@ -33,8 +33,9 @@ done
echo " ok"
echo "== 3. every script answers --help"
+# _common was the one file here with no --help; it is a package directory since the refactor
+# after 1.15.0, which scripts/*.py does not match, so every file this glob finds answers --help.
for f in "$TMP"/home/.claude/skills/ffmpeg-skill/scripts/*.py; do
- case "$(basename "$f")" in _common.py) continue;; esac
python3 "$f" --help >/dev/null 2>&1 || { echo "FAIL: $(basename "$f") --help"; exit 1; }
done
echo " ok"
diff --git a/tests/test_all.py b/tests/test_all.py
index 260d932..6839778 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -2,5572 +2,35 @@
"""End-to-end tests: build synthetic footage, run every script, verify with probe.
python3 tests/test_all.py # or: python3 -m unittest tests/test_all.py
+
+The cases themselves live one module per tool group -- test_analysis, test_editing, test_audio,
+test_picture, test_delivery, test_orchestration -- over the fixtures in _fixtures.py. This file
+imports all six so that the entry point every CI job, npm test and release_check.sh already runs
+keeps running exactly the same set; each group module is also runnable on its own.
"""
-import contextlib
-import io
-import json
-import platform
-import re
-import os
-import shutil
-import subprocess
import sys
import unittest
from pathlib import Path
-ROOT = Path(__file__).resolve().parent.parent
-SCRIPTS = ROOT / "scripts"
-OUT = Path(os.environ.get("OUT", ROOT / "tests" / "out"))
-sys.path.insert(0, str(SCRIPTS))
-from _common import default_font_file, detect_script, font_for_script, font_family_for_script, escape_drawtext, escape_filter_path, probe, shell_quote # noqa: E402
-
-TONES = ("0.6*sin(2*PI*440*t)*gt(sin(2*PI*0.37*t)\\,0.3)+0.4*sin(2*PI*880*t)*gt(sin(2*PI*0.53*t+1)\\,0.6)"
- "+0.3*sin(2*PI*220*t)*gt(sin(2*PI*0.21*t+2)\\,0.7)")
-
-
-def sh(*cmd, expect_fail=False, env=None):
- proc = subprocess.run([str(c) for c in cmd], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", env=env)
- if expect_fail:
- assert proc.returncode != 0, f"expected failure but succeeded: {cmd}"
- return proc
- assert proc.returncode == 0, f"{cmd}\nSTDOUT:\n{proc.stdout}\nSTDERR:\n{proc.stderr}"
- return proc
-
-
-def png_size(path) -> tuple:
- with open(path, "rb") as fh:
- head = fh.read(24)
- return int.from_bytes(head[16:20], "big"), int.from_bytes(head[20:24], "big")
-
-
-def script(name, *args, **kw):
- return sh(sys.executable, SCRIPTS / name, *args, **kw)
-
-
-class FFmpegSkillTests(unittest.TestCase):
- @classmethod
- def setUpClass(cls):
- if not shutil.which("ffmpeg"):
- # Locally a skip; in CI (GitHub sets CI=true) a missing ffmpeg is a broken install
- # step and must fail, or a job with zero real tests reports green -- see
- # test_contract.py's require_ffmpeg_or_skip for the incident this guards against.
- if os.environ.get("CI"):
- raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step, not a reason to skip")
- raise unittest.SkipTest("ffmpeg not on PATH")
- OUT.mkdir(parents=True, exist_ok=True)
- cls.src = OUT / "source.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30",
- "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000",
- "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p",
- "-c:a", "aac", "-b:a", "128k", cls.src)
- cls.mic = OUT / "lavmic.wav"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "2.5", "-i", cls.src, "-vn", "-c:a", "pcm_s16le", cls.mic)
- cls.logo = OUT / "logo.png"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "[email protected]:s=240x90,format=rgba", "-frames:v", "1", cls.logo)
- cls.cues = OUT / "cues.txt"
- cls.cues.write_text("0:00-0:03 Hello world\n0:03-0:06 Second | line\nAuto timed cue\n", encoding="utf-8")
-
- # --- "real world" material: VFR, rotated phone clip, 5.1 audio, 10-bit HDR10 HEVC, long drifting pair
- cls.vfr = OUT / "vfr.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000",
- "-t", "12", "-vf", "select='gt(random(1)\\,0.3)'", "-fps_mode", "vfr",
- "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", cls.vfr)
- cls.rot = OUT / "rot.mp4"
- # -display_rotation arrived in FFmpeg 6.0; on 5.x the rotation is written the old way,
- # as the stream's rotate tag, which every probe here reads the same. Only the fixture
- # builder cares -- the tools under test never emit either.
- if subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-display_rotation", "90", "-f", "lavfi", "-i", "color=c=black:s=16x16:d=0.1", "-f", "null", "-"],
- stdout=subprocess.PIPE, stderr=subprocess.PIPE).returncode == 0:
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-display_rotation", "90", "-i", cls.src, "-t", "6", "-c", "copy", cls.rot)
- else:
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", cls.src, "-t", "6", "-c", "copy", "-metadata:s:v:0", "rotate=90", cls.rot)
- cls.surround = OUT / "surround.mov"
- six = "|".join([TONES, TONES, "0.5*" + TONES, "0.2*sin(2*PI*60*t)", "0.3*" + TONES, "0.3*" + TONES])
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-f", "lavfi", "-i", f"aevalsrc='{six}':s=48000:c=5.1",
- "-t", "6", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", "-ac", "6", cls.surround)
- cls.hdr = OUT / "hdr10.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "testsrc2=size=1920x1080:rate=30", "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000",
- "-t", "4", "-vf", "format=yuv420p10le", "-c:v", "libx265", "-preset", "ultrafast",
- "-x265-params", "colorprim=bt2020:transfer=smpte2084:colormatrix=bt2020nc:log-level=error",
- "-tag:v", "hvc1", "-c:a", "aac", cls.hdr)
- cls.long_ref = OUT / "long_ref.wav"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000", "-t", "200", "-c:a", "pcm_s16le", cls.long_ref)
- cls.long_drift = OUT / "long_drift.wav"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1.2", "-i", cls.long_ref,
- "-af", "asetrate=48000*0.9995,aresample=48000", "-c:a", "pcm_s16le", cls.long_drift)
-
- def assertClose(self, a, b, tol, msg=""):
- self.assertIsNotNone(a, msg)
- self.assertLessEqual(abs(a - b), tol, f"{msg}: {a} vs {b} (tol {tol})")
-
- # ---------------------------------------------------------------- probe
- def test_probe_json_and_fields(self):
- out = script("probe.py", self.src).stdout
- data = json.loads(out)
- self.assertClose(data["duration"], 12.0, 0.1)
- self.assertEqual((data["video"]["width"], data["video"]["height"]), (1280, 720))
- self.assertClose(data["video"]["fps"], 30.0, 0.01)
- self.assertEqual(data["video"]["codec"], "h264")
- self.assertEqual(data["audio"]["channels"], 1)
- self.assertEqual(data["audio"]["sample_rate"], 48000)
- field = script("probe.py", self.src, "--field", "video.width").stdout.strip()
- self.assertEqual(field, "1280")
- compact = script("probe.py", self.src, "--compact").stdout
- self.assertIn("1280x720", compact)
-
- def test_probe_accepts_common_flags(self):
- out = script("probe.py", self.src, "--json", "--field", "duration").stdout.strip()
- self.assertClose(float(out), 12.0, 0.1)
-
- def test_probe_missing_file_fails(self):
- proc = script("probe.py", OUT / "nope.mp4", expect_fail=True)
- self.assertIn("not found", proc.stderr)
-
- # ---------------------------------------------------------------- cut
- def test_cut_single_copy(self):
- out = OUT / "cut1.mp4"
- script("cut.py", self.src, "--start", "2", "--end", "6", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 4.0, 0.5, "lossless cut falls back to re-encode when the keyframe snap is too far")
- self.assertEqual(m["video"]["codec"], "h264")
-
- def test_cut_copy_never_reencodes_when_tolerance_disabled(self):
- out = OUT / "cut3.mp4"
- proc = script("cut.py", self.src, "--start", "2", "--end", "6", "--tolerance", "-1", "-o", out)
- self.assertIn("lossless stream copy", proc.stderr)
-
- def test_cut_segments_accurate(self):
- out = OUT / "cut2.mp4"
- script("cut.py", self.src, "--segments", "1-3,6-9", "--accurate", "-o", out)
- self.assertClose(probe(str(out))["duration"], 5.0, 0.15)
-
- def test_cut_json_reports_requested_vs_actual_and_mode(self):
- # exact-second cut on a keyframe-aligned GOP: expect a clean lossless copy
- out = OUT / "cut_honest_copy.mp4"
- data = json.loads(script("cut.py", self.src, "--start", "2", "--end", "6", "--tolerance", "-1", "-o", out, "--json").stdout)
- self.assertEqual(data["mode"], "copy")
- self.assertTrue(data["keyframe_snapped"])
- self.assertEqual(data["requested_start"], 2.0)
- self.assertEqual(data["requested_end"], 6.0)
- self.assertEqual(data["requested_duration"], 4.0)
- self.assertAlmostEqual(data["output_duration"], probe(str(out))["duration"], places=2)
- self.assertAlmostEqual(data["duration_delta_seconds"], data["duration_error_ms"] / 1000, places=6)
-
- # --accurate: forced re-encode, never "hybrid"
- out2 = OUT / "cut_honest_accurate.mp4"
- data2 = json.loads(script("cut.py", self.src, "--start", "2", "--end", "6", "--accurate", "-o", out2, "--json").stdout)
- self.assertEqual(data2["mode"], "accurate")
- self.assertFalse(data2["keyframe_snapped"])
-
- # a start/end that doesn't land on a keyframe, with a tight tolerance, must silently
- # upgrade from copy to re-encode -- and say "hybrid", not just "reencoded: true"
- out3 = OUT / "cut_honest_hybrid.mp4"
- data3 = json.loads(script("cut.py", self.src, "--start", "1.13", "--end", "5.71", "--tolerance", "0.02", "-o", out3, "--json").stdout)
- self.assertTrue(data3["reencoded"])
- self.assertEqual(data3["mode"], "hybrid")
- self.assertFalse(data3["keyframe_snapped"])
- # ...and name the keyframes a lossless cut could have used instead (x264's default GOP on the
- # fixture puts the only one within 5 s of 1.13 at 0.0)
- self.assertTrue(data3["nearest_keyframes"], data3)
- self.assertIn(0.0, data3["nearest_keyframes"])
- self.assertIsNone(data["nearest_keyframes"], "a clean copy has no alternative to offer")
-
- # multi-segment: requested_start/end are None, requested_segments lists each range
- out4 = OUT / "cut_honest_segments.mp4"
- data4 = json.loads(script("cut.py", self.src, "--segments", "1-3,6-9", "--accurate", "-o", out4, "--json").stdout)
- self.assertIsNone(data4["requested_start"])
- self.assertIsNone(data4["requested_end"])
- self.assertEqual(data4["requested_segments"], [[1.0, 3.0], [6.0, 9.0]])
- self.assertEqual(data4["requested_duration"], 5.0)
-
- def test_cut_copy_keyframe_snap_reports_a_real_nonzero_delta(self):
- """Pins the actual failure mode `mode`/`keyframe_snapped`/`duration_delta_seconds` exist to
- surface: a non-keyframe-aligned request that stays within --tolerance keeps the fast
- stream copy (mode=copy) rather than upgrading to hybrid, but the copy still snapped to an
- earlier keyframe and pulled in extra content -- output_duration and requested_duration
- genuinely diverge, and a caller must be told this happened, not left to assume the file
- starts exactly where it asked."""
- out = OUT / "cut_copy_keyframe_snap.mp4"
- data = json.loads(script("cut.py", self.src, "--start", "1.13", "--end", "5.71", "--tolerance", "2.0", "-o", out, "--json").stdout)
- self.assertEqual(data["mode"], "copy")
- self.assertTrue(data["keyframe_snapped"])
- self.assertFalse(data["reencoded"])
- actual = probe(str(out))["duration"]
- self.assertAlmostEqual(data["output_duration"], actual, places=2)
- self.assertGreater(abs(data["duration_delta_seconds"]), 0.05, "this scenario must produce a real, visible divergence, not a rounding artefact")
- self.assertAlmostEqual(data["duration_delta_seconds"], data["output_duration"] - data["requested_duration"], places=6)
-
- def test_cut_bad_range_fails(self):
- script("cut.py", self.src, "--start", "5", "--end", "2", expect_fail=True)
-
- def test_cut_refuses_negative_start_and_end(self):
- """Unlike freeze.py/background.py, which explicitly refuse negative durations, cut.py
- passed --start/--end straight through to parse_time() with no sign check at all, so a
- negative value (e.g. from an agent computing an offset that went wrong) reached ffmpeg's
- -ss as -5.000000 instead of being refused with a clear error naming the flag."""
- proc = script("cut.py", self.src, "--start", "-5", "--end", "2", expect_fail=True)
- self.assertIn("--start", proc.stderr)
- proc = script("cut.py", self.src, "--start", "0", "--end", "-2", expect_fail=True)
- self.assertIn("--end", proc.stderr)
-
- # ---------------------------------------------------------------- fit
- def test_fit_duration_speed_and_aspect_pad(self):
- out = OUT / "fit1.mp4"
- script("fit.py", self.src, "--duration", "6", "--aspect", "9:16", "--fit", "pad", "--width", "540", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 6.0, 0.15)
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (540, 960))
-
- def test_broll_cutaway_shows_b_in_the_window_and_keeps_a_elsewhere(self):
- """#141: broll.py shows B's picture over A for a window and returns to A at A's own time;
- the output is exactly A's length. Checked frame by frame: inside the window a frame
- matches B (at --from + offset) and not A; outside it matches A. --audio a stream-copies
- A's audio; two cutaways in one call; overlapping or past-the-end windows are refused."""
- def frame_luma(path, t):
- proc = sh("ffmpeg", "-hide_banner", "-loglevel", "error", "-ss", str(t), "-i", path, "-frames:v", "1",
- "-vf", "signalstats,metadata=print:file=-", "-f", "null", "-")
- return float(re.search(r"lavfi\.signalstats\.YAVG=([0-9.]+)", proc.stdout).group(1))
- b = OUT / "broll_b.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "smptebars=size=960x540:rate=25:d=8",
- "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=48000:duration=8", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", b)
- out = OUT / "broll_out.mp4"
- data = json.loads(script("broll.py", self.src, "--insert", b, "--at", "4", "--end", "7", "--from", "1", "--fast", "--json", "-o", out).stdout)
- # --pad-color is spliced into the filter graph like every other colour flag, so it is validated like them
- inj = script("broll.py", self.src, "--insert", b, "--at", "4", "--end", "7", "--pad-color", "black,drawtext=text=INJECTED",
- "--json", "-o", OUT / "broll_inj.mp4", expect_fail=True)
- self.assertIn("plain colour", json.loads(inj.stdout)["error"]["message"])
- self.assertEqual(json.loads(inj.stdout)["commands"], [], "refused before ffmpeg ran")
- self.assertEqual(data["cutaways"], [{"insert": str(b), "at": 4.0, "end": 7.0, "from": 1.0}])
- m = probe(str(out))
- self.assertClose(m["duration"], probe(str(self.src))["duration"], 0.1)
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
- self.assertEqual(m["audio"]["codec"], probe(str(self.src))["audio"]["codec"], "--audio a stream-copies A's audio")
- inside_out, inside_b, inside_a = frame_luma(str(out), 5.5), frame_luma(str(b), 2.5), frame_luma(str(self.src), 5.5)
- self.assertLess(abs(inside_out - inside_b), 6, f"inside the window the frame must be B's: out {inside_out} b {inside_b} a {inside_a}")
- self.assertGreater(abs(inside_out - inside_a), 6, "inside the window the frame must not be A's")
- for t in (2.0, 9.0):
- self.assertLess(abs(frame_luma(str(out), t) - frame_luma(str(self.src), t)), 3, f"outside the window ({t}s) A must show unchanged")
- # two cutaways, B's audio mixed in, per-cutaway durations
- out2 = OUT / "broll_out2.mp4"
- script("broll.py", self.src, "--insert", b, "--at", "1", "--duration", "2", "--insert", b, "--at", "8", "--duration", "3", "--audio", "mix", "--fast", "-o", out2)
- m2 = probe(str(out2))
- self.assertClose(m2["duration"], 12.0, 0.1)
- self.assertEqual(m2["audio"]["codec"], "aac")
- self.assertLess(abs(frame_luma(str(out2), 9.5) - frame_luma(str(b), 1.5)), 6)
- # refusals: overlap, past the end, B too short, missing --at
- script("broll.py", self.src, "--insert", b, "--at", "1", "--duration", "3", "--insert", b, "--at", "2", "-o", OUT / "broll_bad1.mp4", expect_fail=True)
- script("broll.py", self.src, "--insert", b, "--at", "10", "--duration", "5", "-o", OUT / "broll_bad2.mp4", expect_fail=True)
- script("broll.py", self.src, "--insert", b, "--at", "1", "--duration", "5", "--from", "5", "-o", OUT / "broll_bad3.mp4", expect_fail=True)
- script("broll.py", self.src, "--insert", b, "--insert", b, "--at", "1", "-o", OUT / "broll_bad4.mp4", expect_fail=True)
- dry = OUT / "broll_dry.mp4"
- script("broll.py", self.src, "--insert", b, "--at", "4", "--dry-run", "-o", dry)
- self.assertFalse(dry.exists())
-
- def test_metadata_writes_chapters_and_tags_with_streams_copied(self):
- """#140: metadata.py writes container chapter markers from a `TIME TITLE` file and the
- common tags, with every stream copied bit for bit; probe reports both back. Chapters on a
- container that cannot hold them are refused, --clear-chapters removes them, a chapter
- past the end or out of order is refused, and the input is never rewritten in place."""
- chapters = OUT / "chapters.txt"
- chapters.write_text("# episode\n0:00 Intro\n4 Setup, with a comma; and =signs\n0:08 Outro\n", encoding="utf-8")
- out = OUT / "meta_chapters.mp4"
- data = json.loads(script("metadata.py", self.src, "--chapters", chapters, "--title", "Episode 12", "--artist", "Studio", "--comment", "final", "--json", "-o", out).stdout)
- self.assertTrue(data["streams_copied"])
- m = probe(str(out))
- self.assertEqual([(round(c["start"]), round(c["end"]), c["title"]) for c in m["chapters"]],
- [(0, 4, "Intro"), (4, 8, "Setup, with a comma; and =signs"), (8, 12, "Outro")])
- self.assertEqual(m["tags"].get("title"), "Episode 12")
- self.assertEqual(m["tags"].get("artist"), "Studio")
- self.assertEqual(m["tags"].get("comment"), "final")
- src = probe(str(self.src))
- self.assertEqual((m["video"]["codec"], m["audio"]["codec"]), (src["video"]["codec"], src["audio"]["codec"]))
- self.assertEqual(self._frame_count(out), self._frame_count(self.src))
- self.assertEqual(self._psnr(self.src, out), float("inf"), "streams must be copied, not re-encoded")
- # tags alone keep the chapters; --clear-chapters removes them and keeps the tags
- tagged = OUT / "meta_tagged.mp4"
- script("metadata.py", out, "--comment", "v2", "-o", tagged)
- self.assertEqual(len(probe(str(tagged))["chapters"]), 3)
- self.assertEqual(probe(str(tagged))["tags"].get("comment"), "v2")
- cleared = OUT / "meta_cleared.mp4"
- script("metadata.py", out, "--clear-chapters", "-o", cleared)
- self.assertEqual(probe(str(cleared))["chapters"], [])
- self.assertEqual(probe(str(cleared))["tags"].get("title"), "Episode 12")
- # refusals
- script("metadata.py", OUT / "long_ref.wav", "--chapters", chapters, "-o", OUT / "meta_bad.wav", expect_fail=True)
- script("metadata.py", self.src, "-o", OUT / "meta_nothing.mp4", expect_fail=True)
- script("metadata.py", self.src, "--title", "x", "-o", self.src, expect_fail=True)
- bad = OUT / "chapters_bad.txt"
- bad.write_text("0:00 A\n0:30 B\n", encoding="utf-8")
- script("metadata.py", self.src, "--chapters", bad, "-o", OUT / "meta_bad2.mp4", expect_fail=True)
- bad.write_text("0:05 A\n0:02 B\n", encoding="utf-8")
- script("metadata.py", self.src, "--chapters", bad, "-o", OUT / "meta_bad3.mp4", expect_fail=True)
- # dry run writes nothing
- dry = OUT / "meta_dry.mp4"
- script("metadata.py", self.src, "--chapters", chapters, "--dry-run", "-o", dry)
- self.assertFalse(dry.exists())
-
- def test_fit_pad_fill_blur_puts_picture_in_the_bars_and_color_stays_solid(self):
- """#139: --fit pad --pad-fill blur fills the letterbox/pillarbox bars with a blurred,
- scaled-to-cover copy of the frame (the phone-editor "make it vertical" look) instead of a
- solid --pad-color. The source is landscape, so 9:16 gives bars above and below: with
- blur they must carry picture (not black, not one flat value), with color (the default)
- they must stay the solid pad colour exactly as before. export.py shares the same path."""
- def bar_stats(path, top_px=60):
- # mean and spread of the top bar's luma over a frame at t=1s
- proc = sh("ffmpeg", "-hide_banner", "-loglevel", "error", "-ss", "1", "-i", path, "-frames:v", "1",
- "-vf", f"crop=iw:{top_px}:0:0,signalstats,metadata=print:file=-", "-f", "null", "-")
- vals = {k: float(v) for k, v in re.findall(r"lavfi\.signalstats\.(YAVG|YMIN|YMAX)=([0-9.]+)", proc.stdout)}
- return vals["YAVG"], vals["YMAX"] - vals["YMIN"]
- blur = OUT / "fit_pad_blur.mp4"
- script("fit.py", self.src, "--duration", "3", "--aspect", "9:16", "--fit", "pad", "--pad-fill", "blur", "--width", "360", "--fast", "-o", blur)
- m = probe(str(blur))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (360, 640))
- avg, spread = bar_stats(str(blur))
- self.assertGreater(avg, 20, f"blurred bar is (nearly) black: YAVG {avg}")
- self.assertGreater(spread, 10, f"blurred bar is flat: spread {spread}")
- solid = OUT / "fit_pad_color.mp4"
- script("fit.py", self.src, "--duration", "3", "--aspect", "9:16", "--fit", "pad", "--width", "360", "--fast", "-o", solid)
- avg, spread = bar_stats(str(solid))
- self.assertLess(avg, 20, f"solid black bar is not black: YAVG {avg}")
- self.assertLess(spread, 4, f"solid bar is not flat: spread {spread}")
- # the same option on export.py's preset frame
- exp = OUT / "export_pad_blur.mp4"
- script("export.py", self.src, "--preset", "reels", "--pad-fill", "blur", "--fast", "-o", exp)
- avg, spread = bar_stats(str(exp), 120)
- self.assertGreater(avg, 20); self.assertGreater(spread, 10)
- script("fit.py", self.src, "--aspect", "9:16", "--pad-fill", "blur", "--pad-blur", "0", "--dry-run", expect_fail=True)
-
- def test_fit_trim_and_crop_square(self):
- out = OUT / "fit2.mp4"
- script("fit.py", self.src, "--duration", "4", "--method", "trim", "--from-center", "--aspect", "1:1", "--fit", "crop", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 4.0, 0.15)
- self.assertEqual(m["video"]["width"], m["video"]["height"])
-
- def test_fit_aspect_only_never_upscales_past_source_resolution(self):
- """With only --aspect given (no --width/--height), the "elif ratio and src_ratio" branch
- used to bound a narrower/taller target by the source's WIDTH, not its height -- so a
- 1280x720 (16:9) source asked for 9:16 came out 1280x2276, a ~3.16x unrequested upscale in
- both fit=pad and fit=crop. Neither dimension of the output should exceed the source's."""
- out = OUT / "fit_aspect_only_tall.mp4"
- script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--fast", "-o", out)
- m = probe(str(out))
- self.assertLessEqual(m["video"]["width"], 1280)
- self.assertLessEqual(m["video"]["height"], 720)
- self.assertEqual(m["video"]["height"], 720, "bounded by source height, not blown up")
-
- def test_fit_refuses_extreme_speed(self):
- script("fit.py", self.src, "--duration", "1", expect_fail=True)
-
- def test_fit_crop_anchor_keeps_a_chosen_edge_not_just_the_centre(self):
- """A centre crop can cut a subject held to one side; --crop-x/-y say what to keep."""
- left = OUT / "fit_crop_left.mp4"
- right = OUT / "fit_crop_right.mp4"
- center = OUT / "fit_crop_center.mp4"
- script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--width", "360", "--crop-x", "0", "-o", left)
- script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--width", "360", "--crop-x", "1", "-o", right)
- script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--width", "360", "-o", center)
- for out in (left, right, center):
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (360, 640))
- # different horizontal anchors must crop different content, not just resize the same crop
- self.assertLess(self._psnr(left, right), 40, "crop-x=0 vs crop-x=1 kept the same picture")
-
- def test_fit_crop_anchor_out_of_range_is_refused(self):
- script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--crop-x", "1.5", expect_fail=True)
- script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--crop-y", "-0.1", expect_fail=True)
-
- def test_fit_height_alone_follows_source_aspect(self):
- out = OUT / "fit_h.mp4"
- script("fit.py", self.src, "--height", "480", "-o", out)
- m = probe(str(out))
- # source is 1280x720 (16:9); height 480 -> width 853.33 rounds to even 854
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (854, 480))
-
- def test_fit_width_and_height_both_given_is_exact(self):
- out = OUT / "fit_wh.mp4"
- script("fit.py", self.src, "--width", "500", "--height", "500", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (500, 500))
-
- def test_fit_width_alone_still_works(self):
- out = OUT / "fit_w.mp4"
- script("fit.py", self.src, "--width", "640", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
-
- def test_fit_rotate_90_swaps_dimensions(self):
- out = OUT / "fit_rot90.mp4"
- script("fit.py", self.src, "--rotate", "90", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (720, 1280))
-
- def test_fit_rotate_and_flip_change_actual_pixels(self):
- """Not just that dimensions are right -- a known left/right split must actually swap or rotate."""
- quad = OUT / "quad_src.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=red:s=100x50",
- "-f", "lavfi", "-i", "color=c=blue:s=100x50", "-filter_complex", "[0][1]hstack", "-frames:v", "1", "-t", "1",
- "-c:v", "libx264", "-pix_fmt", "yuv420p", quad)
-
- def px(path, x, y):
- r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path),
- "-vf", f"crop=2:2:{x}:{y}", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
- stdout=subprocess.PIPE, stderr=subprocess.PIPE)
- return r.stdout[:3]
-
- fliph = OUT / "quad_fliph.mp4"
- script("fit.py", quad, "--flip", "h", "-o", fliph)
- self.assertGreater(px(fliph, 10, 10)[2], 100, "flip h: left side should now be blue (high B channel)")
- self.assertGreater(px(fliph, 150, 10)[0], 100, "flip h: right side should now be red (high R channel)")
-
- rot90 = OUT / "quad_rot90.mp4"
- script("fit.py", quad, "--rotate", "90", "-o", rot90)
- self.assertGreater(px(rot90, 10, 10)[0], 100, "rotate 90cw: original left (red) column becomes the top row")
-
- def test_fit_nothing_to_do_is_refused(self):
- script("fit.py", self.src, expect_fail=True)
-
- def test_fit_audio_stream_selects_the_requested_track_not_always_the_first(self):
- two = OUT / "fit_two_streams.mkv"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
- "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
- "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
- self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
- out1 = OUT / "fit_two_s1.mp4"
- script("fit.py", two, "--audio-stream", "1", "--width", "160", "-o", out1, "--preset", "veryfast")
- self.assertIsNotNone(probe(str(out1))["audio"], "default fit.py now explicitly maps audio too, not just the automatic 'best stream' pick")
- proc = script("fit.py", two, "--audio-stream", "5", "--width", "160", "-o", OUT / "fit_nope.mp4", "--json", expect_fail=True)
- self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
- self.assertIn("audio-stream", proc.stderr)
-
- # ---------------------------------------------------------------- crop
- def test_crop_exact_rectangle(self):
- out = OUT / "crop1.mp4"
- script("crop.py", self.src, "--x", "100", "--y", "0", "--width", "1080", "--height", "720", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (1080, 720))
- self.assertClose(m["duration"], 12.0, 0.2)
-
- def test_crop_out_of_bounds_is_refused(self):
- script("crop.py", self.src, "--x", "1200", "--y", "0", "--width", "200", "--height", "200", expect_fail=True)
-
- def test_crop_odd_dimensions_refused(self):
- script("crop.py", self.src, "--x", "0", "--y", "0", "--width", "101", "--height", "100", expect_fail=True)
-
- def test_crop_negative_offset_refused(self):
- script("crop.py", self.src, "--x", "-5", "--y", "0", "--width", "100", "--height", "100", expect_fail=True)
-
- def test_zero_or_negative_fps_refused_across_every_cfr_script(self):
- """--fps flows straight into cfr_args(meta, args.fps) / a `fps or source_fps or 30.0`
- fallback in several scripts without ever being validated first. `0` is falsy in Python, so
- `--fps 0` used to be silently discarded and fall back to the source's own fps (or 30) --
- the tool claims to force a specific constant frame rate and quietly does something else
- instead. A negative value is truthy, so `--fps -5` passed straight through to ffmpeg's
- `-r`/`fps=` filter option, which rejects it -- an unhelpful ffmpeg-level crash instead of a
- clear error naming --fps. Verify every affected script now refuses both up front."""
- for name, extra in (
- ("crop.py", ["--x", "0", "--y", "0", "--width", "32", "--height", "32"]),
- ("denoise.py", []),
- ("redact.py", ["--x", "0", "--y", "0", "--width", "32", "--height", "32"]),
- ("straighten.py", ["--degrees", "3"]),
- ("sphere.py", []),
- ("join.py", []), # fps is validated before the "give >= 2 clips" check, one input is enough
- ("multicam.py", []), # fps is validated before the "give >= 2 inputs" check too
- ):
- for bad in ("0", "-5"):
- proc = script(name, self.src, *extra, "--fps", bad, expect_fail=True)
- self.assertIn("--fps", proc.stderr, f"{name} --fps {bad} should name --fps in its error")
-
- # ---------------------------------------------------------------- cropdetect
- def test_cropdetect_reports_a_black_bar_rectangle(self):
- bars = OUT / "cropdetect_bars.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi",
- "-i", "color=black:size=640x480:duration=2,drawbox=y=100:h=280:color=white@1:t=fill",
- "-r", "10", "-pix_fmt", "yuv420p", bars)
- proc = script("cropdetect.py", bars, "--seconds", "2", "--samples", "2", "--json")
- result = json.loads(proc.stdout)
- self.assertIsNotNone(result["crop"])
- self.assertEqual(result["crop"]["width"], 640)
- self.assertLess(result["crop"]["height"], 480)
- self.assertGreater(result["crop"]["y"], 0)
-
- def test_cropdetect_writes_no_file(self):
- before = set(OUT.iterdir())
- script("cropdetect.py", self.src, "--seconds", "1", "--samples", "1")
- self.assertEqual(before, set(OUT.iterdir()))
-
- def test_cropdetect_bad_seconds_refused(self):
- script("cropdetect.py", self.src, "--seconds", "0", expect_fail=True)
-
- # ---------------------------------------------------------------- deinterlace
- def test_deinterlace_frame_mode_keeps_fps(self):
- out = OUT / "deint1.mp4"
- script("deinterlace.py", self.src, "-o", out)
- m = probe(str(out))
- self.assertClose(m["video"]["fps"], 30.0, 0.5)
- self.assertClose(m["duration"], 12.0, 0.3)
- self.assertIsNotNone(m["audio"])
-
- def test_deinterlace_field_mode_doubles_fps(self):
- out = OUT / "deint2.mp4"
- script("deinterlace.py", self.src, "--mode", "field", "-o", out)
- m = probe(str(out))
- self.assertClose(m["video"]["fps"], 60.0, 0.5)
-
- # ---------------------------------------------------------------- denoise
- def test_denoise_produces_valid_output(self):
- out = OUT / "denoise1.mp4"
- script("denoise.py", self.src, "--strength", "high", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
- self.assertClose(m["duration"], 12.0, 0.3)
-
- def test_denoise_negative_override_refused(self):
- script("denoise.py", self.src, "--luma-spatial", "-1", expect_fail=True)
-
- # ---------------------------------------------------------------- redact
- def test_redact_blur_keeps_frame_size(self):
- out = OUT / "redact1.mp4"
- script("redact.py", self.src, "--x", "100", "--y", "50", "--width", "200", "--height", "100", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
-
- def test_redact_pixelate_mode(self):
- out = OUT / "redact2.mp4"
- script("redact.py", self.src, "--x", "100", "--y", "50", "--width", "200", "--height", "100",
- "--mode", "pixelate", "--block-size", "16", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
-
- def test_redact_out_of_bounds_refused(self):
- script("redact.py", self.src, "--x", "1200", "--y", "0", "--width", "200", "--height", "200", expect_fail=True)
-
- def test_redact_odd_dimensions_refused(self):
- script("redact.py", self.src, "--x", "0", "--y", "0", "--width", "101", "--height", "100", expect_fail=True)
-
- # ---------------------------------------------------------------- sphere
- def test_sphere_extracts_a_flat_viewport(self):
- out = OUT / "sphere1.mp4"
- script("sphere.py", self.src, "--yaw", "90", "--pitch", "10", "--h-fov", "100", "--v-fov", "70",
- "--width", "640", "--height", "360", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
- self.assertClose(m["duration"], 12.0, 0.2)
- self.assertIsNotNone(m["audio"])
-
- def test_sphere_defaults_and_no_audio_source(self):
- no_audio = OUT / "sphere_no_audio_src.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=640x320:rate=25",
- "-t", "2", "-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p", no_audio)
- out = OUT / "sphere2.mp4"
- script("sphere.py", no_audio, "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (1920, 1080))
- self.assertIsNone(m["audio"])
-
- def test_sphere_yaw_out_of_range_refused(self):
- script("sphere.py", self.src, "--yaw", "200", expect_fail=True)
-
- def test_sphere_fov_out_of_range_refused(self):
- script("sphere.py", self.src, "--h-fov", "0", expect_fail=True)
-
- def test_sphere_odd_dimensions_refused(self):
- script("sphere.py", self.src, "--width", "641", "--height", "360", expect_fail=True)
-
- def test_sphere_audio_stream_out_of_range_refused(self):
- script("sphere.py", self.src, "--audio-stream", "5", expect_fail=True)
-
- # ---------------------------------------------------------------- straighten
- def test_straighten_crop_fit_has_no_black_corner(self):
- out = OUT / "straighten1.mp4"
- script("straighten.py", self.src, "--degrees", "10", "--fit", "crop", "-o", out)
- m = probe(str(out))
- self.assertLess(m["video"]["width"], 1280)
- self.assertLess(m["video"]["height"], 720)
- self.assertEqual(m["video"]["width"] % 2, 0)
- self.assertEqual(m["video"]["height"] % 2, 0)
- frame = OUT / "straighten1_corner.raw"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", out, "-vf", "crop=8:8:0:0",
- "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", frame)
- data = frame.read_bytes()
- self.assertFalse(all(b == 0 for b in data), "top-left corner is pure black -- straighten left a visible gap")
-
- def test_straighten_pad_fit_grows_the_frame(self):
- out = OUT / "straighten2.mp4"
- script("straighten.py", self.src, "--degrees", "-8", "--fit", "pad", "-o", out)
- m = probe(str(out))
- self.assertGreater(m["video"]["width"], 1280)
- self.assertGreater(m["video"]["height"], 720)
-
- def test_straighten_zero_degrees_refused(self):
- script("straighten.py", self.src, "--degrees", "0", expect_fail=True)
-
- def test_straighten_out_of_range_refused(self):
- script("straighten.py", self.src, "--degrees", "60", expect_fail=True)
-
- # ---------------------------------------------------------------- freeze
- def test_freeze_insert_extends_duration(self):
- out = OUT / "freeze1.mp4"
- script("freeze.py", self.src, "--at", "5", "--hold", "1", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 13.0, 0.3)
-
- def test_freeze_extend_mode_at_end(self):
- out = OUT / "freeze2.mp4"
- script("freeze.py", self.src, "--hold", "1.5", "--mode", "extend", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 13.5, 0.3)
-
- def test_freeze_mid_clip_audio_pad_matches_the_frame_rounded_video_hold(self):
- """The video hold is n = round(hold * fps) whole frames -- n / fps in general isn't
- exactly --hold when hold*fps isn't an integer (e.g. 1.4s at 30fps -> n=42, 42/30=1.4
- exactly here, so use a value where it doesn't divide evenly). apad used to pad by the
- raw --hold value instead of that same frame-rounded duration, so video and audio drifted
- apart by up to half a frame -- a permanent A/V sync error from that point on. Verify the
- constructed apad=pad_dur= matches n/fps, not the raw --hold value."""
- out = OUT / "freeze_avsync.mp4"
- fps = probe(self.src)["video"]["fps"]
- hold = 1.03 # picked so hold*fps is not a whole number at this source's fps
- data = json.loads(script("freeze.py", self.src, "--at", "5", "--hold", str(hold), "-o", out, "--fast", "--json").stdout)
- n = round(hold * fps)
- expected_pad = n / fps
- cmd = data["commands"][0]
- m = re.search(r"apad=pad_dur=([\d.]+)", cmd)
- self.assertIsNotNone(m, f"expected an apad=pad_dur= in: {cmd}")
- self.assertAlmostEqual(float(m.group(1)), expected_pad, places=4)
-
- def test_freeze_extend_mode_before_end_refused(self):
- script("freeze.py", self.src, "--at", "2", "--hold", "1", "--mode", "extend", expect_fail=True)
-
- def test_freeze_zero_hold_refused(self):
- script("freeze.py", self.src, "--hold", "0", expect_fail=True)
-
- def test_freeze_at_zero_holds_the_first_frame(self):
- """--at 0 has no preceding segment to trim/clone from in the general insert-mode filter
- graph (an empty trim=end=0 stream broke ffmpeg filtering entirely); this exercises the
- dedicated at==0 branch that pads the front of the clip instead."""
- out = OUT / "freeze3.mp4"
- script("freeze.py", self.src, "--at", "0", "--hold", "1", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 13.0, 0.3)
-
- # ---------------------------------------------------------------- pad
- def test_pad_start_and_end_extend_duration(self):
- out = OUT / "pad1.mp4"
- script("pad.py", self.src, "--start", "1", "--end", "2", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 15.0, 0.3)
-
- def test_pad_nothing_refused(self):
- script("pad.py", self.src, expect_fail=True)
-
- def test_pad_negative_refused(self):
- script("pad.py", self.src, "--start", "-1", expect_fail=True)
-
- # ---------------------------------------------------------------- speedramp
- def test_speedramp_segments_change_overall_duration(self):
- out = OUT / "ramp1.mp4"
- script("speedramp.py", self.src, "--segment", "0-6:1.0", "--segment", "6-9:0.5", "--segment", "9-12:2.0", "-o", out)
- m = probe(str(out))
- # 6/1.0 + 3/0.5 + 3/2.0 = 6 + 6 + 1.5 = 13.5s
- self.assertClose(m["duration"], 13.5, 0.5)
-
- def test_speedramp_bad_segment_format_refused(self):
- script("speedramp.py", self.src, "--segment", "not-a-segment", expect_fail=True)
-
- def test_speedramp_gap_refused(self):
- script("speedramp.py", self.src, "--segment", "0-5:1.0", "--segment", "6-12:1.0", expect_fail=True)
-
- def test_speedramp_must_start_at_zero_refused(self):
- script("speedramp.py", self.src, "--segment", "1-12:1.0", expect_fail=True)
-
- # ---------------------------------------------------------------- loop
- def test_loop_times_multiplies_duration(self):
- out = OUT / "loop1.mp4"
- script("loop.py", self.src, "--times", "3", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 36.0, 1.0)
-
- def test_loop_duration_hits_exact_target(self):
- out = OUT / "loop2.mp4"
- script("loop.py", self.src, "--duration", "20", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 20.0, 0.1)
-
- def test_loop_times_too_small_refused(self):
- script("loop.py", self.src, "--times", "1", expect_fail=True)
-
- def test_loop_duration_shorter_than_source_refused(self):
- script("loop.py", self.src, "--duration", "3", expect_fail=True)
-
- # ---------------------------------------------------------------- grid
- def test_grid_composites_cols_rows_with_labels(self):
- out = OUT / "grid1.mp4"
- script("grid.py", self.src, self.rot, self.vfr, self.hdr, "--cols", "2", "--rows", "2",
- "--cell-width", "320", "--cell-height", "180", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
-
- def test_grid_wrong_input_count_refused(self):
- script("grid.py", self.src, self.rot, "--cols", "2", "--rows", "2", expect_fail=True)
-
- def test_grid_label_none_skips_drawtext(self):
- proc = script("grid.py", self.src, self.rot, "--cols", "2", "--rows", "1", "--label", "none", "-o", OUT / "grid2.mp4")
- self.assertNotIn("drawtext", proc.stderr)
-
- def test_grid_audio_from_selects_track(self):
- out = OUT / "grid3.mp4"
- script("grid.py", self.src, self.rot, "--cols", "2", "--rows", "1", "--audio-from", "1", "-o", out)
- m = probe(str(out))
- self.assertTrue(m.get("audio"))
-
- def test_grid_pad_extends_shorter_clip_to_the_longest(self):
- short = OUT / "grid_short.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-t", "2", "-c", "copy", short)
- out = OUT / "grid4.mp4"
- script("grid.py", short, self.src, "--cols", "2", "--rows", "1", "--pad", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], probe(str(self.src))["duration"], 0.5)
-
- def test_grid_pad_also_pads_the_selected_audio_track_with_silence(self):
- """--pad holds a shorter cell's video on its last frame out to the longest clip -- but
- --audio-from's track was, until fixed, mapped straight through with no padding at all, so
- a grid with --pad and a short --audio-from track silently lost audio for the padded tail.
- The audio stream must actually span the full padded duration, not just the video."""
- short = OUT / "grid_pad_audio_short.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-t", "2", "-c", "copy", short)
- out = OUT / "grid6.mp4"
- script("grid.py", short, self.src, "--cols", "2", "--rows", "1", "--audio-from", "0", "--pad", "-o", out)
- full_duration = probe(str(self.src))["duration"]
- audio_duration = float(sh("ffprobe", "-v", "error", "-select_streams", "a:0", "-show_entries",
- "stream=duration", "-of", "default=nw=1:nk=1", out).stdout.strip())
- self.assertClose(audio_duration, full_duration, 0.5, "audio must be padded with silence to match the padded video, not stop at 2s")
-
- def test_grid_filename_derived_label_refuses_filter_graph_injection(self):
- """The per-cell label is the clip's own filename (extension stripped), which the caller
- does not choose through a flag -- but on a filesystem where filenames can contain a comma
- or colon, it still reaches a drawtext=text=... option the same way --font's fallback did
- in the #108 finding. Confirm the escaping catches it: a filename shaped like a filter-graph
- breakout payload must render literally, not start a sibling filter."""
- evil = OUT / "evil,drawtext=text=OWNED.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-t", "2", "-c", "copy", evil)
- proc = script("grid.py", evil, self.rot, "--cols", "2", "--rows", "1", "-o", OUT / "grid5.mp4")
- self.assertIn("\\,drawtext=text=OWNED", proc.stderr, "comma in the filename-derived label must be escaped")
-
- # ---------------------------------------------------------------- insert
- def test_insert_native_size_and_duration(self):
- out = OUT / "insert1.mp4"
- script("insert.py", self.logo, "--duration", "3", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 3.0, 0.15)
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (240, 90))
- self.assertIsNone(m["audio"])
-
- def test_insert_exact_frame_size_and_fps(self):
- out = OUT / "insert2.mp4"
- script("insert.py", self.logo, "--duration", "2", "--width", "500", "--height", "500", "--fps", "24", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 2.0, 0.15)
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (500, 500))
- self.assertClose(m["video"]["fps"], 24.0, 0.01)
-
- def test_insert_refuses_zero_duration(self):
- script("insert.py", self.logo, "--duration", "0", expect_fail=True)
-
- def test_insert_ken_burns_zoom_in_actually_scales_over_time(self):
- """The frame must actually change scale over the clip, not just accept the flag."""
- kb_src = OUT / "kb_src.png"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=white:s=800x800",
- "-vf", "drawbox=x=300:y=300:w=200:h=200:color=red:t=fill", "-frames:v", "1", kb_src)
- out = OUT / "kb1.mp4"
- script("insert.py", kb_src, "--duration", "3", "--zoom", "in", "--zoom-amount", "1.3",
- "--width", "640", "--height", "640", "--fps", "10", "-o", out)
-
- def px(path, t, x, y):
- r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path), "-ss", str(t),
- "-vf", f"crop=2:2:{x}:{y}", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
- stdout=subprocess.PIPE, stderr=subprocess.PIPE)
- return r.stdout[:3]
-
- # a screen point between the square's edge at zoom=1 (0.625 normalised) and zoom=1.3 (0.6625):
- # white at the start (not yet covered by the square), red by the end (zoomed in enough to cover it).
- # Tolerant of lossy x264 rounding (e.g. macOS's build lands white at 0xfd, not a pure 0xff).
- start_r, start_g, start_b = px(out, 0.1, 410, 410)
- self.assertGreater(start_r, 240, "should still be white/unpainted before the zoom covers it")
- self.assertGreater(start_g, 240)
- self.assertGreater(start_b, 240)
- end_r, end_g, end_b = px(out, 2.9, 410, 410)
- self.assertGreater(end_r, 200, "should be red by the end (zoomed in enough to cover this point)")
- self.assertLess(end_b, 60)
-
- def test_insert_pan_without_zoom_is_refused(self):
- script("insert.py", self.logo, "--duration", "2", "--pan", "left", expect_fail=True)
-
- def test_insert_bad_zoom_amount_refused(self):
- script("insert.py", self.logo, "--duration", "2", "--zoom", "in", "--zoom-amount", "1.0", expect_fail=True)
-
- # ---------------------------------------------------------------- background
- def test_background_solid_color(self):
- out = OUT / "bg_solid.mp4"
- script("background.py", "-o", out, "--duration", "2", "--width", "640", "--height", "360", "--color", "0x00ff00")
- m = probe(str(out))
- self.assertClose(m["duration"], 2.0, 0.1)
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
-
- def test_background_gradient_has_two_distinct_colors(self):
- out = OUT / "bg_grad.mp4"
- script("background.py", "-o", out, "--duration", "1", "--width", "640", "--height", "360",
- "--gradient", "0xff0000:0x0000ff")
-
- def px(path, x, y):
- r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path),
- "-vf", f"crop=2:2:{x}:{y}", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
- stdout=subprocess.PIPE, stderr=subprocess.PIPE)
- return r.stdout[:3]
-
- left = px(out, 10, 180)
- right = px(out, 620, 180)
- self.assertGreater(left[0], right[0], "left edge should be redder than the right edge")
- self.assertGreater(right[2], left[2], "right edge should be bluer than the left edge")
-
- def test_background_gradient_pins_speed_and_seed_for_a_static_reproducible_clip(self):
- """The `gradients` source filter defaults to speed=0.01 (a slow rotation applied every
- frame) and seed=-1 (a fresh random seed every run) -- so this "static" background (per
- its own docstring: "a title card background, a placeholder behind a logo") silently
- drifted frame to frame instead of staying put, and was not reproducible between runs,
- breaking the bit_exact/deterministic contract _contract.py declares for background.py.
- Confirmed live: the same pixel changed value between t=0s and t=1s of a 3s clip before
- pinning speed near its filter-enforced floor (1e-05; 0 itself is refused). Check the
- constructed filter string directly rather than sampled pixels, since a pixel-value
- comparison is sensitive to x264 encoder rounding that differs between platforms/builds
- independently of whether speed/seed are actually pinned."""
- out = OUT / "bg_grad_pin.mp4"
- data = json.loads(script("background.py", "-o", out, "--duration", "3", "--width", "320", "--height", "240",
- "--gradient", "0x000000:0xffffff", "--angle", "37", "--fast", "--json").stdout)
- cmd = data["commands"][0]
- self.assertIn("gradients=", cmd)
- self.assertRegex(cmd, r"seed=\d+", "seed must be pinned to a fixed value, not left at the -1 (random) default")
- self.assertNotIn("speed=0.01", cmd, "speed must not be left at its default 0.01 (a visible per-frame rotation)")
- m = re.search(r"speed=([\d.e-]+)", cmd)
- self.assertIsNotNone(m, f"expected an explicit speed= in: {cmd}")
- self.assertLess(float(m.group(1)), 0.001, "speed must be pinned near-zero, not left animating")
-
- def test_background_odd_dimensions_refused(self):
- script("background.py", "-o", OUT / "bg_bad.mp4", "--duration", "1", "--width", "641", "--height", "360", expect_fail=True)
-
- def test_background_zero_duration_refused(self):
- script("background.py", "-o", OUT / "bg_bad2.mp4", "--duration", "0", "--width", "640", "--height", "360", expect_fail=True)
-
- # ---------------------------------------------------------------- reverse
- def test_reverse_swaps_start_and_end(self):
- halfcolor = OUT / "halfcolor.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=red:s=64x64:d=1.5",
- "-f", "lavfi", "-i", "color=c=blue:s=64x64:d=1.5", "-filter_complex", "[0][1]concat=n=2:v=1:a=0",
- "-c:v", "libx264", "-pix_fmt", "yuv420p", halfcolor)
- out = OUT / "rev1.mp4"
- script("reverse.py", halfcolor, "-o", out)
-
- def px(path, t):
- r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path), "-ss", str(t),
- "-vf", "crop=2:2:10:10", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
- stdout=subprocess.PIPE, stderr=subprocess.PIPE)
- return r.stdout[:3]
-
- self.assertGreater(px(out, 0.2)[2], 100, "reversed clip starts with the original's last half (blue)")
- self.assertGreater(px(out, 2.8)[0], 100, "reversed clip ends with the original's first half (red)")
-
- def test_reverse_no_audio_drops_track(self):
- out = OUT / "rev_noaudio.mp4"
- script("reverse.py", self.src, "--no-audio", "-o", out)
- m = probe(str(out))
- self.assertIsNone(m["audio"])
-
- # ---------------------------------------------------------------- stabilize
- def test_stabilize_reduces_frame_to_frame_motion(self):
- """Proves the actual effect, not just that the command runs: measured motion must drop.
-
- Three different synthetic "shaky" fixtures (a clean two-frequency sine, then jitter kept
- within real hand-tremor range after the first version's ~9 Hz component turned out too
- fast for optical-flow tracking at 30 fps) were each measured making the output *more*
- jittery, not less, on at least one real macOS ffmpeg/libvidstab build -- while every one
- of them was reliably corrected on Linux. This isn't a fixture-tuning problem: vidstab's
- actual tracking/correction behaviour genuinely differs enough across builds that no
- synthetic camera-shake pattern found so far is a portable ground truth. The quantitative
- "motion measurably dropped" claim is therefore only enforced on the platform where it has
- held up across repeated, differently-tuned fixtures (Linux); elsewhere this still proves
- stabilize.py actually ran vidstabdetect/vidstabtransform and produced a valid, correctly
- durationed output -- just not a specific claim about how much quieter it is.
- """
- shaky = OUT / "shaky.mp4"
- jitter_x = "60+18*sin(2*PI*t*1.3)+9*sin(2*PI*t*2.1+1)"
- jitter_y = "60+14*cos(2*PI*t*0.9)+8*sin(2*PI*t*1.7+0.5)"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=1400x1000:rate=30",
- "-t", "4", "-vf", f"crop=1280:720:x='{jitter_x}':y='{jitter_y}'",
- "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", shaky)
- out = OUT / "stab1.mp4"
- script("stabilize.py", shaky, "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 4.0, 0.3)
-
- def motion_score(path):
- # a Windows path's drive-letter colon must be escaped for a lavfi filter option value
- movie_path = escape_filter_path(str(path))
- cmd = ["ffprobe", "-hide_banner", "-f", "lavfi", "-i", f"movie={movie_path},tblend=all_mode=difference,signalstats",
- "-show_entries", "frame_tags=lavfi.signalstats.YAVG", "-of", "csv=p=0"]
- proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
- return [float(x) for x in proc.stdout.split() if x.strip()]
-
- shaky_scores = motion_score(shaky)
- stab_scores = motion_score(out)
- self.assertTrue(shaky_scores, "motion_score produced no frames -- check the lavfi movie= filter path/escaping")
- self.assertTrue(stab_scores, "motion_score produced no frames -- check the lavfi movie= filter path/escaping")
- if platform.system() == "Linux":
- shaky_avg = sum(shaky_scores) / len(shaky_scores)
- stab_avg = sum(stab_scores) / len(stab_scores)
- self.assertLess(stab_avg, shaky_avg, f"stabilized motion ({stab_avg:.2f}) should be below shaky ({shaky_avg:.2f})")
-
- def test_stabilize_bad_shakiness_refused(self):
- script("stabilize.py", self.src, "--shakiness", "11", expect_fail=True)
-
- def test_stabilize_tripod_and_crop_black_produce_valid_output(self):
- """--tripod and --crop black (vidstabdetect/vidstabtransform's own tripod and crop=1
- options, #96) wire two more of the real filters' documented parameters through as typed
- flags. vidstab's actual correction strength/appearance on synthetic content is build- and
- content-dependent (see the docstring above on test_stabilize_reduces_frame_to_frame_motion
- for why this suite doesn't try to assert an exact "how much" here) -- what's verifiable
- portably is that both flags are accepted, reach the filter graph, and produce a valid,
- correctly durationed/shaped output rather than being silently ignored or crashing."""
- shaky = OUT / "shaky.mp4"
- if not shaky.exists():
- jitter_x = "60+18*sin(2*PI*t*1.3)+9*sin(2*PI*t*2.1+1)"
- jitter_y = "60+14*cos(2*PI*t*0.9)+8*sin(2*PI*t*1.7+0.5)"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=1400x1000:rate=30",
- "-t", "4", "-vf", f"crop=1280:720:x='{jitter_x}':y='{jitter_y}'",
- "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", shaky)
- out = OUT / "stab_tripod_crop_black.mp4"
- proc = script("stabilize.py", shaky, "--tripod", "--crop", "black", "-o", out, "--json")
- # CodeRabbit (#97): duration/dimensions alone don't prove the flags actually reached the
- # filter graph -- an implementation that accepted but silently dropped them would still
- # pass those checks. Inspect the recorded commands directly.
- commands = json.loads(proc.stdout)["commands"]
- self.assertTrue(any("vidstabdetect=" in c and ":tripod=1" in c for c in commands),
- f"--tripod should reach vidstabdetect's own tripod option: {commands}")
- self.assertTrue(any("vidstabtransform=" in c and ":crop=1" in c and ":tripod=1" in c for c in commands),
- f"--tripod/--crop black should reach vidstabtransform's tripod/crop options: {commands}")
- m = probe(str(out))
- self.assertClose(m["duration"], 4.0, 0.3)
- self.assertEqual(m["video"]["width"], 1280)
- self.assertEqual(m["video"]["height"], 720)
-
- def test_stabilize_bad_crop_refused(self):
- script("stabilize.py", self.src, "--crop", "nonsense", expect_fail=True)
-
- # ---------------------------------------------------------------- sequence
- def test_sequence_numbered_pattern_preserves_order(self):
- frames_dir = OUT / "seqframes"
- frames_dir.mkdir(exist_ok=True)
- for i in range(5):
- color = "red" if i % 2 == 0 else "blue"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", f"-i", f"color=c={color}:s=64x48",
- "-frames:v", "1", frames_dir / f"frame_{i:04d}.png")
- out = OUT / "seq1.mp4"
- script("sequence.py", "--dir", frames_dir, "--pattern", "frame_%04d.png", "--fps", "5", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 1.0, 0.1)
-
- raw = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(out), "-vf", "crop=2:2:10:10",
- "-f", "rawvideo", "-pix_fmt", "rgb24", "-"], stdout=subprocess.PIPE, stderr=subprocess.PIPE).stdout
- frame_px = [raw[i * 12:i * 12 + 3] for i in range(len(raw) // 12)]
- self.assertEqual(len(frame_px), 5)
- for i, px in enumerate(frame_px):
- if i % 2 == 0:
- self.assertGreater(px[0], 100, f"frame {i} should be red")
- else:
- self.assertGreater(px[2], 100, f"frame {i} should be blue")
-
- def test_sequence_glob_pattern(self):
- frames_dir = OUT / "seqframes_glob"
- frames_dir.mkdir(exist_ok=True)
- for i in range(5):
- color = "red" if i % 2 == 0 else "blue"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", f"-i", f"color=c={color}:s=64x48",
- "-frames:v", "1", frames_dir / f"frame_{i:04d}.png")
- out = OUT / "seq2.mp4"
- script("sequence.py", "--dir", frames_dir, "--pattern", "*.png", "--fps", "5", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 1.0, 0.1)
-
- def test_sequence_no_match_refused(self):
- frames_dir = OUT / "seqframes"
- script("sequence.py", "--dir", frames_dir, "--pattern", "*.jpg", "--fps", "5", expect_fail=True)
-
- def test_sequence_missing_dir_refused(self):
- script("sequence.py", "--dir", str(OUT / "does_not_exist"), "--pattern", "*.png", "--fps", "5", expect_fail=True)
-
- # ---------------------------------------------------------------- waveform
- def test_waveform_style_default(self):
- out = OUT / "waveform1.mp4"
- script("waveform.py", self.src, "--width", "640", "--height", "360", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
- self.assertIsNotNone(m["audio"])
- self.assertClose(m["duration"], 12.0, 0.3)
-
- def test_waveform_spectrum_style(self):
- out = OUT / "waveform2.mp4"
- script("waveform.py", self.src, "--style", "spectrum", "--width", "640", "--height", "360", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
-
- def test_waveform_audio_only_input(self):
- out = OUT / "waveform3.mp4"
- script("waveform.py", self.mic, "--width", "480", "--height", "270", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (480, 270))
-
- def test_waveform_no_audio_refused(self):
- silent = OUT / "waveform_silent_src.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x240:rate=25",
- "-t", "1", "-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p", silent)
- script("waveform.py", silent, expect_fail=True)
-
- def test_waveform_odd_dimensions_refused(self):
- script("waveform.py", self.src, "--width", "641", "--height", "360", expect_fail=True)
-
- def test_waveform_audio_stream_selects_the_requested_track_not_always_the_first(self):
- """--audio-stream must steer which track is actually visualized, not just which track
- ends up in the output's audio -- the filter_complex used to reference [0:a] unconditionally
- regardless of --audio-stream, so every multi-track input rendered track 0's waveform no
- matter which track was requested."""
- multitrack = OUT / "wave_multitrack.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "anullsrc=r=48000:cl=mono:d=2",
- "-f", "lavfi", "-i", "sine=frequency=800:duration=2",
- "-map", "0:a", "-map", "1:a", "-c:a", "aac", multitrack)
- track0 = OUT / "wave_track0.mp4"
- track1 = OUT / "wave_track1.mp4"
- script("waveform.py", multitrack, "--audio-stream", "0", "--width", "320", "--height", "180", "-o", track0)
- script("waveform.py", multitrack, "--audio-stream", "1", "--width", "320", "--height", "180", "-o", track1)
- # track 0 is silent (a flat line); track 1 is a loud sine (a visibly varying waveform) --
- # their rendered frames must differ.
- frame0 = OUT / "wave_track0.raw"
- frame1 = OUT / "wave_track1.raw"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1", "-i", track0, "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", frame0)
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1", "-i", track1, "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", frame1)
- self.assertNotEqual(frame0.read_bytes(), frame1.read_bytes(), "--audio-stream 0 and 1 rendered identical frames")
-
- # ---------------------------------------------------------------- caption
- def test_caption_text_to_srt_and_burn(self):
- srt = OUT / "cues.srt"
- out = OUT / "cap.mp4"
- script("caption.py", self.src, "--text", self.cues, "--write-srt", srt, "--position", "top", "--bold", "-o", out)
- text = srt.read_text(encoding="utf-8")
- self.assertIn("00:00:03,000 --> 00:00:06,000", text)
- self.assertIn("Second\nline", text)
- self.assertIn("00:00:06,000 --> 00:00:09,000", text, "auto-timed cue follows previous")
- m = probe(str(out))
- self.assertClose(m["duration"], 12.0, 0.15)
- self.assertEqual(m["video"]["width"], 1280)
-
- # ------------------------------------------------- captions people can read (1.12)
- def _small(self):
- """A 640x360 clip: the wrap is computed from the real frame geometry, and a small frame
- makes the safe-area limit bite at an ordinary caption size."""
- small = OUT / "cap_small.mp4"
- if not small.exists():
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi",
- "-i", "testsrc2=size=640x360:rate=30", "-f", "lavfi", "-i", "sine=f=440",
- "-t", "6", "-c:v", "libx264", "-preset", "veryfast", "-crf", "24",
- "-pix_fmt", "yuv420p", "-c:a", "aac", small)
- return small
-
- @staticmethod
- def _srt_cues(path):
- blocks = [b for b in Path(path).read_text(encoding="utf-8").strip().split("\n\n") if b.strip()]
- out = []
- for b in blocks:
- lines = b.splitlines()
- out.append((lines[1], lines[2:]))
- return out
-
- def test_caption_wraps_a_long_latin_cue_to_the_safe_area(self):
- """A 60-character cue at size 48 on a 640-wide frame does not fit one line; it is wrapped
- to the safe area and, past --max-lines, split into consecutive cues rather than running
- off the frame or covering the picture."""
- import caption # noqa: E402 -- the wrap table under test
- cues = OUT / "wrap_latin.txt"
- text = "the quick brown fox jumps over the lazy dog and keeps runnin"
- self.assertEqual(len(text), 60)
- cues.write_text(f"0:00-0:04 {text}\n", encoding="utf-8")
- srt = OUT / "wrap_latin.srt"
- script("caption.py", self._small(), "--text", cues, "--size", "48", "--max-lines", "2",
- "--write-srt", srt, "--fast", "-o", OUT / "wrap_latin.mp4")
- blocks = self._srt_cues(srt)
- self.assertGreater(len(blocks), 1, "60 characters at size 48 cannot fit 2 lines of a 640px frame")
- max_em = 640 * caption.SAFE_WIDTH_FRACTION / (48 * 360 / 288.0)
- for _, lines in blocks:
- self.assertLessEqual(len(lines), 2, f"--max-lines 2 exceeded: {lines}")
- for line in lines:
- self.assertLessEqual(caption.text_width_em(line), max_em + 1e-6,
- f"line wider than the safe area: {line!r}")
- self.assertEqual(" ".join(l for _, lines in blocks for l in lines), text, "no word is lost or cut")
-
- def test_caption_wraps_cjk_between_characters(self):
- """Chinese has no spaces: the line breaks between any two characters, and every character
- counts as a full em (Latin averages just over half)."""
- import caption # noqa: E402
- from _common import font_for_script # noqa: E402
- if font_for_script("zh") is None:
- self.skipTest("this machine has no font covering zh")
- text = "你好世界这是一个很长的中文字幕需要换行处理的测试"
- self.assertEqual(len(text), 24)
- cues = OUT / "wrap_cjk.txt"
- cues.write_text(f"0:00-0:04 {text}\n", encoding="utf-8")
- srt = OUT / "wrap_cjk.srt"
- proc = script("caption.py", self._small(), "--text", cues, "--size", "48", "--write-srt", srt,
- "--fast", "-o", OUT / "wrap_cjk.mp4")
- blocks = self._srt_cues(srt)
- lines = [l for _, ls in blocks for l in ls]
- self.assertGreater(len(lines), 1, "a 24-character CJK cue at size 48 must break")
- max_em = 640 * caption.SAFE_WIDTH_FRACTION / (48 * 360 / 288.0)
- for line in lines:
- self.assertLessEqual(caption.text_width_em(line), max_em + 1e-6, line)
- self.assertEqual("".join(lines), text, "no character is lost")
- self.assertIn("font:", proc.stderr, "a Chinese cue resolves a font by script")
- self.assertRegex(proc.stderr, r"cues: .*(wrapped|split)")
-
- def test_caption_wrap_puts_mixed_script_text_back_exactly_as_written(self):
- """A wrap must never change the text: CJK gains no spaces, and the author's own spaces
- around a Latin word inside CJK survive."""
- import caption # noqa: E402
- for text in ("Hello 世界 this is mixed 混合文本 wrapping",
- "你好世界这是一个很长的中文字幕",
- "one two three four five six"):
- with self.subTest(text=text):
- lines = caption.wrap_text(text, 8)
- self.assertGreater(len(lines), 1)
- rebuilt = ""
- for line in lines:
- if not rebuilt:
- rebuilt = line
- elif text[len(rebuilt)] == " ":
- rebuilt += " " + line
- else:
- rebuilt += line
- self.assertEqual(rebuilt, text)
-
- def test_caption_offset_shifts_every_cue_in_both_directions(self):
- cues = OUT / "offset_cues.txt"
- cues.write_text("0:02-0:04 one\n0:05-0:07 two\n", encoding="utf-8")
- late = OUT / "offset_late.srt"
- script("caption.py", "--text", cues, "--write-srt", late, "--offset", "1.5")
- self.assertIn("00:00:03,500 --> 00:00:05,500", late.read_text(encoding="utf-8"))
- early = OUT / "offset_early.srt"
- script("caption.py", "--text", cues, "--write-srt", early, "--offset", "-1.5")
- self.assertIn("00:00:00,500 --> 00:00:02,500", early.read_text(encoding="utf-8"))
-
- def test_caption_offset_rewrites_a_copy_never_the_callers_srt(self):
- """--offset on a hand-written SRT must not edit the file the user passed in."""
- src_srt = OUT / "offset_source.srt"
- src_srt.write_text("1\n00:00:02,000 --> 00:00:04,000\nhello\n\n", encoding="utf-8")
- before = src_srt.read_text(encoding="utf-8")
- out = OUT / "offset_burn.mp4"
- proc = script("caption.py", self._small(), "--srt", src_srt, "--offset", "1.0", "--fast", "-o", out)
- self.assertEqual(src_srt.read_text(encoding="utf-8"), before, "the caller's SRT is never edited in place")
- adjusted = OUT / "offset_burn_adjusted.srt"
- self.assertTrue(adjusted.exists(), proc.stderr)
- self.assertIn("00:00:03,000 --> 00:00:05,000", adjusted.read_text(encoding="utf-8"))
- self.assertIn(str(adjusted), proc.stderr)
-
- def test_caption_min_duration_extends_a_flashed_cue_but_never_past_the_next(self):
- cues = OUT / "min_dur_cues.txt"
- cues.write_text("0:00-0:00.3 flash\n0:01-0:03 next\n", encoding="utf-8")
- srt = OUT / "min_dur.srt"
- proc = script("caption.py", "--text", cues, "--write-srt", srt, "--min-duration", "1.5")
- text = srt.read_text(encoding="utf-8")
- self.assertIn("00:00:00,000 --> 00:00:01,000", text, "extended up to the next cue's start, not over it")
- self.assertIn("extended", proc.stderr)
- loose = OUT / "min_dur_loose.srt"
- script("caption.py", "--text", cues, "--write-srt", loose, "--min-duration", "0")
- self.assertIn("00:00:00,000 --> 00:00:00,300", loose.read_text(encoding="utf-8"), "--min-duration 0 leaves cues alone")
-
- def test_caption_karaoke_uses_whisper_word_timings_when_the_transcript_has_them(self):
- """A whisper JSON next to the SRT carries real per-word start/end times; --karaoke must
- follow them instead of splitting the cue evenly or guessing from audio energy."""
- srt = OUT / "words.srt"
- srt.write_text("1\n00:00:00,000 --> 00:00:04,000\nalpha beta gamma\n\n", encoding="utf-8")
- (OUT / "words.json").write_text(json.dumps({"segments": [{"words": [
- {"word": "alpha", "start": 0.0, "end": 0.5},
- {"word": "beta", "start": 0.5, "end": 1.0},
- {"word": "gamma", "start": 1.0, "end": 4.0}]}]}), encoding="utf-8")
- ass = OUT / "words.ass"
- proc = script("caption.py", self._small(), "--srt", srt, "--karaoke", "--write-ass", ass,
- "--fast", "-o", OUT / "words.mp4")
- self.assertIn("word timings", proc.stderr)
- body = ass.read_text(encoding="utf-8-sig")
- self.assertIn(r"{\kf50}alpha", body)
- self.assertIn(r"{\kf50}beta", body)
- self.assertIn(r"{\kf300}gamma", body)
-
- def test_caption_brand_styles_caption_block_sets_the_look(self):
- """brand.json's `styles.caption` is the documented 1.12 spelling, shared with graphics.py;
- an explicit flag still beats it."""
- brand = OUT / "brand_styles.json"
- brand.write_text(json.dumps({"styles": {"caption": {
- "font": "DejaVu Serif", "size": 33, "colour": "00FF00", "position": "top", "box": True}}}), encoding="utf-8")
- ass = OUT / "brand_styles.ass"
- script("caption.py", self._small(), "--text", self.cues, "--brand", brand, "--animate", "fade",
- "--write-ass", ass, "--fast", "-o", OUT / "brand_styles.mp4")
- style = next(l for l in ass.read_text(encoding="utf-8-sig").splitlines() if l.startswith("Style: Default"))
- self.assertIn("DejaVu Serif", style)
- self.assertIn("&H0000FF00", style, "colour (British spelling) is read")
- self.assertEqual(style.split(",")[-5], "8", "position top -> ASS alignment 8")
- self.assertEqual(style.split(",")[15], "3", "box -> BorderStyle 3")
-
- def test_caption_non_latin_text_picks_a_font_that_covers_it(self):
- """Korean, Chinese, Arabic and Thai cues burn with a font that has the glyphs: the run
- exits 0, names the font file it chose, and the caption band actually gains ink (tofu
- boxes would too, which is why the font file is asserted as well)."""
- if _no_fontconfig():
- self.skipTest("no fc-list on this machine: fonts cannot be resolved by script here")
- small = self._small()
- base = self._band_luma(small, OUT / "band_plain.png")
- samples = {"ko": "안녕하세요 여러분", "zh": "你好世界大家好", "ar": "مرحبا بالعالم", "th": "สวัสดีชาวโลก"}
- for lang, text in samples.items():
- with self.subTest(lang=lang):
- if font_for_script(lang) is None:
- self.skipTest(f"this machine has no font covering {lang}")
- cues = OUT / f"nl_{lang}.txt"
- cues.write_text(f"0:00-0:04 {text}\n", encoding="utf-8")
- out = OUT / f"nl_{lang}.mp4"
- proc = script("caption.py", small, "--text", cues, "--lang", lang, "--size", "40",
- "--fast", "-o", out)
- m = probe(str(out))
- self.assertEqual(m["video"]["width"], 640)
- chosen = re.search(r"^font: (.+?) \(covers (\w+)\)", proc.stderr, re.M)
- self.assertIsNotNone(chosen, proc.stderr)
- self.assertTrue(os.path.exists(chosen.group(1)), chosen.group(1))
- self.assertEqual(chosen.group(2), lang)
- inked = self._band_luma(out, OUT / f"band_{lang}.png")
- self.assertNotAlmostEqual(inked, base, delta=0.05,
- msg=f"{lang}: the caption band is identical to the uncaptioned frame")
-
- def _band_luma(self, video, png):
- """Mean luminance of the bottom quarter of a frame -- the caption band."""
- script("look.py", video, "--at", "1", "-o", png, "--no-timecode")
- raw = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(png),
- "-vf", "crop=iw:ih/4:0:ih*3/4", "-f", "rawvideo", "-pix_fmt", "gray", "-"],
- stdout=subprocess.PIPE).stdout
- self.assertTrue(raw)
- return sum(raw) / len(raw)
-
- def test_graphics_and_overlay_pick_a_font_by_script_for_non_latin_text(self):
- """drawtext renders a box per missing glyph and still exits 0; graphics.py and overlay.py
- resolve a font that covers the text instead, and say which file they chose."""
- if _no_fontconfig():
- self.skipTest("no fc-list on this machine: fonts cannot be resolved by script here")
- if font_for_script("ko") is None:
- self.skipTest("this machine has no font covering ko")
- gfx = OUT / "gfx_ko.mp4"
- proc = script("graphics.py", self._small(), "--template", "lower-third", "--name", "김민준",
- "--title", "감독", "--lang", "ko", "--preset", "veryfast", "-o", gfx, "--json")
- chosen = re.search(r"^font: (.+?) \(covers ko\)", proc.stderr, re.M)
- self.assertIsNotNone(chosen, proc.stderr)
- self.assertIn(f"fontfile={escape_filter_path(chosen.group(1))}", json.loads(proc.stdout)["commands"][0])
- ov = OUT / "overlay_ja.mp4"
- proc2 = script("overlay.py", self._small(), "--text", "こんにちは世界", "--preset", "veryfast", "-o", ov, "--json")
- chosen2 = re.search(r"^font: (.+?) \(covers ja\)", proc2.stderr, re.M)
- self.assertIsNotNone(chosen2, proc2.stderr)
- self.assertIn("fontfile=", json.loads(proc2.stdout)["commands"][0])
-
- def test_an_explicit_font_is_kept_even_when_it_does_not_cover_the_script(self):
- """A stated --font is the user's decision: it is warned about, never silently replaced."""
- if _no_fontconfig():
- self.skipTest("no fc-list on this machine")
- cues = OUT / "explicit_font.txt"
- cues.write_text("0:00-0:03 你好世界\n", encoding="utf-8")
- proc = script("caption.py", self._small(), "--text", cues, "--font", "DejaVu Sans",
- "--fast", "-o", OUT / "explicit_font.mp4")
- self.assertIn("FontName=DejaVu Sans", " ".join(proc.stderr.splitlines()))
- self.assertNotIn("(covers zh)", proc.stderr, "an explicit font is never replaced")
- if shutil.which("fc-list"):
- self.assertIn("does not cover", proc.stderr, "but the caller is told it will not render")
- else:
- # Windows resolves fonts by file name and has no fontconfig to ask: coverage is
- # unknown, so keeping the font silently (no "does not cover" claim) is correct.
- self.assertNotIn("does not cover", proc.stderr)
-
- def test_no_font_for_the_script_is_a_failed_job_not_tofu(self):
- """The whole point: a machine that cannot render the text refuses the job instead of
- writing a video of empty boxes that ffmpeg reports as a success. Forced with an fc-list
- that answers normally (exit 0) and lists nothing -- fontconfig saying "no font covers
- this", which is what a bare container with fontconfig but no font files looks like."""
- if platform.system() == "Windows":
- self.skipTest("the shim below is a #!/bin/sh script; Windows resolves fonts by file name, not fontconfig")
- shim = OUT / "nofc"
- shim.mkdir(exist_ok=True)
- (shim / "fc-list").write_text("#!/bin/sh\nexit 0\n")
- (shim / "fc-list").chmod(0o755)
- env = dict(os.environ, PATH=f"{shim}{os.pathsep}{os.environ['PATH']}")
- cues = OUT / "no_font.txt"
- cues.write_text("0:00-0:03 안녕하세요\n", encoding="utf-8")
- proc = script("caption.py", self._small(), "--text", cues, "--json", "--fast",
- "-o", OUT / "no_font.mp4", env=env, expect_fail=True)
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["status"], "failed")
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("Korean", doc["error"]["message"])
- self.assertIn("--fonts-dir", doc["error"]["message"], "the message names a flag caption.py has")
- self.assertNotIn("or pass --font-file", doc["error"]["message"], "caption.py has no --font-file")
- self.assertFalse((OUT / "no_font.mp4").exists(), "nothing is written for a job that cannot be read")
-
- def test_a_broken_or_absent_fontconfig_is_unknown_not_missing(self):
- """`unknown` is not `missing` (the rule every other capability in this repo follows):
- with no fc-list on PATH -- or one that fails -- coverage cannot be verified, so the job
- runs with the caller's font (libass has its own font backend) behind one info line,
- instead of refusing work that 1.11.1 rendered."""
- if platform.system() == "Windows":
- self.skipTest("the shim below is a #!/bin/sh script; Windows resolves fonts by file name, not fontconfig")
- cues = OUT / "unknown_fc.txt"
- cues.write_text("0:00-0:03 안녕하세요\n", encoding="utf-8")
- broken = OUT / "brokenfc"
- broken.mkdir(exist_ok=True)
- (broken / "fc-list").write_text("#!/bin/sh\nexit 1\n")
- (broken / "fc-list").chmod(0o755)
- empty = OUT / "nobin"
- empty.mkdir(exist_ok=True)
- for tool in ("ffmpeg", "ffprobe"):
- link = empty / tool
- if not link.exists():
- link.symlink_to(shutil.which(tool))
- cases = {
- "fc-list fails": dict(os.environ, PATH=f"{broken}{os.pathsep}{os.environ['PATH']}"),
- "no fc-list at all": dict(os.environ, PATH=str(empty)),
- }
- for label, env in cases.items():
- with self.subTest(case=label):
- out = OUT / "unknown_fc.mp4"
- proc = script("caption.py", self._small(), "--text", cues, "--json", "--fast",
- "-o", out, env=env)
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["status"], "completed", proc.stderr)
- self.assertIn("could not verify", proc.stderr)
- self.assertNotIn("no installed font covers", proc.stderr)
- self.assertIn("FontName=DejaVu Sans", " ".join(doc["commands"]),
- "the caller's font stands when coverage is unknown")
-
- def test_caption_dry_run_plans_the_same_file_the_real_run_burns(self):
- """--dry-run/--plan must describe the job the real run executes: when --offset/--max-lines/
- --min-duration adjust a hand-written SRT, the planned command names the adjusted copy (the
- file the real run burns), the plan document says where it comes from, and no side file is
- written under a dry run."""
- src_srt = OUT / "plan_parity.srt"
- src_srt.write_text("1\n00:00:01,000 --> 00:00:01,300\nflash\n\n"
- "2\n00:00:02,000 --> 00:00:04,000\n"
- "this is a very long caption line that certainly needs wrapping here\n\n",
- encoding="utf-8")
- out = OUT / "plan_parity.mp4"
- adjusted = OUT / "plan_parity_adjusted.srt"
- if adjusted.exists():
- adjusted.unlink()
- plan = OUT / "plan_parity.json"
- proc = script("caption.py", self._small(), "--srt", src_srt, "--size", "48",
- "-o", out, "--plan", plan)
- doc = json.loads(plan.read_text(encoding="utf-8"))
- planned = [c for c in doc["commands"] if "-vf" in c]
- self.assertTrue(planned, doc["commands"])
- # the filter string escapes the path (Windows: `D\\:/a/...`), so match the file name
- self.assertIn(adjusted.name, planned[0], "the plan burns the adjusted copy, not the caller's file")
- self.assertNotIn(src_srt.name, planned[0])
- self.assertTrue(any(str(adjusted) in n for n in doc.get("notes") or []),
- f"the plan records the side file: {doc.get('notes')}")
- self.assertFalse(adjusted.exists(), "a dry run writes no side file")
- real = script("caption.py", self._small(), "--srt", src_srt, "--size", "48",
- "--fast", "-o", out, "--json")
- self.assertTrue(adjusted.exists(), real.stderr)
- burned = [c for c in json.loads(real.stdout)["commands"] if "-vf" in c]
- self.assertIn(adjusted.name, burned[0], "the real run burns the file the plan named")
-
- def test_a_brand_file_without_a_font_does_not_switch_font_by_script_off(self):
- """BRAND_DEFAULTS always supplies a font, so the merged brand document cannot say whether
- the CALLER chose one: a brand.json that only sets colours must still resolve a font by
- script (and still refuse when nothing covers it)."""
- if _no_fontconfig():
- self.skipTest("no fc-list on this machine")
- if font_for_script("ko") is None:
- self.skipTest("this machine has no font covering ko")
- brand = OUT / "brand_no_font.json"
- brand.write_text(json.dumps({"colors": {"text": "FFFFFF"}}), encoding="utf-8")
- cues = OUT / "brand_ko.txt"
- cues.write_text("0:00-0:03 안녕하세요\n", encoding="utf-8")
- proc = script("caption.py", self._small(), "--text", cues, "--brand", brand,
- "--animate", "none", "--fast", "-o", OUT / "brand_ko.mp4")
- self.assertRegex(proc.stderr, r"(?m)^font: .+? \(covers ko\)")
- self.assertNotIn("does not cover", proc.stderr)
- stated = OUT / "brand_with_font.json"
- stated.write_text(json.dumps({"font": "DejaVu Sans"}), encoding="utf-8")
- proc2 = script("caption.py", self._small(), "--text", cues, "--brand", stated,
- "--animate", "none", "--fast", "-o", OUT / "brand_ko2.mp4")
- if shutil.which("fc-list"):
- self.assertIn("does not cover", proc2.stderr, "a font the brand file itself states is kept")
- else:
- self.assertNotIn("does not cover", proc2.stderr, "no fontconfig: coverage is unknown, nothing is claimed")
- self.assertNotIn("(covers ko)", proc2.stderr)
-
- def test_caption_never_breaks_before_a_combining_mark(self):
- """Thai tone marks and vowel signs, Devanagari matras, Arabic and Hebrew points are their
- own code points: a line may never start with one, and they advance the pen by nothing."""
- import caption # noqa: E402
- import unicodedata
- for text in ("กิ้น" * 6, "मैंने" * 6, "مَرْحَبًا " * 4, "שָׁלוֹם " * 4):
- with self.subTest(text=text[:8]):
- for width in (1.5, 3.0, 6.0):
- for line in caption.wrap_text(text, width):
- first = line[0]
- self.assertEqual(unicodedata.combining(first), 0, f"line starts with a mark: {line!r}")
- self.assertNotIn(unicodedata.category(first), ("Mn", "Mc"), f"line starts with a mark: {line!r}")
- self.assertEqual("".join(caption.wrap_text(text, 3.0)).replace(" ", ""),
- text.replace(" ", ""), "no character is lost")
- self.assertEqual(caption.text_width_em("\u0e01\u0e34\u0e49"), caption.text_width_em("\u0e01"),
- "a combining mark is charged no width")
- self.assertEqual(caption.wrap_text("เก", 10.0), ["เก"], "a leading Thai vowel stays with its consonant")
-
- def test_caption_offset_takes_the_skills_time_grammar(self):
- """SKILL.md lists --offset among the timestamp flags: mm:ss and hh:mm:ss(.fff) work,
- signed, and a bad value is a `kind: input` refusal document, not an argparse dump."""
- cues = OUT / "offset_grammar.txt"
- cues.write_text("0:05-0:07 one\n", encoding="utf-8")
- for value, expected in (("0:02", "00:00:07,000 --> 00:00:09,000"),
- ("-0:00:02.500", "00:00:02,500 --> 00:00:04,500"),
- ("00:00:01:15@30", "00:00:06,500 --> 00:00:08,500")):
- with self.subTest(offset=value):
- srt = OUT / "offset_grammar.srt"
- script("caption.py", "--text", cues, "--write-srt", srt, "--offset", value)
- self.assertIn(expected, srt.read_text(encoding="utf-8"))
- proc = script("caption.py", "--text", cues, "--write-srt", OUT / "offset_bad.srt",
- "--offset", "half past two", "--json", expect_fail=True)
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["status"], "failed")
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("--offset", doc["error"]["message"])
-
- def test_caption_max_lines_holds_for_all_caps_text(self):
- """Uppercase is far wider than the mixed-case average: an all-caps cue must be measured
- with a per-character table, or libass re-wraps each line the wrapper produced and four
- lines are drawn where --max-lines 2 was asked for."""
- import caption # noqa: E402
- text = "WE MEASURE EVERY CAPITAL LETTER BECAUSE UPPERCASE RUNS WIDE"
- cues = OUT / "caps_cue.txt"
- cues.write_text(f"0:01-0:05 {text}\n", encoding="utf-8")
- srt = OUT / "caps_cue.srt"
- script("caption.py", self._small(), "--text", cues, "--size", "48", "--max-lines", "2",
- "--write-srt", srt, "--fast", "-o", OUT / "caps_cue.mp4")
- max_em = 640 * caption.SAFE_WIDTH_FRACTION / (48 * 360 / 288.0)
- blocks = self._srt_cues(srt)
- for _, lines in blocks:
- self.assertLessEqual(len(lines), 2, f"--max-lines 2 exceeded: {lines}")
- # The real DejaVu Sans advances (hmtx/unitsPerEm, unrounded), not caption.py's own table:
- # what libass will actually draw has to fit, or it re-wraps the line and --max-lines 2
- # becomes four lines in the picture.
- real = {"A": .684, "B": .686, "C": .698, "D": .770, "E": .632, "F": .575, "G": .775,
- "H": .752, "I": .295, "J": .295, "K": .656, "L": .557, "M": .863, "N": .748,
- "O": .787, "P": .603, "Q": .787, "R": .695, "S": .635, "T": .611, "U": .732,
- "V": .684, "W": .989, "X": .685, "Y": .611, "Z": .685, " ": .318}
- for _, lines in blocks:
- for line in lines:
- drawn = sum(real[ch] for ch in line)
- self.assertLessEqual(drawn, max_em, f"libass would re-wrap this line: {line!r}")
- self.assertEqual(" ".join(l for _, lines in blocks for l in lines), text)
- self.assertGreater(caption.text_width_em("CAPITALS"), caption.text_width_em("capitals"))
-
- def test_fonts_dir_does_not_bypass_the_coverage_check(self):
- """--fonts-dir says "also look here", not "this exact face": a directory that does not
- cover the script must not silently switch the guarantee off."""
- if _no_fontconfig() or not shutil.which("fc-scan"):
- self.skipTest("no fontconfig tools on this machine")
- if font_for_script("ko") is None:
- self.skipTest("this machine has no font covering ko")
- latin_only = Path(default_font_file("DejaVu Sans") or "")
- if not latin_only.exists():
- self.skipTest("no DejaVu Sans file to point --fonts-dir at")
- # an isolated directory holding only the Latin face: the system font directory that
- # file lives in may well cover Korean too (macOS ships Apple SD Gothic Neo next to it)
- latin_dir = OUT / "fontsdir_latin_only"
- latin_dir.mkdir(exist_ok=True)
- shutil.copyfile(latin_only, latin_dir / latin_only.name)
- cues = OUT / "fontsdir_ko.txt"
- cues.write_text("0:00-0:03 안녕하세요\n", encoding="utf-8")
- proc = script("caption.py", self._small(), "--text", cues, "--fonts-dir", latin_dir,
- "--fast", "-o", OUT / "fontsdir_ko.mp4", "--json")
- self.assertIn("covers ko", proc.stderr, proc.stderr)
- self.assertIn("no face in", proc.stderr, "the caller is told the directory does not cover the script")
- self.assertNotIn("FontName=DejaVu Sans", " ".join(json.loads(proc.stdout)["commands"]))
-
- def test_a_resolved_font_path_with_spaces_survives_into_the_command(self):
- """macOS resolves "/Library/Fonts/Arial Unicode.ttf": a space in the font path must not
- split the info line, the drawtext `fontfile=`, or the libass `fontsdir=`."""
- import _common # noqa: E402
- spaced_dir = OUT / "font dir"
- spaced_dir.mkdir(exist_ok=True)
- source = default_font_file("DejaVu Sans")
- if not source or not os.path.exists(source):
- self.skipTest("no concrete font file on this machine to copy")
- spaced = spaced_dir / "My Font.ttf"
- shutil.copyfile(source, spaced)
-
- # the resolver's own answer and the line it prints keep the path whole
- entry = (str(spaced), "My Font")
- saved = dict(_common._SCRIPT_FONT_CACHE)
- try:
- _common._SCRIPT_FONT_CACHE[("ko", None)] = entry
- with contextlib.redirect_stderr(io.StringIO()): # the resolver's own info line
- _script, resolved, family = _common.script_font_for_text("안녕하세요")
- finally:
- _common._SCRIPT_FONT_CACHE.clear()
- _common._SCRIPT_FONT_CACHE.update(saved)
- self.assertEqual(resolved, str(spaced))
- self.assertEqual(family, "My Font")
- line = f"font: {resolved} (covers ko)"
- self.assertEqual(re.search(r"^font: (.+?) \(covers (\w+)\)", line, re.M).group(1), str(spaced),
- "the info line's path is read whole, not up to the first space")
-
- # and the same path reaches ffmpeg as one argument in both draw paths
- proc = script("overlay.py", self._small(), "--text", "spaced", "--font-file", spaced,
- "--preset", "veryfast", "-o", OUT / "spaced_overlay.mp4", "--json")
- cmd = json.loads(proc.stdout)["commands"][0]
- self.assertIn(f"fontfile={escape_filter_path(str(spaced))}", cmd)
- cues = OUT / "spaced_cue.txt"
- cues.write_text("0:00-0:02 spaced\n", encoding="utf-8")
- proc2 = script("caption.py", self._small(), "--text", cues, "--fonts-dir", spaced_dir,
- "--fast", "-o", OUT / "spaced_caption.mp4", "--json")
- self.assertIn(f"fontsdir={escape_filter_path(str(spaced_dir))}", json.loads(proc2.stdout)["commands"][0])
-
- def test_caption_srt_only(self):
- srt = OUT / "only.srt"
- proc = script("caption.py", "--text", self.cues, "--write-srt", srt)
- self.assertTrue(srt.exists())
- self.assertEqual(proc.stdout.strip(), str(srt))
-
- def test_caption_srt_lands_next_to_output_not_source(self):
- sub = OUT / "capdir"
- sub.mkdir(exist_ok=True)
- out = sub / "cap_side.mp4"
- script("caption.py", self.src, "--text", self.cues, "--preset", "veryfast", "-o", out)
- self.assertTrue((sub / "cap_side.srt").exists(), "SRT written beside the output")
- self.assertFalse((OUT / "source.srt").exists(), "no SRT dropped next to the source")
-
- def test_time_grammar_is_one_parser_with_an_fps_suffix(self):
- """1.9 (roadmap): hh:mm:ss:ff@fps names the rate; broll / cut / freeze refuse a bad time as
- kind input naming the flag, like every other tool, instead of their own wording."""
- sys.path.insert(0, str(SCRIPTS))
- try:
- import _common as c
- finally:
- sys.path.pop(0)
- self.assertAlmostEqual(c.parse_time("00:00:01:15@30"), 1.5)
- self.assertAlmostEqual(c.parse_time("00:00:01:15@30", fps=24), 1.5, msg="the suffix beats the fps a tool passed in")
- self.assertAlmostEqual(c.parse_time("01:00:00:[email protected]"), 108000 / 29.97)
- with self.assertRaises(ValueError):
- c.parse_time("12.5@30")
- with self.assertRaises(ValueError):
- c.parse_time("00:00:01:15@fast")
- with self.assertRaises(c.MissingFpsError):
- c.parse_time("00:00:01:15")
- # the three tools that had their own wrappers
- d = json.loads(script("cut.py", self.src, "--start", "00:00:01:15@30", "--end", "00:00:02:00@30", "-o", OUT / "tc_cut.mp4", "--json", "--overwrite").stdout)
- self.assertAlmostEqual(d["expected_duration"], 0.5, places=2)
- d = json.loads(script("cut.py", self.src, "--start", "nonsense", "-o", OUT / "tc_bad.mp4", "--json", expect_fail=True).stdout)
- self.assertEqual(d["error"]["kind"], "input")
- self.assertIn("--start", d["error"]["message"])
- d = json.loads(script("freeze.py", self.src, "--at", "1:xx", "--hold", "1", "-o", OUT / "tc_freeze.mp4", "--json", expect_fail=True).stdout)
- self.assertEqual(d["error"]["kind"], "input")
- self.assertIn("--at", d["error"]["message"])
- d = json.loads(script("broll.py", self.src, "--insert", self.src, "--at", "1:xx", "-o", OUT / "tc_broll.mp4", "--json", expect_fail=True).stdout)
- self.assertEqual(d["error"]["kind"], "input")
- self.assertIn("--at", d["error"]["message"])
- # 1.9.1 (audit 8): a cue file may carry the suffix too -- the timecodes must not become the caption text
- with self.assertRaises(ValueError) as cm:
- c.parse_time("00:00:01:15@30@30")
- self.assertIn("only one @fps", str(cm.exception), "no interpreter internals in the refusal")
- tc = OUT / "tc_at_cues.txt"
- tc.write_text("00:00:00:15@30 --> 00:00:02:00@30 Hello there\n", encoding="utf-8")
- srt = OUT / "tc_at.srt"
- script("caption.py", "--text", tc, "--write-srt", srt)
- text = srt.read_text(encoding="utf-8")
- self.assertIn("00:00:00,500 --> 00:00:02,000\nHello there", text)
- self.assertNotIn("@30", text)
- # metadata / multicam / speedramp refuse through the same parser and name the suffix
- ch = OUT / "tc_chapters.txt"
- ch.write_text("00:00:01:00 Intro\n", encoding="utf-8")
- d = json.loads(script("metadata.py", self.src, "--chapters", ch, "-o", OUT / "tc_md.mp4", "--json", "--dry-run", expect_fail=True).stdout)
- self.assertEqual(d["error"]["kind"], "input")
- self.assertIn("@fps", d["error"]["message"])
- ch.write_text("00:00:01:00@30 Intro\n", encoding="utf-8")
- script("metadata.py", self.src, "--chapters", ch, "-o", OUT / "tc_md.mp4", "--json", "--dry-run")
- d = json.loads(script("multicam.py", self.src, self.src, "--switch", "0-1:xx:0", "-o", OUT / "tc_mc.mp4", "--json", "--dry-run", expect_fail=True).stdout)
- self.assertEqual(d["error"]["kind"], "input")
- self.assertIn("@fps", d["error"]["message"])
- d = json.loads(script("speedramp.py", self.src, "--segment", "0-1:xx:2", "-o", OUT / "tc_sr.mp4", "--json", "--dry-run", expect_fail=True).stdout)
- self.assertEqual(d["error"]["kind"], "input")
- self.assertIn("@fps", d["error"]["message"])
-
- def test_probe_hdr_signal_is_the_transfer_not_the_primaries(self):
- """1.9: hdr_signal is true for PQ / HLG / Dolby Vision only; hdr keeps its 1.x meaning."""
- m = probe(str(self.hdr))
- self.assertTrue(m["video"]["hdr"])
- self.assertTrue(m["video"]["hdr_signal"])
- m = probe(str(self.src))
- self.assertFalse(m["video"]["hdr"])
- self.assertFalse(m["video"]["hdr_signal"])
-
- def test_caption_smpte_timecode_cues_convert_frames_to_seconds(self):
- tc = OUT / "tc_cues.txt"
- tc.write_text("00:00:00:12 --> 00:00:02:00 Hello\n00:00:02:00 --> 00:00:04:00 World\n", encoding="utf-8")
- srt = OUT / "tc.srt"
- script("caption.py", "--text", tc, "--write-srt", srt, "--fps", "24")
- text = srt.read_text(encoding="utf-8")
- self.assertIn("00:00:00,500 --> 00:00:02,000", text, "frame 12 at 24fps is exactly 0.5s")
-
- def test_caption_smpte_timecode_without_fps_fails_loudly(self):
- """A cue that looks like hh:mm:ss:ff but has no --fps must not be silently swallowed as auto-timed text."""
- tc = OUT / "tc_no_fps.txt"
- tc.write_text("00:00:00:12 --> 00:00:02:00 Hello\n", encoding="utf-8")
- proc = script("caption.py", "--text", tc, "--write-srt", OUT / "tc_no_fps.srt", "--json", expect_fail=True)
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("fps", doc["error"]["message"])
- self.assertFalse((OUT / "tc_no_fps.srt").exists())
-
- def test_caption_fps_defaults_to_the_input_videos_own_fps(self):
- tc = OUT / "tc_auto_fps.txt"
- tc.write_text("00:00:00:15 --> 00:00:02:00 Hello\n", encoding="utf-8")
- out = OUT / "tc_auto.mp4"
- script("caption.py", self.src, "--text", tc, "-o", out, "--preset", "veryfast")
- srt_text = (OUT / "tc_auto.srt").read_text(encoding="utf-8")
- # self.src is 30fps: frame 15 is exactly 0.5s
- self.assertIn("00:00:00,500 --> 00:00:02,000", srt_text)
-
- def test_caption_mux_copies_streams_and_adds_a_subtitle_track(self):
- srt = OUT / "mux_cues.srt"
- out = OUT / "cap_mux.mp4"
- script("caption.py", self.src, "--text", self.cues, "--write-srt", srt, "--mode", "mux", "-o", out)
- m = probe(str(out))
- self.assertEqual(m["subtitle_streams"], 1)
- self.assertEqual(m["video"]["codec"], "h264", "video must be copied, not re-encoded to a different codec")
- self.assertEqual(m["audio"]["codec"], "aac", "audio must be copied untouched")
- self.assertClose(m["duration"], 12.0, 0.15)
-
- def test_caption_mux_chained_keeps_every_language_track(self):
- """--mode mux used to drop any subtitle track the input already had when adding a new
- one (its map list never included 0:s?), so chaining it once per language -- the natural
- way to build a multi-language subtitle set (e.g. an English track, then a Japanese one)
- -- silently lost every earlier language but the last (#93). Each call must now keep what
- was already there."""
- srt_en = OUT / "mux_chain_en.srt"
- srt_en.write_text("1\n00:00:00,000 --> 00:00:02,000\nHello\n", encoding="utf-8")
- srt_ja = OUT / "mux_chain_ja.srt"
- srt_ja.write_text("1\n00:00:00,000 --> 00:00:02,000\nこんにちは\n", encoding="utf-8")
- step1 = OUT / "cap_mux_chain1.mkv"
- script("caption.py", self.src, "--srt", srt_en, "--mode", "mux", "--language", "en", "-o", step1)
- step2 = OUT / "cap_mux_chain2.mkv"
- script("caption.py", step1, "--srt", srt_ja, "--mode", "mux", "--language", "ja", "-o", step2)
- m = probe(str(step2))
- self.assertEqual(m["subtitle_streams"], 2)
- langs = sh("ffprobe", "-v", "error", "-select_streams", "s", "-show_entries", "stream_tags=language",
- "-of", "csv=p=0", step2).stdout.split()
- self.assertEqual(langs, ["en", "ja"])
- self.assertEqual(m["video"]["codec"], "h264", "video must stay copied through both chained calls")
- self.assertEqual(m["audio"]["codec"], "aac", "audio must stay copied through both chained calls")
-
- def test_caption_mux_picks_the_subtitle_codec_from_the_container(self):
- srt = OUT / "mux_container_cues.srt"
- script("caption.py", "--text", self.cues, "--write-srt", srt)
- for ext, expect_codec in ((".mp4", "mov_text"), (".mkv", "subrip")):
- out = OUT / f"cap_mux{ext}"
- script("caption.py", self.src, "--srt", srt, "--mode", "mux", "-o", out)
- streams = sh("ffprobe", "-v", "error", "-select_streams", "s", "-show_entries", "stream=codec_name",
- "-of", "csv=p=0", out).stdout.strip()
- self.assertEqual(streams, expect_codec, f"{ext} output")
-
- def test_caption_mux_refuses_ass_and_animation(self):
- script("caption.py", self.src, "--ass", "/nonexistent.ass", "--mode", "mux", "-o", OUT / "x.mp4", expect_fail=True)
- srt = OUT / "mux_refuse_cues.srt"
- script("caption.py", "--text", self.cues, "--write-srt", srt)
- script("caption.py", self.src, "--srt", srt, "--mode", "mux", "--karaoke", "-o", OUT / "x2.mp4", expect_fail=True)
-
- def test_caption_mux_refuses_an_unrecognized_container(self):
- srt = OUT / "mux_avi_cues.srt"
- script("caption.py", "--text", self.cues, "--write-srt", srt)
- script("caption.py", self.src, "--srt", srt, "--mode", "mux", "-o", OUT / "x.avi", expect_fail=True)
-
- def test_caption_audio_stream_selects_the_requested_track_not_always_the_first(self):
- two = OUT / "cap_two_streams.mkv"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
- "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
- "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
- self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
- cue = OUT / "cap_two_cue.txt"
- cue.write_text("0:00-0:02 Hello\n", encoding="utf-8")
- # mux mode: the picked track survives a stream copy untouched, verified by its own probed sample rate
- out_mux = OUT / "cap_two_mux.mp4"
- script("caption.py", two, "--text", cue, "--audio-stream", "1", "--mode", "mux", "-o", out_mux, "--write-srt", OUT / "cap_two_mux.srt")
- self.assertEqual(probe(str(out_mux))["audio"]["sample_rate"], 44100, "mux must keep the requested track (index 1), not default to index 0")
- # burn mode: the picked track survives re-encoding to AAC too (sample rate normally changes on re-encode,
- # so compare against the same tool re-encoding the default track 0 instead)
- out_burn1 = OUT / "cap_two_burn1.mp4"
- script("caption.py", two, "--text", cue, "--audio-stream", "1", "-o", out_burn1, "--preset", "veryfast")
- out_burn0 = OUT / "cap_two_burn0.mp4"
- script("caption.py", two, "--text", cue, "-o", out_burn0, "--preset", "veryfast")
- # both re-encode to AAC, but decoding each and comparing peak frequency would be overkill here --
- # the -map argument itself is what this test protects, already proven correct in mux mode above;
- # this just confirms burn mode doesn't crash or silently drop audio when --audio-stream is given
- self.assertIsNotNone(probe(str(out_burn1))["audio"])
- self.assertIsNotNone(probe(str(out_burn0))["audio"])
-
- def test_caption_audio_stream_out_of_range_refused(self):
- cue = OUT / "cap_range_cue.txt"
- cue.write_text("0:00-0:02 Hello\n", encoding="utf-8")
- proc = script("caption.py", self.src, "--text", cue, "--audio-stream", "5", "-o", OUT / "x.mp4", "--json", expect_fail=True)
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("audio-stream", doc["error"]["message"])
-
- # ---------------------------------------------------------------- overlay
- def test_overlay_image_and_text(self):
- out1 = OUT / "ov_img.mp4"
- script("overlay.py", self.src, "--image", self.logo, "--position", "top-right", "--scale", "200",
- "--opacity", "0.8", "--start", "1", "--end", "5", "--fade", "0.5", "-o", out1)
- m = probe(str(out1))
- self.assertClose(m["duration"], 12.0, 0.2)
- self.assertIsNotNone(m["audio"], "audio must be kept")
- out2 = OUT / "ov_txt.mp4"
- script("overlay.py", self.src, "--text", "Episode 12", "--position", "bottom", "--box", "--start", "1", "--end", "5", "--fade", "0.3", "-o", out2)
- self.assertClose(probe(str(out2))["duration"], 12.0, 0.15)
-
- # ---------------------------------------------------------------- sync
- def test_sync_detects_offset_and_replaces_audio(self):
- proc = script("sync.py", self.src, self.mic, "--json")
- data = json.loads(proc.stdout)
- self.assertClose(data["offset_seconds"], 2.5, 0.05, "lav mic started 2.5 s later")
- self.assertGreater(data["confidence"], 0.5)
- out = OUT / "synced.mp4"
- script("sync.py", self.src, self.mic, "--replace-audio", "-o", out)
- again = json.loads(script("sync.py", self.src, out, "--json").stdout)
- self.assertClose(again["offset_seconds"], 0.0, 0.05, "aligned output has no residual offset")
-
- def test_sync_negative_offset_trim_second(self):
- early = OUT / "early.wav"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "aevalsrc=0:s=48000:d=1.5",
- "-i", self.src, "-filter_complex", "[0:a][1:a]concat=n=2:v=0:a=1", early)
- data = json.loads(script("sync.py", self.src, early, "--json").stdout)
- self.assertClose(data["offset_seconds"], -1.5, 0.05)
- out = OUT / "early_synced.wav"
- script("sync.py", self.src, early, "--trim-second", "-o", out)
- self.assertEqual(probe(str(out))["audio"]["codec"], "pcm_s16le")
- again = json.loads(script("sync.py", self.src, out, "--json").stdout)
- self.assertClose(again["offset_seconds"], 0.0, 0.05)
-
- # ---------------------------------------------------------------- loudness
- def test_loudness_two_pass(self):
- out = OUT / "loud.mp4"
- script("loudness.py", self.src, "-I", "-16", "--tp", "-1.5", "-o", out)
- stats = json.loads(script("loudness.py", out, "--measure-only", "-I", "-16", "--tp", "-1.5").stdout)
- self.assertClose(float(stats["input_i"]), -16.0, 1.0, "integrated loudness")
- self.assertLessEqual(float(stats["input_tp"]), -1.0, "true peak ceiling")
- self.assertEqual(probe(str(out))["video"]["codec"], "h264", "video stream copied")
-
- # ---------------------------------------------------------------- export
- def test_export_presets(self):
- cases = {
- "youtube": ("mp4", "h264", (1920, 1080)),
- "reels": ("mp4", "h264", (1080, 1920)),
- "x": ("mp4", "h264", (1280, 720)),
- "prores": ("mov", "prores", (1280, 720)),
- "h265": ("mp4", "hevc", (1280, 720)),
- }
- for preset, (ext, codec, size) in cases.items():
- with self.subTest(preset=preset):
- out = OUT / f"export_{preset}.{ext}"
- script("export.py", self.src, "--preset", preset, "-o", out)
- m = probe(str(out))
- self.assertEqual(m["video"]["codec"], codec)
- self.assertEqual((m["video"]["width"], m["video"]["height"]), size)
- self.assertClose(m["duration"], 12.0, 0.2)
- if preset in ("youtube", "reels", "x", "h265"):
- self.assertEqual(m["video"]["color_space"], "bt709")
-
- def test_export_list(self):
- self.assertIn("youtube", script("export.py", "--list").stdout)
-
- def test_export_copy_is_a_real_stream_copy(self):
- """`--preset copy`: same bytes as a source→same-container remux would produce, not a re-encode — verified by
- codec/resolution/bitrate/frame-count staying exactly the source's, not by trusting the preset name."""
- out = OUT / "export_copy.mp4"
- script("export.py", self.src, "--preset", "copy", "-o", out)
- src_m, out_m = probe(str(self.src)), probe(str(out))
- self.assertEqual(out_m["video"]["codec"], src_m["video"]["codec"])
- self.assertEqual((out_m["video"]["width"], out_m["video"]["height"]), (src_m["video"]["width"], src_m["video"]["height"]))
- self.assertEqual(out_m["audio"]["codec"], src_m["audio"]["codec"])
- self.assertClose(out_m["duration"], src_m["duration"], 0.05)
- src_frames = sh("ffprobe", "-v", "error", "-count_frames", "-select_streams", "v:0", "-show_entries", "stream=nb_read_frames", "-of", "csv=p=0", self.src).stdout.strip()
- out_frames = sh("ffprobe", "-v", "error", "-count_frames", "-select_streams", "v:0", "-show_entries", "stream=nb_read_frames", "-of", "csv=p=0", out).stdout.strip()
- self.assertEqual(out_frames, src_frames, "a re-encode could drop/duplicate frames; a copy cannot")
- # a genuinely untouched source has no colour tags to begin with (never asserts a re-encoder's own default)
- self.assertEqual(out_m["video"]["color_space"], src_m["video"]["color_space"])
- # no audio in the source: copy must not invent a silent track, and must not error demanding one
- noaudio = OUT / "noaudio_source.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-t", "2", "-an", "-c:v", "copy", noaudio)
- out_na = OUT / "export_copy_noaudio.mp4"
- script("export.py", noaudio, "--preset", "copy", "-o", out_na)
- self.assertIsNone(probe(str(out_na)).get("audio"))
-
- def test_export_copy_preserves_hdr_tags_untouched(self):
- """The HDR-warning branch that every re-encoding preset trips (`export.py` docstring: "outputs SDR BT.709
- tags without tone mapping") must not apply to `copy` — it doesn't touch colour at all, so the source's own
- HDR tags must survive exactly, not get silently flattened to BT.709 like every other preset does."""
- out = OUT / "export_copy_hdr.mov"
- proc = script("export.py", self.hdr, "--preset", "copy", "-o", out)
- self.assertNotIn("BT.709", proc.stdout + proc.stderr, "copy re-encodes nothing, so it never issues the SDR-flattening warning")
- m = probe(str(out))
- self.assertTrue(m["video"]["hdr"], "the source's real HDR tags must survive a stream copy")
- self.assertNotEqual(m["video"]["color_space"], "bt709", "copy must never relabel HDR content as bt709")
-
- def test_proxy_default_width_and_crf_keeps_audio(self):
- out = OUT / "proxy_default.mp4"
- script("proxy.py", self.src, "-o", out)
- m = probe(str(out))
- self.assertEqual(m["video"]["width"], 640)
- self.assertEqual(m["video"]["codec"], "h264")
- self.assertIsNotNone(m.get("audio"), "default keeps audio when the source has it")
- self.assertClose(m["duration"], 12.0, 0.2)
-
- def test_proxy_scale_and_no_audio(self):
- out = OUT / "proxy_scale.mp4"
- script("proxy.py", self.src, "--scale", "0.25", "--no-audio", "-o", out)
- src_w = probe(str(self.src))["video"]["width"]
- m = probe(str(out))
- self.assertEqual(m["video"]["width"], src_w // 4)
- self.assertIsNone(m.get("audio"), "--no-audio must drop the track, not just mute it")
-
- def test_proxy_forces_fps(self):
- out = OUT / "proxy_fps.mp4"
- script("proxy.py", self.vfr, "--fps", "10", "-o", out)
- m = probe(str(out))
- self.assertFalse(m["video"]["variable_frame_rate_suspected"], "an explicit --fps must conform a VFR source to CFR")
- self.assertClose(m["video"]["fps"], 10.0, 0.5)
-
- def test_proxy_keeps_hdr_dynamic_range_like_every_other_reencode(self):
- """A proxy meant for machine consumption still shouldn't silently wash out HDR to a
- mislabelled BT.709 file — same posture as fit.py/caption.py: keep HDR as HEVC10, and
- let color.py --to-sdr be the tool that makes the SDR-vs-HDR call, not this one."""
- out = OUT / "proxy_hdr.mp4"
- script("proxy.py", self.hdr, "-o", out)
- m = probe(str(out))
- self.assertTrue(m["video"]["hdr"])
- self.assertEqual(m["video"]["codec"], "hevc")
-
- def test_proxy_rejects_bad_scale_and_width(self):
- script("proxy.py", self.src, "--scale", "1.5", expect_fail=True)
- script("proxy.py", self.src, "--scale", "0", expect_fail=True)
- script("proxy.py", self.src, "--width", "0", expect_fail=True)
-
- def test_proxy_dry_run_writes_nothing(self):
- out = OUT / "proxy_dry_run_absent.mp4"
- proc = script("proxy.py", self.src, "-o", out, "--dry-run", "--json")
- doc = json.loads(proc.stdout)
- self.assertTrue(doc["dry_run"])
- self.assertFalse(out.exists())
-
- # ---------------------------------------------------------------- real-world material
- def test_probe_detects_vfr_rotation_surround_hdr(self):
- self.assertTrue(probe(str(self.vfr))["video"]["variable_frame_rate_suspected"])
- self.assertEqual(probe(str(self.rot))["video"]["rotation"], 90)
- self.assertEqual(probe(str(self.surround))["audio"]["channels"], 6)
- h = probe(str(self.hdr))["video"]
- self.assertTrue(h["hdr"])
- self.assertEqual(h["hdr_format"], "HDR10/PQ")
- self.assertEqual(h["bit_depth"], 10)
- self.assertEqual(h["codec"], "hevc")
-
- def test_vfr_is_conformed_to_cfr_on_cut_and_fit(self):
- out = OUT / "vfr_cut.mp4"
- proc = script("cut.py", self.vfr, "--start", "2", "--end", "6", "-o", out)
- self.assertIn("variable-frame-rate", proc.stderr)
- m = probe(str(out))
- self.assertFalse(m["video"]["variable_frame_rate_suspected"])
- self.assertClose(m["duration"], 4.0, 0.2)
- out2 = OUT / "vfr_fit.mp4"
- script("fit.py", self.vfr, "--fps", "30", "--aspect", "1:1", "-o", out2)
- m2 = probe(str(out2))
- self.assertClose(m2["video"]["fps"], 30.0, 0.05)
- self.assertFalse(m2["video"]["variable_frame_rate_suspected"])
-
- def test_rotated_source_uses_display_orientation(self):
- out = OUT / "rot_fit.mp4"
- script("fit.py", self.rot, "--aspect", "9:16", "--fit", "pad", "--width", "540", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (540, 960))
- self.assertEqual(m["video"]["rotation"], 0)
-
- def test_hdr_to_sdr_tonemap(self):
- out = OUT / "sdr.mp4"
- script("color.py", self.hdr, "--to-sdr", "--preset", "veryfast", "-o", out)
- v = probe(str(out))["video"]
- self.assertFalse(v["hdr"])
- self.assertEqual((v["color_transfer"], v["color_primaries"], v["pix_fmt"]), ("bt709", "bt709", "yuv420p"))
- self.assertEqual((v["width"], v["height"]), (1920, 1080))
- # refuses on SDR input unless forced
- script("color.py", self.src, "--to-sdr", expect_fail=True)
-
- def test_color_retag_is_stream_copy(self):
- out = OUT / "retag.mp4"
- proc = script("color.py", self.src, "--retag", "bt601", "-o", out)
- self.assertIn("-c copy", proc.stderr)
- self.assertEqual(probe(str(out))["video"]["color_transfer"], "smpte170m")
-
- def test_color_audio_stream_selects_the_requested_track_not_always_the_first(self):
- two = OUT / "color_two_streams.mkv"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
- "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
- "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
- self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
- out1 = OUT / "color_two_correct1.mp4"
- script("color.py", two, "--correct", "--exposure", "0.2", "--audio-stream", "1", "-o", out1, "--preset", "veryfast")
- self.assertIsNotNone(probe(str(out1))["audio"])
- proc = script("color.py", two, "--correct", "--audio-stream", "5", "-o", OUT / "color_nope.mp4", "--json", expect_fail=True)
- self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
- self.assertIn("audio-stream", proc.stderr)
-
- def test_color_lut(self):
- lut = OUT / "invert.cube"
- lines = ["LUT_3D_SIZE 2"]
- for b in (0, 1):
- for g in (0, 1):
- for r in (0, 1):
- lines.append(f"{1 - r} {1 - g} {1 - b}")
- lut.write_text("\n".join(lines) + "\n")
- out = OUT / "lut.mp4"
- script("color.py", self.src, "--lut", lut, "--lut-strength", "0.5", "--preset", "veryfast", "-o", out)
- self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
-
- def test_color_lut_strength_zero_means_no_lut_and_out_of_range_is_refused(self):
- """--lut-strength's blend branch only fired for the OPEN interval (0, 1); anything outside
- it -- including exactly 0, and any value > 1 or < 0 -- fell into the "apply at full
- strength" fallback with the number silently discarded. --lut-strength 0 is documented as
- "blend graded and original, 0..1" -- 0 should mean the original, unmodified picture, not a
- 100%-strength grade (the opposite of what was asked). Verify 0 now leaves the picture
- untouched, and an out-of-range value is refused instead of silently applying full strength."""
- lut = OUT / "invert_strength.cube"
- lines = ["LUT_3D_SIZE 2"]
- for b in (0, 1):
- for g in (0, 1):
- for r in (0, 1):
- lines.append(f"{1 - r} {1 - g} {1 - b}")
- lut.write_text("\n".join(lines) + "\n")
- zero = OUT / "lut_zero.mp4"
- script("color.py", self.src, "--lut", lut, "--lut-strength", "0", "--preset", "veryfast", "-o", zero)
- self.assertGreater(self._psnr(self.src, zero), 40, "--lut-strength 0 must leave the picture unchanged, not fully inverted")
- self.assertEqual(self._frame_count(zero), self._frame_count(self.src), "no frame may be dropped or duplicated by a no-op grade")
- script("color.py", self.src, "--lut", lut, "--lut-strength", "2.5", "-o", OUT / "lut_oob.mp4", expect_fail=True)
- script("color.py", self.src, "--lut", lut, "--lut-strength", "-1", "-o", OUT / "lut_oob2.mp4", expect_fail=True)
-
- def test_color_correct_identity_holds_on_a_bt709_tagged_source(self):
- """#159: the identity test below only ever ran on the untagged synthetic source. On a
- source *tagged* bt709 (any camera file, anything export.py wrote) an all-defaults
- --correct came back 26 dB PSNR and ~8 % less saturated, because libavfilter's auto-
- inserted swscale legs around the RGB filters disagreed: yuv->rgb honoured the frame's
- bt709 tag, rgb->yuv used the default bt601. Both legs are now pinned to one matrix, so
- the result is the same on a tagged and an untagged copy of the same pixels, on FFmpeg
- 5.1 through 8.1 (measured 39.5 dB on all four)."""
- tagged = OUT / "correct_src709.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", str(self.src), "-t", "3",
- "-vf", "setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv",
- "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", "-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709", "-an", str(tagged))
- self.assertEqual(probe(str(tagged))["video"]["color_space"], "bt709")
- untagged = OUT / "correct_srcU.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", str(self.src), "-t", "3", "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", "-an", str(untagged))
- results = {}
- for name, src in (("tagged", tagged), ("untagged", untagged)):
- out = OUT / f"correct_identity_{name}.mp4"
- data = json.loads(script("color.py", src, "--correct", "--preset", "veryfast", "-o", out, "--json").stdout)
- m = data["measurements"]
- self.assertAlmostEqual(m["input"]["saturation_avg"], m["output"]["saturation_avg"], delta=2.5, msg=name)
- results[name] = self._psnr(src, out)
- self.assertGreater(results[name], 36, f"{name}: an all-defaults --correct must be near-identity, got {results[name]:.1f} dB")
- self.assertAlmostEqual(results["tagged"], results["untagged"], delta=1.0, msg="the colour tag must not change what --correct does to the pixels")
-
- def test_color_correct_defaults_are_near_identity(self):
- out = OUT / "correct_neutral.mp4"
- data = json.loads(script("color.py", self.src, "--correct", "--preset", "veryfast", "-o", out, "--json").stdout)
- m = data["measurements"]
- self.assertIn("y_avg", m["input"])
- self.assertAlmostEqual(m["input"]["y_avg"], m["output"]["y_avg"], delta=2.0)
- self.assertAlmostEqual(m["input"]["saturation_avg"], m["output"]["saturation_avg"], delta=2.0)
- v = probe(str(out))["video"]
- self.assertEqual((v["width"], v["height"]), (1280, 720))
-
- def test_color_correct_exposure_and_saturation_change_measured_levels(self):
- brighter = OUT / "correct_bright.mp4"
- data = json.loads(script("color.py", self.src, "--correct", "--exposure", "0.6", "--preset", "veryfast", "-o", brighter, "--json").stdout)
- m = data["measurements"]
- self.assertGreater(m["output"]["y_avg"], m["input"]["y_avg"], "positive exposure must raise measured luma")
-
- gray = OUT / "correct_gray.mp4"
- data2 = json.loads(script("color.py", self.src, "--correct", "--saturation", "0", "--preset", "veryfast", "-o", gray, "--json").stdout)
- m2 = data2["measurements"]
- self.assertLess(m2["output"]["saturation_avg"], m2["input"]["saturation_avg"], "saturation 0 must desaturate")
- self.assertLess(m2["output"]["saturation_avg"], 5.0, "saturation 0 must be close to grayscale")
-
- def test_color_correct_temperature_and_tint_run_and_preserve_geometry(self):
- out = OUT / "correct_wb.mp4"
- script("color.py", self.src, "--correct", "--temperature", "3200", "--tint", "-0.3", "--contrast", "1.1", "--preset", "veryfast", "-o", out)
- v = probe(str(out))["video"]
- self.assertEqual((v["width"], v["height"]), (1280, 720))
- self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
-
- def test_color_correct_rejects_out_of_safe_range_parameters(self):
- for flag, bad in (("--exposure", "5"), ("--contrast", "3"), ("--saturation", "-1"), ("--temperature", "40000"), ("--tint", "2")):
- out = OUT / "correct_reject.mp4"
- proc = script("color.py", self.src, "--correct", flag, bad, "-o", out, expect_fail=True)
- self.assertIn("outside", proc.stderr, f"{flag} {bad} should be refused as out of range")
- self.assertFalse(out.exists(), f"{flag} {bad}: no partial output on refusal")
-
- def test_color_correct_gamma_changes_measured_luma(self):
- brighter = OUT / "correct_gamma_up.mp4"
- data = json.loads(script("color.py", self.src, "--correct", "--gamma", "1.6", "--preset", "veryfast", "-o", brighter, "--json").stdout)
- m = data["measurements"]
- self.assertGreater(m["output"]["y_avg"], m["input"]["y_avg"], "gamma > 1 must raise measured luma")
-
- darker = OUT / "correct_gamma_down.mp4"
- data2 = json.loads(script("color.py", self.src, "--correct", "--gamma", "0.5", "--preset", "veryfast", "-o", darker, "--json").stdout)
- m2 = data2["measurements"]
- self.assertLess(m2["output"]["y_avg"], m2["input"]["y_avg"], "gamma < 1 must lower measured luma")
-
- def test_color_correct_lift_and_gain_run_and_shift_measured_levels(self):
- lifted = OUT / "correct_lift.mp4"
- data = json.loads(script("color.py", self.src, "--correct", "--lift", "0.3", "--preset", "veryfast", "-o", lifted, "--json").stdout)
- m = data["measurements"]
- self.assertGreater(m["output"]["y_min"], m["input"]["y_min"], "positive lift must raise the shadow floor")
-
- gained = OUT / "correct_gain.mp4"
- data2 = json.loads(script("color.py", self.src, "--correct", "--gain", "-0.3", "--preset", "veryfast", "-o", gained, "--json").stdout)
- m2 = data2["measurements"]
- self.assertLess(m2["output"]["y_avg"], m2["input"]["y_avg"], "negative gain must dim the highlights and lower measured luma")
- v = probe(str(gained))["video"]
- self.assertEqual((v["width"], v["height"]), (1280, 720))
-
- def test_color_correct_levels_narrows_measured_dynamic_range(self):
- out = OUT / "correct_levels_out.mp4"
- data = json.loads(script("color.py", self.src, "--correct", "--levels-out-black", "64", "--levels-out-white", "192",
- "--preset", "veryfast", "-o", out, "--json").stdout)
- m = data["measurements"]
- # colorlevels' output remap is an affine map into [romin, romax]: no output pixel can fall
- # outside it (mod encoder rounding), so this is a mathematical guarantee, not a content guess.
- self.assertGreaterEqual(m["output"]["y_min"], 64 - 3, "--levels-out-black 64 must floor the output near 64")
- self.assertLessEqual(m["output"]["y_max"], 192 + 3, "--levels-out-white 192 must ceiling the output near 192")
- self.assertLess(m["output"]["y_max"] - m["output"]["y_min"], m["input"]["y_max"] - m["input"]["y_min"],
- "narrowing the output levels must narrow the measured dynamic range")
-
- out2 = OUT / "correct_levels_in.mp4"
- script("color.py", self.src, "--correct", "--levels-in-black", "16", "--levels-in-white", "235", "--preset", "veryfast", "-o", out2)
- v = probe(str(out2))["video"]
- self.assertEqual((v["width"], v["height"]), (1280, 720))
- self.assertClose(probe(str(out2))["duration"], 12.0, 0.2)
-
- # an all-default --levels-* call must not add a colorlevels term to the chain
- neutral_chain = script("color.py", self.src, "--correct", "--dry-run").stderr
- self.assertNotIn("colorlevels", neutral_chain)
-
- def test_color_correct_curves_preset_runs_and_preserves_geometry(self):
- out = OUT / "correct_curves.mp4"
- script("color.py", self.src, "--correct", "--curves", "medium_contrast", "--preset", "veryfast", "-o", out)
- v = probe(str(out))["video"]
- self.assertEqual((v["width"], v["height"]), (1280, 720))
- self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
- # omitting --curves must not add a curves term to the chain
- neutral_chain = script("color.py", self.src, "--correct", "--dry-run").stderr
- self.assertNotIn("curves=", neutral_chain)
- proc = script("color.py", self.src, "--correct", "--curves", "not-a-real-preset", "-o", OUT / "correct_curves_bad.mp4", expect_fail=True)
- self.assertIn("invalid choice", proc.stderr)
-
- def test_color_correct_rejects_new_flags_out_of_range(self):
- for flag, bad in (("--gamma", "0.05"), ("--gamma", "11"), ("--lift", "-1.5"), ("--gain", "1.5")):
- out = OUT / "correct_reject_new.mp4"
- proc = script("color.py", self.src, "--correct", flag, bad, "-o", out, expect_fail=True)
- self.assertIn("outside", proc.stderr, f"{flag} {bad} should be refused as out of range")
- self.assertFalse(out.exists(), f"{flag} {bad}: no partial output on refusal")
-
- out = OUT / "correct_reject_levels_in.mp4"
- proc = script("color.py", self.src, "--correct", "--levels-in-black", "200", "--levels-in-white", "100", "-o", out, expect_fail=True)
- self.assertIn("must be less than", proc.stderr)
- self.assertFalse(out.exists())
-
- out2 = OUT / "correct_reject_levels_out.mp4"
- proc2 = script("color.py", self.src, "--correct", "--levels-out-black", "200", "--levels-out-white", "100", "-o", out2, expect_fail=True)
- self.assertIn("must be less than", proc2.stderr)
- self.assertFalse(out2.exists())
-
- def test_export_warns_on_hdr(self):
- out = OUT / "hdr_youtube.mp4"
- proc = script("export.py", self.hdr, "--preset", "x", "-o", out)
- self.assertIn("HDR", proc.stderr)
-
- def test_audio_music_bed_never_shortens_the_video(self):
- """#164: a looped music bed under --duck came out 11.925 s from a 12.00 s source, and
- -shortest then cut the stream-copied *video* to match: four frames gone from a tool whose
- contract says the picture is never touched. The audio is now padded/trimmed to the source
- duration and a video-keeping output never uses -shortest. Every music mode, plus --replace
- with a shorter track, must keep the source's duration and frame count exactly."""
- src_dur = probe(str(self.src))["duration"]
- src_frames = self._frame_count(self.src)
- for tag, flags in (("loop_duck", ["--music", str(self.mic), "--duck", "--music-loop"]),
- ("loop", ["--music", str(self.mic), "--music-loop"]),
- ("plain", ["--music", str(self.mic)]),
- ("replace_short", ["--replace", str(OUT / "c_mic_short.wav")])):
- if tag == "replace_short":
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", str(self.mic), "-t", "3", str(OUT / "c_mic_short.wav"))
- out = OUT / f"music_len_{tag}.mp4"
- script("audio.py", self.src, *flags, "-o", out)
- m = probe(str(out))
- self.assertAlmostEqual(m["duration"], src_dur, msg=tag, delta=0.02)
- self.assertEqual(self._frame_count(out), src_frames, f"{tag}: the picture lost or gained frames")
- self.assertAlmostEqual(m["audio"].get("duration") or m["duration"], src_dur, msg=tag, delta=0.05)
-
- def test_audio_downmix_voice_and_ducking(self):
- out = OUT / "downmix.mp4"
- script("audio.py", self.surround, "--downmix", "--voice", "-o", out)
- a = probe(str(out))["audio"]
- self.assertEqual(a["channels"], 2)
- out2 = OUT / "ducked.mp4"
- proc = script("audio.py", self.src, "--music", self.long_ref, "--duck", "--music-fade-out", "2", "-o", out2)
- self.assertIn("sidechaincompress", proc.stderr)
- self.assertEqual(proc.stderr.count("afade=t=out"), 1, "only the bed fades, not the whole mix")
- proc_mix = script("audio.py", self.src, "--fade-out", "1", "--dry-run")
- self.assertEqual(proc_mix.stderr.count("afade=t=out"), 1)
- self.assertClose(probe(str(out2))["duration"], 12.0, 0.2)
- out3 = OUT / "replaced.mp4"
- script("audio.py", self.src, "--replace", self.mic, "--stereo", "-o", out3)
- m3 = probe(str(out3))
- self.assertEqual(m3["audio"]["channels"], 2)
- self.assertClose(m3["duration"], 12.0, 0.2)
-
- # ------------------------------------------------------------------ 1.13: the audio bed
- def _audio_filters(self, *args):
- """The filter graph audio.py plans, from --dry-run --json (no encode)."""
- data = json.loads(script("audio.py", *args, "--dry-run", "--json").stdout)
- cmd = next(c for c in data["commands"] if "-filter_complex" in c)
- return cmd.split("-filter_complex ", 1)[1].split(" -map", 1)[0].strip("'"), data
-
- def test_audio_voice_levels_are_three_different_chains(self):
- """1.13: --voice takes a strength. A bare --voice must stay byte-identical to the chain
- it produced before the flag took a value (every existing call and MCP request sends it
- bare), and each named level must actually be a different chain -- a preset that is only
- a different word in the help is worse than no preset."""
- out = OUT / "voice_level.mp4"
- bare, _ = self._audio_filters(self.src, "--voice", "-o", out)
- self.assertEqual(bare, "[0:a:0]highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,"
- "acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2[main];"
- "[main]apad,atrim=0:12.000[out]",
- "a bare --voice is the 1.12 chain, unchanged")
- chains = {}
- for level in ("light", "medium", "strong"):
- chains[level], data = self._audio_filters(self.src, "--voice", level, "-o", out)
- self.assertEqual(data["audio"]["voice"], level)
- self.assertEqual(chains["medium"], bare, "bare --voice == --voice medium")
- self.assertEqual(len(set(chains.values())), 3, "each level is a different filter chain")
- self.assertNotIn("deesser", chains["light"])
- self.assertNotIn("afftdn", chains["light"], "light leaves the noise floor alone")
- self.assertIn("acompressor=threshold=-18dB:ratio=2", chains["light"])
- self.assertIn("deesser=i=0.6", chains["strong"])
- self.assertIn("alimiter=limit=0.891251:level=disabled", chains["strong"], "strong ends in a soft limiter")
- self.assertTrue(chains["strong"].count("acompressor") == 2, "strong compresses twice")
- # and each one really encodes
- for level in ("light", "strong"):
- real = OUT / f"voice_{level}.m4a"
- script("audio.py", self.mic, "--voice", level, "-o", real)
- self.assertGreater(probe(str(real))["duration"], 1.0)
-
- def test_audio_duck_parameters_reach_the_sidechain_filter(self):
- """1.13: the ducking knobs are sayable. The default command line must not move (the
- threshold flag speaks dBFS, the filter takes the same 0.05 linear it always did), and
- every flag must land in the filter string and in --json's audio block."""
- out = OUT / "duck_params.mp4"
- default, data = self._audio_filters(self.src, "--music", self.long_ref, "--duck", "-o", out)
- self.assertIn("sidechaincompress=threshold=0.05:ratio=4.0:attack=20:release=400:makeup=1", default,
- "the default duck filter is unchanged")
- self.assertEqual(data["audio"]["duck"]["threshold_linear"], 0.05)
- tuned, data = self._audio_filters(self.src, "--music", self.long_ref, "--duck", "--duck-amount", "18",
- "--duck-threshold", "-30", "--duck-attack", "5", "--duck-release", "250", "-o", out)
- self.assertIn("sidechaincompress=threshold=0.0316228:ratio=6.0:attack=5:release=250:makeup=1", tuned)
- self.assertEqual(data["audio"]["duck"], {"amount_db": 18.0, "threshold_db": -30.0, "threshold_linear": 0.0316228,
- "ratio": 6.0, "attack_ms": 5.0, "release_ms": 250.0})
- # no --duck: the block says so rather than describing settings nothing used
- _, data = self._audio_filters(self.src, "--music", self.long_ref, "-o", out)
- self.assertIsNone(data["audio"]["duck"])
- # out of range is refused before ffmpeg sees it
- doc = json.loads(script("audio.py", self.src, "--music", self.long_ref, "--duck", "--duck-release", "99999",
- "-o", out, "--json", expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("--duck-release", doc["error"]["message"])
-
- def _side_peak_db(self, path):
- """Peak level of the side signal (L-R) in dBFS; -inf (returned as -120) means the two
- channels are identical, i.e. the file has no stereo image at all."""
- proc = sh("ffmpeg", "-hide_banner", "-nostdin", "-i", str(path), "-af",
- "pan=mono|c0=c0-c1,astats=measure_overall=Peak_level:measure_perchannel=none", "-f", "null", "-")
- peak = re.search(r"Peak level dB: (-?[0-9.]+|-inf)", proc.stderr)
- self.assertIsNotNone(peak, proc.stderr[-400:])
- return -120.0 if peak.group(1) == "-inf" else float(peak.group(1))
-
- def test_audio_stereo_widen_needs_a_real_stereo_source(self):
- """1.13: widening scales the side signal (L-R). Duplicating a mono track to two channels
- leaves L == R, so the side signal is exactly zero and scaling it changes nothing -- the
- file comes out bit-identical and still mono. Mono is refused outright, --stereo included,
- rather than pointed at a workaround that cannot work."""
- mono = OUT / "widen_mono.wav"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", str(self.mic), "-ac", "1", str(mono))
- out = OUT / "widened.wav"
- for extra in ([], ["--stereo"]):
- doc = json.loads(script("audio.py", mono, "--stereo-widen", "0.5", *extra, "-o", out,
- "--json", expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input", extra)
- self.assertIn("real stereo source", doc["error"]["message"], extra)
- # a real stereo source -- different content per channel -- is widened, and the widening
- # is audible in the only place it can be: the side signal
- stereo = OUT / "widen_stereo.wav"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i",
- "aevalsrc='0.15*sin(2*PI*300*t)|0.1*sin(2*PI*900*t)':s=48000:c=stereo", "-t", "4", str(stereo))
- before = self._side_peak_db(stereo)
- graph, data = self._audio_filters(stereo, "--stereo-widen", "1", "-o", out)
- self.assertIn("extrastereo=m=3", graph)
- self.assertEqual(data["audio"]["stereo_widen"], 1.0)
- script("audio.py", stereo, "--stereo-widen", "1", "-o", out)
- after = self._side_peak_db(out)
- self.assertEqual(probe(str(out))["audio"]["channels"], 2)
- self.assertGreater(after, -60.0, "L-R must not be silent after widening: that is the whole effect")
- self.assertGreater(after, before + 3.0, "the side signal is louder than it was")
- doc = json.loads(script("audio.py", stereo, "--stereo-widen", "4", "-o", out, "--json", expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input")
-
- def test_audio_stereo_widen_refuses_more_than_two_channels_without_downmix(self):
- """1.13: extrastereo is a stereo-only filter, so libavfilter would auto-insert a downmix
- and throw four channels of a 5.1 master away with no flag and no warning. Losing channels
- is the caller's decision (--downmix), and with it the widening runs on the fold-down."""
- out = OUT / "widen_surround.m4a"
- doc = json.loads(script("audio.py", self.surround, "--stereo-widen", "0.5", "-o", out,
- "--json", expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("--downmix", doc["error"]["message"])
- self.assertIn("6 channels", doc["error"]["message"])
- graph, _ = self._audio_filters(self.surround, "--stereo-widen", "0.5", "--downmix", "-o", out)
- self.assertLess(graph.index("pan=stereo"), graph.index("extrastereo="), "widen runs after the downmix")
- data = json.loads(script("audio.py", self.surround, "--stereo-widen", "0.5", "--downmix",
- "-o", out, "--json").stdout)
- self.assertEqual(data["probe"]["audio"]["channels"], 2)
- self.assertEqual(data["probe"]["audio"]["channel_layout"], "stereo")
-
- def test_audio_duck_parameters_need_their_switch_and_a_bed(self):
- """1.13: --duck-release 250 that silently delivers the default 400 ms is invisible to the
- caller, and --duck with no --music has nothing to duck. Both are refusals naming the
- missing flag, the same rule the typed dynamics parameters already follow."""
- out = OUT / "duck_guard.mp4"
- for flag, value in (("--duck-threshold", "-40"), ("--duck-attack", "5"), ("--duck-release", "250"), ("--duck-amount", "18")):
- doc = json.loads(script("audio.py", self.src, "--music", self.long_ref, flag, value, "-o", out,
- "--json", expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input", flag)
- self.assertIn(flag, doc["error"]["message"])
- self.assertIn("--duck", doc["error"]["message"])
- doc = json.loads(script("audio.py", self.src, "--duck", "--duck-release", "250", "-o", out,
- "--json", expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("--music", doc["error"]["message"])
- # the combination that means something still runs
- graph, _ = self._audio_filters(self.src, "--music", self.long_ref, "--duck", "--duck-release", "250", "-o", out)
- self.assertIn("release=250", graph)
-
- def test_audio_effects_bed_is_mixed_and_never_ducked(self):
- """1.13: --effects is a third bed at its own level. It is mixed after the ducked music,
- outside the sidechain, because effects are cut to the picture."""
- out = OUT / "effects.mp4"
- graph, data = self._audio_filters(self.src, "--music", self.long_ref, "--duck",
- "--effects", self.mic, "--effects-volume", "-20", "-o", out)
- self.assertIn("volume=-20dB", graph)
- self.assertIn("[effects]", graph)
- self.assertGreater(graph.index("[effects]"), graph.index("sidechaincompress"),
- "the effects bed is mixed after the duck, so the sidechain never sees it")
- self.assertTrue(data["audio"]["effects"])
- script("audio.py", self.src, "--effects", self.mic, "--effects-volume", "-20", "-o", out)
- self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
-
- def test_loudness_json_reports_the_measurement_and_the_targets(self):
- """1.13: --json carries the input's own loudnorm measurement (including its loudness
- range) and the targets that were asked for, next to the result measured off the written
- file -- so a caller can see what it started from without a second --measure-only run.
-
- There is deliberately no speech gate here: loudnorm's EBU R128 integrated measurement
- already applies the -70 LUFS absolute and -10 LU relative gates, so gating on
- silencedetect spans moves the result by a fraction of check.py's own tolerance (see
- references/gotchas.md#loudness-and-ambience)."""
- out = OUT / "loud_targets.m4a"
- data = json.loads(script("loudness.py", self.mic, "-I", "-16", "--tp", "-1.5", "--lra", "9",
- "-o", out, "--json").stdout)
- self.assertEqual(data["targets"], {"lufs": -16.0, "tp": -1.5, "lra": 9.0})
- for key in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset"):
- self.assertIn(key, data["measured"], key)
- self.assertIn(key, data["result"], key)
- measured_only = json.loads(script("loudness.py", self.mic, "--measure-only", "--json").stdout)["measured"]
- self.assertEqual(data["measured"]["input_i"], measured_only["input_i"],
- "the reported measurement is the same pass-1 measurement --measure-only prints")
- self.assertClose(float(data["result"]["input_i"]), -16.0, 1.0)
- self.assertNotIn("dialogue", script("loudness.py", "--help").stdout,
- "the speech gate was withdrawn; the flag must not come back without the evidence")
-
- def test_check_podcast_reports_chapters_and_channel_count(self):
- """1.13: two informational podcast rows. Neither may FAIL a delivery, and neither may
- appear for a platform that does not care."""
- data = json.loads(script("check.py", self.mic, "--platform", "podcast", "--no-loudness", "--json").stdout)
- rows = {r["check"]: r for r in data["checks"]}
- self.assertEqual(rows["chapters"]["status"], "WARN")
- self.assertEqual(rows["chapters"]["value"], "none")
- self.assertIn("metadata.py", rows["chapters"]["fix"])
- self.assertEqual(rows["channels"]["status"], "PASS", "mono is fine for a podcast")
- self.assertTrue(data["ok"], "informational rows never fail the delivery")
- # after metadata.py the chapters row passes
- chapters = OUT / "podcast_chapters.txt"
- chapters.write_text("0:00 Intro\n0:04 Body\n", encoding="utf-8")
- tagged = OUT / "podcast_tagged.m4a"
- script("audio.py", self.mic, "-o", OUT / "podcast.m4a")
- script("metadata.py", OUT / "podcast.m4a", "--chapters", chapters, "-o", tagged)
- rows = {r["check"]: r for r in json.loads(script("check.py", tagged, "--platform", "podcast", "--no-loudness", "--json").stdout)["checks"]}
- self.assertEqual(rows["chapters"]["status"], "PASS")
- self.assertEqual(rows["chapters"]["value"], "2")
- # 5.1 warns, with the reason a publisher needs
- rows = {r["check"]: r for r in json.loads(script("check.py", self.surround, "--platform", "podcast", "--no-loudness", "--json").stdout)["checks"]}
- self.assertEqual(rows["channels"]["status"], "WARN")
- self.assertIn("downmix", rows["channels"]["reason"])
- # absent for every other platform
- for platform in ("youtube", "reels"):
- proc = subprocess.run([sys.executable, str(SCRIPTS / "check.py"), str(self.src), "--platform", platform,
- "--no-loudness", "--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
- names = {r["check"] for r in json.loads(proc.stdout)["checks"]}
- self.assertNotIn("chapters", names, platform)
- self.assertNotIn("channels", names, platform)
-
- def test_render_audio_stems_and_chapters_stage(self):
- """1.13: stems are a vocabulary over the flags that already exist, and the chapters stage
- puts the markers in the file that ships (metadata.py, streams copied)."""
- proj = OUT / "project_stems.json"
- proj.write_text(json.dumps({
- "output": "render_stems.mp4",
- "clips": [{"src": "source.mp4"}],
- "audio": {"music": "lavmic.wav", "effects": "lavmic.wav", "duck": True, "voice": "light",
- "stems": {"dialogue": -2, "music": -18, "effects": -24}},
- "export": {"preset": "youtube", "normalize": False},
- "chapters": [{"at": "0:00", "title": "Intro"}, {"at": 3, "title": "Body"}],
- }), encoding="utf-8")
- data = json.loads(script("render.py", proj, "--dry-run", "--json").stdout)
- graph = next(c for c in data["commands"] if "sidechaincompress" in c)
- self.assertIn("volume=-2dB", graph, "stems.dialogue is the main track's gain")
- self.assertIn("volume=-18dB", graph, "stems.music is the bed's level")
- self.assertIn("volume=-24dB", graph, "stems.effects is the effects bed's level")
- self.assertIn("highpass=f=80,acompressor=threshold=-18dB:ratio=2", graph, '"voice": "light" picks the light chain')
- # the chapters stage is planned like every other stage: the dry run names the same
- # metadata.py command against the same delivered file, and lists the stage. A plan that
- # hides a stage is a plan the user cannot approve.
- planned = json.loads(script("render.py", proj, "--dry-run", "--json").stdout)
- real = json.loads(script("render.py", proj, "--fast", "--json").stdout)
- self.assertIn("chapters", planned["stages"])
- self.assertEqual(planned["stages"], real["stages"], "the plan lists the stages the run does")
- for doc in (planned, real):
- chapter_cmds = [c for c in doc["commands"] if "-map_chapters 1" in c]
- self.assertEqual(len(chapter_cmds), 1, doc["stages"])
- self.assertIn(str(OUT / "render_stems.mp4"), chapter_cmds[0], "planned against the delivered file")
- data = real
- written = probe(str(OUT / "render_stems.mp4")).get("chapters") or []
- self.assertEqual([c["title"] for c in written], ["Intro", "Body"])
- self.assertClose(written[1]["start"], 3.0, 0.05)
- # a chapters file path works the same way
- proj2 = OUT / "project_chapters_file.json"
- (OUT / "render_chapters.txt").write_text("0:00 One\n0:05 Two\n", encoding="utf-8")
- proj2.write_text(json.dumps({
- "output": "render_chapters.mp4", "clips": [{"src": "source.mp4"}],
- "export": {"preset": "youtube", "normalize": False}, "chapters": "render_chapters.txt",
- }), encoding="utf-8")
- script("render.py", proj2, "--fast", "--json")
- self.assertEqual(len(probe(str(OUT / "render_chapters.mp4")).get("chapters") or []), 2)
- # a stems level with no effects file, and a misspelled stem, are refusals by name
- proj3 = OUT / "project_stems_bad.json"
- proj3.write_text(json.dumps({"output": "render_stems_bad.mp4", "clips": [{"src": "source.mp4"}],
- "audio": {"stems": {"effects": -20}}}), encoding="utf-8")
- doc = json.loads(script("render.py", proj3, "--dry-run", "--json", expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("effects", doc["error"]["message"])
- proj3.write_text(json.dumps({"output": "render_stems_bad.mp4", "clips": [{"src": "source.mp4"}],
- "audio": {"stems": {"voice": -20}}}), encoding="utf-8")
- doc = json.loads(script("render.py", proj3, "--dry-run", "--json", expect_fail=True).stdout)
- self.assertIn("dialogue", doc["error"]["message"], "the nearest valid stem is named")
- # a music level with no music file is refused the same way an effects level is
- proj3.write_text(json.dumps({"output": "render_stems_bad.mp4", "clips": [{"src": "source.mp4"}],
- "audio": {"stems": {"music": -18}}}), encoding="utf-8")
- doc = json.loads(script("render.py", proj3, "--dry-run", "--json", expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("music", doc["error"]["message"])
-
- def test_render_chapters_are_validated_before_any_stage_runs(self):
- """1.13: every other project error is raised before the first ffmpeg call. A bad chapter
- entry used to surface inside the last stage, after place_output had already delivered an
- unchaptered file and reported the render as done."""
- out = OUT / "render_bad_chapters.mp4"
- proj = OUT / "project_bad_chapters.json"
- for chapters, needle in (([{"title": "A"}], "at"), ([{"at": "0:00"}], "title"),
- ("no_such_chapters.txt", "not found")):
- if out.exists():
- out.unlink()
- proj.write_text(json.dumps({"output": "render_bad_chapters.mp4", "clips": [{"src": "source.mp4"}],
- "export": {"preset": "youtube", "normalize": False},
- "chapters": chapters}), encoding="utf-8")
- doc = json.loads(script("render.py", proj, "--fast", "--json", expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input", chapters)
- self.assertIn(needle, doc["error"]["message"], chapters)
- self.assertEqual(doc.get("commands") or [], [], "refused before the first ffmpeg call")
- self.assertFalse(out.exists(), "no half-done delivery is left behind")
-
- def test_sync_fine_resolution_and_drift(self):
- data = json.loads(script("sync.py", self.long_ref, self.long_drift, "--fix-drift", "--json").stdout)
- self.assertClose(data["offset_seconds"], 1.2, 0.01, "offset extrapolated to t=0 at 1 ms resolution")
- self.assertClose(data["drift"]["drift_ppm"], 500.0, 40.0)
- out = OUT / "drift_fixed.wav"
- script("sync.py", self.long_ref, self.long_drift, "--fix-drift", "--trim-second", "-o", out)
- again = json.loads(script("sync.py", self.long_ref, out, "--fix-drift", "--json").stdout)
- self.assertClose(again["offset_seconds"], 0.0, 0.01)
- self.assertClose(again["drift"]["drift_ppm"], 0.0, 40.0)
-
- def test_fit_smooth_slow_motion_blend(self):
- out = OUT / "slow.mp4"
- script("fit.py", self.src, "--duration", "18", "--smooth", "blend", "--preset", "veryfast", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 18.0, 0.2)
- self.assertClose(m["video"]["fps"], 30.0, 0.05, "frame rate preserved while slowing down")
-
- def test_caption_animated_karaoke_ass(self):
- out = OUT / "karaoke.mp4"
- ass = OUT / "karaoke.ass"
- script("caption.py", self.src, "--text", self.cues, "--animate", "pop", "--karaoke", "--write-ass", ass, "--preset", "veryfast", "-o", out)
- text = ass.read_text(encoding="utf-8-sig")
- self.assertIn("PlayResX: 1280", text)
- self.assertIn("\\kf", text)
- self.assertIn("\\fscx", text)
- self.assertEqual(text.count("Dialogue:"), 3)
- self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
- # from an existing SRT too
- srt = OUT / "cues.srt"
- if not srt.exists():
- script("caption.py", "--text", self.cues, "--write-srt", srt)
- out2 = OUT / "fade.mp4"
- script("caption.py", self.src, "--srt", srt, "--animate", "fade", "--preset", "veryfast", "-o", out2)
- self.assertTrue((OUT / "fade.ass").exists())
-
- # ---------------------------------------------------------------- v0.3: look / silence / join / agent flags
- def test_look_contact_sheet_and_frames(self):
- sheet = OUT / "sheet.png"
- proc = script("look.py", self.src, "--tiles", "4x3", "--width", "1280", "-o", sheet)
- self.assertTrue(sheet.exists())
- self.assertIn("12 frames", proc.stderr)
- w, h = png_size(sheet)
- self.assertGreaterEqual(w, 1280)
- self.assertGreater(h, 500, "three rows of 16:9 tiles")
- proc = script("look.py", self.src, "--at", "2.5", "--at", "0:07", "-o", OUT / "frame")
- frames = [OUT / "frame_2.500s.png", OUT / "frame_7.000s.png"]
- for f in frames:
- self.assertTrue(f.exists(), f)
- self.assertEqual(png_size(frames[0]), (1280, 720))
- cmp_png = OUT / "cmp.png"
- script("look.py", self.src, "--compare", self.src, "--at", "1", "-o", cmp_png)
- self.assertEqual(png_size(cmp_png)[0], 1280)
-
- def test_shell_quote_quotes_backslashes(self):
- """CodeRabbit (#101): fixing the invalid-escape-sequence SyntaxWarning in shell_quote()'s
- character set (a stray `\\` before an already-unescaped `;`) accidentally dropped a real,
- load-bearing backslash from the quoting trigger set -- the original `\\;` literal, due to
- Python keeping an unrecognised escape's backslash, actually matched on `\\` OR `;`, not just
- `;`. Without a backslash trigger, a Windows path like `C:\\media\\clip.mp4` would render
- unquoted in --dry-run/--json command output. Assert the fixed version still quotes it."""
- self.assertEqual(shell_quote("C:\\media\\clip.mp4"), "'C:\\media\\clip.mp4'")
- self.assertEqual(shell_quote("plain.mp4"), "plain.mp4")
- self.assertEqual(shell_quote("has;semicolon"), "'has;semicolon'")
-
- def test_look_scenes_overlay_graphics_prefer_fontfile_over_font_when_resolvable(self):
- """#100: drawtext's own fontconfig resolution (font=<name>) crashed with an access violation
- on some real Windows ffmpeg builds, with or without a valid fonts.conf; fontfile=<path> is
- the only form confirmed not to crash, since it never touches fontconfig at all. Every
- drawtext-using tool now resolves a concrete font file (default_font_file() in _common.py)
- and prefers fontfile= whenever one can be found, falling back to font= only when nothing
- resolves. This sandbox has fc-match + DejaVu Sans, so a file is always resolvable here --
- skip rather than false-fail on a machine where it genuinely cannot be (no fc-match, no
- fonts installed), since font= is still the documented, correct fallback there."""
- if not default_font_file("DejaVu Sans"):
- self.skipTest("no resolvable default font on this machine (no fc-match / no fonts) -- font= fallback is correct here")
-
- out = OUT / "fontfile_look.png"
- proc = script("look.py", self.src, "--at", "1", "-o", out, "--json")
- data = json.loads(proc.stdout)
- self.assertTrue(any("fontfile=" in c for c in data["commands"]), data["commands"])
-
- scenes_sheet = OUT / "fontfile_scenes.png"
- proc = subprocess.run([sys.executable, str(SCRIPTS / "scenes.py"), str(self.src), "--sheet", str(scenes_sheet), "--json"],
- stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
- self.assertEqual(proc.returncode, 0, proc.stderr)
- self.assertIn("fontfile=", proc.stderr, "scenes.py --sheet should log a drawtext with fontfile=")
-
- out2 = OUT / "fontfile_overlay.mp4"
- proc = script("overlay.py", self.src, "--text", "hi", "-o", out2, "--json")
- data2 = json.loads(proc.stdout)
- self.assertTrue(any("fontfile=" in c for c in data2["commands"]), data2["commands"])
-
- out3 = OUT / "fontfile_gfx.mp4"
- proc = script("graphics.py", self.src, "--template", "title", "--title", "hi", "-o", out3, "--json")
- data3 = json.loads(proc.stdout)
- self.assertTrue(any("fontfile=" in c for c in data3["commands"]), data3["commands"])
-
- def test_silence_removal(self):
- gappy = OUT / "gappy.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*gt(sin(2*PI*0.25*t)\\,0)':s=48000",
- "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30", "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", gappy)
- data = json.loads(script("silence.py", gappy, "--list", "--json").stdout)
- self.assertEqual(len(data["silences"]), 3)
- self.assertNotIn("hint", data, "a hit needs no hint")
- # a track with nothing under the threshold says what the floor is and which flag to change,
- # instead of a bare "0 silences" that sends an agent off to raw ffmpeg (evals iteration 5, finding 1)
- tone = OUT / "tone.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000",
- "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30", "-t", "4", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", tone)
- none = json.loads(script("silence.py", tone, "--list", "--json").stdout)
- self.assertEqual(none["silences"], [])
- self.assertIn("--threshold", none["hint"])
- self.assertIn("mean level", none["hint"])
- self.assertClose(data["removed_seconds"], 5.25, 0.3)
- out = OUT / "tight.mp4"
- edl = OUT / "keep.txt"
- script("silence.py", gappy, "--preset", "veryfast", "--edl", edl, "-o", out)
- self.assertClose(probe(str(out))["duration"], 6.75, 0.3)
- self.assertEqual(len(edl.read_text().strip().splitlines()), 3)
- # the EDL feeds cut.py --segments directly
- segs = ",".join(edl.read_text().split())
- out2 = OUT / "tight_via_cut.mp4"
- script("cut.py", gappy, "--segments", segs, "--accurate", "--preset", "veryfast", "-o", out2)
- self.assertClose(probe(str(out2))["duration"], 6.75, 0.4)
-
- def test_silence_on_wav_input_keeps_pcm_not_forced_aac(self):
- """silence.py's final ffmpeg command used to unconditionally append aac_args() (-c:a aac)
- regardless of the output container. That's fine for .mp4/.m4a, but AAC cannot be muxed
- into a .wav file -- so silence removal on any audio-only WAV input (a very ordinary case:
- podcasts, voice memos, any --list workflow feeding straight into a WAV pipeline) crashed
- ffmpeg outright, whether or not -o was given explicitly. Verify a WAV input still produces
- a valid, playable WAV output (PCM), not a codec/container mismatch crash."""
- wav_in = OUT / "silence_wav_in.wav"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*gt(sin(2*PI*0.25*t)\\,0)':s=48000",
- "-t", "6", wav_in)
- proc = script("silence.py", wav_in)
- out = Path(proc.stdout.strip())
- self.assertEqual(out.suffix, ".wav")
- m = probe(str(out))
- self.assertTrue(m["audio"]["codec"].startswith("pcm"), f"WAV output must stay PCM, got {m['audio']['codec']}")
-
- def test_join_with_transition_normalises_mismatched_clips(self):
- out = OUT / "joined.mp4"
- # 720p 30fps stereo + rotated portrait + 640x360 mono clip without audio
- silent = OUT / "silent.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=25", "-t", "4", "-c:v", "libx264", "-preset", "veryfast", silent)
- script("join.py", self.src, self.rot, silent, "--transition", "fadeblack", "--duration", "0.5", "--preset", "veryfast", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
- self.assertClose(m["video"]["fps"], 30.0, 0.05)
- self.assertEqual(m["audio"]["channels"], 2)
- self.assertClose(m["duration"], 12 + 6 + 4 - 1.0, 0.3)
- out2 = OUT / "joined_cut.mp4"
- script("join.py", self.src, silent, "--transition", "none", "--preset", "veryfast", "-o", out2)
- self.assertClose(probe(str(out2))["duration"], 16.0, 0.3)
- script("join.py", self.src, expect_fail=True)
-
- def test_join_two_or_more_audio_less_clips(self):
- """Every no-audio clip gets a synthetic silent audio track added as an extra ffmpeg input (join.py
- builds this itself, not this test's fixtures) -- `idx` must be this ffmpeg input's actual position
- (n + how many synthetic inputs were already added), not `n + len(extra_inputs)` (the six argv tokens
- each synthetic input contributes, not a count of inputs). With exactly one no-audio clip both counts
- happen to agree; a real multi-camera join where every clip lacked audio is what caught the divergence
- starting from the second one -- ffmpeg refused with "Invalid file index" naming an input far past the
- real count, since the miscomputed index grew by 6 (not 1) per extra no-audio clip."""
- silent_a = OUT / "silent_a.mp4"
- silent_b = OUT / "silent_b.mp4"
- silent_c = OUT / "silent_c.mp4"
- for out, size in ((silent_a, "640x360"), (silent_b, "480x270"), (silent_c, "960x540")):
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", f"testsrc2=size={size}:rate=25", "-t", "3", "-c:v", "libx264", "-preset", "veryfast", out)
- out = OUT / "joined_all_silent.mp4"
- script("join.py", silent_a, silent_b, silent_c, "--transition", "none", "--preset", "veryfast", "-o", out)
- m = probe(str(out))
- self.assertClose(m["duration"], 9.0, 0.3)
- self.assertEqual(m["audio"]["channels"], 2, "every clip's missing track became silent stereo, not a dropped audio stream")
- # mixed: audio-bearing clip first, then two without -- exercises the same off-by-more-than-one index
- # for the second and third synthetic input regardless of which position the real audio clip sits in
- out2 = OUT / "joined_mixed_silent.mp4"
- script("join.py", self.src, silent_a, silent_b, "--transition", "none", "--preset", "veryfast", "-o", out2)
- self.assertClose(probe(str(out2))["duration"], 12 + 3 + 3, 0.3)
-
- def test_dry_run_and_json_on_every_script(self):
- cases = [
- ("cut.py", [self.src, "--start", "1", "--end", "3"]),
- ("fit.py", [self.src, "--duration", "6"]),
- ("caption.py", [self.src, "--srt", OUT / "cues.srt"]),
- ("overlay.py", [self.src, "--image", self.logo]),
- ("export.py", [self.src, "--preset", "x"]),
- ("color.py", [self.src, "--retag", "bt709"]),
- ("audio.py", [self.src, "--denoise"]),
- ("join.py", [self.src, self.src]),
- ]
- if not (OUT / "cues.srt").exists():
- script("caption.py", "--text", self.cues, "--write-srt", OUT / "cues.srt")
- for name, argv in cases:
- out = OUT / f"dry_{name}.mp4"
- proc = script(name, *argv, "-o", out, "--dry-run", "--json")
- self.assertFalse(out.exists(), f"{name} wrote a file in --dry-run")
- data = json.loads(proc.stdout)
- self.assertTrue(data["dry_run"], name)
- self.assertTrue(data["commands"] and all("ffmpeg" in c for c in data["commands"]), name)
- self.assertEqual(data["output"], str(out), name)
- # --json on a real run includes the probe of the output
- out = OUT / "json_cut.mp4"
- data = json.loads(script("cut.py", self.src, "--start", "0", "--end", "2", "-o", out, "--json").stdout)
- self.assertClose(data["probe"]["duration"], 2.0, 0.6)
-
- # ---------------------------------------------------------------- v0.4: verify / multicam / HLG / Log / energy karaoke / progress
- def test_probe_hlg_and_log_detection(self):
- hlg = OUT / "hlg.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-t", "3",
- "-vf", "format=yuv420p10le", "-c:v", "libx265", "-preset", "ultrafast",
- "-x265-params", "colorprim=bt2020:transfer=arib-std-b67:colormatrix=bt2020nc:log-level=error", "-tag:v", "hvc1", hlg)
- v = probe(str(hlg))["video"]
- self.assertEqual(v["hdr_format"], "HLG")
- self.assertIsNone(v["dolby_vision"])
- out = OUT / "hlg_sdr.mp4"
- script("color.py", hlg, "--to-sdr", "--fast", "-o", out)
- self.assertEqual(probe(str(out))["video"]["color_transfer"], "bt709")
- nodv = OUT / "hlg_nodv.mp4"
- proc = script("color.py", hlg, "--strip-dovi", "-o", nodv)
- self.assertIn("filter_units", proc.stderr)
- self.assertEqual(probe(str(nodv))["video"]["hdr_format"], "HLG")
- flat = OUT / "loglike.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-t", "3",
- "-vf", "curves=all='0/0.36 1/0.88',hue=s=0.4,format=yuv420p", "-c:v", "libx264", "-preset", "veryfast", flat)
- data = json.loads(script("probe.py", flat, "--analyze").stdout)
- self.assertTrue(data["levels"]["looks_like_log"])
- data = json.loads(script("probe.py", self.src, "--analyze").stdout)
- self.assertFalse(data["levels"]["looks_like_log"])
- compact = script("probe.py", flat, "--analyze", "--compact").stdout
- self.assertIn("[Log?]", compact)
-
- def test_karaoke_energy_timing_follows_audio(self):
- gappy = OUT / "gappy_k.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*lt(t\\,2)':s=48000",
- "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30", "-t", "4", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", gappy)
- cues = OUT / "kcues.txt"
- cues.write_text("0:00-0:04 one two three four\n", encoding="utf-8")
- ass = OUT / "ke.ass"
- script("caption.py", gappy, "--text", cues, "--karaoke", "--write-ass", ass, "--fast", "-o", OUT / "ke.mp4")
- line = [l for l in ass.read_text(encoding="utf-8-sig").splitlines() if l.startswith("Dialogue")][0]
- durs = [int(x) for x in re.findall(r"\\kf(\d+)", line)]
- self.assertEqual(len(durs), 4)
- self.assertEqual(sum(durs), 400)
- self.assertLess(sum(durs[:3]), 200, "first three words should sit inside the 2 s of sound")
- ass2 = OUT / "ke_even.ass"
- script("caption.py", gappy, "--text", cues, "--karaoke", "--karaoke-timing", "even", "--write-ass", ass2, "--fast", "-o", OUT / "ke2.mp4")
- line2 = [l for l in ass2.read_text(encoding="utf-8-sig").splitlines() if l.startswith("Dialogue")][0]
- self.assertEqual([int(x) for x in re.findall(r"\\kf(\d+)", line2)], [100, 100, 100, 100])
-
- def test_multicam_offsets_and_switch(self):
- camB = OUT / "camB.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1.5", "-i", self.src, "-vf", "hue=h=90", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", camB)
- data = json.loads(script("multicam.py", self.src, camB, self.mic, "--offsets-only", "--json").stdout)
- self.assertClose(data["offsets_seconds"][1], 1.5, 0.05)
- self.assertClose(data["offsets_seconds"][2], 2.5, 0.05)
- out = OUT / "mc.mp4"
- data = json.loads(script("multicam.py", self.src, camB, self.mic, "--audio", "2", "--switch", "0-3:0,3-6:1,6-9:0", "--fast", "-o", out, "--json").stdout)
- self.assertEqual(len(data["cuts"]), 4, "three named ranges plus the gap-fill to the end")
- m = probe(str(out))
- self.assertClose(m["duration"], 12.0, 0.2)
- self.assertEqual(m["audio"]["channels"], 2)
- # camB is hue-shifted: a frame at 4.5 s (camera 1) must differ from one at 2 s (camera 0)
- script("look.py", out, "--at", "2", "--at", "4.5", "-o", OUT / "mcf")
- self.assertNotEqual((OUT / "mcf_2.000s.png").read_bytes()[100:2000], (OUT / "mcf_4.500s.png").read_bytes()[100:2000])
- auto = OUT / "mc_auto.mp4"
- script("multicam.py", self.src, camB, "--auto", "4", "--fast", "-o", auto)
- self.assertClose(probe(str(auto))["duration"], 12.0, 0.2)
- script("multicam.py", self.src, camB, "--switch", "0-3:5", expect_fail=True)
-
- def test_multicam_fix_drift_trims_before_resample_not_after(self):
- """--fix-drift's audio path computes a_start (an atrim start point) in the source's own
- pre-correction time axis, but the filter chain used to apply asetrate/aresample (the drift
- correction) *before* atrim -- so the trim landed on the already-rescaled timeline instead
- of the raw one it was computed for, same bug class as sync.py already avoids by seeking
- with -ss (an input-level, pre-filter operation) before its own drift_af. Build a camera
- whose audio started before the reference (offsets[a] < 0, so a_start > 0) and also drifts
- (ratios[a] != 1), then check the constructed [<audio input>:a] filter chain: atrim=start=
- must appear before asetrate, mirroring sync.py's ordering."""
- base = OUT / "mc_drift_base.wav"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000", "-t", "200", "-c:a", "pcm_s16le", base)
- ref_audio = OUT / "mc_drift_ref.wav"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1.2", "-i", base, "-c:a", "pcm_s16le", ref_audio)
- camB = OUT / "mc_drift_camB.wav"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", base, "-af", "asetrate=48000*0.9995,aresample=48000", "-c:a", "pcm_s16le", camB)
- cam0 = OUT / "mc_drift_cam0.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc=size=160x120:rate=15", "-i", ref_audio, "-c:v", "libx264", "-preset", "ultrafast", "-c:a", "aac", "-shortest", cam0)
-
- data = json.loads(script("multicam.py", cam0, camB, "--audio", "1", "--switch", "0-198:0", "--fix-drift", "--max-offset", "5", "--fast", "-o", OUT / "mc_drift_out.mp4", "--json").stdout)
- self.assertLess(data["offsets_seconds"][1], 0, "camera 1 must have started before the reference for a_start > 0 to be exercised")
- self.assertNotEqual(data["drift_ppm"][1], 0.0, "drift must actually be detected for asetrate/aresample to be in the chain")
- audio_chain = data["commands"][0].split("[1:a]", 1)[1]
- self.assertLess(audio_chain.index("atrim=start="), audio_chain.index("asetrate="),
- "atrim=start= (in the pre-correction time axis) must run before asetrate/aresample rescale that axis")
-
- def test_multicam_negative_auto_interval_refused_not_infinite_loop(self):
- """--auto builds cuts with `while t < ref_dur: ... t += args.auto` -- `elif args.auto:` is
- only false for exactly 0, so a negative value used to pass that check and enter the loop
- with t decreasing every iteration, meaning t < ref_dur never becomes false: the process
- hangs forever instead of erroring on invalid input. Must be refused up front instead."""
- script("multicam.py", self.src, self.src, "--auto", "-1", "--fast", "-o", OUT / "mc_auto_neg.mp4", expect_fail=True)
-
- def test_multicam_warns_on_a_camera_with_no_shared_audio_event(self):
- """A camera whose audio has nothing in common with the reference must not align silently."""
- unrelated = OUT / "camC_unrelated.mp4"
- # a flat-envelope tone: nothing for the envelope-based cross-correlation to lock onto,
- # unlike the reference's gated tones -- unrelated in the way a different room's constant hum would be
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30",
- "-f", "lavfi", "-i", "sine=frequency=233:sample_rate=48000", "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", unrelated)
- proc = script("multicam.py", self.src, unrelated, "--offsets-only", "--json")
- data = json.loads(proc.stdout)
- self.assertLess(data["confidence"][1], 0.1)
- self.assertIn("low correlation confidence", proc.stderr)
-
- def test_verify_kit_runs_on_real_world_fixtures(self):
- folder = OUT / "vfx"
- folder.mkdir(exist_ok=True)
- for f in (self.hdr, self.surround, self.vfr):
- (folder / Path(f).name).write_bytes(Path(f).read_bytes())
- report = OUT / "verify.md"
- data = json.loads(script("verify.py", folder, "--quick", "--report", report, "--json").stdout)
- self.assertEqual(data["failed"], 0)
- self.assertEqual(len(data["files"]), 3)
- text = report.read_text()
- self.assertIn("| PASS |", text)
- self.assertNotIn("| FAIL |", text)
- self.assertIn("HDR10/PQ", text)
- script("verify.py", OUT / "does_not_exist", expect_fail=True)
-
- def test_verify_disambiguates_same_named_files_from_different_folders(self):
- """Every file's outputs share one flat --out directory keyed only on stem = outdir /
- f.stem -- two files with the same basename from different subfolders (entirely normal for
- real footage pulled from multiple cameras/SD cards, e.g. two "clip.mp4"s in separate
- campaign folders) used to resolve to the identical output prefix. Each file's own steps
- ran correctly in isolation, but with --keep the second file's outputs silently overwrote
- the first file's on disk, with the report still showing PASS for both and no collision
- ever flagged (same bug class fixed in batch.py). Verify same-named files from different
- folders now get distinct, non-colliding output prefixes."""
- folder = OUT / "verify_collision"
- (folder / "campaignA").mkdir(parents=True, exist_ok=True)
- (folder / "campaignB").mkdir(parents=True, exist_ok=True)
- (folder / "campaignA" / "clip.mp4").write_bytes(Path(self.src).read_bytes())
- (folder / "campaignB" / "clip.mp4").write_bytes(Path(self.src).read_bytes())
- out = OUT / "verify_collision_out"
- data = json.loads(script("verify.py", folder, "--quick", "--keep", "--out", out, "--json").stdout)
- self.assertEqual(len(data["files"]), 2)
- self.assertTrue(all(s["ok"] for f in data["files"] for s in f["steps"]))
- cut_files = sorted(p.name for p in out.glob("clip*_cut.mp4"))
- self.assertEqual(len(cut_files), 2, f"expected two distinct 'cut' outputs, one per same-named source file, got {cut_files}")
- cap_files = sorted(p.name for p in out.glob("clip*_cap.mp4"))
- self.assertEqual(len(cap_files), 2, f"expected two distinct 'caption' outputs, got {cap_files}")
-
- def test_verify_full_plan_hdr_surround_broken_file_and_timeout(self):
- """verify.py's non---quick plan (overlay, look sheet, probe --analyze, loudness, silence,
- color --to-sdr + the HDR-preserved check on an HDR file, --downmix on >2ch audio), the
- "ffprobe failed" row for a file that is not media, the plain-text report path (no --json)
- and the per-step timeout were all unexercised: the two existing verify tests only ran
- --quick --json on good files (#147). A collection with one HDR10 file, one 5.1 file and
- one file of garbage bytes exits 1 (the garbage), while every step on the two real files
- still passes."""
- folder = OUT / "verify_full"
- folder.mkdir(exist_ok=True)
- (folder / Path(self.hdr).name).write_bytes(Path(self.hdr).read_bytes())
- (folder / Path(self.surround).name).write_bytes(Path(self.surround).read_bytes())
- (folder / "broken.mp4").write_bytes(b"this is not a media file\n" * 64)
- out = OUT / "verify_full_out"
- report = OUT / "verify_full.md"
- proc = script("verify.py", folder, "--seconds", "2", "--keep", "--out", out, "--report", report, expect_fail=True)
- text = report.read_text(encoding="utf-8")
- self.assertIn(text.strip(), proc.stdout.strip(), "without --json the report is printed to stdout")
- self.assertIn("| probe | FAIL | 0s | ffprobe failed |", text)
- for step in ("overlay text", "look sheet", "probe analyze", "loudness measure", "silence list",
- "color to-sdr", "hdr preserved", "audio downmix", "export x"):
- self.assertIn(f"| {step} | PASS |", text, f"{step} missing or failed:\n{text}")
- self.assertNotIn("| FAIL |", text.replace("| probe | FAIL | 0s | ffprobe failed |", ""))
- self.assertTrue((out / f"{Path(self.hdr).stem}_sdr.mp4").exists())
- self.assertTrue((out / f"{Path(self.surround).stem}_st.mp4").exists())
- # a per-step timeout is reported per step, never raised
- data = json.loads(script("verify.py", self.src, "--quick", "--timeout", "0.01", "--json", expect_fail=True).stdout)
- self.assertEqual((data["status"], data["error"]["kind"]), ("failed", "verification"))
- timed_out = [s for f in data["files"] for s in f["steps"] if s["error"].startswith("timeout after")]
- self.assertTrue(timed_out, data)
- self.assertEqual(data["failed"], len(timed_out))
-
- def test_progress_and_fast_flags(self):
- out = OUT / "prog.mp4"
- proc = script("fit.py", self.src, "--duration", "6", "--fast", "--progress", "-o", out)
- self.assertIn("%", proc.stderr)
- self.assertIn("-preset veryfast", proc.stderr, "--fast overrides the preset")
- self.assertClose(probe(str(out))["duration"], 6.0, 0.2)
-
- # ---------------------------------------------------------------- colour-flag filter-graph injection (adversarial)
- def test_color_like_flags_refuse_filter_graph_injection(self):
- """Every flag that string-formats a colour straight into a filter graph (color=c=...,
- tpad=...:color=..., rotate=...:fillcolor=..., drawtext=...:fontcolor=..., pad=...:color=...)
- used to accept any string verbatim. Since ffmpeg filter options are comma/colon-delimited,
- a value like "black,drawtext=text=INJECTED" doesn't just set an odd colour -- the comma ends
- the colour filter early and starts an entirely new one, so the payload actually gets burnt
- into the frame (confirmed by rendering it and inspecting the pixels before this fix existed).
- This is a real filter-graph injection, not just a cosmetic validation gap -- every colour-like
- flag across the codebase must refuse anything that isn't a plain colour token."""
- payload = "black,drawtext=text=INJECTED"
- cases = [
- ("pad.py", [self.src, "--start", "1", "--color", payload]),
- ("straighten.py", [self.src, "--degrees", "5", "--fit", "pad", "--fill-color", payload]),
- ("waveform.py", [self.src, "--background", payload]),
- ("waveform.py", [self.src, "--color", payload]),
- ("background.py", ["--duration", "1", "--width", "640", "--height", "360", "--color", payload, "-o", OUT / "bg_inject.mp4"]),
- ("background.py", ["--duration", "1", "--width", "640", "--height", "360", "--gradient", f"{payload}:0x0057ff", "-o", OUT / "bg_inject2.mp4"]),
- ("fit.py", [self.src, "--aspect", "1:1", "--fit", "pad", "--pad-color", payload]),
- ("export.py", [self.src, "--preset", "reels", "--pad-color", payload]),
- ("join.py", [self.src, self.src, "--pad-color", payload]),
- ("overlay.py", [self.src, "--text", "hi", "--font-color", payload]),
- ("overlay.py", [self.src, "--text", "hi", "--border-color", payload]),
- ("overlay.py", [self.src, "--text", "hi", "--box-color", payload]),
- ("overlay.py", [self.src, "--video", self.src, "--chromakey", payload]),
- ]
- for name, argv in cases:
- proc = script(name, *argv, expect_fail=True)
- self.assertIn("colour", proc.stderr, f"{name} {argv}: expected a colour-validation refusal")
-
- def test_color_like_flags_still_accept_real_colors(self):
- script("pad.py", self.src, "--start", "0.5", "--color", "0x101010", "-o", OUT / "colorok1.mp4")
- script("straighten.py", self.src, "--degrees", "5", "--fit", "pad", "--fill-color", "black", "-o", OUT / "colorok2.mp4")
- script("waveform.py", self.src, "--background", "0x101010", "--color", "cyan|magenta", "-o", OUT / "colorok3.mp4")
- script("background.py", "--duration", "1", "--width", "640", "--height", "360", "--gradient", "0xff6a00:0x0057ff", "-o", OUT / "colorok4.mp4")
- script("overlay.py", self.src, "--text", "hi", "--box-color", "[email protected]", "-o", OUT / "colorok5.mp4")
-
- # ---------------------------------------------------------------- font-name filter-graph injection (adversarial)
- @unittest.skipIf(platform.system() == "Windows", "forces the fc-match-missing fallback path by symlinking just "
- "ffmpeg/ffprobe into a stub PATH dir -- os.symlink needs an elevated/dev-mode privilege on "
- "Windows that CI runners don't grant, and default_font_file() doesn't even consult fc-match "
- "there (it resolves a fixed arial.ttf under WINDIR, see its docstring), so this specific "
- "repro doesn't generalise to Windows. The fix itself (escape_drawtext() around the fallback "
- "value) is plain string handling with no OS branch, so it's equally in effect there.")
- def test_font_flag_escapes_filter_graph_injection_when_unresolved(self):
- """overlay.py and graphics.py both accept --font as a family NAME, not a file path, and try
- to resolve it to a concrete file via default_font_file() (fc-match) first -- but that
- resolution returns None whenever fc-match isn't on PATH (always true on some real systems,
- e.g. minimal containers and every Windows build), in which case both tools used to fall back
- to embedding the raw name straight into `font='{args.font}'` with zero escaping. Since
- drawtext=... options are comma/colon-delimited, a value like "X',drawtext=text=OWNED"
- doesn't just set an odd font -- the comma ends the font option (and the whole drawtext
- filter) early and starts an entirely new drawtext filter, which actually rendered (confirmed
- by rendering the pre-fix code and visually inspecting the burnt-in "OWNED" text). Force the
- None-fallback path by hiding fc-match from PATH, exactly as it's naturally absent on some
- real systems, and confirm the built filter graph no longer contains a live breakout."""
- payload = "X',drawtext=text=OWNED:fontcolor=yellow:fontsize=40:x=10:y=10"
- stub_dir = OUT / "no_fc_match_path"
- stub_dir.mkdir(exist_ok=True)
- for exe in ("ffmpeg", "ffprobe"):
- real = shutil.which(exe)
- link = stub_dir / exe
- if not link.exists():
- os.symlink(real, link)
- # Python's own bin dir has to stay on PATH, and on a system-python machine (the Debian
- # container job) that dir is /usr/bin, which also holds the real fc-match -- so "hidden
- # by PATH" was not hidden at all there and the tool resolved a real fontfile= instead of
- # taking the font= fallback this test exists to exercise. A stub fc-match that always
- # fails sits first on PATH so the resolver returns None on every layout.
- if platform.system() != "Windows":
- stub = stub_dir / "fc-match"
- stub.write_text("#!/bin/sh\nexit 1\n", encoding="utf-8")
- stub.chmod(0o755)
- env = dict(os.environ)
- env["PATH"] = os.pathsep.join([str(stub_dir), str(Path(sys.executable).parent)])
-
- out = OUT / "font_inject_overlay.mp4"
- proc = sh(sys.executable, SCRIPTS / "overlay.py", self.src, "--text", "hello", "--font", payload, "-o", out, env=env)
- # The escaped payload must show up with a backslash-escaped comma ahead of the injected
- # "drawtext=text=OWNED" -- proof it stays a literal char inside font='...' instead of
- # closing the option early and starting a sibling filter.
- self.assertIn("\\,drawtext=text=OWNED", proc.stderr, "comma must be escaped so it can't break out of font= into a new filter")
-
- frame = OUT / "font_inject_overlay_frame.png"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", out, "-ss", "1", "-vframes", "1", frame)
- self.assertTrue(frame.exists())
-
- def test_caption_font_with_comma_and_colon_does_not_corrupt_ass_style(self):
- """caption.py's --font flows into two ASS constructs escape_drawtext() was never meant to
- cover: the comma-delimited [V4+ Styles] Style: line (write_ass()), and the comma-separated
- Key=Value list inside a -vf subtitles=...:force_style='...' option. Neither is a drawtext
- filter, so unlike overlay.py/graphics.py this call site used to embed args.font completely
- raw. A font name containing a comma shifts every field after it (size, colours, bold flag,
- alignment, margins) in the Style: line, and a comma or colon inside force_style's FontName=
- breaks the option-list/-vf parsing the same way. Verify a hostile font name survives as an
- inert, field-count-preserving value in both the --write-ass path and the plain SRT-burn
- (force_style) path."""
- hostile_font = "Arial,Bold:evil"
- ass_out = OUT / "font_inject.ass"
- script("caption.py", self.src, "--text", self.cues, "--font", hostile_font, "--animate", "fade", "--write-ass", ass_out, "--fast", "-o", OUT / "font_inject.mp4")
- style_line = next(l for l in ass_out.read_text(encoding="utf-8").splitlines() if l.startswith("Style: Default,"))
- self.assertNotIn(",Arial,Bold:evil,", style_line, "raw hostile font must not appear -- it would shift every later field")
- fields = style_line.split(",")
- self.assertEqual(len(fields), 23, "Style: line must keep its full field count (Format: line lists 23 columns)")
-
- out = OUT / "font_inject_caption.mp4"
- proc = sh(sys.executable, SCRIPTS / "caption.py", self.src, "--text", self.cues, "--font", hostile_font, "-o", out, "--dry-run")
- self.assertNotIn("Arial,Bold:evil", proc.stderr, "hostile font must not reach force_style unsanitised")
-
- def test_caption_ass_dialogue_text_cannot_forge_override_blocks(self):
- """ASS Dialogue text treats a literal `{...}` as an override block -- real style/animation
- commands (\\pos, \\fscx, \\t, ...), not literal characters. Cue text is effectively user-
- controlled (--text cues, an SRT file, or ASR transcription), so cue content containing
- braces used to be interpreted as those commands instead of being read out literally,
- letting a caption reposition/rescale/recolor itself or later text. Verify a hostile cue
- survives as inert text with the override syntax neutralised."""
- hostile_cues = OUT / "brace_inject_cues.txt"
- hostile_cues.write_text("00:00:00 --> 00:00:03 hi {\\pos(0,0)\\fscx500}INJECTED\n", encoding="utf-8")
- ass_out = OUT / "brace_inject.ass"
- # a real (fast) burn: since 1.4.9 --dry-run writes no side files, the generated ASS included
- script("caption.py", self.src, "--text", hostile_cues, "--animate", "fade", "--write-ass", ass_out, "--fast", "-o", OUT / "brace_inject.mp4")
- dialogue = next(l for l in ass_out.read_text(encoding="utf-8").splitlines() if l.startswith("Dialogue: "))
- # --animate fade legitimately prepends its own "{\fad(200,200)}" override block; only the
- # cue-text-derived braces from the hostile payload must be gone.
- self.assertNotIn("{\\pos(0,0)\\fscx500}", dialogue, "cue text must not be able to open a real ASS override block")
- self.assertIn("\\{\\pos(0,0)\\fscx500\\}INJECTED", dialogue,
- "the braces the user typed are ESCAPED (libass \\{ / \\}), not deleted: the cue "
- "reads out exactly what was written and still cannot open an override block")
-
- def test_caption_srt_blank_line_in_cue_text_does_not_split_the_block(self):
- """parse_text_cues() turns a bare '|' into a newline (a documented way to write a two-line
- caption), so a source line with two adjacent pipes ("a||b") produces cue text containing a
- blank line ("a\\n\\nb"). A blank line is SRT's own block separator (index / timecode / text
- / blank / next block) -- writing it raw used to split one cue into two malformed half-
- blocks, the second missing its own index and timecode. Verify the generated SRT still
- parses back as exactly the cues that were written, not more."""
- hostile_cues = OUT / "blank_line_cues.txt"
- hostile_cues.write_text("00:00:00 --> 00:00:03 a||b\n00:00:03 --> 00:00:06 second cue\n", encoding="utf-8")
- srt_out = OUT / "blank_line.srt"
- script("caption.py", "--text", hostile_cues, "--write-srt", srt_out)
- from caption import parse_srt
- cues = parse_srt(str(srt_out))
- self.assertEqual(len(cues), 2, "the blank line inside cue text must not fake a third block boundary")
- self.assertEqual(cues[0][2], "a\nb", "text after the fake blank-line boundary must not be silently dropped")
- self.assertEqual(cues[1][2], "second cue", "the second cue must still have its own timecode/index, not be swallowed as stray text")
-
- def test_caption_malformed_timestamp_falls_back_to_just_the_text_not_the_whole_line(self):
- """TIME_RE can match a line (finding a text portion after the arrow) even when one of the
- two timestamps inside it fails parse_time() (e.g. a malformed "00:00:03.15.999" with a
- stray extra segment). The except ValueError fallback used `line.strip()` -- the entire raw
- line, broken timestamp included -- instead of the already-captured `m.group("text")`, so
- the malformed timestamp string itself got burned into the caption as visible text."""
- cues = OUT / "malformed_timestamp_cues.txt"
- cues.write_text("00:00:00.15.999 --> 00:00:02 Hello there\n", encoding="utf-8")
- srt_out = OUT / "malformed_timestamp.srt"
- script("caption.py", "--text", cues, "--write-srt", srt_out)
- from caption import parse_srt
- parsed = parse_srt(str(srt_out))
- self.assertEqual(len(parsed), 1)
- self.assertEqual(parsed[0][2], "Hello there", "the broken timestamp text must not leak into the caption")
-
- def test_drawtext_semicolon_and_quote_render_as_inert_literal_text(self):
- """Before 1.15 this text went inline into the filtergraph, where two characters had no
- escape that survives every call shape: ';' splits a filterchain exactly like ',', and the
- quote corrupts a -filter_complex chain that uses explicit [label] pads (trailing option
- text leaked into the picture as burnt-in literal text). The old fix dropped the quote and
- escaped the semicolon. 1.15 removes the whole class: the drawn text is handed to drawtext
- as `textfile=<path>:expansion=none`, so the graph parser never sees it -- the quote is now
- KEPT, and nothing can leak into the options. Assert the new route, not the old escape."""
- out = OUT / "semicolon_quote.mp4"
- doc = json.loads(script("overlay.py", self.src, "--text", "a'b;c", "-o", out, "--json").stdout)
- graph = " ".join(doc["commands"])
- m = re.search(r"textfile=(\S+?\.txt)", graph.replace("\\", ""))
- self.assertTrue(m, "drawn text must go through textfile=, not inline: " + graph)
- self.assertIn("expansion=none", graph)
- self.assertNotIn("a\\;c", graph, "no inline escaped copy of the text may remain in the graph")
- # The textfile lives in a private 0700 per-run directory and is removed when the run
- # ends -- assert both, since a world-shared, never-cleaned /tmp directory was the 1.15.0
- # shape. The frame ink below is what proves the characters reached the picture.
- self.assertTrue(Path(m.group(1)).parent.name.startswith("ffmpeg-skill-text-"),
- "drawn text must go in a private per-run directory: " + m.group(1))
- self.assertFalse(Path(m.group(1)).exists(),
- "the drawn-text temp file must not outlive the run")
- self.assertEqual(doc["status"], "completed")
- frame = OUT / "semicolon_quote_frame.png"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", out, "-vframes", "1", frame)
- self.assertTrue(frame.exists())
-
- # ---------------------------------------------------------------- real iPhone regressions (Dolby Vision 8.4 / HLG, VFR, extra tracks)
- def test_hdr_source_stays_hdr_through_reencodes(self):
- # HLG 10-bit HEVC with audio AND a timecode data track, like an iPhone .mov
- hlg = OUT / "hlg_tc.mov"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000",
- "-t", "5", "-vf", "format=yuv420p10le", "-c:v", "libx265", "-preset", "ultrafast",
- "-x265-params", "colorprim=bt2020:transfer=arib-std-b67:colormatrix=bt2020nc:log-level=error", "-tag:v", "hvc1",
- "-c:a", "aac", "-timecode", "01:00:00:00", hlg)
- streams = json.loads(sh("ffprobe", "-v", "error", "-print_format", "json", "-show_streams", hlg).stdout)["streams"]
- self.assertEqual(len(streams), 3, "video + audio + tmcd data track")
- for name, argv in [
- ("cut.py", [hlg, "--start", "1", "--end", "3", "--accurate"]),
- ("fit.py", [hlg, "--aspect", "1:1", "--width", "480"]),
- ("caption.py", [hlg, "--text", self.cues]),
- ("overlay.py", [hlg, "--text", "hdr"]),
- ("silence.py", [hlg]),
- ("join.py", [hlg, hlg, "--transition", "none"]),
- ]:
- out = OUT / f"hdrkeep_{name}.mp4"
- script(name, *argv, "--fast", "-o", out)
- v = probe(str(out))["video"]
- self.assertTrue(v["hdr"], name)
- self.assertEqual((v["codec"], v["pix_fmt"], v["color_transfer"]), ("hevc", "yuv420p10le", "arib-std-b67"), name)
- # tone-mapping and the display path still work on the multi-track file
- sdr = OUT / "hlg_tc_sdr.mp4"
- script("color.py", hlg, "--to-sdr", "--fast", "-o", sdr)
- self.assertFalse(probe(str(sdr))["video"]["hdr"])
- proc = script("look.py", hlg, "--at", "1", "-o", OUT / "hlgframe")
- self.assertIn("tone-mapped", proc.stderr)
- self.assertTrue((OUT / "hlgframe_1.000s.png").exists())
- # 10-bit levels are reported on an 8-bit scale, so a normal HDR clip is not called Log
- data = json.loads(script("probe.py", hlg, "--analyze").stdout)
- self.assertLessEqual(data["levels"]["y_max"], 255)
- self.assertFalse(data["levels"]["looks_like_log"])
-
- # ---------------------------------------------------------------- v0.5: check / scenes / render
- def test_codec_and_quality_resolve_in_one_place(self):
- """1.8 (issue #189 B pre-shipped): --codec / --quality on every re-encoding tool, resolved by
- encoder_args(). hevc on SDR is 8-bit BT.709 HEVC; prores needs a .mov; h264 refuses HDR;
- --quality is the CRF; export keeps its presets; without --codec nothing changes."""
- sys.path.insert(0, str(SCRIPTS))
- try:
- import _common
- finally:
- sys.path.pop(0)
- out = OUT / "codec_hevc.mp4"
- d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "hevc", "--quality", "30", "-o", out, "--fast", "--json", "--overwrite").stdout)
- self.assertEqual(d["status"], "completed")
- m = probe(str(out))
- self.assertEqual(m["video"]["codec"], "hevc")
- self.assertIn("yuv420p", m["video"].get("pix_fmt", "yuv420p"))
- self.assertTrue(any("-crf 30" in c for c in d["commands"]), d["commands"])
- # prores wants a .mov: .mp4 is refused before ffmpeg runs, .mov works
- d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "prores", "-o", OUT / "codec_prores.mp4", "--json", expect_fail=True).stdout)
- self.assertEqual(d["error"]["kind"], "input")
- self.assertIn(".mov", d["error"]["hint"])
- mov = OUT / "codec_prores.mov"
- script("fit.py", self.src, "--width", "320", "--codec", "prores", "-o", mov, "--fast", "--json", "--overwrite")
- self.assertEqual(probe(str(mov))["video"]["codec"], "prores")
- # h264 cannot carry HDR; hevc keeps it
- d = json.loads(script("fit.py", self.hdr, "--width", "320", "--codec", "h264", "-o", OUT / "codec_hdr_h264.mp4", "--json", expect_fail=True).stdout)
- self.assertEqual(d["error"]["kind"], "input")
- self.assertIn("to-sdr", d["error"]["hint"])
- hdr_out = OUT / "codec_hdr_hevc.mp4"
- script("fit.py", self.hdr, "--width", "320", "--codec", "hevc", "-o", hdr_out, "--fast", "--json", "--overwrite")
- self.assertTrue(probe(str(hdr_out))["video"]["hdr"])
- # av1 when the build has an encoder, a missing_tool refusal otherwise
- av1 = OUT / "codec_av1.mp4"
- proc = script("fit.py", self.src, "--width", "320", "--codec", "av1", "-o", av1, "--fast", "--json", "--overwrite", expect_fail=not (_common.ffmpeg_encoders() & {"libsvtav1", "libaom-av1"}))
- d = json.loads(proc.stdout)
- if d["status"] == "completed":
- self.assertEqual(probe(str(av1))["video"]["codec"], "av1")
- else:
- self.assertEqual(d["error"]["kind"], "missing_tool")
- # --quality bounds follow the codec; export refuses --codec
- d = json.loads(script("fit.py", self.src, "--width", "320", "--quality", "60", "-o", out, "--json", expect_fail=True).stdout)
- self.assertEqual(d["error"]["kind"], "input")
- proc = script("export.py", self.src, "--preset", "x", "--codec", "hevc", "-o", OUT / "codec_export.mp4", "--json", expect_fail=True)
- self.assertIn("--codec", proc.stderr) # argparse: the preset decides, the flag is not offered (review 7)
- self.assertNotIn("--codec", script("export.py", "--help").stdout)
- # review 7: prores without -o would have failed inside ffmpeg (mp4 cannot hold it)
- d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "prores", "--json", expect_fail=True).stdout)
- self.assertEqual(d["error"]["kind"], "input")
- self.assertIn("-o NAME.mov", d["error"]["hint"])
- # review 7: cut's lossless path used to keep the source codec under --codec
- cutout = OUT / "codec_cut.mp4"
- script("cut.py", self.src, "--start", "0", "--end", "2", "--codec", "hevc", "-o", cutout, "--fast", "--json", "--overwrite")
- self.assertEqual(probe(str(cutout))["video"]["codec"], "hevc")
- # review 7: waveform.py built its own x264 line and ignored the flag
- wf = OUT / "codec_wave.mp4"
- script("waveform.py", self.src, "--codec", "hevc", "-o", wf, "--fast", "--json", "--overwrite") # source.mp4: c_tone.wav is a test_contract fixture
- self.assertEqual(probe(str(wf))["video"]["codec"], "hevc")
- # review 7: the av1 bound is named in the --crf message, and HDR hevc --quality 51 does not overflow
- d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "av1", "--crf", "70", "-o", out, "--json", expect_fail=True).stdout)
- self.assertIn("63", d["error"]["message"])
- sys.path.insert(0, str(SCRIPTS))
- try:
- import _common as c
- finally:
- sys.path.pop(0)
- args = c.encoder_args("hevc", 51, "medium", {"video": {"hdr": True, "color_transfer": "smpte2084"}})
- self.assertEqual(args[args.index("-crf") + 1], "51")
- self.assertNotIn("-colorspace", c.encoder_args("hevc", 18, "medium", None, keep_bt709=False))
- # the contract lists each --codec encoder once per tool
- spec = json.loads(script("_contract.py", "--json").stdout)
- fit_caps = [o["capability"] for o in next(t for t in spec["tools"] if t["name"] == "fit")["capabilities"]["optional"]]
- self.assertEqual(len(fit_caps), len(set(fit_caps)), fit_caps)
- self.assertNotIn("codec", next(t for t in spec["tools"] if t["name"] == "export")["input_schema"]["properties"])
- # no --codec: the old default line, byte for byte
- d = json.loads(script("fit.py", self.src, "--width", "320", "-o", out, "--fast", "--json", "--overwrite").stdout)
- self.assertTrue(any("libx264" in c for c in d["commands"]))
- # every tool that declares --crf now advertises the two flags
- for name in ("cut", "caption", "overlay", "color", "join", "proxy"):
- h = script(f"{name}.py", "--help").stdout
- self.assertIn("--codec", h, name)
- self.assertIn("--quality", h, name)
-
- def test_check_compliance(self):
- reels = OUT / "export_reels.mp4"
- if not reels.exists():
- script("export.py", self.src, "--preset", "reels", "--fit", "crop", "-o", reels)
- data = json.loads(script("check.py", reels, "--platform", "reels", "--json", expect_fail=True).stdout)
- # a failed check is a failed run: status says so (before 1.4.3 it said "completed" next to exit 1)
- self.assertEqual((data["status"], data["error"]["kind"], data["error"]["code"]), ("failed", "verification", "VERIFICATION_FAILED"))
- self.assertFalse(data["ok"])
- names = {r["check"]: r["status"] for r in data["checks"]}
- kinds = {r["check"]: r["kind"] for r in data["checks"]}
- self.assertEqual(kinds["loudness"], "judgement")
- self.assertEqual(kinds["video codec"], "format")
- self.assertIn("ambience", [r["fix"] for r in data["checks"] if r["check"] == "loudness"][0])
- self.assertEqual(names["aspect"], "PASS")
- self.assertEqual(names["pixel format"], "PASS")
- self.assertEqual(names["loudness"], "FAIL", "unnormalised test tone is far from -14 LUFS")
- self.assertFalse(data["ok"])
- # FAILs a non-technical caller would ask "so what?" about carry a plain-language reason,
- # distinct from `fix` (the command); PASS rows never carry one
- loudness_row = [r for r in data["checks"] if r["check"] == "loudness"][0]
- self.assertTrue(loudness_row["reason"])
- self.assertNotEqual(loudness_row["reason"], loudness_row["fix"])
- pass_rows = [r for r in data["checks"] if r["status"] == "PASS"]
- self.assertTrue(pass_rows)
- self.assertTrue(all(r["reason"] == "" for r in pass_rows))
- # after loudness.py the same file passes
- norm = OUT / "reels_norm.mp4"
- script("loudness.py", reels, "-o", norm)
- data = json.loads(script("check.py", norm, "--platform", "reels", "--json").stdout)
- self.assertTrue(data["ok"], [r for r in data["checks"] if r["status"] != "PASS"])
- # HDR on an SDR-only platform fails the colour check
- data = json.loads(script("check.py", self.hdr, "--platform", "x", "--no-loudness", "--json", expect_fail=True).stdout)
- colour_row = [r for r in data["checks"] if r["check"] == "colour"][0]
- self.assertEqual(colour_row["status"], "FAIL")
- self.assertTrue(colour_row["reason"])
- # custom overrides
- data = json.loads(script("check.py", self.src, "--platform", "custom", "--max-duration", "5", "--no-loudness", "--json", expect_fail=True).stdout)
- self.assertEqual({r["check"]: r["status"] for r in data["checks"]}["duration"], "FAIL")
-
- def test_check_without_a_platform_reports_judgement_rows_as_warn(self):
- """Eval 7: runs that only wanted the format rows got youtube's loudness / true-peak FAILs
- (the default platform) and explained at length why they left them alone. Without a
- named platform those rows are advisory: WARN, exit 0, and a notes line says so."""
- data = json.loads(script("check.py", self.src, "--json").stdout)
- self.assertEqual(data["status"], "completed")
- self.assertTrue(data["ok"])
- self.assertEqual(data["failed"], 0)
- rows = {r["check"]: r for r in data["checks"]}
- self.assertEqual(rows["true peak"]["status"], "WARN")
- self.assertEqual(rows["loudness"]["kind"], "judgement")
- self.assertEqual(rows["true peak"]["kind"], "judgement")
- self.assertTrue(any("no --platform" in n for n in data["notes"]))
- # the same file with the platform named is the same FAIL as before
- data = json.loads(script("check.py", self.src, "--platform", "youtube", "--json", expect_fail=True).stdout)
- self.assertFalse(data["ok"])
- self.assertNotIn("notes", data)
-
- def test_render_export_normalize_forwards_the_flag(self):
- proj = OUT / "project_normalize.json"
- proj.write_text(json.dumps({
- "output": "render_normalize.mp4",
- "clips": [{"src": "source.mp4"}],
- "export": {"preset": "x", "normalize": True},
- "check": {"platform": "x"},
- }), encoding="utf-8")
- data = json.loads(script("render.py", proj, "--fast", "--json").stdout)
- self.assertTrue(data["check"]["ok"], data["check"])
- rows = {r["check"]: r["status"] for r in data["check"]["checks"]}
- self.assertEqual(rows["loudness"], "PASS", "the -9 LUFS source (whole clip: a 2 s slice happens to sit at -13 LUFS) only passes when export ran --normalize")
- # 1.9: a platform preset with no loudness stage normalises by default; false opts out
- proj.write_text(json.dumps({
- "output": "render_normalize_default.mp4",
- "clips": [{"src": "source.mp4"}],
- "export": {"preset": "x"},
- "check": {"platform": "x"},
- }), encoding="utf-8")
- data = json.loads(script("render.py", proj, "--fast", "--json").stdout)
- self.assertEqual({r["check"]: r["status"] for r in data["check"]["checks"]}["loudness"], "PASS")
- proj.write_text(json.dumps({
- "output": "render_normalize_off.mp4",
- "clips": [{"src": "source.mp4"}],
- "export": {"preset": "x", "normalize": False},
- "check": {"platform": "x"},
- }), encoding="utf-8")
- data = json.loads(script("render.py", proj, "--fast", "--json", expect_fail=True).stdout)
- self.assertEqual({r["check"]: r["status"] for r in data["check"]["checks"]}["loudness"], "FAIL")
-
- def test_check_unmeasurable_loudness_warns_instead_of_silently_passing(self):
- """measure_loudness() returns {} when ffmpeg's loudnorm JSON doesn't parse out of stderr
- (malformed/unexpected output). main() used to gate the loudness/true-peak rows entirely on
- `if lm:`, so a measurement failure meant those rows were never appended at all -- not FAIL,
- not WARN, just absent -- and check.py would still report an overall PASS for a platform
- with a loudness requirement it never actually verified. A silent false PASS is worse than a
- crash for a compliance tool. Verify a forced measurement failure surfaces as WARN rows,
- not a vanished check."""
- from unittest.mock import patch
- sys.path.insert(0, str(SCRIPTS))
- import check
- with patch.object(check, "measure_loudness", return_value={}):
- buf = __import__("io").StringIO()
- import contextlib
- with contextlib.redirect_stdout(buf):
- sys.argv = ["check.py", str(self.src), "--platform", "youtube", "--json"]
- check.main()
- data = json.loads(buf.getvalue())
- statuses = {r["check"]: r["status"] for r in data["checks"]}
- self.assertIn("loudness", statuses, "an unmeasurable loudness check must still appear in the report")
- self.assertIn("true peak", statuses)
- self.assertEqual(statuses["loudness"], "WARN")
- self.assertEqual(statuses["true peak"], "WARN")
-
- def test_scenes_and_highlights(self):
- src = OUT / "scenes_src.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30:d=4", "-f", "lavfi", "-i", "smptebars=size=640x360:rate=30:d=4",
- "-f", "lavfi", "-i", "mandelbrot=size=640x360:rate=30",
- "-f", "lavfi", "-i", "aevalsrc='0.6*sin(2*PI*440*t)*between(t\\,5\\,7)+0.3*sin(2*PI*330*t)*between(t\\,9\\,10)':s=48000",
- "-filter_complex", "[2:v]trim=0:4,setpts=PTS-STARTPTS[m];[0:v][1:v][m]concat=n=3:v=1:a=0[v]",
- "-map", "[v]", "-map", "3:a", "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", src)
- edl = OUT / "picks.txt"
- sheet = OUT / "scenes.png"
- data = json.loads(script("scenes.py", src, "--highlights", "2", "--target", "6", "--edl", edl, "--sheet", sheet, "--json").stdout)
- self.assertEqual(data["scene_count"], 3)
- self.assertEqual([round(sc["start"]) for sc in data["scenes"]], [0, 4, 8])
- self.assertEqual(len(data["highlights"]), 2)
- self.assertClose(data["highlights_total"], 6.0, 0.6)
- # the loudest pick must cover the 5-7 s tone
- self.assertTrue(any(h["start"] <= 5.5 and h["end"] >= 6.5 for h in data["highlights"]), data["highlights"])
- self.assertTrue(sheet.exists())
- self.assertGreater(png_size(sheet)[0], 1200, "three tiles across")
- # EDL feeds cut.py
- segs = ",".join(edl.read_text().split())
- out = OUT / "digest.mp4"
- script("cut.py", src, "--segments", segs, "--accurate", "--fast", "-o", out)
- self.assertClose(probe(str(out))["duration"], 6.0, 0.6)
-
- def test_scenes_rank_by_duration_picks_longest_scenes_not_loudest(self):
- src = OUT / "scenes_rank_src.mp4"
- # three scenes: 2s, 6s (longest, silent), 4s (loud tone) -- audio and duration ranking must disagree
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30:d=2", "-f", "lavfi", "-i", "smptebars=size=640x360:rate=30:d=6",
- "-f", "lavfi", "-i", "mandelbrot=size=640x360:rate=30",
- "-f", "lavfi", "-i", "aevalsrc='0.6*sin(2*PI*440*t)*between(t\\,8\\,11)':s=48000",
- "-filter_complex", "[2:v]trim=0:4,setpts=PTS-STARTPTS[m];[0:v][1:v][m]concat=n=3:v=1:a=0[v]",
- "-map", "[v]", "-map", "3:a", "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", src)
- by_audio = json.loads(script("scenes.py", src, "--highlights", "1", "--json").stdout)
- by_duration = json.loads(script("scenes.py", src, "--highlights", "1", "--rank-by", "duration", "--json").stdout)
- self.assertEqual(by_audio["highlights_rank_by"], "audio")
- self.assertEqual(by_duration["highlights_rank_by"], "duration")
- # audio ranking picks the loud scene (8-11s window, inside scene 3 at 8-12s)
- self.assertTrue(any(h["start"] >= 7.5 for h in by_audio["highlights"]), by_audio["highlights"])
- # duration ranking picks the longest (silent) scene, which starts at 2s
- self.assertTrue(any(round(h["start"]) == 2 for h in by_duration["highlights"]), by_duration["highlights"])
-
- def test_render_project(self):
- proj = OUT / "project.json"
- proj.write_text(json.dumps({
- "output": "render_final.mp4",
- "frame": {"aspect": "9:16", "width": 720, "fps": 30},
- "clips": [{"src": "source.mp4", "in": "0:01", "out": "0:05"}, {"src": "source.mp4", "in": 6, "out": 10, "speed": 1.25}],
- "transition": {"type": "fade", "duration": 0.5},
- "captions": {"text": "cues.txt", "animate": "pop", "karaoke": True, "size": 26},
- "overlays": [{"text": "render test", "position": "top-left", "start": 0.5, "end": 3, "fade": 0.3, "box": True}],
- "audio": {"music": "long_ref.wav", "music_volume": -20, "duck": True, "fade_out": 1},
- "loudness": {"lufs": -14, "tp": -1},
- "export": {"preset": "reels"},
- "check": {"platform": "reels"},
- }), encoding="utf-8")
- if not (OUT / "cues.txt").exists():
- (OUT / "cues.txt").write_text("0:00-0:03 Hello world\n", encoding="utf-8")
- (OUT / "render_final.mp4").unlink(missing_ok=True)
- plan = json.loads(script("render.py", proj, "--dry-run", "--json").stdout)
- self.assertTrue(plan["dry_run"])
- self.assertFalse((OUT / "render_final.mp4").exists())
- data = json.loads(script("render.py", proj, "--fast", "--json").stdout)
- self.assertEqual(data["stages"], ["clips", "join", "fit", "captions", "overlays", "audio", "loudness", "export", "check"])
- self.assertTrue(data["check"]["ok"], data["check"])
- m = probe(str(OUT / "render_final.mp4"))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (1080, 1920))
- self.assertClose(m["duration"], 4 + 3.2 - 0.5, 0.4)
- self.assertEqual(list(OUT.glob("render_final_work*")), [], "work dir removed when not kept")
- init = OUT / "init.json"
- script("render.py", "--init", init)
- self.assertIn("clips", json.loads(init.read_text()))
- # --stop-after keeps the intermediate
- out = json.loads(script("render.py", proj, "--fast", "--stop-after", "join", "--work", OUT / "rw", "--json").stdout)
- self.assertEqual(out["stages"], ["clips", "join"])
- self.assertTrue(Path(out["output"]).exists())
-
- def test_render_every_stage_flag_and_every_refusal(self):
- """render.py's stage branches that test_render_project does not take (silence, captions
- from srt/ass, graphics, image and logo overlays, audio replace/loop/stereo/mono/downmix,
- export fit/crf, brand forwarding, the no-export copy path) and its refusals (no project,
- unreadable project, empty clips, captions/graphics/overlays without their required key,
- a child script failing) were untested (#147). --dry-run drives every argv-building branch
- without encoding; the copy path and the child failure run for real on a 2 s clip."""
- srt = OUT / "render_full.srt"
- srt.write_text("1\n00:00:00,000 --> 00:00:01,500\nHello\n\n", encoding="utf-8")
- ass = OUT / "render_full.ass"
- logo = OUT / "render_full_logo.png"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=red:s=64x64:d=1", "-frames:v", "1", logo)
- brand = OUT / "render_full_brand.json"
- brand.write_text(json.dumps({"logo": logo.name, "logo_position": "top-right", "colors": {"primary": "FF6A00", "text": "FFFFFF"}}), encoding="utf-8")
- full = {
- "output": "render_full.mp4",
- "brand": brand.name,
- "clips": [{"src": "source.mp4", "in": 0, "out": 2}, {"src": "source.mp4", "in": 2, "out": 4}],
- "frame": {"width": 640, "height": 360, "fps": 25},
- "fit": {"duration": 3.5, "method": "trim"},
- "captions": {"srt": srt.name, "font": "DejaVu Sans", "position": "top", "bold": True, "box": True},
- "graphics": [{"template": "lower-third", "name": "Ada", "title": "Analyst", "start": 0, "end": 2},
- {"template": "title", "title": "T", "subtitle": "S", "start": 0, "end": 1, "position": "top-left"}],
- "overlays": [{"image": logo.name, "position": "bottom-right", "opacity": 0.5, "scale": 80},
- {"logo": True, "start": 0, "end": 1},
- {"text": "txt", "font_size": 24, "margin": 12, "box": True}],
- "audio": {"replace": "long_ref.wav", "music_volume": -12, "gain": 1, "music_loop": True, "stereo": True, "denoise": True},
- "loudness": {"lufs": -16},
- "export": {"preset": "youtube", "fit": "pad", "crf": 20},
- }
- proj = OUT / "render_full.json"
- proj.write_text(json.dumps(full), encoding="utf-8")
- proc = script("render.py", proj, "--dry-run", "--json")
- plan = json.loads(proc.stdout)
- self.assertEqual(plan["stages"], ["clips", "join", "fit", "captions", "graphics", "overlays", "audio", "loudness", "export"])
- forwarded = "\n".join(l for l in proc.stderr.splitlines() if l.startswith("→ ")) # render's own child invocations
- for needle in ("--srt", "--template lower-third", "--image", "--logo", "--replace", "--music-loop", "--fit pad --crf 20", "--brand"):
- self.assertIn(needle, forwarded, f"{needle} not forwarded:\n{forwarded}")
- for stage in ("fit", "captions", "graphics", "overlays", "audio", "loudness"):
- out = json.loads(script("render.py", proj, "--dry-run", "--stop-after", stage, "--json").stdout)
- self.assertEqual(out["stages"][-1], stage)
- # single uncut clip (so silence.py can analyse a real file under --dry-run), silence stage,
- # captions from .ass, mono/downmix/duck audio, voice flag: the other branches of the same tables
- alt = dict(full, clips=[{"src": "source.mp4"}], silence={"threshold": -40, "min_silence": 0.4, "margin": 0.1},
- captions={"ass": ass.name}, audio={"music": "long_ref.wav", "mono": True, "downmix": True, "duck": True, "voice": True, "duck_amount": 8}, graphics=[], overlays=[])
- ass.write_text("[Script Info]\nScriptType: v4.00+\n\n[Events]\nFormat: Layer, Start, End, Style, Text\nDialogue: 0,0:00:00.00,0:00:01.00,Default,hi\n", encoding="utf-8")
- (OUT / "render_full_alt.json").write_text(json.dumps(alt), encoding="utf-8")
- proc = script("render.py", OUT / "render_full_alt.json", "--dry-run", "--json")
- self.assertEqual(json.loads(proc.stdout)["stages"], ["clips", "silence", "fit", "captions", "audio", "loudness", "export"])
- forwarded = "\n".join(l for l in proc.stderr.splitlines() if l.startswith("→ "))
- for needle in ("--ass", "--min-silence 0.4", "--mono", "--downmix", "--duck-amount 8", "--voice"):
- self.assertIn(needle, forwarded, f"{needle} not forwarded:\n{forwarded}")
- out = json.loads(script("render.py", OUT / "render_full_alt.json", "--dry-run", "--stop-after", "silence", "--json").stdout)
- self.assertEqual(out["stages"], ["clips", "silence"])
- # no export block: the last stage is copied to the output, for real
- copy_proj = OUT / "render_copy.json"
- copy_proj.write_text(json.dumps({"output": "render_copy.mp4", "clips": [{"src": "source.mp4", "in": 0, "out": 2}]}), encoding="utf-8")
- data = json.loads(script("render.py", copy_proj, "--fast", "--json").stdout)
- self.assertEqual(data["stages"], ["clips"])
- self.assertClose(probe(str(OUT / "render_copy.mp4"))["duration"], 2.0, 0.3)
- # refusals: each names its cause and exits non-zero
- cases = {
- "no_project": ([], "give a project.json"),
- "unreadable": ([OUT / "render_missing.json"], "cannot read project"),
- "empty_clips": ([self._proj("render_e1.json", {"clips": []})], "clips is empty"),
- "captions_key": ([self._proj("render_e2.json", {"clips": full["clips"], "captions": {"size": 20}}), "--dry-run"], "captions needs text, srt or ass"),
- "graphics_key": ([self._proj("render_e3.json", {"clips": full["clips"], "graphics": [{"name": "x"}]}), "--dry-run"], "needs a template"),
- "overlay_key": ([self._proj("render_e4.json", {"clips": full["clips"], "overlays": [{"opacity": 1}]}), "--dry-run"], "needs image or text"),
- "child_failed": ([self._proj("render_e5.json", {"clips": [{"src": "source.mp4", "in": "not-a-time", "out": 2}]}), "--dry-run"], "cut.py failed"),
- }
- for name, (argv, message) in cases.items():
- proc = script("render.py", *argv, expect_fail=True)
- self.assertIn(message, proc.stderr, f"{name}: {proc.stderr[-400:]}")
-
- def _proj(self, name, body):
- p = OUT / name
- p.write_text(json.dumps(dict({"output": name.replace(".json", ".mp4")}, **body)), encoding="utf-8")
- return p
-
- def test_render_refuses_an_unknown_project_key_naming_the_nearest_valid_one(self):
- """Review 9: a project was read with dict.get only, so a mistyped key was silently
- ignored -- a clip "start"/"end" (the spelling graphics and overlays use for their own
- times) rendered the whole clip untrimmed, and "exports" dropped the export stage, both
- reported as a successful render. Every key of the project and of each stage/clip object
- is now checked, and the template still validates."""
- cases = {
- "clip_key": ({"clips": [{"src": "source.mp4", "start": 0, "end": 2}], "export": {"preset": "reels"}},
- "clips[0]: unknown key 'start' (did you mean 'in'?)"),
- "stage_key": ({"clips": [{"src": "source.mp4", "in": 0, "out": 2}], "exports": {"preset": "reels"}},
- "project: unknown key 'exports' (did you mean 'export'?)"),
- "nested_key": ({"clips": [{"src": "source.mp4"}], "export": {"preset": "reels", "quality": 20}},
- "export: unknown key 'quality'"),
- }
- for name, (body, message) in cases.items():
- proc = script("render.py", self._proj(f"render_key_{name}.json", body), "--dry-run", "--json", expect_fail=True)
- self.assertIn(message, proc.stderr, f"{name}: {proc.stderr[-400:]}")
- doc = json.loads(proc.stdout)
- self.assertEqual((doc["status"], doc["error"]["kind"]), ("failed", "input"))
- tmpl = OUT / "render_template_valid.json"
- script("render.py", "--init", tmpl)
- proc = script("render.py", tmpl, "--dry-run", expect_fail=True) # only REPLACE_ME.mp4 is missing
- self.assertIn("source not found", proc.stderr)
- self.assertNotIn("unknown key", proc.stderr)
-
- def test_emit_and_die_use_the_ctx_they_were_given_for_the_plan(self):
- """Review 9: run()/emit()/die() took ctx= but write_plan() and the atexit hook still read
- STATE -- emit(ctx=...) wrote an empty plan while reporting one, and die(ctx=...) let the
- hook write a plan for a failed run."""
- code = (
- "import sys, atexit, json\n"
- f"sys.path.insert(0, {str(SCRIPTS)!r})\n"
- "import _common as c\n"
- "atexit.register(c._plan_at_exit)\n"
- "mode, src, plan = sys.argv[1], sys.argv[2], sys.argv[3]\n"
- "ctx = c.Context(); ctx.json = True; ctx.dry_run = True; ctx.plan = plan\n"
- "c.STATE.plan = plan\n"
- "c.run(['/usr/bin/ffmpeg', '-i', src, '-t', '1', src + '.out.mp4'], ctx=ctx)\n"
- "if mode == 'emit':\n"
- " c.emit(None, ctx=ctx)\n"
- "else:\n"
- " c.die('boom', ctx=ctx)\n"
- )
- src = str(OUT / "source.mp4")
- plan = OUT / "ctx_plan.json"
- sh(sys.executable, "-c", code, "emit", src, plan)
- doc = json.loads(plan.read_text(encoding="utf-8"))
- self.assertEqual(len(doc["commands"]), 1, doc)
- self.assertIn("ffmpeg", doc["commands"][0])
- plan2 = OUT / "ctx_plan_die.json"
- if plan2.exists():
- plan2.unlink()
- proc = sh(sys.executable, "-c", code, "die", src, plan2, expect_fail=True)
- self.assertIn("boom", proc.stderr)
- self.assertFalse(plan2.exists(), "die() left a plan behind for a failed run")
-
- def test_render_default_work_dir_is_unique_per_process(self):
- """The default work dir name came only from the output path (e.g. "out_work"), no PID or
- timestamp -- two concurrent render.py runs targeting the same output (a batch.py "project"
- recipe processing files in parallel, or simply two runs by mistake) shared the same work
- directory and clobbered each other's same-named intermediates (clip00.mp4, fit.mp4, ...)
- mid-run. Verify the auto-derived work dir name includes this process's own PID."""
- proj = OUT / "project_workdir.json"
- proj.write_text(json.dumps({"output": "render_workdir_check.mp4", "clips": [{"src": "source.mp4", "in": 0, "out": 2}]}), encoding="utf-8")
- # --keep leaves the PID-suffixed dir behind, so a second run of this suite in the same
- # OUT (a local re-run, or a coverage pass) would count the previous run's dir too.
- for stale in OUT.glob("render_workdir_check_work*"):
- if stale.is_dir():
- shutil.rmtree(stale)
- out = json.loads(script("render.py", proj, "--fast", "--stop-after", "clips", "--keep", "--json").stdout)
- self.assertEqual(out["stages"], ["clips"])
- work_dirs = [p for p in OUT.glob("render_workdir_check_work*") if p.is_dir()]
- self.assertEqual(len(work_dirs), 1)
- self.assertRegex(work_dirs[0].name, r"^render_workdir_check_work_\d+$",
- "the default work dir name must carry a PID suffix, not just the bare output stem")
-
- def test_render_single_clip_fit_height_is_not_silently_dropped(self):
- """The single-clip fit path only ever inherited width/fps from project.frame, and the
- flag-forwarding list that turns project.fit's own keys into fit.py argv omitted height
- entirely -- so a project.json specifying "fit": {"height": N} (with no other fit key)
- used to build fit.py argv with nothing in it at all ("nothing to do" crash), and combined
- with another fit key (e.g. duration) the height silently never reached fit.py -- the
- output's height was left unchanged with no error. Verify height alone now actually
- resizes a single-clip render."""
- proj = OUT / "project_height.json"
- proj.write_text(json.dumps({
- "output": "render_height.mp4",
- "clips": [{"src": "source.mp4", "in": "0:01", "out": "0:04"}],
- "fit": {"height": 480},
- }), encoding="utf-8")
- script("render.py", proj, "--fast", "--json")
- m = probe(str(OUT / "render_height.mp4"))
- self.assertEqual(m["video"]["height"], 480)
-
- def test_render_frame_aspect_takes_the_export_presets_size(self):
- """Eval 7 (j08 twice, e01 by hand): "frame": {"aspect": "9:16"} with a reels export fitted
- a 1280x720 source to 406x720, captions were burned there and export.py upscaled them
- soft. When the export preset names a delivery frame of the same aspect, the fit stage
- uses it; a preset of another shape (or an explicit width/height) is left alone."""
- proj = OUT / "project_aspect.json"
- work = OUT / "render_aspect_work"
- proj.write_text(json.dumps({
- "output": "render_aspect.mp4",
- "clips": [{"src": "source.mp4", "in": "0:01", "out": "0:03"}],
- "frame": {"aspect": "9:16"},
- "export": {"preset": "reels"},
- }), encoding="utf-8")
- script("render.py", proj, "--fast", "--json", "--work", work, "--keep")
- m = probe(str(work / "fit.mp4"))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (1080, 1920))
- sys.path.insert(0, str(SCRIPTS))
- try:
- import render
- finally:
- sys.path.pop(0)
- frame = {"aspect": "1:1"}
- render.frame_from_preset(frame, {"preset": "reels"})
- self.assertEqual(frame, {"aspect": "1:1"})
- frame = {"aspect": "9:16", "width": 540}
- render.frame_from_preset(frame, {"preset": "reels"})
- self.assertEqual(frame, {"aspect": "9:16", "width": 540})
-
- def test_export_normalize_meets_the_platform_loudness_in_one_call(self):
- """Eval 7: every platform job ran export -> loudness.py -> export again. --normalize runs
- the levels pass on the written file (audio only) so one export delivers the spec."""
- out = OUT / "export_normalize.mp4"
- proc = script("export.py", OUT / "source.mp4", "--preset", "x", "--normalize", "-o", out, "--fast", "--json", "--overwrite")
- d = json.loads(proc.stdout)
- self.assertEqual(d["status"], "completed")
- self.assertTrue(d["loudness"]["ok"], d["loudness"])
- self.assertTrue(d["loudness"]["normalized"])
- self.assertTrue(d["verified"])
- self.assertAlmostEqual(d["loudness"]["lufs"], -14.0, delta=1.0)
- self.assertFalse((OUT / "export_normalize_loudnorm.mp4").exists())
- self.assertTrue(any("linear=true" in c for c in d["commands"]), "the normalising encode is in the command log (review 7)")
- # review 7 P0: a real <output>_loudnorm.<ext> next to the export survives --normalize
- precious = OUT / "export_normalize_loudnorm.mp4"
- precious.write_bytes(b"PRECIOUS")
- try:
- script("export.py", OUT / "source.mp4", "--preset", "x", "--normalize", "-o", out, "--fast", "--json", "--overwrite")
- self.assertEqual(precious.read_bytes(), b"PRECIOUS")
- finally:
- precious.unlink()
- # --normalize on a preset without a loudness spec is refused; under --dry-run it says what it would do
- d = json.loads(script("export.py", OUT / "source.mp4", "--preset", "h265", "--normalize", "-o", OUT / "export_norm_h265.mp4", "--json", expect_fail=True).stdout)
- self.assertEqual(d["error"]["kind"], "input")
- d = json.loads(script("export.py", OUT / "source.mp4", "--preset", "x", "--normalize", "-o", out, "--dry-run", "--json").stdout)
- self.assertTrue(any("--normalize" in n for n in d.get("notes", [])), d)
- # without the flag the same file is reported, not fixed
- proc = script("export.py", OUT / "source.mp4", "--preset", "x", "-o", out, "--fast", "--json", "--overwrite")
- d = json.loads(proc.stdout)
- self.assertFalse(d["loudness"]["ok"])
- self.assertNotIn("normalized", d["loudness"])
- self.assertIn("--normalize", " ".join(d["notes"]))
-
- def test_render_exits_nonzero_when_the_check_stage_fails(self):
- """A render whose deliverable fails its own check stage must not report success."""
- proj = OUT / "project_bad_check.json"
- proj.write_text(json.dumps({
- "output": "render_bad.mp4",
- "clips": [{"src": "source.mp4", "in": "0:01", "out": "0:04"}],
- "export": {"preset": "reels"}, # portrait 9:16 output
- "check": {"platform": "broadcast"}, # broadcast requires 16:9 -- guaranteed aspect FAIL
- }), encoding="utf-8")
- proc = script("render.py", proj, "--fast", "--json", expect_fail=True)
- data = json.loads(proc.stdout)
- self.assertGreater(data["check"]["failed"], 0, data["check"])
- self.assertEqual((data["status"], data["error"]["kind"]), ("failed", "verification"))
- self.assertIn("aspect", data["error"]["message"])
- self.assertTrue(Path(data["output"]).exists(), "the deliverable is still written even though it fails delivery spec")
- # the outer --timeout reaches every stage: an impossible limit fails inside the first stage
- proc = script("render.py", proj, "--fast", "--timeout", "0.05", "--json", expect_fail=True)
- self.assertIn("time limit", proc.stderr)
- self.assertIn("--timeout 0.05", proc.stderr, "the flag must be forwarded to the child command line")
- # ...and the stage's own failure is what render reports: kind timeout, exit 124, the stage named
- tdoc = json.loads(proc.stdout)
- self.assertEqual((tdoc["status"], tdoc["error"]["kind"], tdoc["exit_code"], tdoc["stage"]), ("failed", "timeout", 124, "cut.py"))
-
- def test_join_width_keeps_aspect(self):
- out = OUT / "join_w.mp4"
- script("join.py", self.src, self.src, "--transition", "none", "--width", "640", "--fast", "-o", out)
- m = probe(str(out))["video"]
- self.assertEqual((m["width"], m["height"]), (640, 360))
-
- # ---------------------------------------------------------------- v0.6: graphics / brand / report
- def test_graphics_templates(self):
- brand = OUT / "brand.json"
- brand.write_text(json.dumps({"font": "DejaVu Sans", "colors": {"primary": "FF6A00", "text": "FFFFFF", "background": "0B1D2A"},
- "logo": "logo.png", "logo_position": "top-right", "logo_scale": 140, "safe_margin": 40,
- "caption": {"size": 28, "position": "bottom", "animate": "pop", "karaoke": True, "bold": True}}), encoding="utf-8")
- cases = {
- "lower-third": ["--name", "Ada Lovelace", "--title", "Analyst", "--start", "1", "--end", "6"],
- "title": ["--title", "Episode 12", "--subtitle", "The math of video", "--start", "0", "--end", "4"],
- "chapter": ["--title", "Part 2", "--start", "0", "--end", "5"],
- "progress": [],
- "countdown": ["--from", "3", "--start", "1", "--end", "5"],
- "bug": ["--title", "@handle"],
- }
- for name, argv in cases.items():
- out = OUT / f"gfx_{name}.mp4"
- proc = script("graphics.py", self.src, "--template", name, "--brand", brand, "--fast", "-o", out, *argv)
- self.assertClose(probe(str(out))["duration"], 12.0, 0.2, name)
- self.assertTrue("FF6A00" in proc.stderr or "0B1D2A" in proc.stderr, f"{name} uses the brand colours")
- # animated templates must actually move: lower-third frame mid-slide differs from settled frame
- script("look.py", OUT / "gfx_lower-third.mp4", "--at", "1.15", "--at", "3", "--no-timecode", "-o", OUT / "lt")
- a, b = (OUT / "lt_1.150s.png").read_bytes(), (OUT / "lt_3.000s.png").read_bytes()
- self.assertNotEqual(a[200:4000], b[200:4000])
- script("graphics.py", self.src, "--template", "lower-third", expect_fail=True)
-
- # ------------------------------------------------------- delivery templates (1.14)
- def _region_stats(self, path, crop, at=1.0):
- """Mean luma and spread of one region of a frame, as signalstats reports them."""
- proc = sh("ffmpeg", "-hide_banner", "-loglevel", "error", "-ss", str(at), "-i", str(path), "-frames:v", "1",
- "-vf", f"crop={crop},signalstats,metadata=print:file=-", "-f", "null", "-")
- vals = {k: float(v) for k, v in re.findall(r"lavfi\.signalstats\.(YAVG|YMIN|YMAX)=([0-9.]+)", proc.stdout)}
- return vals["YAVG"], vals["YMAX"] - vals["YMIN"]
-
- def test_every_delivery_template_renders_and_passes_its_own_check(self):
- """1.14: `render.py --template NAME INPUT` is the one command a delivery request becomes,
- so every shipped template has to survive its own pipeline on real footage and come back
- with its own platform's check passing -- the frame, the caption burn, the loudness pass,
- the export preset and check.py agreeing is exactly the thing a template promises and the
- thing that used to be assembled by hand differently every time."""
- names = sorted(p.stem for p in (ROOT / "templates").glob("*.json"))
- self.assertEqual(names, ["facebook", "linkedin", "podcast", "reels", "shorts", "tiktok",
- "x", "youtube", "youtube-shorts"], "every shipped template is exercised here")
- for name in names:
- with self.subTest(template=name):
- src = self.mic if name == "podcast" else self.src
- argv = [str(src), "--template", name, "--fast", "--json",
- "-o", str(OUT / ("tpl_%s.%s" % (name, "m4a" if name == "podcast" else "mp4")))]
- if name != "podcast":
- argv += ["--cues", str(self.cues)]
- doc = json.loads(script("render.py", *argv).stdout)
- self.assertEqual(doc["status"], "completed")
- self.assertTrue(os.path.exists(doc["output"]), doc["output"])
- self.assertTrue(doc["check"]["ok"],
- f"{name}: {[r for r in doc['check']['checks'] if r['status'] == 'FAIL']}")
- platform = json.loads((ROOT / "templates" / f"{name}.json").read_text())["check"]["platform"]
- self.assertEqual(doc["check"]["platform"], platform)
-
- def test_template_keeps_caption_and_graphic_out_of_the_platform_safe_zone(self):
- """The whole point of the table's safe zones: TikTok draws its description block over the
- bottom 22 % of the frame and its like/comment column over the right 14 %. A caption burned
- at the historical margin sits under the description; a right-hand graphic sits under the
- buttons. Asserted on the planned commands (--dry-run --json), which is where the ASS
- MarginV and the drawtext x actually are."""
- sys.path.insert(0, str(SCRIPTS))
- from _platforms import PLATFORMS, ass_units
- safe = PLATFORMS["tiktok"]["safe"]
- proj = OUT / "safe_project.json"
- script("render.py", self.src, "--template", "tiktok", "--cues", self.cues,
- "--write-project", proj, "-o", str(OUT / "safe_out.mp4"))
- cap = json.loads(proj.read_text())["captions"]
- self.assertEqual(cap["margin"], ass_units(safe["bottom"]), "the template's caption margin is the safe zone")
- # the burn itself: the generated .ass carries MarginV in the same 288-unit grid, scaled
- plan = json.loads(script("render.py", proj, "--dry-run", "--json").stdout)
- ass_lines = [c for c in plan["commands"] if "captioned.ass" in c]
- self.assertTrue(ass_lines, plan["commands"])
- # the ASS grid is 288 lines, so a fraction of the frame lands on the nearest of ~6.7 px
- margin_px = round(cap["margin"] * 1920 / 288)
- self.assertGreaterEqual(margin_px, round(safe["bottom"] * 1920) - 1920 / 288,
- "the caption's baseline margin must clear TikTok's description bar")
- # a right-positioned graphic: drawtext's x must leave the like column free
- gfx = json.loads(script("graphics.py", self.src, "--template", "bug", "--title", "@handle",
- "--position", "top-right", "--platform", "tiktok", "--dry-run", "--json",
- "-o", str(OUT / "safe_bug.mp4")).stdout)
- W, H = 1280, 720 # the fixture's own frame: the margins are fractions of it
- drawtext = [c for c in gfx["commands"] if "drawtext" in c][0]
- m = re.search(r"x=w-text_w-(\d+)", drawtext)
- self.assertTrue(m, drawtext)
- self.assertGreaterEqual(int(m.group(1)), round(safe["right"] * W) - 1,
- "a right-hand graphic must sit left of TikTok's like column")
- m = re.search(r"y=(\d+):box", drawtext)
- self.assertGreaterEqual(int(m.group(1)), round(safe["top"] * H) - 1)
-
- def test_list_templates_names_every_template_with_its_safe_zones(self):
- out = script("render.py", "--list-templates").stdout
- sys.path.insert(0, str(SCRIPTS))
- from _platforms import PLATFORMS
- for path in sorted((ROOT / "templates").glob("*.json")):
- self.assertIn(path.stem, out)
- for edge, frac in PLATFORMS["tiktok"]["safe"].items():
- self.assertIn(f"{edge} {frac:.2f}", out, f"--list-templates must state tiktok's {edge} safe zone")
- self.assertIn("1080x1920", out)
- script("render.py", self.src, "--template", "myspace", expect_fail=True)
-
- def test_write_project_writes_a_project_render_accepts(self):
- """--write-project is the "let me edit it first" path: it must write a project the real
- renderer takes without a single further change, and render nothing itself."""
- proj = OUT / "wp_project.json"
- out = OUT / "wp_out.mp4"
- out.unlink(missing_ok=True)
- doc = json.loads(script("render.py", self.src, "--template", "reels", "--cues", self.cues,
- "--write-project", proj, "-o", out, "--json").stdout)
- self.assertEqual(doc["output"], str(proj))
- self.assertFalse(out.exists(), "--write-project renders nothing")
- loaded = json.loads(proj.read_text())
- self.assertEqual(loaded["template"], "reels")
- self.assertEqual(loaded["clips"][0]["src"], str(self.src.resolve()))
- plan = json.loads(script("render.py", proj, "--dry-run", "--json").stdout)
- self.assertEqual(plan["status"], "completed")
- self.assertIn("export", plan["stages"])
-
- def test_social_pack_writes_one_file_per_destination_and_a_table(self):
- """--template all / a comma list: one edit, N deliveries, one table. The table is what the
- user is handed, so it must have exactly one row per destination and name the real files."""
- doc = json.loads(script("render.py", self.src, "--template", "tiktok,x,linkedin",
- "--cues", self.cues, "--fast", "--json").stdout)
- self.assertEqual([r["platform"] for r in doc["pack"]], ["tiktok", "x", "linkedin"])
- for row in doc["pack"]:
- self.assertTrue(os.path.exists(row["path"]), row)
- self.assertEqual(row["check"], "pass", row)
- pack = Path(doc["output"])
- self.assertTrue(pack.exists())
- body = pack.read_text(encoding="utf-8")
- rows = [l for l in body.splitlines() if l.startswith("|") and not set(l.strip("| ")) <= set("-: |")]
- self.assertEqual(len(rows), 4, "one header row plus one row per destination")
- html_out = OUT / "pack.html"
- script("report.py", "--pack", pack, "-o", html_out)
- html_text = html_out.read_text(encoding="utf-8")
- for name in ("tiktok", "x", "linkedin"):
- self.assertIn(name, html_text)
-
- def test_export_presets_per_destination_are_distinct_and_hdr_av1_refuse_honestly(self):
- """1.14: tiktok/shorts/linkedin/facebook stop being aliases of reels/youtube -- each is its
- own frame and duration limit. youtube-hdr must keep a real HDR source's tags (the point of
- the preset) and refuse an SDR one instead of labelling SDR as HDR; youtube-av1 must refuse
- with kind: missing_tool on a build with no AV1 encoder rather than failing inside ffmpeg."""
- sys.path.insert(0, str(SCRIPTS))
- import export as export_mod
- frames = {name: (p["w"], p["h"], p["max"]) for name, p in export_mod.PRESETS.items()
- if name in ("reels", "tiktok", "shorts", "linkedin", "facebook")}
- self.assertEqual(len(set(frames.values())), 5, f"presets must be distinct entries: {frames}")
- for preset, size in (("tiktok", (1080, 1920)), ("linkedin", (1080, 1080))):
- out = OUT / f"export_{preset}.mp4"
- script("export.py", self.src, "--preset", preset, "--fast", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), size)
- hdr_out = OUT / "export_yt_hdr.mp4"
- script("export.py", self.hdr, "--preset", "youtube-hdr", "--fast", "-o", hdr_out)
- m = probe(str(hdr_out))
- self.assertTrue(m["video"]["hdr"], "youtube-hdr must keep the source's HDR")
- self.assertNotEqual(m["video"]["color_space"], "bt709")
- doc = json.loads(script("export.py", self.src, "--preset", "youtube-hdr", "--json",
- "-o", str(OUT / "never.mp4"), expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("SDR", doc["error"]["message"])
- from _common import ffmpeg_encoders
- av1_out = OUT / "export_yt_av1.mp4"
- if {"libsvtav1", "libaom-av1"} & ffmpeg_encoders():
- script("export.py", self.src, "--preset", "youtube-av1", "--fast", "-o", av1_out)
- self.assertEqual(probe(str(av1_out))["video"]["codec"], "av1")
- else:
- doc = json.loads(script("export.py", self.src, "--preset", "youtube-av1", "--json",
- "-o", str(av1_out), expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "missing_tool")
-
- def test_check_and_export_read_one_loudness_spec_per_platform(self):
- """The 1.14 table exists so `export.py --normalize` and `check.py` cannot drift: the
- loudness a preset normalises to is read from the same entry the check enforces."""
- sys.path.insert(0, str(SCRIPTS))
- import export as export_mod
- from check import SPECS
- from _platforms import loudness_of
- for preset, platform in export_mod.PLATFORM_OF.items():
- with self.subTest(preset=preset):
- spec = SPECS[platform]
- table = loudness_of(platform)
- self.assertEqual((spec["lufs"], spec["lufs_tol"], spec["tp"]),
- (table["lufs"], table["lufs_tol"], table["tp"]))
-
- def test_fit_blur_keeps_the_whole_picture_on_a_blurred_border(self):
- """--fit blur: the target aspect, nothing cropped, borders that carry a dimmed copy of the
- picture rather than black, and a centre band that is still the scaled source."""
- out = OUT / "fit_blur.mp4"
- script("fit.py", self.src, "--duration", "3", "--aspect", "9:16", "--fit", "blur",
- "--width", "360", "--fast", "-o", out)
- m = probe(str(out))
- self.assertEqual((m["video"]["width"], m["video"]["height"]), (360, 640))
- top_avg, top_spread = self._region_stats(out, "iw:80:0:0")
- self.assertGreater(top_avg, 10, f"blurred border is black: {top_avg}")
- self.assertGreater(top_spread, 8, f"blurred border is flat: {top_spread}")
- # the centre band is the fitted source: 360x202 sits at y=(640-202)/2
- ref = OUT / "fit_blur_ref.mp4"
- script("fit.py", self.src, "--duration", "3", "--width", "360", "--fast", "-o", ref)
- mid_avg, _ = self._region_stats(out, "iw:180:0:230")
- ref_avg, _ = self._region_stats(ref, "iw:180:0:10")
- self.assertClose(mid_avg, ref_avg, 12, "the centre of a blur fit is the scaled source")
- # the darkening is an eq on code values: a -15 % perceptual dim on SDR, something else on
- # PQ/HLG, so an HDR source keeps its background at its own levels (review 12)
- sdr_plan = json.loads(script("fit.py", self.src, "--aspect", "9:16", "--fit", "blur",
- "--dry-run", "--json", "-o", str(OUT / "blur_sdr.mp4")).stdout)
- hdr_plan = json.loads(script("fit.py", self.hdr, "--aspect", "9:16", "--fit", "blur",
- "--dry-run", "--json", "-o", str(OUT / "blur_hdr.mp4")).stdout)
- self.assertTrue(any("eq=brightness" in c for c in sdr_plan["commands"]))
- self.assertTrue(any("boxblur" in c for c in hdr_plan["commands"]))
- self.assertFalse(any("eq=brightness" in c for c in hdr_plan["commands"]),
- "an HDR source must not be dimmed by an SDR-shaped eq")
-
- def test_look_safe_shades_only_the_platforms_occluded_zones(self):
- """`look.py --safe tiktok` is how "is the caption readable" gets answered about the app and
- not just the file: the bottom fifth and the right column come back visibly marked, the
- middle of the frame untouched."""
- plain, marked = OUT / "safe_plain.png", OUT / "safe_marked.png"
- script("look.py", self.src, "--at", "2", "--no-timecode", "-o", plain)
- doc = json.loads(script("look.py", self.src, "--at", "2", "--no-timecode", "--safe", "tiktok",
- "-o", marked, "--json").stdout)
- self.assertTrue(os.path.exists(doc["output"]))
- self.assertEqual(png_size(plain), png_size(marked))
- self.assertNotEqual(plain.read_bytes(), marked.read_bytes(), "--safe must mark the frame")
- cmd = [c for c in doc["commands"] if "drawbox" in c]
- self.assertTrue(cmd, doc["commands"])
- self.assertIn("y=ih*(1-0.22)", cmd[0])
- self.assertIn("x=iw*(1-0.14)", cmd[0])
-
- def test_sticker_hook_and_meme_draw_ink_where_they_promise(self):
- """The three social graphics templates: each must render, put ink where the layout says it
- goes (top band for the hook's progress bar, the two edges for a meme), and -- for the
- sticker -- stay inside the platform's safe zone when --platform names one."""
- sys.path.insert(0, str(SCRIPTS))
- from _platforms import PLATFORMS
- vertical = OUT / "safe_vertical.mp4"
- script("fit.py", self.src, "--duration", "4", "--aspect", "9:16", "--fit", "crop",
- "--width", "540", "--fast", "-o", vertical)
- base = self._region_stats(vertical, "iw:60:0:0", at=1.0)
-
- sticker = OUT / "gfx_sticker.mp4"
- doc = json.loads(script("graphics.py", vertical, "--template", "sticker", "--text", "NEW",
- "--position", "top-right", "--platform", "tiktok", "--fast",
- "-o", sticker, "--json").stdout)
- self.assertTrue(os.path.exists(sticker))
- drawtext = [c for c in doc["commands"] if "drawtext" in c][0]
- safe = PLATFORMS["tiktok"]["safe"]
- W, H = 540, 960
- right = int(re.search(r"x=w-text_w-(\d+)", drawtext).group(1))
- top = int(re.search(r"y=[^0-9]*(\d+)\+", drawtext).group(1)) # the shell quoting around the expression varies
- self.assertGreaterEqual(right, round(safe["right"] * W) - 1, "the sticker must clear the like column")
- self.assertGreaterEqual(top, round(safe["top"] * H) - 1, "the sticker must clear the status bar")
-
- hook = OUT / "gfx_hook.mp4"
- script("graphics.py", vertical, "--template", "hook", "--title", "How I cut this",
- "--duration", "3", "--fast", "-o", hook)
- band_avg, _ = self._region_stats(hook, "iw:12:0:0", at=0.5)
- late_avg, _ = self._region_stats(hook, "iw:12:0:0", at=3.5)
- self.assertGreater(abs(band_avg - late_avg), 4,
- "the hook's progress bar must be drawn while the card is up and gone after it")
- mid_card, _ = self._region_stats(hook, "iw:200:0:380", at=0.5)
- mid_after, _ = self._region_stats(hook, "iw:200:0:380", at=3.5)
- self.assertNotAlmostEqual(mid_card, mid_after, delta=1.0,
- msg="the hook card must darken the middle of the frame while it is up")
-
- meme = OUT / "gfx_meme.mp4"
- script("graphics.py", vertical, "--template", "meme", "--top", "when the render",
- "--bottom", "finally finishes", "--fast", "-o", meme)
- plain_top, _ = self._region_stats(vertical, "iw:120:0:40", at=1.0)
- meme_top, _ = self._region_stats(meme, "iw:120:0:40", at=1.0)
- plain_bottom, _ = self._region_stats(vertical, "iw:120:0:820", at=1.0)
- meme_bottom, _ = self._region_stats(meme, "iw:120:0:820", at=1.0)
- self.assertNotAlmostEqual(meme_top, plain_top, delta=0.5, msg="meme --top draws nothing")
- self.assertNotAlmostEqual(meme_bottom, plain_bottom, delta=0.5, msg="meme --bottom draws nothing")
- script("graphics.py", vertical, "--template", "sticker", expect_fail=True)
- script("graphics.py", vertical, "--template", "meme", expect_fail=True)
-
- def test_project_graphics_entry_renders_a_sticker_and_a_meme(self):
- """The three social graphics templates are advertised as usable inside a render.py
- graphics[] entry, and until review 12 the project validator refused their own keys
- (text/top/bottom/duration), so sticker and meme could only be run from the CLI."""
- out = OUT / "gproj_out.mp4"
- proj = OUT / "gproj.json"
- proj.write_text(json.dumps({
- "output": str(out),
- "clips": [{"src": str(self.src.resolve()), "in": 0, "out": 4}],
- "graphics": [
- {"template": "sticker", "text": "NEW", "position": "top-right", "platform": "tiktok"},
- {"template": "meme", "top": "when the render", "bottom": "finally finishes"},
- {"template": "hook", "title": "How I cut this", "duration": 2},
- ]}), encoding="utf-8")
- doc = json.loads(script("render.py", proj, "--fast", "--json").stdout)
- self.assertEqual(doc["status"], "completed")
- self.assertIn("graphics", doc["stages"])
- self.assertTrue(out.exists())
- # ink where the meme layout puts it: the two edges of the frame change, and the sticker
- # corner does too -- a validator that accepted the keys but dropped them would not show here
- for crop, y in (("iw:100:0:20", "top"), ("iw:100:0:600", "bottom")):
- before, _ = self._region_stats(self.src, crop, at=1.0)
- after, _ = self._region_stats(out, crop, at=1.0)
- self.assertNotAlmostEqual(before, after, delta=0.5, msg=f"nothing was drawn at the {y}")
- # an unknown key is still a refusal, with the valid ones named
- proj.write_text(json.dumps({"output": str(out), "clips": [{"src": str(self.src.resolve())}],
- "graphics": [{"template": "sticker", "caption": "NEW"}]}), encoding="utf-8")
- proc = script("render.py", proj, "--dry-run", "--json", expect_fail=True)
- self.assertIn("unknown key", proc.stderr)
-
- def test_template_logo_lands_inside_the_platform_safe_zone(self):
- """A template's --logo used to be drawn 24 px from the corner -- i.e. under TikTok's own
- status bar and next to its tab row. The overlay stage now hears the destination like the
- caption and graphics stages do, so the planned overlay sits inside the safe zone."""
- sys.path.insert(0, str(SCRIPTS))
- from _platforms import PLATFORMS
- safe = PLATFORMS["tiktok"]["safe"]
- W, H = PLATFORMS["tiktok"]["frame"]["w"], PLATFORMS["tiktok"]["frame"]["h"]
- doc = json.loads(script("render.py", self.src, "--template", "tiktok", "--cues", self.cues,
- "--logo", self.logo, "--dry-run", "--json",
- "-o", str(OUT / "logo_safe.mp4")).stdout)
- cmd = [c for c in doc["commands"] if "logo.png" in c and "overlay=" in c]
- self.assertTrue(cmd, doc["commands"])
- x, y = re.search(r"overlay=(-?\d+):(-?\d+)", cmd[0]).groups()
- self.assertGreaterEqual(int(x), round(safe["left"] * W) - 1,
- "the logo must clear the left safe margin")
- self.assertGreaterEqual(int(y), round(safe["top"] * H) - 1,
- "the logo must clear TikTok's status bar and tab row")
- self.assertLess(int(y), H - round(safe["bottom"] * H))
-
- def test_pack_dry_run_plans_every_command_and_reports_no_result(self):
- """A pack is the one path that writes seven files, so --dry-run has to show all of them --
- and must never report a check result or a file size for a run that encoded nothing (the
- sizes used to be read off files left behind by an earlier real run)."""
- packdir = OUT / "packdry"
- packdir.mkdir(exist_ok=True)
- stale = packdir / "source_tiktok.mp4"
- stale.write_bytes(b"0" * 4096) # a leftover from an earlier real run
- doc = json.loads(script("render.py", self.src, "--template", "tiktok,podcast",
- "--cues", self.cues, "--dry-run", "--json",
- "-o", str(packdir / "ignored.mp4")).stdout)
- self.assertTrue(any("ffmpeg" in c for c in doc["commands"]),
- "the pack's planned commands are the plan; --dry-run must show them")
- self.assertTrue(any("loudnorm" in c or "libx264" in c for c in doc["commands"]))
- for row in doc["pack"]:
- self.assertEqual(row["check"], "planned", row)
- self.assertIsNone(row["size_bytes"], row)
- self.assertIsNone(row["duration"], row)
- self.assertEqual(stale.stat().st_size, 4096, "a dry run must not touch the files it plans")
- # the audio-only destination of a pack is named like the single-template form: .m4a
- self.assertEqual([Path(r["file"]).suffix for r in doc["pack"]], [".mp4", ".m4a"])
- self.assertFalse((packdir / "source_pack.md").exists(), "a dry run writes no table either")
-
- def test_export_presets_are_the_platform_tables_frame_and_duration(self):
- """docs/contract.md says export.py's PRESETS/PLATFORM_OF come from scripts/_platforms.py.
- Until review 12 only check.py's SPECS did, and the facebook preset had already drifted
- (no duration cap against the table's 14400 s). Every platform preset is the table now,
- except the two deliberate, documented exceptions."""
- sys.path.insert(0, str(SCRIPTS))
- import export as export_mod
- from _platforms import PLATFORMS, loudness_of
- from check import SPECS
- # youtube4k delivers to youtube at 2160p; neither youtube preset trims at the 12-hour cap
- exceptions = {"youtube": {"max"}, "youtube4k": {"w", "h", "max"},
- "youtube-hdr": {"w", "h", "max"}, "youtube-av1": {"max"}}
- for preset, platform in sorted(export_mod.PLATFORM_OF.items()):
- with self.subTest(preset=preset):
- p = export_mod.PRESETS[preset]
- frame = PLATFORMS[platform]["frame"]
- spec = PLATFORMS[platform]["spec"]
- skip = exceptions.get(preset, set())
- if "w" not in skip:
- self.assertEqual((p["w"], p["h"]), (frame["w"], frame["h"]),
- f"{preset} frame must be {platform}'s frame")
- if "max" not in skip:
- self.assertEqual(p["max"], float(spec["max_duration"]) if spec["max_duration"] else None,
- f"{preset} duration cap must be {platform}'s")
- table = loudness_of(platform)
- self.assertEqual((SPECS[platform]["lufs"], SPECS[platform]["lufs_tol"], SPECS[platform]["tp"]),
- (table["lufs"], table["lufs_tol"], table["tp"]))
- self.assertEqual(export_mod.PRESETS["facebook"]["max"], 14400.0,
- "the drift review 12 found: facebook had no duration cap at all")
-
- def test_every_template_caption_block_is_the_tables_safe_zone(self):
- """The templates must not restate the numbers the table exists to own: change a
- destination's safe zone and every shipped template follows, rather than keeping an old
- margin silently."""
- sys.path.insert(0, str(SCRIPTS))
- from _platforms import PLATFORMS, caption_defaults
- import render as render_mod
- for path in sorted((ROOT / "templates").glob("*.json")):
- tpl = json.loads(path.read_text(encoding="utf-8"))
- cap = tpl.get("captions")
- if not cap:
- continue
- dest = tpl["check"]["platform"]
- with self.subTest(template=path.stem):
- want = caption_defaults(dest)
- self.assertEqual((cap["size"], cap["margin"]), (want["size"], want["margin"]),
- f"{path.name} restates {dest}'s caption size/margin")
- self.assertTrue(PLATFORMS[dest]["frame"])
- # and the filled project takes them from the table, not from the file's literals
- proj = OUT / "tplcap_project.json"
- script("render.py", self.src, "--template", "reels", "--cues", self.cues,
- "--write-project", proj, "-o", str(OUT / "tplcap.mp4"))
- filled = json.loads(proj.read_text())["captions"]
- want = caption_defaults("reels")
- self.assertEqual((filled["size"], filled["margin"]), (want["size"], want["margin"]))
-
- def test_platform_aliases_resolve_the_same_on_every_tool(self):
- """One resolve(): 'youtube-shorts' is 'shorts' for check, export, caption, graphics, look
- and render alike. Before review 12 the alias map was written, advertised in the docs and
- called from nowhere, so no tool accepted a single one of them."""
- sys.path.insert(0, str(SCRIPTS))
- import render as render_mod
- self.assertEqual(render_mod.expand_templates("ig"), ["reels"])
- self.assertEqual(render_mod.expand_templates("twitter,yt"), ["x", "youtube"])
- self.assertEqual(render_mod.expand_templates("youtube-shorts"), ["youtube-shorts"],
- "a template that ships under its own name stays itself")
- target = OUT / "alias_src.mp4"
- script("fit.py", self.src, "--duration", "3", "--aspect", "9:16", "--fit", "crop",
- "--width", "360", "--fast", "-o", target)
-
- def commands(tool, *argv):
- doc = json.loads(script(tool, target, *argv, "--dry-run", "--json").stdout)
- # drawn text goes through a private PER-RUN temp directory (1.15: mkdtemp, 0700,
- # removed at exit), so its random name differs between two processes by design and
- # is not part of what "the same destination" means.
- return [re.sub(r"ffmpeg-skill-text-[^/]+/", "ffmpeg-skill-text/", c)
- for c in doc["commands"] if "ffmpeg" in c or "drawtext" in c]
-
- # the alias is the point here, not compliance: a 3 s crop can miss the fps row on some
- # ffmpeg builds (7.1 reports the speed-changed rate differently), and check.py names
- # the resolved platform in its JSON on failure as well as on success
- proc_a = subprocess.run([sys.executable, str(SCRIPTS / "check.py"), str(target), "--platform",
- "youtube-shorts", "--no-loudness", "--json"],
- stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8")
- doc_a = json.loads(proc_a.stdout)
- self.assertEqual(doc_a["platform"], "shorts")
- self.assertTrue(doc_a["checks"], "check.py must have run the shorts rows under the alias")
- for tool, argv in (
- ("export.py", ("--preset", "youtube-shorts", "-o", str(OUT / "alias_exp.mp4"))),
- ("caption.py", ("--text", self.cues, "-o", str(OUT / "alias_cap.mp4"), "--platform", "youtube-shorts")),
- ("graphics.py", ("--template", "bug", "--title", "@x", "-o", str(OUT / "alias_gfx.mp4"), "--platform", "youtube-shorts")),
- ("look.py", ("--at", "1", "-o", str(OUT / "alias_look.png"), "--safe", "youtube-shorts"))):
- with self.subTest(tool=tool):
- canonical = tuple("shorts" if a == "youtube-shorts" else a for a in argv)
- self.assertEqual(commands(tool, *argv), commands(tool, *canonical),
- f"{tool} must treat youtube-shorts and shorts as one destination")
-
- def test_graphics_audio_stream_selects_the_requested_track_not_always_the_first(self):
- two = OUT / "gfx_two_streams.mkv"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
- "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
- "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
- self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
- out1 = OUT / "gfx_two_s1.mp4"
- script("graphics.py", two, "--template", "bug", "--title", "@handle", "--audio-stream", "1", "-o", out1, "--fast")
- self.assertIsNotNone(probe(str(out1))["audio"])
- out_prog = OUT / "gfx_two_progress.mp4"
- script("graphics.py", two, "--template", "progress", "--audio-stream", "1", "-o", out_prog, "--fast")
- self.assertIsNotNone(probe(str(out_prog))["audio"])
- proc = script("graphics.py", two, "--template", "bug", "--title", "x", "--audio-stream", "5", "-o", OUT / "gfx_nope.mp4", "--json", expect_fail=True)
- self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
- self.assertIn("audio-stream", proc.stderr)
-
- def test_brand_defaults_apply_to_caption_and_logo(self):
- brand = OUT / "brand.json"
- if not brand.exists():
- self.test_graphics_templates()
- ass = OUT / "brand.ass"
- script("caption.py", self.src, "--text", self.cues, "--brand", brand, "--write-ass", ass, "--fast", "-o", OUT / "brand_cap.mp4")
- style = [l for l in ass.read_text(encoding="utf-8-sig").splitlines() if l.startswith("Style:")][0]
- self.assertIn("&H00006AFF", style, "primary FF6A00 becomes the karaoke fill (BGR)")
- self.assertIn(",70,", style, "size 28 scaled to 720p")
- self.assertIn("\\kf", ass.read_text(encoding="utf-8-sig"), "brand enables karaoke")
- proc = script("overlay.py", self.src, "--logo", "--brand", brand, "--fast", "-o", OUT / "brand_logo.mp4")
- self.assertIn("scale=140:-1", proc.stderr)
- self.assertIn("overlay=W-w-40:40", proc.stderr)
- script("overlay.py", self.src, "--logo", expect_fail=True)
-
- def test_report_html(self):
- reels = OUT / "export_reels.mp4"
- if not reels.exists():
- script("export.py", self.src, "--preset", "reels", "--fit", "crop", "-o", reels)
- cmds = OUT / "cmds.txt"
- cmds.write_text("python3 export.py source.mp4 --preset reels\n")
- out = OUT / "report.html"
- data = json.loads(script("report.py", "--before", self.src, "--after", reels, "--platform", "reels", "--commands", cmds, "--title", "Test delivery", "-o", out, "--json").stdout)
- self.assertEqual(data["report"], str(out))
- html_text = out.read_text(encoding="utf-8")
- self.assertIn("Test delivery", html_text)
- self.assertEqual(html_text.count("data:image/png;base64"), 2, "before and after contact sheets")
- self.assertIn("export.py source.mp4 --preset reels", html_text)
- self.assertIn("class='verdict", html_text)
- self.assertIn("1080×1920", html_text)
- script("report.py", "--after", reels, "--no-sheets", "-o", OUT / "report2.html")
- self.assertLess((OUT / "report2.html").stat().st_size, 40000)
-
- # ---------------------------------------------------------------- v0.7: MCP server / batch / ASR bridge
- def test_mcp_server_stdio(self):
- server = ROOT / "mcp" / "server.py"
- reqs = [
- {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}},
- {"jsonrpc": "2.0", "method": "notifications/initialized"},
- {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
- {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "probe", "arguments": {"inputs": [str(self.src)]}}},
- {"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "cut", "arguments": {"input": str(self.src), "start": 1, "end": 3, "output": str(OUT / "mcp_cut.mp4")}}},
- {"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "cut", "arguments": {"argv": [str(self.src), "--start", "0", "--end", "2", "-o", str(OUT / "mcp_cut2.mp4")]}}},
- {"jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {"name": "nope", "arguments": {}}},
- {"jsonrpc": "2.0", "id": 7, "method": "bogus/method"},
- ]
- proc = subprocess.run([sys.executable, str(server)], input="\n".join(json.dumps(r) for r in reqs) + "\n", stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
- self.assertEqual(proc.returncode, 0, proc.stderr)
- resp = {r["id"]: r for r in (json.loads(l) for l in proc.stdout.splitlines() if l.strip())}
- self.assertEqual(resp[1]["result"]["serverInfo"]["name"], "ffmpeg-skill")
- names = {t["name"] for t in resp[2]["result"]["tools"]}
- self.assertTrue({"probe", "cut", "render", "check", "scenes", "batch"} <= names or {"probe", "cut", "render", "check", "scenes"} <= names)
- self.assertEqual(resp[3]["result"]["structuredContent"]["duration"], 12.0)
- self.assertClose(resp[4]["result"]["structuredContent"]["probe"]["duration"], 2.0, 0.6)
- self.assertTrue(Path(resp[5]["result"]["structuredContent"]["output"]).exists())
- self.assertTrue(resp[6]["result"].get("isError"))
- self.assertEqual(resp[7]["error"]["code"], -32601)
-
- def test_mcp_server_survives_a_non_object_json_line(self):
- """json.loads accepts any valid JSON value, not just an object -- a bare `42`, `null`,
- `true` or `[1,2]` line parses without raising, but main()'s very next line, `"id" not in
- req`, raised an uncaught TypeError for a non-dict req (an int/bool/None isn't iterable the
- way `in` needs). That check sat outside the try/except wrapping handle(), so the exception
- propagated out of the stdin loop and killed the whole stdio server process -- not just
- that one malformed line, but every other in-flight and future tool call in the session.
- Verify a line like this is now skipped, and the server stays alive and answers the next
- (valid) request instead of exiting non-zero with nothing produced for it."""
- server = ROOT / "mcp" / "server.py"
- lines = ["42", "null", "true", "[1,2,3]",
- json.dumps({"jsonrpc": "2.0", "id": 1, "method": "tools/list"})]
- proc = subprocess.run([sys.executable, str(server)], input="\n".join(lines) + "\n", stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
- self.assertEqual(proc.returncode, 0, f"server must not crash on non-object JSON lines; stderr: {proc.stderr}")
- resp = [json.loads(response_line) for response_line in proc.stdout.splitlines() if response_line.strip()]
- self.assertEqual(len(resp), 1, "only the one real request should get a response")
- self.assertEqual(resp[0]["id"], 1)
- self.assertIn("tools", resp[0]["result"])
-
- def test_batch_recipe_and_cache(self):
- folder = OUT / "batch_in"
- folder.mkdir(exist_ok=True)
- for name in ("a.mp4", "b.mp4"):
- (folder / name).write_bytes(Path(self.src).read_bytes())
- recipe = folder / "batch.json"
- recipe.write_text(json.dumps({"glob": "*.mp4", "output_dir": "out", "suffix": "_final",
- "steps": [["fit.py", "{in}", "--duration", "5", "-o", "{out}"], ["export.py", "{in}", "--preset", "x", "-o", "{out}"]]}))
- data = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--json").stdout)
- self.assertEqual(data["processed"], 2)
- self.assertFalse(any(r.get("cached") for r in data["results"]))
- for r in data["results"]:
- m = probe(r["output"])
- self.assertClose(m["duration"], 5.0, 0.3)
- self.assertEqual(m["video"]["width"], 1280)
- data = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--json").stdout)
- self.assertTrue(all(r.get("cached") for r in data["results"]), "second run served from cache")
- data = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--force", "--json").stdout)
- self.assertFalse(any(r.get("cached") for r in data["results"]))
- # project-based recipe
- proj = folder / "p.json"
- proj.write_text(json.dumps({"clips": [{"src": "x", "in": 0, "out": 3}], "export": {"preset": "x"}}))
- recipe2 = folder / "batch2.json"
- recipe2.write_text(json.dumps({"glob": "a.mp4", "output_dir": "out2", "suffix": "_p", "project": "p.json"}))
- data = json.loads(script("batch.py", folder, "--recipe", recipe2, "--fast", "--json").stdout)
- self.assertEqual(data["processed"], 1)
- self.assertClose(probe(data["results"][0]["output"])["duration"], 3.0, 0.3)
-
- def test_batch_project_recipe_cache_invalidates_on_project_json_content_change(self):
- """A "project" recipe is just {"project": "<path>", "clip_key": N} -- the real settings
- (export preset, captions, everything) live in the file at that path. The cache key used
- to hash only this outer recipe dict, so editing project.json's content (export preset
- swapped from "copy" to "x", a real re-encode) without touching batch.json itself left the
- key unchanged, and the stale cached output was served for the new settings with no error
- or warning. Verify a content-only change to project.json invalidates the cache."""
- folder = OUT / "batch_project_cache"
- folder.mkdir(exist_ok=True)
- (folder / "clip.mp4").write_bytes(Path(self.src).read_bytes())
- proj = folder / "p.json"
- proj.write_text(json.dumps({"clips": [{}], "export": {"preset": "copy"}}))
- recipe = folder / "batch.json"
- recipe.write_text(json.dumps({"glob": "clip.mp4", "output_dir": "out", "project": "p.json"}))
- data = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--json").stdout)
- self.assertFalse(data["results"][0].get("cached"))
- proj.write_text(json.dumps({"clips": [{}], "export": {"preset": "x"}}))
- data = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--json").stdout)
- self.assertFalse(data["results"][0].get("cached"), "a content-only project.json change must not be served from a stale cache")
-
- def test_batch_cache_write_is_atomic_no_leftover_temp_file(self):
- """The cache file used to be written with a plain write_text(), which is not atomic -- a
- process killed mid-write leaves a truncated file that the next run's json.loads() treats
- as corrupt and silently discards (every prior cache entry lost, not just the interrupted
- one). Now written via a sibling temp file + os.replace(). Verify a normal run leaves the
- cache file valid and no stray .tmp<pid> file behind."""
- folder = OUT / "batch_cache_atomic"
- folder.mkdir(exist_ok=True)
- (folder / "clip.mp4").write_bytes(Path(self.src).read_bytes())
- recipe = folder / "batch.json"
- recipe.write_text(json.dumps({"glob": "clip.mp4", "output_dir": "out", "steps": [["export.py", "{in}", "--preset", "copy", "-o", "{out}"]]}))
- script("batch.py", folder, "--recipe", recipe, "--fast")
- outdir = folder / "out"
- cache_path = outdir / ".ffskill_cache.json"
- self.assertTrue(cache_path.exists())
- json.loads(cache_path.read_text(encoding="utf-8")) # must not be truncated/corrupt
- leftover = list(outdir.glob(".ffskill_cache.json.tmp*"))
- self.assertEqual(leftover, [], f"temp cache file(s) left behind: {leftover}")
-
- def test_batch_refuses_a_recipe_step_naming_a_script_outside_scripts_dir(self):
- """run_step() built its command as `HERE / argv[0]`, where argv[0] came straight from an
- untrusted recipe JSON step. Path's / operator silently ignores the left side when the
- right side is itself an absolute path, and does nothing to stop a "../" traversal either
- -- so a recipe (from a template, a shared config, anywhere the caller didn't author it
- themselves) naming an absolute or ../-relative path got that file executed as a Python
- script, with the caller's own privileges, once per matching media file. Verify both an
- absolute path and a traversal path are refused instead of executed."""
- folder = OUT / "batch_security"
- folder.mkdir(exist_ok=True)
- (folder / "a.mp4").write_bytes(Path(self.src).read_bytes())
- evil = OUT / "batch_security_evil.py"
- marker = OUT / "batch_security_pwned.txt"
- marker.unlink(missing_ok=True)
- evil.write_text(f"open({str(marker)!r}, 'w').write('pwned')\n", encoding="utf-8")
-
- for step in ([str(evil)], ["../../../../tmp/does_not_matter.py"]):
- recipe = folder / "batch.json"
- recipe.write_text(json.dumps({"glob": "*.mp4", "steps": [step]}))
- proc = script("batch.py", folder, "--recipe", recipe, "--fast", "--force", expect_fail=True)
- self.assertIn("scripts/", proc.stderr)
- self.assertFalse(marker.exists(), f"step {step} must not have executed")
-
- def test_batch_refuses_a_fixed_ext_recipe_that_collapses_two_sources_to_one_output(self):
- """final_path() falls back to each source's OWN extension by default, so files that only
- differ by extension don't collide -- but a recipe with a fixed "ext" (e.g. converting a
- folder of mixed .mp4/.mov masters to one format) makes two sources with the same stem
- (clip.mp4 and clip.mov) resolve to the identical final path (clip_out.mp4). process() had
- no collision detection: the file processed later in sorted() order used to silently
- overwrite the earlier one's finished output, with the cache still recording both entries
- as ok. Verify this is now refused up front, before either file is processed, rather than
- one silently clobbering the other."""
- folder = OUT / "batch_collision_in"
- folder.mkdir(exist_ok=True)
- for name in ("clip.mp4", "clip.mov"):
- (folder / name).write_bytes(Path(self.src).read_bytes())
- recipe = folder / "collide.json"
- recipe.write_text(json.dumps({"ext": "mp4", "steps": [["export.py", "{in}", "--preset", "x", "-o", "{out}"]]}))
- proc = script("batch.py", folder, "--recipe", recipe, "--fast", expect_fail=True)
- self.assertIn("collision", proc.stderr)
- self.assertIn("clip.mp4", proc.stderr)
- self.assertIn("clip.mov", proc.stderr)
- self.assertFalse((folder / "out" / "clip_out.mp4").exists(), "nothing should be written once a collision is detected")
-
- def test_transcribe_without_engine_explains(self):
- import shutil
- if shutil.which("whisper-cli") or shutil.which("whisper"):
- self.skipTest("a local ASR engine is installed")
- try:
- import faster_whisper # noqa: F401
- self.skipTest("faster-whisper installed")
- except ImportError:
- pass
- proc = script("caption.py", self.src, "--transcribe", "-o", OUT / "asr.mp4", expect_fail=True)
- self.assertIn("no local speech-to-text engine", proc.stderr)
- self.assertIn("whisper", proc.stderr)
-
- # ---------------------------------------------------------------- Phase 3 regressions
- def test_sync_large_offset_on_repetitive_music(self):
- # repetitive music-like signal: a 4-bar loop with slow variation; raw correlation used to prefer
- # the small-overlap-friendly wrong lag, NCC must find the true -28 s offset in a 60 s window
- loop = OUT / "loop.wav"
- # speech-like: dialogue from the demo tones plus random-looking bursts (incommensurate gates,
- # a slowly drifting pitch and pink-noise "room"), so no two 9 s stretches look alike
- expr = (TONES + "+0.25*sin(2*PI*(165+30*sin(2*PI*0.031*t))*t)*gt(sin(2*PI*0.113*t+0.4)\\,0.55)"
- "+0.3*sin(2*PI*(520+80*sin(2*PI*0.017*t+1))*t)*gt(sin(2*PI*0.29*t+2.1)*sin(2*PI*0.073*t)\\,0.35)")
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", f"aevalsrc='{expr}':s=48000",
- "-f", "lavfi", "-i", "anoisesrc=a=0.02:c=pink:r=48000", "-t", "200", "-filter_complex", "amix=inputs=2:duration=first:normalize=0", "-c:a", "pcm_s16le", loop)
- ref = OUT / "loop_ref.wav"
- sec = OUT / "loop_sec.wav"
- # 28 s offset inside a 120 s analysis window (the documented rule: window >= 4x max offset)
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "40", "-i", loop, "-t", "120", "-c:a", "pcm_s16le", ref)
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "12", "-i", loop, "-t", "120", "-af", "volume=-8dB,highpass=f=300", "-c:a", "pcm_s16le", sec)
- data = json.loads(script("sync.py", ref, sec, "--json", "--max-offset", "30").stdout)
- self.assertClose(data["offset_seconds"], -28.0, 0.02)
- self.assertGreater(data["confidence"], 0.3)
-
- def test_audio_only_inputs_through_the_audio_scripts(self):
- """WAV / M4A / MP3 with no video stream: loudness, silence, audio (voice, convert), cut, check."""
- m4a = OUT / "gappy.m4a"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*gt(sin(2*PI*0.25*t)\\,0)':s=48000",
- "-t", "12", "-c:a", "aac", "-b:a", "128k", m4a)
- self.assertIsNone(probe(str(m4a)).get("video"))
- # loudness: wav -> m4a, codec follows the output extension
- norm = OUT / "lav_norm.m4a"
- script("loudness.py", self.mic, "-I", "-16", "--tp", "-1.5", "-o", norm)
- a = probe(str(norm))["audio"]
- self.assertEqual(a["codec"], "aac")
- self.assertIn("PASS", script("check.py", norm, "--platform", "podcast").stdout)
- # silence removal on an m4a
- tight = OUT / "gappy_tight.m4a"
- data = json.loads(script("silence.py", m4a, "-o", tight, "--json").stdout)
- self.assertClose(data["removed_seconds"], 5.25, 0.3)
- self.assertClose(probe(str(tight))["duration"], 6.75, 0.3)
- # voice clean-up keeps the container, plain -o converts
- clean = OUT / "gappy_clean.m4a"
- script("audio.py", m4a, "--voice", "-o", clean)
- self.assertEqual(probe(str(clean))["audio"]["codec"], "aac")
- mp3 = OUT / "lav.mp3"
- script("audio.py", self.mic, "-o", mp3)
- self.assertEqual(probe(str(mp3))["audio"]["codec"], "mp3")
- # trim is a stream copy on wav and mp3
- cut_wav = OUT / "lav_cut.wav"
- proc = script("cut.py", self.mic, "--start", "0:02", "--end", "0:06", "-o", cut_wav)
- self.assertIn("lossless", proc.stderr)
- self.assertClose(probe(str(cut_wav))["duration"], 4.0, 0.05)
- cut_mp3 = OUT / "lav_cut.mp3"
- script("cut.py", mp3, "--start", "2", "--end", "6", "-o", cut_mp3)
- self.assertClose(probe(str(cut_mp3))["duration"], 4.0, 0.1)
- # picture-only scripts refuse clearly instead of failing inside ffmpeg
- for argv in (("fit.py", "--duration", "5"), ("export.py", "--preset", "youtube"), ("look.py",)):
- proc = script(argv[0], self.mic, *argv[1:], "-o", OUT / "nope.out", expect_fail=True)
- self.assertIn("no video stream", proc.stderr)
-
- def test_loudness_silent_input_is_reported_not_crashed(self):
- silent = OUT / "silent.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30", "-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo",
- "-t", "3", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", silent)
- data = json.loads(script("loudness.py", silent, "--measure-only").stdout)
- self.assertTrue(data["silent"])
- proc = script("loudness.py", silent, "-o", OUT / "silent_norm.mp4", expect_fail=True)
- self.assertIn("silent", proc.stderr)
-
- def test_overlay_fade_without_start_end_fades_in_only(self):
- """--fade without --end fades in at 0 and stays; the fade-out belongs to --end (eval 6,
- e03-logo: every "fade in at the start" run had to caveat an unasked-for fade-out)."""
- proc = script("overlay.py", self.src, "--image", self.logo, "--fade", "0.5", "--dry-run")
- self.assertIn("fade=t=in:st=0.000", proc.stderr)
- self.assertNotIn("fade=t=out", proc.stderr)
- self.assertNotIn("\nwrote ", proc.stderr, "dry-run must not claim a file was written")
- proc = script("overlay.py", self.src, "--image", self.logo, "--fade", "0.5", "--end", "5", "--dry-run")
- self.assertIn("fade=t=out:st=4.500", proc.stderr)
-
- # ---------------------------------------------------------------- _common
- def test_context_is_attribute_only_and_resets(self):
- """Context once carried dict-style shims for older call sites; every site uses attributes
- now and the shims are gone, so a stray STATE["x"] is a TypeError at the call site rather
- than a second, silently-diverging access path. __slots__ also refuses unknown names."""
- from _common import Context
- ctx = Context()
- ctx.dry_run = True
- ctx.fast = True
- self.assertTrue(ctx.dry_run and ctx.fast)
- self.assertIsNone(ctx.duration_hint)
- with self.assertRaises(TypeError):
- ctx["dry_run"] # noqa: B018 -- the mapping shim is gone on purpose
- with self.assertRaises(AttributeError):
- ctx.nonexistent = 1
- ctx.commands.append("x")
- ctx.reset()
- self.assertEqual((ctx.dry_run, ctx.fast, ctx.commands), (False, False, []))
-
- # ---------------------------------------------------------------- help
-
- # ------------------------------------------------------------------ audio: extraction, concat, precision, dynamics
- @staticmethod
- def _samples(path):
- """(codec, sample_rate, duration_ts) of the first audio stream as ffprobe sees it."""
- out = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "a:0", "-show_entries", "stream=codec_name,sample_rate,duration_ts",
- "-of", "csv=p=0", str(path)], stdout=subprocess.PIPE, text=True, check=True).stdout.strip().split(",")
- return out[0], int(out[1]), int(out[2])
-
- @staticmethod
- def _peak_rms(path):
- proc = subprocess.run(["ffmpeg", "-hide_banner", "-i", str(path), "-af", "astats=measure_overall=Peak_level+RMS_level:measure_perchannel=none",
- "-f", "null", "-"], stderr=subprocess.PIPE, text=True)
- vals = dict(re.findall(r"(Peak level|RMS level) dB: (-?[\d.]+)", proc.stderr))
- return float(vals["Peak level"]), float(vals["RMS level"])
-
- def test_audio_extraction_from_video_container(self):
- """mp4 -> wav / m4a through audio.py and cut.py: no video stream, codec from the extension, stream selection."""
- wav = OUT / "ex_audio.wav"
- data = json.loads(script("audio.py", self.src, "-o", wav, "--json").stdout)
- self.assertIsNone(data["probe"]["video"])
- self.assertEqual(data["probe"]["audio"]["codec"], "pcm_s16le")
- self.assertFalse(data["video"])
- m4a = OUT / "ex_voice.m4a"
- data = json.loads(script("audio.py", self.src, "--voice", "-o", m4a, "--json").stdout)
- self.assertIsNone(data["probe"]["video"])
- self.assertEqual(data["probe"]["audio"]["codec"], "aac")
- # a video output keeps the stream-copied picture as before
- mp4 = OUT / "ex_keep.mp4"
- data = json.loads(script("audio.py", self.src, "--denoise", "-o", mp4, "--json").stdout)
- self.assertIsNotNone(data["probe"]["video"])
- self.assertTrue(data["video"])
- # two audio streams: --audio-stream 1 picks the 880 Hz / 44.1 kHz track, an index past the end fails as input
- two = OUT / "two_streams.mkv"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
- "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
- "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
- self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
- self.assertEqual(probe(str(two))["audio_streams"][1]["sample_rate"], 44100)
- s1 = OUT / "two_s1.wav"
- data = json.loads(script("audio.py", two, "--audio-stream", "1", "-o", s1, "--json").stdout)
- self.assertEqual(data["audio_stream"], 1)
- self.assertEqual(self._samples(s1)[1], 44100)
- proc = script("audio.py", two, "--audio-stream", "2", "-o", OUT / "nope.wav", "--json", expect_fail=True)
- self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
- self.assertIn("2 audio stream", proc.stderr)
- # cut.py with an audio extension extracts too, and never copies AAC packets into a WAV
- cw = OUT / "ex_cut.wav"
- data = json.loads(script("cut.py", self.src, "--start", "1", "--end", "3", "-o", cw, "--json").stdout)
- self.assertIsNone(data["probe"]["video"])
- self.assertEqual(self._samples(cw)[0], "pcm_s16le")
- self.assertEqual(data["precision"], "sample")
-
- def test_join_audio_only_inputs(self):
- """WAV + M4A + MP3 of different rates and channel counts join as audio; video containers and mixed inputs are refused."""
- st = OUT / "j_stereo44.m4a"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=1000:sample_rate=44100", "-t", "3", "-ac", "2", "-c:a", "aac", st)
- mp3 = OUT / "j_mono.mp3"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=500:sample_rate=48000", "-t", "3", "-c:a", "libmp3lame", mp3)
- mic_dur = probe(str(self.mic))["duration"]
- # crossfade -> flac: rate of the first clip, widest layout
- out = OUT / "j_audio.flac"
- data = json.loads(script("join.py", self.mic, st, mp3, "-o", out, "--json").stdout)
- self.assertEqual(data["mode"], "audio")
- self.assertEqual((data["sample_rate"], data["channels"]), (48000, 2))
- self.assertIsNone(data["probe"]["video"])
- self.assertEqual(data["probe"]["audio"]["codec"], "flac")
- self.assertClose(data["probe"]["duration"], mic_dur + 3 + 3 - 2 * 0.5, 0.15)
- # butt join -> wav, explicit rate and channels
- out2 = OUT / "j_audio.wav"
- data = json.loads(script("join.py", st, mp3, "--transition", "none", "--sample-rate", "44100", "--channels", "1", "-o", out2, "--json").stdout)
- self.assertEqual(self._samples(out2)[:2], ("pcm_s16le", 44100))
- self.assertEqual(data["probe"]["audio"]["channels"], 1)
- self.assertClose(data["probe"]["duration"], 6.0, 0.1)
- # refusals are input errors, before ffmpeg runs
- proc = script("join.py", self.mic, mp3, "-o", OUT / "j_audio.mp4", "--json", expect_fail=True)
- self.assertIn("audio extension", json.loads(proc.stdout)["error"]["message"])
- self.assertNotIn("ffmpeg ", proc.stderr.replace("/usr/bin/", ""), "refused before ffmpeg ran")
- proc = script("join.py", self.src, self.mic, "-o", OUT / "j_mixed.mp4", "--json", expect_fail=True)
- self.assertIn("has no video stream", proc.stderr)
- self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
- # dry-run plans the audio join and writes nothing
- planned = OUT / "j_dry.wav"
- data = json.loads(script("join.py", self.mic, mp3, "-o", planned, "--dry-run", "--json").stdout)
- self.assertTrue(data["dry_run"])
- self.assertIn("acrossfade", data["commands"][0])
- self.assertFalse(planned.exists())
-
- def test_cut_audio_precision_is_measured(self):
- """Stream copy is packet-accurate, --accurate is sample-exact on PCM/FLAC, lossy outputs say codec_frame."""
- start, end = 1.2345, 2.3456
- want = round((end - start) * 48000) # 53333 samples
- # WAV copy: packet boundary, reported as such, within a few ms
- cw = OUT / "prec_copy.wav"
- data = json.loads(script("cut.py", self.mic, "--start", str(start), "--end", str(end), "-o", cw, "--json").stdout)
- self.assertEqual(data["precision"], "packet")
- self.assertFalse(data["reencoded"])
- self.assertLess(abs(data["duration_error_ms"]), 50)
- self.assertEqual(self._samples(cw)[0], "pcm_s16le")
- # WAV --accurate: exactly the requested number of samples
- ca = OUT / "prec_acc.wav"
- data = json.loads(script("cut.py", self.mic, "--start", str(start), "--end", str(end), "--accurate", "-o", ca, "--json").stdout)
- self.assertEqual(data["precision"], "sample")
- self.assertEqual(self._samples(ca), ("pcm_s16le", 48000, want))
- self.assertLess(abs(data["duration_error_ms"]), 0.05)
- # 44.1 kHz FLAC, --accurate: exact at its own rate
- flac = OUT / "prec_44.flac"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=1000:sample_rate=44100", "-t", "3", "-c:a", "flac", flac)
- fa = OUT / "prec_44_cut.flac"
- data = json.loads(script("cut.py", flac, "--start", "0.5", "--end", "1.7", "--accurate", "-o", fa, "--json").stdout)
- self.assertEqual(data["precision"], "sample")
- self.assertEqual(self._samples(fa), ("flac", 44100, round(1.2 * 44100)))
- # compressed source (AAC in mp4) decoded to PCM with --accurate: exact; to AAC: codec_frame, not "sample"
- ma = OUT / "prec_from_aac.wav"
- data = json.loads(script("cut.py", self.src, "--start", str(start), "--end", str(end), "--accurate", "-o", ma, "--json").stdout)
- self.assertEqual(data["precision"], "sample")
- self.assertEqual(self._samples(ma)[2], want)
- m4a = OUT / "prec_to_aac.m4a"
- data = json.loads(script("cut.py", self.src, "--start", str(start), "--end", str(end), "--accurate", "-o", m4a, "--json").stdout)
- self.assertEqual(data["precision"], "codec_frame")
- self.assertEqual(self._samples(m4a)[0], "aac")
- # video re-encode keeps reporting frame precision; a plain copy keeps packet
- mp4 = OUT / "prec_video.mp4"
- data = json.loads(script("cut.py", self.src, "--start", "1", "--end", "3", "--accurate", "--preset", "ultrafast", "-o", mp4, "--json").stdout)
- self.assertEqual(data["precision"], "frame")
- self.assertIsNotNone(data["probe"]["video"])
-
- def test_audio_typed_dynamics(self):
- """--gate / --compress / --limit map typed flags onto acompressor, alimiter, agate; ranges are enforced; the ceiling holds."""
- out = OUT / "dyn.wav"
- data = json.loads(script("audio.py", self.mic, "--gate", "--gate-threshold", "-50", "--compress", "--comp-threshold", "-20",
- "--comp-ratio", "4", "--comp-attack", "5", "--comp-release", "80", "--comp-makeup", "6",
- "--limit", "--limit-ceiling", "-3", "-o", out, "--json").stdout)
- self.assertEqual(data["dynamics"], ["agate", "acompressor", "alimiter"])
- cmd = data["commands"][0]
- self.assertIn("agate=threshold=0.00316228", cmd)
- self.assertIn("acompressor=threshold=0.1:ratio=4:attack=5:release=80:makeup=1.99526", cmd)
- self.assertIn("alimiter=limit=0.707946:level=disabled", cmd)
- peak, rms = self._peak_rms(out)
- self.assertLessEqual(peak, -3.0 + 0.1, "limiter ceiling")
- # the compressor alone on a full-scale sine: threshold -20 dB, ratio 4 settle far below 0 dB and above the threshold
- sine = OUT / "dyn_sine.wav"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-t", "3", "-af", "volume=18.06dB", "-c:a", "pcm_s16le", sine)
- comp = OUT / "dyn_comp.wav"
- script("audio.py", sine, "--compress", "--comp-threshold", "-20", "--comp-ratio", "4", "--comp-attack", "5", "--comp-release", "80", "-o", comp)
- peak_c, _ = self._peak_rms(comp)
- self.assertGreater(self._peak_rms(sine)[0], -0.5)
- self.assertLess(peak_c, -3.0, "compressor reduced a 0 dBFS tone (measured -7.5 dB: ffmpeg detects RMS, knee 2.83 dB)")
- self.assertGreater(peak_c, -20.0, "compression, not a gate")
- # every flag is range-checked before ffmpeg runs
- for flags, text in ((("--compress", "--comp-ratio", "50"), "1..20"),
- (("--limit", "--limit-ceiling", "1"), "-24..0"),
- (("--gate", "--gate-attack", "0"), "0.01..9000"),
- (("--compress", "--comp-makeup", "40"), "0..36")):
- proc = script("audio.py", self.mic, *flags, "-o", OUT / "dyn_bad.wav", "--json", expect_fail=True)
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn(text, doc["error"]["message"])
- self.assertNotIn("$ ", proc.stderr, "refused before ffmpeg ran")
- # a parameter without its switch is an error, not silently ignored
- proc = script("audio.py", self.mic, "--comp-ratio", "4", "-o", OUT / "dyn_bad.wav", expect_fail=True)
- self.assertIn("add --compress", proc.stderr)
- # the limiter alone on a video input keeps the picture
- mp4 = OUT / "dyn_video.mp4"
- data = json.loads(script("audio.py", self.src, "--limit", "--limit-ceiling", "-1", "-o", mp4, "--json").stdout)
- self.assertIsNotNone(data["probe"]["video"])
- self.assertLessEqual(self._peak_rms(mp4)[0], -1.0 + 0.3)
-
-
- # ------------------------------------------------------------------ FFmpeg 8+ / Windows compatibility
- @staticmethod
- def _frame_count(path):
- proc = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-count_packets", "-show_entries", "stream=nb_read_packets", "-of", "csv=p=0", str(path)],
- stdout=subprocess.PIPE, text=True)
- return int(proc.stdout.strip())
-
- @staticmethod
- def _psnr(a, b):
- """Average PSNR of b against a (dB); lower means the picture changed more. inf when identical."""
- # Two things make this compare pixels and nothing else. (1) Both inputs are re-stamped by
- # frame *number*, so the psnr filter (which pairs frames by timestamp) never compares a
- # frame with its neighbour; frame *count* equality is asserted separately by the callers
- # that care, so a genuinely dropped frame still fails. (2) Both inputs get the *same*
- # colour tags before psnr. From FFmpeg 7.1 libavfilter negotiates colourspace, and psnr
- # on an untagged source vs a bt709-tagged output auto-inserts a real bt709->bt601
- # conversion on one side (8.x: 26 dB for a byte-identical picture) -- and, worse, hides
- # an encode-time conversion by undoing it (8.x reported 40 dB for an output whose pixels
- # had been re-matrixed, which is how the 7.1+ -colorspace bug in #156 went unnoticed on
- # macOS). With the tags pinned identical, every build from 5.1 to 8.1 reports the same
- # number for the same two files.
- same = "setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv"
- proc = subprocess.run(["ffmpeg", "-hide_banner", "-i", str(a), "-i", str(b), "-lavfi",
- f"[0:v]setpts=N/FRAME_RATE/TB,{same}[a];[1:v]setpts=N/FRAME_RATE/TB,{same}[b];[a][b]psnr", "-f", "null", "-"],
- stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace")
- m = re.search(r"average:(inf|[\d.]+)", proc.stderr)
- assert m, proc.stderr[-400:]
- return float("inf") if m.group(1) == "inf" else float(m.group(1))
-
- def test_filter_paths_with_drive_colon_spaces_and_unicode(self):
- """subtitles= / ass= / lut3d=file= / fontfile= take a path with a colon, spaces and non-ASCII.
-
- A Windows path `D:\\a\\x.srt` is what broke on the Windows CI: the filter option value is
- parsed twice, so the colon needs two levels of escaping. On POSIX a directory literally named
- `D:` reproduces it; on Windows the real drive letter does.
- """
- base = OUT / "compat dir ünïcode"
- d = base if os.name == "nt" else base / "D:"
- d.mkdir(parents=True, exist_ok=True)
- src = d / "src vid.mp4"
- shutil.copyfile(self.src, src)
- cues = d / "cues täxt.txt"
- cues.write_text("0:00-0:06 Hello caption\n", encoding="utf-8")
- # captions via subtitles= (SRT) and ass=, both re-parsed by libass
- cap = d / "cap.mp4"
- script("caption.py", src, "--text", cues, "--size", "40", "--fast", "-o", cap)
- self.assertLess(self._psnr(self.src, cap), 45, "burned caption changed the picture")
- capa = d / "cap ass.mp4"
- script("caption.py", src, "--text", cues, "--animate", "pop", "--fast", "-o", capa)
- self.assertTrue((d / "cap ass.ass").exists())
- self.assertLess(self._psnr(self.src, capa), 45)
- # a fonts dir with the same kind of path
- script("caption.py", src, "--text", cues, "--fonts-dir", d, "--fast", "-o", d / "cap fonts.mp4")
- # LUT file: full strength inverts the picture, half strength goes through the split/blend graph
- lut = d / "invert lut.cube"
- lines = ["LUT_3D_SIZE 2"] + [f"{1 - r} {1 - g} {1 - b}" for b in (0, 1) for g in (0, 1) for r in (0, 1)]
- lut.write_text("\n".join(lines) + "\n")
- inv = d / "lut.mp4"
- script("color.py", src, "--lut", lut, "--preset", "veryfast", "-o", inv)
- self.assertLess(self._psnr(self.src, inv), 15, "inverted LUT changed every pixel")
- half = d / "lut half.mp4"
- script("color.py", src, "--lut", lut, "--lut-strength", "0.5", "--preset", "veryfast", "-o", half)
- self.assertClose(probe(str(half))["duration"], 12.0, 0.2)
- # drawtext fontfile= with the same path shape (when a TTF is available to copy)
- font = self._any_ttf()
- if font:
- ttf = d / "my font.ttf"
- shutil.copyfile(font, ttf)
- script("overlay.py", src, "--text", "Hi", "--font-file", ttf, "--fast", "-o", d / "ov.mp4")
-
- @staticmethod
- def _any_ttf():
- for root in ("/usr/share/fonts", "/usr/local/share/fonts", "/Library/Fonts", "/System/Library/Fonts", "C:/Windows/Fonts"):
- for pat in ("**/DejaVuSans.ttf", "**/Arial.ttf", "**/arial.ttf", "**/*.ttf"):
- hits = list(Path(root).glob(pat)) if Path(root).exists() else []
- if hits:
- return hits[0]
- return None
-
- def test_overlay_still_is_bounded_by_the_video_length(self):
- """A looped still (-loop 1) must not make the output longer than the video (FFmpeg 7+ -shortest keeps a buffer)."""
- out = OUT / "ov_bound.mp4"
- data = json.loads(script("overlay.py", self.src, "--image", self.logo, "--fast", "-o", out, "--json").stdout)
- self.assertIn("-t", data["commands"][0])
- self.assertClose(data["probe"]["duration"], 12.0, 0.15)
-
- def test_overlay_on_audio_less_video_terminates(self):
- """Every other overlay test uses self.src, which has audio. Cover the audio-less case too:
- overlay is documented elsewhere as risky on inputs with no audio stream to help -shortest
- bound the looped-image (-loop 1) input, so pin down that it completes and the output duration
- matches the source exactly (the explicit -t, not -shortest, is what actually bounds it)."""
- noaudio = OUT / "overlay_noaudio_source.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-an", "-c:v", "copy", noaudio)
- self.assertIsNone(probe(str(noaudio)).get("audio"))
- out = OUT / "overlay_noaudio.mp4"
- proc = subprocess.run(
- [sys.executable, str(SCRIPTS / "overlay.py"), str(noaudio), "--image", str(self.logo),
- "--position", "bottom-right", "--start", "1", "--end", "5", "--fade", "0.3", "-o", str(out)],
- stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", timeout=60)
- self.assertEqual(proc.returncode, 0, f"STDOUT:\n{proc.stdout}\nSTDERR:\n{proc.stderr}")
- self.assertClose(probe(str(out))["duration"], probe(str(noaudio))["duration"], 0.15)
-
- def test_overlay_audio_stream_selects_the_requested_track_not_always_the_first(self):
- two = OUT / "ov_two_streams.mkv"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
- "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
- "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
- self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
- out_text = OUT / "ov_two_text.mp4"
- script("overlay.py", two, "--text", "hi", "--audio-stream", "1", "-o", out_text, "--preset", "veryfast")
- self.assertIsNotNone(probe(str(out_text))["audio"])
- out_img = OUT / "ov_two_img.mp4"
- script("overlay.py", two, "--image", self.logo, "--audio-stream", "1", "-o", out_img, "--preset", "veryfast")
- self.assertIsNotNone(probe(str(out_img))["audio"])
- proc = script("overlay.py", two, "--text", "hi", "--audio-stream", "5", "-o", OUT / "ov_nope.mp4", "--json", expect_fail=True)
- self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
- self.assertIn("audio-stream", proc.stderr)
-
- def test_overlay_video_pip_composites_at_the_right_position(self):
- red_bg = OUT / "red_bg.mp4"
- blue_quad = OUT / "blue_quad.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=red:s=1280x720:d=1",
- "-c:v", "libx264", "-pix_fmt", "yuv420p", red_bg)
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=blue:s=200x50:d=1",
- "-c:v", "libx264", "-pix_fmt", "yuv420p", blue_quad)
- out = OUT / "pip1.mp4"
- script("overlay.py", red_bg, "--video", blue_quad, "--position", "bottom-right", "--scale", "200", "-o", out)
-
- def px(path, x, y):
- r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path),
- "-vf", f"crop=2:2:{x}:{y}", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
- stdout=subprocess.PIPE, stderr=subprocess.PIPE)
- return r.stdout[:3]
-
- # PiP at bottom-right, 200 wide (50 tall for the 4:1 source), default margin 24:
- # x=1280-200-24=1056, y=720-50-24=646
- self.assertGreater(px(out, 1100, 660)[2], 100, "PiP area should show the blue overlay")
- self.assertGreater(px(out, 100, 100)[0], 100, "outside the PiP area, the red background must remain")
-
- def test_overlay_chromakey_removes_the_key_color(self):
- red_bg = OUT / "ck_red_bg.mp4"
- green_fg = OUT / "ck_green_fg.mp4"
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=red:s=100x100:d=1",
- "-c:v", "libx264", "-pix_fmt", "yuv420p", red_bg)
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=0x00ff00:s=100x100:d=1",
- "-f", "lavfi", "-i", "color=c=white:s=20x20:d=1", "-filter_complex", "[0][1]overlay=40:40",
- "-c:v", "libx264", "-pix_fmt", "yuv420p", green_fg)
- out = OUT / "ck1.mp4"
- script("overlay.py", red_bg, "--video", green_fg, "--chromakey", "0x00ff00", "--position", "top-left",
- "--margin", "0", "--scale", "100", "-o", out)
-
- def px(path, x, y):
- r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path),
- "-vf", f"crop=2:2:{x}:{y}", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
- stdout=subprocess.PIPE, stderr=subprocess.PIPE)
- return r.stdout[:3]
-
- self.assertGreater(px(out, 10, 10)[0], 100, "keyed-out green should show the red background through it")
- self.assertGreater(min(px(out, 45, 45)), 100, "the white square inside the green should be unaffected")
-
- def test_overlay_chromakey_without_video_refused(self):
- script("overlay.py", self.src, "--chromakey", "green", expect_fail=True)
-
- def test_help_survives_a_legacy_console_encoding(self):
- """--help contains non-ASCII (Japanese example, arrows); a cp1252 console must not raise UnicodeEncodeError."""
- env = dict(os.environ, PYTHONIOENCODING="cp1252")
- for name in ("overlay.py", "render.py", "caption.py"):
- proc = subprocess.run([sys.executable, str(SCRIPTS / name), "--help"], stdout=subprocess.PIPE, stderr=subprocess.PIPE,
- env=env, encoding="utf-8", errors="replace")
- self.assertEqual(proc.returncode, 0, f"{name}: {proc.stderr[-300:]}")
- self.assertIn("usage:", proc.stdout)
-
- def test_run_records_commands_on_a_passed_context_not_the_global_state(self):
- """1.10 threads an optional `ctx=` through run()/emit()/die() (issue #189 B; 2.0 makes it
- required). A fresh Context() must collect that call's commands itself and leave the
- process-global STATE untouched, which is the property the 2.0 signature change relies on."""
- import _common
- ctx = _common.Context()
- ctx.dry_run = True
- before = list(_common.STATE.commands)
- proc = _common.run(["ffmpeg", "-i", "in.mp4", "out.mp4"], quiet=True, ctx=ctx)
- self.assertEqual(proc.returncode, 0, "a dry run plans without executing ffmpeg")
- self.assertEqual(ctx.commands, ["ffmpeg -i in.mp4 out.mp4"])
- self.assertEqual(_common.STATE.commands, before, "the global STATE must not have seen this call")
-
- def test_crf_warns_once_as_a_deprecated_alias_of_quality(self):
- """docs/contract.md, "Deprecation policy" step 1: the old spelling keeps working and says
- what replaces it. argparse's own default (18) must stay silent."""
- quiet = script("cut.py", self.src, "--start", "0", "--end", "1", "--dry-run", "-o", str(OUT / "crf_default.mp4"))
- self.assertNotIn("--crf is deprecated", quiet.stderr)
- warned = script("cut.py", self.src, "--start", "0", "--end", "1", "--crf", "20", "--dry-run", "-o", str(OUT / "crf_explicit.mp4"))
- self.assertIn("--crf is deprecated", warned.stderr)
- self.assertIn("--quality", warned.stderr)
- helptext = " ".join(script("cut.py", "--help").stdout.split())
- self.assertIn("(deprecated: use --quality)", helptext)
-
- def test_json_brief_is_a_shorter_json_with_the_same_verdict(self):
- """1.11.0 token diet: `--json-brief` is additive -- the same success document with the
- probe summarised, the command lines counted and the per-step verification list dropped.
- `--json` itself must be untouched, so both are run on the same edit and compared."""
- full = json.loads(script("cut.py", self.src, "--start", "0", "--end", "2", "-o", str(OUT / "brief_full.mp4"), "--json").stdout)
- brief = json.loads(script("cut.py", self.src, "--start", "0", "--end", "2", "-o", str(OUT / "brief_short.mp4"), "--json-brief").stdout)
- self.assertEqual(set(full) - set(brief), {"probe", "verification"}, "only the bulky keys go")
- self.assertEqual(set(brief) - set(full), {"summary"})
- self.assertEqual(brief["status"], "completed")
- self.assertEqual(brief["dry_run"], full["dry_run"])
- self.assertEqual(brief["verified"], full["verified"])
- self.assertNotIn("probe", brief)
- self.assertNotIn("verification", brief)
- self.assertEqual(brief["commands"], len(full["commands"]), "commands is the count, not the list")
- summary = brief["summary"]
- self.assertEqual(summary["width"], full["probe"]["video"]["width"])
- self.assertEqual(summary["height"], full["probe"]["video"]["height"])
- self.assertEqual(summary["vcodec"], full["probe"]["video"]["codec"])
- self.assertEqual(summary["acodec"], full["probe"]["audio"]["codec"])
- self.assertAlmostEqual(summary["duration_s"], full["probe"]["duration"], places=2)
- for key in ("precision", "reencoded", "expected_duration"):
- self.assertEqual(brief[key], full[key], f"{key}: the tool's own keys survive the diet")
- self.assertLess(len(json.dumps(brief)), len(json.dumps(full)) / 2, "the point of the flag is fewer bytes")
-
- def test_json_brief_failure_is_the_usual_failure_document(self):
- """A failure must not be trimmed: die() prints the same document with or without the flag,
- so a caller never loses the error kind, message or hint by asking for brevity."""
- proc = script("cut.py", str(OUT / "does_not_exist.mp4"), "--start", "0", "--end", "1", "--json-brief", expect_fail=True)
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["status"], "failed")
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertTrue(doc["error"]["message"])
- self.assertNotIn("summary", doc)
-
- def test_skill_md_stays_within_the_agent_reading_budget(self):
- """1.11.0: SKILL.md is the file every session loads, so its size is a real per-run cost.
- The two-tier split (long-form prose in references/gotchas.md, one line plus an anchor
- here) brought it from 362 lines / 37.8 KB to under this ceiling; a new rule belongs in a
- references/ file with a one-line pointer, not in an ever-growing SKILL.md."""
- text = (ROOT / "SKILL.md").read_text(encoding="utf-8")
- lines, size = len(text.splitlines()), len(text.encode("utf-8"))
- self.assertLessEqual(lines, 220, f"SKILL.md is {lines} lines; move detail to references/")
- self.assertLessEqual(size, 30000, f"SKILL.md is {size} bytes; move detail to references/")
- gotchas = (ROOT / "references" / "gotchas.md").read_text(encoding="utf-8")
- # every "details:" pointer resolves to a real heading in the file it names
- for anchor in re.findall(r"references/gotchas\.md#([a-z0-9-]+)", text):
- headings = ["".join(ch for ch in h.lower().replace(" ", "-") if ch.isalnum() or ch == "-")
- for h in re.findall(r"(?m)^#+ (.+)$", gotchas)]
- self.assertIn(anchor, headings, f"SKILL.md points at references/gotchas.md#{anchor}, which has no such heading")
-
- def test_every_script_has_help(self):
- for name in sorted(p.name for p in SCRIPTS.glob("*.py") if not p.name.startswith("_")):
- with self.subTest(script=name):
- out = script(name, "--help").stdout
- self.assertIn("usage:", out)
-
-
-# ---------------------------------------------------------------------------- fonts by script (1.12)
-def _no_fontconfig():
- """fc-list absent (a bare container, Windows) -- the script->font resolution cannot be
- exercised, and skipping says so rather than failing on an environment gap."""
- return shutil.which("fc-list") is None and platform.system() != "Windows"
-
-
-class ScriptFontTests(unittest.TestCase):
- """1.12: which script text is written in, and a font file that actually covers it."""
-
- def test_detect_script_reads_the_characters_not_the_locale(self):
- cases = {
- "こんにちは世界": "ja", # kana + han -> Japanese
- "カタカナ": "ja",
- "你好世界": "zh", # han alone -> Chinese
- "안녕하세요": "ko",
- "ㅎㅏㄴ": "ko", # jamo, not syllables
- "مرحبا بالعالم": "ar",
- "שלום עולם": "he",
- "नमस्ते दुनिया": "hi",
- "สวัสดีชาวโลก": "th",
- "Привет мир": "ru",
- "Γειά σου κόσμε": "el",
- "Hello world": "latin",
- "": "latin",
- "1080p 30fps": "latin",
- }
- for text, expected in cases.items():
- with self.subTest(text=text):
- self.assertEqual(detect_script(text), expected)
-
- def test_detect_script_mixed_text_goes_by_character_count(self):
- self.assertEqual(detect_script("Episode 12 — 日本語のテスト"), "ja")
- self.assertEqual(detect_script("Part 2: 第二部分的内容说明"), "zh")
- # kana anywhere makes the whole string Japanese, however few
- self.assertEqual(detect_script("漢字漢字漢字の"), "ja")
- # the non-Latin script with the most characters wins
- self.assertEqual(detect_script("Привет 你好世界大家好"), "zh")
-
- def test_lang_hint_only_breaks_the_han_only_tie(self):
- """Han with no kana is Chinese by default; only the caller knows when it is Japanese or
- Korean hanja. The hint never overrides what the characters already prove."""
- self.assertEqual(detect_script("漢字表記"), "zh")
- self.assertEqual(detect_script("漢字表記", lang="ja"), "ja")
- self.assertEqual(detect_script("漢字表記", lang="ko"), "ko")
- self.assertEqual(detect_script("漢字表記", lang="ja-JP"), "ja")
- self.assertEqual(detect_script("こんにちは", lang="zh"), "ja", "kana is not ambiguous -- the hint must not win")
- self.assertEqual(detect_script("안녕하세요", lang="ja"), "ko")
-
- @unittest.skipIf(_no_fontconfig(), "no fc-list on this machine: fonts cannot be resolved by script here")
- def test_font_for_script_finds_a_real_file_for_every_script(self):
- for script in ("ja", "zh", "ko", "ar", "he", "hi", "th", "ru", "el"):
- with self.subTest(script=script):
- path = font_for_script(script)
- if path is None:
- self.skipTest(f"this machine has no font covering {script}")
- self.assertTrue(os.path.exists(path), path)
- family = font_family_for_script(script)
- self.assertTrue(family)
- # "Unifont Sample" draws the code point in a box instead of the glyph -- the exact
- # unreadable result this feature exists to avoid. It is only ever acceptable when
- # nothing else on the machine covers the script at all.
- if any(f for f in _families_for(script) if "unifont" not in f.lower()):
- self.assertNotIn("unifont", family.lower(),
- f"{script}: picked {family} while a real font is installed")
-
- @unittest.skipIf(_no_fontconfig(), "no fc-list on this machine")
- def test_font_for_script_is_cached_and_stable(self):
- self.assertEqual(font_for_script("ja"), font_for_script("ja"))
-
-
-class DemoGalleryTests(unittest.TestCase):
- """The gallery in docs/demos.md is committed, so its builder is a shipped artefact: if
- demos/build.py stops rendering, the README's pictures quietly describe an older tool.
-
- One cheap demo is enough to prove the whole path -- fixtures, a real script invocation, the
- side-by-side, the preview and the size budget -- without spending several minutes of CI on all
- of them (the `demos` job in demos/CI.md runs the full set)."""
-
- def test_build_one_demo_and_stay_under_the_preview_budget(self):
- if not shutil.which("ffmpeg"):
- if os.environ.get("CI"):
- raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step")
- raise unittest.SkipTest("ffmpeg not on PATH")
- from _common import script_font_status
- if script_font_status("ja") == "missing":
- # Not a failure: the demo itself skips for the same reason. A machine with no CJK
- # font cannot render Japanese captions, and a tofu-filled GIF would be worse than none.
- raise unittest.SkipTest("no font on this machine covers Japanese: captions_ja cannot render")
- preview = ROOT / "docs" / "demos" / "captions_ja.gif"
- before = preview.read_bytes() if preview.exists() else None
- try:
- sh(sys.executable, ROOT / "demos" / "build.py", "--only", "captions_ja")
- self.assertTrue(preview.exists(), f"{preview} was not written")
- size = preview.stat().st_size
- self.assertLessEqual(size, 500 * 1024,
- f"{preview.name} is {size} bytes; previews are committed and "
- f"capped at 500 KB (demos/build.py enforces this too)")
- self.assertGreater(size, 1024, "a preview that small did not render anything")
- for name in ("captions_ja_before.mp4", "captions_ja_after.mp4", "captions_ja.mp4"):
- self.assertTrue((ROOT / "demos" / "out" / name).exists(), f"demos/out/{name} missing")
- finally:
- # Leave the committed preview exactly as it was: this machine's ffmpeg writes
- # different GIF bytes than the one that built the gallery, and a test must not
- # dirty the working tree it ran in.
- if before is not None:
- preview.write_bytes(before)
-
- def test_every_demo_in_the_table_is_listed_and_documented(self):
- """--list and docs/demos.md are two views of the same table; a demo added to the
- builder without a gallery entry is a picture nobody ever sees."""
- listed = sh(sys.executable, ROOT / "demos" / "build.py", "--list").stdout
- names = [line.split()[0] for line in listed.splitlines() if line.strip()]
- self.assertGreaterEqual(len(names), 10, "the gallery lost most of its demos")
- page = (ROOT / "docs" / "demos.md").read_text(encoding="utf-8")
- for name in names:
- self.assertIn(f"demos/{name}.gif", page,
- f"{name} is built but has no section in docs/demos.md "
- f"(run: python3 demos/build.py --docs)")
-
- def test_every_script_is_shown_working_by_a_demo(self):
- """A tool nobody can see working is hard to review and harder to trust. Every script
- under scripts/ either appears in a demo's command line (so the gallery renders it end to
- end on every build) or is on the builder's INSPECTION list -- the tools whose entire
- output is a table or an HTML file, which get a command and a sentence in docs/demos.md
- instead of a picture. Nothing is allowed to be in neither list."""
- sys.path.insert(0, str(ROOT / "demos"))
- try:
- import build as demo_build
- finally:
- sys.path.pop(0)
- commands = " ".join(cmd for name in demo_build.BY_NAME
- for cmd in demo_build._commands_for(name))
- inspection = {tool for tool, _cmd, _what in demo_build.INSPECTION}
- page = (ROOT / "docs" / "demos.md").read_text(encoding="utf-8")
- for script in sorted(p.name for p in (ROOT / "scripts").glob("*.py")):
- if script.startswith("_"):
- continue
- if script in inspection:
- self.assertIn(script, page,
- f"{script} is on demos/build.py's INSPECTION list but is not in "
- f"docs/demos.md (run: python3 demos/build.py --docs)")
- continue
- self.assertIn(f"scripts/{script} ", commands + " ",
- f"no demo in demos/build.py runs {script}: add one (a before/after "
- f"demo) or, if it only ever prints a table, add it to INSPECTION")
-
-
-# ---------------------------------------------------------------------------- emoji + shaping (1.15)
-def _emoji_assets(names=("1f389", "1f44d", "1f1ef-1f1f5", "1f469-200d-1f4bb")):
- """A directory of placeholder emoji PNGs drawn by ffmpeg at run time.
-
- The package ships no emoji art on purpose: Twemoji is CC-BY 4.0 and Noto Emoji OFL/Apache-2.0,
- and a test does not need to redistribute either. What --emoji-assets actually requires is the
- NAMING (lowercase hex code points joined by '-'), which a coloured square proves exactly as
- well as a real glyph.
- """
- d = OUT / "emoji_assets"
- d.mkdir(parents=True, exist_ok=True)
- for i, name in enumerate(names):
- path = d / (name + ".png")
- if not path.exists():
- colour = ("orange", "gold", "tomato", "limegreen")[i % 4]
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi",
- "-i", "color=c=%s:s=72x72:d=0.04" % colour, "-vf", "format=rgba",
- "-frames:v", "1", str(path))
- return d
-
-
-class EmojiTests(unittest.TestCase):
- """1.15: emoji are detected as clusters, measured at a full em, reserved in the ASS and
- composited as PNGs -- and every degraded path says so instead of lying."""
-
- @classmethod
- def setUpClass(cls):
- if not shutil.which("ffmpeg"):
- if os.environ.get("CI"):
- raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step")
- raise unittest.SkipTest("ffmpeg not on PATH")
- OUT.mkdir(parents=True, exist_ok=True)
- cls.src = OUT / "emoji_src.mp4"
- if not cls.src.exists():
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=25",
- "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000",
- "-t", "4", "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p",
- "-c:a", "aac", str(cls.src))
- cls.cues = OUT / "cues_emoji.txt"
- cls.cues.write_text("0:00-0:02 Hello \U0001F389 world\n0:02-0:04 Nice \U0001F44D job\n",
- encoding="utf-8")
-
- def test_emoji_cluster_detection_keeps_zwj_and_skin_tone_sequences_together(self):
- from _common import emoji_clusters, emoji_codepoint_name, has_emoji
- text = "\u3084\u3063\u305f \U0001F389 \U0001F469\u200d\U0001F4BB \U0001F1EF\U0001F1F5 \U0001F44D\U0001F3FD 1\ufe0f\u20e3"
- names = [emoji_codepoint_name(cl) for _i, cl in emoji_clusters(text)]
- self.assertEqual(names, ["1f389", "1f469-200d-1f4bb", "1f1ef-1f1f5", "1f44d-1f3fd", "31-fe0f-20e3"])
- self.assertTrue(has_emoji(text))
- self.assertFalse(has_emoji("plain ascii"))
-
- def test_emoji_is_orthogonal_to_the_writing_system(self):
- """A cue can be Japanese AND emoji: adding an "emoji" script would corrupt the font
- resolution for the rest of the line."""
- self.assertEqual(detect_script("\u3084\u3063\u305f \U0001F389"), "ja")
- self.assertEqual(detect_script("Hello \U0001F389"), "latin")
-
- def test_caption_wrap_counts_an_emoji_as_a_full_width_atom(self):
- from _common import text_width_em
- import importlib, sys as _s
- _s.path.insert(0, str(SCRIPTS))
- caption = importlib.import_module("caption")
- self.assertAlmostEqual(text_width_em("\U0001F389"), 1.0, places=6)
- self.assertAlmostEqual(text_width_em("\U0001F389", 1.5), 1.5, places=6)
- # a wrap never breaks inside a cluster
- lines = caption.wrap_text("aaa \U0001F469\u200d\U0001F4BB bbb", 3.0)
- self.assertIn("\U0001F469\u200d\U0001F4BB", lines)
- for line in lines:
- self.assertNotEqual(line, "\U0001F469")
-
- def _plan(self, *extra):
- out = OUT / "emoji_out.mp4"
- proc = script("caption.py", self.src, "--text", self.cues, "-o", out,
- "--dry-run", "--json", *extra)
- return json.loads(proc.stdout)
-
- def test_caption_emoji_overlay_places_one_png_per_cluster_inside_the_safe_area(self):
- doc = self._plan("--emoji-assets", _emoji_assets())
- self.assertEqual(doc["emoji"]["mode"], "png")
- self.assertEqual(doc["emoji"]["overlays"], 2)
- graph = [c for c in doc["commands"] if "overlay=" in c][-1]
- overlays = re.findall(r"overlay=x=(\d+):y=(\d+):enable=\D*?between\(t,([\d.]+),([\d.]+)\)", graph)
- self.assertEqual(len(overlays), 2, graph)
- for x, y, start, end in overlays:
- x, y = int(x), int(y)
- self.assertTrue(0.05 * 640 <= x <= 0.95 * 640, f"x={x} outside the safe area")
- self.assertTrue(0.05 * 360 <= y <= 0.95 * 360, f"y={y} outside the safe area")
- self.assertLess(float(start), float(end))
- self.assertEqual([(o[2], o[3]) for o in overlays], [("0.000", "2.000"), ("2.000", "4.000")])
-
- def test_caption_emoji_placeholder_reserves_the_gap_in_the_generated_ass(self):
- out = OUT / "emoji_ass.mp4"
- script("caption.py", self.src, "--text", self.cues, "-o", out,
- "--emoji-assets", _emoji_assets())
- ass = (OUT / "emoji_ass.ass").read_text(encoding="utf-8-sig")
- dialogue = [l for l in ass.splitlines() if l.startswith("Dialogue:")]
- self.assertTrue(dialogue)
- for line in dialogue:
- self.assertIn("\\alpha&HFF&", line)
- self.assertNotIn("\U0001F389", line, "the raw code point must not reach the drawn text")
- self.assertNotIn("\U0001F44D", line)
-
- def test_the_emoji_placeholder_reserves_exactly_the_box_it_asks_for(self):
- """The reservation is measured, not assumed: U+2588 is 0.66-0.83 em depending on the face,
- so the gap is reserved with alpha-hidden \\fsp spacing, which is exact in every face."""
- from _ass_overlay import emoji_placeholder
- families = ["FreeSans", "DejaVu Sans", "IPAPGothic", "WenQuanYi Zen Hei", "Loma"]
- tested = 0
- for family in families:
- if not _family_installed(family):
- continue
- tested += 1
- base = _ass_advance(family, "|")
- with_gap = _ass_advance(family, emoji_placeholder(60) + "|")
- if base is None or with_gap is None:
- self.skipTest("libass render probe produced no ink here")
- self.assertAlmostEqual(with_gap - base, 60, delta=2,
- msg=f"{family}: reserved {with_gap - base}px, asked for 60")
- if not tested:
- self.skipTest("none of the measured families is installed here")
-
- def test_caption_emoji_without_assets_is_a_warning_not_a_failure(self):
- from _common import emoji_support
- support = emoji_support(probe=True)
- if support["mode"] not in ("mono", "none"):
- self.skipTest("this machine has a colour emoji path; the degraded branch cannot be exercised")
- out = OUT / "emoji_mono.mp4"
- proc = script("caption.py", self.src, "--text", self.cues, "-o", out, "--json")
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["status"], "completed")
- self.assertEqual(doc["emoji"]["mode"], support["mode"])
- if support["mode"] == "mono":
- self.assertIn("monochrome", proc.stderr + proc.stdout)
- self.assertTrue(any("monochrome" in n for n in doc.get("notes", [])), doc.get("notes"))
-
- def test_emoji_assets_directory_that_does_not_exist_is_a_failed_job(self):
- out = OUT / "emoji_missing.mp4"
- proc = script("caption.py", self.src, "--text", self.cues, "-o", out, "--json",
- "--emoji-assets", str(OUT / "no_such_emoji_dir"), expect_fail=True)
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("twemoji", doc["error"]["message"].lower())
- self.assertIn("no network", doc["error"]["message"].lower())
-
- def test_the_skill_never_fetches_an_emoji_asset(self):
- """Mirror of the existing no-network assertions: nothing on the emoji path may import a
- network module, and no tool offers a download flag for one."""
- import _common
- source = Path(_common.__file__).read_text(encoding="utf-8")
- for banned in ("urllib", "http.client", "requests", "socket."):
- self.assertNotIn(banned, source, f"{banned} is reachable from the emoji path")
- for tool in ("caption.py", "graphics.py", "overlay.py"):
- helptext = script(tool, "--help").stdout.lower()
- self.assertNotIn("--emoji-download", helptext)
- self.assertNotIn("download", helptext.split("--emoji")[-1][:400])
-
- def test_caption_emoji_overlay_is_capped(self):
- many = OUT / "cues_many_emoji.txt"
- many.write_text("".join("0:0%d-0:0%d %s\n" % (i, i + 1, "\U0001F389" * 9)
- for i in range(0, 8)), encoding="utf-8")
- out = OUT / "emoji_capped.mp4"
- proc = script("caption.py", self.src, "--text", many, "-o", out, "--json", "--dry-run",
- "--emoji-assets", _emoji_assets(), "--emoji-max", "4", expect_fail=True)
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("--emoji-max", doc["error"]["message"])
-
- def test_graphics_all_emoji_title_without_a_glyph_is_a_failed_job(self):
- out = OUT / "emoji_title.mp4"
- proc = script("graphics.py", self.src, "--template", "title", "--title", "\U0001F389",
- "--start", "0", "--end", "2", "--emoji", "none", "-o", out, "--json",
- expect_fail=True)
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("blank", doc["error"]["message"])
-
- def test_overlay_text_refuses_the_png_emoji_route_and_names_the_tools_that_have_one(self):
- out = OUT / "emoji_overlay.mp4"
- proc = script("overlay.py", self.src, "--text", "Ship it \U0001F680", "--emoji", "png",
- "-o", out, "--json", expect_fail=True)
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("caption.py", doc["error"]["message"])
- self.assertIn("graphics.py", doc["error"]["message"])
-
-
- # ---------------------------------------------------------------- 1.15.0 fix pass
- def test_emoji_cluster_never_starts_at_a_joiner_a_selector_or_a_plain_letter(self):
- """U+200D ZWJ and U+200C ZWNJ are ordinary Indic/Persian orthography, not emoji: क्‍ष is
- ka + virama + ZWJ + ssa. Treating a joiner (or a VS16, or a skin-tone modifier) as a
- cluster TAIL that glues itself to whatever stands before it turned a Hindi conjunct into
- "an emoji" -- reported as such, warned about as monochrome, and on the PNG route replaced
- by an invisible gap, i.e. a different word. A cluster may only START at an emoji base."""
- from _common import emoji_clusters, emoji_codepoint_name, has_emoji
-
- def names(text):
- return [emoji_codepoint_name(cl) for _i, cl in emoji_clusters(text)]
-
- self.assertEqual(names("\u0915\u094d\u200d\u0937"), [], "a Hindi conjunct is not an emoji")
- self.assertFalse(has_emoji("\u0905\u200c\u092c"), "a ZWNJ is not an emoji either")
- self.assertEqual(names("abc\u200ddef"), [])
- self.assertEqual(names("A\ufe0f"), [], "a VS16 after a letter does not make it an emoji")
- self.assertEqual(names("\u00a9 \u2122 0123456789"), [], "(c), (tm) and digits are not emoji")
- # ... and every real cluster still survives whole
- self.assertEqual(names("\U0001F468\u200d\U0001F469\u200d\U0001F467"),
- ["1f468-200d-1f469-200d-1f467"])
- self.assertEqual(names("\U0001F3F3\ufe0f\u200d\U0001F308"), ["1f3f3-fe0f-200d-1f308"])
- self.assertEqual(names("1\ufe0f\u20e3"), ["31-fe0f-20e3"])
- self.assertEqual(names("\U0001F1EF\U0001F1F5"), ["1f1ef-1f1f5"])
-
- def test_vs15_asks_for_the_character_not_the_picture(self):
- """U+FE0E is the TEXT presentation selector: the author explicitly asked for the glyph,
- so the cluster must not be routed to the PNG overlay."""
- from _common import emoji_clusters
- self.assertEqual(emoji_clusters("\u2764\ufe0e"), [], "VS15 means: draw the character")
- self.assertTrue(emoji_clusters("\u2764\ufe0f"), "VS16 still means: draw the emoji")
-
- def test_caption_emoji_png_is_on_screen_for_the_whole_cue_and_only_that_cue(self):
- """The one assertion the 1.15.0 emoji tests were all missing: a rendered frame from the
- MIDDLE of the cue. A PNG input is a single frame at pts 0, so `eof_action=pass` (which
- switches off overlay's "hold the last frame of the secondary input") composited every
- emoji on frame 0 and nowhere else -- the demo GIF shipped an empty reserved gap."""
- cues = OUT / "cues_one_emoji.txt"
- cues.write_text("0:00-0:02 Hello \U0001F389 world\n", encoding="utf-8")
- out = OUT / "emoji_midcue.mp4"
- doc = json.loads(script("caption.py", self.src, "--text", cues, "-o", out, "--json",
- "--dry-run", "--emoji-assets", _emoji_assets()).stdout)
- graph = [c for c in doc["commands"] if "overlay=" in c][-1]
- m = re.search(r"overlay=x=(\d+):y=(\d+)", graph)
- self.assertTrue(m, graph)
- x, y = int(m.group(1)) + 4, int(m.group(2)) + 4
- script("caption.py", self.src, "--text", cues, "-o", out,
- "--emoji-assets", _emoji_assets())
- orange = (255, 165, 0) # _emoji_assets() draws 1f389 as a plain orange square
-
- def near(pix):
- return sum(abs(a - b) for a, b in zip(pix, orange)) < 60
-
- self.assertTrue(near(_pixel_at(out, 1.0, x, y)),
- "the emoji is gone by the middle of its own cue: %r" % (_pixel_at(out, 1.0, x, y),))
- self.assertTrue(near(_pixel_at(out, 1.8, x, y)), "the emoji left before its cue ended")
- self.assertFalse(near(_pixel_at(out, 3.0, x, y)),
- "the emoji is still on screen a second after its cue ended")
-
- def test_caption_rtl_emoji_is_placed_by_the_rendered_order_not_the_logical_prefix(self):
- """libass lays an RTL line out right-to-left, so the LOGICAL prefix of a cluster occupies
- the RIGHT end of the rendered line. Measuring from the left put the PNG on top of the
- Arabic text, a prefix-width away from the gap libass actually reserved."""
- from _common import script_font_status
- cues = OUT / "cues_rtl.txt"
- # the emoji is FIRST in logical order, so it must be drawn at the RIGHT end of the line
- cues.write_text("0:00-0:02 \U0001F389 \u0645\u0631\u062d\u0628\u0627 \u0628\u0627\u0644\u0639\u0627\u0644\u0645\n",
- encoding="utf-8")
- out = OUT / "emoji_rtl.mp4"
- doc = json.loads(script("caption.py", self.src, "--text", cues, "-o", out, "--json",
- "--dry-run", "--emoji-assets", _emoji_assets()).stdout)
- graph = [c for c in doc["commands"] if "overlay=" in c][-1]
- m = re.search(r"overlay=x=(\d+):y=(\d+)", graph)
- self.assertTrue(m, graph)
- x, y = int(m.group(1)), int(m.group(2))
- self.assertGreater(x, 320, "a logically-first cluster in an RTL line belongs on the right "
- "half of a centred line, not the left: x=%d" % x)
- if script_font_status("ar") != "available":
- self.skipTest("no font on this machine covers Arabic; tests never install fonts")
- # and the box must land where libass drew nothing -- the reserved gap, not over a glyph
- script("caption.py", self.src, "--text", cues, "-o", out, "--emoji-assets", _emoji_assets())
- box = doc["emoji"].get("box_px") or 24
- ink = _ass_ink_columns(OUT / "emoji_rtl.ass", 640, 360)
- if not ink:
- # the probe renders the sidecar with a bare `ass=` filter; without fontconfig (Windows,
- # a static build) libass may resolve no face for Arabic and draw nothing, which says
- # nothing about placement -- the caption itself goes through fontsdir handling
- self.skipTest("the ASS probe drew no ink on this build (libass found no Arabic face)")
- covered = [c for c in range(x + 2, x + box - 2) if c in ink]
- self.assertEqual(covered, [], "the PNG would be composited over drawn text at columns %r" % covered)
-
- def test_caption_emoji_max_zero_means_no_overlays_at_all(self):
- """`int(args.emoji_max or 60)` swallowed the one value a caller would use to say 'none'."""
- out = OUT / "emoji_max0.mp4"
- doc = json.loads(script("caption.py", self.src, "--text", self.cues, "-o", out, "--json",
- "--dry-run", "--emoji-assets", _emoji_assets(), "--emoji-max", "0",
- expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("limit 0", doc["error"]["message"])
-
- def test_caption_animate_fades_the_emoji_with_the_text(self):
- """--animate fade gives the TEXT a \\fad; the PNG used to pop in against a fading line."""
- cues = OUT / "cues_fade_emoji.txt"
- cues.write_text("0:00-0:02 Hello \U0001F389 world\n", encoding="utf-8")
- out = OUT / "emoji_fade.mp4"
- doc = json.loads(script("caption.py", self.src, "--text", cues, "-o", out, "--json",
- "--dry-run", "--animate", "fade",
- "--emoji-assets", _emoji_assets()).stdout)
- graph = [c for c in doc["commands"] if "overlay=" in c][-1]
- self.assertIn("fade=t=in", graph)
- self.assertIn("fade=t=out", graph)
- self.assertIn("alpha=1", graph)
- m = re.search(r"overlay=x=(\d+):y=(\d+)", graph)
- x, y = int(m.group(1)) + 4, int(m.group(2)) + 4
- script("caption.py", self.src, "--text", cues, "-o", out, "--animate", "fade",
- "--emoji-assets", _emoji_assets())
- orange = (255, 165, 0)
-
- def dist(t):
- return sum(abs(a - b) for a, b in zip(_pixel_at(out, t, x, y), orange))
-
- self.assertLess(dist(1.0), 60, "the emoji never reached full opacity")
- self.assertGreater(dist(0.02), dist(1.0), "the emoji did not fade in with the text")
-
- def test_graphics_drawtext_route_never_reports_monochrome_emoji(self):
- """drawtext loads ONE font file and has no fallback chain, so "whatever glyph the text
- font has" is an empty box. Reporting `mode: mono` from that route is a claim the frame
- does not keep: the run must route to libass (which does have a fallback chain) or strip."""
- out = OUT / "emoji_gfx_mono.mp4"
- doc = json.loads(script("graphics.py", self.src, "--template", "title",
- "--title", "Ship it \U0001F389 now", "--start", "0", "--end", "2",
- "-o", out, "--json", "--dry-run").stdout)
- if doc.get("emoji", {}).get("mode") == "mono":
- self.assertEqual(doc["text_renderer"], "ass",
- "mode mono on the drawtext route draws tofu, not a glyph")
- pinned = json.loads(script("graphics.py", self.src, "--template", "title",
- "--title", "Ship it \U0001F389 now", "--start", "0", "--end", "2",
- "--text-render", "drawtext", "-o", out, "--json", "--dry-run").stdout)
- self.assertEqual(pinned["text_renderer"], "drawtext")
- self.assertNotEqual(pinned.get("emoji", {}).get("mode"), "mono",
- "a pinned drawtext run must not claim monochrome either")
-
- def test_graphics_emoji_none_actually_strips_the_cluster(self):
- """`--emoji none` only guarded the all-emoji case: the cluster stayed in the drawn text
- and drawtext drew the same empty box it would have drawn anyway."""
- with_emoji = OUT / "emoji_gfx_none.mp4"
- without = OUT / "emoji_gfx_plain.mp4"
- script("graphics.py", self.src, "--template", "title", "--title", "Ship it \U0001F389 now",
- "--start", "0", "--end", "3", "--emoji", "none", "-o", with_emoji)
- script("graphics.py", self.src, "--template", "title", "--title", "Ship it now",
- "--start", "0", "--end", "3", "-o", without)
- self.assertAlmostEqual(_frame_ink(with_emoji), _frame_ink(without),
- delta=max(1, _frame_ink(without) // 500),
- msg="--emoji none must draw the same frame as text with no emoji in it")
-
- def test_drawn_text_temp_files_are_private_and_never_outlive_the_run(self):
- """1.15.0 wrote every drawn label into a world-shared, predictable, never-cleaned
- /tmp/ffmpeg-skill-text -- including under --dry-run and on the ASS route, which never
- reads them."""
- import glob
- import tempfile as _tf
- out = OUT / "textfile_life.mp4"
- doc = json.loads(script("overlay.py", self.src, "--text", "Label", "-o", out,
- "--json", "--dry-run").stdout)
- m = re.search(r"textfile=(\S+?\.txt)", " ".join(doc["commands"]).replace("\\", ""))
- self.assertTrue(m, "the plan must still name the path it would use")
- self.assertFalse(os.path.exists(m.group(1)), "a dry run wrote a file")
- self.assertFalse(os.path.isdir(os.path.dirname(m.group(1))), "a dry run created a directory")
- self.assertEqual(glob.glob(os.path.join(_tf.gettempdir(), "ffmpeg-skill-text-*")), [],
- "a drawn-text directory was left behind")
- self.assertFalse(os.path.exists(os.path.join(_tf.gettempdir(), "ffmpeg-skill-text")),
- "the shared world-writable directory must not be created at all")
-
- def test_the_ass_route_writes_no_drawtext_textfile(self):
- from _common import script_font_status
- if script_font_status("hi") != "available":
- self.skipTest("no font on this machine covers Devanagari; tests never install fonts")
- import glob
- import tempfile as _tf
- out = OUT / "textfile_ass_route.mp4"
- script("graphics.py", self.src, "--template", "title", "--title", "\u0915\u093f\u0924\u093e\u092c",
- "--start", "0", "--end", "2", "-o", out)
- self.assertEqual(glob.glob(os.path.join(_tf.gettempdir(), "ffmpeg-skill-text-*")), [],
- "the ASS route wrote (and kept) a drawtext textfile it never reads")
-
- def test_the_ass_route_keeps_braces_and_backslashes(self):
- """The same title through drawtext and through libass must produce the same characters:
- 1.15.0 deleted `{`, `}` and `\\` on the ASS route while drawtext kept them."""
- from _ass_overlay import ass_escape
- self.assertEqual(ass_escape("A {b} c \\ d"), "A \\{b\\} c \\ d")
- out = OUT / "ass_braces.mp4"
- doc = json.loads(script("graphics.py", self.src, "--template", "title",
- "--title", "A {b} c \\ d", "--start", "0", "--end", "2",
- "--text-render", "ass", "-o", out, "--json").stdout)
- ass = Path(doc["ass"]).read_text(encoding="utf-8-sig")
- dialogue = next(l for l in ass.splitlines() if l.startswith("Dialogue:"))
- self.assertIn("A \\{b\\} c \\ d", dialogue)
-
-
-def _pixel_at(video, t, x, y):
- """The RGB triple at (x, y) of the frame at `t` seconds of `video`."""
- proc = subprocess.run(["ffmpeg", "-v", "error", "-ss", str(t), "-i", str(video), "-frames:v", "1",
- "-f", "rawvideo", "-pix_fmt", "rgb24", "-"], stdout=subprocess.PIPE)
- w = int(subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
- "stream=width", "-of", "csv=p=0", str(video)],
- stdout=subprocess.PIPE, text=True).stdout.strip())
- off = (y * w + x) * 3
- return tuple(proc.stdout[off:off + 3])
-
-
-def _ass_ink_columns(ass_path, w, h, threshold=60):
- """The set of x columns that carry ink when `ass_path` is rendered over black at w x h."""
- proc = subprocess.run(
- ["ffmpeg", "-v", "error", "-f", "lavfi", "-i", "color=c=black:s=%dx%d:d=0.04" % (w, h),
- "-vf", "ass=%s" % str(ass_path).replace("\\", "/"), "-frames:v", "1",
- "-f", "rawvideo", "-pix_fmt", "gray", "-"], stdout=subprocess.PIPE)
- data = proc.stdout
- if len(data) < w * h:
- return set()
- return {x for x in range(w) if any(data[y * w + x] > threshold for y in range(h))}
-
-
-def _family_installed(family):
- if not shutil.which("fc-list"):
- return False
- proc = subprocess.run(["fc-list", ":family=%s" % family, "file"], stdout=subprocess.PIPE, text=True)
- return bool(proc.stdout.strip())
-
-
-def _ass_advance(family, body):
- """x of the rightmost lit pixel of a left-anchored one-line ASS render, or None."""
- W, H, FS = 900, 140, 60
- path = OUT / "advance.ass"
- path.write_text(
- "[Script Info]\nScriptType: v4.00+\nPlayResX: %d\nPlayResY: %d\nWrapStyle: 2\n\n"
- "[V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, "
- "OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, "
- "Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding\n"
- "Style: D,%s,%d,&H00FFFFFF,&H00FFFFFF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,0,0,7,0,0,0,1\n\n"
- "[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\n"
- "Dialogue: 0,0:00:00.00,0:00:05.00,D,,0,0,0,,{\\pos(0,0)}%s\n" % (W, H, family, FS, body),
- encoding="utf-8-sig")
- proc = subprocess.run(
- ["ffmpeg", "-v", "error", "-f", "lavfi", "-i", "color=c=black:s=%dx%d:d=0.04" % (W, H),
- "-vf", "ass=%s" % str(path).replace("\\", "/"), "-frames:v", "1",
- "-f", "rawvideo", "-pix_fmt", "gray", "-"], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
- data = proc.stdout
- if proc.returncode != 0 or len(data) < W * H:
- return None
- for x in range(W - 1, -1, -1):
- if any(data[y * W + x] > 60 for y in range(H)):
- return x
- return None
-
-
-class ShapingTests(unittest.TestCase):
- """1.15: drawtext does bidi and Arabic joining on a fribidi build but never reorders or
- re-clusters. graphics.py routes what it cannot shape through libass; overlay.py refuses."""
-
- @classmethod
- def setUpClass(cls):
- if not shutil.which("ffmpeg"):
- if os.environ.get("CI"):
- raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step")
- raise unittest.SkipTest("ffmpeg not on PATH")
- OUT.mkdir(parents=True, exist_ok=True)
- cls.src = OUT / "emoji_src.mp4"
- if not cls.src.exists():
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=25", "-t", "4",
- "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", str(cls.src))
-
- def _skip_without(self, script_code):
- from _common import script_font_status
- if script_font_status(script_code) != "available":
- raise unittest.SkipTest("no font on this machine covers %r; tests never install fonts"
- % script_code)
-
- def test_graphics_devanagari_renders_through_libass_not_drawtext(self):
- self._skip_without("hi")
- out = OUT / "shape_hi.mp4"
- doc = json.loads(script("graphics.py", self.src, "--template", "lower-third",
- "--name", "\u092a\u094d\u0930\u093f\u092f\u093e \u0936\u0930\u094d\u092e\u093e",
- "--title", "\u0928\u093f\u0930\u094d\u0926\u0947\u0936\u0915",
- "--start", "0", "--end", "3", "-o", out, "--dry-run", "--json").stdout)
- self.assertEqual(doc["text_renderer"], "ass")
- self.assertEqual(doc["script"], "hi")
- graph = " ".join(doc["commands"])
- self.assertIn("ass=", graph)
- self.assertNotIn("drawtext=", graph, "the text must not also go through drawtext")
-
- def test_graphics_latin_still_renders_through_drawtext(self):
- out = OUT / "shape_latin.mp4"
- doc = json.loads(script("graphics.py", self.src, "--template", "title",
- "--title", "Episode 12", "--start", "0", "--end", "3",
- "-o", out, "--dry-run", "--json").stdout)
- self.assertEqual(doc["text_renderer"], "drawtext")
- self.assertNotIn("ass", doc)
- self.assertIn("drawtext=", " ".join(doc["commands"]))
-
- def test_graphics_drawtext_forced_with_an_indic_script_is_refused_naming_the_script(self):
- self._skip_without("hi")
- out = OUT / "shape_refuse.mp4"
- doc = json.loads(script("graphics.py", self.src, "--template", "title",
- "--title", "\u0915\u093f\u0924\u093e\u092c", "--start", "0", "--end", "3",
- "--text-render", "drawtext", "-o", out, "--json",
- expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("Devanagari", doc["error"]["message"])
- self.assertIn("harfbuzz", doc["error"]["message"])
-
- def test_graphics_arabic_is_not_rerouted_on_a_fribidi_build(self):
- from _common import drawtext_shaping
- if not drawtext_shaping()["fribidi"]:
- raise unittest.SkipTest("this ffmpeg has no fribidi: Arabic legitimately needs the ASS route")
- self._skip_without("ar")
- out = OUT / "shape_ar.mp4"
- doc = json.loads(script("graphics.py", self.src, "--template", "title",
- "--title", "\u0645\u0631\u062d\u0628\u0627 \u0628\u0627\u0644\u0639\u0627\u0644\u0645",
- "--start", "0", "--end", "3", "-o", out, "--dry-run", "--json").stdout)
- self.assertEqual(doc["text_renderer"], "drawtext")
-
- def test_graphics_font_file_override_survives_the_ass_route(self):
- self._skip_without("hi")
- font = font_for_script("hi")
- out = OUT / "shape_fontfile.mp4"
- proc = script("graphics.py", self.src, "--template", "title", "--title",
- "\u0915\u093f\u0924\u093e\u092c", "--start", "0", "--end", "3",
- "--font-file", font, "-o", out, "--json")
- doc = json.loads(proc.stdout)
- self.assertEqual(doc["text_renderer"], "ass")
- self.assertIn("fontsdir=", " ".join(doc["commands"]))
- from _common import font_family_of_file
- family = font_family_of_file(font)
- ass = Path(doc["ass"]).read_text(encoding="utf-8-sig")
- self.assertIn(family, ass, "the --font-file's own family must reach the ASS Style line")
-
- def test_overlay_text_refuses_a_shaping_script_naming_the_tools_that_render_it(self):
- out = OUT / "shape_overlay.mp4"
- doc = json.loads(script("overlay.py", self.src, "--text", "\u0915\u093f\u0924\u093e\u092c",
- "-o", out, "--json", expect_fail=True).stdout)
- self.assertEqual(doc["error"]["kind"], "input")
- self.assertIn("caption.py", doc["error"]["message"])
- self.assertIn("graphics.py", doc["error"]["message"])
-
-
-class ApostropheAndPercentTests(unittest.TestCase):
- """1.15: `'` and `%` reach the picture. They used to be dropped outright by escape_drawtext."""
-
- @classmethod
- def setUpClass(cls):
- if not shutil.which("ffmpeg"):
- if os.environ.get("CI"):
- raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step")
- raise unittest.SkipTest("ffmpeg not on PATH")
- OUT.mkdir(parents=True, exist_ok=True)
- cls.src = OUT / "emoji_src.mp4"
- if not cls.src.exists():
- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
- "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=25", "-t", "4",
- "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", str(cls.src))
-
- def test_drawtext_keeps_an_apostrophe_and_a_percent_sign(self):
- out = OUT / "pct_overlay.mp4"
- doc = json.loads(script("overlay.py", self.src, "--text", "it's 100% done",
- "-o", out, "--json").stdout)
- graph = " ".join(doc["commands"])
- m = re.search(r"textfile=(\S+?\.txt)", graph.replace("\\", ""))
- self.assertTrue(m, graph)
- self.assertIn("expansion=none", graph)
- self.assertTrue(Path(m.group(1)).parent.name.startswith("ffmpeg-skill-text-"),
- "drawn text must go in a private per-run directory: " + m.group(1))
- self.assertFalse(Path(m.group(1)).exists(), "the drawn-text temp file must not outlive the run")
- self.assertEqual(doc["status"], "completed")
- # the drawn ink differs from the same render with the two characters stripped
- stripped = OUT / "pct_overlay_stripped.mp4"
- script("overlay.py", self.src, "--text", "its 100 done", "-o", stripped)
- self.assertNotEqual(_frame_ink(out), _frame_ink(stripped),
- "the apostrophe and the percent sign left no ink on the frame")
-
- def test_caption_keeps_apostrophe_and_percent_in_the_drawn_text(self):
- cues = OUT / "cues_pct.txt"
- cues.write_text("0:00-0:02 it's 100% done\n", encoding="utf-8")
- out = OUT / "pct_caption.mp4"
- script("caption.py", self.src, "--text", cues, "--animate", "fade", "-o", out)
- srt = (OUT / "pct_caption.srt").read_text(encoding="utf-8")
- ass = (OUT / "pct_caption.ass").read_text(encoding="utf-8-sig")
- self.assertIn("it's 100% done", srt)
- self.assertIn("it's 100% done", ass)
-
-
-def _frame_ink(path):
- proc = subprocess.run(["ffmpeg", "-v", "error", "-i", str(path), "-ss", "1", "-frames:v", "1",
- "-f", "rawvideo", "-pix_fmt", "gray", "-"], stdout=subprocess.PIPE)
- return sum(proc.stdout)
-
-
-class WrapReadabilityTests(unittest.TestCase):
- """1.15: no one-character orphan line, and a balanced break for spaced scripts."""
-
- def setUp(self):
- sys.path.insert(0, str(SCRIPTS))
- import importlib
- self.caption = importlib.import_module("caption")
-
- def test_caption_wrap_never_leaves_a_one_character_orphan_line(self):
- C = self.caption
- cases = [
- # th1's Thai cue and dl3's Japanese cue, at sizes where greedy wrapping stranded one character
- ("\u0e1a\u0e23\u0e23\u0e17\u0e31\u0e14\u0e17\u0e35\u0e48\u0e2a\u0e2d\u0e07\u0e02\u0e2d\u0e07\u0e04\u0e33\u0e1a\u0e23\u0e23\u0e22\u0e32\u0e22 "
- "\u0e1a\u0e23\u0e23\u0e17\u0e31\u0e14\u0e19\u0e35\u0e49\u0e15\u0e31\u0e49\u0e07\u0e40\u0e27\u0e25\u0e32\u0e43\u0e2b\u0e49\u0e2d\u0e31\u0e15\u0e42\u0e19\u0e21\u0e31\u0e15\u0e34", 8),
- ("\u3053\u3093\u306b\u3061\u306f\u3001\u4e16\u754c 2 \u884c\u76ee\u306e\u5b57\u5e55\u3067\u3059 "
- "\u81ea\u52d5\u3067\u30bf\u30a4\u30df\u30f3\u30b0\u304c\u6c7a\u307e\u308b\u884c", 10),
- ("\u3053\u3093\u306b\u3061\u306f\u3001\u4e16\u754c 2 \u884c\u76ee\u306e\u5b57\u5e55\u3067\u3059 "
- "\u81ea\u52d5\u3067\u30bf\u30a4\u30df\u30f3\u30b0\u304c\u6c7a\u307e\u308b\u884c", 29),
- ]
- for text, max_em in cases:
- with self.subTest(max_em=max_em):
- greedy = C.wrap_text(text, max_em, balance=False)
- self.assertTrue(len(C._atoms(greedy[-1])) == 1 and C.text_width_em(greedy[-1]) < C.ORPHAN_MIN_EM,
- "the case no longer reproduces greedily: %r" % greedy)
- lines = C.wrap_text(text, max_em)
- self.assertGreater(C.text_width_em(lines[-1]), C.ORPHAN_MIN_EM, lines)
- for line in lines:
- self.assertLessEqual(C.text_width_em(line), max_em, lines)
- self.assertEqual("".join(lines).replace(" ", ""), "".join(greedy).replace(" ", ""))
+sys.path.insert(0, str(Path(__file__).resolve().parent))
- def test_caption_wrap_prefers_a_balanced_break_for_latin(self):
- C = self.caption
- text = "A third line the tool times for me"
- greedy = C.wrap_text(text, 14, balance=False)
- balanced = C.wrap_text(text, 14)
- self.assertEqual(len(greedy), len(balanced))
- self.assertLessEqual(max(C.text_width_em(l) for l in balanced),
- max(C.text_width_em(l) for l in greedy))
- self.assertEqual(" ".join(balanced), text)
- self.assertNotEqual(greedy, balanced, "dl1's break did not move")
+import test_analysis # noqa: E402
+import test_audio # noqa: E402
+import test_delivery # noqa: E402
+import test_editing # noqa: E402
+import test_orchestration # noqa: E402
+import test_picture # noqa: E402
- def test_caption_wrap_rebalance_never_changes_the_line_count(self):
- C = self.caption
- samples = ["A third line the tool times for me",
- "Hello world", "one two three four five six seven eight nine ten",
- "\u3053\u3093\u306b\u3061\u306f\u3001\u4e16\u754c\u306e\u5b57\u5e55\u3067\u3059",
- "Shipping day \U0001F389 for everyone here"]
- for text in samples:
- for max_em in range(4, 30):
- with self.subTest(text=text[:12], max_em=max_em):
- self.assertEqual(len(C.wrap_text(text, max_em)),
- len(C.wrap_text(text, max_em, balance=False)))
+MODULES = (test_analysis, test_editing, test_audio, test_picture, test_delivery, test_orchestration)
-def _families_for(script):
- """Families fontconfig lists for `script`, or [] where there is no fontconfig to ask (Windows
- resolves fonts by file name, so font_for_script() answers there without an fc-list on PATH --
- shelling out unconditionally raised FileNotFoundError in CI)."""
- from _common import FC_LANG
- if not shutil.which("fc-list"):
- return []
- proc = subprocess.run(["fc-list", f":lang={FC_LANG[script]}", "family"], stdout=subprocess.PIPE, text=True)
- return [f for line in proc.stdout.splitlines() for f in line.split(",")]
+def load_tests(loader, tests, pattern):
+ """unittest calls this instead of scanning this module: the cases are in the six group
+ modules, and naming them here keeps the set (and the order groups run in) explicit."""
+ suite = unittest.TestSuite()
+ for module in MODULES:
+ suite.addTests(loader.loadTestsFromModule(module))
+ return suite
if __name__ == "__main__":
diff --git a/tests/test_analysis.py b/tests/test_analysis.py
new file mode 100644
index 0000000..a828e70
--- /dev/null
+++ b/tests/test_analysis.py
@@ -0,0 +1,535 @@
+#!/usr/bin/env python3
+"""End-to-end tests for probe, check, verify, scenes, cropdetect, report, look and sync.
+
+ python3 tests/test_analysis.py # this group alone
+ python3 tests/test_all.py # every group
+"""
+import json
+import os
+import shutil
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _fixtures import MediaFixtures, OUT, SCRIPTS, TONES, _no_fontconfig, png_size, script, sh # noqa: E402
+from _common import default_font_file, font_for_script, probe # noqa: E402
+
+
+class AnalysisTests(MediaFixtures):
+ """Probe, check, verify, scenes, cropdetect, report, look and sync."""
+
+ # ---------------------------------------------------------------- probe
+ def test_probe_json_and_fields(self):
+ out = script("probe.py", self.src).stdout
+ data = json.loads(out)
+ self.assertClose(data["duration"], 12.0, 0.1)
+ self.assertEqual((data["video"]["width"], data["video"]["height"]), (1280, 720))
+ self.assertClose(data["video"]["fps"], 30.0, 0.01)
+ self.assertEqual(data["video"]["codec"], "h264")
+ self.assertEqual(data["audio"]["channels"], 1)
+ self.assertEqual(data["audio"]["sample_rate"], 48000)
+ field = script("probe.py", self.src, "--field", "video.width").stdout.strip()
+ self.assertEqual(field, "1280")
+ compact = script("probe.py", self.src, "--compact").stdout
+ self.assertIn("1280x720", compact)
+
+ def test_probe_accepts_common_flags(self):
+ out = script("probe.py", self.src, "--json", "--field", "duration").stdout.strip()
+ self.assertClose(float(out), 12.0, 0.1)
+
+ def test_probe_missing_file_fails(self):
+ proc = script("probe.py", OUT / "nope.mp4", expect_fail=True)
+ self.assertIn("not found", proc.stderr)
+
+ # ---------------------------------------------------------------- cropdetect
+ def test_cropdetect_reports_a_black_bar_rectangle(self):
+ bars = OUT / "cropdetect_bars.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi",
+ "-i", "color=black:size=640x480:duration=2,drawbox=y=100:h=280:color=white@1:t=fill",
+ "-r", "10", "-pix_fmt", "yuv420p", bars)
+ proc = script("cropdetect.py", bars, "--seconds", "2", "--samples", "2", "--json")
+ result = json.loads(proc.stdout)
+ self.assertIsNotNone(result["crop"])
+ self.assertEqual(result["crop"]["width"], 640)
+ self.assertLess(result["crop"]["height"], 480)
+ self.assertGreater(result["crop"]["y"], 0)
+
+ def test_cropdetect_writes_no_file(self):
+ before = set(OUT.iterdir())
+ script("cropdetect.py", self.src, "--seconds", "1", "--samples", "1")
+ self.assertEqual(before, set(OUT.iterdir()))
+
+ def test_cropdetect_bad_seconds_refused(self):
+ script("cropdetect.py", self.src, "--seconds", "0", expect_fail=True)
+
+ def test_fonts_dir_does_not_bypass_the_coverage_check(self):
+ """--fonts-dir says "also look here", not "this exact face": a directory that does not
+ cover the script must not silently switch the guarantee off."""
+ if _no_fontconfig() or not shutil.which("fc-scan"):
+ self.skipTest("no fontconfig tools on this machine")
+ if font_for_script("ko") is None:
+ self.skipTest("this machine has no font covering ko")
+ latin_only = Path(default_font_file("DejaVu Sans") or "")
+ if not latin_only.exists():
+ self.skipTest("no DejaVu Sans file to point --fonts-dir at")
+ # an isolated directory holding only the Latin face: the system font directory that
+ # file lives in may well cover Korean too (macOS ships Apple SD Gothic Neo next to it)
+ latin_dir = OUT / "fontsdir_latin_only"
+ latin_dir.mkdir(exist_ok=True)
+ shutil.copyfile(latin_only, latin_dir / latin_only.name)
+ cues = OUT / "fontsdir_ko.txt"
+ cues.write_text("0:00-0:03 안녕하세요\n", encoding="utf-8")
+ proc = script("caption.py", self._small(), "--text", cues, "--fonts-dir", latin_dir,
+ "--fast", "-o", OUT / "fontsdir_ko.mp4", "--json")
+ self.assertIn("covers ko", proc.stderr, proc.stderr)
+ self.assertIn("no face in", proc.stderr, "the caller is told the directory does not cover the script")
+ self.assertNotIn("FontName=DejaVu Sans", " ".join(json.loads(proc.stdout)["commands"]))
+
+ def test_probe_hdr_signal_is_the_transfer_not_the_primaries(self):
+ """1.9: hdr_signal is true for PQ / HLG / Dolby Vision only; hdr keeps its 1.x meaning."""
+ m = probe(str(self.hdr))
+ self.assertTrue(m["video"]["hdr"])
+ self.assertTrue(m["video"]["hdr_signal"])
+ m = probe(str(self.src))
+ self.assertFalse(m["video"]["hdr"])
+ self.assertFalse(m["video"]["hdr_signal"])
+
+ # ---------------------------------------------------------------- sync
+ def test_sync_detects_offset_and_replaces_audio(self):
+ proc = script("sync.py", self.src, self.mic, "--json")
+ data = json.loads(proc.stdout)
+ self.assertClose(data["offset_seconds"], 2.5, 0.05, "lav mic started 2.5 s later")
+ self.assertGreater(data["confidence"], 0.5)
+ out = OUT / "synced.mp4"
+ script("sync.py", self.src, self.mic, "--replace-audio", "-o", out)
+ again = json.loads(script("sync.py", self.src, out, "--json").stdout)
+ self.assertClose(again["offset_seconds"], 0.0, 0.05, "aligned output has no residual offset")
+
+ def test_sync_negative_offset_trim_second(self):
+ early = OUT / "early.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "aevalsrc=0:s=48000:d=1.5",
+ "-i", self.src, "-filter_complex", "[0:a][1:a]concat=n=2:v=0:a=1", early)
+ data = json.loads(script("sync.py", self.src, early, "--json").stdout)
+ self.assertClose(data["offset_seconds"], -1.5, 0.05)
+ out = OUT / "early_synced.wav"
+ script("sync.py", self.src, early, "--trim-second", "-o", out)
+ self.assertEqual(probe(str(out))["audio"]["codec"], "pcm_s16le")
+ again = json.loads(script("sync.py", self.src, out, "--json").stdout)
+ self.assertClose(again["offset_seconds"], 0.0, 0.05)
+
+ # ---------------------------------------------------------------- real-world material
+ def test_probe_detects_vfr_rotation_surround_hdr(self):
+ self.assertTrue(probe(str(self.vfr))["video"]["variable_frame_rate_suspected"])
+ self.assertEqual(probe(str(self.rot))["video"]["rotation"], 90)
+ self.assertEqual(probe(str(self.surround))["audio"]["channels"], 6)
+ h = probe(str(self.hdr))["video"]
+ self.assertTrue(h["hdr"])
+ self.assertEqual(h["hdr_format"], "HDR10/PQ")
+ self.assertEqual(h["bit_depth"], 10)
+ self.assertEqual(h["codec"], "hevc")
+
+ def test_check_podcast_reports_chapters_and_channel_count(self):
+ """1.13: two informational podcast rows. Neither may FAIL a delivery, and neither may
+ appear for a platform that does not care."""
+ data = json.loads(script("check.py", self.mic, "--platform", "podcast", "--no-loudness", "--json").stdout)
+ rows = {r["check"]: r for r in data["checks"]}
+ self.assertEqual(rows["chapters"]["status"], "WARN")
+ self.assertEqual(rows["chapters"]["value"], "none")
+ self.assertIn("metadata.py", rows["chapters"]["fix"])
+ self.assertEqual(rows["channels"]["status"], "PASS", "mono is fine for a podcast")
+ self.assertTrue(data["ok"], "informational rows never fail the delivery")
+ # after metadata.py the chapters row passes
+ chapters = OUT / "podcast_chapters.txt"
+ chapters.write_text("0:00 Intro\n0:04 Body\n", encoding="utf-8")
+ tagged = OUT / "podcast_tagged.m4a"
+ script("audio.py", self.mic, "-o", OUT / "podcast.m4a")
+ script("metadata.py", OUT / "podcast.m4a", "--chapters", chapters, "-o", tagged)
+ rows = {r["check"]: r for r in json.loads(script("check.py", tagged, "--platform", "podcast", "--no-loudness", "--json").stdout)["checks"]}
+ self.assertEqual(rows["chapters"]["status"], "PASS")
+ self.assertEqual(rows["chapters"]["value"], "2")
+ # 5.1 warns, with the reason a publisher needs
+ rows = {r["check"]: r for r in json.loads(script("check.py", self.surround, "--platform", "podcast", "--no-loudness", "--json").stdout)["checks"]}
+ self.assertEqual(rows["channels"]["status"], "WARN")
+ self.assertIn("downmix", rows["channels"]["reason"])
+ # absent for every other platform
+ for platform in ("youtube", "reels"):
+ proc = subprocess.run([sys.executable, str(SCRIPTS / "check.py"), str(self.src), "--platform", platform,
+ "--no-loudness", "--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ names = {r["check"] for r in json.loads(proc.stdout)["checks"]}
+ self.assertNotIn("chapters", names, platform)
+ self.assertNotIn("channels", names, platform)
+
+ def test_sync_fine_resolution_and_drift(self):
+ data = json.loads(script("sync.py", self.long_ref, self.long_drift, "--fix-drift", "--json").stdout)
+ self.assertClose(data["offset_seconds"], 1.2, 0.01, "offset extrapolated to t=0 at 1 ms resolution")
+ self.assertClose(data["drift"]["drift_ppm"], 500.0, 40.0)
+ out = OUT / "drift_fixed.wav"
+ script("sync.py", self.long_ref, self.long_drift, "--fix-drift", "--trim-second", "-o", out)
+ again = json.loads(script("sync.py", self.long_ref, out, "--fix-drift", "--json").stdout)
+ self.assertClose(again["offset_seconds"], 0.0, 0.01)
+ self.assertClose(again["drift"]["drift_ppm"], 0.0, 40.0)
+
+ # ---------------------------------------------------------------- v0.3: look / silence / join / agent flags
+ def test_look_contact_sheet_and_frames(self):
+ sheet = OUT / "sheet.png"
+ proc = script("look.py", self.src, "--tiles", "4x3", "--width", "1280", "-o", sheet)
+ self.assertTrue(sheet.exists())
+ self.assertIn("12 frames", proc.stderr)
+ w, h = png_size(sheet)
+ self.assertGreaterEqual(w, 1280)
+ self.assertGreater(h, 500, "three rows of 16:9 tiles")
+ proc = script("look.py", self.src, "--at", "2.5", "--at", "0:07", "-o", OUT / "frame")
+ frames = [OUT / "frame_2.500s.png", OUT / "frame_7.000s.png"]
+ for f in frames:
+ self.assertTrue(f.exists(), f)
+ self.assertEqual(png_size(frames[0]), (1280, 720))
+ cmp_png = OUT / "cmp.png"
+ script("look.py", self.src, "--compare", self.src, "--at", "1", "-o", cmp_png)
+ self.assertEqual(png_size(cmp_png)[0], 1280)
+
+ def test_look_scenes_overlay_graphics_prefer_fontfile_over_font_when_resolvable(self):
+ """#100: drawtext's own fontconfig resolution (font=<name>) crashed with an access violation
+ on some real Windows ffmpeg builds, with or without a valid fonts.conf; fontfile=<path> is
+ the only form confirmed not to crash, since it never touches fontconfig at all. Every
+ drawtext-using tool now resolves a concrete font file (default_font_file() in _common.text)
+ and prefers fontfile= whenever one can be found, falling back to font= only when nothing
+ resolves. This sandbox has fc-match + DejaVu Sans, so a file is always resolvable here --
+ skip rather than false-fail on a machine where it genuinely cannot be (no fc-match, no
+ fonts installed), since font= is still the documented, correct fallback there."""
+ if not default_font_file("DejaVu Sans"):
+ self.skipTest("no resolvable default font on this machine (no fc-match / no fonts) -- font= fallback is correct here")
+
+ out = OUT / "fontfile_look.png"
+ proc = script("look.py", self.src, "--at", "1", "-o", out, "--json")
+ data = json.loads(proc.stdout)
+ self.assertTrue(any("fontfile=" in c for c in data["commands"]), data["commands"])
+
+ scenes_sheet = OUT / "fontfile_scenes.png"
+ proc = subprocess.run([sys.executable, str(SCRIPTS / "scenes.py"), str(self.src), "--sheet", str(scenes_sheet), "--json"],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ self.assertEqual(proc.returncode, 0, proc.stderr)
+ self.assertIn("fontfile=", proc.stderr, "scenes.py --sheet should log a drawtext with fontfile=")
+
+ out2 = OUT / "fontfile_overlay.mp4"
+ proc = script("overlay.py", self.src, "--text", "hi", "-o", out2, "--json")
+ data2 = json.loads(proc.stdout)
+ self.assertTrue(any("fontfile=" in c for c in data2["commands"]), data2["commands"])
+
+ out3 = OUT / "fontfile_gfx.mp4"
+ proc = script("graphics.py", self.src, "--template", "title", "--title", "hi", "-o", out3, "--json")
+ data3 = json.loads(proc.stdout)
+ self.assertTrue(any("fontfile=" in c for c in data3["commands"]), data3["commands"])
+
+ # ---------------------------------------------------------------- v0.4: verify / multicam / HLG / Log / energy karaoke / progress
+ def test_probe_hlg_and_log_detection(self):
+ hlg = OUT / "hlg.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-t", "3",
+ "-vf", "format=yuv420p10le", "-c:v", "libx265", "-preset", "ultrafast",
+ "-x265-params", "colorprim=bt2020:transfer=arib-std-b67:colormatrix=bt2020nc:log-level=error", "-tag:v", "hvc1", hlg)
+ v = probe(str(hlg))["video"]
+ self.assertEqual(v["hdr_format"], "HLG")
+ self.assertIsNone(v["dolby_vision"])
+ out = OUT / "hlg_sdr.mp4"
+ script("color.py", hlg, "--to-sdr", "--fast", "-o", out)
+ self.assertEqual(probe(str(out))["video"]["color_transfer"], "bt709")
+ nodv = OUT / "hlg_nodv.mp4"
+ proc = script("color.py", hlg, "--strip-dovi", "-o", nodv)
+ self.assertIn("filter_units", proc.stderr)
+ self.assertEqual(probe(str(nodv))["video"]["hdr_format"], "HLG")
+ flat = OUT / "loglike.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-t", "3",
+ "-vf", "curves=all='0/0.36 1/0.88',hue=s=0.4,format=yuv420p", "-c:v", "libx264", "-preset", "veryfast", flat)
+ data = json.loads(script("probe.py", flat, "--analyze").stdout)
+ self.assertTrue(data["levels"]["looks_like_log"])
+ data = json.loads(script("probe.py", self.src, "--analyze").stdout)
+ self.assertFalse(data["levels"]["looks_like_log"])
+ compact = script("probe.py", flat, "--analyze", "--compact").stdout
+ self.assertIn("[Log?]", compact)
+
+ def test_verify_kit_runs_on_real_world_fixtures(self):
+ folder = OUT / "vfx"
+ folder.mkdir(exist_ok=True)
+ for f in (self.hdr, self.surround, self.vfr):
+ (folder / Path(f).name).write_bytes(Path(f).read_bytes())
+ report = OUT / "verify.md"
+ data = json.loads(script("verify.py", folder, "--quick", "--report", report, "--json").stdout)
+ self.assertEqual(data["failed"], 0)
+ self.assertEqual(len(data["files"]), 3)
+ text = report.read_text()
+ self.assertIn("| PASS |", text)
+ self.assertNotIn("| FAIL |", text)
+ self.assertIn("HDR10/PQ", text)
+ script("verify.py", OUT / "does_not_exist", expect_fail=True)
+
+ def test_verify_disambiguates_same_named_files_from_different_folders(self):
+ """Every file's outputs share one flat --out directory keyed only on stem = outdir /
+ f.stem -- two files with the same basename from different subfolders (entirely normal for
+ real footage pulled from multiple cameras/SD cards, e.g. two "clip.mp4"s in separate
+ campaign folders) used to resolve to the identical output prefix. Each file's own steps
+ ran correctly in isolation, but with --keep the second file's outputs silently overwrote
+ the first file's on disk, with the report still showing PASS for both and no collision
+ ever flagged (same bug class fixed in batch.py). Verify same-named files from different
+ folders now get distinct, non-colliding output prefixes."""
+ folder = OUT / "verify_collision"
+ (folder / "campaignA").mkdir(parents=True, exist_ok=True)
+ (folder / "campaignB").mkdir(parents=True, exist_ok=True)
+ (folder / "campaignA" / "clip.mp4").write_bytes(Path(self.src).read_bytes())
+ (folder / "campaignB" / "clip.mp4").write_bytes(Path(self.src).read_bytes())
+ out = OUT / "verify_collision_out"
+ data = json.loads(script("verify.py", folder, "--quick", "--keep", "--out", out, "--json").stdout)
+ self.assertEqual(len(data["files"]), 2)
+ self.assertTrue(all(s["ok"] for f in data["files"] for s in f["steps"]))
+ cut_files = sorted(p.name for p in out.glob("clip*_cut.mp4"))
+ self.assertEqual(len(cut_files), 2, f"expected two distinct 'cut' outputs, one per same-named source file, got {cut_files}")
+ cap_files = sorted(p.name for p in out.glob("clip*_cap.mp4"))
+ self.assertEqual(len(cap_files), 2, f"expected two distinct 'caption' outputs, got {cap_files}")
+
+ def test_verify_full_plan_hdr_surround_broken_file_and_timeout(self):
+ """verify.py's non---quick plan (overlay, look sheet, probe --analyze, loudness, silence,
+ color --to-sdr + the HDR-preserved check on an HDR file, --downmix on >2ch audio), the
+ "ffprobe failed" row for a file that is not media, the plain-text report path (no --json)
+ and the per-step timeout were all unexercised: the two existing verify tests only ran
+ --quick --json on good files (#147). A collection with one HDR10 file, one 5.1 file and
+ one file of garbage bytes exits 1 (the garbage), while every step on the two real files
+ still passes."""
+ folder = OUT / "verify_full"
+ folder.mkdir(exist_ok=True)
+ (folder / Path(self.hdr).name).write_bytes(Path(self.hdr).read_bytes())
+ (folder / Path(self.surround).name).write_bytes(Path(self.surround).read_bytes())
+ (folder / "broken.mp4").write_bytes(b"this is not a media file\n" * 64)
+ out = OUT / "verify_full_out"
+ report = OUT / "verify_full.md"
+ proc = script("verify.py", folder, "--seconds", "2", "--keep", "--out", out, "--report", report, expect_fail=True)
+ text = report.read_text(encoding="utf-8")
+ self.assertIn(text.strip(), proc.stdout.strip(), "without --json the report is printed to stdout")
+ self.assertIn("| probe | FAIL | 0s | ffprobe failed |", text)
+ for step in ("overlay text", "look sheet", "probe analyze", "loudness measure", "silence list",
+ "color to-sdr", "hdr preserved", "audio downmix", "export x"):
+ self.assertIn(f"| {step} | PASS |", text, f"{step} missing or failed:\n{text}")
+ self.assertNotIn("| FAIL |", text.replace("| probe | FAIL | 0s | ffprobe failed |", ""))
+ self.assertTrue((out / f"{Path(self.hdr).stem}_sdr.mp4").exists())
+ self.assertTrue((out / f"{Path(self.surround).stem}_st.mp4").exists())
+ # a per-step timeout is reported per step, never raised
+ data = json.loads(script("verify.py", self.src, "--quick", "--timeout", "0.01", "--json", expect_fail=True).stdout)
+ self.assertEqual((data["status"], data["error"]["kind"]), ("failed", "verification"))
+ timed_out = [s for f in data["files"] for s in f["steps"] if s["error"].startswith("timeout after")]
+ self.assertTrue(timed_out, data)
+ self.assertEqual(data["failed"], len(timed_out))
+
+ def test_check_compliance(self):
+ reels = OUT / "export_reels.mp4"
+ if not reels.exists():
+ script("export.py", self.src, "--preset", "reels", "--fit", "crop", "-o", reels)
+ data = json.loads(script("check.py", reels, "--platform", "reels", "--json", expect_fail=True).stdout)
+ # a failed check is a failed run: status says so (before 1.4.3 it said "completed" next to exit 1)
+ self.assertEqual((data["status"], data["error"]["kind"], data["error"]["code"]), ("failed", "verification", "VERIFICATION_FAILED"))
+ self.assertFalse(data["ok"])
+ names = {r["check"]: r["status"] for r in data["checks"]}
+ kinds = {r["check"]: r["kind"] for r in data["checks"]}
+ self.assertEqual(kinds["loudness"], "judgement")
+ self.assertEqual(kinds["video codec"], "format")
+ self.assertIn("ambience", [r["fix"] for r in data["checks"] if r["check"] == "loudness"][0])
+ self.assertEqual(names["aspect"], "PASS")
+ self.assertEqual(names["pixel format"], "PASS")
+ self.assertEqual(names["loudness"], "FAIL", "unnormalised test tone is far from -14 LUFS")
+ self.assertFalse(data["ok"])
+ # FAILs a non-technical caller would ask "so what?" about carry a plain-language reason,
+ # distinct from `fix` (the command); PASS rows never carry one
+ loudness_row = [r for r in data["checks"] if r["check"] == "loudness"][0]
+ self.assertTrue(loudness_row["reason"])
+ self.assertNotEqual(loudness_row["reason"], loudness_row["fix"])
+ pass_rows = [r for r in data["checks"] if r["status"] == "PASS"]
+ self.assertTrue(pass_rows)
+ self.assertTrue(all(r["reason"] == "" for r in pass_rows))
+ # after loudness.py the same file passes
+ norm = OUT / "reels_norm.mp4"
+ script("loudness.py", reels, "-o", norm)
+ data = json.loads(script("check.py", norm, "--platform", "reels", "--json").stdout)
+ self.assertTrue(data["ok"], [r for r in data["checks"] if r["status"] != "PASS"])
+ # HDR on an SDR-only platform fails the colour check
+ data = json.loads(script("check.py", self.hdr, "--platform", "x", "--no-loudness", "--json", expect_fail=True).stdout)
+ colour_row = [r for r in data["checks"] if r["check"] == "colour"][0]
+ self.assertEqual(colour_row["status"], "FAIL")
+ self.assertTrue(colour_row["reason"])
+ # custom overrides
+ data = json.loads(script("check.py", self.src, "--platform", "custom", "--max-duration", "5", "--no-loudness", "--json", expect_fail=True).stdout)
+ self.assertEqual({r["check"]: r["status"] for r in data["checks"]}["duration"], "FAIL")
+
+ def test_check_without_a_platform_reports_judgement_rows_as_warn(self):
+ """Eval 7: runs that only wanted the format rows got youtube's loudness / true-peak FAILs
+ (the default platform) and explained at length why they left them alone. Without a
+ named platform those rows are advisory: WARN, exit 0, and a notes line says so."""
+ data = json.loads(script("check.py", self.src, "--json").stdout)
+ self.assertEqual(data["status"], "completed")
+ self.assertTrue(data["ok"])
+ self.assertEqual(data["failed"], 0)
+ rows = {r["check"]: r for r in data["checks"]}
+ self.assertEqual(rows["true peak"]["status"], "WARN")
+ self.assertEqual(rows["loudness"]["kind"], "judgement")
+ self.assertEqual(rows["true peak"]["kind"], "judgement")
+ self.assertTrue(any("no --platform" in n for n in data["notes"]))
+ # the same file with the platform named is the same FAIL as before
+ data = json.loads(script("check.py", self.src, "--platform", "youtube", "--json", expect_fail=True).stdout)
+ self.assertFalse(data["ok"])
+ self.assertNotIn("notes", data)
+
+ def test_check_unmeasurable_loudness_warns_instead_of_silently_passing(self):
+ """measure_loudness() returns {} when ffmpeg's loudnorm JSON doesn't parse out of stderr
+ (malformed/unexpected output). main() used to gate the loudness/true-peak rows entirely on
+ `if lm:`, so a measurement failure meant those rows were never appended at all -- not FAIL,
+ not WARN, just absent -- and check.py would still report an overall PASS for a platform
+ with a loudness requirement it never actually verified. A silent false PASS is worse than a
+ crash for a compliance tool. Verify a forced measurement failure surfaces as WARN rows,
+ not a vanished check."""
+ from unittest.mock import patch
+ sys.path.insert(0, str(SCRIPTS))
+ import check
+ with patch.object(check, "measure_loudness", return_value={}):
+ buf = __import__("io").StringIO()
+ import contextlib
+ with contextlib.redirect_stdout(buf):
+ sys.argv = ["check.py", str(self.src), "--platform", "youtube", "--json"]
+ check.main()
+ data = json.loads(buf.getvalue())
+ statuses = {r["check"]: r["status"] for r in data["checks"]}
+ self.assertIn("loudness", statuses, "an unmeasurable loudness check must still appear in the report")
+ self.assertIn("true peak", statuses)
+ self.assertEqual(statuses["loudness"], "WARN")
+ self.assertEqual(statuses["true peak"], "WARN")
+
+ def test_scenes_and_highlights(self):
+ src = OUT / "scenes_src.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30:d=4", "-f", "lavfi", "-i", "smptebars=size=640x360:rate=30:d=4",
+ "-f", "lavfi", "-i", "mandelbrot=size=640x360:rate=30",
+ "-f", "lavfi", "-i", "aevalsrc='0.6*sin(2*PI*440*t)*between(t\\,5\\,7)+0.3*sin(2*PI*330*t)*between(t\\,9\\,10)':s=48000",
+ "-filter_complex", "[2:v]trim=0:4,setpts=PTS-STARTPTS[m];[0:v][1:v][m]concat=n=3:v=1:a=0[v]",
+ "-map", "[v]", "-map", "3:a", "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", src)
+ edl = OUT / "picks.txt"
+ sheet = OUT / "scenes.png"
+ data = json.loads(script("scenes.py", src, "--highlights", "2", "--target", "6", "--edl", edl, "--sheet", sheet, "--json").stdout)
+ self.assertEqual(data["scene_count"], 3)
+ self.assertEqual([round(sc["start"]) for sc in data["scenes"]], [0, 4, 8])
+ self.assertEqual(len(data["highlights"]), 2)
+ self.assertClose(data["highlights_total"], 6.0, 0.6)
+ # the loudest pick must cover the 5-7 s tone
+ self.assertTrue(any(h["start"] <= 5.5 and h["end"] >= 6.5 for h in data["highlights"]), data["highlights"])
+ self.assertTrue(sheet.exists())
+ self.assertGreater(png_size(sheet)[0], 1200, "three tiles across")
+ # EDL feeds cut.py
+ segs = ",".join(edl.read_text().split())
+ out = OUT / "digest.mp4"
+ script("cut.py", src, "--segments", segs, "--accurate", "--fast", "-o", out)
+ self.assertClose(probe(str(out))["duration"], 6.0, 0.6)
+
+ def test_scenes_rank_by_duration_picks_longest_scenes_not_loudest(self):
+ src = OUT / "scenes_rank_src.mp4"
+ # three scenes: 2s, 6s (longest, silent), 4s (loud tone) -- audio and duration ranking must disagree
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30:d=2", "-f", "lavfi", "-i", "smptebars=size=640x360:rate=30:d=6",
+ "-f", "lavfi", "-i", "mandelbrot=size=640x360:rate=30",
+ "-f", "lavfi", "-i", "aevalsrc='0.6*sin(2*PI*440*t)*between(t\\,8\\,11)':s=48000",
+ "-filter_complex", "[2:v]trim=0:4,setpts=PTS-STARTPTS[m];[0:v][1:v][m]concat=n=3:v=1:a=0[v]",
+ "-map", "[v]", "-map", "3:a", "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", src)
+ by_audio = json.loads(script("scenes.py", src, "--highlights", "1", "--json").stdout)
+ by_duration = json.loads(script("scenes.py", src, "--highlights", "1", "--rank-by", "duration", "--json").stdout)
+ self.assertEqual(by_audio["highlights_rank_by"], "audio")
+ self.assertEqual(by_duration["highlights_rank_by"], "duration")
+ # audio ranking picks the loud scene (8-11s window, inside scene 3 at 8-12s)
+ self.assertTrue(any(h["start"] >= 7.5 for h in by_audio["highlights"]), by_audio["highlights"])
+ # duration ranking picks the longest (silent) scene, which starts at 2s
+ self.assertTrue(any(round(h["start"]) == 2 for h in by_duration["highlights"]), by_duration["highlights"])
+
+ def test_social_pack_writes_one_file_per_destination_and_a_table(self):
+ """--template all / a comma list: one edit, N deliveries, one table. The table is what the
+ user is handed, so it must have exactly one row per destination and name the real files."""
+ doc = json.loads(script("render.py", self.src, "--template", "tiktok,x,linkedin",
+ "--cues", self.cues, "--fast", "--json").stdout)
+ self.assertEqual([r["platform"] for r in doc["pack"]], ["tiktok", "x", "linkedin"])
+ for row in doc["pack"]:
+ self.assertTrue(os.path.exists(row["path"]), row)
+ self.assertEqual(row["check"], "pass", row)
+ pack = Path(doc["output"])
+ self.assertTrue(pack.exists())
+ body = pack.read_text(encoding="utf-8")
+ rows = [l for l in body.splitlines() if l.startswith("|") and not set(l.strip("| ")) <= set("-: |")]
+ self.assertEqual(len(rows), 4, "one header row plus one row per destination")
+ html_out = OUT / "pack.html"
+ script("report.py", "--pack", pack, "-o", html_out)
+ html_text = html_out.read_text(encoding="utf-8")
+ for name in ("tiktok", "x", "linkedin"):
+ self.assertIn(name, html_text)
+
+ def test_check_and_export_read_one_loudness_spec_per_platform(self):
+ """The 1.14 table exists so `export.py --normalize` and `check.py` cannot drift: the
+ loudness a preset normalises to is read from the same entry the check enforces."""
+ sys.path.insert(0, str(SCRIPTS))
+ import export as export_mod
+ from check import SPECS
+ from _platforms import loudness_of
+ for preset, platform in export_mod.PLATFORM_OF.items():
+ with self.subTest(preset=preset):
+ spec = SPECS[platform]
+ table = loudness_of(platform)
+ self.assertEqual((spec["lufs"], spec["lufs_tol"], spec["tp"]),
+ (table["lufs"], table["lufs_tol"], table["tp"]))
+
+ def test_look_safe_shades_only_the_platforms_occluded_zones(self):
+ """`look.py --safe tiktok` is how "is the caption readable" gets answered about the app and
+ not just the file: the bottom fifth and the right column come back visibly marked, the
+ middle of the frame untouched."""
+ plain, marked = OUT / "safe_plain.png", OUT / "safe_marked.png"
+ script("look.py", self.src, "--at", "2", "--no-timecode", "-o", plain)
+ doc = json.loads(script("look.py", self.src, "--at", "2", "--no-timecode", "--safe", "tiktok",
+ "-o", marked, "--json").stdout)
+ self.assertTrue(os.path.exists(doc["output"]))
+ self.assertEqual(png_size(plain), png_size(marked))
+ self.assertNotEqual(plain.read_bytes(), marked.read_bytes(), "--safe must mark the frame")
+ cmd = [c for c in doc["commands"] if "drawbox" in c]
+ self.assertTrue(cmd, doc["commands"])
+ self.assertIn("y=ih*(1-0.22)", cmd[0])
+ self.assertIn("x=iw*(1-0.14)", cmd[0])
+
+ def test_report_html(self):
+ reels = OUT / "export_reels.mp4"
+ if not reels.exists():
+ script("export.py", self.src, "--preset", "reels", "--fit", "crop", "-o", reels)
+ cmds = OUT / "cmds.txt"
+ cmds.write_text("python3 export.py source.mp4 --preset reels\n")
+ out = OUT / "report.html"
+ data = json.loads(script("report.py", "--before", self.src, "--after", reels, "--platform", "reels", "--commands", cmds, "--title", "Test delivery", "-o", out, "--json").stdout)
+ self.assertEqual(data["report"], str(out))
+ html_text = out.read_text(encoding="utf-8")
+ self.assertIn("Test delivery", html_text)
+ self.assertEqual(html_text.count("data:image/png;base64"), 2, "before and after contact sheets")
+ self.assertIn("export.py source.mp4 --preset reels", html_text)
+ self.assertIn("class='verdict", html_text)
+ self.assertIn("1080×1920", html_text)
+ script("report.py", "--after", reels, "--no-sheets", "-o", OUT / "report2.html")
+ self.assertLess((OUT / "report2.html").stat().st_size, 40000)
+
+ # ---------------------------------------------------------------- Phase 3 regressions
+ def test_sync_large_offset_on_repetitive_music(self):
+ # repetitive music-like signal: a 4-bar loop with slow variation; raw correlation used to prefer
+ # the small-overlap-friendly wrong lag, NCC must find the true -28 s offset in a 60 s window
+ loop = OUT / "loop.wav"
+ # speech-like: dialogue from the demo tones plus random-looking bursts (incommensurate gates,
+ # a slowly drifting pitch and pink-noise "room"), so no two 9 s stretches look alike
+ expr = (TONES + "+0.25*sin(2*PI*(165+30*sin(2*PI*0.031*t))*t)*gt(sin(2*PI*0.113*t+0.4)\\,0.55)"
+ "+0.3*sin(2*PI*(520+80*sin(2*PI*0.017*t+1))*t)*gt(sin(2*PI*0.29*t+2.1)*sin(2*PI*0.073*t)\\,0.35)")
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", f"aevalsrc='{expr}':s=48000",
+ "-f", "lavfi", "-i", "anoisesrc=a=0.02:c=pink:r=48000", "-t", "200", "-filter_complex", "amix=inputs=2:duration=first:normalize=0", "-c:a", "pcm_s16le", loop)
+ ref = OUT / "loop_ref.wav"
+ sec = OUT / "loop_sec.wav"
+ # 28 s offset inside a 120 s analysis window (the documented rule: window >= 4x max offset)
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "40", "-i", loop, "-t", "120", "-c:a", "pcm_s16le", ref)
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "12", "-i", loop, "-t", "120", "-af", "volume=-8dB,highpass=f=300", "-c:a", "pcm_s16le", sec)
+ data = json.loads(script("sync.py", ref, sec, "--json", "--max-offset", "30").stdout)
+ self.assertClose(data["offset_seconds"], -28.0, 0.02)
+ self.assertGreater(data["confidence"], 0.3)
+
+
+if __name__ == "__main__":
+ unittest.main(verbosity=2)
diff --git a/tests/test_audio.py b/tests/test_audio.py
new file mode 100644
index 0000000..3479220
--- /dev/null
+++ b/tests/test_audio.py
@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""End-to-end tests for audio, loudness and waveform.
+
+ python3 tests/test_audio.py # this group alone
+ python3 tests/test_all.py # every group
+"""
+import json
+import sys
+import unittest
+
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _fixtures import MediaFixtures, OUT, script, sh # noqa: E402
+from _common import probe # noqa: E402
+
+
+class AudioTests(MediaFixtures):
+ """Audio, loudness and waveform."""
+
+ # ---------------------------------------------------------------- waveform
+ def test_waveform_style_default(self):
+ out = OUT / "waveform1.mp4"
+ script("waveform.py", self.src, "--width", "640", "--height", "360", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
+ self.assertIsNotNone(m["audio"])
+ self.assertClose(m["duration"], 12.0, 0.3)
+
+ def test_waveform_spectrum_style(self):
+ out = OUT / "waveform2.mp4"
+ script("waveform.py", self.src, "--style", "spectrum", "--width", "640", "--height", "360", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
+
+ def test_waveform_audio_only_input(self):
+ out = OUT / "waveform3.mp4"
+ script("waveform.py", self.mic, "--width", "480", "--height", "270", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (480, 270))
+
+ def test_waveform_no_audio_refused(self):
+ silent = OUT / "waveform_silent_src.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x240:rate=25",
+ "-t", "1", "-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p", silent)
+ script("waveform.py", silent, expect_fail=True)
+
+ def test_waveform_odd_dimensions_refused(self):
+ script("waveform.py", self.src, "--width", "641", "--height", "360", expect_fail=True)
+
+ def test_waveform_audio_stream_selects_the_requested_track_not_always_the_first(self):
+ """--audio-stream must steer which track is actually visualized, not just which track
+ ends up in the output's audio -- the filter_complex used to reference [0:a] unconditionally
+ regardless of --audio-stream, so every multi-track input rendered track 0's waveform no
+ matter which track was requested."""
+ multitrack = OUT / "wave_multitrack.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "anullsrc=r=48000:cl=mono:d=2",
+ "-f", "lavfi", "-i", "sine=frequency=800:duration=2",
+ "-map", "0:a", "-map", "1:a", "-c:a", "aac", multitrack)
+ track0 = OUT / "wave_track0.mp4"
+ track1 = OUT / "wave_track1.mp4"
+ script("waveform.py", multitrack, "--audio-stream", "0", "--width", "320", "--height", "180", "-o", track0)
+ script("waveform.py", multitrack, "--audio-stream", "1", "--width", "320", "--height", "180", "-o", track1)
+ # track 0 is silent (a flat line); track 1 is a loud sine (a visibly varying waveform) --
+ # their rendered frames must differ.
+ frame0 = OUT / "wave_track0.raw"
+ frame1 = OUT / "wave_track1.raw"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1", "-i", track0, "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", frame0)
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1", "-i", track1, "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", frame1)
+ self.assertNotEqual(frame0.read_bytes(), frame1.read_bytes(), "--audio-stream 0 and 1 rendered identical frames")
+
+ # ---------------------------------------------------------------- loudness
+ def test_loudness_two_pass(self):
+ out = OUT / "loud.mp4"
+ script("loudness.py", self.src, "-I", "-16", "--tp", "-1.5", "-o", out)
+ stats = json.loads(script("loudness.py", out, "--measure-only", "-I", "-16", "--tp", "-1.5").stdout)
+ self.assertClose(float(stats["input_i"]), -16.0, 1.0, "integrated loudness")
+ self.assertLessEqual(float(stats["input_tp"]), -1.0, "true peak ceiling")
+ self.assertEqual(probe(str(out))["video"]["codec"], "h264", "video stream copied")
+
+ def test_audio_music_bed_never_shortens_the_video(self):
+ """#164: a looped music bed under --duck came out 11.925 s from a 12.00 s source, and
+ -shortest then cut the stream-copied *video* to match: four frames gone from a tool whose
+ contract says the picture is never touched. The audio is now padded/trimmed to the source
+ duration and a video-keeping output never uses -shortest. Every music mode, plus --replace
+ with a shorter track, must keep the source's duration and frame count exactly."""
+ src_dur = probe(str(self.src))["duration"]
+ src_frames = self._frame_count(self.src)
+ for tag, flags in (("loop_duck", ["--music", str(self.mic), "--duck", "--music-loop"]),
+ ("loop", ["--music", str(self.mic), "--music-loop"]),
+ ("plain", ["--music", str(self.mic)]),
+ ("replace_short", ["--replace", str(OUT / "c_mic_short.wav")])):
+ if tag == "replace_short":
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", str(self.mic), "-t", "3", str(OUT / "c_mic_short.wav"))
+ out = OUT / f"music_len_{tag}.mp4"
+ script("audio.py", self.src, *flags, "-o", out)
+ m = probe(str(out))
+ self.assertAlmostEqual(m["duration"], src_dur, msg=tag, delta=0.02)
+ self.assertEqual(self._frame_count(out), src_frames, f"{tag}: the picture lost or gained frames")
+ self.assertAlmostEqual(m["audio"].get("duration") or m["duration"], src_dur, msg=tag, delta=0.05)
+
+ def test_audio_downmix_voice_and_ducking(self):
+ out = OUT / "downmix.mp4"
+ script("audio.py", self.surround, "--downmix", "--voice", "-o", out)
+ a = probe(str(out))["audio"]
+ self.assertEqual(a["channels"], 2)
+ out2 = OUT / "ducked.mp4"
+ proc = script("audio.py", self.src, "--music", self.long_ref, "--duck", "--music-fade-out", "2", "-o", out2)
+ self.assertIn("sidechaincompress", proc.stderr)
+ self.assertEqual(proc.stderr.count("afade=t=out"), 1, "only the bed fades, not the whole mix")
+ proc_mix = script("audio.py", self.src, "--fade-out", "1", "--dry-run")
+ self.assertEqual(proc_mix.stderr.count("afade=t=out"), 1)
+ self.assertClose(probe(str(out2))["duration"], 12.0, 0.2)
+ out3 = OUT / "replaced.mp4"
+ script("audio.py", self.src, "--replace", self.mic, "--stereo", "-o", out3)
+ m3 = probe(str(out3))
+ self.assertEqual(m3["audio"]["channels"], 2)
+ self.assertClose(m3["duration"], 12.0, 0.2)
+
+ def test_audio_voice_levels_are_three_different_chains(self):
+ """1.13: --voice takes a strength. A bare --voice must stay byte-identical to the chain
+ it produced before the flag took a value (every existing call and MCP request sends it
+ bare), and each named level must actually be a different chain -- a preset that is only
+ a different word in the help is worse than no preset."""
+ out = OUT / "voice_level.mp4"
+ bare, _ = self._audio_filters(self.src, "--voice", "-o", out)
+ self.assertEqual(bare, "[0:a:0]highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,"
+ "acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2[main];"
+ "[main]apad,atrim=0:12.000[out]",
+ "a bare --voice is the 1.12 chain, unchanged")
+ chains = {}
+ for level in ("light", "medium", "strong"):
+ chains[level], data = self._audio_filters(self.src, "--voice", level, "-o", out)
+ self.assertEqual(data["audio"]["voice"], level)
+ self.assertEqual(chains["medium"], bare, "bare --voice == --voice medium")
+ self.assertEqual(len(set(chains.values())), 3, "each level is a different filter chain")
+ self.assertNotIn("deesser", chains["light"])
+ self.assertNotIn("afftdn", chains["light"], "light leaves the noise floor alone")
+ self.assertIn("acompressor=threshold=-18dB:ratio=2", chains["light"])
+ self.assertIn("deesser=i=0.6", chains["strong"])
+ self.assertIn("alimiter=limit=0.891251:level=disabled", chains["strong"], "strong ends in a soft limiter")
+ self.assertTrue(chains["strong"].count("acompressor") == 2, "strong compresses twice")
+ # and each one really encodes
+ for level in ("light", "strong"):
+ real = OUT / f"voice_{level}.m4a"
+ script("audio.py", self.mic, "--voice", level, "-o", real)
+ self.assertGreater(probe(str(real))["duration"], 1.0)
+
+ def test_audio_duck_parameters_reach_the_sidechain_filter(self):
+ """1.13: the ducking knobs are sayable. The default command line must not move (the
+ threshold flag speaks dBFS, the filter takes the same 0.05 linear it always did), and
+ every flag must land in the filter string and in --json's audio block."""
+ out = OUT / "duck_params.mp4"
+ default, data = self._audio_filters(self.src, "--music", self.long_ref, "--duck", "-o", out)
+ self.assertIn("sidechaincompress=threshold=0.05:ratio=4.0:attack=20:release=400:makeup=1", default,
+ "the default duck filter is unchanged")
+ self.assertEqual(data["audio"]["duck"]["threshold_linear"], 0.05)
+ tuned, data = self._audio_filters(self.src, "--music", self.long_ref, "--duck", "--duck-amount", "18",
+ "--duck-threshold", "-30", "--duck-attack", "5", "--duck-release", "250", "-o", out)
+ self.assertIn("sidechaincompress=threshold=0.0316228:ratio=6.0:attack=5:release=250:makeup=1", tuned)
+ self.assertEqual(data["audio"]["duck"], {"amount_db": 18.0, "threshold_db": -30.0, "threshold_linear": 0.0316228,
+ "ratio": 6.0, "attack_ms": 5.0, "release_ms": 250.0})
+ # no --duck: the block says so rather than describing settings nothing used
+ _, data = self._audio_filters(self.src, "--music", self.long_ref, "-o", out)
+ self.assertIsNone(data["audio"]["duck"])
+ # out of range is refused before ffmpeg sees it
+ doc = json.loads(script("audio.py", self.src, "--music", self.long_ref, "--duck", "--duck-release", "99999",
+ "-o", out, "--json", expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("--duck-release", doc["error"]["message"])
+
+ def test_audio_stereo_widen_needs_a_real_stereo_source(self):
+ """1.13: widening scales the side signal (L-R). Duplicating a mono track to two channels
+ leaves L == R, so the side signal is exactly zero and scaling it changes nothing -- the
+ file comes out bit-identical and still mono. Mono is refused outright, --stereo included,
+ rather than pointed at a workaround that cannot work."""
+ mono = OUT / "widen_mono.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", str(self.mic), "-ac", "1", str(mono))
+ out = OUT / "widened.wav"
+ for extra in ([], ["--stereo"]):
+ doc = json.loads(script("audio.py", mono, "--stereo-widen", "0.5", *extra, "-o", out,
+ "--json", expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input", extra)
+ self.assertIn("real stereo source", doc["error"]["message"], extra)
+ # a real stereo source -- different content per channel -- is widened, and the widening
+ # is audible in the only place it can be: the side signal
+ stereo = OUT / "widen_stereo.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i",
+ "aevalsrc='0.15*sin(2*PI*300*t)|0.1*sin(2*PI*900*t)':s=48000:c=stereo", "-t", "4", str(stereo))
+ before = self._side_peak_db(stereo)
+ graph, data = self._audio_filters(stereo, "--stereo-widen", "1", "-o", out)
+ self.assertIn("extrastereo=m=3", graph)
+ self.assertEqual(data["audio"]["stereo_widen"], 1.0)
+ script("audio.py", stereo, "--stereo-widen", "1", "-o", out)
+ after = self._side_peak_db(out)
+ self.assertEqual(probe(str(out))["audio"]["channels"], 2)
+ self.assertGreater(after, -60.0, "L-R must not be silent after widening: that is the whole effect")
+ self.assertGreater(after, before + 3.0, "the side signal is louder than it was")
+ doc = json.loads(script("audio.py", stereo, "--stereo-widen", "4", "-o", out, "--json", expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+
+ def test_audio_stereo_widen_refuses_more_than_two_channels_without_downmix(self):
+ """1.13: extrastereo is a stereo-only filter, so libavfilter would auto-insert a downmix
+ and throw four channels of a 5.1 master away with no flag and no warning. Losing channels
+ is the caller's decision (--downmix), and with it the widening runs on the fold-down."""
+ out = OUT / "widen_surround.m4a"
+ doc = json.loads(script("audio.py", self.surround, "--stereo-widen", "0.5", "-o", out,
+ "--json", expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("--downmix", doc["error"]["message"])
+ self.assertIn("6 channels", doc["error"]["message"])
+ graph, _ = self._audio_filters(self.surround, "--stereo-widen", "0.5", "--downmix", "-o", out)
+ self.assertLess(graph.index("pan=stereo"), graph.index("extrastereo="), "widen runs after the downmix")
+ data = json.loads(script("audio.py", self.surround, "--stereo-widen", "0.5", "--downmix",
+ "-o", out, "--json").stdout)
+ self.assertEqual(data["probe"]["audio"]["channels"], 2)
+ self.assertEqual(data["probe"]["audio"]["channel_layout"], "stereo")
+
+ def test_audio_duck_parameters_need_their_switch_and_a_bed(self):
+ """1.13: --duck-release 250 that silently delivers the default 400 ms is invisible to the
+ caller, and --duck with no --music has nothing to duck. Both are refusals naming the
+ missing flag, the same rule the typed dynamics parameters already follow."""
+ out = OUT / "duck_guard.mp4"
+ for flag, value in (("--duck-threshold", "-40"), ("--duck-attack", "5"), ("--duck-release", "250"), ("--duck-amount", "18")):
+ doc = json.loads(script("audio.py", self.src, "--music", self.long_ref, flag, value, "-o", out,
+ "--json", expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input", flag)
+ self.assertIn(flag, doc["error"]["message"])
+ self.assertIn("--duck", doc["error"]["message"])
+ doc = json.loads(script("audio.py", self.src, "--duck", "--duck-release", "250", "-o", out,
+ "--json", expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("--music", doc["error"]["message"])
+ # the combination that means something still runs
+ graph, _ = self._audio_filters(self.src, "--music", self.long_ref, "--duck", "--duck-release", "250", "-o", out)
+ self.assertIn("release=250", graph)
+
+ def test_audio_effects_bed_is_mixed_and_never_ducked(self):
+ """1.13: --effects is a third bed at its own level. It is mixed after the ducked music,
+ outside the sidechain, because effects are cut to the picture."""
+ out = OUT / "effects.mp4"
+ graph, data = self._audio_filters(self.src, "--music", self.long_ref, "--duck",
+ "--effects", self.mic, "--effects-volume", "-20", "-o", out)
+ self.assertIn("volume=-20dB", graph)
+ self.assertIn("[effects]", graph)
+ self.assertGreater(graph.index("[effects]"), graph.index("sidechaincompress"),
+ "the effects bed is mixed after the duck, so the sidechain never sees it")
+ self.assertTrue(data["audio"]["effects"])
+ script("audio.py", self.src, "--effects", self.mic, "--effects-volume", "-20", "-o", out)
+ self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
+
+ def test_loudness_json_reports_the_measurement_and_the_targets(self):
+ """1.13: --json carries the input's own loudnorm measurement (including its loudness
+ range) and the targets that were asked for, next to the result measured off the written
+ file -- so a caller can see what it started from without a second --measure-only run.
+
+ There is deliberately no speech gate here: loudnorm's EBU R128 integrated measurement
+ already applies the -70 LUFS absolute and -10 LU relative gates, so gating on
+ silencedetect spans moves the result by a fraction of check.py's own tolerance (see
+ references/gotchas.md#loudness-and-ambience)."""
+ out = OUT / "loud_targets.m4a"
+ data = json.loads(script("loudness.py", self.mic, "-I", "-16", "--tp", "-1.5", "--lra", "9",
+ "-o", out, "--json").stdout)
+ self.assertEqual(data["targets"], {"lufs": -16.0, "tp": -1.5, "lra": 9.0})
+ for key in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset"):
+ self.assertIn(key, data["measured"], key)
+ self.assertIn(key, data["result"], key)
+ measured_only = json.loads(script("loudness.py", self.mic, "--measure-only", "--json").stdout)["measured"]
+ self.assertEqual(data["measured"]["input_i"], measured_only["input_i"],
+ "the reported measurement is the same pass-1 measurement --measure-only prints")
+ self.assertClose(float(data["result"]["input_i"]), -16.0, 1.0)
+ self.assertNotIn("dialogue", script("loudness.py", "--help").stdout,
+ "the speech gate was withdrawn; the flag must not come back without the evidence")
+
+ def test_audio_only_inputs_through_the_audio_scripts(self):
+ """WAV / M4A / MP3 with no video stream: loudness, silence, audio (voice, convert), cut, check."""
+ m4a = OUT / "gappy.m4a"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*gt(sin(2*PI*0.25*t)\\,0)':s=48000",
+ "-t", "12", "-c:a", "aac", "-b:a", "128k", m4a)
+ self.assertIsNone(probe(str(m4a)).get("video"))
+ # loudness: wav -> m4a, codec follows the output extension
+ norm = OUT / "lav_norm.m4a"
+ script("loudness.py", self.mic, "-I", "-16", "--tp", "-1.5", "-o", norm)
+ a = probe(str(norm))["audio"]
+ self.assertEqual(a["codec"], "aac")
+ self.assertIn("PASS", script("check.py", norm, "--platform", "podcast").stdout)
+ # silence removal on an m4a
+ tight = OUT / "gappy_tight.m4a"
+ data = json.loads(script("silence.py", m4a, "-o", tight, "--json").stdout)
+ self.assertClose(data["removed_seconds"], 5.25, 0.3)
+ self.assertClose(probe(str(tight))["duration"], 6.75, 0.3)
+ # voice clean-up keeps the container, plain -o converts
+ clean = OUT / "gappy_clean.m4a"
+ script("audio.py", m4a, "--voice", "-o", clean)
+ self.assertEqual(probe(str(clean))["audio"]["codec"], "aac")
+ mp3 = OUT / "lav.mp3"
+ script("audio.py", self.mic, "-o", mp3)
+ self.assertEqual(probe(str(mp3))["audio"]["codec"], "mp3")
+ # trim is a stream copy on wav and mp3
+ cut_wav = OUT / "lav_cut.wav"
+ proc = script("cut.py", self.mic, "--start", "0:02", "--end", "0:06", "-o", cut_wav)
+ self.assertIn("lossless", proc.stderr)
+ self.assertClose(probe(str(cut_wav))["duration"], 4.0, 0.05)
+ cut_mp3 = OUT / "lav_cut.mp3"
+ script("cut.py", mp3, "--start", "2", "--end", "6", "-o", cut_mp3)
+ self.assertClose(probe(str(cut_mp3))["duration"], 4.0, 0.1)
+ # picture-only scripts refuse clearly instead of failing inside ffmpeg
+ for argv in (("fit.py", "--duration", "5"), ("export.py", "--preset", "youtube"), ("look.py",)):
+ proc = script(argv[0], self.mic, *argv[1:], "-o", OUT / "nope.out", expect_fail=True)
+ self.assertIn("no video stream", proc.stderr)
+
+ def test_loudness_silent_input_is_reported_not_crashed(self):
+ silent = OUT / "silent.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30", "-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo",
+ "-t", "3", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", silent)
+ data = json.loads(script("loudness.py", silent, "--measure-only").stdout)
+ self.assertTrue(data["silent"])
+ proc = script("loudness.py", silent, "-o", OUT / "silent_norm.mp4", expect_fail=True)
+ self.assertIn("silent", proc.stderr)
+
+ def test_audio_extraction_from_video_container(self):
+ """mp4 -> wav / m4a through audio.py and cut.py: no video stream, codec from the extension, stream selection."""
+ wav = OUT / "ex_audio.wav"
+ data = json.loads(script("audio.py", self.src, "-o", wav, "--json").stdout)
+ self.assertIsNone(data["probe"]["video"])
+ self.assertEqual(data["probe"]["audio"]["codec"], "pcm_s16le")
+ self.assertFalse(data["video"])
+ m4a = OUT / "ex_voice.m4a"
+ data = json.loads(script("audio.py", self.src, "--voice", "-o", m4a, "--json").stdout)
+ self.assertIsNone(data["probe"]["video"])
+ self.assertEqual(data["probe"]["audio"]["codec"], "aac")
+ # a video output keeps the stream-copied picture as before
+ mp4 = OUT / "ex_keep.mp4"
+ data = json.loads(script("audio.py", self.src, "--denoise", "-o", mp4, "--json").stdout)
+ self.assertIsNotNone(data["probe"]["video"])
+ self.assertTrue(data["video"])
+ # two audio streams: --audio-stream 1 picks the 880 Hz / 44.1 kHz track, an index past the end fails as input
+ two = OUT / "two_streams.mkv"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
+ "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
+ "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
+ self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
+ self.assertEqual(probe(str(two))["audio_streams"][1]["sample_rate"], 44100)
+ s1 = OUT / "two_s1.wav"
+ data = json.loads(script("audio.py", two, "--audio-stream", "1", "-o", s1, "--json").stdout)
+ self.assertEqual(data["audio_stream"], 1)
+ self.assertEqual(self._samples(s1)[1], 44100)
+ proc = script("audio.py", two, "--audio-stream", "2", "-o", OUT / "nope.wav", "--json", expect_fail=True)
+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
+ self.assertIn("2 audio stream", proc.stderr)
+ # cut.py with an audio extension extracts too, and never copies AAC packets into a WAV
+ cw = OUT / "ex_cut.wav"
+ data = json.loads(script("cut.py", self.src, "--start", "1", "--end", "3", "-o", cw, "--json").stdout)
+ self.assertIsNone(data["probe"]["video"])
+ self.assertEqual(self._samples(cw)[0], "pcm_s16le")
+ self.assertEqual(data["precision"], "sample")
+
+ def test_audio_typed_dynamics(self):
+ """--gate / --compress / --limit map typed flags onto acompressor, alimiter, agate; ranges are enforced; the ceiling holds."""
+ out = OUT / "dyn.wav"
+ data = json.loads(script("audio.py", self.mic, "--gate", "--gate-threshold", "-50", "--compress", "--comp-threshold", "-20",
+ "--comp-ratio", "4", "--comp-attack", "5", "--comp-release", "80", "--comp-makeup", "6",
+ "--limit", "--limit-ceiling", "-3", "-o", out, "--json").stdout)
+ self.assertEqual(data["dynamics"], ["agate", "acompressor", "alimiter"])
+ cmd = data["commands"][0]
+ self.assertIn("agate=threshold=0.00316228", cmd)
+ self.assertIn("acompressor=threshold=0.1:ratio=4:attack=5:release=80:makeup=1.99526", cmd)
+ self.assertIn("alimiter=limit=0.707946:level=disabled", cmd)
+ peak, rms = self._peak_rms(out)
+ self.assertLessEqual(peak, -3.0 + 0.1, "limiter ceiling")
+ # the compressor alone on a full-scale sine: threshold -20 dB, ratio 4 settle far below 0 dB and above the threshold
+ sine = OUT / "dyn_sine.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-t", "3", "-af", "volume=18.06dB", "-c:a", "pcm_s16le", sine)
+ comp = OUT / "dyn_comp.wav"
+ script("audio.py", sine, "--compress", "--comp-threshold", "-20", "--comp-ratio", "4", "--comp-attack", "5", "--comp-release", "80", "-o", comp)
+ peak_c, _ = self._peak_rms(comp)
+ self.assertGreater(self._peak_rms(sine)[0], -0.5)
+ self.assertLess(peak_c, -3.0, "compressor reduced a 0 dBFS tone (measured -7.5 dB: ffmpeg detects RMS, knee 2.83 dB)")
+ self.assertGreater(peak_c, -20.0, "compression, not a gate")
+ # every flag is range-checked before ffmpeg runs
+ for flags, text in ((("--compress", "--comp-ratio", "50"), "1..20"),
+ (("--limit", "--limit-ceiling", "1"), "-24..0"),
+ (("--gate", "--gate-attack", "0"), "0.01..9000"),
+ (("--compress", "--comp-makeup", "40"), "0..36")):
+ proc = script("audio.py", self.mic, *flags, "-o", OUT / "dyn_bad.wav", "--json", expect_fail=True)
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn(text, doc["error"]["message"])
+ self.assertNotIn("$ ", proc.stderr, "refused before ffmpeg ran")
+ # a parameter without its switch is an error, not silently ignored
+ proc = script("audio.py", self.mic, "--comp-ratio", "4", "-o", OUT / "dyn_bad.wav", expect_fail=True)
+ self.assertIn("add --compress", proc.stderr)
+ # the limiter alone on a video input keeps the picture
+ mp4 = OUT / "dyn_video.mp4"
+ data = json.loads(script("audio.py", self.src, "--limit", "--limit-ceiling", "-1", "-o", mp4, "--json").stdout)
+ self.assertIsNotNone(data["probe"]["video"])
+ self.assertLessEqual(self._peak_rms(mp4)[0], -1.0 + 0.3)
+
+
+if __name__ == "__main__":
+ unittest.main(verbosity=2)
diff --git a/tests/test_contract.py b/tests/test_contract.py
index a8a1ed9..ae92f22 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -28,6 +28,16 @@ import _common # noqa: E402
import server as mcp_server # noqa: E402
+def script_sources():
+ """Every Python file under scripts/, the _common package included.
+
+ _common is a directory since the refactor after 1.15.0, so a plain `scripts/*.py` glob no
+ longer reaches the helpers -- which is exactly the source a scan like "no shell=True
+ anywhere" must not stop covering. Tool *enumeration* still uses the bare glob on purpose:
+ a package directory is not a tool."""
+ return sorted(SCRIPTS.glob("*.py")) + sorted(SCRIPTS.glob("*/*.py"))
+
+
def sh(*cmd, check=True, env=None, cwd=None):
proc = subprocess.run([str(c) for c in cmd], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", env=env, cwd=cwd)
if check and proc.returncode != 0:
@@ -329,7 +339,7 @@ class ContractTests(unittest.TestCase):
for cap in caps["required"] + caps["optional"]:
self.assertTrue(re.fullmatch(r"ffmpeg|ffprobe|encoder:\w+|filter:\w+|bsf:\w+|external:\w+", cap), cap)
# every encoder / filter / bsf named in the contract is referenced by some script
- source = "\n".join(p.read_text(encoding="utf-8") for p in SCRIPTS.glob("*.py"))
+ source = "\n".join(p.read_text(encoding="utf-8") for p in script_sources())
for cap in caps["required"] + caps["optional"]:
if ":" in cap and not cap.startswith("external:"):
self.assertIn(cap.split(":", 1)[1], source, f"{cap} declared but no script uses it")
@@ -1596,7 +1606,7 @@ class ContractTests(unittest.TestCase):
self.assertEqual(_common._bit_depth(pix), depth, pix)
self.assertEqual(_common.fmt_secs(None), "?s")
self.assertEqual(_common.fmt_secs(1.5), "1.500s")
- leftovers = [p.name for p in SCRIPTS.glob("*.py") if re.search(r"duration['\"]\]:\.3f\}s|duration['\"]\):\.3f\}s", p.read_text(encoding="utf-8"))]
+ leftovers = [p.name for p in script_sources() if re.search(r"duration['\"]\]:\.3f\}s|duration['\"]\):\.3f\}s", p.read_text(encoding="utf-8"))]
self.assertEqual(leftovers, [], "a script still formats a possibly-None duration with :.3f")
self.assertIn(".mxf", _common.MEDIA_EXT)
import batch as batch_mod # noqa: E402
@@ -2239,7 +2249,7 @@ class ContractTests(unittest.TestCase):
for name in ("cut", "audio", "loudness", "silence", "fit", "export", "caption", "overlay", "color", "join", "graphics", "multicam"):
src = (SCRIPTS / f"{name}.py").read_text(encoding="utf-8")
self.assertIn("emit(", src, f"{name} does not go through emit()")
- self.assertIn("verify_output(output)", (SCRIPTS / "_common.py").read_text(encoding="utf-8"))
+ self.assertIn("verify_output(output)", (SCRIPTS / "_common" / "emit.py").read_text(encoding="utf-8"))
with self.assertRaises(SystemExit):
_common.verify_output(str(self.work / "never_written.mp4"))
@@ -2350,7 +2360,7 @@ class ContractTests(unittest.TestCase):
def test_every_tool_help_and_no_shell_paths(self):
for t in self.contract["tools"]:
self.assertIn("usage:", tool(t["name"], "--help").stdout)
- for path in list(SCRIPTS.glob("*.py")) + [ROOT / "mcp" / "server.py"]:
+ for path in script_sources() + [ROOT / "mcp" / "server.py"]:
src = path.read_text(encoding="utf-8")
for forbidden in ("shell=True", "os.system(", "eval(", "exec(", "os.popen("):
self.assertNotIn(forbidden, src, f"{path.name} uses {forbidden}")
diff --git a/tests/test_delivery.py b/tests/test_delivery.py
new file mode 100644
index 0000000..7aa07f3
--- /dev/null
+++ b/tests/test_delivery.py
@@ -0,0 +1,387 @@
+#!/usr/bin/env python3
+"""End-to-end tests for export, proxy and the delivery templates.
+
+ python3 tests/test_delivery.py # this group alone
+ python3 tests/test_all.py # every group
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+import unittest
+
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _fixtures import MediaFixtures, OUT, ROOT, SCRIPTS, script, sh # noqa: E402
+from _common import probe # noqa: E402
+
+
+class DeliveryTests(MediaFixtures):
+ """Export, proxy and the delivery templates."""
+
+ # ---------------------------------------------------------------- export
+ def test_export_presets(self):
+ cases = {
+ "youtube": ("mp4", "h264", (1920, 1080)),
+ "reels": ("mp4", "h264", (1080, 1920)),
+ "x": ("mp4", "h264", (1280, 720)),
+ "prores": ("mov", "prores", (1280, 720)),
+ "h265": ("mp4", "hevc", (1280, 720)),
+ }
+ for preset, (ext, codec, size) in cases.items():
+ with self.subTest(preset=preset):
+ out = OUT / f"export_{preset}.{ext}"
+ script("export.py", self.src, "--preset", preset, "-o", out)
+ m = probe(str(out))
+ self.assertEqual(m["video"]["codec"], codec)
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), size)
+ self.assertClose(m["duration"], 12.0, 0.2)
+ if preset in ("youtube", "reels", "x", "h265"):
+ self.assertEqual(m["video"]["color_space"], "bt709")
+
+ def test_export_list(self):
+ self.assertIn("youtube", script("export.py", "--list").stdout)
+
+ def test_export_copy_is_a_real_stream_copy(self):
+ """`--preset copy`: same bytes as a source→same-container remux would produce, not a re-encode — verified by
+ codec/resolution/bitrate/frame-count staying exactly the source's, not by trusting the preset name."""
+ out = OUT / "export_copy.mp4"
+ script("export.py", self.src, "--preset", "copy", "-o", out)
+ src_m, out_m = probe(str(self.src)), probe(str(out))
+ self.assertEqual(out_m["video"]["codec"], src_m["video"]["codec"])
+ self.assertEqual((out_m["video"]["width"], out_m["video"]["height"]), (src_m["video"]["width"], src_m["video"]["height"]))
+ self.assertEqual(out_m["audio"]["codec"], src_m["audio"]["codec"])
+ self.assertClose(out_m["duration"], src_m["duration"], 0.05)
+ src_frames = sh("ffprobe", "-v", "error", "-count_frames", "-select_streams", "v:0", "-show_entries", "stream=nb_read_frames", "-of", "csv=p=0", self.src).stdout.strip()
+ out_frames = sh("ffprobe", "-v", "error", "-count_frames", "-select_streams", "v:0", "-show_entries", "stream=nb_read_frames", "-of", "csv=p=0", out).stdout.strip()
+ self.assertEqual(out_frames, src_frames, "a re-encode could drop/duplicate frames; a copy cannot")
+ # a genuinely untouched source has no colour tags to begin with (never asserts a re-encoder's own default)
+ self.assertEqual(out_m["video"]["color_space"], src_m["video"]["color_space"])
+ # no audio in the source: copy must not invent a silent track, and must not error demanding one
+ noaudio = OUT / "noaudio_source.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-t", "2", "-an", "-c:v", "copy", noaudio)
+ out_na = OUT / "export_copy_noaudio.mp4"
+ script("export.py", noaudio, "--preset", "copy", "-o", out_na)
+ self.assertIsNone(probe(str(out_na)).get("audio"))
+
+ def test_export_copy_preserves_hdr_tags_untouched(self):
+ """The HDR-warning branch that every re-encoding preset trips (`export.py` docstring: "outputs SDR BT.709
+ tags without tone mapping") must not apply to `copy` — it doesn't touch colour at all, so the source's own
+ HDR tags must survive exactly, not get silently flattened to BT.709 like every other preset does."""
+ out = OUT / "export_copy_hdr.mov"
+ proc = script("export.py", self.hdr, "--preset", "copy", "-o", out)
+ self.assertNotIn("BT.709", proc.stdout + proc.stderr, "copy re-encodes nothing, so it never issues the SDR-flattening warning")
+ m = probe(str(out))
+ self.assertTrue(m["video"]["hdr"], "the source's real HDR tags must survive a stream copy")
+ self.assertNotEqual(m["video"]["color_space"], "bt709", "copy must never relabel HDR content as bt709")
+
+ def test_proxy_default_width_and_crf_keeps_audio(self):
+ out = OUT / "proxy_default.mp4"
+ script("proxy.py", self.src, "-o", out)
+ m = probe(str(out))
+ self.assertEqual(m["video"]["width"], 640)
+ self.assertEqual(m["video"]["codec"], "h264")
+ self.assertIsNotNone(m.get("audio"), "default keeps audio when the source has it")
+ self.assertClose(m["duration"], 12.0, 0.2)
+
+ def test_proxy_scale_and_no_audio(self):
+ out = OUT / "proxy_scale.mp4"
+ script("proxy.py", self.src, "--scale", "0.25", "--no-audio", "-o", out)
+ src_w = probe(str(self.src))["video"]["width"]
+ m = probe(str(out))
+ self.assertEqual(m["video"]["width"], src_w // 4)
+ self.assertIsNone(m.get("audio"), "--no-audio must drop the track, not just mute it")
+
+ def test_proxy_forces_fps(self):
+ out = OUT / "proxy_fps.mp4"
+ script("proxy.py", self.vfr, "--fps", "10", "-o", out)
+ m = probe(str(out))
+ self.assertFalse(m["video"]["variable_frame_rate_suspected"], "an explicit --fps must conform a VFR source to CFR")
+ self.assertClose(m["video"]["fps"], 10.0, 0.5)
+
+ def test_proxy_keeps_hdr_dynamic_range_like_every_other_reencode(self):
+ """A proxy meant for machine consumption still shouldn't silently wash out HDR to a
+ mislabelled BT.709 file — same posture as fit.py/caption.py: keep HDR as HEVC10, and
+ let color.py --to-sdr be the tool that makes the SDR-vs-HDR call, not this one."""
+ out = OUT / "proxy_hdr.mp4"
+ script("proxy.py", self.hdr, "-o", out)
+ m = probe(str(out))
+ self.assertTrue(m["video"]["hdr"])
+ self.assertEqual(m["video"]["codec"], "hevc")
+
+ def test_proxy_rejects_bad_scale_and_width(self):
+ script("proxy.py", self.src, "--scale", "1.5", expect_fail=True)
+ script("proxy.py", self.src, "--scale", "0", expect_fail=True)
+ script("proxy.py", self.src, "--width", "0", expect_fail=True)
+
+ def test_proxy_dry_run_writes_nothing(self):
+ out = OUT / "proxy_dry_run_absent.mp4"
+ proc = script("proxy.py", self.src, "-o", out, "--dry-run", "--json")
+ doc = json.loads(proc.stdout)
+ self.assertTrue(doc["dry_run"])
+ self.assertFalse(out.exists())
+
+ def test_export_warns_on_hdr(self):
+ out = OUT / "hdr_youtube.mp4"
+ proc = script("export.py", self.hdr, "--preset", "x", "-o", out)
+ self.assertIn("HDR", proc.stderr)
+
+ def test_export_normalize_meets_the_platform_loudness_in_one_call(self):
+ """Eval 7: every platform job ran export -> loudness.py -> export again. --normalize runs
+ the levels pass on the written file (audio only) so one export delivers the spec."""
+ out = OUT / "export_normalize.mp4"
+ proc = script("export.py", OUT / "source.mp4", "--preset", "x", "--normalize", "-o", out, "--fast", "--json", "--overwrite")
+ d = json.loads(proc.stdout)
+ self.assertEqual(d["status"], "completed")
+ self.assertTrue(d["loudness"]["ok"], d["loudness"])
+ self.assertTrue(d["loudness"]["normalized"])
+ self.assertTrue(d["verified"])
+ self.assertAlmostEqual(d["loudness"]["lufs"], -14.0, delta=1.0)
+ self.assertFalse((OUT / "export_normalize_loudnorm.mp4").exists())
+ self.assertTrue(any("linear=true" in c for c in d["commands"]), "the normalising encode is in the command log (review 7)")
+ # review 7 P0: a real <output>_loudnorm.<ext> next to the export survives --normalize
+ precious = OUT / "export_normalize_loudnorm.mp4"
+ precious.write_bytes(b"PRECIOUS")
+ try:
+ script("export.py", OUT / "source.mp4", "--preset", "x", "--normalize", "-o", out, "--fast", "--json", "--overwrite")
+ self.assertEqual(precious.read_bytes(), b"PRECIOUS")
+ finally:
+ precious.unlink()
+ # --normalize on a preset without a loudness spec is refused; under --dry-run it says what it would do
+ d = json.loads(script("export.py", OUT / "source.mp4", "--preset", "h265", "--normalize", "-o", OUT / "export_norm_h265.mp4", "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ d = json.loads(script("export.py", OUT / "source.mp4", "--preset", "x", "--normalize", "-o", out, "--dry-run", "--json").stdout)
+ self.assertTrue(any("--normalize" in n for n in d.get("notes", [])), d)
+ # without the flag the same file is reported, not fixed
+ proc = script("export.py", OUT / "source.mp4", "--preset", "x", "-o", out, "--fast", "--json", "--overwrite")
+ d = json.loads(proc.stdout)
+ self.assertFalse(d["loudness"]["ok"])
+ self.assertNotIn("normalized", d["loudness"])
+ self.assertIn("--normalize", " ".join(d["notes"]))
+
+ def test_every_delivery_template_renders_and_passes_its_own_check(self):
+ """1.14: `render.py --template NAME INPUT` is the one command a delivery request becomes,
+ so every shipped template has to survive its own pipeline on real footage and come back
+ with its own platform's check passing -- the frame, the caption burn, the loudness pass,
+ the export preset and check.py agreeing is exactly the thing a template promises and the
+ thing that used to be assembled by hand differently every time."""
+ names = sorted(p.stem for p in (ROOT / "templates").glob("*.json"))
+ self.assertEqual(names, ["facebook", "linkedin", "podcast", "reels", "shorts", "tiktok",
+ "x", "youtube", "youtube-shorts"], "every shipped template is exercised here")
+ for name in names:
+ with self.subTest(template=name):
+ src = self.mic if name == "podcast" else self.src
+ argv = [str(src), "--template", name, "--fast", "--json",
+ "-o", str(OUT / ("tpl_%s.%s" % (name, "m4a" if name == "podcast" else "mp4")))]
+ if name != "podcast":
+ argv += ["--cues", str(self.cues)]
+ doc = json.loads(script("render.py", *argv).stdout)
+ self.assertEqual(doc["status"], "completed")
+ self.assertTrue(os.path.exists(doc["output"]), doc["output"])
+ self.assertTrue(doc["check"]["ok"],
+ f"{name}: {[r for r in doc['check']['checks'] if r['status'] == 'FAIL']}")
+ platform = json.loads((ROOT / "templates" / f"{name}.json").read_text())["check"]["platform"]
+ self.assertEqual(doc["check"]["platform"], platform)
+
+ def test_template_keeps_caption_and_graphic_out_of_the_platform_safe_zone(self):
+ """The whole point of the table's safe zones: TikTok draws its description block over the
+ bottom 22 % of the frame and its like/comment column over the right 14 %. A caption burned
+ at the historical margin sits under the description; a right-hand graphic sits under the
+ buttons. Asserted on the planned commands (--dry-run --json), which is where the ASS
+ MarginV and the drawtext x actually are."""
+ sys.path.insert(0, str(SCRIPTS))
+ from _platforms import PLATFORMS, ass_units
+ safe = PLATFORMS["tiktok"]["safe"]
+ proj = OUT / "safe_project.json"
+ script("render.py", self.src, "--template", "tiktok", "--cues", self.cues,
+ "--write-project", proj, "-o", str(OUT / "safe_out.mp4"))
+ cap = json.loads(proj.read_text())["captions"]
+ self.assertEqual(cap["margin"], ass_units(safe["bottom"]), "the template's caption margin is the safe zone")
+ # the burn itself: the generated .ass carries MarginV in the same 288-unit grid, scaled
+ plan = json.loads(script("render.py", proj, "--dry-run", "--json").stdout)
+ ass_lines = [c for c in plan["commands"] if "captioned.ass" in c]
+ self.assertTrue(ass_lines, plan["commands"])
+ # the ASS grid is 288 lines, so a fraction of the frame lands on the nearest of ~6.7 px
+ margin_px = round(cap["margin"] * 1920 / 288)
+ self.assertGreaterEqual(margin_px, round(safe["bottom"] * 1920) - 1920 / 288,
+ "the caption's baseline margin must clear TikTok's description bar")
+ # a right-positioned graphic: drawtext's x must leave the like column free
+ gfx = json.loads(script("graphics.py", self.src, "--template", "bug", "--title", "@handle",
+ "--position", "top-right", "--platform", "tiktok", "--dry-run", "--json",
+ "-o", str(OUT / "safe_bug.mp4")).stdout)
+ W, H = 1280, 720 # the fixture's own frame: the margins are fractions of it
+ drawtext = [c for c in gfx["commands"] if "drawtext" in c][0]
+ m = re.search(r"x=w-text_w-(\d+)", drawtext)
+ self.assertTrue(m, drawtext)
+ self.assertGreaterEqual(int(m.group(1)), round(safe["right"] * W) - 1,
+ "a right-hand graphic must sit left of TikTok's like column")
+ m = re.search(r"y=(\d+):box", drawtext)
+ self.assertGreaterEqual(int(m.group(1)), round(safe["top"] * H) - 1)
+
+ def test_list_templates_names_every_template_with_its_safe_zones(self):
+ out = script("render.py", "--list-templates").stdout
+ sys.path.insert(0, str(SCRIPTS))
+ from _platforms import PLATFORMS
+ for path in sorted((ROOT / "templates").glob("*.json")):
+ self.assertIn(path.stem, out)
+ for edge, frac in PLATFORMS["tiktok"]["safe"].items():
+ self.assertIn(f"{edge} {frac:.2f}", out, f"--list-templates must state tiktok's {edge} safe zone")
+ self.assertIn("1080x1920", out)
+ script("render.py", self.src, "--template", "myspace", expect_fail=True)
+
+ def test_export_presets_per_destination_are_distinct_and_hdr_av1_refuse_honestly(self):
+ """1.14: tiktok/shorts/linkedin/facebook stop being aliases of reels/youtube -- each is its
+ own frame and duration limit. youtube-hdr must keep a real HDR source's tags (the point of
+ the preset) and refuse an SDR one instead of labelling SDR as HDR; youtube-av1 must refuse
+ with kind: missing_tool on a build with no AV1 encoder rather than failing inside ffmpeg."""
+ sys.path.insert(0, str(SCRIPTS))
+ import export as export_mod
+ frames = {name: (p["w"], p["h"], p["max"]) for name, p in export_mod.PRESETS.items()
+ if name in ("reels", "tiktok", "shorts", "linkedin", "facebook")}
+ self.assertEqual(len(set(frames.values())), 5, f"presets must be distinct entries: {frames}")
+ for preset, size in (("tiktok", (1080, 1920)), ("linkedin", (1080, 1080))):
+ out = OUT / f"export_{preset}.mp4"
+ script("export.py", self.src, "--preset", preset, "--fast", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), size)
+ hdr_out = OUT / "export_yt_hdr.mp4"
+ script("export.py", self.hdr, "--preset", "youtube-hdr", "--fast", "-o", hdr_out)
+ m = probe(str(hdr_out))
+ self.assertTrue(m["video"]["hdr"], "youtube-hdr must keep the source's HDR")
+ self.assertNotEqual(m["video"]["color_space"], "bt709")
+ doc = json.loads(script("export.py", self.src, "--preset", "youtube-hdr", "--json",
+ "-o", str(OUT / "never.mp4"), expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("SDR", doc["error"]["message"])
+ from _common import ffmpeg_encoders
+ av1_out = OUT / "export_yt_av1.mp4"
+ if {"libsvtav1", "libaom-av1"} & ffmpeg_encoders():
+ script("export.py", self.src, "--preset", "youtube-av1", "--fast", "-o", av1_out)
+ self.assertEqual(probe(str(av1_out))["video"]["codec"], "av1")
+ else:
+ doc = json.loads(script("export.py", self.src, "--preset", "youtube-av1", "--json",
+ "-o", str(av1_out), expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "missing_tool")
+
+ def test_template_logo_lands_inside_the_platform_safe_zone(self):
+ """A template's --logo used to be drawn 24 px from the corner -- i.e. under TikTok's own
+ status bar and next to its tab row. The overlay stage now hears the destination like the
+ caption and graphics stages do, so the planned overlay sits inside the safe zone."""
+ sys.path.insert(0, str(SCRIPTS))
+ from _platforms import PLATFORMS
+ safe = PLATFORMS["tiktok"]["safe"]
+ W, H = PLATFORMS["tiktok"]["frame"]["w"], PLATFORMS["tiktok"]["frame"]["h"]
+ doc = json.loads(script("render.py", self.src, "--template", "tiktok", "--cues", self.cues,
+ "--logo", self.logo, "--dry-run", "--json",
+ "-o", str(OUT / "logo_safe.mp4")).stdout)
+ cmd = [c for c in doc["commands"] if "logo.png" in c and "overlay=" in c]
+ self.assertTrue(cmd, doc["commands"])
+ x, y = re.search(r"overlay=(-?\d+):(-?\d+)", cmd[0]).groups()
+ self.assertGreaterEqual(int(x), round(safe["left"] * W) - 1,
+ "the logo must clear the left safe margin")
+ self.assertGreaterEqual(int(y), round(safe["top"] * H) - 1,
+ "the logo must clear TikTok's status bar and tab row")
+ self.assertLess(int(y), H - round(safe["bottom"] * H))
+
+ def test_export_presets_are_the_platform_tables_frame_and_duration(self):
+ """docs/contract.md says export.py's PRESETS/PLATFORM_OF come from scripts/_platforms.py.
+ Until review 12 only check.py's SPECS did, and the facebook preset had already drifted
+ (no duration cap against the table's 14400 s). Every platform preset is the table now,
+ except the two deliberate, documented exceptions."""
+ sys.path.insert(0, str(SCRIPTS))
+ import export as export_mod
+ from _platforms import PLATFORMS, loudness_of
+ from check import SPECS
+ # youtube4k delivers to youtube at 2160p; neither youtube preset trims at the 12-hour cap
+ exceptions = {"youtube": {"max"}, "youtube4k": {"w", "h", "max"},
+ "youtube-hdr": {"w", "h", "max"}, "youtube-av1": {"max"}}
+ for preset, platform in sorted(export_mod.PLATFORM_OF.items()):
+ with self.subTest(preset=preset):
+ p = export_mod.PRESETS[preset]
+ frame = PLATFORMS[platform]["frame"]
+ spec = PLATFORMS[platform]["spec"]
+ skip = exceptions.get(preset, set())
+ if "w" not in skip:
+ self.assertEqual((p["w"], p["h"]), (frame["w"], frame["h"]),
+ f"{preset} frame must be {platform}'s frame")
+ if "max" not in skip:
+ self.assertEqual(p["max"], float(spec["max_duration"]) if spec["max_duration"] else None,
+ f"{preset} duration cap must be {platform}'s")
+ table = loudness_of(platform)
+ self.assertEqual((SPECS[platform]["lufs"], SPECS[platform]["lufs_tol"], SPECS[platform]["tp"]),
+ (table["lufs"], table["lufs_tol"], table["tp"]))
+ self.assertEqual(export_mod.PRESETS["facebook"]["max"], 14400.0,
+ "the drift review 12 found: facebook had no duration cap at all")
+
+ def test_every_template_caption_block_is_the_tables_safe_zone(self):
+ """The templates must not restate the numbers the table exists to own: change a
+ destination's safe zone and every shipped template follows, rather than keeping an old
+ margin silently."""
+ sys.path.insert(0, str(SCRIPTS))
+ from _platforms import PLATFORMS, caption_defaults
+ import render as render_mod
+ for path in sorted((ROOT / "templates").glob("*.json")):
+ tpl = json.loads(path.read_text(encoding="utf-8"))
+ cap = tpl.get("captions")
+ if not cap:
+ continue
+ dest = tpl["check"]["platform"]
+ with self.subTest(template=path.stem):
+ want = caption_defaults(dest)
+ self.assertEqual((cap["size"], cap["margin"]), (want["size"], want["margin"]),
+ f"{path.name} restates {dest}'s caption size/margin")
+ self.assertTrue(PLATFORMS[dest]["frame"])
+ # and the filled project takes them from the table, not from the file's literals
+ proj = OUT / "tplcap_project.json"
+ script("render.py", self.src, "--template", "reels", "--cues", self.cues,
+ "--write-project", proj, "-o", str(OUT / "tplcap.mp4"))
+ filled = json.loads(proj.read_text())["captions"]
+ want = caption_defaults("reels")
+ self.assertEqual((filled["size"], filled["margin"]), (want["size"], want["margin"]))
+
+ def test_platform_aliases_resolve_the_same_on_every_tool(self):
+ """One resolve(): 'youtube-shorts' is 'shorts' for check, export, caption, graphics, look
+ and render alike. Before review 12 the alias map was written, advertised in the docs and
+ called from nowhere, so no tool accepted a single one of them."""
+ sys.path.insert(0, str(SCRIPTS))
+ import render as render_mod
+ self.assertEqual(render_mod.expand_templates("ig"), ["reels"])
+ self.assertEqual(render_mod.expand_templates("twitter,yt"), ["x", "youtube"])
+ self.assertEqual(render_mod.expand_templates("youtube-shorts"), ["youtube-shorts"],
+ "a template that ships under its own name stays itself")
+ target = OUT / "alias_src.mp4"
+ script("fit.py", self.src, "--duration", "3", "--aspect", "9:16", "--fit", "crop",
+ "--width", "360", "--fast", "-o", target)
+
+ def commands(tool, *argv):
+ doc = json.loads(script(tool, target, *argv, "--dry-run", "--json").stdout)
+ # drawn text goes through a private PER-RUN temp directory (1.15: mkdtemp, 0700,
+ # removed at exit), so its random name differs between two processes by design and
+ # is not part of what "the same destination" means.
+ return [re.sub(r"ffmpeg-skill-text-[^/]+/", "ffmpeg-skill-text/", c)
+ for c in doc["commands"] if "ffmpeg" in c or "drawtext" in c]
+
+ # the alias is the point here, not compliance: a 3 s crop can miss the fps row on some
+ # ffmpeg builds (7.1 reports the speed-changed rate differently), and check.py names
+ # the resolved platform in its JSON on failure as well as on success
+ proc_a = subprocess.run([sys.executable, str(SCRIPTS / "check.py"), str(target), "--platform",
+ "youtube-shorts", "--no-loudness", "--json"],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8")
+ doc_a = json.loads(proc_a.stdout)
+ self.assertEqual(doc_a["platform"], "shorts")
+ self.assertTrue(doc_a["checks"], "check.py must have run the shorts rows under the alias")
+ for tool, argv in (
+ ("export.py", ("--preset", "youtube-shorts", "-o", str(OUT / "alias_exp.mp4"))),
+ ("caption.py", ("--text", self.cues, "-o", str(OUT / "alias_cap.mp4"), "--platform", "youtube-shorts")),
+ ("graphics.py", ("--template", "bug", "--title", "@x", "-o", str(OUT / "alias_gfx.mp4"), "--platform", "youtube-shorts")),
+ ("look.py", ("--at", "1", "-o", str(OUT / "alias_look.png"), "--safe", "youtube-shorts"))):
+ with self.subTest(tool=tool):
+ canonical = tuple("shorts" if a == "youtube-shorts" else a for a in argv)
+ self.assertEqual(commands(tool, *argv), commands(tool, *canonical),
+ f"{tool} must treat youtube-shorts and shorts as one destination")
+
+
+if __name__ == "__main__":
+ unittest.main(verbosity=2)
diff --git a/tests/test_editing.py b/tests/test_editing.py
new file mode 100644
index 0000000..2975b14
--- /dev/null
+++ b/tests/test_editing.py
@@ -0,0 +1,1041 @@
+#!/usr/bin/env python3
+"""End-to-end tests for cut, fit, crop, join, insert, broll, freeze, pad, speedramp, loop, reverse, sequence, silence, metadata, straighten and sphere.
+
+ python3 tests/test_editing.py # this group alone
+ python3 tests/test_all.py # every group
+"""
+import json
+import re
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _fixtures import MediaFixtures, OUT, SCRIPTS, script, sh # noqa: E402
+from _common import probe # noqa: E402
+
+
+class EditingTests(MediaFixtures):
+ """Cut, fit, crop, join, insert, broll, freeze, pad, speedramp, loop, reverse, sequence, silence, metadata, straighten and sphere."""
+
+ # ---------------------------------------------------------------- cut
+ def test_cut_single_copy(self):
+ out = OUT / "cut1.mp4"
+ script("cut.py", self.src, "--start", "2", "--end", "6", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 4.0, 0.5, "lossless cut falls back to re-encode when the keyframe snap is too far")
+ self.assertEqual(m["video"]["codec"], "h264")
+
+ def test_cut_copy_never_reencodes_when_tolerance_disabled(self):
+ out = OUT / "cut3.mp4"
+ proc = script("cut.py", self.src, "--start", "2", "--end", "6", "--tolerance", "-1", "-o", out)
+ self.assertIn("lossless stream copy", proc.stderr)
+
+ def test_cut_segments_accurate(self):
+ out = OUT / "cut2.mp4"
+ script("cut.py", self.src, "--segments", "1-3,6-9", "--accurate", "-o", out)
+ self.assertClose(probe(str(out))["duration"], 5.0, 0.15)
+
+ def test_cut_json_reports_requested_vs_actual_and_mode(self):
+ # exact-second cut on a keyframe-aligned GOP: expect a clean lossless copy
+ out = OUT / "cut_honest_copy.mp4"
+ data = json.loads(script("cut.py", self.src, "--start", "2", "--end", "6", "--tolerance", "-1", "-o", out, "--json").stdout)
+ self.assertEqual(data["mode"], "copy")
+ self.assertTrue(data["keyframe_snapped"])
+ self.assertEqual(data["requested_start"], 2.0)
+ self.assertEqual(data["requested_end"], 6.0)
+ self.assertEqual(data["requested_duration"], 4.0)
+ self.assertAlmostEqual(data["output_duration"], probe(str(out))["duration"], places=2)
+ self.assertAlmostEqual(data["duration_delta_seconds"], data["duration_error_ms"] / 1000, places=6)
+
+ # --accurate: forced re-encode, never "hybrid"
+ out2 = OUT / "cut_honest_accurate.mp4"
+ data2 = json.loads(script("cut.py", self.src, "--start", "2", "--end", "6", "--accurate", "-o", out2, "--json").stdout)
+ self.assertEqual(data2["mode"], "accurate")
+ self.assertFalse(data2["keyframe_snapped"])
+
+ # a start/end that doesn't land on a keyframe, with a tight tolerance, must silently
+ # upgrade from copy to re-encode -- and say "hybrid", not just "reencoded: true"
+ out3 = OUT / "cut_honest_hybrid.mp4"
+ data3 = json.loads(script("cut.py", self.src, "--start", "1.13", "--end", "5.71", "--tolerance", "0.02", "-o", out3, "--json").stdout)
+ self.assertTrue(data3["reencoded"])
+ self.assertEqual(data3["mode"], "hybrid")
+ self.assertFalse(data3["keyframe_snapped"])
+ # ...and name the keyframes a lossless cut could have used instead (x264's default GOP on the
+ # fixture puts the only one within 5 s of 1.13 at 0.0)
+ self.assertTrue(data3["nearest_keyframes"], data3)
+ self.assertIn(0.0, data3["nearest_keyframes"])
+ self.assertIsNone(data["nearest_keyframes"], "a clean copy has no alternative to offer")
+
+ # multi-segment: requested_start/end are None, requested_segments lists each range
+ out4 = OUT / "cut_honest_segments.mp4"
+ data4 = json.loads(script("cut.py", self.src, "--segments", "1-3,6-9", "--accurate", "-o", out4, "--json").stdout)
+ self.assertIsNone(data4["requested_start"])
+ self.assertIsNone(data4["requested_end"])
+ self.assertEqual(data4["requested_segments"], [[1.0, 3.0], [6.0, 9.0]])
+ self.assertEqual(data4["requested_duration"], 5.0)
+
+ def test_cut_copy_keyframe_snap_reports_a_real_nonzero_delta(self):
+ """Pins the actual failure mode `mode`/`keyframe_snapped`/`duration_delta_seconds` exist to
+ surface: a non-keyframe-aligned request that stays within --tolerance keeps the fast
+ stream copy (mode=copy) rather than upgrading to hybrid, but the copy still snapped to an
+ earlier keyframe and pulled in extra content -- output_duration and requested_duration
+ genuinely diverge, and a caller must be told this happened, not left to assume the file
+ starts exactly where it asked."""
+ out = OUT / "cut_copy_keyframe_snap.mp4"
+ data = json.loads(script("cut.py", self.src, "--start", "1.13", "--end", "5.71", "--tolerance", "2.0", "-o", out, "--json").stdout)
+ self.assertEqual(data["mode"], "copy")
+ self.assertTrue(data["keyframe_snapped"])
+ self.assertFalse(data["reencoded"])
+ actual = probe(str(out))["duration"]
+ self.assertAlmostEqual(data["output_duration"], actual, places=2)
+ self.assertGreater(abs(data["duration_delta_seconds"]), 0.05, "this scenario must produce a real, visible divergence, not a rounding artefact")
+ self.assertAlmostEqual(data["duration_delta_seconds"], data["output_duration"] - data["requested_duration"], places=6)
+
+ def test_cut_bad_range_fails(self):
+ script("cut.py", self.src, "--start", "5", "--end", "2", expect_fail=True)
+
+ def test_cut_refuses_negative_start_and_end(self):
+ """Unlike freeze.py/background.py, which explicitly refuse negative durations, cut.py
+ passed --start/--end straight through to parse_time() with no sign check at all, so a
+ negative value (e.g. from an agent computing an offset that went wrong) reached ffmpeg's
+ -ss as -5.000000 instead of being refused with a clear error naming the flag."""
+ proc = script("cut.py", self.src, "--start", "-5", "--end", "2", expect_fail=True)
+ self.assertIn("--start", proc.stderr)
+ proc = script("cut.py", self.src, "--start", "0", "--end", "-2", expect_fail=True)
+ self.assertIn("--end", proc.stderr)
+
+ # ---------------------------------------------------------------- fit
+ def test_fit_duration_speed_and_aspect_pad(self):
+ out = OUT / "fit1.mp4"
+ script("fit.py", self.src, "--duration", "6", "--aspect", "9:16", "--fit", "pad", "--width", "540", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 6.0, 0.15)
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (540, 960))
+
+ def test_broll_cutaway_shows_b_in_the_window_and_keeps_a_elsewhere(self):
+ """#141: broll.py shows B's picture over A for a window and returns to A at A's own time;
+ the output is exactly A's length. Checked frame by frame: inside the window a frame
+ matches B (at --from + offset) and not A; outside it matches A. --audio a stream-copies
+ A's audio; two cutaways in one call; overlapping or past-the-end windows are refused."""
+ def frame_luma(path, t):
+ proc = sh("ffmpeg", "-hide_banner", "-loglevel", "error", "-ss", str(t), "-i", path, "-frames:v", "1",
+ "-vf", "signalstats,metadata=print:file=-", "-f", "null", "-")
+ return float(re.search(r"lavfi\.signalstats\.YAVG=([0-9.]+)", proc.stdout).group(1))
+ b = OUT / "broll_b.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "smptebars=size=960x540:rate=25:d=8",
+ "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=48000:duration=8", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", b)
+ out = OUT / "broll_out.mp4"
+ data = json.loads(script("broll.py", self.src, "--insert", b, "--at", "4", "--end", "7", "--from", "1", "--fast", "--json", "-o", out).stdout)
+ # --pad-color is spliced into the filter graph like every other colour flag, so it is validated like them
+ inj = script("broll.py", self.src, "--insert", b, "--at", "4", "--end", "7", "--pad-color", "black,drawtext=text=INJECTED",
+ "--json", "-o", OUT / "broll_inj.mp4", expect_fail=True)
+ self.assertIn("plain colour", json.loads(inj.stdout)["error"]["message"])
+ self.assertEqual(json.loads(inj.stdout)["commands"], [], "refused before ffmpeg ran")
+ self.assertEqual(data["cutaways"], [{"insert": str(b), "at": 4.0, "end": 7.0, "from": 1.0}])
+ m = probe(str(out))
+ self.assertClose(m["duration"], probe(str(self.src))["duration"], 0.1)
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
+ self.assertEqual(m["audio"]["codec"], probe(str(self.src))["audio"]["codec"], "--audio a stream-copies A's audio")
+ inside_out, inside_b, inside_a = frame_luma(str(out), 5.5), frame_luma(str(b), 2.5), frame_luma(str(self.src), 5.5)
+ self.assertLess(abs(inside_out - inside_b), 6, f"inside the window the frame must be B's: out {inside_out} b {inside_b} a {inside_a}")
+ self.assertGreater(abs(inside_out - inside_a), 6, "inside the window the frame must not be A's")
+ for t in (2.0, 9.0):
+ self.assertLess(abs(frame_luma(str(out), t) - frame_luma(str(self.src), t)), 3, f"outside the window ({t}s) A must show unchanged")
+ # two cutaways, B's audio mixed in, per-cutaway durations
+ out2 = OUT / "broll_out2.mp4"
+ script("broll.py", self.src, "--insert", b, "--at", "1", "--duration", "2", "--insert", b, "--at", "8", "--duration", "3", "--audio", "mix", "--fast", "-o", out2)
+ m2 = probe(str(out2))
+ self.assertClose(m2["duration"], 12.0, 0.1)
+ self.assertEqual(m2["audio"]["codec"], "aac")
+ self.assertLess(abs(frame_luma(str(out2), 9.5) - frame_luma(str(b), 1.5)), 6)
+ # refusals: overlap, past the end, B too short, missing --at
+ script("broll.py", self.src, "--insert", b, "--at", "1", "--duration", "3", "--insert", b, "--at", "2", "-o", OUT / "broll_bad1.mp4", expect_fail=True)
+ script("broll.py", self.src, "--insert", b, "--at", "10", "--duration", "5", "-o", OUT / "broll_bad2.mp4", expect_fail=True)
+ script("broll.py", self.src, "--insert", b, "--at", "1", "--duration", "5", "--from", "5", "-o", OUT / "broll_bad3.mp4", expect_fail=True)
+ script("broll.py", self.src, "--insert", b, "--insert", b, "--at", "1", "-o", OUT / "broll_bad4.mp4", expect_fail=True)
+ dry = OUT / "broll_dry.mp4"
+ script("broll.py", self.src, "--insert", b, "--at", "4", "--dry-run", "-o", dry)
+ self.assertFalse(dry.exists())
+
+ def test_metadata_writes_chapters_and_tags_with_streams_copied(self):
+ """#140: metadata.py writes container chapter markers from a `TIME TITLE` file and the
+ common tags, with every stream copied bit for bit; probe reports both back. Chapters on a
+ container that cannot hold them are refused, --clear-chapters removes them, a chapter
+ past the end or out of order is refused, and the input is never rewritten in place."""
+ chapters = OUT / "chapters.txt"
+ chapters.write_text("# episode\n0:00 Intro\n4 Setup, with a comma; and =signs\n0:08 Outro\n", encoding="utf-8")
+ out = OUT / "meta_chapters.mp4"
+ data = json.loads(script("metadata.py", self.src, "--chapters", chapters, "--title", "Episode 12", "--artist", "Studio", "--comment", "final", "--json", "-o", out).stdout)
+ self.assertTrue(data["streams_copied"])
+ m = probe(str(out))
+ self.assertEqual([(round(c["start"]), round(c["end"]), c["title"]) for c in m["chapters"]],
+ [(0, 4, "Intro"), (4, 8, "Setup, with a comma; and =signs"), (8, 12, "Outro")])
+ self.assertEqual(m["tags"].get("title"), "Episode 12")
+ self.assertEqual(m["tags"].get("artist"), "Studio")
+ self.assertEqual(m["tags"].get("comment"), "final")
+ src = probe(str(self.src))
+ self.assertEqual((m["video"]["codec"], m["audio"]["codec"]), (src["video"]["codec"], src["audio"]["codec"]))
+ self.assertEqual(self._frame_count(out), self._frame_count(self.src))
+ self.assertEqual(self._psnr(self.src, out), float("inf"), "streams must be copied, not re-encoded")
+ # tags alone keep the chapters; --clear-chapters removes them and keeps the tags
+ tagged = OUT / "meta_tagged.mp4"
+ script("metadata.py", out, "--comment", "v2", "-o", tagged)
+ self.assertEqual(len(probe(str(tagged))["chapters"]), 3)
+ self.assertEqual(probe(str(tagged))["tags"].get("comment"), "v2")
+ cleared = OUT / "meta_cleared.mp4"
+ script("metadata.py", out, "--clear-chapters", "-o", cleared)
+ self.assertEqual(probe(str(cleared))["chapters"], [])
+ self.assertEqual(probe(str(cleared))["tags"].get("title"), "Episode 12")
+ # refusals
+ script("metadata.py", OUT / "long_ref.wav", "--chapters", chapters, "-o", OUT / "meta_bad.wav", expect_fail=True)
+ script("metadata.py", self.src, "-o", OUT / "meta_nothing.mp4", expect_fail=True)
+ script("metadata.py", self.src, "--title", "x", "-o", self.src, expect_fail=True)
+ bad = OUT / "chapters_bad.txt"
+ bad.write_text("0:00 A\n0:30 B\n", encoding="utf-8")
+ script("metadata.py", self.src, "--chapters", bad, "-o", OUT / "meta_bad2.mp4", expect_fail=True)
+ bad.write_text("0:05 A\n0:02 B\n", encoding="utf-8")
+ script("metadata.py", self.src, "--chapters", bad, "-o", OUT / "meta_bad3.mp4", expect_fail=True)
+ # dry run writes nothing
+ dry = OUT / "meta_dry.mp4"
+ script("metadata.py", self.src, "--chapters", chapters, "--dry-run", "-o", dry)
+ self.assertFalse(dry.exists())
+
+ def test_fit_pad_fill_blur_puts_picture_in_the_bars_and_color_stays_solid(self):
+ """#139: --fit pad --pad-fill blur fills the letterbox/pillarbox bars with a blurred,
+ scaled-to-cover copy of the frame (the phone-editor "make it vertical" look) instead of a
+ solid --pad-color. The source is landscape, so 9:16 gives bars above and below: with
+ blur they must carry picture (not black, not one flat value), with color (the default)
+ they must stay the solid pad colour exactly as before. export.py shares the same path."""
+ def bar_stats(path, top_px=60):
+ # mean and spread of the top bar's luma over a frame at t=1s
+ proc = sh("ffmpeg", "-hide_banner", "-loglevel", "error", "-ss", "1", "-i", path, "-frames:v", "1",
+ "-vf", f"crop=iw:{top_px}:0:0,signalstats,metadata=print:file=-", "-f", "null", "-")
+ vals = {k: float(v) for k, v in re.findall(r"lavfi\.signalstats\.(YAVG|YMIN|YMAX)=([0-9.]+)", proc.stdout)}
+ return vals["YAVG"], vals["YMAX"] - vals["YMIN"]
+ blur = OUT / "fit_pad_blur.mp4"
+ script("fit.py", self.src, "--duration", "3", "--aspect", "9:16", "--fit", "pad", "--pad-fill", "blur", "--width", "360", "--fast", "-o", blur)
+ m = probe(str(blur))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (360, 640))
+ avg, spread = bar_stats(str(blur))
+ self.assertGreater(avg, 20, f"blurred bar is (nearly) black: YAVG {avg}")
+ self.assertGreater(spread, 10, f"blurred bar is flat: spread {spread}")
+ solid = OUT / "fit_pad_color.mp4"
+ script("fit.py", self.src, "--duration", "3", "--aspect", "9:16", "--fit", "pad", "--width", "360", "--fast", "-o", solid)
+ avg, spread = bar_stats(str(solid))
+ self.assertLess(avg, 20, f"solid black bar is not black: YAVG {avg}")
+ self.assertLess(spread, 4, f"solid bar is not flat: spread {spread}")
+ # the same option on export.py's preset frame
+ exp = OUT / "export_pad_blur.mp4"
+ script("export.py", self.src, "--preset", "reels", "--pad-fill", "blur", "--fast", "-o", exp)
+ avg, spread = bar_stats(str(exp), 120)
+ self.assertGreater(avg, 20); self.assertGreater(spread, 10)
+ script("fit.py", self.src, "--aspect", "9:16", "--pad-fill", "blur", "--pad-blur", "0", "--dry-run", expect_fail=True)
+
+ def test_fit_trim_and_crop_square(self):
+ out = OUT / "fit2.mp4"
+ script("fit.py", self.src, "--duration", "4", "--method", "trim", "--from-center", "--aspect", "1:1", "--fit", "crop", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 4.0, 0.15)
+ self.assertEqual(m["video"]["width"], m["video"]["height"])
+
+ def test_fit_aspect_only_never_upscales_past_source_resolution(self):
+ """With only --aspect given (no --width/--height), the "elif ratio and src_ratio" branch
+ used to bound a narrower/taller target by the source's WIDTH, not its height -- so a
+ 1280x720 (16:9) source asked for 9:16 came out 1280x2276, a ~3.16x unrequested upscale in
+ both fit=pad and fit=crop. Neither dimension of the output should exceed the source's."""
+ out = OUT / "fit_aspect_only_tall.mp4"
+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--fast", "-o", out)
+ m = probe(str(out))
+ self.assertLessEqual(m["video"]["width"], 1280)
+ self.assertLessEqual(m["video"]["height"], 720)
+ self.assertEqual(m["video"]["height"], 720, "bounded by source height, not blown up")
+
+ def test_fit_refuses_extreme_speed(self):
+ script("fit.py", self.src, "--duration", "1", expect_fail=True)
+
+ def test_fit_crop_anchor_keeps_a_chosen_edge_not_just_the_centre(self):
+ """A centre crop can cut a subject held to one side; --crop-x/-y say what to keep."""
+ left = OUT / "fit_crop_left.mp4"
+ right = OUT / "fit_crop_right.mp4"
+ center = OUT / "fit_crop_center.mp4"
+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--width", "360", "--crop-x", "0", "-o", left)
+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--width", "360", "--crop-x", "1", "-o", right)
+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--width", "360", "-o", center)
+ for out in (left, right, center):
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (360, 640))
+ # different horizontal anchors must crop different content, not just resize the same crop
+ self.assertLess(self._psnr(left, right), 40, "crop-x=0 vs crop-x=1 kept the same picture")
+
+ def test_fit_crop_anchor_out_of_range_is_refused(self):
+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--crop-x", "1.5", expect_fail=True)
+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--crop-y", "-0.1", expect_fail=True)
+
+ def test_fit_height_alone_follows_source_aspect(self):
+ out = OUT / "fit_h.mp4"
+ script("fit.py", self.src, "--height", "480", "-o", out)
+ m = probe(str(out))
+ # source is 1280x720 (16:9); height 480 -> width 853.33 rounds to even 854
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (854, 480))
+
+ def test_fit_width_and_height_both_given_is_exact(self):
+ out = OUT / "fit_wh.mp4"
+ script("fit.py", self.src, "--width", "500", "--height", "500", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (500, 500))
+
+ def test_fit_width_alone_still_works(self):
+ out = OUT / "fit_w.mp4"
+ script("fit.py", self.src, "--width", "640", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
+
+ def test_fit_rotate_90_swaps_dimensions(self):
+ out = OUT / "fit_rot90.mp4"
+ script("fit.py", self.src, "--rotate", "90", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (720, 1280))
+
+ def test_fit_rotate_and_flip_change_actual_pixels(self):
+ """Not just that dimensions are right -- a known left/right split must actually swap or rotate."""
+ quad = OUT / "quad_src.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=red:s=100x50",
+ "-f", "lavfi", "-i", "color=c=blue:s=100x50", "-filter_complex", "[0][1]hstack", "-frames:v", "1", "-t", "1",
+ "-c:v", "libx264", "-pix_fmt", "yuv420p", quad)
+
+ def px(path, x, y):
+ r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path),
+ "-vf", f"crop=2:2:{x}:{y}", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ return r.stdout[:3]
+
+ fliph = OUT / "quad_fliph.mp4"
+ script("fit.py", quad, "--flip", "h", "-o", fliph)
+ self.assertGreater(px(fliph, 10, 10)[2], 100, "flip h: left side should now be blue (high B channel)")
+ self.assertGreater(px(fliph, 150, 10)[0], 100, "flip h: right side should now be red (high R channel)")
+
+ rot90 = OUT / "quad_rot90.mp4"
+ script("fit.py", quad, "--rotate", "90", "-o", rot90)
+ self.assertGreater(px(rot90, 10, 10)[0], 100, "rotate 90cw: original left (red) column becomes the top row")
+
+ def test_fit_nothing_to_do_is_refused(self):
+ script("fit.py", self.src, expect_fail=True)
+
+ def test_fit_audio_stream_selects_the_requested_track_not_always_the_first(self):
+ two = OUT / "fit_two_streams.mkv"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
+ "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
+ "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
+ self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
+ out1 = OUT / "fit_two_s1.mp4"
+ script("fit.py", two, "--audio-stream", "1", "--width", "160", "-o", out1, "--preset", "veryfast")
+ self.assertIsNotNone(probe(str(out1))["audio"], "default fit.py now explicitly maps audio too, not just the automatic 'best stream' pick")
+ proc = script("fit.py", two, "--audio-stream", "5", "--width", "160", "-o", OUT / "fit_nope.mp4", "--json", expect_fail=True)
+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
+ self.assertIn("audio-stream", proc.stderr)
+
+ # ---------------------------------------------------------------- crop
+ def test_crop_exact_rectangle(self):
+ out = OUT / "crop1.mp4"
+ script("crop.py", self.src, "--x", "100", "--y", "0", "--width", "1080", "--height", "720", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1080, 720))
+ self.assertClose(m["duration"], 12.0, 0.2)
+
+ def test_crop_out_of_bounds_is_refused(self):
+ script("crop.py", self.src, "--x", "1200", "--y", "0", "--width", "200", "--height", "200", expect_fail=True)
+
+ def test_crop_odd_dimensions_refused(self):
+ script("crop.py", self.src, "--x", "0", "--y", "0", "--width", "101", "--height", "100", expect_fail=True)
+
+ def test_crop_negative_offset_refused(self):
+ script("crop.py", self.src, "--x", "-5", "--y", "0", "--width", "100", "--height", "100", expect_fail=True)
+
+ # ---------------------------------------------------------------- sphere
+ def test_sphere_extracts_a_flat_viewport(self):
+ out = OUT / "sphere1.mp4"
+ script("sphere.py", self.src, "--yaw", "90", "--pitch", "10", "--h-fov", "100", "--v-fov", "70",
+ "--width", "640", "--height", "360", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
+ self.assertClose(m["duration"], 12.0, 0.2)
+ self.assertIsNotNone(m["audio"])
+
+ def test_sphere_defaults_and_no_audio_source(self):
+ no_audio = OUT / "sphere_no_audio_src.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=640x320:rate=25",
+ "-t", "2", "-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p", no_audio)
+ out = OUT / "sphere2.mp4"
+ script("sphere.py", no_audio, "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1920, 1080))
+ self.assertIsNone(m["audio"])
+
+ def test_sphere_yaw_out_of_range_refused(self):
+ script("sphere.py", self.src, "--yaw", "200", expect_fail=True)
+
+ def test_sphere_fov_out_of_range_refused(self):
+ script("sphere.py", self.src, "--h-fov", "0", expect_fail=True)
+
+ def test_sphere_odd_dimensions_refused(self):
+ script("sphere.py", self.src, "--width", "641", "--height", "360", expect_fail=True)
+
+ def test_sphere_audio_stream_out_of_range_refused(self):
+ script("sphere.py", self.src, "--audio-stream", "5", expect_fail=True)
+
+ # ---------------------------------------------------------------- straighten
+ def test_straighten_crop_fit_has_no_black_corner(self):
+ out = OUT / "straighten1.mp4"
+ script("straighten.py", self.src, "--degrees", "10", "--fit", "crop", "-o", out)
+ m = probe(str(out))
+ self.assertLess(m["video"]["width"], 1280)
+ self.assertLess(m["video"]["height"], 720)
+ self.assertEqual(m["video"]["width"] % 2, 0)
+ self.assertEqual(m["video"]["height"] % 2, 0)
+ frame = OUT / "straighten1_corner.raw"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", out, "-vf", "crop=8:8:0:0",
+ "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", frame)
+ data = frame.read_bytes()
+ self.assertFalse(all(b == 0 for b in data), "top-left corner is pure black -- straighten left a visible gap")
+
+ def test_straighten_pad_fit_grows_the_frame(self):
+ out = OUT / "straighten2.mp4"
+ script("straighten.py", self.src, "--degrees", "-8", "--fit", "pad", "-o", out)
+ m = probe(str(out))
+ self.assertGreater(m["video"]["width"], 1280)
+ self.assertGreater(m["video"]["height"], 720)
+
+ def test_straighten_zero_degrees_refused(self):
+ script("straighten.py", self.src, "--degrees", "0", expect_fail=True)
+
+ def test_straighten_out_of_range_refused(self):
+ script("straighten.py", self.src, "--degrees", "60", expect_fail=True)
+
+ # ---------------------------------------------------------------- freeze
+ def test_freeze_insert_extends_duration(self):
+ out = OUT / "freeze1.mp4"
+ script("freeze.py", self.src, "--at", "5", "--hold", "1", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 13.0, 0.3)
+
+ def test_freeze_extend_mode_at_end(self):
+ out = OUT / "freeze2.mp4"
+ script("freeze.py", self.src, "--hold", "1.5", "--mode", "extend", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 13.5, 0.3)
+
+ def test_freeze_mid_clip_audio_pad_matches_the_frame_rounded_video_hold(self):
+ """The video hold is n = round(hold * fps) whole frames -- n / fps in general isn't
+ exactly --hold when hold*fps isn't an integer (e.g. 1.4s at 30fps -> n=42, 42/30=1.4
+ exactly here, so use a value where it doesn't divide evenly). apad used to pad by the
+ raw --hold value instead of that same frame-rounded duration, so video and audio drifted
+ apart by up to half a frame -- a permanent A/V sync error from that point on. Verify the
+ constructed apad=pad_dur= matches n/fps, not the raw --hold value."""
+ out = OUT / "freeze_avsync.mp4"
+ fps = probe(self.src)["video"]["fps"]
+ hold = 1.03 # picked so hold*fps is not a whole number at this source's fps
+ data = json.loads(script("freeze.py", self.src, "--at", "5", "--hold", str(hold), "-o", out, "--fast", "--json").stdout)
+ n = round(hold * fps)
+ expected_pad = n / fps
+ cmd = data["commands"][0]
+ m = re.search(r"apad=pad_dur=([\d.]+)", cmd)
+ self.assertIsNotNone(m, f"expected an apad=pad_dur= in: {cmd}")
+ self.assertAlmostEqual(float(m.group(1)), expected_pad, places=4)
+
+ def test_freeze_extend_mode_before_end_refused(self):
+ script("freeze.py", self.src, "--at", "2", "--hold", "1", "--mode", "extend", expect_fail=True)
+
+ def test_freeze_zero_hold_refused(self):
+ script("freeze.py", self.src, "--hold", "0", expect_fail=True)
+
+ def test_freeze_at_zero_holds_the_first_frame(self):
+ """--at 0 has no preceding segment to trim/clone from in the general insert-mode filter
+ graph (an empty trim=end=0 stream broke ffmpeg filtering entirely); this exercises the
+ dedicated at==0 branch that pads the front of the clip instead."""
+ out = OUT / "freeze3.mp4"
+ script("freeze.py", self.src, "--at", "0", "--hold", "1", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 13.0, 0.3)
+
+ # ---------------------------------------------------------------- pad
+ def test_pad_start_and_end_extend_duration(self):
+ out = OUT / "pad1.mp4"
+ script("pad.py", self.src, "--start", "1", "--end", "2", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 15.0, 0.3)
+
+ def test_pad_nothing_refused(self):
+ script("pad.py", self.src, expect_fail=True)
+
+ def test_pad_negative_refused(self):
+ script("pad.py", self.src, "--start", "-1", expect_fail=True)
+
+ # ---------------------------------------------------------------- speedramp
+ def test_speedramp_segments_change_overall_duration(self):
+ out = OUT / "ramp1.mp4"
+ script("speedramp.py", self.src, "--segment", "0-6:1.0", "--segment", "6-9:0.5", "--segment", "9-12:2.0", "-o", out)
+ m = probe(str(out))
+ # 6/1.0 + 3/0.5 + 3/2.0 = 6 + 6 + 1.5 = 13.5s
+ self.assertClose(m["duration"], 13.5, 0.5)
+
+ def test_speedramp_bad_segment_format_refused(self):
+ script("speedramp.py", self.src, "--segment", "not-a-segment", expect_fail=True)
+
+ def test_speedramp_gap_refused(self):
+ script("speedramp.py", self.src, "--segment", "0-5:1.0", "--segment", "6-12:1.0", expect_fail=True)
+
+ def test_speedramp_must_start_at_zero_refused(self):
+ script("speedramp.py", self.src, "--segment", "1-12:1.0", expect_fail=True)
+
+ # ---------------------------------------------------------------- loop
+ def test_loop_times_multiplies_duration(self):
+ out = OUT / "loop1.mp4"
+ script("loop.py", self.src, "--times", "3", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 36.0, 1.0)
+
+ def test_loop_duration_hits_exact_target(self):
+ out = OUT / "loop2.mp4"
+ script("loop.py", self.src, "--duration", "20", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 20.0, 0.1)
+
+ def test_loop_times_too_small_refused(self):
+ script("loop.py", self.src, "--times", "1", expect_fail=True)
+
+ def test_loop_duration_shorter_than_source_refused(self):
+ script("loop.py", self.src, "--duration", "3", expect_fail=True)
+
+ # ---------------------------------------------------------------- insert
+ def test_insert_native_size_and_duration(self):
+ out = OUT / "insert1.mp4"
+ script("insert.py", self.logo, "--duration", "3", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 3.0, 0.15)
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (240, 90))
+ self.assertIsNone(m["audio"])
+
+ def test_insert_exact_frame_size_and_fps(self):
+ out = OUT / "insert2.mp4"
+ script("insert.py", self.logo, "--duration", "2", "--width", "500", "--height", "500", "--fps", "24", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 2.0, 0.15)
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (500, 500))
+ self.assertClose(m["video"]["fps"], 24.0, 0.01)
+
+ def test_insert_refuses_zero_duration(self):
+ script("insert.py", self.logo, "--duration", "0", expect_fail=True)
+
+ def test_insert_ken_burns_zoom_in_actually_scales_over_time(self):
+ """The frame must actually change scale over the clip, not just accept the flag."""
+ kb_src = OUT / "kb_src.png"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=white:s=800x800",
+ "-vf", "drawbox=x=300:y=300:w=200:h=200:color=red:t=fill", "-frames:v", "1", kb_src)
+ out = OUT / "kb1.mp4"
+ script("insert.py", kb_src, "--duration", "3", "--zoom", "in", "--zoom-amount", "1.3",
+ "--width", "640", "--height", "640", "--fps", "10", "-o", out)
+
+ def px(path, t, x, y):
+ r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path), "-ss", str(t),
+ "-vf", f"crop=2:2:{x}:{y}", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ return r.stdout[:3]
+
+ # a screen point between the square's edge at zoom=1 (0.625 normalised) and zoom=1.3 (0.6625):
+ # white at the start (not yet covered by the square), red by the end (zoomed in enough to cover it).
+ # Tolerant of lossy x264 rounding (e.g. macOS's build lands white at 0xfd, not a pure 0xff).
+ start_r, start_g, start_b = px(out, 0.1, 410, 410)
+ self.assertGreater(start_r, 240, "should still be white/unpainted before the zoom covers it")
+ self.assertGreater(start_g, 240)
+ self.assertGreater(start_b, 240)
+ end_r, end_g, end_b = px(out, 2.9, 410, 410)
+ self.assertGreater(end_r, 200, "should be red by the end (zoomed in enough to cover this point)")
+ self.assertLess(end_b, 60)
+
+ def test_insert_pan_without_zoom_is_refused(self):
+ script("insert.py", self.logo, "--duration", "2", "--pan", "left", expect_fail=True)
+
+ def test_insert_bad_zoom_amount_refused(self):
+ script("insert.py", self.logo, "--duration", "2", "--zoom", "in", "--zoom-amount", "1.0", expect_fail=True)
+
+ # ---------------------------------------------------------------- reverse
+ def test_reverse_swaps_start_and_end(self):
+ halfcolor = OUT / "halfcolor.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=red:s=64x64:d=1.5",
+ "-f", "lavfi", "-i", "color=c=blue:s=64x64:d=1.5", "-filter_complex", "[0][1]concat=n=2:v=1:a=0",
+ "-c:v", "libx264", "-pix_fmt", "yuv420p", halfcolor)
+ out = OUT / "rev1.mp4"
+ script("reverse.py", halfcolor, "-o", out)
+
+ def px(path, t):
+ r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path), "-ss", str(t),
+ "-vf", "crop=2:2:10:10", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ return r.stdout[:3]
+
+ self.assertGreater(px(out, 0.2)[2], 100, "reversed clip starts with the original's last half (blue)")
+ self.assertGreater(px(out, 2.8)[0], 100, "reversed clip ends with the original's first half (red)")
+
+ def test_reverse_no_audio_drops_track(self):
+ out = OUT / "rev_noaudio.mp4"
+ script("reverse.py", self.src, "--no-audio", "-o", out)
+ m = probe(str(out))
+ self.assertIsNone(m["audio"])
+
+ # ---------------------------------------------------------------- sequence
+ def test_sequence_numbered_pattern_preserves_order(self):
+ frames_dir = OUT / "seqframes"
+ frames_dir.mkdir(exist_ok=True)
+ for i in range(5):
+ color = "red" if i % 2 == 0 else "blue"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", f"-i", f"color=c={color}:s=64x48",
+ "-frames:v", "1", frames_dir / f"frame_{i:04d}.png")
+ out = OUT / "seq1.mp4"
+ script("sequence.py", "--dir", frames_dir, "--pattern", "frame_%04d.png", "--fps", "5", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 1.0, 0.1)
+
+ raw = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(out), "-vf", "crop=2:2:10:10",
+ "-f", "rawvideo", "-pix_fmt", "rgb24", "-"], stdout=subprocess.PIPE, stderr=subprocess.PIPE).stdout
+ frame_px = [raw[i * 12:i * 12 + 3] for i in range(len(raw) // 12)]
+ self.assertEqual(len(frame_px), 5)
+ for i, px in enumerate(frame_px):
+ if i % 2 == 0:
+ self.assertGreater(px[0], 100, f"frame {i} should be red")
+ else:
+ self.assertGreater(px[2], 100, f"frame {i} should be blue")
+
+ def test_sequence_glob_pattern(self):
+ frames_dir = OUT / "seqframes_glob"
+ frames_dir.mkdir(exist_ok=True)
+ for i in range(5):
+ color = "red" if i % 2 == 0 else "blue"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", f"-i", f"color=c={color}:s=64x48",
+ "-frames:v", "1", frames_dir / f"frame_{i:04d}.png")
+ out = OUT / "seq2.mp4"
+ script("sequence.py", "--dir", frames_dir, "--pattern", "*.png", "--fps", "5", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 1.0, 0.1)
+
+ def test_sequence_no_match_refused(self):
+ frames_dir = OUT / "seqframes"
+ script("sequence.py", "--dir", frames_dir, "--pattern", "*.jpg", "--fps", "5", expect_fail=True)
+
+ def test_sequence_missing_dir_refused(self):
+ script("sequence.py", "--dir", str(OUT / "does_not_exist"), "--pattern", "*.png", "--fps", "5", expect_fail=True)
+
+ def test_time_grammar_is_one_parser_with_an_fps_suffix(self):
+ """1.9 (roadmap): hh:mm:ss:ff@fps names the rate; broll / cut / freeze refuse a bad time as
+ kind input naming the flag, like every other tool, instead of their own wording."""
+ sys.path.insert(0, str(SCRIPTS))
+ try:
+ import _common as c
+ finally:
+ sys.path.pop(0)
+ self.assertAlmostEqual(c.parse_time("00:00:01:15@30"), 1.5)
+ self.assertAlmostEqual(c.parse_time("00:00:01:15@30", fps=24), 1.5, msg="the suffix beats the fps a tool passed in")
+ self.assertAlmostEqual(c.parse_time("01:00:00:[email protected]"), 108000 / 29.97)
+ with self.assertRaises(ValueError):
+ c.parse_time("12.5@30")
+ with self.assertRaises(ValueError):
+ c.parse_time("00:00:01:15@fast")
+ with self.assertRaises(c.MissingFpsError):
+ c.parse_time("00:00:01:15")
+ # the three tools that had their own wrappers
+ d = json.loads(script("cut.py", self.src, "--start", "00:00:01:15@30", "--end", "00:00:02:00@30", "-o", OUT / "tc_cut.mp4", "--json", "--overwrite").stdout)
+ self.assertAlmostEqual(d["expected_duration"], 0.5, places=2)
+ d = json.loads(script("cut.py", self.src, "--start", "nonsense", "-o", OUT / "tc_bad.mp4", "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ self.assertIn("--start", d["error"]["message"])
+ d = json.loads(script("freeze.py", self.src, "--at", "1:xx", "--hold", "1", "-o", OUT / "tc_freeze.mp4", "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ self.assertIn("--at", d["error"]["message"])
+ d = json.loads(script("broll.py", self.src, "--insert", self.src, "--at", "1:xx", "-o", OUT / "tc_broll.mp4", "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ self.assertIn("--at", d["error"]["message"])
+ # 1.9.1 (audit 8): a cue file may carry the suffix too -- the timecodes must not become the caption text
+ with self.assertRaises(ValueError) as cm:
+ c.parse_time("00:00:01:15@30@30")
+ self.assertIn("only one @fps", str(cm.exception), "no interpreter internals in the refusal")
+ tc = OUT / "tc_at_cues.txt"
+ tc.write_text("00:00:00:15@30 --> 00:00:02:00@30 Hello there\n", encoding="utf-8")
+ srt = OUT / "tc_at.srt"
+ script("caption.py", "--text", tc, "--write-srt", srt)
+ text = srt.read_text(encoding="utf-8")
+ self.assertIn("00:00:00,500 --> 00:00:02,000\nHello there", text)
+ self.assertNotIn("@30", text)
+ # metadata / multicam / speedramp refuse through the same parser and name the suffix
+ ch = OUT / "tc_chapters.txt"
+ ch.write_text("00:00:01:00 Intro\n", encoding="utf-8")
+ d = json.loads(script("metadata.py", self.src, "--chapters", ch, "-o", OUT / "tc_md.mp4", "--json", "--dry-run", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ self.assertIn("@fps", d["error"]["message"])
+ ch.write_text("00:00:01:00@30 Intro\n", encoding="utf-8")
+ script("metadata.py", self.src, "--chapters", ch, "-o", OUT / "tc_md.mp4", "--json", "--dry-run")
+ d = json.loads(script("multicam.py", self.src, self.src, "--switch", "0-1:xx:0", "-o", OUT / "tc_mc.mp4", "--json", "--dry-run", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ self.assertIn("@fps", d["error"]["message"])
+ d = json.loads(script("speedramp.py", self.src, "--segment", "0-1:xx:2", "-o", OUT / "tc_sr.mp4", "--json", "--dry-run", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ self.assertIn("@fps", d["error"]["message"])
+
+ def test_vfr_is_conformed_to_cfr_on_cut_and_fit(self):
+ out = OUT / "vfr_cut.mp4"
+ proc = script("cut.py", self.vfr, "--start", "2", "--end", "6", "-o", out)
+ self.assertIn("variable-frame-rate", proc.stderr)
+ m = probe(str(out))
+ self.assertFalse(m["video"]["variable_frame_rate_suspected"])
+ self.assertClose(m["duration"], 4.0, 0.2)
+ out2 = OUT / "vfr_fit.mp4"
+ script("fit.py", self.vfr, "--fps", "30", "--aspect", "1:1", "-o", out2)
+ m2 = probe(str(out2))
+ self.assertClose(m2["video"]["fps"], 30.0, 0.05)
+ self.assertFalse(m2["video"]["variable_frame_rate_suspected"])
+
+ def test_rotated_source_uses_display_orientation(self):
+ out = OUT / "rot_fit.mp4"
+ script("fit.py", self.rot, "--aspect", "9:16", "--fit", "pad", "--width", "540", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (540, 960))
+ self.assertEqual(m["video"]["rotation"], 0)
+
+ def test_fit_smooth_slow_motion_blend(self):
+ out = OUT / "slow.mp4"
+ script("fit.py", self.src, "--duration", "18", "--smooth", "blend", "--preset", "veryfast", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 18.0, 0.2)
+ self.assertClose(m["video"]["fps"], 30.0, 0.05, "frame rate preserved while slowing down")
+
+ def test_silence_removal(self):
+ gappy = OUT / "gappy.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*gt(sin(2*PI*0.25*t)\\,0)':s=48000",
+ "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30", "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", gappy)
+ data = json.loads(script("silence.py", gappy, "--list", "--json").stdout)
+ self.assertEqual(len(data["silences"]), 3)
+ self.assertNotIn("hint", data, "a hit needs no hint")
+ # a track with nothing under the threshold says what the floor is and which flag to change,
+ # instead of a bare "0 silences" that sends an agent off to raw ffmpeg (evals iteration 5, finding 1)
+ tone = OUT / "tone.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000",
+ "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30", "-t", "4", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", tone)
+ none = json.loads(script("silence.py", tone, "--list", "--json").stdout)
+ self.assertEqual(none["silences"], [])
+ self.assertIn("--threshold", none["hint"])
+ self.assertIn("mean level", none["hint"])
+ self.assertClose(data["removed_seconds"], 5.25, 0.3)
+ out = OUT / "tight.mp4"
+ edl = OUT / "keep.txt"
+ script("silence.py", gappy, "--preset", "veryfast", "--edl", edl, "-o", out)
+ self.assertClose(probe(str(out))["duration"], 6.75, 0.3)
+ self.assertEqual(len(edl.read_text().strip().splitlines()), 3)
+ # the EDL feeds cut.py --segments directly
+ segs = ",".join(edl.read_text().split())
+ out2 = OUT / "tight_via_cut.mp4"
+ script("cut.py", gappy, "--segments", segs, "--accurate", "--preset", "veryfast", "-o", out2)
+ self.assertClose(probe(str(out2))["duration"], 6.75, 0.4)
+
+ def test_silence_on_wav_input_keeps_pcm_not_forced_aac(self):
+ """silence.py's final ffmpeg command used to unconditionally append aac_args() (-c:a aac)
+ regardless of the output container. That's fine for .mp4/.m4a, but AAC cannot be muxed
+ into a .wav file -- so silence removal on any audio-only WAV input (a very ordinary case:
+ podcasts, voice memos, any --list workflow feeding straight into a WAV pipeline) crashed
+ ffmpeg outright, whether or not -o was given explicitly. Verify a WAV input still produces
+ a valid, playable WAV output (PCM), not a codec/container mismatch crash."""
+ wav_in = OUT / "silence_wav_in.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*gt(sin(2*PI*0.25*t)\\,0)':s=48000",
+ "-t", "6", wav_in)
+ proc = script("silence.py", wav_in)
+ out = Path(proc.stdout.strip())
+ self.assertEqual(out.suffix, ".wav")
+ m = probe(str(out))
+ self.assertTrue(m["audio"]["codec"].startswith("pcm"), f"WAV output must stay PCM, got {m['audio']['codec']}")
+
+ def test_join_with_transition_normalises_mismatched_clips(self):
+ out = OUT / "joined.mp4"
+ # 720p 30fps stereo + rotated portrait + 640x360 mono clip without audio
+ silent = OUT / "silent.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=25", "-t", "4", "-c:v", "libx264", "-preset", "veryfast", silent)
+ script("join.py", self.src, self.rot, silent, "--transition", "fadeblack", "--duration", "0.5", "--preset", "veryfast", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
+ self.assertClose(m["video"]["fps"], 30.0, 0.05)
+ self.assertEqual(m["audio"]["channels"], 2)
+ self.assertClose(m["duration"], 12 + 6 + 4 - 1.0, 0.3)
+ out2 = OUT / "joined_cut.mp4"
+ script("join.py", self.src, silent, "--transition", "none", "--preset", "veryfast", "-o", out2)
+ self.assertClose(probe(str(out2))["duration"], 16.0, 0.3)
+ script("join.py", self.src, expect_fail=True)
+
+ def test_join_two_or_more_audio_less_clips(self):
+ """Every no-audio clip gets a synthetic silent audio track added as an extra ffmpeg input (join.py
+ builds this itself, not this test's fixtures) -- `idx` must be this ffmpeg input's actual position
+ (n + how many synthetic inputs were already added), not `n + len(extra_inputs)` (the six argv tokens
+ each synthetic input contributes, not a count of inputs). With exactly one no-audio clip both counts
+ happen to agree; a real multi-camera join where every clip lacked audio is what caught the divergence
+ starting from the second one -- ffmpeg refused with "Invalid file index" naming an input far past the
+ real count, since the miscomputed index grew by 6 (not 1) per extra no-audio clip."""
+ silent_a = OUT / "silent_a.mp4"
+ silent_b = OUT / "silent_b.mp4"
+ silent_c = OUT / "silent_c.mp4"
+ for out, size in ((silent_a, "640x360"), (silent_b, "480x270"), (silent_c, "960x540")):
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", f"testsrc2=size={size}:rate=25", "-t", "3", "-c:v", "libx264", "-preset", "veryfast", out)
+ out = OUT / "joined_all_silent.mp4"
+ script("join.py", silent_a, silent_b, silent_c, "--transition", "none", "--preset", "veryfast", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 9.0, 0.3)
+ self.assertEqual(m["audio"]["channels"], 2, "every clip's missing track became silent stereo, not a dropped audio stream")
+ # mixed: audio-bearing clip first, then two without -- exercises the same off-by-more-than-one index
+ # for the second and third synthetic input regardless of which position the real audio clip sits in
+ out2 = OUT / "joined_mixed_silent.mp4"
+ script("join.py", self.src, silent_a, silent_b, "--transition", "none", "--preset", "veryfast", "-o", out2)
+ self.assertClose(probe(str(out2))["duration"], 12 + 3 + 3, 0.3)
+
+ def test_progress_and_fast_flags(self):
+ out = OUT / "prog.mp4"
+ proc = script("fit.py", self.src, "--duration", "6", "--fast", "--progress", "-o", out)
+ self.assertIn("%", proc.stderr)
+ self.assertIn("-preset veryfast", proc.stderr, "--fast overrides the preset")
+ self.assertClose(probe(str(out))["duration"], 6.0, 0.2)
+
+ # ---------------------------------------------------------------- v0.5: check / scenes / render
+ def test_codec_and_quality_resolve_in_one_place(self):
+ """1.8 (issue #189 B pre-shipped): --codec / --quality on every re-encoding tool, resolved by
+ encoder_args(). hevc on SDR is 8-bit BT.709 HEVC; prores needs a .mov; h264 refuses HDR;
+ --quality is the CRF; export keeps its presets; without --codec nothing changes."""
+ sys.path.insert(0, str(SCRIPTS))
+ try:
+ import _common
+ finally:
+ sys.path.pop(0)
+ out = OUT / "codec_hevc.mp4"
+ d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "hevc", "--quality", "30", "-o", out, "--fast", "--json", "--overwrite").stdout)
+ self.assertEqual(d["status"], "completed")
+ m = probe(str(out))
+ self.assertEqual(m["video"]["codec"], "hevc")
+ self.assertIn("yuv420p", m["video"].get("pix_fmt", "yuv420p"))
+ self.assertTrue(any("-crf 30" in c for c in d["commands"]), d["commands"])
+ # prores wants a .mov: .mp4 is refused before ffmpeg runs, .mov works
+ d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "prores", "-o", OUT / "codec_prores.mp4", "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ self.assertIn(".mov", d["error"]["hint"])
+ mov = OUT / "codec_prores.mov"
+ script("fit.py", self.src, "--width", "320", "--codec", "prores", "-o", mov, "--fast", "--json", "--overwrite")
+ self.assertEqual(probe(str(mov))["video"]["codec"], "prores")
+ # h264 cannot carry HDR; hevc keeps it
+ d = json.loads(script("fit.py", self.hdr, "--width", "320", "--codec", "h264", "-o", OUT / "codec_hdr_h264.mp4", "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ self.assertIn("to-sdr", d["error"]["hint"])
+ hdr_out = OUT / "codec_hdr_hevc.mp4"
+ script("fit.py", self.hdr, "--width", "320", "--codec", "hevc", "-o", hdr_out, "--fast", "--json", "--overwrite")
+ self.assertTrue(probe(str(hdr_out))["video"]["hdr"])
+ # av1 when the build has an encoder, a missing_tool refusal otherwise
+ av1 = OUT / "codec_av1.mp4"
+ proc = script("fit.py", self.src, "--width", "320", "--codec", "av1", "-o", av1, "--fast", "--json", "--overwrite", expect_fail=not (_common.ffmpeg_encoders() & {"libsvtav1", "libaom-av1"}))
+ d = json.loads(proc.stdout)
+ if d["status"] == "completed":
+ self.assertEqual(probe(str(av1))["video"]["codec"], "av1")
+ else:
+ self.assertEqual(d["error"]["kind"], "missing_tool")
+ # --quality bounds follow the codec; export refuses --codec
+ d = json.loads(script("fit.py", self.src, "--width", "320", "--quality", "60", "-o", out, "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ proc = script("export.py", self.src, "--preset", "x", "--codec", "hevc", "-o", OUT / "codec_export.mp4", "--json", expect_fail=True)
+ self.assertIn("--codec", proc.stderr) # argparse: the preset decides, the flag is not offered (review 7)
+ self.assertNotIn("--codec", script("export.py", "--help").stdout)
+ # review 7: prores without -o would have failed inside ffmpeg (mp4 cannot hold it)
+ d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "prores", "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ self.assertIn("-o NAME.mov", d["error"]["hint"])
+ # review 7: cut's lossless path used to keep the source codec under --codec
+ cutout = OUT / "codec_cut.mp4"
+ script("cut.py", self.src, "--start", "0", "--end", "2", "--codec", "hevc", "-o", cutout, "--fast", "--json", "--overwrite")
+ self.assertEqual(probe(str(cutout))["video"]["codec"], "hevc")
+ # review 7: waveform.py built its own x264 line and ignored the flag
+ wf = OUT / "codec_wave.mp4"
+ script("waveform.py", self.src, "--codec", "hevc", "-o", wf, "--fast", "--json", "--overwrite") # source.mp4: c_tone.wav is a test_contract fixture
+ self.assertEqual(probe(str(wf))["video"]["codec"], "hevc")
+ # review 7: the av1 bound is named in the --crf message, and HDR hevc --quality 51 does not overflow
+ d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "av1", "--crf", "70", "-o", out, "--json", expect_fail=True).stdout)
+ self.assertIn("63", d["error"]["message"])
+ sys.path.insert(0, str(SCRIPTS))
+ try:
+ import _common as c
+ finally:
+ sys.path.pop(0)
+ args = c.encoder_args("hevc", 51, "medium", {"video": {"hdr": True, "color_transfer": "smpte2084"}})
+ self.assertEqual(args[args.index("-crf") + 1], "51")
+ self.assertNotIn("-colorspace", c.encoder_args("hevc", 18, "medium", None, keep_bt709=False))
+ # the contract lists each --codec encoder once per tool
+ spec = json.loads(script("_contract.py", "--json").stdout)
+ fit_caps = [o["capability"] for o in next(t for t in spec["tools"] if t["name"] == "fit")["capabilities"]["optional"]]
+ self.assertEqual(len(fit_caps), len(set(fit_caps)), fit_caps)
+ self.assertNotIn("codec", next(t for t in spec["tools"] if t["name"] == "export")["input_schema"]["properties"])
+ # no --codec: the old default line, byte for byte
+ d = json.loads(script("fit.py", self.src, "--width", "320", "-o", out, "--fast", "--json", "--overwrite").stdout)
+ self.assertTrue(any("libx264" in c for c in d["commands"]))
+ # every tool that declares --crf now advertises the two flags
+ for name in ("cut", "caption", "overlay", "color", "join", "proxy"):
+ h = script(f"{name}.py", "--help").stdout
+ self.assertIn("--codec", h, name)
+ self.assertIn("--quality", h, name)
+
+ def test_join_width_keeps_aspect(self):
+ out = OUT / "join_w.mp4"
+ script("join.py", self.src, self.src, "--transition", "none", "--width", "640", "--fast", "-o", out)
+ m = probe(str(out))["video"]
+ self.assertEqual((m["width"], m["height"]), (640, 360))
+
+ def test_fit_blur_keeps_the_whole_picture_on_a_blurred_border(self):
+ """--fit blur: the target aspect, nothing cropped, borders that carry a dimmed copy of the
+ picture rather than black, and a centre band that is still the scaled source."""
+ out = OUT / "fit_blur.mp4"
+ script("fit.py", self.src, "--duration", "3", "--aspect", "9:16", "--fit", "blur",
+ "--width", "360", "--fast", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (360, 640))
+ top_avg, top_spread = self._region_stats(out, "iw:80:0:0")
+ self.assertGreater(top_avg, 10, f"blurred border is black: {top_avg}")
+ self.assertGreater(top_spread, 8, f"blurred border is flat: {top_spread}")
+ # the centre band is the fitted source: 360x202 sits at y=(640-202)/2
+ ref = OUT / "fit_blur_ref.mp4"
+ script("fit.py", self.src, "--duration", "3", "--width", "360", "--fast", "-o", ref)
+ mid_avg, _ = self._region_stats(out, "iw:180:0:230")
+ ref_avg, _ = self._region_stats(ref, "iw:180:0:10")
+ self.assertClose(mid_avg, ref_avg, 12, "the centre of a blur fit is the scaled source")
+ # the darkening is an eq on code values: a -15 % perceptual dim on SDR, something else on
+ # PQ/HLG, so an HDR source keeps its background at its own levels (review 12)
+ sdr_plan = json.loads(script("fit.py", self.src, "--aspect", "9:16", "--fit", "blur",
+ "--dry-run", "--json", "-o", str(OUT / "blur_sdr.mp4")).stdout)
+ hdr_plan = json.loads(script("fit.py", self.hdr, "--aspect", "9:16", "--fit", "blur",
+ "--dry-run", "--json", "-o", str(OUT / "blur_hdr.mp4")).stdout)
+ self.assertTrue(any("eq=brightness" in c for c in sdr_plan["commands"]))
+ self.assertTrue(any("boxblur" in c for c in hdr_plan["commands"]))
+ self.assertFalse(any("eq=brightness" in c for c in hdr_plan["commands"]),
+ "an HDR source must not be dimmed by an SDR-shaped eq")
+
+ def test_join_audio_only_inputs(self):
+ """WAV + M4A + MP3 of different rates and channel counts join as audio; video containers and mixed inputs are refused."""
+ st = OUT / "j_stereo44.m4a"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=1000:sample_rate=44100", "-t", "3", "-ac", "2", "-c:a", "aac", st)
+ mp3 = OUT / "j_mono.mp3"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=500:sample_rate=48000", "-t", "3", "-c:a", "libmp3lame", mp3)
+ mic_dur = probe(str(self.mic))["duration"]
+ # crossfade -> flac: rate of the first clip, widest layout
+ out = OUT / "j_audio.flac"
+ data = json.loads(script("join.py", self.mic, st, mp3, "-o", out, "--json").stdout)
+ self.assertEqual(data["mode"], "audio")
+ self.assertEqual((data["sample_rate"], data["channels"]), (48000, 2))
+ self.assertIsNone(data["probe"]["video"])
+ self.assertEqual(data["probe"]["audio"]["codec"], "flac")
+ self.assertClose(data["probe"]["duration"], mic_dur + 3 + 3 - 2 * 0.5, 0.15)
+ # butt join -> wav, explicit rate and channels
+ out2 = OUT / "j_audio.wav"
+ data = json.loads(script("join.py", st, mp3, "--transition", "none", "--sample-rate", "44100", "--channels", "1", "-o", out2, "--json").stdout)
+ self.assertEqual(self._samples(out2)[:2], ("pcm_s16le", 44100))
+ self.assertEqual(data["probe"]["audio"]["channels"], 1)
+ self.assertClose(data["probe"]["duration"], 6.0, 0.1)
+ # refusals are input errors, before ffmpeg runs
+ proc = script("join.py", self.mic, mp3, "-o", OUT / "j_audio.mp4", "--json", expect_fail=True)
+ self.assertIn("audio extension", json.loads(proc.stdout)["error"]["message"])
+ self.assertNotIn("ffmpeg ", proc.stderr.replace("/usr/bin/", ""), "refused before ffmpeg ran")
+ proc = script("join.py", self.src, self.mic, "-o", OUT / "j_mixed.mp4", "--json", expect_fail=True)
+ self.assertIn("has no video stream", proc.stderr)
+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
+ # dry-run plans the audio join and writes nothing
+ planned = OUT / "j_dry.wav"
+ data = json.loads(script("join.py", self.mic, mp3, "-o", planned, "--dry-run", "--json").stdout)
+ self.assertTrue(data["dry_run"])
+ self.assertIn("acrossfade", data["commands"][0])
+ self.assertFalse(planned.exists())
+
+ def test_cut_audio_precision_is_measured(self):
+ """Stream copy is packet-accurate, --accurate is sample-exact on PCM/FLAC, lossy outputs say codec_frame."""
+ start, end = 1.2345, 2.3456
+ want = round((end - start) * 48000) # 53333 samples
+ # WAV copy: packet boundary, reported as such, within a few ms
+ cw = OUT / "prec_copy.wav"
+ data = json.loads(script("cut.py", self.mic, "--start", str(start), "--end", str(end), "-o", cw, "--json").stdout)
+ self.assertEqual(data["precision"], "packet")
+ self.assertFalse(data["reencoded"])
+ self.assertLess(abs(data["duration_error_ms"]), 50)
+ self.assertEqual(self._samples(cw)[0], "pcm_s16le")
+ # WAV --accurate: exactly the requested number of samples
+ ca = OUT / "prec_acc.wav"
+ data = json.loads(script("cut.py", self.mic, "--start", str(start), "--end", str(end), "--accurate", "-o", ca, "--json").stdout)
+ self.assertEqual(data["precision"], "sample")
+ self.assertEqual(self._samples(ca), ("pcm_s16le", 48000, want))
+ self.assertLess(abs(data["duration_error_ms"]), 0.05)
+ # 44.1 kHz FLAC, --accurate: exact at its own rate
+ flac = OUT / "prec_44.flac"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=1000:sample_rate=44100", "-t", "3", "-c:a", "flac", flac)
+ fa = OUT / "prec_44_cut.flac"
+ data = json.loads(script("cut.py", flac, "--start", "0.5", "--end", "1.7", "--accurate", "-o", fa, "--json").stdout)
+ self.assertEqual(data["precision"], "sample")
+ self.assertEqual(self._samples(fa), ("flac", 44100, round(1.2 * 44100)))
+ # compressed source (AAC in mp4) decoded to PCM with --accurate: exact; to AAC: codec_frame, not "sample"
+ ma = OUT / "prec_from_aac.wav"
+ data = json.loads(script("cut.py", self.src, "--start", str(start), "--end", str(end), "--accurate", "-o", ma, "--json").stdout)
+ self.assertEqual(data["precision"], "sample")
+ self.assertEqual(self._samples(ma)[2], want)
+ m4a = OUT / "prec_to_aac.m4a"
+ data = json.loads(script("cut.py", self.src, "--start", str(start), "--end", str(end), "--accurate", "-o", m4a, "--json").stdout)
+ self.assertEqual(data["precision"], "codec_frame")
+ self.assertEqual(self._samples(m4a)[0], "aac")
+ # video re-encode keeps reporting frame precision; a plain copy keeps packet
+ mp4 = OUT / "prec_video.mp4"
+ data = json.loads(script("cut.py", self.src, "--start", "1", "--end", "3", "--accurate", "--preset", "ultrafast", "-o", mp4, "--json").stdout)
+ self.assertEqual(data["precision"], "frame")
+ self.assertIsNotNone(data["probe"]["video"])
+
+ def test_crf_warns_once_as_a_deprecated_alias_of_quality(self):
+ """docs/contract.md, "Deprecation policy" step 1: the old spelling keeps working and says
+ what replaces it. argparse's own default (18) must stay silent."""
+ quiet = script("cut.py", self.src, "--start", "0", "--end", "1", "--dry-run", "-o", str(OUT / "crf_default.mp4"))
+ self.assertNotIn("--crf is deprecated", quiet.stderr)
+ warned = script("cut.py", self.src, "--start", "0", "--end", "1", "--crf", "20", "--dry-run", "-o", str(OUT / "crf_explicit.mp4"))
+ self.assertIn("--crf is deprecated", warned.stderr)
+ self.assertIn("--quality", warned.stderr)
+ helptext = " ".join(script("cut.py", "--help").stdout.split())
+ self.assertIn("(deprecated: use --quality)", helptext)
+
+ def test_json_brief_is_a_shorter_json_with_the_same_verdict(self):
+ """1.11.0 token diet: `--json-brief` is additive -- the same success document with the
+ probe summarised, the command lines counted and the per-step verification list dropped.
+ `--json` itself must be untouched, so both are run on the same edit and compared."""
+ full = json.loads(script("cut.py", self.src, "--start", "0", "--end", "2", "-o", str(OUT / "brief_full.mp4"), "--json").stdout)
+ brief = json.loads(script("cut.py", self.src, "--start", "0", "--end", "2", "-o", str(OUT / "brief_short.mp4"), "--json-brief").stdout)
+ self.assertEqual(set(full) - set(brief), {"probe", "verification"}, "only the bulky keys go")
+ self.assertEqual(set(brief) - set(full), {"summary"})
+ self.assertEqual(brief["status"], "completed")
+ self.assertEqual(brief["dry_run"], full["dry_run"])
+ self.assertEqual(brief["verified"], full["verified"])
+ self.assertNotIn("probe", brief)
+ self.assertNotIn("verification", brief)
+ self.assertEqual(brief["commands"], len(full["commands"]), "commands is the count, not the list")
+ summary = brief["summary"]
+ self.assertEqual(summary["width"], full["probe"]["video"]["width"])
+ self.assertEqual(summary["height"], full["probe"]["video"]["height"])
+ self.assertEqual(summary["vcodec"], full["probe"]["video"]["codec"])
+ self.assertEqual(summary["acodec"], full["probe"]["audio"]["codec"])
+ self.assertAlmostEqual(summary["duration_s"], full["probe"]["duration"], places=2)
+ for key in ("precision", "reencoded", "expected_duration"):
+ self.assertEqual(brief[key], full[key], f"{key}: the tool's own keys survive the diet")
+ self.assertLess(len(json.dumps(brief)), len(json.dumps(full)) / 2, "the point of the flag is fewer bytes")
+
+ def test_json_brief_failure_is_the_usual_failure_document(self):
+ """A failure must not be trimmed: die() prints the same document with or without the flag,
+ so a caller never loses the error kind, message or hint by asking for brevity."""
+ proc = script("cut.py", str(OUT / "does_not_exist.mp4"), "--start", "0", "--end", "1", "--json-brief", expect_fail=True)
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["status"], "failed")
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertTrue(doc["error"]["message"])
+ self.assertNotIn("summary", doc)
+
+
+if __name__ == "__main__":
+ unittest.main(verbosity=2)
diff --git a/tests/test_orchestration.py b/tests/test_orchestration.py
new file mode 100644
index 0000000..fb7d398
--- /dev/null
+++ b/tests/test_orchestration.py
@@ -0,0 +1,935 @@
+#!/usr/bin/env python3
+"""End-to-end tests for render, batch and multicam, plus the toolkit-wide invariants every script has to satisfy.
+
+ python3 tests/test_orchestration.py # this group alone
+ python3 tests/test_all.py # every group
+"""
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _fixtures import MediaFixtures, OUT, ROOT, SCRIPTS, TONES, _no_fontconfig, script, sh # noqa: E402
+from _common import font_for_script, probe, shell_quote # noqa: E402
+
+
+class OrchestrationTests(MediaFixtures):
+ """Render, batch and multicam, plus the toolkit-wide invariants every script has to satisfy."""
+
+ def test_zero_or_negative_fps_refused_across_every_cfr_script(self):
+ """--fps flows straight into cfr_args(meta, args.fps) / a `fps or source_fps or 30.0`
+ fallback in several scripts without ever being validated first. `0` is falsy in Python, so
+ `--fps 0` used to be silently discarded and fall back to the source's own fps (or 30) --
+ the tool claims to force a specific constant frame rate and quietly does something else
+ instead. A negative value is truthy, so `--fps -5` passed straight through to ffmpeg's
+ `-r`/`fps=` filter option, which rejects it -- an unhelpful ffmpeg-level crash instead of a
+ clear error naming --fps. Verify every affected script now refuses both up front."""
+ for name, extra in (
+ ("crop.py", ["--x", "0", "--y", "0", "--width", "32", "--height", "32"]),
+ ("denoise.py", []),
+ ("redact.py", ["--x", "0", "--y", "0", "--width", "32", "--height", "32"]),
+ ("straighten.py", ["--degrees", "3"]),
+ ("sphere.py", []),
+ ("join.py", []), # fps is validated before the "give >= 2 clips" check, one input is enough
+ ("multicam.py", []), # fps is validated before the "give >= 2 inputs" check too
+ ):
+ for bad in ("0", "-5"):
+ proc = script(name, self.src, *extra, "--fps", bad, expect_fail=True)
+ self.assertIn("--fps", proc.stderr, f"{name} --fps {bad} should name --fps in its error")
+
+ def test_a_brand_file_without_a_font_does_not_switch_font_by_script_off(self):
+ """BRAND_DEFAULTS always supplies a font, so the merged brand document cannot say whether
+ the CALLER chose one: a brand.json that only sets colours must still resolve a font by
+ script (and still refuse when nothing covers it)."""
+ if _no_fontconfig():
+ self.skipTest("no fc-list on this machine")
+ if font_for_script("ko") is None:
+ self.skipTest("this machine has no font covering ko")
+ brand = OUT / "brand_no_font.json"
+ brand.write_text(json.dumps({"colors": {"text": "FFFFFF"}}), encoding="utf-8")
+ cues = OUT / "brand_ko.txt"
+ cues.write_text("0:00-0:03 안녕하세요\n", encoding="utf-8")
+ proc = script("caption.py", self._small(), "--text", cues, "--brand", brand,
+ "--animate", "none", "--fast", "-o", OUT / "brand_ko.mp4")
+ self.assertRegex(proc.stderr, r"(?m)^font: .+? \(covers ko\)")
+ self.assertNotIn("does not cover", proc.stderr)
+ stated = OUT / "brand_with_font.json"
+ stated.write_text(json.dumps({"font": "DejaVu Sans"}), encoding="utf-8")
+ proc2 = script("caption.py", self._small(), "--text", cues, "--brand", stated,
+ "--animate", "none", "--fast", "-o", OUT / "brand_ko2.mp4")
+ if shutil.which("fc-list"):
+ self.assertIn("does not cover", proc2.stderr, "a font the brand file itself states is kept")
+ else:
+ self.assertNotIn("does not cover", proc2.stderr, "no fontconfig: coverage is unknown, nothing is claimed")
+ self.assertNotIn("(covers ko)", proc2.stderr)
+
+ def test_render_audio_stems_and_chapters_stage(self):
+ """1.13: stems are a vocabulary over the flags that already exist, and the chapters stage
+ puts the markers in the file that ships (metadata.py, streams copied)."""
+ proj = OUT / "project_stems.json"
+ proj.write_text(json.dumps({
+ "output": "render_stems.mp4",
+ "clips": [{"src": "source.mp4"}],
+ "audio": {"music": "lavmic.wav", "effects": "lavmic.wav", "duck": True, "voice": "light",
+ "stems": {"dialogue": -2, "music": -18, "effects": -24}},
+ "export": {"preset": "youtube", "normalize": False},
+ "chapters": [{"at": "0:00", "title": "Intro"}, {"at": 3, "title": "Body"}],
+ }), encoding="utf-8")
+ data = json.loads(script("render.py", proj, "--dry-run", "--json").stdout)
+ graph = next(c for c in data["commands"] if "sidechaincompress" in c)
+ self.assertIn("volume=-2dB", graph, "stems.dialogue is the main track's gain")
+ self.assertIn("volume=-18dB", graph, "stems.music is the bed's level")
+ self.assertIn("volume=-24dB", graph, "stems.effects is the effects bed's level")
+ self.assertIn("highpass=f=80,acompressor=threshold=-18dB:ratio=2", graph, '"voice": "light" picks the light chain')
+ # the chapters stage is planned like every other stage: the dry run names the same
+ # metadata.py command against the same delivered file, and lists the stage. A plan that
+ # hides a stage is a plan the user cannot approve.
+ planned = json.loads(script("render.py", proj, "--dry-run", "--json").stdout)
+ real = json.loads(script("render.py", proj, "--fast", "--json").stdout)
+ self.assertIn("chapters", planned["stages"])
+ self.assertEqual(planned["stages"], real["stages"], "the plan lists the stages the run does")
+ for doc in (planned, real):
+ chapter_cmds = [c for c in doc["commands"] if "-map_chapters 1" in c]
+ self.assertEqual(len(chapter_cmds), 1, doc["stages"])
+ self.assertIn(str(OUT / "render_stems.mp4"), chapter_cmds[0], "planned against the delivered file")
+ data = real
+ written = probe(str(OUT / "render_stems.mp4")).get("chapters") or []
+ self.assertEqual([c["title"] for c in written], ["Intro", "Body"])
+ self.assertClose(written[1]["start"], 3.0, 0.05)
+ # a chapters file path works the same way
+ proj2 = OUT / "project_chapters_file.json"
+ (OUT / "render_chapters.txt").write_text("0:00 One\n0:05 Two\n", encoding="utf-8")
+ proj2.write_text(json.dumps({
+ "output": "render_chapters.mp4", "clips": [{"src": "source.mp4"}],
+ "export": {"preset": "youtube", "normalize": False}, "chapters": "render_chapters.txt",
+ }), encoding="utf-8")
+ script("render.py", proj2, "--fast", "--json")
+ self.assertEqual(len(probe(str(OUT / "render_chapters.mp4")).get("chapters") or []), 2)
+ # a stems level with no effects file, and a misspelled stem, are refusals by name
+ proj3 = OUT / "project_stems_bad.json"
+ proj3.write_text(json.dumps({"output": "render_stems_bad.mp4", "clips": [{"src": "source.mp4"}],
+ "audio": {"stems": {"effects": -20}}}), encoding="utf-8")
+ doc = json.loads(script("render.py", proj3, "--dry-run", "--json", expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("effects", doc["error"]["message"])
+ proj3.write_text(json.dumps({"output": "render_stems_bad.mp4", "clips": [{"src": "source.mp4"}],
+ "audio": {"stems": {"voice": -20}}}), encoding="utf-8")
+ doc = json.loads(script("render.py", proj3, "--dry-run", "--json", expect_fail=True).stdout)
+ self.assertIn("dialogue", doc["error"]["message"], "the nearest valid stem is named")
+ # a music level with no music file is refused the same way an effects level is
+ proj3.write_text(json.dumps({"output": "render_stems_bad.mp4", "clips": [{"src": "source.mp4"}],
+ "audio": {"stems": {"music": -18}}}), encoding="utf-8")
+ doc = json.loads(script("render.py", proj3, "--dry-run", "--json", expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("music", doc["error"]["message"])
+
+ def test_render_chapters_are_validated_before_any_stage_runs(self):
+ """1.13: every other project error is raised before the first ffmpeg call. A bad chapter
+ entry used to surface inside the last stage, after place_output had already delivered an
+ unchaptered file and reported the render as done."""
+ out = OUT / "render_bad_chapters.mp4"
+ proj = OUT / "project_bad_chapters.json"
+ for chapters, needle in (([{"title": "A"}], "at"), ([{"at": "0:00"}], "title"),
+ ("no_such_chapters.txt", "not found")):
+ if out.exists():
+ out.unlink()
+ proj.write_text(json.dumps({"output": "render_bad_chapters.mp4", "clips": [{"src": "source.mp4"}],
+ "export": {"preset": "youtube", "normalize": False},
+ "chapters": chapters}), encoding="utf-8")
+ doc = json.loads(script("render.py", proj, "--fast", "--json", expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input", chapters)
+ self.assertIn(needle, doc["error"]["message"], chapters)
+ self.assertEqual(doc.get("commands") or [], [], "refused before the first ffmpeg call")
+ self.assertFalse(out.exists(), "no half-done delivery is left behind")
+
+ def test_shell_quote_quotes_backslashes(self):
+ """CodeRabbit (#101): fixing the invalid-escape-sequence SyntaxWarning in shell_quote()'s
+ character set (a stray `\\` before an already-unescaped `;`) accidentally dropped a real,
+ load-bearing backslash from the quoting trigger set -- the original `\\;` literal, due to
+ Python keeping an unrecognised escape's backslash, actually matched on `\\` OR `;`, not just
+ `;`. Without a backslash trigger, a Windows path like `C:\\media\\clip.mp4` would render
+ unquoted in --dry-run/--json command output. Assert the fixed version still quotes it."""
+ self.assertEqual(shell_quote("C:\\media\\clip.mp4"), "'C:\\media\\clip.mp4'")
+ self.assertEqual(shell_quote("plain.mp4"), "plain.mp4")
+ self.assertEqual(shell_quote("has;semicolon"), "'has;semicolon'")
+
+ def test_dry_run_and_json_on_every_script(self):
+ cases = [
+ ("cut.py", [self.src, "--start", "1", "--end", "3"]),
+ ("fit.py", [self.src, "--duration", "6"]),
+ ("caption.py", [self.src, "--srt", OUT / "cues.srt"]),
+ ("overlay.py", [self.src, "--image", self.logo]),
+ ("export.py", [self.src, "--preset", "x"]),
+ ("color.py", [self.src, "--retag", "bt709"]),
+ ("audio.py", [self.src, "--denoise"]),
+ ("join.py", [self.src, self.src]),
+ ]
+ if not (OUT / "cues.srt").exists():
+ script("caption.py", "--text", self.cues, "--write-srt", OUT / "cues.srt")
+ for name, argv in cases:
+ out = OUT / f"dry_{name}.mp4"
+ proc = script(name, *argv, "-o", out, "--dry-run", "--json")
+ self.assertFalse(out.exists(), f"{name} wrote a file in --dry-run")
+ data = json.loads(proc.stdout)
+ self.assertTrue(data["dry_run"], name)
+ self.assertTrue(data["commands"] and all("ffmpeg" in c for c in data["commands"]), name)
+ self.assertEqual(data["output"], str(out), name)
+ # --json on a real run includes the probe of the output
+ out = OUT / "json_cut.mp4"
+ data = json.loads(script("cut.py", self.src, "--start", "0", "--end", "2", "-o", out, "--json").stdout)
+ self.assertClose(data["probe"]["duration"], 2.0, 0.6)
+
+ def test_multicam_offsets_and_switch(self):
+ camB = OUT / "camB.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1.5", "-i", self.src, "-vf", "hue=h=90", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", camB)
+ data = json.loads(script("multicam.py", self.src, camB, self.mic, "--offsets-only", "--json").stdout)
+ self.assertClose(data["offsets_seconds"][1], 1.5, 0.05)
+ self.assertClose(data["offsets_seconds"][2], 2.5, 0.05)
+ out = OUT / "mc.mp4"
+ data = json.loads(script("multicam.py", self.src, camB, self.mic, "--audio", "2", "--switch", "0-3:0,3-6:1,6-9:0", "--fast", "-o", out, "--json").stdout)
+ self.assertEqual(len(data["cuts"]), 4, "three named ranges plus the gap-fill to the end")
+ m = probe(str(out))
+ self.assertClose(m["duration"], 12.0, 0.2)
+ self.assertEqual(m["audio"]["channels"], 2)
+ # camB is hue-shifted: a frame at 4.5 s (camera 1) must differ from one at 2 s (camera 0)
+ script("look.py", out, "--at", "2", "--at", "4.5", "-o", OUT / "mcf")
+ self.assertNotEqual((OUT / "mcf_2.000s.png").read_bytes()[100:2000], (OUT / "mcf_4.500s.png").read_bytes()[100:2000])
+ auto = OUT / "mc_auto.mp4"
+ script("multicam.py", self.src, camB, "--auto", "4", "--fast", "-o", auto)
+ self.assertClose(probe(str(auto))["duration"], 12.0, 0.2)
+ script("multicam.py", self.src, camB, "--switch", "0-3:5", expect_fail=True)
+
+ def test_multicam_fix_drift_trims_before_resample_not_after(self):
+ """--fix-drift's audio path computes a_start (an atrim start point) in the source's own
+ pre-correction time axis, but the filter chain used to apply asetrate/aresample (the drift
+ correction) *before* atrim -- so the trim landed on the already-rescaled timeline instead
+ of the raw one it was computed for, same bug class as sync.py already avoids by seeking
+ with -ss (an input-level, pre-filter operation) before its own drift_af. Build a camera
+ whose audio started before the reference (offsets[a] < 0, so a_start > 0) and also drifts
+ (ratios[a] != 1), then check the constructed [<audio input>:a] filter chain: atrim=start=
+ must appear before asetrate, mirroring sync.py's ordering."""
+ base = OUT / "mc_drift_base.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000", "-t", "200", "-c:a", "pcm_s16le", base)
+ ref_audio = OUT / "mc_drift_ref.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1.2", "-i", base, "-c:a", "pcm_s16le", ref_audio)
+ camB = OUT / "mc_drift_camB.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", base, "-af", "asetrate=48000*0.9995,aresample=48000", "-c:a", "pcm_s16le", camB)
+ cam0 = OUT / "mc_drift_cam0.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc=size=160x120:rate=15", "-i", ref_audio, "-c:v", "libx264", "-preset", "ultrafast", "-c:a", "aac", "-shortest", cam0)
+
+ data = json.loads(script("multicam.py", cam0, camB, "--audio", "1", "--switch", "0-198:0", "--fix-drift", "--max-offset", "5", "--fast", "-o", OUT / "mc_drift_out.mp4", "--json").stdout)
+ self.assertLess(data["offsets_seconds"][1], 0, "camera 1 must have started before the reference for a_start > 0 to be exercised")
+ self.assertNotEqual(data["drift_ppm"][1], 0.0, "drift must actually be detected for asetrate/aresample to be in the chain")
+ audio_chain = data["commands"][0].split("[1:a]", 1)[1]
+ self.assertLess(audio_chain.index("atrim=start="), audio_chain.index("asetrate="),
+ "atrim=start= (in the pre-correction time axis) must run before asetrate/aresample rescale that axis")
+
+ def test_multicam_negative_auto_interval_refused_not_infinite_loop(self):
+ """--auto builds cuts with `while t < ref_dur: ... t += args.auto` -- `elif args.auto:` is
+ only false for exactly 0, so a negative value used to pass that check and enter the loop
+ with t decreasing every iteration, meaning t < ref_dur never becomes false: the process
+ hangs forever instead of erroring on invalid input. Must be refused up front instead."""
+ script("multicam.py", self.src, self.src, "--auto", "-1", "--fast", "-o", OUT / "mc_auto_neg.mp4", expect_fail=True)
+
+ def test_multicam_warns_on_a_camera_with_no_shared_audio_event(self):
+ """A camera whose audio has nothing in common with the reference must not align silently."""
+ unrelated = OUT / "camC_unrelated.mp4"
+ # a flat-envelope tone: nothing for the envelope-based cross-correlation to lock onto,
+ # unlike the reference's gated tones -- unrelated in the way a different room's constant hum would be
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30",
+ "-f", "lavfi", "-i", "sine=frequency=233:sample_rate=48000", "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", unrelated)
+ proc = script("multicam.py", self.src, unrelated, "--offsets-only", "--json")
+ data = json.loads(proc.stdout)
+ self.assertLess(data["confidence"][1], 0.1)
+ self.assertIn("low correlation confidence", proc.stderr)
+
+ def test_render_export_normalize_forwards_the_flag(self):
+ proj = OUT / "project_normalize.json"
+ proj.write_text(json.dumps({
+ "output": "render_normalize.mp4",
+ "clips": [{"src": "source.mp4"}],
+ "export": {"preset": "x", "normalize": True},
+ "check": {"platform": "x"},
+ }), encoding="utf-8")
+ data = json.loads(script("render.py", proj, "--fast", "--json").stdout)
+ self.assertTrue(data["check"]["ok"], data["check"])
+ rows = {r["check"]: r["status"] for r in data["check"]["checks"]}
+ self.assertEqual(rows["loudness"], "PASS", "the -9 LUFS source (whole clip: a 2 s slice happens to sit at -13 LUFS) only passes when export ran --normalize")
+ # 1.9: a platform preset with no loudness stage normalises by default; false opts out
+ proj.write_text(json.dumps({
+ "output": "render_normalize_default.mp4",
+ "clips": [{"src": "source.mp4"}],
+ "export": {"preset": "x"},
+ "check": {"platform": "x"},
+ }), encoding="utf-8")
+ data = json.loads(script("render.py", proj, "--fast", "--json").stdout)
+ self.assertEqual({r["check"]: r["status"] for r in data["check"]["checks"]}["loudness"], "PASS")
+ proj.write_text(json.dumps({
+ "output": "render_normalize_off.mp4",
+ "clips": [{"src": "source.mp4"}],
+ "export": {"preset": "x", "normalize": False},
+ "check": {"platform": "x"},
+ }), encoding="utf-8")
+ data = json.loads(script("render.py", proj, "--fast", "--json", expect_fail=True).stdout)
+ self.assertEqual({r["check"]: r["status"] for r in data["check"]["checks"]}["loudness"], "FAIL")
+
+ def test_render_project(self):
+ proj = OUT / "project.json"
+ proj.write_text(json.dumps({
+ "output": "render_final.mp4",
+ "frame": {"aspect": "9:16", "width": 720, "fps": 30},
+ "clips": [{"src": "source.mp4", "in": "0:01", "out": "0:05"}, {"src": "source.mp4", "in": 6, "out": 10, "speed": 1.25}],
+ "transition": {"type": "fade", "duration": 0.5},
+ "captions": {"text": "cues.txt", "animate": "pop", "karaoke": True, "size": 26},
+ "overlays": [{"text": "render test", "position": "top-left", "start": 0.5, "end": 3, "fade": 0.3, "box": True}],
+ "audio": {"music": "long_ref.wav", "music_volume": -20, "duck": True, "fade_out": 1},
+ "loudness": {"lufs": -14, "tp": -1},
+ "export": {"preset": "reels"},
+ "check": {"platform": "reels"},
+ }), encoding="utf-8")
+ if not (OUT / "cues.txt").exists():
+ (OUT / "cues.txt").write_text("0:00-0:03 Hello world\n", encoding="utf-8")
+ (OUT / "render_final.mp4").unlink(missing_ok=True)
+ plan = json.loads(script("render.py", proj, "--dry-run", "--json").stdout)
+ self.assertTrue(plan["dry_run"])
+ self.assertFalse((OUT / "render_final.mp4").exists())
+ data = json.loads(script("render.py", proj, "--fast", "--json").stdout)
+ self.assertEqual(data["stages"], ["clips", "join", "fit", "captions", "overlays", "audio", "loudness", "export", "check"])
+ self.assertTrue(data["check"]["ok"], data["check"])
+ m = probe(str(OUT / "render_final.mp4"))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1080, 1920))
+ self.assertClose(m["duration"], 4 + 3.2 - 0.5, 0.4)
+ self.assertEqual(list(OUT.glob("render_final_work*")), [], "work dir removed when not kept")
+ init = OUT / "init.json"
+ script("render.py", "--init", init)
+ self.assertIn("clips", json.loads(init.read_text()))
+ # --stop-after keeps the intermediate
+ out = json.loads(script("render.py", proj, "--fast", "--stop-after", "join", "--work", OUT / "rw", "--json").stdout)
+ self.assertEqual(out["stages"], ["clips", "join"])
+ self.assertTrue(Path(out["output"]).exists())
+
+ def test_render_every_stage_flag_and_every_refusal(self):
+ """render.py's stage branches that test_render_project does not take (silence, captions
+ from srt/ass, graphics, image and logo overlays, audio replace/loop/stereo/mono/downmix,
+ export fit/crf, brand forwarding, the no-export copy path) and its refusals (no project,
+ unreadable project, empty clips, captions/graphics/overlays without their required key,
+ a child script failing) were untested (#147). --dry-run drives every argv-building branch
+ without encoding; the copy path and the child failure run for real on a 2 s clip."""
+ srt = OUT / "render_full.srt"
+ srt.write_text("1\n00:00:00,000 --> 00:00:01,500\nHello\n\n", encoding="utf-8")
+ ass = OUT / "render_full.ass"
+ logo = OUT / "render_full_logo.png"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=red:s=64x64:d=1", "-frames:v", "1", logo)
+ brand = OUT / "render_full_brand.json"
+ brand.write_text(json.dumps({"logo": logo.name, "logo_position": "top-right", "colors": {"primary": "FF6A00", "text": "FFFFFF"}}), encoding="utf-8")
+ full = {
+ "output": "render_full.mp4",
+ "brand": brand.name,
+ "clips": [{"src": "source.mp4", "in": 0, "out": 2}, {"src": "source.mp4", "in": 2, "out": 4}],
+ "frame": {"width": 640, "height": 360, "fps": 25},
+ "fit": {"duration": 3.5, "method": "trim"},
+ "captions": {"srt": srt.name, "font": "DejaVu Sans", "position": "top", "bold": True, "box": True},
+ "graphics": [{"template": "lower-third", "name": "Ada", "title": "Analyst", "start": 0, "end": 2},
+ {"template": "title", "title": "T", "subtitle": "S", "start": 0, "end": 1, "position": "top-left"}],
+ "overlays": [{"image": logo.name, "position": "bottom-right", "opacity": 0.5, "scale": 80},
+ {"logo": True, "start": 0, "end": 1},
+ {"text": "txt", "font_size": 24, "margin": 12, "box": True}],
+ "audio": {"replace": "long_ref.wav", "music_volume": -12, "gain": 1, "music_loop": True, "stereo": True, "denoise": True},
+ "loudness": {"lufs": -16},
+ "export": {"preset": "youtube", "fit": "pad", "crf": 20},
+ }
+ proj = OUT / "render_full.json"
+ proj.write_text(json.dumps(full), encoding="utf-8")
+ proc = script("render.py", proj, "--dry-run", "--json")
+ plan = json.loads(proc.stdout)
+ self.assertEqual(plan["stages"], ["clips", "join", "fit", "captions", "graphics", "overlays", "audio", "loudness", "export"])
+ forwarded = "\n".join(l for l in proc.stderr.splitlines() if l.startswith("→ ")) # render's own child invocations
+ for needle in ("--srt", "--template lower-third", "--image", "--logo", "--replace", "--music-loop", "--fit pad --crf 20", "--brand"):
+ self.assertIn(needle, forwarded, f"{needle} not forwarded:\n{forwarded}")
+ for stage in ("fit", "captions", "graphics", "overlays", "audio", "loudness"):
+ out = json.loads(script("render.py", proj, "--dry-run", "--stop-after", stage, "--json").stdout)
+ self.assertEqual(out["stages"][-1], stage)
+ # single uncut clip (so silence.py can analyse a real file under --dry-run), silence stage,
+ # captions from .ass, mono/downmix/duck audio, voice flag: the other branches of the same tables
+ alt = dict(full, clips=[{"src": "source.mp4"}], silence={"threshold": -40, "min_silence": 0.4, "margin": 0.1},
+ captions={"ass": ass.name}, audio={"music": "long_ref.wav", "mono": True, "downmix": True, "duck": True, "voice": True, "duck_amount": 8}, graphics=[], overlays=[])
+ ass.write_text("[Script Info]\nScriptType: v4.00+\n\n[Events]\nFormat: Layer, Start, End, Style, Text\nDialogue: 0,0:00:00.00,0:00:01.00,Default,hi\n", encoding="utf-8")
+ (OUT / "render_full_alt.json").write_text(json.dumps(alt), encoding="utf-8")
+ proc = script("render.py", OUT / "render_full_alt.json", "--dry-run", "--json")
+ self.assertEqual(json.loads(proc.stdout)["stages"], ["clips", "silence", "fit", "captions", "audio", "loudness", "export"])
+ forwarded = "\n".join(l for l in proc.stderr.splitlines() if l.startswith("→ "))
+ for needle in ("--ass", "--min-silence 0.4", "--mono", "--downmix", "--duck-amount 8", "--voice"):
+ self.assertIn(needle, forwarded, f"{needle} not forwarded:\n{forwarded}")
+ out = json.loads(script("render.py", OUT / "render_full_alt.json", "--dry-run", "--stop-after", "silence", "--json").stdout)
+ self.assertEqual(out["stages"], ["clips", "silence"])
+ # no export block: the last stage is copied to the output, for real
+ copy_proj = OUT / "render_copy.json"
+ copy_proj.write_text(json.dumps({"output": "render_copy.mp4", "clips": [{"src": "source.mp4", "in": 0, "out": 2}]}), encoding="utf-8")
+ data = json.loads(script("render.py", copy_proj, "--fast", "--json").stdout)
+ self.assertEqual(data["stages"], ["clips"])
+ self.assertClose(probe(str(OUT / "render_copy.mp4"))["duration"], 2.0, 0.3)
+ # refusals: each names its cause and exits non-zero
+ cases = {
+ "no_project": ([], "give a project.json"),
+ "unreadable": ([OUT / "render_missing.json"], "cannot read project"),
+ "empty_clips": ([self._proj("render_e1.json", {"clips": []})], "clips is empty"),
+ "captions_key": ([self._proj("render_e2.json", {"clips": full["clips"], "captions": {"size": 20}}), "--dry-run"], "captions needs text, srt or ass"),
+ "graphics_key": ([self._proj("render_e3.json", {"clips": full["clips"], "graphics": [{"name": "x"}]}), "--dry-run"], "needs a template"),
+ "overlay_key": ([self._proj("render_e4.json", {"clips": full["clips"], "overlays": [{"opacity": 1}]}), "--dry-run"], "needs image or text"),
+ "child_failed": ([self._proj("render_e5.json", {"clips": [{"src": "source.mp4", "in": "not-a-time", "out": 2}]}), "--dry-run"], "cut.py failed"),
+ }
+ for name, (argv, message) in cases.items():
+ proc = script("render.py", *argv, expect_fail=True)
+ self.assertIn(message, proc.stderr, f"{name}: {proc.stderr[-400:]}")
+
+ def test_render_refuses_an_unknown_project_key_naming_the_nearest_valid_one(self):
+ """Review 9: a project was read with dict.get only, so a mistyped key was silently
+ ignored -- a clip "start"/"end" (the spelling graphics and overlays use for their own
+ times) rendered the whole clip untrimmed, and "exports" dropped the export stage, both
+ reported as a successful render. Every key of the project and of each stage/clip object
+ is now checked, and the template still validates."""
+ cases = {
+ "clip_key": ({"clips": [{"src": "source.mp4", "start": 0, "end": 2}], "export": {"preset": "reels"}},
+ "clips[0]: unknown key 'start' (did you mean 'in'?)"),
+ "stage_key": ({"clips": [{"src": "source.mp4", "in": 0, "out": 2}], "exports": {"preset": "reels"}},
+ "project: unknown key 'exports' (did you mean 'export'?)"),
+ "nested_key": ({"clips": [{"src": "source.mp4"}], "export": {"preset": "reels", "quality": 20}},
+ "export: unknown key 'quality'"),
+ }
+ for name, (body, message) in cases.items():
+ proc = script("render.py", self._proj(f"render_key_{name}.json", body), "--dry-run", "--json", expect_fail=True)
+ self.assertIn(message, proc.stderr, f"{name}: {proc.stderr[-400:]}")
+ doc = json.loads(proc.stdout)
+ self.assertEqual((doc["status"], doc["error"]["kind"]), ("failed", "input"))
+ tmpl = OUT / "render_template_valid.json"
+ script("render.py", "--init", tmpl)
+ proc = script("render.py", tmpl, "--dry-run", expect_fail=True) # only REPLACE_ME.mp4 is missing
+ self.assertIn("source not found", proc.stderr)
+ self.assertNotIn("unknown key", proc.stderr)
+
+ def test_emit_and_die_use_the_ctx_they_were_given_for_the_plan(self):
+ """Review 9: run()/emit()/die() took ctx= but write_plan() and the atexit hook still read
+ STATE -- emit(ctx=...) wrote an empty plan while reporting one, and die(ctx=...) let the
+ hook write a plan for a failed run."""
+ code = (
+ "import sys, atexit, json\n"
+ f"sys.path.insert(0, {str(SCRIPTS)!r})\n"
+ "import _common as c\n"
+ "atexit.register(c._plan_at_exit)\n"
+ "mode, src, plan = sys.argv[1], sys.argv[2], sys.argv[3]\n"
+ "ctx = c.Context(); ctx.json = True; ctx.dry_run = True; ctx.plan = plan\n"
+ "c.STATE.plan = plan\n"
+ "c.run(['/usr/bin/ffmpeg', '-i', src, '-t', '1', src + '.out.mp4'], ctx=ctx)\n"
+ "if mode == 'emit':\n"
+ " c.emit(None, ctx=ctx)\n"
+ "else:\n"
+ " c.die('boom', ctx=ctx)\n"
+ )
+ src = str(OUT / "source.mp4")
+ plan = OUT / "ctx_plan.json"
+ sh(sys.executable, "-c", code, "emit", src, plan)
+ doc = json.loads(plan.read_text(encoding="utf-8"))
+ self.assertEqual(len(doc["commands"]), 1, doc)
+ self.assertIn("ffmpeg", doc["commands"][0])
+ plan2 = OUT / "ctx_plan_die.json"
+ if plan2.exists():
+ plan2.unlink()
+ proc = sh(sys.executable, "-c", code, "die", src, plan2, expect_fail=True)
+ self.assertIn("boom", proc.stderr)
+ self.assertFalse(plan2.exists(), "die() left a plan behind for a failed run")
+
+ def test_render_default_work_dir_is_unique_per_process(self):
+ """The default work dir name came only from the output path (e.g. "out_work"), no PID or
+ timestamp -- two concurrent render.py runs targeting the same output (a batch.py "project"
+ recipe processing files in parallel, or simply two runs by mistake) shared the same work
+ directory and clobbered each other's same-named intermediates (clip00.mp4, fit.mp4, ...)
+ mid-run. Verify the auto-derived work dir name includes this process's own PID."""
+ proj = OUT / "project_workdir.json"
+ proj.write_text(json.dumps({"output": "render_workdir_check.mp4", "clips": [{"src": "source.mp4", "in": 0, "out": 2}]}), encoding="utf-8")
+ # --keep leaves the PID-suffixed dir behind, so a second run of this suite in the same
+ # OUT (a local re-run, or a coverage pass) would count the previous run's dir too.
+ for stale in OUT.glob("render_workdir_check_work*"):
+ if stale.is_dir():
+ shutil.rmtree(stale)
+ out = json.loads(script("render.py", proj, "--fast", "--stop-after", "clips", "--keep", "--json").stdout)
+ self.assertEqual(out["stages"], ["clips"])
+ work_dirs = [p for p in OUT.glob("render_workdir_check_work*") if p.is_dir()]
+ self.assertEqual(len(work_dirs), 1)
+ self.assertRegex(work_dirs[0].name, r"^render_workdir_check_work_\d+$",
+ "the default work dir name must carry a PID suffix, not just the bare output stem")
+
+ def test_render_single_clip_fit_height_is_not_silently_dropped(self):
+ """The single-clip fit path only ever inherited width/fps from project.frame, and the
+ flag-forwarding list that turns project.fit's own keys into fit.py argv omitted height
+ entirely -- so a project.json specifying "fit": {"height": N} (with no other fit key)
+ used to build fit.py argv with nothing in it at all ("nothing to do" crash), and combined
+ with another fit key (e.g. duration) the height silently never reached fit.py -- the
+ output's height was left unchanged with no error. Verify height alone now actually
+ resizes a single-clip render."""
+ proj = OUT / "project_height.json"
+ proj.write_text(json.dumps({
+ "output": "render_height.mp4",
+ "clips": [{"src": "source.mp4", "in": "0:01", "out": "0:04"}],
+ "fit": {"height": 480},
+ }), encoding="utf-8")
+ script("render.py", proj, "--fast", "--json")
+ m = probe(str(OUT / "render_height.mp4"))
+ self.assertEqual(m["video"]["height"], 480)
+
+ def test_render_frame_aspect_takes_the_export_presets_size(self):
+ """Eval 7 (j08 twice, e01 by hand): "frame": {"aspect": "9:16"} with a reels export fitted
+ a 1280x720 source to 406x720, captions were burned there and export.py upscaled them
+ soft. When the export preset names a delivery frame of the same aspect, the fit stage
+ uses it; a preset of another shape (or an explicit width/height) is left alone."""
+ proj = OUT / "project_aspect.json"
+ work = OUT / "render_aspect_work"
+ proj.write_text(json.dumps({
+ "output": "render_aspect.mp4",
+ "clips": [{"src": "source.mp4", "in": "0:01", "out": "0:03"}],
+ "frame": {"aspect": "9:16"},
+ "export": {"preset": "reels"},
+ }), encoding="utf-8")
+ script("render.py", proj, "--fast", "--json", "--work", work, "--keep")
+ m = probe(str(work / "fit.mp4"))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1080, 1920))
+ sys.path.insert(0, str(SCRIPTS))
+ try:
+ import render
+ finally:
+ sys.path.pop(0)
+ frame = {"aspect": "1:1"}
+ render.frame_from_preset(frame, {"preset": "reels"})
+ self.assertEqual(frame, {"aspect": "1:1"})
+ frame = {"aspect": "9:16", "width": 540}
+ render.frame_from_preset(frame, {"preset": "reels"})
+ self.assertEqual(frame, {"aspect": "9:16", "width": 540})
+
+ def test_render_exits_nonzero_when_the_check_stage_fails(self):
+ """A render whose deliverable fails its own check stage must not report success."""
+ proj = OUT / "project_bad_check.json"
+ proj.write_text(json.dumps({
+ "output": "render_bad.mp4",
+ "clips": [{"src": "source.mp4", "in": "0:01", "out": "0:04"}],
+ "export": {"preset": "reels"}, # portrait 9:16 output
+ "check": {"platform": "broadcast"}, # broadcast requires 16:9 -- guaranteed aspect FAIL
+ }), encoding="utf-8")
+ proc = script("render.py", proj, "--fast", "--json", expect_fail=True)
+ data = json.loads(proc.stdout)
+ self.assertGreater(data["check"]["failed"], 0, data["check"])
+ self.assertEqual((data["status"], data["error"]["kind"]), ("failed", "verification"))
+ self.assertIn("aspect", data["error"]["message"])
+ self.assertTrue(Path(data["output"]).exists(), "the deliverable is still written even though it fails delivery spec")
+ # the outer --timeout reaches every stage: an impossible limit fails inside the first stage
+ proc = script("render.py", proj, "--fast", "--timeout", "0.05", "--json", expect_fail=True)
+ self.assertIn("time limit", proc.stderr)
+ self.assertIn("--timeout 0.05", proc.stderr, "the flag must be forwarded to the child command line")
+ # ...and the stage's own failure is what render reports: kind timeout, exit 124, the stage named
+ tdoc = json.loads(proc.stdout)
+ self.assertEqual((tdoc["status"], tdoc["error"]["kind"], tdoc["exit_code"], tdoc["stage"]), ("failed", "timeout", 124, "cut.py"))
+
+ def test_write_project_writes_a_project_render_accepts(self):
+ """--write-project is the "let me edit it first" path: it must write a project the real
+ renderer takes without a single further change, and render nothing itself."""
+ proj = OUT / "wp_project.json"
+ out = OUT / "wp_out.mp4"
+ out.unlink(missing_ok=True)
+ doc = json.loads(script("render.py", self.src, "--template", "reels", "--cues", self.cues,
+ "--write-project", proj, "-o", out, "--json").stdout)
+ self.assertEqual(doc["output"], str(proj))
+ self.assertFalse(out.exists(), "--write-project renders nothing")
+ loaded = json.loads(proj.read_text())
+ self.assertEqual(loaded["template"], "reels")
+ self.assertEqual(loaded["clips"][0]["src"], str(self.src.resolve()))
+ plan = json.loads(script("render.py", proj, "--dry-run", "--json").stdout)
+ self.assertEqual(plan["status"], "completed")
+ self.assertIn("export", plan["stages"])
+
+ def test_project_graphics_entry_renders_a_sticker_and_a_meme(self):
+ """The three social graphics templates are advertised as usable inside a render.py
+ graphics[] entry, and until review 12 the project validator refused their own keys
+ (text/top/bottom/duration), so sticker and meme could only be run from the CLI."""
+ out = OUT / "gproj_out.mp4"
+ proj = OUT / "gproj.json"
+ proj.write_text(json.dumps({
+ "output": str(out),
+ "clips": [{"src": str(self.src.resolve()), "in": 0, "out": 4}],
+ "graphics": [
+ {"template": "sticker", "text": "NEW", "position": "top-right", "platform": "tiktok"},
+ {"template": "meme", "top": "when the render", "bottom": "finally finishes"},
+ {"template": "hook", "title": "How I cut this", "duration": 2},
+ ]}), encoding="utf-8")
+ doc = json.loads(script("render.py", proj, "--fast", "--json").stdout)
+ self.assertEqual(doc["status"], "completed")
+ self.assertIn("graphics", doc["stages"])
+ self.assertTrue(out.exists())
+ # ink where the meme layout puts it: the two edges of the frame change, and the sticker
+ # corner does too -- a validator that accepted the keys but dropped them would not show here
+ for crop, y in (("iw:100:0:20", "top"), ("iw:100:0:600", "bottom")):
+ before, _ = self._region_stats(self.src, crop, at=1.0)
+ after, _ = self._region_stats(out, crop, at=1.0)
+ self.assertNotAlmostEqual(before, after, delta=0.5, msg=f"nothing was drawn at the {y}")
+ # an unknown key is still a refusal, with the valid ones named
+ proj.write_text(json.dumps({"output": str(out), "clips": [{"src": str(self.src.resolve())}],
+ "graphics": [{"template": "sticker", "caption": "NEW"}]}), encoding="utf-8")
+ proc = script("render.py", proj, "--dry-run", "--json", expect_fail=True)
+ self.assertIn("unknown key", proc.stderr)
+
+ def test_pack_dry_run_plans_every_command_and_reports_no_result(self):
+ """A pack is the one path that writes seven files, so --dry-run has to show all of them --
+ and must never report a check result or a file size for a run that encoded nothing (the
+ sizes used to be read off files left behind by an earlier real run)."""
+ packdir = OUT / "packdry"
+ packdir.mkdir(exist_ok=True)
+ stale = packdir / "source_tiktok.mp4"
+ stale.write_bytes(b"0" * 4096) # a leftover from an earlier real run
+ doc = json.loads(script("render.py", self.src, "--template", "tiktok,podcast",
+ "--cues", self.cues, "--dry-run", "--json",
+ "-o", str(packdir / "ignored.mp4")).stdout)
+ self.assertTrue(any("ffmpeg" in c for c in doc["commands"]),
+ "the pack's planned commands are the plan; --dry-run must show them")
+ self.assertTrue(any("loudnorm" in c or "libx264" in c for c in doc["commands"]))
+ for row in doc["pack"]:
+ self.assertEqual(row["check"], "planned", row)
+ self.assertIsNone(row["size_bytes"], row)
+ self.assertIsNone(row["duration"], row)
+ self.assertEqual(stale.stat().st_size, 4096, "a dry run must not touch the files it plans")
+ # the audio-only destination of a pack is named like the single-template form: .m4a
+ self.assertEqual([Path(r["file"]).suffix for r in doc["pack"]], [".mp4", ".m4a"])
+ self.assertFalse((packdir / "source_pack.md").exists(), "a dry run writes no table either")
+
+ def test_brand_defaults_apply_to_caption_and_logo(self):
+ brand = OUT / "brand.json"
+ if not brand.exists():
+ self.test_graphics_templates()
+ ass = OUT / "brand.ass"
+ script("caption.py", self.src, "--text", self.cues, "--brand", brand, "--write-ass", ass, "--fast", "-o", OUT / "brand_cap.mp4")
+ style = [l for l in ass.read_text(encoding="utf-8-sig").splitlines() if l.startswith("Style:")][0]
+ self.assertIn("&H00006AFF", style, "primary FF6A00 becomes the karaoke fill (BGR)")
+ self.assertIn(",70,", style, "size 28 scaled to 720p")
+ self.assertIn("\\kf", ass.read_text(encoding="utf-8-sig"), "brand enables karaoke")
+ proc = script("overlay.py", self.src, "--logo", "--brand", brand, "--fast", "-o", OUT / "brand_logo.mp4")
+ self.assertIn("scale=140:-1", proc.stderr)
+ self.assertIn("overlay=W-w-40:40", proc.stderr)
+ script("overlay.py", self.src, "--logo", expect_fail=True)
+
+ # ---------------------------------------------------------------- v0.7: MCP server / batch / ASR bridge
+ def test_mcp_server_stdio(self):
+ server = ROOT / "mcp" / "server.py"
+ reqs = [
+ {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}},
+ {"jsonrpc": "2.0", "method": "notifications/initialized"},
+ {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
+ {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "probe", "arguments": {"inputs": [str(self.src)]}}},
+ {"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "cut", "arguments": {"input": str(self.src), "start": 1, "end": 3, "output": str(OUT / "mcp_cut.mp4")}}},
+ {"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "cut", "arguments": {"argv": [str(self.src), "--start", "0", "--end", "2", "-o", str(OUT / "mcp_cut2.mp4")]}}},
+ {"jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {"name": "nope", "arguments": {}}},
+ {"jsonrpc": "2.0", "id": 7, "method": "bogus/method"},
+ ]
+ proc = subprocess.run([sys.executable, str(server)], input="\n".join(json.dumps(r) for r in reqs) + "\n", stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ self.assertEqual(proc.returncode, 0, proc.stderr)
+ resp = {r["id"]: r for r in (json.loads(l) for l in proc.stdout.splitlines() if l.strip())}
+ self.assertEqual(resp[1]["result"]["serverInfo"]["name"], "ffmpeg-skill")
+ names = {t["name"] for t in resp[2]["result"]["tools"]}
+ self.assertTrue({"probe", "cut", "render", "check", "scenes", "batch"} <= names or {"probe", "cut", "render", "check", "scenes"} <= names)
+ self.assertEqual(resp[3]["result"]["structuredContent"]["duration"], 12.0)
+ self.assertClose(resp[4]["result"]["structuredContent"]["probe"]["duration"], 2.0, 0.6)
+ self.assertTrue(Path(resp[5]["result"]["structuredContent"]["output"]).exists())
+ self.assertTrue(resp[6]["result"].get("isError"))
+ self.assertEqual(resp[7]["error"]["code"], -32601)
+
+ def test_mcp_server_survives_a_non_object_json_line(self):
+ """json.loads accepts any valid JSON value, not just an object -- a bare `42`, `null`,
+ `true` or `[1,2]` line parses without raising, but main()'s very next line, `"id" not in
+ req`, raised an uncaught TypeError for a non-dict req (an int/bool/None isn't iterable the
+ way `in` needs). That check sat outside the try/except wrapping handle(), so the exception
+ propagated out of the stdin loop and killed the whole stdio server process -- not just
+ that one malformed line, but every other in-flight and future tool call in the session.
+ Verify a line like this is now skipped, and the server stays alive and answers the next
+ (valid) request instead of exiting non-zero with nothing produced for it."""
+ server = ROOT / "mcp" / "server.py"
+ lines = ["42", "null", "true", "[1,2,3]",
+ json.dumps({"jsonrpc": "2.0", "id": 1, "method": "tools/list"})]
+ proc = subprocess.run([sys.executable, str(server)], input="\n".join(lines) + "\n", stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ self.assertEqual(proc.returncode, 0, f"server must not crash on non-object JSON lines; stderr: {proc.stderr}")
+ resp = [json.loads(response_line) for response_line in proc.stdout.splitlines() if response_line.strip()]
+ self.assertEqual(len(resp), 1, "only the one real request should get a response")
+ self.assertEqual(resp[0]["id"], 1)
+ self.assertIn("tools", resp[0]["result"])
+
+ def test_batch_recipe_and_cache(self):
+ folder = OUT / "batch_in"
+ folder.mkdir(exist_ok=True)
+ for name in ("a.mp4", "b.mp4"):
+ (folder / name).write_bytes(Path(self.src).read_bytes())
+ recipe = folder / "batch.json"
+ recipe.write_text(json.dumps({"glob": "*.mp4", "output_dir": "out", "suffix": "_final",
+ "steps": [["fit.py", "{in}", "--duration", "5", "-o", "{out}"], ["export.py", "{in}", "--preset", "x", "-o", "{out}"]]}))
+ data = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--json").stdout)
+ self.assertEqual(data["processed"], 2)
+ self.assertFalse(any(r.get("cached") for r in data["results"]))
+ for r in data["results"]:
+ m = probe(r["output"])
+ self.assertClose(m["duration"], 5.0, 0.3)
+ self.assertEqual(m["video"]["width"], 1280)
+ data = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--json").stdout)
+ self.assertTrue(all(r.get("cached") for r in data["results"]), "second run served from cache")
+ data = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--force", "--json").stdout)
+ self.assertFalse(any(r.get("cached") for r in data["results"]))
+ # project-based recipe
+ proj = folder / "p.json"
+ proj.write_text(json.dumps({"clips": [{"src": "x", "in": 0, "out": 3}], "export": {"preset": "x"}}))
+ recipe2 = folder / "batch2.json"
+ recipe2.write_text(json.dumps({"glob": "a.mp4", "output_dir": "out2", "suffix": "_p", "project": "p.json"}))
+ data = json.loads(script("batch.py", folder, "--recipe", recipe2, "--fast", "--json").stdout)
+ self.assertEqual(data["processed"], 1)
+ self.assertClose(probe(data["results"][0]["output"])["duration"], 3.0, 0.3)
+
+ def test_batch_project_recipe_cache_invalidates_on_project_json_content_change(self):
+ """A "project" recipe is just {"project": "<path>", "clip_key": N} -- the real settings
+ (export preset, captions, everything) live in the file at that path. The cache key used
+ to hash only this outer recipe dict, so editing project.json's content (export preset
+ swapped from "copy" to "x", a real re-encode) without touching batch.json itself left the
+ key unchanged, and the stale cached output was served for the new settings with no error
+ or warning. Verify a content-only change to project.json invalidates the cache."""
+ folder = OUT / "batch_project_cache"
+ folder.mkdir(exist_ok=True)
+ (folder / "clip.mp4").write_bytes(Path(self.src).read_bytes())
+ proj = folder / "p.json"
+ proj.write_text(json.dumps({"clips": [{}], "export": {"preset": "copy"}}))
+ recipe = folder / "batch.json"
+ recipe.write_text(json.dumps({"glob": "clip.mp4", "output_dir": "out", "project": "p.json"}))
+ data = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--json").stdout)
+ self.assertFalse(data["results"][0].get("cached"))
+ proj.write_text(json.dumps({"clips": [{}], "export": {"preset": "x"}}))
+ data = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--json").stdout)
+ self.assertFalse(data["results"][0].get("cached"), "a content-only project.json change must not be served from a stale cache")
+
+ def test_batch_cache_write_is_atomic_no_leftover_temp_file(self):
+ """The cache file used to be written with a plain write_text(), which is not atomic -- a
+ process killed mid-write leaves a truncated file that the next run's json.loads() treats
+ as corrupt and silently discards (every prior cache entry lost, not just the interrupted
+ one). Now written via a sibling temp file + os.replace(). Verify a normal run leaves the
+ cache file valid and no stray .tmp<pid> file behind."""
+ folder = OUT / "batch_cache_atomic"
+ folder.mkdir(exist_ok=True)
+ (folder / "clip.mp4").write_bytes(Path(self.src).read_bytes())
+ recipe = folder / "batch.json"
+ recipe.write_text(json.dumps({"glob": "clip.mp4", "output_dir": "out", "steps": [["export.py", "{in}", "--preset", "copy", "-o", "{out}"]]}))
+ script("batch.py", folder, "--recipe", recipe, "--fast")
+ outdir = folder / "out"
+ cache_path = outdir / ".ffskill_cache.json"
+ self.assertTrue(cache_path.exists())
+ json.loads(cache_path.read_text(encoding="utf-8")) # must not be truncated/corrupt
+ leftover = list(outdir.glob(".ffskill_cache.json.tmp*"))
+ self.assertEqual(leftover, [], f"temp cache file(s) left behind: {leftover}")
+
+ def test_batch_refuses_a_recipe_step_naming_a_script_outside_scripts_dir(self):
+ """run_step() built its command as `HERE / argv[0]`, where argv[0] came straight from an
+ untrusted recipe JSON step. Path's / operator silently ignores the left side when the
+ right side is itself an absolute path, and does nothing to stop a "../" traversal either
+ -- so a recipe (from a template, a shared config, anywhere the caller didn't author it
+ themselves) naming an absolute or ../-relative path got that file executed as a Python
+ script, with the caller's own privileges, once per matching media file. Verify both an
+ absolute path and a traversal path are refused instead of executed."""
+ folder = OUT / "batch_security"
+ folder.mkdir(exist_ok=True)
+ (folder / "a.mp4").write_bytes(Path(self.src).read_bytes())
+ evil = OUT / "batch_security_evil.py"
+ marker = OUT / "batch_security_pwned.txt"
+ marker.unlink(missing_ok=True)
+ evil.write_text(f"open({str(marker)!r}, 'w').write('pwned')\n", encoding="utf-8")
+
+ for step in ([str(evil)], ["../../../../tmp/does_not_matter.py"]):
+ recipe = folder / "batch.json"
+ recipe.write_text(json.dumps({"glob": "*.mp4", "steps": [step]}))
+ proc = script("batch.py", folder, "--recipe", recipe, "--fast", "--force", expect_fail=True)
+ self.assertIn("scripts/", proc.stderr)
+ self.assertFalse(marker.exists(), f"step {step} must not have executed")
+
+ def test_batch_refuses_a_fixed_ext_recipe_that_collapses_two_sources_to_one_output(self):
+ """final_path() falls back to each source's OWN extension by default, so files that only
+ differ by extension don't collide -- but a recipe with a fixed "ext" (e.g. converting a
+ folder of mixed .mp4/.mov masters to one format) makes two sources with the same stem
+ (clip.mp4 and clip.mov) resolve to the identical final path (clip_out.mp4). process() had
+ no collision detection: the file processed later in sorted() order used to silently
+ overwrite the earlier one's finished output, with the cache still recording both entries
+ as ok. Verify this is now refused up front, before either file is processed, rather than
+ one silently clobbering the other."""
+ folder = OUT / "batch_collision_in"
+ folder.mkdir(exist_ok=True)
+ for name in ("clip.mp4", "clip.mov"):
+ (folder / name).write_bytes(Path(self.src).read_bytes())
+ recipe = folder / "collide.json"
+ recipe.write_text(json.dumps({"ext": "mp4", "steps": [["export.py", "{in}", "--preset", "x", "-o", "{out}"]]}))
+ proc = script("batch.py", folder, "--recipe", recipe, "--fast", expect_fail=True)
+ self.assertIn("collision", proc.stderr)
+ self.assertIn("clip.mp4", proc.stderr)
+ self.assertIn("clip.mov", proc.stderr)
+ self.assertFalse((folder / "out" / "clip_out.mp4").exists(), "nothing should be written once a collision is detected")
+
+ # ---------------------------------------------------------------- _common
+ def test_context_is_attribute_only_and_resets(self):
+ """Context once carried dict-style shims for older call sites; every site uses attributes
+ now and the shims are gone, so a stray STATE["x"] is a TypeError at the call site rather
+ than a second, silently-diverging access path. __slots__ also refuses unknown names."""
+ from _common import Context
+ ctx = Context()
+ ctx.dry_run = True
+ ctx.fast = True
+ self.assertTrue(ctx.dry_run and ctx.fast)
+ self.assertIsNone(ctx.duration_hint)
+ with self.assertRaises(TypeError):
+ ctx["dry_run"] # noqa: B018 -- the mapping shim is gone on purpose
+ with self.assertRaises(AttributeError):
+ ctx.nonexistent = 1
+ ctx.commands.append("x")
+ ctx.reset()
+ self.assertEqual((ctx.dry_run, ctx.fast, ctx.commands), (False, False, []))
+
+ def test_run_records_commands_on_a_passed_context_not_the_global_state(self):
+ """1.10 threads an optional `ctx=` through run()/emit()/die() (issue #189 B; 2.0 makes it
+ required). A fresh Context() must collect that call's commands itself and leave the
+ process-global STATE untouched, which is the property the 2.0 signature change relies on."""
+ import _common
+ ctx = _common.Context()
+ ctx.dry_run = True
+ before = list(_common.STATE.commands)
+ proc = _common.run(["ffmpeg", "-i", "in.mp4", "out.mp4"], quiet=True, ctx=ctx)
+ self.assertEqual(proc.returncode, 0, "a dry run plans without executing ffmpeg")
+ self.assertEqual(ctx.commands, ["ffmpeg -i in.mp4 out.mp4"])
+ self.assertEqual(_common.STATE.commands, before, "the global STATE must not have seen this call")
+
+ def test_skill_md_stays_within_the_agent_reading_budget(self):
+ """1.11.0: SKILL.md is the file every session loads, so its size is a real per-run cost.
+ The two-tier split (long-form prose in references/gotchas.md, one line plus an anchor
+ here) brought it from 362 lines / 37.8 KB to under this ceiling; a new rule belongs in a
+ references/ file with a one-line pointer, not in an ever-growing SKILL.md."""
+ text = (ROOT / "SKILL.md").read_text(encoding="utf-8")
+ lines, size = len(text.splitlines()), len(text.encode("utf-8"))
+ self.assertLessEqual(lines, 220, f"SKILL.md is {lines} lines; move detail to references/")
+ self.assertLessEqual(size, 30000, f"SKILL.md is {size} bytes; move detail to references/")
+ gotchas = (ROOT / "references" / "gotchas.md").read_text(encoding="utf-8")
+ # every "details:" pointer resolves to a real heading in the file it names
+ for anchor in re.findall(r"references/gotchas\.md#([a-z0-9-]+)", text):
+ headings = ["".join(ch for ch in h.lower().replace(" ", "-") if ch.isalnum() or ch == "-")
+ for h in re.findall(r"(?m)^#+ (.+)$", gotchas)]
+ self.assertIn(anchor, headings, f"SKILL.md points at references/gotchas.md#{anchor}, which has no such heading")
+
+ def test_every_script_has_help(self):
+ for name in sorted(p.name for p in SCRIPTS.glob("*.py") if not p.name.startswith("_")):
+ with self.subTest(script=name):
+ out = script(name, "--help").stdout
+ self.assertIn("usage:", out)
+
+
+class DemoGalleryTests(unittest.TestCase):
+ """The gallery in docs/demos.md is committed, so its builder is a shipped artefact: if
+ demos/build.py stops rendering, the README's pictures quietly describe an older tool.
+
+ One cheap demo is enough to prove the whole path -- fixtures, a real script invocation, the
+ side-by-side, the preview and the size budget -- without spending several minutes of CI on all
+ of them (the `demos` job in demos/CI.md runs the full set)."""
+
+ def test_build_one_demo_and_stay_under_the_preview_budget(self):
+ if not shutil.which("ffmpeg"):
+ if os.environ.get("CI"):
+ raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step")
+ raise unittest.SkipTest("ffmpeg not on PATH")
+ from _common import script_font_status
+ if script_font_status("ja") == "missing":
+ # Not a failure: the demo itself skips for the same reason. A machine with no CJK
+ # font cannot render Japanese captions, and a tofu-filled GIF would be worse than none.
+ raise unittest.SkipTest("no font on this machine covers Japanese: captions_ja cannot render")
+ preview = ROOT / "docs" / "demos" / "captions_ja.gif"
+ before = preview.read_bytes() if preview.exists() else None
+ try:
+ sh(sys.executable, ROOT / "demos" / "build.py", "--only", "captions_ja")
+ self.assertTrue(preview.exists(), f"{preview} was not written")
+ size = preview.stat().st_size
+ self.assertLessEqual(size, 500 * 1024,
+ f"{preview.name} is {size} bytes; previews are committed and "
+ f"capped at 500 KB (demos/build.py enforces this too)")
+ self.assertGreater(size, 1024, "a preview that small did not render anything")
+ for name in ("captions_ja_before.mp4", "captions_ja_after.mp4", "captions_ja.mp4"):
+ self.assertTrue((ROOT / "demos" / "out" / name).exists(), f"demos/out/{name} missing")
+ finally:
+ # Leave the committed preview exactly as it was: this machine's ffmpeg writes
+ # different GIF bytes than the one that built the gallery, and a test must not
+ # dirty the working tree it ran in.
+ if before is not None:
+ preview.write_bytes(before)
+
+ def test_every_demo_in_the_table_is_listed_and_documented(self):
+ """--list and docs/demos.md are two views of the same table; a demo added to the
+ builder without a gallery entry is a picture nobody ever sees."""
+ listed = sh(sys.executable, ROOT / "demos" / "build.py", "--list").stdout
+ names = [line.split()[0] for line in listed.splitlines() if line.strip()]
+ self.assertGreaterEqual(len(names), 10, "the gallery lost most of its demos")
+ page = (ROOT / "docs" / "demos.md").read_text(encoding="utf-8")
+ for name in names:
+ self.assertIn(f"demos/{name}.gif", page,
+ f"{name} is built but has no section in docs/demos.md "
+ f"(run: python3 demos/build.py --docs)")
+
+ def test_every_script_is_shown_working_by_a_demo(self):
+ """A tool nobody can see working is hard to review and harder to trust. Every script
+ under scripts/ either appears in a demo's command line (so the gallery renders it end to
+ end on every build) or is on the builder's INSPECTION list -- the tools whose entire
+ output is a table or an HTML file, which get a command and a sentence in docs/demos.md
+ instead of a picture. Nothing is allowed to be in neither list."""
+ sys.path.insert(0, str(ROOT / "demos"))
+ try:
+ import build as demo_build
+ finally:
+ sys.path.pop(0)
+ commands = " ".join(cmd for name in demo_build.BY_NAME
+ for cmd in demo_build._commands_for(name))
+ inspection = {tool for tool, _cmd, _what in demo_build.INSPECTION}
+ page = (ROOT / "docs" / "demos.md").read_text(encoding="utf-8")
+ for script in sorted(p.name for p in (ROOT / "scripts").glob("*.py")):
+ if script.startswith("_"):
+ continue
+ if script in inspection:
+ self.assertIn(script, page,
+ f"{script} is on demos/build.py's INSPECTION list but is not in "
+ f"docs/demos.md (run: python3 demos/build.py --docs)")
+ continue
+ self.assertIn(f"scripts/{script} ", commands + " ",
+ f"no demo in demos/build.py runs {script}: add one (a before/after "
+ f"demo) or, if it only ever prints a table, add it to INSPECTION")
+
+
+if __name__ == "__main__":
+ unittest.main(verbosity=2)
+
+
+class CommonFacadeTests(unittest.TestCase):
+ """`_common` is a package with a facade since the refactor release after 1.15.0. A name
+ rebound through the facade must reach the module that defines it, a read through the facade
+ must see the live value the defining module holds, and a reload must not rewrite the
+ submodules' own dunders (audit 14, P1-1 and P1-2)."""
+
+ def test_rebinding_through_the_facade_reaches_the_defining_module_and_reads_live(self):
+ import importlib
+ from unittest import mock
+ import _common
+ runner = sys.modules["_common.runner"]
+ _common.ffmpeg_version()
+ self.assertIsNotNone(runner._FFMPEG_VERSION)
+ self.assertEqual(_common._FFMPEG_VERSION, runner._FFMPEG_VERSION)
+ with mock.patch.object(_common, "_FFMPEG_VERSION", (7, 1)):
+ self.assertEqual(runner._FFMPEG_VERSION, (7, 1))
+ self.assertEqual(runner.ffmpeg_version(), (7, 1))
+ self.assertEqual(_common._FFMPEG_VERSION, runner._FFMPEG_VERSION)
+ with mock.patch("_common.ffmpeg_version", return_value=(9, 9)):
+ self.assertEqual(runner.ffmpeg_version(), (9, 9))
+ self.assertNotEqual(runner.ffmpeg_version(), (9, 9))
+ before = runner.__file__
+ importlib.reload(_common)
+ self.assertEqual(runner.__file__, before)
+ self.assertTrue(callable(_common.emit) and callable(_common.probe))
diff --git a/tests/test_picture.py b/tests/test_picture.py
new file mode 100644
index 0000000..84bc825
--- /dev/null
+++ b/tests/test_picture.py
@@ -0,0 +1,2130 @@
+#!/usr/bin/env python3
+"""End-to-end tests for caption, overlay, graphics, color, redact, deinterlace, denoise, stabilize, background and grid, plus fonts, emoji, shaping and caption wrap.
+
+ python3 tests/test_picture.py # this group alone
+ python3 tests/test_all.py # every group
+"""
+import contextlib
+import io
+import json
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _fixtures import MediaFixtures, OUT, SCRIPTS, TONES, _ass_advance, _ass_ink_columns, _emoji_assets, _families_for, _family_installed, _frame_ink, _no_fontconfig, _pixel_at, script, sh # noqa: E402
+from _common import default_font_file, detect_script, escape_filter_path, font_family_for_script, font_for_script, probe # noqa: E402
+
+
+class PictureTests(MediaFixtures):
+ """Caption, overlay, graphics, color, redact, deinterlace, denoise, stabilize, background and grid, plus fonts, emoji, shaping and caption wrap."""
+
+ # ---------------------------------------------------------------- deinterlace
+ def test_deinterlace_frame_mode_keeps_fps(self):
+ out = OUT / "deint1.mp4"
+ script("deinterlace.py", self.src, "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["video"]["fps"], 30.0, 0.5)
+ self.assertClose(m["duration"], 12.0, 0.3)
+ self.assertIsNotNone(m["audio"])
+
+ def test_deinterlace_field_mode_doubles_fps(self):
+ out = OUT / "deint2.mp4"
+ script("deinterlace.py", self.src, "--mode", "field", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["video"]["fps"], 60.0, 0.5)
+
+ # ---------------------------------------------------------------- denoise
+ def test_denoise_produces_valid_output(self):
+ out = OUT / "denoise1.mp4"
+ script("denoise.py", self.src, "--strength", "high", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
+ self.assertClose(m["duration"], 12.0, 0.3)
+
+ def test_denoise_negative_override_refused(self):
+ script("denoise.py", self.src, "--luma-spatial", "-1", expect_fail=True)
+
+ # ---------------------------------------------------------------- redact
+ def test_redact_blur_keeps_frame_size(self):
+ out = OUT / "redact1.mp4"
+ script("redact.py", self.src, "--x", "100", "--y", "50", "--width", "200", "--height", "100", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
+
+ def test_redact_pixelate_mode(self):
+ out = OUT / "redact2.mp4"
+ script("redact.py", self.src, "--x", "100", "--y", "50", "--width", "200", "--height", "100",
+ "--mode", "pixelate", "--block-size", "16", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
+
+ def test_redact_out_of_bounds_refused(self):
+ script("redact.py", self.src, "--x", "1200", "--y", "0", "--width", "200", "--height", "200", expect_fail=True)
+
+ def test_redact_odd_dimensions_refused(self):
+ script("redact.py", self.src, "--x", "0", "--y", "0", "--width", "101", "--height", "100", expect_fail=True)
+
+ # ---------------------------------------------------------------- grid
+ def test_grid_composites_cols_rows_with_labels(self):
+ out = OUT / "grid1.mp4"
+ script("grid.py", self.src, self.rot, self.vfr, self.hdr, "--cols", "2", "--rows", "2",
+ "--cell-width", "320", "--cell-height", "180", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
+
+ def test_grid_wrong_input_count_refused(self):
+ script("grid.py", self.src, self.rot, "--cols", "2", "--rows", "2", expect_fail=True)
+
+ def test_grid_label_none_skips_drawtext(self):
+ proc = script("grid.py", self.src, self.rot, "--cols", "2", "--rows", "1", "--label", "none", "-o", OUT / "grid2.mp4")
+ self.assertNotIn("drawtext", proc.stderr)
+
+ def test_grid_audio_from_selects_track(self):
+ out = OUT / "grid3.mp4"
+ script("grid.py", self.src, self.rot, "--cols", "2", "--rows", "1", "--audio-from", "1", "-o", out)
+ m = probe(str(out))
+ self.assertTrue(m.get("audio"))
+
+ def test_grid_pad_extends_shorter_clip_to_the_longest(self):
+ short = OUT / "grid_short.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-t", "2", "-c", "copy", short)
+ out = OUT / "grid4.mp4"
+ script("grid.py", short, self.src, "--cols", "2", "--rows", "1", "--pad", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], probe(str(self.src))["duration"], 0.5)
+
+ def test_grid_pad_also_pads_the_selected_audio_track_with_silence(self):
+ """--pad holds a shorter cell's video on its last frame out to the longest clip -- but
+ --audio-from's track was, until fixed, mapped straight through with no padding at all, so
+ a grid with --pad and a short --audio-from track silently lost audio for the padded tail.
+ The audio stream must actually span the full padded duration, not just the video."""
+ short = OUT / "grid_pad_audio_short.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-t", "2", "-c", "copy", short)
+ out = OUT / "grid6.mp4"
+ script("grid.py", short, self.src, "--cols", "2", "--rows", "1", "--audio-from", "0", "--pad", "-o", out)
+ full_duration = probe(str(self.src))["duration"]
+ audio_duration = float(sh("ffprobe", "-v", "error", "-select_streams", "a:0", "-show_entries",
+ "stream=duration", "-of", "default=nw=1:nk=1", out).stdout.strip())
+ self.assertClose(audio_duration, full_duration, 0.5, "audio must be padded with silence to match the padded video, not stop at 2s")
+
+ def test_grid_filename_derived_label_refuses_filter_graph_injection(self):
+ """The per-cell label is the clip's own filename (extension stripped), which the caller
+ does not choose through a flag -- but on a filesystem where filenames can contain a comma
+ or colon, it still reaches a drawtext=text=... option the same way --font's fallback did
+ in the #108 finding. Confirm the escaping catches it: a filename shaped like a filter-graph
+ breakout payload must render literally, not start a sibling filter."""
+ evil = OUT / "evil,drawtext=text=OWNED.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-t", "2", "-c", "copy", evil)
+ proc = script("grid.py", evil, self.rot, "--cols", "2", "--rows", "1", "-o", OUT / "grid5.mp4")
+ self.assertIn("\\,drawtext=text=OWNED", proc.stderr, "comma in the filename-derived label must be escaped")
+
+ # ---------------------------------------------------------------- background
+ def test_background_solid_color(self):
+ out = OUT / "bg_solid.mp4"
+ script("background.py", "-o", out, "--duration", "2", "--width", "640", "--height", "360", "--color", "0x00ff00")
+ m = probe(str(out))
+ self.assertClose(m["duration"], 2.0, 0.1)
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
+
+ def test_background_gradient_has_two_distinct_colors(self):
+ out = OUT / "bg_grad.mp4"
+ script("background.py", "-o", out, "--duration", "1", "--width", "640", "--height", "360",
+ "--gradient", "0xff0000:0x0000ff")
+
+ def px(path, x, y):
+ r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path),
+ "-vf", f"crop=2:2:{x}:{y}", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ return r.stdout[:3]
+
+ left = px(out, 10, 180)
+ right = px(out, 620, 180)
+ self.assertGreater(left[0], right[0], "left edge should be redder than the right edge")
+ self.assertGreater(right[2], left[2], "right edge should be bluer than the left edge")
+
+ def test_background_gradient_pins_speed_and_seed_for_a_static_reproducible_clip(self):
+ """The `gradients` source filter defaults to speed=0.01 (a slow rotation applied every
+ frame) and seed=-1 (a fresh random seed every run) -- so this "static" background (per
+ its own docstring: "a title card background, a placeholder behind a logo") silently
+ drifted frame to frame instead of staying put, and was not reproducible between runs,
+ breaking the bit_exact/deterministic contract _contract.py declares for background.py.
+ Confirmed live: the same pixel changed value between t=0s and t=1s of a 3s clip before
+ pinning speed near its filter-enforced floor (1e-05; 0 itself is refused). Check the
+ constructed filter string directly rather than sampled pixels, since a pixel-value
+ comparison is sensitive to x264 encoder rounding that differs between platforms/builds
+ independently of whether speed/seed are actually pinned."""
+ out = OUT / "bg_grad_pin.mp4"
+ data = json.loads(script("background.py", "-o", out, "--duration", "3", "--width", "320", "--height", "240",
+ "--gradient", "0x000000:0xffffff", "--angle", "37", "--fast", "--json").stdout)
+ cmd = data["commands"][0]
+ self.assertIn("gradients=", cmd)
+ self.assertRegex(cmd, r"seed=\d+", "seed must be pinned to a fixed value, not left at the -1 (random) default")
+ self.assertNotIn("speed=0.01", cmd, "speed must not be left at its default 0.01 (a visible per-frame rotation)")
+ m = re.search(r"speed=([\d.e-]+)", cmd)
+ self.assertIsNotNone(m, f"expected an explicit speed= in: {cmd}")
+ self.assertLess(float(m.group(1)), 0.001, "speed must be pinned near-zero, not left animating")
+
+ def test_background_odd_dimensions_refused(self):
+ script("background.py", "-o", OUT / "bg_bad.mp4", "--duration", "1", "--width", "641", "--height", "360", expect_fail=True)
+
+ def test_background_zero_duration_refused(self):
+ script("background.py", "-o", OUT / "bg_bad2.mp4", "--duration", "0", "--width", "640", "--height", "360", expect_fail=True)
+
+ # ---------------------------------------------------------------- stabilize
+ def test_stabilize_reduces_frame_to_frame_motion(self):
+ """Proves the actual effect, not just that the command runs: measured motion must drop.
+
+ Three different synthetic "shaky" fixtures (a clean two-frequency sine, then jitter kept
+ within real hand-tremor range after the first version's ~9 Hz component turned out too
+ fast for optical-flow tracking at 30 fps) were each measured making the output *more*
+ jittery, not less, on at least one real macOS ffmpeg/libvidstab build -- while every one
+ of them was reliably corrected on Linux. This isn't a fixture-tuning problem: vidstab's
+ actual tracking/correction behaviour genuinely differs enough across builds that no
+ synthetic camera-shake pattern found so far is a portable ground truth. The quantitative
+ "motion measurably dropped" claim is therefore only enforced on the platform where it has
+ held up across repeated, differently-tuned fixtures (Linux); elsewhere this still proves
+ stabilize.py actually ran vidstabdetect/vidstabtransform and produced a valid, correctly
+ durationed output -- just not a specific claim about how much quieter it is.
+ """
+ shaky = OUT / "shaky.mp4"
+ jitter_x = "60+18*sin(2*PI*t*1.3)+9*sin(2*PI*t*2.1+1)"
+ jitter_y = "60+14*cos(2*PI*t*0.9)+8*sin(2*PI*t*1.7+0.5)"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=1400x1000:rate=30",
+ "-t", "4", "-vf", f"crop=1280:720:x='{jitter_x}':y='{jitter_y}'",
+ "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", shaky)
+ out = OUT / "stab1.mp4"
+ script("stabilize.py", shaky, "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 4.0, 0.3)
+
+ def motion_score(path):
+ # a Windows path's drive-letter colon must be escaped for a lavfi filter option value
+ movie_path = escape_filter_path(str(path))
+ cmd = ["ffprobe", "-hide_banner", "-f", "lavfi", "-i", f"movie={movie_path},tblend=all_mode=difference,signalstats",
+ "-show_entries", "frame_tags=lavfi.signalstats.YAVG", "-of", "csv=p=0"]
+ proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ return [float(x) for x in proc.stdout.split() if x.strip()]
+
+ shaky_scores = motion_score(shaky)
+ stab_scores = motion_score(out)
+ self.assertTrue(shaky_scores, "motion_score produced no frames -- check the lavfi movie= filter path/escaping")
+ self.assertTrue(stab_scores, "motion_score produced no frames -- check the lavfi movie= filter path/escaping")
+ if platform.system() == "Linux":
+ shaky_avg = sum(shaky_scores) / len(shaky_scores)
+ stab_avg = sum(stab_scores) / len(stab_scores)
+ self.assertLess(stab_avg, shaky_avg, f"stabilized motion ({stab_avg:.2f}) should be below shaky ({shaky_avg:.2f})")
+
+ def test_stabilize_bad_shakiness_refused(self):
+ script("stabilize.py", self.src, "--shakiness", "11", expect_fail=True)
+
+ def test_stabilize_tripod_and_crop_black_produce_valid_output(self):
+ """--tripod and --crop black (vidstabdetect/vidstabtransform's own tripod and crop=1
+ options, #96) wire two more of the real filters' documented parameters through as typed
+ flags. vidstab's actual correction strength/appearance on synthetic content is build- and
+ content-dependent (see the docstring above on test_stabilize_reduces_frame_to_frame_motion
+ for why this suite doesn't try to assert an exact "how much" here) -- what's verifiable
+ portably is that both flags are accepted, reach the filter graph, and produce a valid,
+ correctly durationed/shaped output rather than being silently ignored or crashing."""
+ shaky = OUT / "shaky.mp4"
+ if not shaky.exists():
+ jitter_x = "60+18*sin(2*PI*t*1.3)+9*sin(2*PI*t*2.1+1)"
+ jitter_y = "60+14*cos(2*PI*t*0.9)+8*sin(2*PI*t*1.7+0.5)"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=1400x1000:rate=30",
+ "-t", "4", "-vf", f"crop=1280:720:x='{jitter_x}':y='{jitter_y}'",
+ "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", shaky)
+ out = OUT / "stab_tripod_crop_black.mp4"
+ proc = script("stabilize.py", shaky, "--tripod", "--crop", "black", "-o", out, "--json")
+ # CodeRabbit (#97): duration/dimensions alone don't prove the flags actually reached the
+ # filter graph -- an implementation that accepted but silently dropped them would still
+ # pass those checks. Inspect the recorded commands directly.
+ commands = json.loads(proc.stdout)["commands"]
+ self.assertTrue(any("vidstabdetect=" in c and ":tripod=1" in c for c in commands),
+ f"--tripod should reach vidstabdetect's own tripod option: {commands}")
+ self.assertTrue(any("vidstabtransform=" in c and ":crop=1" in c and ":tripod=1" in c for c in commands),
+ f"--tripod/--crop black should reach vidstabtransform's tripod/crop options: {commands}")
+ m = probe(str(out))
+ self.assertClose(m["duration"], 4.0, 0.3)
+ self.assertEqual(m["video"]["width"], 1280)
+ self.assertEqual(m["video"]["height"], 720)
+
+ def test_stabilize_bad_crop_refused(self):
+ script("stabilize.py", self.src, "--crop", "nonsense", expect_fail=True)
+
+ # ---------------------------------------------------------------- caption
+ def test_caption_text_to_srt_and_burn(self):
+ srt = OUT / "cues.srt"
+ out = OUT / "cap.mp4"
+ script("caption.py", self.src, "--text", self.cues, "--write-srt", srt, "--position", "top", "--bold", "-o", out)
+ text = srt.read_text(encoding="utf-8")
+ self.assertIn("00:00:03,000 --> 00:00:06,000", text)
+ self.assertIn("Second\nline", text)
+ self.assertIn("00:00:06,000 --> 00:00:09,000", text, "auto-timed cue follows previous")
+ m = probe(str(out))
+ self.assertClose(m["duration"], 12.0, 0.15)
+ self.assertEqual(m["video"]["width"], 1280)
+
+ def test_caption_wraps_a_long_latin_cue_to_the_safe_area(self):
+ """A 60-character cue at size 48 on a 640-wide frame does not fit one line; it is wrapped
+ to the safe area and, past --max-lines, split into consecutive cues rather than running
+ off the frame or covering the picture."""
+ import caption # noqa: E402 -- the wrap table under test
+ cues = OUT / "wrap_latin.txt"
+ text = "the quick brown fox jumps over the lazy dog and keeps runnin"
+ self.assertEqual(len(text), 60)
+ cues.write_text(f"0:00-0:04 {text}\n", encoding="utf-8")
+ srt = OUT / "wrap_latin.srt"
+ script("caption.py", self._small(), "--text", cues, "--size", "48", "--max-lines", "2",
+ "--write-srt", srt, "--fast", "-o", OUT / "wrap_latin.mp4")
+ blocks = self._srt_cues(srt)
+ self.assertGreater(len(blocks), 1, "60 characters at size 48 cannot fit 2 lines of a 640px frame")
+ max_em = 640 * caption.SAFE_WIDTH_FRACTION / (48 * 360 / 288.0)
+ for _, lines in blocks:
+ self.assertLessEqual(len(lines), 2, f"--max-lines 2 exceeded: {lines}")
+ for line in lines:
+ self.assertLessEqual(caption.text_width_em(line), max_em + 1e-6,
+ f"line wider than the safe area: {line!r}")
+ self.assertEqual(" ".join(l for _, lines in blocks for l in lines), text, "no word is lost or cut")
+
+ def test_caption_wraps_cjk_between_characters(self):
+ """Chinese has no spaces: the line breaks between any two characters, and every character
+ counts as a full em (Latin averages just over half)."""
+ import caption # noqa: E402
+ from _common import font_for_script # noqa: E402
+ if font_for_script("zh") is None:
+ self.skipTest("this machine has no font covering zh")
+ text = "你好世界这是一个很长的中文字幕需要换行处理的测试"
+ self.assertEqual(len(text), 24)
+ cues = OUT / "wrap_cjk.txt"
+ cues.write_text(f"0:00-0:04 {text}\n", encoding="utf-8")
+ srt = OUT / "wrap_cjk.srt"
+ proc = script("caption.py", self._small(), "--text", cues, "--size", "48", "--write-srt", srt,
+ "--fast", "-o", OUT / "wrap_cjk.mp4")
+ blocks = self._srt_cues(srt)
+ lines = [l for _, ls in blocks for l in ls]
+ self.assertGreater(len(lines), 1, "a 24-character CJK cue at size 48 must break")
+ max_em = 640 * caption.SAFE_WIDTH_FRACTION / (48 * 360 / 288.0)
+ for line in lines:
+ self.assertLessEqual(caption.text_width_em(line), max_em + 1e-6, line)
+ self.assertEqual("".join(lines), text, "no character is lost")
+ self.assertIn("font:", proc.stderr, "a Chinese cue resolves a font by script")
+ self.assertRegex(proc.stderr, r"cues: .*(wrapped|split)")
+
+ def test_caption_wrap_puts_mixed_script_text_back_exactly_as_written(self):
+ """A wrap must never change the text: CJK gains no spaces, and the author's own spaces
+ around a Latin word inside CJK survive."""
+ import caption # noqa: E402
+ for text in ("Hello 世界 this is mixed 混合文本 wrapping",
+ "你好世界这是一个很长的中文字幕",
+ "one two three four five six"):
+ with self.subTest(text=text):
+ lines = caption.wrap_text(text, 8)
+ self.assertGreater(len(lines), 1)
+ rebuilt = ""
+ for line in lines:
+ if not rebuilt:
+ rebuilt = line
+ elif text[len(rebuilt)] == " ":
+ rebuilt += " " + line
+ else:
+ rebuilt += line
+ self.assertEqual(rebuilt, text)
+
+ def test_caption_offset_shifts_every_cue_in_both_directions(self):
+ cues = OUT / "offset_cues.txt"
+ cues.write_text("0:02-0:04 one\n0:05-0:07 two\n", encoding="utf-8")
+ late = OUT / "offset_late.srt"
+ script("caption.py", "--text", cues, "--write-srt", late, "--offset", "1.5")
+ self.assertIn("00:00:03,500 --> 00:00:05,500", late.read_text(encoding="utf-8"))
+ early = OUT / "offset_early.srt"
+ script("caption.py", "--text", cues, "--write-srt", early, "--offset", "-1.5")
+ self.assertIn("00:00:00,500 --> 00:00:02,500", early.read_text(encoding="utf-8"))
+
+ def test_caption_offset_rewrites_a_copy_never_the_callers_srt(self):
+ """--offset on a hand-written SRT must not edit the file the user passed in."""
+ src_srt = OUT / "offset_source.srt"
+ src_srt.write_text("1\n00:00:02,000 --> 00:00:04,000\nhello\n\n", encoding="utf-8")
+ before = src_srt.read_text(encoding="utf-8")
+ out = OUT / "offset_burn.mp4"
+ proc = script("caption.py", self._small(), "--srt", src_srt, "--offset", "1.0", "--fast", "-o", out)
+ self.assertEqual(src_srt.read_text(encoding="utf-8"), before, "the caller's SRT is never edited in place")
+ adjusted = OUT / "offset_burn_adjusted.srt"
+ self.assertTrue(adjusted.exists(), proc.stderr)
+ self.assertIn("00:00:03,000 --> 00:00:05,000", adjusted.read_text(encoding="utf-8"))
+ self.assertIn(str(adjusted), proc.stderr)
+
+ def test_caption_min_duration_extends_a_flashed_cue_but_never_past_the_next(self):
+ cues = OUT / "min_dur_cues.txt"
+ cues.write_text("0:00-0:00.3 flash\n0:01-0:03 next\n", encoding="utf-8")
+ srt = OUT / "min_dur.srt"
+ proc = script("caption.py", "--text", cues, "--write-srt", srt, "--min-duration", "1.5")
+ text = srt.read_text(encoding="utf-8")
+ self.assertIn("00:00:00,000 --> 00:00:01,000", text, "extended up to the next cue's start, not over it")
+ self.assertIn("extended", proc.stderr)
+ loose = OUT / "min_dur_loose.srt"
+ script("caption.py", "--text", cues, "--write-srt", loose, "--min-duration", "0")
+ self.assertIn("00:00:00,000 --> 00:00:00,300", loose.read_text(encoding="utf-8"), "--min-duration 0 leaves cues alone")
+
+ def test_caption_karaoke_uses_whisper_word_timings_when_the_transcript_has_them(self):
+ """A whisper JSON next to the SRT carries real per-word start/end times; --karaoke must
+ follow them instead of splitting the cue evenly or guessing from audio energy."""
+ srt = OUT / "words.srt"
+ srt.write_text("1\n00:00:00,000 --> 00:00:04,000\nalpha beta gamma\n\n", encoding="utf-8")
+ (OUT / "words.json").write_text(json.dumps({"segments": [{"words": [
+ {"word": "alpha", "start": 0.0, "end": 0.5},
+ {"word": "beta", "start": 0.5, "end": 1.0},
+ {"word": "gamma", "start": 1.0, "end": 4.0}]}]}), encoding="utf-8")
+ ass = OUT / "words.ass"
+ proc = script("caption.py", self._small(), "--srt", srt, "--karaoke", "--write-ass", ass,
+ "--fast", "-o", OUT / "words.mp4")
+ self.assertIn("word timings", proc.stderr)
+ body = ass.read_text(encoding="utf-8-sig")
+ self.assertIn(r"{\kf50}alpha", body)
+ self.assertIn(r"{\kf50}beta", body)
+ self.assertIn(r"{\kf300}gamma", body)
+
+ def test_caption_brand_styles_caption_block_sets_the_look(self):
+ """brand.json's `styles.caption` is the documented 1.12 spelling, shared with graphics.py;
+ an explicit flag still beats it."""
+ brand = OUT / "brand_styles.json"
+ brand.write_text(json.dumps({"styles": {"caption": {
+ "font": "DejaVu Serif", "size": 33, "colour": "00FF00", "position": "top", "box": True}}}), encoding="utf-8")
+ ass = OUT / "brand_styles.ass"
+ script("caption.py", self._small(), "--text", self.cues, "--brand", brand, "--animate", "fade",
+ "--write-ass", ass, "--fast", "-o", OUT / "brand_styles.mp4")
+ style = next(l for l in ass.read_text(encoding="utf-8-sig").splitlines() if l.startswith("Style: Default"))
+ self.assertIn("DejaVu Serif", style)
+ self.assertIn("&H0000FF00", style, "colour (British spelling) is read")
+ self.assertEqual(style.split(",")[-5], "8", "position top -> ASS alignment 8")
+ self.assertEqual(style.split(",")[15], "3", "box -> BorderStyle 3")
+
+ def test_caption_non_latin_text_picks_a_font_that_covers_it(self):
+ """Korean, Chinese, Arabic and Thai cues burn with a font that has the glyphs: the run
+ exits 0, names the font file it chose, and the caption band actually gains ink (tofu
+ boxes would too, which is why the font file is asserted as well)."""
+ if _no_fontconfig():
+ self.skipTest("no fc-list on this machine: fonts cannot be resolved by script here")
+ small = self._small()
+ base = self._band_luma(small, OUT / "band_plain.png")
+ samples = {"ko": "안녕하세요 여러분", "zh": "你好世界大家好", "ar": "مرحبا بالعالم", "th": "สวัสดีชาวโลก"}
+ for lang, text in samples.items():
+ with self.subTest(lang=lang):
+ if font_for_script(lang) is None:
+ self.skipTest(f"this machine has no font covering {lang}")
+ cues = OUT / f"nl_{lang}.txt"
+ cues.write_text(f"0:00-0:04 {text}\n", encoding="utf-8")
+ out = OUT / f"nl_{lang}.mp4"
+ proc = script("caption.py", small, "--text", cues, "--lang", lang, "--size", "40",
+ "--fast", "-o", out)
+ m = probe(str(out))
+ self.assertEqual(m["video"]["width"], 640)
+ chosen = re.search(r"^font: (.+?) \(covers (\w+)\)", proc.stderr, re.M)
+ self.assertIsNotNone(chosen, proc.stderr)
+ self.assertTrue(os.path.exists(chosen.group(1)), chosen.group(1))
+ self.assertEqual(chosen.group(2), lang)
+ inked = self._band_luma(out, OUT / f"band_{lang}.png")
+ self.assertNotAlmostEqual(inked, base, delta=0.05,
+ msg=f"{lang}: the caption band is identical to the uncaptioned frame")
+
+ def test_graphics_and_overlay_pick_a_font_by_script_for_non_latin_text(self):
+ """drawtext renders a box per missing glyph and still exits 0; graphics.py and overlay.py
+ resolve a font that covers the text instead, and say which file they chose."""
+ if _no_fontconfig():
+ self.skipTest("no fc-list on this machine: fonts cannot be resolved by script here")
+ if font_for_script("ko") is None:
+ self.skipTest("this machine has no font covering ko")
+ gfx = OUT / "gfx_ko.mp4"
+ proc = script("graphics.py", self._small(), "--template", "lower-third", "--name", "김민준",
+ "--title", "감독", "--lang", "ko", "--preset", "veryfast", "-o", gfx, "--json")
+ chosen = re.search(r"^font: (.+?) \(covers ko\)", proc.stderr, re.M)
+ self.assertIsNotNone(chosen, proc.stderr)
+ self.assertIn(f"fontfile={escape_filter_path(chosen.group(1))}", json.loads(proc.stdout)["commands"][0])
+ ov = OUT / "overlay_ja.mp4"
+ proc2 = script("overlay.py", self._small(), "--text", "こんにちは世界", "--preset", "veryfast", "-o", ov, "--json")
+ chosen2 = re.search(r"^font: (.+?) \(covers ja\)", proc2.stderr, re.M)
+ self.assertIsNotNone(chosen2, proc2.stderr)
+ self.assertIn("fontfile=", json.loads(proc2.stdout)["commands"][0])
+
+ def test_an_explicit_font_is_kept_even_when_it_does_not_cover_the_script(self):
+ """A stated --font is the user's decision: it is warned about, never silently replaced."""
+ if _no_fontconfig():
+ self.skipTest("no fc-list on this machine")
+ cues = OUT / "explicit_font.txt"
+ cues.write_text("0:00-0:03 你好世界\n", encoding="utf-8")
+ proc = script("caption.py", self._small(), "--text", cues, "--font", "DejaVu Sans",
+ "--fast", "-o", OUT / "explicit_font.mp4")
+ self.assertIn("FontName=DejaVu Sans", " ".join(proc.stderr.splitlines()))
+ self.assertNotIn("(covers zh)", proc.stderr, "an explicit font is never replaced")
+ if shutil.which("fc-list"):
+ self.assertIn("does not cover", proc.stderr, "but the caller is told it will not render")
+ else:
+ # Windows resolves fonts by file name and has no fontconfig to ask: coverage is
+ # unknown, so keeping the font silently (no "does not cover" claim) is correct.
+ self.assertNotIn("does not cover", proc.stderr)
+
+ def test_no_font_for_the_script_is_a_failed_job_not_tofu(self):
+ """The whole point: a machine that cannot render the text refuses the job instead of
+ writing a video of empty boxes that ffmpeg reports as a success. Forced with an fc-list
+ that answers normally (exit 0) and lists nothing -- fontconfig saying "no font covers
+ this", which is what a bare container with fontconfig but no font files looks like."""
+ if platform.system() == "Windows":
+ self.skipTest("the shim below is a #!/bin/sh script; Windows resolves fonts by file name, not fontconfig")
+ shim = OUT / "nofc"
+ shim.mkdir(exist_ok=True)
+ (shim / "fc-list").write_text("#!/bin/sh\nexit 0\n")
+ (shim / "fc-list").chmod(0o755)
+ env = dict(os.environ, PATH=f"{shim}{os.pathsep}{os.environ['PATH']}")
+ cues = OUT / "no_font.txt"
+ cues.write_text("0:00-0:03 안녕하세요\n", encoding="utf-8")
+ proc = script("caption.py", self._small(), "--text", cues, "--json", "--fast",
+ "-o", OUT / "no_font.mp4", env=env, expect_fail=True)
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["status"], "failed")
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("Korean", doc["error"]["message"])
+ self.assertIn("--fonts-dir", doc["error"]["message"], "the message names a flag caption.py has")
+ self.assertNotIn("or pass --font-file", doc["error"]["message"], "caption.py has no --font-file")
+ self.assertFalse((OUT / "no_font.mp4").exists(), "nothing is written for a job that cannot be read")
+
+ def test_a_broken_or_absent_fontconfig_is_unknown_not_missing(self):
+ """`unknown` is not `missing` (the rule every other capability in this repo follows):
+ with no fc-list on PATH -- or one that fails -- coverage cannot be verified, so the job
+ runs with the caller's font (libass has its own font backend) behind one info line,
+ instead of refusing work that 1.11.1 rendered."""
+ if platform.system() == "Windows":
+ self.skipTest("the shim below is a #!/bin/sh script; Windows resolves fonts by file name, not fontconfig")
+ cues = OUT / "unknown_fc.txt"
+ cues.write_text("0:00-0:03 안녕하세요\n", encoding="utf-8")
+ broken = OUT / "brokenfc"
+ broken.mkdir(exist_ok=True)
+ (broken / "fc-list").write_text("#!/bin/sh\nexit 1\n")
+ (broken / "fc-list").chmod(0o755)
+ empty = OUT / "nobin"
+ empty.mkdir(exist_ok=True)
+ for tool in ("ffmpeg", "ffprobe"):
+ link = empty / tool
+ if not link.exists():
+ link.symlink_to(shutil.which(tool))
+ cases = {
+ "fc-list fails": dict(os.environ, PATH=f"{broken}{os.pathsep}{os.environ['PATH']}"),
+ "no fc-list at all": dict(os.environ, PATH=str(empty)),
+ }
+ for label, env in cases.items():
+ with self.subTest(case=label):
+ out = OUT / "unknown_fc.mp4"
+ proc = script("caption.py", self._small(), "--text", cues, "--json", "--fast",
+ "-o", out, env=env)
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["status"], "completed", proc.stderr)
+ self.assertIn("could not verify", proc.stderr)
+ self.assertNotIn("no installed font covers", proc.stderr)
+ self.assertIn("FontName=DejaVu Sans", " ".join(doc["commands"]),
+ "the caller's font stands when coverage is unknown")
+
+ def test_caption_dry_run_plans_the_same_file_the_real_run_burns(self):
+ """--dry-run/--plan must describe the job the real run executes: when --offset/--max-lines/
+ --min-duration adjust a hand-written SRT, the planned command names the adjusted copy (the
+ file the real run burns), the plan document says where it comes from, and no side file is
+ written under a dry run."""
+ src_srt = OUT / "plan_parity.srt"
+ src_srt.write_text("1\n00:00:01,000 --> 00:00:01,300\nflash\n\n"
+ "2\n00:00:02,000 --> 00:00:04,000\n"
+ "this is a very long caption line that certainly needs wrapping here\n\n",
+ encoding="utf-8")
+ out = OUT / "plan_parity.mp4"
+ adjusted = OUT / "plan_parity_adjusted.srt"
+ if adjusted.exists():
+ adjusted.unlink()
+ plan = OUT / "plan_parity.json"
+ proc = script("caption.py", self._small(), "--srt", src_srt, "--size", "48",
+ "-o", out, "--plan", plan)
+ doc = json.loads(plan.read_text(encoding="utf-8"))
+ planned = [c for c in doc["commands"] if "-vf" in c]
+ self.assertTrue(planned, doc["commands"])
+ # the filter string escapes the path (Windows: `D\\:/a/...`), so match the file name
+ self.assertIn(adjusted.name, planned[0], "the plan burns the adjusted copy, not the caller's file")
+ self.assertNotIn(src_srt.name, planned[0])
+ self.assertTrue(any(str(adjusted) in n for n in doc.get("notes") or []),
+ f"the plan records the side file: {doc.get('notes')}")
+ self.assertFalse(adjusted.exists(), "a dry run writes no side file")
+ real = script("caption.py", self._small(), "--srt", src_srt, "--size", "48",
+ "--fast", "-o", out, "--json")
+ self.assertTrue(adjusted.exists(), real.stderr)
+ burned = [c for c in json.loads(real.stdout)["commands"] if "-vf" in c]
+ self.assertIn(adjusted.name, burned[0], "the real run burns the file the plan named")
+
+ def test_caption_never_breaks_before_a_combining_mark(self):
+ """Thai tone marks and vowel signs, Devanagari matras, Arabic and Hebrew points are their
+ own code points: a line may never start with one, and they advance the pen by nothing."""
+ import caption # noqa: E402
+ import unicodedata
+ for text in ("กิ้น" * 6, "मैंने" * 6, "مَرْحَبًا " * 4, "שָׁלוֹם " * 4):
+ with self.subTest(text=text[:8]):
+ for width in (1.5, 3.0, 6.0):
+ for line in caption.wrap_text(text, width):
+ first = line[0]
+ self.assertEqual(unicodedata.combining(first), 0, f"line starts with a mark: {line!r}")
+ self.assertNotIn(unicodedata.category(first), ("Mn", "Mc"), f"line starts with a mark: {line!r}")
+ self.assertEqual("".join(caption.wrap_text(text, 3.0)).replace(" ", ""),
+ text.replace(" ", ""), "no character is lost")
+ self.assertEqual(caption.text_width_em("\u0e01\u0e34\u0e49"), caption.text_width_em("\u0e01"),
+ "a combining mark is charged no width")
+ self.assertEqual(caption.wrap_text("เก", 10.0), ["เก"], "a leading Thai vowel stays with its consonant")
+
+ def test_caption_offset_takes_the_skills_time_grammar(self):
+ """SKILL.md lists --offset among the timestamp flags: mm:ss and hh:mm:ss(.fff) work,
+ signed, and a bad value is a `kind: input` refusal document, not an argparse dump."""
+ cues = OUT / "offset_grammar.txt"
+ cues.write_text("0:05-0:07 one\n", encoding="utf-8")
+ for value, expected in (("0:02", "00:00:07,000 --> 00:00:09,000"),
+ ("-0:00:02.500", "00:00:02,500 --> 00:00:04,500"),
+ ("00:00:01:15@30", "00:00:06,500 --> 00:00:08,500")):
+ with self.subTest(offset=value):
+ srt = OUT / "offset_grammar.srt"
+ script("caption.py", "--text", cues, "--write-srt", srt, "--offset", value)
+ self.assertIn(expected, srt.read_text(encoding="utf-8"))
+ proc = script("caption.py", "--text", cues, "--write-srt", OUT / "offset_bad.srt",
+ "--offset", "half past two", "--json", expect_fail=True)
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["status"], "failed")
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("--offset", doc["error"]["message"])
+
+ def test_caption_max_lines_holds_for_all_caps_text(self):
+ """Uppercase is far wider than the mixed-case average: an all-caps cue must be measured
+ with a per-character table, or libass re-wraps each line the wrapper produced and four
+ lines are drawn where --max-lines 2 was asked for."""
+ import caption # noqa: E402
+ text = "WE MEASURE EVERY CAPITAL LETTER BECAUSE UPPERCASE RUNS WIDE"
+ cues = OUT / "caps_cue.txt"
+ cues.write_text(f"0:01-0:05 {text}\n", encoding="utf-8")
+ srt = OUT / "caps_cue.srt"
+ script("caption.py", self._small(), "--text", cues, "--size", "48", "--max-lines", "2",
+ "--write-srt", srt, "--fast", "-o", OUT / "caps_cue.mp4")
+ max_em = 640 * caption.SAFE_WIDTH_FRACTION / (48 * 360 / 288.0)
+ blocks = self._srt_cues(srt)
+ for _, lines in blocks:
+ self.assertLessEqual(len(lines), 2, f"--max-lines 2 exceeded: {lines}")
+ # The real DejaVu Sans advances (hmtx/unitsPerEm, unrounded), not caption.py's own table:
+ # what libass will actually draw has to fit, or it re-wraps the line and --max-lines 2
+ # becomes four lines in the picture.
+ real = {"A": .684, "B": .686, "C": .698, "D": .770, "E": .632, "F": .575, "G": .775,
+ "H": .752, "I": .295, "J": .295, "K": .656, "L": .557, "M": .863, "N": .748,
+ "O": .787, "P": .603, "Q": .787, "R": .695, "S": .635, "T": .611, "U": .732,
+ "V": .684, "W": .989, "X": .685, "Y": .611, "Z": .685, " ": .318}
+ for _, lines in blocks:
+ for line in lines:
+ drawn = sum(real[ch] for ch in line)
+ self.assertLessEqual(drawn, max_em, f"libass would re-wrap this line: {line!r}")
+ self.assertEqual(" ".join(l for _, lines in blocks for l in lines), text)
+ self.assertGreater(caption.text_width_em("CAPITALS"), caption.text_width_em("capitals"))
+
+ def test_a_resolved_font_path_with_spaces_survives_into_the_command(self):
+ """macOS resolves "/Library/Fonts/Arial Unicode.ttf": a space in the font path must not
+ split the info line, the drawtext `fontfile=`, or the libass `fontsdir=`."""
+ import _common # noqa: E402
+ spaced_dir = OUT / "font dir"
+ spaced_dir.mkdir(exist_ok=True)
+ source = default_font_file("DejaVu Sans")
+ if not source or not os.path.exists(source):
+ self.skipTest("no concrete font file on this machine to copy")
+ spaced = spaced_dir / "My Font.ttf"
+ shutil.copyfile(source, spaced)
+
+ # the resolver's own answer and the line it prints keep the path whole
+ entry = (str(spaced), "My Font")
+ saved = dict(_common._SCRIPT_FONT_CACHE)
+ try:
+ _common._SCRIPT_FONT_CACHE[("ko", None)] = entry
+ with contextlib.redirect_stderr(io.StringIO()): # the resolver's own info line
+ _script, resolved, family = _common.script_font_for_text("안녕하세요")
+ finally:
+ _common._SCRIPT_FONT_CACHE.clear()
+ _common._SCRIPT_FONT_CACHE.update(saved)
+ self.assertEqual(resolved, str(spaced))
+ self.assertEqual(family, "My Font")
+ line = f"font: {resolved} (covers ko)"
+ self.assertEqual(re.search(r"^font: (.+?) \(covers (\w+)\)", line, re.M).group(1), str(spaced),
+ "the info line's path is read whole, not up to the first space")
+
+ # and the same path reaches ffmpeg as one argument in both draw paths
+ proc = script("overlay.py", self._small(), "--text", "spaced", "--font-file", spaced,
+ "--preset", "veryfast", "-o", OUT / "spaced_overlay.mp4", "--json")
+ cmd = json.loads(proc.stdout)["commands"][0]
+ self.assertIn(f"fontfile={escape_filter_path(str(spaced))}", cmd)
+ cues = OUT / "spaced_cue.txt"
+ cues.write_text("0:00-0:02 spaced\n", encoding="utf-8")
+ proc2 = script("caption.py", self._small(), "--text", cues, "--fonts-dir", spaced_dir,
+ "--fast", "-o", OUT / "spaced_caption.mp4", "--json")
+ self.assertIn(f"fontsdir={escape_filter_path(str(spaced_dir))}", json.loads(proc2.stdout)["commands"][0])
+
+ def test_caption_srt_only(self):
+ srt = OUT / "only.srt"
+ proc = script("caption.py", "--text", self.cues, "--write-srt", srt)
+ self.assertTrue(srt.exists())
+ self.assertEqual(proc.stdout.strip(), str(srt))
+
+ def test_caption_srt_lands_next_to_output_not_source(self):
+ sub = OUT / "capdir"
+ sub.mkdir(exist_ok=True)
+ out = sub / "cap_side.mp4"
+ script("caption.py", self.src, "--text", self.cues, "--preset", "veryfast", "-o", out)
+ self.assertTrue((sub / "cap_side.srt").exists(), "SRT written beside the output")
+ self.assertFalse((OUT / "source.srt").exists(), "no SRT dropped next to the source")
+
+ def test_caption_smpte_timecode_cues_convert_frames_to_seconds(self):
+ tc = OUT / "tc_cues.txt"
+ tc.write_text("00:00:00:12 --> 00:00:02:00 Hello\n00:00:02:00 --> 00:00:04:00 World\n", encoding="utf-8")
+ srt = OUT / "tc.srt"
+ script("caption.py", "--text", tc, "--write-srt", srt, "--fps", "24")
+ text = srt.read_text(encoding="utf-8")
+ self.assertIn("00:00:00,500 --> 00:00:02,000", text, "frame 12 at 24fps is exactly 0.5s")
+
+ def test_caption_smpte_timecode_without_fps_fails_loudly(self):
+ """A cue that looks like hh:mm:ss:ff but has no --fps must not be silently swallowed as auto-timed text."""
+ tc = OUT / "tc_no_fps.txt"
+ tc.write_text("00:00:00:12 --> 00:00:02:00 Hello\n", encoding="utf-8")
+ proc = script("caption.py", "--text", tc, "--write-srt", OUT / "tc_no_fps.srt", "--json", expect_fail=True)
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("fps", doc["error"]["message"])
+ self.assertFalse((OUT / "tc_no_fps.srt").exists())
+
+ def test_caption_fps_defaults_to_the_input_videos_own_fps(self):
+ tc = OUT / "tc_auto_fps.txt"
+ tc.write_text("00:00:00:15 --> 00:00:02:00 Hello\n", encoding="utf-8")
+ out = OUT / "tc_auto.mp4"
+ script("caption.py", self.src, "--text", tc, "-o", out, "--preset", "veryfast")
+ srt_text = (OUT / "tc_auto.srt").read_text(encoding="utf-8")
+ # self.src is 30fps: frame 15 is exactly 0.5s
+ self.assertIn("00:00:00,500 --> 00:00:02,000", srt_text)
+
+ def test_caption_mux_copies_streams_and_adds_a_subtitle_track(self):
+ srt = OUT / "mux_cues.srt"
+ out = OUT / "cap_mux.mp4"
+ script("caption.py", self.src, "--text", self.cues, "--write-srt", srt, "--mode", "mux", "-o", out)
+ m = probe(str(out))
+ self.assertEqual(m["subtitle_streams"], 1)
+ self.assertEqual(m["video"]["codec"], "h264", "video must be copied, not re-encoded to a different codec")
+ self.assertEqual(m["audio"]["codec"], "aac", "audio must be copied untouched")
+ self.assertClose(m["duration"], 12.0, 0.15)
+
+ def test_caption_mux_chained_keeps_every_language_track(self):
+ """--mode mux used to drop any subtitle track the input already had when adding a new
+ one (its map list never included 0:s?), so chaining it once per language -- the natural
+ way to build a multi-language subtitle set (e.g. an English track, then a Japanese one)
+ -- silently lost every earlier language but the last (#93). Each call must now keep what
+ was already there."""
+ srt_en = OUT / "mux_chain_en.srt"
+ srt_en.write_text("1\n00:00:00,000 --> 00:00:02,000\nHello\n", encoding="utf-8")
+ srt_ja = OUT / "mux_chain_ja.srt"
+ srt_ja.write_text("1\n00:00:00,000 --> 00:00:02,000\nこんにちは\n", encoding="utf-8")
+ step1 = OUT / "cap_mux_chain1.mkv"
+ script("caption.py", self.src, "--srt", srt_en, "--mode", "mux", "--language", "en", "-o", step1)
+ step2 = OUT / "cap_mux_chain2.mkv"
+ script("caption.py", step1, "--srt", srt_ja, "--mode", "mux", "--language", "ja", "-o", step2)
+ m = probe(str(step2))
+ self.assertEqual(m["subtitle_streams"], 2)
+ langs = sh("ffprobe", "-v", "error", "-select_streams", "s", "-show_entries", "stream_tags=language",
+ "-of", "csv=p=0", step2).stdout.split()
+ self.assertEqual(langs, ["en", "ja"])
+ self.assertEqual(m["video"]["codec"], "h264", "video must stay copied through both chained calls")
+ self.assertEqual(m["audio"]["codec"], "aac", "audio must stay copied through both chained calls")
+
+ def test_caption_mux_picks_the_subtitle_codec_from_the_container(self):
+ srt = OUT / "mux_container_cues.srt"
+ script("caption.py", "--text", self.cues, "--write-srt", srt)
+ for ext, expect_codec in ((".mp4", "mov_text"), (".mkv", "subrip")):
+ out = OUT / f"cap_mux{ext}"
+ script("caption.py", self.src, "--srt", srt, "--mode", "mux", "-o", out)
+ streams = sh("ffprobe", "-v", "error", "-select_streams", "s", "-show_entries", "stream=codec_name",
+ "-of", "csv=p=0", out).stdout.strip()
+ self.assertEqual(streams, expect_codec, f"{ext} output")
+
+ def test_caption_mux_refuses_ass_and_animation(self):
+ script("caption.py", self.src, "--ass", "/nonexistent.ass", "--mode", "mux", "-o", OUT / "x.mp4", expect_fail=True)
+ srt = OUT / "mux_refuse_cues.srt"
+ script("caption.py", "--text", self.cues, "--write-srt", srt)
+ script("caption.py", self.src, "--srt", srt, "--mode", "mux", "--karaoke", "-o", OUT / "x2.mp4", expect_fail=True)
+
+ def test_caption_mux_refuses_an_unrecognized_container(self):
+ srt = OUT / "mux_avi_cues.srt"
+ script("caption.py", "--text", self.cues, "--write-srt", srt)
+ script("caption.py", self.src, "--srt", srt, "--mode", "mux", "-o", OUT / "x.avi", expect_fail=True)
+
+ def test_caption_audio_stream_selects_the_requested_track_not_always_the_first(self):
+ two = OUT / "cap_two_streams.mkv"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
+ "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
+ "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
+ self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
+ cue = OUT / "cap_two_cue.txt"
+ cue.write_text("0:00-0:02 Hello\n", encoding="utf-8")
+ # mux mode: the picked track survives a stream copy untouched, verified by its own probed sample rate
+ out_mux = OUT / "cap_two_mux.mp4"
+ script("caption.py", two, "--text", cue, "--audio-stream", "1", "--mode", "mux", "-o", out_mux, "--write-srt", OUT / "cap_two_mux.srt")
+ self.assertEqual(probe(str(out_mux))["audio"]["sample_rate"], 44100, "mux must keep the requested track (index 1), not default to index 0")
+ # burn mode: the picked track survives re-encoding to AAC too (sample rate normally changes on re-encode,
+ # so compare against the same tool re-encoding the default track 0 instead)
+ out_burn1 = OUT / "cap_two_burn1.mp4"
+ script("caption.py", two, "--text", cue, "--audio-stream", "1", "-o", out_burn1, "--preset", "veryfast")
+ out_burn0 = OUT / "cap_two_burn0.mp4"
+ script("caption.py", two, "--text", cue, "-o", out_burn0, "--preset", "veryfast")
+ # both re-encode to AAC, but decoding each and comparing peak frequency would be overkill here --
+ # the -map argument itself is what this test protects, already proven correct in mux mode above;
+ # this just confirms burn mode doesn't crash or silently drop audio when --audio-stream is given
+ self.assertIsNotNone(probe(str(out_burn1))["audio"])
+ self.assertIsNotNone(probe(str(out_burn0))["audio"])
+
+ def test_caption_audio_stream_out_of_range_refused(self):
+ cue = OUT / "cap_range_cue.txt"
+ cue.write_text("0:00-0:02 Hello\n", encoding="utf-8")
+ proc = script("caption.py", self.src, "--text", cue, "--audio-stream", "5", "-o", OUT / "x.mp4", "--json", expect_fail=True)
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("audio-stream", doc["error"]["message"])
+
+ # ---------------------------------------------------------------- overlay
+ def test_overlay_image_and_text(self):
+ out1 = OUT / "ov_img.mp4"
+ script("overlay.py", self.src, "--image", self.logo, "--position", "top-right", "--scale", "200",
+ "--opacity", "0.8", "--start", "1", "--end", "5", "--fade", "0.5", "-o", out1)
+ m = probe(str(out1))
+ self.assertClose(m["duration"], 12.0, 0.2)
+ self.assertIsNotNone(m["audio"], "audio must be kept")
+ out2 = OUT / "ov_txt.mp4"
+ script("overlay.py", self.src, "--text", "Episode 12", "--position", "bottom", "--box", "--start", "1", "--end", "5", "--fade", "0.3", "-o", out2)
+ self.assertClose(probe(str(out2))["duration"], 12.0, 0.15)
+
+ def test_hdr_to_sdr_tonemap(self):
+ out = OUT / "sdr.mp4"
+ script("color.py", self.hdr, "--to-sdr", "--preset", "veryfast", "-o", out)
+ v = probe(str(out))["video"]
+ self.assertFalse(v["hdr"])
+ self.assertEqual((v["color_transfer"], v["color_primaries"], v["pix_fmt"]), ("bt709", "bt709", "yuv420p"))
+ self.assertEqual((v["width"], v["height"]), (1920, 1080))
+ # refuses on SDR input unless forced
+ script("color.py", self.src, "--to-sdr", expect_fail=True)
+
+ def test_color_retag_is_stream_copy(self):
+ out = OUT / "retag.mp4"
+ proc = script("color.py", self.src, "--retag", "bt601", "-o", out)
+ self.assertIn("-c copy", proc.stderr)
+ self.assertEqual(probe(str(out))["video"]["color_transfer"], "smpte170m")
+
+ def test_color_audio_stream_selects_the_requested_track_not_always_the_first(self):
+ two = OUT / "color_two_streams.mkv"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
+ "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
+ "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
+ self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
+ out1 = OUT / "color_two_correct1.mp4"
+ script("color.py", two, "--correct", "--exposure", "0.2", "--audio-stream", "1", "-o", out1, "--preset", "veryfast")
+ self.assertIsNotNone(probe(str(out1))["audio"])
+ proc = script("color.py", two, "--correct", "--audio-stream", "5", "-o", OUT / "color_nope.mp4", "--json", expect_fail=True)
+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
+ self.assertIn("audio-stream", proc.stderr)
+
+ def test_color_lut(self):
+ lut = OUT / "invert.cube"
+ lines = ["LUT_3D_SIZE 2"]
+ for b in (0, 1):
+ for g in (0, 1):
+ for r in (0, 1):
+ lines.append(f"{1 - r} {1 - g} {1 - b}")
+ lut.write_text("\n".join(lines) + "\n")
+ out = OUT / "lut.mp4"
+ script("color.py", self.src, "--lut", lut, "--lut-strength", "0.5", "--preset", "veryfast", "-o", out)
+ self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
+
+ def test_color_lut_strength_zero_means_no_lut_and_out_of_range_is_refused(self):
+ """--lut-strength's blend branch only fired for the OPEN interval (0, 1); anything outside
+ it -- including exactly 0, and any value > 1 or < 0 -- fell into the "apply at full
+ strength" fallback with the number silently discarded. --lut-strength 0 is documented as
+ "blend graded and original, 0..1" -- 0 should mean the original, unmodified picture, not a
+ 100%-strength grade (the opposite of what was asked). Verify 0 now leaves the picture
+ untouched, and an out-of-range value is refused instead of silently applying full strength."""
+ lut = OUT / "invert_strength.cube"
+ lines = ["LUT_3D_SIZE 2"]
+ for b in (0, 1):
+ for g in (0, 1):
+ for r in (0, 1):
+ lines.append(f"{1 - r} {1 - g} {1 - b}")
+ lut.write_text("\n".join(lines) + "\n")
+ zero = OUT / "lut_zero.mp4"
+ script("color.py", self.src, "--lut", lut, "--lut-strength", "0", "--preset", "veryfast", "-o", zero)
+ self.assertGreater(self._psnr(self.src, zero), 40, "--lut-strength 0 must leave the picture unchanged, not fully inverted")
+ self.assertEqual(self._frame_count(zero), self._frame_count(self.src), "no frame may be dropped or duplicated by a no-op grade")
+ script("color.py", self.src, "--lut", lut, "--lut-strength", "2.5", "-o", OUT / "lut_oob.mp4", expect_fail=True)
+ script("color.py", self.src, "--lut", lut, "--lut-strength", "-1", "-o", OUT / "lut_oob2.mp4", expect_fail=True)
+
+ def test_color_correct_identity_holds_on_a_bt709_tagged_source(self):
+ """#159: the identity test below only ever ran on the untagged synthetic source. On a
+ source *tagged* bt709 (any camera file, anything export.py wrote) an all-defaults
+ --correct came back 26 dB PSNR and ~8 % less saturated, because libavfilter's auto-
+ inserted swscale legs around the RGB filters disagreed: yuv->rgb honoured the frame's
+ bt709 tag, rgb->yuv used the default bt601. Both legs are now pinned to one matrix, so
+ the result is the same on a tagged and an untagged copy of the same pixels, on FFmpeg
+ 5.1 through 8.1 (measured 39.5 dB on all four)."""
+ tagged = OUT / "correct_src709.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", str(self.src), "-t", "3",
+ "-vf", "setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv",
+ "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", "-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709", "-an", str(tagged))
+ self.assertEqual(probe(str(tagged))["video"]["color_space"], "bt709")
+ untagged = OUT / "correct_srcU.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", str(self.src), "-t", "3", "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", "-an", str(untagged))
+ results = {}
+ for name, src in (("tagged", tagged), ("untagged", untagged)):
+ out = OUT / f"correct_identity_{name}.mp4"
+ data = json.loads(script("color.py", src, "--correct", "--preset", "veryfast", "-o", out, "--json").stdout)
+ m = data["measurements"]
+ self.assertAlmostEqual(m["input"]["saturation_avg"], m["output"]["saturation_avg"], delta=2.5, msg=name)
+ results[name] = self._psnr(src, out)
+ self.assertGreater(results[name], 36, f"{name}: an all-defaults --correct must be near-identity, got {results[name]:.1f} dB")
+ self.assertAlmostEqual(results["tagged"], results["untagged"], delta=1.0, msg="the colour tag must not change what --correct does to the pixels")
+
+ def test_color_correct_defaults_are_near_identity(self):
+ out = OUT / "correct_neutral.mp4"
+ data = json.loads(script("color.py", self.src, "--correct", "--preset", "veryfast", "-o", out, "--json").stdout)
+ m = data["measurements"]
+ self.assertIn("y_avg", m["input"])
+ self.assertAlmostEqual(m["input"]["y_avg"], m["output"]["y_avg"], delta=2.0)
+ self.assertAlmostEqual(m["input"]["saturation_avg"], m["output"]["saturation_avg"], delta=2.0)
+ v = probe(str(out))["video"]
+ self.assertEqual((v["width"], v["height"]), (1280, 720))
+
+ def test_color_correct_exposure_and_saturation_change_measured_levels(self):
+ brighter = OUT / "correct_bright.mp4"
+ data = json.loads(script("color.py", self.src, "--correct", "--exposure", "0.6", "--preset", "veryfast", "-o", brighter, "--json").stdout)
+ m = data["measurements"]
+ self.assertGreater(m["output"]["y_avg"], m["input"]["y_avg"], "positive exposure must raise measured luma")
+
+ gray = OUT / "correct_gray.mp4"
+ data2 = json.loads(script("color.py", self.src, "--correct", "--saturation", "0", "--preset", "veryfast", "-o", gray, "--json").stdout)
+ m2 = data2["measurements"]
+ self.assertLess(m2["output"]["saturation_avg"], m2["input"]["saturation_avg"], "saturation 0 must desaturate")
+ self.assertLess(m2["output"]["saturation_avg"], 5.0, "saturation 0 must be close to grayscale")
+
+ def test_color_correct_temperature_and_tint_run_and_preserve_geometry(self):
+ out = OUT / "correct_wb.mp4"
+ script("color.py", self.src, "--correct", "--temperature", "3200", "--tint", "-0.3", "--contrast", "1.1", "--preset", "veryfast", "-o", out)
+ v = probe(str(out))["video"]
+ self.assertEqual((v["width"], v["height"]), (1280, 720))
+ self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
+
+ def test_color_correct_rejects_out_of_safe_range_parameters(self):
+ for flag, bad in (("--exposure", "5"), ("--contrast", "3"), ("--saturation", "-1"), ("--temperature", "40000"), ("--tint", "2")):
+ out = OUT / "correct_reject.mp4"
+ proc = script("color.py", self.src, "--correct", flag, bad, "-o", out, expect_fail=True)
+ self.assertIn("outside", proc.stderr, f"{flag} {bad} should be refused as out of range")
+ self.assertFalse(out.exists(), f"{flag} {bad}: no partial output on refusal")
+
+ def test_color_correct_gamma_changes_measured_luma(self):
+ brighter = OUT / "correct_gamma_up.mp4"
+ data = json.loads(script("color.py", self.src, "--correct", "--gamma", "1.6", "--preset", "veryfast", "-o", brighter, "--json").stdout)
+ m = data["measurements"]
+ self.assertGreater(m["output"]["y_avg"], m["input"]["y_avg"], "gamma > 1 must raise measured luma")
+
+ darker = OUT / "correct_gamma_down.mp4"
+ data2 = json.loads(script("color.py", self.src, "--correct", "--gamma", "0.5", "--preset", "veryfast", "-o", darker, "--json").stdout)
+ m2 = data2["measurements"]
+ self.assertLess(m2["output"]["y_avg"], m2["input"]["y_avg"], "gamma < 1 must lower measured luma")
+
+ def test_color_correct_lift_and_gain_run_and_shift_measured_levels(self):
+ lifted = OUT / "correct_lift.mp4"
+ data = json.loads(script("color.py", self.src, "--correct", "--lift", "0.3", "--preset", "veryfast", "-o", lifted, "--json").stdout)
+ m = data["measurements"]
+ self.assertGreater(m["output"]["y_min"], m["input"]["y_min"], "positive lift must raise the shadow floor")
+
+ gained = OUT / "correct_gain.mp4"
+ data2 = json.loads(script("color.py", self.src, "--correct", "--gain", "-0.3", "--preset", "veryfast", "-o", gained, "--json").stdout)
+ m2 = data2["measurements"]
+ self.assertLess(m2["output"]["y_avg"], m2["input"]["y_avg"], "negative gain must dim the highlights and lower measured luma")
+ v = probe(str(gained))["video"]
+ self.assertEqual((v["width"], v["height"]), (1280, 720))
+
+ def test_color_correct_levels_narrows_measured_dynamic_range(self):
+ out = OUT / "correct_levels_out.mp4"
+ data = json.loads(script("color.py", self.src, "--correct", "--levels-out-black", "64", "--levels-out-white", "192",
+ "--preset", "veryfast", "-o", out, "--json").stdout)
+ m = data["measurements"]
+ # colorlevels' output remap is an affine map into [romin, romax]: no output pixel can fall
+ # outside it (mod encoder rounding), so this is a mathematical guarantee, not a content guess.
+ self.assertGreaterEqual(m["output"]["y_min"], 64 - 3, "--levels-out-black 64 must floor the output near 64")
+ self.assertLessEqual(m["output"]["y_max"], 192 + 3, "--levels-out-white 192 must ceiling the output near 192")
+ self.assertLess(m["output"]["y_max"] - m["output"]["y_min"], m["input"]["y_max"] - m["input"]["y_min"],
+ "narrowing the output levels must narrow the measured dynamic range")
+
+ out2 = OUT / "correct_levels_in.mp4"
+ script("color.py", self.src, "--correct", "--levels-in-black", "16", "--levels-in-white", "235", "--preset", "veryfast", "-o", out2)
+ v = probe(str(out2))["video"]
+ self.assertEqual((v["width"], v["height"]), (1280, 720))
+ self.assertClose(probe(str(out2))["duration"], 12.0, 0.2)
+
+ # an all-default --levels-* call must not add a colorlevels term to the chain
+ neutral_chain = script("color.py", self.src, "--correct", "--dry-run").stderr
+ self.assertNotIn("colorlevels", neutral_chain)
+
+ def test_color_correct_curves_preset_runs_and_preserves_geometry(self):
+ out = OUT / "correct_curves.mp4"
+ script("color.py", self.src, "--correct", "--curves", "medium_contrast", "--preset", "veryfast", "-o", out)
+ v = probe(str(out))["video"]
+ self.assertEqual((v["width"], v["height"]), (1280, 720))
+ self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
+ # omitting --curves must not add a curves term to the chain
+ neutral_chain = script("color.py", self.src, "--correct", "--dry-run").stderr
+ self.assertNotIn("curves=", neutral_chain)
+ proc = script("color.py", self.src, "--correct", "--curves", "not-a-real-preset", "-o", OUT / "correct_curves_bad.mp4", expect_fail=True)
+ self.assertIn("invalid choice", proc.stderr)
+
+ def test_color_correct_rejects_new_flags_out_of_range(self):
+ for flag, bad in (("--gamma", "0.05"), ("--gamma", "11"), ("--lift", "-1.5"), ("--gain", "1.5")):
+ out = OUT / "correct_reject_new.mp4"
+ proc = script("color.py", self.src, "--correct", flag, bad, "-o", out, expect_fail=True)
+ self.assertIn("outside", proc.stderr, f"{flag} {bad} should be refused as out of range")
+ self.assertFalse(out.exists(), f"{flag} {bad}: no partial output on refusal")
+
+ out = OUT / "correct_reject_levels_in.mp4"
+ proc = script("color.py", self.src, "--correct", "--levels-in-black", "200", "--levels-in-white", "100", "-o", out, expect_fail=True)
+ self.assertIn("must be less than", proc.stderr)
+ self.assertFalse(out.exists())
+
+ out2 = OUT / "correct_reject_levels_out.mp4"
+ proc2 = script("color.py", self.src, "--correct", "--levels-out-black", "200", "--levels-out-white", "100", "-o", out2, expect_fail=True)
+ self.assertIn("must be less than", proc2.stderr)
+ self.assertFalse(out2.exists())
+
+ def test_caption_animated_karaoke_ass(self):
+ out = OUT / "karaoke.mp4"
+ ass = OUT / "karaoke.ass"
+ script("caption.py", self.src, "--text", self.cues, "--animate", "pop", "--karaoke", "--write-ass", ass, "--preset", "veryfast", "-o", out)
+ text = ass.read_text(encoding="utf-8-sig")
+ self.assertIn("PlayResX: 1280", text)
+ self.assertIn("\\kf", text)
+ self.assertIn("\\fscx", text)
+ self.assertEqual(text.count("Dialogue:"), 3)
+ self.assertClose(probe(str(out))["duration"], 12.0, 0.2)
+ # from an existing SRT too
+ srt = OUT / "cues.srt"
+ if not srt.exists():
+ script("caption.py", "--text", self.cues, "--write-srt", srt)
+ out2 = OUT / "fade.mp4"
+ script("caption.py", self.src, "--srt", srt, "--animate", "fade", "--preset", "veryfast", "-o", out2)
+ self.assertTrue((OUT / "fade.ass").exists())
+
+ def test_karaoke_energy_timing_follows_audio(self):
+ gappy = OUT / "gappy_k.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*lt(t\\,2)':s=48000",
+ "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=30", "-t", "4", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", gappy)
+ cues = OUT / "kcues.txt"
+ cues.write_text("0:00-0:04 one two three four\n", encoding="utf-8")
+ ass = OUT / "ke.ass"
+ script("caption.py", gappy, "--text", cues, "--karaoke", "--write-ass", ass, "--fast", "-o", OUT / "ke.mp4")
+ line = [l for l in ass.read_text(encoding="utf-8-sig").splitlines() if l.startswith("Dialogue")][0]
+ durs = [int(x) for x in re.findall(r"\\kf(\d+)", line)]
+ self.assertEqual(len(durs), 4)
+ self.assertEqual(sum(durs), 400)
+ self.assertLess(sum(durs[:3]), 200, "first three words should sit inside the 2 s of sound")
+ ass2 = OUT / "ke_even.ass"
+ script("caption.py", gappy, "--text", cues, "--karaoke", "--karaoke-timing", "even", "--write-ass", ass2, "--fast", "-o", OUT / "ke2.mp4")
+ line2 = [l for l in ass2.read_text(encoding="utf-8-sig").splitlines() if l.startswith("Dialogue")][0]
+ self.assertEqual([int(x) for x in re.findall(r"\\kf(\d+)", line2)], [100, 100, 100, 100])
+
+ # ---------------------------------------------------------------- colour-flag filter-graph injection (adversarial)
+ def test_color_like_flags_refuse_filter_graph_injection(self):
+ """Every flag that string-formats a colour straight into a filter graph (color=c=...,
+ tpad=...:color=..., rotate=...:fillcolor=..., drawtext=...:fontcolor=..., pad=...:color=...)
+ used to accept any string verbatim. Since ffmpeg filter options are comma/colon-delimited,
+ a value like "black,drawtext=text=INJECTED" doesn't just set an odd colour -- the comma ends
+ the colour filter early and starts an entirely new one, so the payload actually gets burnt
+ into the frame (confirmed by rendering it and inspecting the pixels before this fix existed).
+ This is a real filter-graph injection, not just a cosmetic validation gap -- every colour-like
+ flag across the codebase must refuse anything that isn't a plain colour token."""
+ payload = "black,drawtext=text=INJECTED"
+ cases = [
+ ("pad.py", [self.src, "--start", "1", "--color", payload]),
+ ("straighten.py", [self.src, "--degrees", "5", "--fit", "pad", "--fill-color", payload]),
+ ("waveform.py", [self.src, "--background", payload]),
+ ("waveform.py", [self.src, "--color", payload]),
+ ("background.py", ["--duration", "1", "--width", "640", "--height", "360", "--color", payload, "-o", OUT / "bg_inject.mp4"]),
+ ("background.py", ["--duration", "1", "--width", "640", "--height", "360", "--gradient", f"{payload}:0x0057ff", "-o", OUT / "bg_inject2.mp4"]),
+ ("fit.py", [self.src, "--aspect", "1:1", "--fit", "pad", "--pad-color", payload]),
+ ("export.py", [self.src, "--preset", "reels", "--pad-color", payload]),
+ ("join.py", [self.src, self.src, "--pad-color", payload]),
+ ("overlay.py", [self.src, "--text", "hi", "--font-color", payload]),
+ ("overlay.py", [self.src, "--text", "hi", "--border-color", payload]),
+ ("overlay.py", [self.src, "--text", "hi", "--box-color", payload]),
+ ("overlay.py", [self.src, "--video", self.src, "--chromakey", payload]),
+ ]
+ for name, argv in cases:
+ proc = script(name, *argv, expect_fail=True)
+ self.assertIn("colour", proc.stderr, f"{name} {argv}: expected a colour-validation refusal")
+
+ def test_color_like_flags_still_accept_real_colors(self):
+ script("pad.py", self.src, "--start", "0.5", "--color", "0x101010", "-o", OUT / "colorok1.mp4")
+ script("straighten.py", self.src, "--degrees", "5", "--fit", "pad", "--fill-color", "black", "-o", OUT / "colorok2.mp4")
+ script("waveform.py", self.src, "--background", "0x101010", "--color", "cyan|magenta", "-o", OUT / "colorok3.mp4")
+ script("background.py", "--duration", "1", "--width", "640", "--height", "360", "--gradient", "0xff6a00:0x0057ff", "-o", OUT / "colorok4.mp4")
+ script("overlay.py", self.src, "--text", "hi", "--box-color", "[email protected]", "-o", OUT / "colorok5.mp4")
+
+ # ---------------------------------------------------------------- font-name filter-graph injection (adversarial)
+ @unittest.skipIf(platform.system() == "Windows", "forces the fc-match-missing fallback path by symlinking just "
+ "ffmpeg/ffprobe into a stub PATH dir -- os.symlink needs an elevated/dev-mode privilege on "
+ "Windows that CI runners don't grant, and default_font_file() doesn't even consult fc-match "
+ "there (it resolves a fixed arial.ttf under WINDIR, see its docstring), so this specific "
+ "repro doesn't generalise to Windows. The fix itself (escape_drawtext() around the fallback "
+ "value) is plain string handling with no OS branch, so it's equally in effect there.")
+ def test_font_flag_escapes_filter_graph_injection_when_unresolved(self):
+ """overlay.py and graphics.py both accept --font as a family NAME, not a file path, and try
+ to resolve it to a concrete file via default_font_file() (fc-match) first -- but that
+ resolution returns None whenever fc-match isn't on PATH (always true on some real systems,
+ e.g. minimal containers and every Windows build), in which case both tools used to fall back
+ to embedding the raw name straight into `font='{args.font}'` with zero escaping. Since
+ drawtext=... options are comma/colon-delimited, a value like "X',drawtext=text=OWNED"
+ doesn't just set an odd font -- the comma ends the font option (and the whole drawtext
+ filter) early and starts an entirely new drawtext filter, which actually rendered (confirmed
+ by rendering the pre-fix code and visually inspecting the burnt-in "OWNED" text). Force the
+ None-fallback path by hiding fc-match from PATH, exactly as it's naturally absent on some
+ real systems, and confirm the built filter graph no longer contains a live breakout."""
+ payload = "X',drawtext=text=OWNED:fontcolor=yellow:fontsize=40:x=10:y=10"
+ stub_dir = OUT / "no_fc_match_path"
+ stub_dir.mkdir(exist_ok=True)
+ for exe in ("ffmpeg", "ffprobe"):
+ real = shutil.which(exe)
+ link = stub_dir / exe
+ if not link.exists():
+ os.symlink(real, link)
+ # Python's own bin dir has to stay on PATH, and on a system-python machine (the Debian
+ # container job) that dir is /usr/bin, which also holds the real fc-match -- so "hidden
+ # by PATH" was not hidden at all there and the tool resolved a real fontfile= instead of
+ # taking the font= fallback this test exists to exercise. A stub fc-match that always
+ # fails sits first on PATH so the resolver returns None on every layout.
+ if platform.system() != "Windows":
+ stub = stub_dir / "fc-match"
+ stub.write_text("#!/bin/sh\nexit 1\n", encoding="utf-8")
+ stub.chmod(0o755)
+ env = dict(os.environ)
+ env["PATH"] = os.pathsep.join([str(stub_dir), str(Path(sys.executable).parent)])
+
+ out = OUT / "font_inject_overlay.mp4"
+ proc = sh(sys.executable, SCRIPTS / "overlay.py", self.src, "--text", "hello", "--font", payload, "-o", out, env=env)
+ # The escaped payload must show up with a backslash-escaped comma ahead of the injected
+ # "drawtext=text=OWNED" -- proof it stays a literal char inside font='...' instead of
+ # closing the option early and starting a sibling filter.
+ self.assertIn("\\,drawtext=text=OWNED", proc.stderr, "comma must be escaped so it can't break out of font= into a new filter")
+
+ frame = OUT / "font_inject_overlay_frame.png"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", out, "-ss", "1", "-vframes", "1", frame)
+ self.assertTrue(frame.exists())
+
+ def test_caption_font_with_comma_and_colon_does_not_corrupt_ass_style(self):
+ """caption.py's --font flows into two ASS constructs escape_drawtext() was never meant to
+ cover: the comma-delimited [V4+ Styles] Style: line (write_ass()), and the comma-separated
+ Key=Value list inside a -vf subtitles=...:force_style='...' option. Neither is a drawtext
+ filter, so unlike overlay.py/graphics.py this call site used to embed args.font completely
+ raw. A font name containing a comma shifts every field after it (size, colours, bold flag,
+ alignment, margins) in the Style: line, and a comma or colon inside force_style's FontName=
+ breaks the option-list/-vf parsing the same way. Verify a hostile font name survives as an
+ inert, field-count-preserving value in both the --write-ass path and the plain SRT-burn
+ (force_style) path."""
+ hostile_font = "Arial,Bold:evil"
+ ass_out = OUT / "font_inject.ass"
+ script("caption.py", self.src, "--text", self.cues, "--font", hostile_font, "--animate", "fade", "--write-ass", ass_out, "--fast", "-o", OUT / "font_inject.mp4")
+ style_line = next(l for l in ass_out.read_text(encoding="utf-8").splitlines() if l.startswith("Style: Default,"))
+ self.assertNotIn(",Arial,Bold:evil,", style_line, "raw hostile font must not appear -- it would shift every later field")
+ fields = style_line.split(",")
+ self.assertEqual(len(fields), 23, "Style: line must keep its full field count (Format: line lists 23 columns)")
+
+ out = OUT / "font_inject_caption.mp4"
+ proc = sh(sys.executable, SCRIPTS / "caption.py", self.src, "--text", self.cues, "--font", hostile_font, "-o", out, "--dry-run")
+ self.assertNotIn("Arial,Bold:evil", proc.stderr, "hostile font must not reach force_style unsanitised")
+
+ def test_caption_ass_dialogue_text_cannot_forge_override_blocks(self):
+ """ASS Dialogue text treats a literal `{...}` as an override block -- real style/animation
+ commands (\\pos, \\fscx, \\t, ...), not literal characters. Cue text is effectively user-
+ controlled (--text cues, an SRT file, or ASR transcription), so cue content containing
+ braces used to be interpreted as those commands instead of being read out literally,
+ letting a caption reposition/rescale/recolor itself or later text. Verify a hostile cue
+ survives as inert text with the override syntax neutralised."""
+ hostile_cues = OUT / "brace_inject_cues.txt"
+ hostile_cues.write_text("00:00:00 --> 00:00:03 hi {\\pos(0,0)\\fscx500}INJECTED\n", encoding="utf-8")
+ ass_out = OUT / "brace_inject.ass"
+ # a real (fast) burn: since 1.4.9 --dry-run writes no side files, the generated ASS included
+ script("caption.py", self.src, "--text", hostile_cues, "--animate", "fade", "--write-ass", ass_out, "--fast", "-o", OUT / "brace_inject.mp4")
+ dialogue = next(l for l in ass_out.read_text(encoding="utf-8").splitlines() if l.startswith("Dialogue: "))
+ # --animate fade legitimately prepends its own "{\fad(200,200)}" override block; only the
+ # cue-text-derived braces from the hostile payload must be gone.
+ self.assertNotIn("{\\pos(0,0)\\fscx500}", dialogue, "cue text must not be able to open a real ASS override block")
+ self.assertIn("\\{\\pos(0,0)\\fscx500\\}INJECTED", dialogue,
+ "the braces the user typed are ESCAPED (libass \\{ / \\}), not deleted: the cue "
+ "reads out exactly what was written and still cannot open an override block")
+
+ def test_caption_srt_blank_line_in_cue_text_does_not_split_the_block(self):
+ """parse_text_cues() turns a bare '|' into a newline (a documented way to write a two-line
+ caption), so a source line with two adjacent pipes ("a||b") produces cue text containing a
+ blank line ("a\\n\\nb"). A blank line is SRT's own block separator (index / timecode / text
+ / blank / next block) -- writing it raw used to split one cue into two malformed half-
+ blocks, the second missing its own index and timecode. Verify the generated SRT still
+ parses back as exactly the cues that were written, not more."""
+ hostile_cues = OUT / "blank_line_cues.txt"
+ hostile_cues.write_text("00:00:00 --> 00:00:03 a||b\n00:00:03 --> 00:00:06 second cue\n", encoding="utf-8")
+ srt_out = OUT / "blank_line.srt"
+ script("caption.py", "--text", hostile_cues, "--write-srt", srt_out)
+ from caption import parse_srt
+ cues = parse_srt(str(srt_out))
+ self.assertEqual(len(cues), 2, "the blank line inside cue text must not fake a third block boundary")
+ self.assertEqual(cues[0][2], "a\nb", "text after the fake blank-line boundary must not be silently dropped")
+ self.assertEqual(cues[1][2], "second cue", "the second cue must still have its own timecode/index, not be swallowed as stray text")
+
+ def test_caption_malformed_timestamp_falls_back_to_just_the_text_not_the_whole_line(self):
+ """TIME_RE can match a line (finding a text portion after the arrow) even when one of the
+ two timestamps inside it fails parse_time() (e.g. a malformed "00:00:03.15.999" with a
+ stray extra segment). The except ValueError fallback used `line.strip()` -- the entire raw
+ line, broken timestamp included -- instead of the already-captured `m.group("text")`, so
+ the malformed timestamp string itself got burned into the caption as visible text."""
+ cues = OUT / "malformed_timestamp_cues.txt"
+ cues.write_text("00:00:00.15.999 --> 00:00:02 Hello there\n", encoding="utf-8")
+ srt_out = OUT / "malformed_timestamp.srt"
+ script("caption.py", "--text", cues, "--write-srt", srt_out)
+ from caption import parse_srt
+ parsed = parse_srt(str(srt_out))
+ self.assertEqual(len(parsed), 1)
+ self.assertEqual(parsed[0][2], "Hello there", "the broken timestamp text must not leak into the caption")
+
+ def test_drawtext_semicolon_and_quote_render_as_inert_literal_text(self):
+ """Before 1.15 this text went inline into the filtergraph, where two characters had no
+ escape that survives every call shape: ';' splits a filterchain exactly like ',', and the
+ quote corrupts a -filter_complex chain that uses explicit [label] pads (trailing option
+ text leaked into the picture as burnt-in literal text). The old fix dropped the quote and
+ escaped the semicolon. 1.15 removes the whole class: the drawn text is handed to drawtext
+ as `textfile=<path>:expansion=none`, so the graph parser never sees it -- the quote is now
+ KEPT, and nothing can leak into the options. Assert the new route, not the old escape."""
+ out = OUT / "semicolon_quote.mp4"
+ doc = json.loads(script("overlay.py", self.src, "--text", "a'b;c", "-o", out, "--json").stdout)
+ graph = " ".join(doc["commands"])
+ m = re.search(r"textfile=(\S+?\.txt)", graph.replace("\\", ""))
+ self.assertTrue(m, "drawn text must go through textfile=, not inline: " + graph)
+ self.assertIn("expansion=none", graph)
+ self.assertNotIn("a\\;c", graph, "no inline escaped copy of the text may remain in the graph")
+ # The textfile lives in a private 0700 per-run directory and is removed when the run
+ # ends -- assert both, since a world-shared, never-cleaned /tmp directory was the 1.15.0
+ # shape. The frame ink below is what proves the characters reached the picture.
+ self.assertTrue(Path(m.group(1)).parent.name.startswith("ffmpeg-skill-text-"),
+ "drawn text must go in a private per-run directory: " + m.group(1))
+ self.assertFalse(Path(m.group(1)).exists(),
+ "the drawn-text temp file must not outlive the run")
+ self.assertEqual(doc["status"], "completed")
+ frame = OUT / "semicolon_quote_frame.png"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", out, "-vframes", "1", frame)
+ self.assertTrue(frame.exists())
+
+ # ---------------------------------------------------------------- real iPhone regressions (Dolby Vision 8.4 / HLG, VFR, extra tracks)
+ def test_hdr_source_stays_hdr_through_reencodes(self):
+ # HLG 10-bit HEVC with audio AND a timecode data track, like an iPhone .mov
+ hlg = OUT / "hlg_tc.mov"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30", "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000",
+ "-t", "5", "-vf", "format=yuv420p10le", "-c:v", "libx265", "-preset", "ultrafast",
+ "-x265-params", "colorprim=bt2020:transfer=arib-std-b67:colormatrix=bt2020nc:log-level=error", "-tag:v", "hvc1",
+ "-c:a", "aac", "-timecode", "01:00:00:00", hlg)
+ streams = json.loads(sh("ffprobe", "-v", "error", "-print_format", "json", "-show_streams", hlg).stdout)["streams"]
+ self.assertEqual(len(streams), 3, "video + audio + tmcd data track")
+ for name, argv in [
+ ("cut.py", [hlg, "--start", "1", "--end", "3", "--accurate"]),
+ ("fit.py", [hlg, "--aspect", "1:1", "--width", "480"]),
+ ("caption.py", [hlg, "--text", self.cues]),
+ ("overlay.py", [hlg, "--text", "hdr"]),
+ ("silence.py", [hlg]),
+ ("join.py", [hlg, hlg, "--transition", "none"]),
+ ]:
+ out = OUT / f"hdrkeep_{name}.mp4"
+ script(name, *argv, "--fast", "-o", out)
+ v = probe(str(out))["video"]
+ self.assertTrue(v["hdr"], name)
+ self.assertEqual((v["codec"], v["pix_fmt"], v["color_transfer"]), ("hevc", "yuv420p10le", "arib-std-b67"), name)
+ # tone-mapping and the display path still work on the multi-track file
+ sdr = OUT / "hlg_tc_sdr.mp4"
+ script("color.py", hlg, "--to-sdr", "--fast", "-o", sdr)
+ self.assertFalse(probe(str(sdr))["video"]["hdr"])
+ proc = script("look.py", hlg, "--at", "1", "-o", OUT / "hlgframe")
+ self.assertIn("tone-mapped", proc.stderr)
+ self.assertTrue((OUT / "hlgframe_1.000s.png").exists())
+ # 10-bit levels are reported on an 8-bit scale, so a normal HDR clip is not called Log
+ data = json.loads(script("probe.py", hlg, "--analyze").stdout)
+ self.assertLessEqual(data["levels"]["y_max"], 255)
+ self.assertFalse(data["levels"]["looks_like_log"])
+
+ # ---------------------------------------------------------------- v0.6: graphics / brand / report
+ def test_graphics_templates(self):
+ brand = OUT / "brand.json"
+ brand.write_text(json.dumps({"font": "DejaVu Sans", "colors": {"primary": "FF6A00", "text": "FFFFFF", "background": "0B1D2A"},
+ "logo": "logo.png", "logo_position": "top-right", "logo_scale": 140, "safe_margin": 40,
+ "caption": {"size": 28, "position": "bottom", "animate": "pop", "karaoke": True, "bold": True}}), encoding="utf-8")
+ cases = {
+ "lower-third": ["--name", "Ada Lovelace", "--title", "Analyst", "--start", "1", "--end", "6"],
+ "title": ["--title", "Episode 12", "--subtitle", "The math of video", "--start", "0", "--end", "4"],
+ "chapter": ["--title", "Part 2", "--start", "0", "--end", "5"],
+ "progress": [],
+ "countdown": ["--from", "3", "--start", "1", "--end", "5"],
+ "bug": ["--title", "@handle"],
+ }
+ for name, argv in cases.items():
+ out = OUT / f"gfx_{name}.mp4"
+ proc = script("graphics.py", self.src, "--template", name, "--brand", brand, "--fast", "-o", out, *argv)
+ self.assertClose(probe(str(out))["duration"], 12.0, 0.2, name)
+ self.assertTrue("FF6A00" in proc.stderr or "0B1D2A" in proc.stderr, f"{name} uses the brand colours")
+ # animated templates must actually move: lower-third frame mid-slide differs from settled frame
+ script("look.py", OUT / "gfx_lower-third.mp4", "--at", "1.15", "--at", "3", "--no-timecode", "-o", OUT / "lt")
+ a, b = (OUT / "lt_1.150s.png").read_bytes(), (OUT / "lt_3.000s.png").read_bytes()
+ self.assertNotEqual(a[200:4000], b[200:4000])
+ script("graphics.py", self.src, "--template", "lower-third", expect_fail=True)
+
+ def test_sticker_hook_and_meme_draw_ink_where_they_promise(self):
+ """The three social graphics templates: each must render, put ink where the layout says it
+ goes (top band for the hook's progress bar, the two edges for a meme), and -- for the
+ sticker -- stay inside the platform's safe zone when --platform names one."""
+ sys.path.insert(0, str(SCRIPTS))
+ from _platforms import PLATFORMS
+ vertical = OUT / "safe_vertical.mp4"
+ script("fit.py", self.src, "--duration", "4", "--aspect", "9:16", "--fit", "crop",
+ "--width", "540", "--fast", "-o", vertical)
+ base = self._region_stats(vertical, "iw:60:0:0", at=1.0)
+
+ sticker = OUT / "gfx_sticker.mp4"
+ doc = json.loads(script("graphics.py", vertical, "--template", "sticker", "--text", "NEW",
+ "--position", "top-right", "--platform", "tiktok", "--fast",
+ "-o", sticker, "--json").stdout)
+ self.assertTrue(os.path.exists(sticker))
+ drawtext = [c for c in doc["commands"] if "drawtext" in c][0]
+ safe = PLATFORMS["tiktok"]["safe"]
+ W, H = 540, 960
+ right = int(re.search(r"x=w-text_w-(\d+)", drawtext).group(1))
+ top = int(re.search(r"y=[^0-9]*(\d+)\+", drawtext).group(1)) # the shell quoting around the expression varies
+ self.assertGreaterEqual(right, round(safe["right"] * W) - 1, "the sticker must clear the like column")
+ self.assertGreaterEqual(top, round(safe["top"] * H) - 1, "the sticker must clear the status bar")
+
+ hook = OUT / "gfx_hook.mp4"
+ script("graphics.py", vertical, "--template", "hook", "--title", "How I cut this",
+ "--duration", "3", "--fast", "-o", hook)
+ band_avg, _ = self._region_stats(hook, "iw:12:0:0", at=0.5)
+ late_avg, _ = self._region_stats(hook, "iw:12:0:0", at=3.5)
+ self.assertGreater(abs(band_avg - late_avg), 4,
+ "the hook's progress bar must be drawn while the card is up and gone after it")
+ mid_card, _ = self._region_stats(hook, "iw:200:0:380", at=0.5)
+ mid_after, _ = self._region_stats(hook, "iw:200:0:380", at=3.5)
+ self.assertNotAlmostEqual(mid_card, mid_after, delta=1.0,
+ msg="the hook card must darken the middle of the frame while it is up")
+
+ meme = OUT / "gfx_meme.mp4"
+ script("graphics.py", vertical, "--template", "meme", "--top", "when the render",
+ "--bottom", "finally finishes", "--fast", "-o", meme)
+ plain_top, _ = self._region_stats(vertical, "iw:120:0:40", at=1.0)
+ meme_top, _ = self._region_stats(meme, "iw:120:0:40", at=1.0)
+ plain_bottom, _ = self._region_stats(vertical, "iw:120:0:820", at=1.0)
+ meme_bottom, _ = self._region_stats(meme, "iw:120:0:820", at=1.0)
+ self.assertNotAlmostEqual(meme_top, plain_top, delta=0.5, msg="meme --top draws nothing")
+ self.assertNotAlmostEqual(meme_bottom, plain_bottom, delta=0.5, msg="meme --bottom draws nothing")
+ script("graphics.py", vertical, "--template", "sticker", expect_fail=True)
+ script("graphics.py", vertical, "--template", "meme", expect_fail=True)
+
+ def test_graphics_audio_stream_selects_the_requested_track_not_always_the_first(self):
+ two = OUT / "gfx_two_streams.mkv"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
+ "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
+ "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
+ self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
+ out1 = OUT / "gfx_two_s1.mp4"
+ script("graphics.py", two, "--template", "bug", "--title", "@handle", "--audio-stream", "1", "-o", out1, "--fast")
+ self.assertIsNotNone(probe(str(out1))["audio"])
+ out_prog = OUT / "gfx_two_progress.mp4"
+ script("graphics.py", two, "--template", "progress", "--audio-stream", "1", "-o", out_prog, "--fast")
+ self.assertIsNotNone(probe(str(out_prog))["audio"])
+ proc = script("graphics.py", two, "--template", "bug", "--title", "x", "--audio-stream", "5", "-o", OUT / "gfx_nope.mp4", "--json", expect_fail=True)
+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
+ self.assertIn("audio-stream", proc.stderr)
+
+ def test_transcribe_without_engine_explains(self):
+ import shutil
+ if shutil.which("whisper-cli") or shutil.which("whisper"):
+ self.skipTest("a local ASR engine is installed")
+ try:
+ import faster_whisper # noqa: F401
+ self.skipTest("faster-whisper installed")
+ except ImportError:
+ pass
+ proc = script("caption.py", self.src, "--transcribe", "-o", OUT / "asr.mp4", expect_fail=True)
+ self.assertIn("no local speech-to-text engine", proc.stderr)
+ self.assertIn("whisper", proc.stderr)
+
+ def test_overlay_fade_without_start_end_fades_in_only(self):
+ """--fade without --end fades in at 0 and stays; the fade-out belongs to --end (eval 6,
+ e03-logo: every "fade in at the start" run had to caveat an unasked-for fade-out)."""
+ proc = script("overlay.py", self.src, "--image", self.logo, "--fade", "0.5", "--dry-run")
+ self.assertIn("fade=t=in:st=0.000", proc.stderr)
+ self.assertNotIn("fade=t=out", proc.stderr)
+ self.assertNotIn("\nwrote ", proc.stderr, "dry-run must not claim a file was written")
+ proc = script("overlay.py", self.src, "--image", self.logo, "--fade", "0.5", "--end", "5", "--dry-run")
+ self.assertIn("fade=t=out:st=4.500", proc.stderr)
+
+ def test_filter_paths_with_drive_colon_spaces_and_unicode(self):
+ """subtitles= / ass= / lut3d=file= / fontfile= take a path with a colon, spaces and non-ASCII.
+
+ A Windows path `D:\\a\\x.srt` is what broke on the Windows CI: the filter option value is
+ parsed twice, so the colon needs two levels of escaping. On POSIX a directory literally named
+ `D:` reproduces it; on Windows the real drive letter does.
+ """
+ base = OUT / "compat dir ünïcode"
+ d = base if os.name == "nt" else base / "D:"
+ d.mkdir(parents=True, exist_ok=True)
+ src = d / "src vid.mp4"
+ shutil.copyfile(self.src, src)
+ cues = d / "cues täxt.txt"
+ cues.write_text("0:00-0:06 Hello caption\n", encoding="utf-8")
+ # captions via subtitles= (SRT) and ass=, both re-parsed by libass
+ cap = d / "cap.mp4"
+ script("caption.py", src, "--text", cues, "--size", "40", "--fast", "-o", cap)
+ self.assertLess(self._psnr(self.src, cap), 45, "burned caption changed the picture")
+ capa = d / "cap ass.mp4"
+ script("caption.py", src, "--text", cues, "--animate", "pop", "--fast", "-o", capa)
+ self.assertTrue((d / "cap ass.ass").exists())
+ self.assertLess(self._psnr(self.src, capa), 45)
+ # a fonts dir with the same kind of path
+ script("caption.py", src, "--text", cues, "--fonts-dir", d, "--fast", "-o", d / "cap fonts.mp4")
+ # LUT file: full strength inverts the picture, half strength goes through the split/blend graph
+ lut = d / "invert lut.cube"
+ lines = ["LUT_3D_SIZE 2"] + [f"{1 - r} {1 - g} {1 - b}" for b in (0, 1) for g in (0, 1) for r in (0, 1)]
+ lut.write_text("\n".join(lines) + "\n")
+ inv = d / "lut.mp4"
+ script("color.py", src, "--lut", lut, "--preset", "veryfast", "-o", inv)
+ self.assertLess(self._psnr(self.src, inv), 15, "inverted LUT changed every pixel")
+ half = d / "lut half.mp4"
+ script("color.py", src, "--lut", lut, "--lut-strength", "0.5", "--preset", "veryfast", "-o", half)
+ self.assertClose(probe(str(half))["duration"], 12.0, 0.2)
+ # drawtext fontfile= with the same path shape (when a TTF is available to copy)
+ font = self._any_ttf()
+ if font:
+ ttf = d / "my font.ttf"
+ shutil.copyfile(font, ttf)
+ script("overlay.py", src, "--text", "Hi", "--font-file", ttf, "--fast", "-o", d / "ov.mp4")
+
+ def test_overlay_still_is_bounded_by_the_video_length(self):
+ """A looped still (-loop 1) must not make the output longer than the video (FFmpeg 7+ -shortest keeps a buffer)."""
+ out = OUT / "ov_bound.mp4"
+ data = json.loads(script("overlay.py", self.src, "--image", self.logo, "--fast", "-o", out, "--json").stdout)
+ self.assertIn("-t", data["commands"][0])
+ self.assertClose(data["probe"]["duration"], 12.0, 0.15)
+
+ def test_overlay_on_audio_less_video_terminates(self):
+ """Every other overlay test uses self.src, which has audio. Cover the audio-less case too:
+ overlay is documented elsewhere as risky on inputs with no audio stream to help -shortest
+ bound the looped-image (-loop 1) input, so pin down that it completes and the output duration
+ matches the source exactly (the explicit -t, not -shortest, is what actually bounds it)."""
+ noaudio = OUT / "overlay_noaudio_source.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-an", "-c:v", "copy", noaudio)
+ self.assertIsNone(probe(str(noaudio)).get("audio"))
+ out = OUT / "overlay_noaudio.mp4"
+ proc = subprocess.run(
+ [sys.executable, str(SCRIPTS / "overlay.py"), str(noaudio), "--image", str(self.logo),
+ "--position", "bottom-right", "--start", "1", "--end", "5", "--fade", "0.3", "-o", str(out)],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", timeout=60)
+ self.assertEqual(proc.returncode, 0, f"STDOUT:\n{proc.stdout}\nSTDERR:\n{proc.stderr}")
+ self.assertClose(probe(str(out))["duration"], probe(str(noaudio))["duration"], 0.15)
+
+ def test_overlay_audio_stream_selects_the_requested_track_not_always_the_first(self):
+ two = OUT / "ov_two_streams.mkv"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30",
+ "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=44100",
+ "-t", "4", "-map", "0:v", "-map", "1:a", "-map", "2:a", "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", two)
+ self.assertEqual(len(probe(str(two))["audio_streams"]), 2)
+ out_text = OUT / "ov_two_text.mp4"
+ script("overlay.py", two, "--text", "hi", "--audio-stream", "1", "-o", out_text, "--preset", "veryfast")
+ self.assertIsNotNone(probe(str(out_text))["audio"])
+ out_img = OUT / "ov_two_img.mp4"
+ script("overlay.py", two, "--image", self.logo, "--audio-stream", "1", "-o", out_img, "--preset", "veryfast")
+ self.assertIsNotNone(probe(str(out_img))["audio"])
+ proc = script("overlay.py", two, "--text", "hi", "--audio-stream", "5", "-o", OUT / "ov_nope.mp4", "--json", expect_fail=True)
+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")
+ self.assertIn("audio-stream", proc.stderr)
+
+ def test_overlay_video_pip_composites_at_the_right_position(self):
+ red_bg = OUT / "red_bg.mp4"
+ blue_quad = OUT / "blue_quad.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=red:s=1280x720:d=1",
+ "-c:v", "libx264", "-pix_fmt", "yuv420p", red_bg)
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=blue:s=200x50:d=1",
+ "-c:v", "libx264", "-pix_fmt", "yuv420p", blue_quad)
+ out = OUT / "pip1.mp4"
+ script("overlay.py", red_bg, "--video", blue_quad, "--position", "bottom-right", "--scale", "200", "-o", out)
+
+ def px(path, x, y):
+ r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path),
+ "-vf", f"crop=2:2:{x}:{y}", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ return r.stdout[:3]
+
+ # PiP at bottom-right, 200 wide (50 tall for the 4:1 source), default margin 24:
+ # x=1280-200-24=1056, y=720-50-24=646
+ self.assertGreater(px(out, 1100, 660)[2], 100, "PiP area should show the blue overlay")
+ self.assertGreater(px(out, 100, 100)[0], 100, "outside the PiP area, the red background must remain")
+
+ def test_overlay_chromakey_removes_the_key_color(self):
+ red_bg = OUT / "ck_red_bg.mp4"
+ green_fg = OUT / "ck_green_fg.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=red:s=100x100:d=1",
+ "-c:v", "libx264", "-pix_fmt", "yuv420p", red_bg)
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=0x00ff00:s=100x100:d=1",
+ "-f", "lavfi", "-i", "color=c=white:s=20x20:d=1", "-filter_complex", "[0][1]overlay=40:40",
+ "-c:v", "libx264", "-pix_fmt", "yuv420p", green_fg)
+ out = OUT / "ck1.mp4"
+ script("overlay.py", red_bg, "--video", green_fg, "--chromakey", "0x00ff00", "--position", "top-left",
+ "--margin", "0", "--scale", "100", "-o", out)
+
+ def px(path, x, y):
+ r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(path),
+ "-vf", f"crop=2:2:{x}:{y}", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ return r.stdout[:3]
+
+ self.assertGreater(px(out, 10, 10)[0], 100, "keyed-out green should show the red background through it")
+ self.assertGreater(min(px(out, 45, 45)), 100, "the white square inside the green should be unaffected")
+
+ def test_overlay_chromakey_without_video_refused(self):
+ script("overlay.py", self.src, "--chromakey", "green", expect_fail=True)
+
+ def test_help_survives_a_legacy_console_encoding(self):
+ """--help contains non-ASCII (Japanese example, arrows); a cp1252 console must not raise UnicodeEncodeError."""
+ env = dict(os.environ, PYTHONIOENCODING="cp1252")
+ for name in ("overlay.py", "render.py", "caption.py"):
+ proc = subprocess.run([sys.executable, str(SCRIPTS / name), "--help"], stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+ env=env, encoding="utf-8", errors="replace")
+ self.assertEqual(proc.returncode, 0, f"{name}: {proc.stderr[-300:]}")
+ self.assertIn("usage:", proc.stdout)
+
+
+class ScriptFontTests(unittest.TestCase):
+ """1.12: which script text is written in, and a font file that actually covers it."""
+
+ def test_detect_script_reads_the_characters_not_the_locale(self):
+ cases = {
+ "こんにちは世界": "ja", # kana + han -> Japanese
+ "カタカナ": "ja",
+ "你好世界": "zh", # han alone -> Chinese
+ "안녕하세요": "ko",
+ "ㅎㅏㄴ": "ko", # jamo, not syllables
+ "مرحبا بالعالم": "ar",
+ "שלום עולם": "he",
+ "नमस्ते दुनिया": "hi",
+ "สวัสดีชาวโลก": "th",
+ "Привет мир": "ru",
+ "Γειά σου κόσμε": "el",
+ "Hello world": "latin",
+ "": "latin",
+ "1080p 30fps": "latin",
+ }
+ for text, expected in cases.items():
+ with self.subTest(text=text):
+ self.assertEqual(detect_script(text), expected)
+
+ def test_detect_script_mixed_text_goes_by_character_count(self):
+ self.assertEqual(detect_script("Episode 12 — 日本語のテスト"), "ja")
+ self.assertEqual(detect_script("Part 2: 第二部分的内容说明"), "zh")
+ # kana anywhere makes the whole string Japanese, however few
+ self.assertEqual(detect_script("漢字漢字漢字の"), "ja")
+ # the non-Latin script with the most characters wins
+ self.assertEqual(detect_script("Привет 你好世界大家好"), "zh")
+
+ def test_lang_hint_only_breaks_the_han_only_tie(self):
+ """Han with no kana is Chinese by default; only the caller knows when it is Japanese or
+ Korean hanja. The hint never overrides what the characters already prove."""
+ self.assertEqual(detect_script("漢字表記"), "zh")
+ self.assertEqual(detect_script("漢字表記", lang="ja"), "ja")
+ self.assertEqual(detect_script("漢字表記", lang="ko"), "ko")
+ self.assertEqual(detect_script("漢字表記", lang="ja-JP"), "ja")
+ self.assertEqual(detect_script("こんにちは", lang="zh"), "ja", "kana is not ambiguous -- the hint must not win")
+ self.assertEqual(detect_script("안녕하세요", lang="ja"), "ko")
+
+ @unittest.skipIf(_no_fontconfig(), "no fc-list on this machine: fonts cannot be resolved by script here")
+ def test_font_for_script_finds_a_real_file_for_every_script(self):
+ for script in ("ja", "zh", "ko", "ar", "he", "hi", "th", "ru", "el"):
+ with self.subTest(script=script):
+ path = font_for_script(script)
+ if path is None:
+ self.skipTest(f"this machine has no font covering {script}")
+ self.assertTrue(os.path.exists(path), path)
+ family = font_family_for_script(script)
+ self.assertTrue(family)
+ # "Unifont Sample" draws the code point in a box instead of the glyph -- the exact
+ # unreadable result this feature exists to avoid. It is only ever acceptable when
+ # nothing else on the machine covers the script at all.
+ if any(f for f in _families_for(script) if "unifont" not in f.lower()):
+ self.assertNotIn("unifont", family.lower(),
+ f"{script}: picked {family} while a real font is installed")
+
+ @unittest.skipIf(_no_fontconfig(), "no fc-list on this machine")
+ def test_font_for_script_is_cached_and_stable(self):
+ self.assertEqual(font_for_script("ja"), font_for_script("ja"))
+
+
+class EmojiTests(unittest.TestCase):
+ """1.15: emoji are detected as clusters, measured at a full em, reserved in the ASS and
+ composited as PNGs -- and every degraded path says so instead of lying."""
+
+ @classmethod
+ def setUpClass(cls):
+ if not shutil.which("ffmpeg"):
+ if os.environ.get("CI"):
+ raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step")
+ raise unittest.SkipTest("ffmpeg not on PATH")
+ OUT.mkdir(parents=True, exist_ok=True)
+ cls.src = OUT / "emoji_src.mp4"
+ if not cls.src.exists():
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=25",
+ "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000",
+ "-t", "4", "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p",
+ "-c:a", "aac", str(cls.src))
+ cls.cues = OUT / "cues_emoji.txt"
+ cls.cues.write_text("0:00-0:02 Hello \U0001F389 world\n0:02-0:04 Nice \U0001F44D job\n",
+ encoding="utf-8")
+
+ def test_emoji_cluster_detection_keeps_zwj_and_skin_tone_sequences_together(self):
+ from _common import emoji_clusters, emoji_codepoint_name, has_emoji
+ text = "\u3084\u3063\u305f \U0001F389 \U0001F469\u200d\U0001F4BB \U0001F1EF\U0001F1F5 \U0001F44D\U0001F3FD 1\ufe0f\u20e3"
+ names = [emoji_codepoint_name(cl) for _i, cl in emoji_clusters(text)]
+ self.assertEqual(names, ["1f389", "1f469-200d-1f4bb", "1f1ef-1f1f5", "1f44d-1f3fd", "31-fe0f-20e3"])
+ self.assertTrue(has_emoji(text))
+ self.assertFalse(has_emoji("plain ascii"))
+
+ def test_emoji_is_orthogonal_to_the_writing_system(self):
+ """A cue can be Japanese AND emoji: adding an "emoji" script would corrupt the font
+ resolution for the rest of the line."""
+ self.assertEqual(detect_script("\u3084\u3063\u305f \U0001F389"), "ja")
+ self.assertEqual(detect_script("Hello \U0001F389"), "latin")
+
+ def test_caption_wrap_counts_an_emoji_as_a_full_width_atom(self):
+ from _common import text_width_em
+ import importlib, sys as _s
+ _s.path.insert(0, str(SCRIPTS))
+ caption = importlib.import_module("caption")
+ self.assertAlmostEqual(text_width_em("\U0001F389"), 1.0, places=6)
+ self.assertAlmostEqual(text_width_em("\U0001F389", 1.5), 1.5, places=6)
+ # a wrap never breaks inside a cluster
+ lines = caption.wrap_text("aaa \U0001F469\u200d\U0001F4BB bbb", 3.0)
+ self.assertIn("\U0001F469\u200d\U0001F4BB", lines)
+ for line in lines:
+ self.assertNotEqual(line, "\U0001F469")
+
+ def _plan(self, *extra):
+ out = OUT / "emoji_out.mp4"
+ proc = script("caption.py", self.src, "--text", self.cues, "-o", out,
+ "--dry-run", "--json", *extra)
+ return json.loads(proc.stdout)
+
+ def test_caption_emoji_overlay_places_one_png_per_cluster_inside_the_safe_area(self):
+ doc = self._plan("--emoji-assets", _emoji_assets())
+ self.assertEqual(doc["emoji"]["mode"], "png")
+ self.assertEqual(doc["emoji"]["overlays"], 2)
+ graph = [c for c in doc["commands"] if "overlay=" in c][-1]
+ overlays = re.findall(r"overlay=x=(\d+):y=(\d+):enable=\D*?between\(t,([\d.]+),([\d.]+)\)", graph)
+ self.assertEqual(len(overlays), 2, graph)
+ for x, y, start, end in overlays:
+ x, y = int(x), int(y)
+ self.assertTrue(0.05 * 640 <= x <= 0.95 * 640, f"x={x} outside the safe area")
+ self.assertTrue(0.05 * 360 <= y <= 0.95 * 360, f"y={y} outside the safe area")
+ self.assertLess(float(start), float(end))
+ self.assertEqual([(o[2], o[3]) for o in overlays], [("0.000", "2.000"), ("2.000", "4.000")])
+
+ def test_caption_emoji_placeholder_reserves_the_gap_in_the_generated_ass(self):
+ out = OUT / "emoji_ass.mp4"
+ script("caption.py", self.src, "--text", self.cues, "-o", out,
+ "--emoji-assets", _emoji_assets())
+ ass = (OUT / "emoji_ass.ass").read_text(encoding="utf-8-sig")
+ dialogue = [l for l in ass.splitlines() if l.startswith("Dialogue:")]
+ self.assertTrue(dialogue)
+ for line in dialogue:
+ self.assertIn("\\alpha&HFF&", line)
+ self.assertNotIn("\U0001F389", line, "the raw code point must not reach the drawn text")
+ self.assertNotIn("\U0001F44D", line)
+
+ def test_the_emoji_placeholder_reserves_exactly_the_box_it_asks_for(self):
+ """The reservation is measured, not assumed: U+2588 is 0.66-0.83 em depending on the face,
+ so the gap is reserved with alpha-hidden \\fsp spacing, which is exact in every face."""
+ from _ass_overlay import emoji_placeholder
+ families = ["FreeSans", "DejaVu Sans", "IPAPGothic", "WenQuanYi Zen Hei", "Loma"]
+ tested = 0
+ for family in families:
+ if not _family_installed(family):
+ continue
+ tested += 1
+ base = _ass_advance(family, "|")
+ with_gap = _ass_advance(family, emoji_placeholder(60) + "|")
+ if base is None or with_gap is None:
+ self.skipTest("libass render probe produced no ink here")
+ self.assertAlmostEqual(with_gap - base, 60, delta=2,
+ msg=f"{family}: reserved {with_gap - base}px, asked for 60")
+ if not tested:
+ self.skipTest("none of the measured families is installed here")
+
+ def test_caption_emoji_without_assets_is_a_warning_not_a_failure(self):
+ from _common import emoji_support
+ support = emoji_support(probe=True)
+ if support["mode"] not in ("mono", "none"):
+ self.skipTest("this machine has a colour emoji path; the degraded branch cannot be exercised")
+ out = OUT / "emoji_mono.mp4"
+ proc = script("caption.py", self.src, "--text", self.cues, "-o", out, "--json")
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["status"], "completed")
+ self.assertEqual(doc["emoji"]["mode"], support["mode"])
+ if support["mode"] == "mono":
+ self.assertIn("monochrome", proc.stderr + proc.stdout)
+ self.assertTrue(any("monochrome" in n for n in doc.get("notes", [])), doc.get("notes"))
+
+ def test_emoji_assets_directory_that_does_not_exist_is_a_failed_job(self):
+ out = OUT / "emoji_missing.mp4"
+ proc = script("caption.py", self.src, "--text", self.cues, "-o", out, "--json",
+ "--emoji-assets", str(OUT / "no_such_emoji_dir"), expect_fail=True)
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("twemoji", doc["error"]["message"].lower())
+ self.assertIn("no network", doc["error"]["message"].lower())
+
+ def test_the_skill_never_fetches_an_emoji_asset(self):
+ """Mirror of the existing no-network assertions: nothing on the emoji path may import a
+ network module, and no tool offers a download flag for one."""
+ import _common
+ # _common is a package: every module in it, not just the facade.
+ source = "\n".join(p.read_text(encoding="utf-8")
+ for p in sorted(Path(_common.__file__).parent.glob("*.py")))
+ for banned in ("urllib", "http.client", "requests", "socket."):
+ self.assertNotIn(banned, source, f"{banned} is reachable from the emoji path")
+ for tool in ("caption.py", "graphics.py", "overlay.py"):
+ helptext = script(tool, "--help").stdout.lower()
+ self.assertNotIn("--emoji-download", helptext)
+ self.assertNotIn("download", helptext.split("--emoji")[-1][:400])
+
+ def test_caption_emoji_overlay_is_capped(self):
+ many = OUT / "cues_many_emoji.txt"
+ many.write_text("".join("0:0%d-0:0%d %s\n" % (i, i + 1, "\U0001F389" * 9)
+ for i in range(0, 8)), encoding="utf-8")
+ out = OUT / "emoji_capped.mp4"
+ proc = script("caption.py", self.src, "--text", many, "-o", out, "--json", "--dry-run",
+ "--emoji-assets", _emoji_assets(), "--emoji-max", "4", expect_fail=True)
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("--emoji-max", doc["error"]["message"])
+
+ def test_graphics_all_emoji_title_without_a_glyph_is_a_failed_job(self):
+ out = OUT / "emoji_title.mp4"
+ proc = script("graphics.py", self.src, "--template", "title", "--title", "\U0001F389",
+ "--start", "0", "--end", "2", "--emoji", "none", "-o", out, "--json",
+ expect_fail=True)
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("blank", doc["error"]["message"])
+
+ def test_overlay_text_refuses_the_png_emoji_route_and_names_the_tools_that_have_one(self):
+ out = OUT / "emoji_overlay.mp4"
+ proc = script("overlay.py", self.src, "--text", "Ship it \U0001F680", "--emoji", "png",
+ "-o", out, "--json", expect_fail=True)
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("caption.py", doc["error"]["message"])
+ self.assertIn("graphics.py", doc["error"]["message"])
+
+
+ # ---------------------------------------------------------------- 1.15.0 fix pass
+ def test_emoji_cluster_never_starts_at_a_joiner_a_selector_or_a_plain_letter(self):
+ """U+200D ZWJ and U+200C ZWNJ are ordinary Indic/Persian orthography, not emoji: क्‍ष is
+ ka + virama + ZWJ + ssa. Treating a joiner (or a VS16, or a skin-tone modifier) as a
+ cluster TAIL that glues itself to whatever stands before it turned a Hindi conjunct into
+ "an emoji" -- reported as such, warned about as monochrome, and on the PNG route replaced
+ by an invisible gap, i.e. a different word. A cluster may only START at an emoji base."""
+ from _common import emoji_clusters, emoji_codepoint_name, has_emoji
+
+ def names(text):
+ return [emoji_codepoint_name(cl) for _i, cl in emoji_clusters(text)]
+
+ self.assertEqual(names("\u0915\u094d\u200d\u0937"), [], "a Hindi conjunct is not an emoji")
+ self.assertFalse(has_emoji("\u0905\u200c\u092c"), "a ZWNJ is not an emoji either")
+ self.assertEqual(names("abc\u200ddef"), [])
+ self.assertEqual(names("A\ufe0f"), [], "a VS16 after a letter does not make it an emoji")
+ self.assertEqual(names("\u00a9 \u2122 0123456789"), [], "(c), (tm) and digits are not emoji")
+ # ... and every real cluster still survives whole
+ self.assertEqual(names("\U0001F468\u200d\U0001F469\u200d\U0001F467"),
+ ["1f468-200d-1f469-200d-1f467"])
+ self.assertEqual(names("\U0001F3F3\ufe0f\u200d\U0001F308"), ["1f3f3-fe0f-200d-1f308"])
+ self.assertEqual(names("1\ufe0f\u20e3"), ["31-fe0f-20e3"])
+ self.assertEqual(names("\U0001F1EF\U0001F1F5"), ["1f1ef-1f1f5"])
+
+ def test_vs15_asks_for_the_character_not_the_picture(self):
+ """U+FE0E is the TEXT presentation selector: the author explicitly asked for the glyph,
+ so the cluster must not be routed to the PNG overlay."""
+ from _common import emoji_clusters
+ self.assertEqual(emoji_clusters("\u2764\ufe0e"), [], "VS15 means: draw the character")
+ self.assertTrue(emoji_clusters("\u2764\ufe0f"), "VS16 still means: draw the emoji")
+
+ def test_caption_emoji_png_is_on_screen_for_the_whole_cue_and_only_that_cue(self):
+ """The one assertion the 1.15.0 emoji tests were all missing: a rendered frame from the
+ MIDDLE of the cue. A PNG input is a single frame at pts 0, so `eof_action=pass` (which
+ switches off overlay's "hold the last frame of the secondary input") composited every
+ emoji on frame 0 and nowhere else -- the demo GIF shipped an empty reserved gap."""
+ cues = OUT / "cues_one_emoji.txt"
+ cues.write_text("0:00-0:02 Hello \U0001F389 world\n", encoding="utf-8")
+ out = OUT / "emoji_midcue.mp4"
+ doc = json.loads(script("caption.py", self.src, "--text", cues, "-o", out, "--json",
+ "--dry-run", "--emoji-assets", _emoji_assets()).stdout)
+ graph = [c for c in doc["commands"] if "overlay=" in c][-1]
+ m = re.search(r"overlay=x=(\d+):y=(\d+)", graph)
+ self.assertTrue(m, graph)
+ x, y = int(m.group(1)) + 4, int(m.group(2)) + 4
+ script("caption.py", self.src, "--text", cues, "-o", out,
+ "--emoji-assets", _emoji_assets())
+ orange = (255, 165, 0) # _emoji_assets() draws 1f389 as a plain orange square
+
+ def near(pix):
+ return sum(abs(a - b) for a, b in zip(pix, orange)) < 60
+
+ self.assertTrue(near(_pixel_at(out, 1.0, x, y)),
+ "the emoji is gone by the middle of its own cue: %r" % (_pixel_at(out, 1.0, x, y),))
+ self.assertTrue(near(_pixel_at(out, 1.8, x, y)), "the emoji left before its cue ended")
+ self.assertFalse(near(_pixel_at(out, 3.0, x, y)),
+ "the emoji is still on screen a second after its cue ended")
+
+ def test_caption_rtl_emoji_is_placed_by_the_rendered_order_not_the_logical_prefix(self):
+ """libass lays an RTL line out right-to-left, so the LOGICAL prefix of a cluster occupies
+ the RIGHT end of the rendered line. Measuring from the left put the PNG on top of the
+ Arabic text, a prefix-width away from the gap libass actually reserved."""
+ from _common import script_font_status
+ cues = OUT / "cues_rtl.txt"
+ # the emoji is FIRST in logical order, so it must be drawn at the RIGHT end of the line
+ cues.write_text("0:00-0:02 \U0001F389 \u0645\u0631\u062d\u0628\u0627 \u0628\u0627\u0644\u0639\u0627\u0644\u0645\n",
+ encoding="utf-8")
+ out = OUT / "emoji_rtl.mp4"
+ doc = json.loads(script("caption.py", self.src, "--text", cues, "-o", out, "--json",
+ "--dry-run", "--emoji-assets", _emoji_assets()).stdout)
+ graph = [c for c in doc["commands"] if "overlay=" in c][-1]
+ m = re.search(r"overlay=x=(\d+):y=(\d+)", graph)
+ self.assertTrue(m, graph)
+ x, y = int(m.group(1)), int(m.group(2))
+ self.assertGreater(x, 320, "a logically-first cluster in an RTL line belongs on the right "
+ "half of a centred line, not the left: x=%d" % x)
+ if script_font_status("ar") != "available":
+ self.skipTest("no font on this machine covers Arabic; tests never install fonts")
+ # and the box must land where libass drew nothing -- the reserved gap, not over a glyph
+ script("caption.py", self.src, "--text", cues, "-o", out, "--emoji-assets", _emoji_assets())
+ box = doc["emoji"].get("box_px") or 24
+ ink = _ass_ink_columns(OUT / "emoji_rtl.ass", 640, 360)
+ if not ink:
+ # the probe renders the sidecar with a bare `ass=` filter; without fontconfig (Windows,
+ # a static build) libass may resolve no face for Arabic and draw nothing, which says
+ # nothing about placement -- the caption itself goes through fontsdir handling
+ self.skipTest("the ASS probe drew no ink on this build (libass found no Arabic face)")
+ covered = [c for c in range(x + 2, x + box - 2) if c in ink]
+ self.assertEqual(covered, [], "the PNG would be composited over drawn text at columns %r" % covered)
+
+ def test_caption_emoji_max_zero_means_no_overlays_at_all(self):
+ """`int(args.emoji_max or 60)` swallowed the one value a caller would use to say 'none'."""
+ out = OUT / "emoji_max0.mp4"
+ doc = json.loads(script("caption.py", self.src, "--text", self.cues, "-o", out, "--json",
+ "--dry-run", "--emoji-assets", _emoji_assets(), "--emoji-max", "0",
+ expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("limit 0", doc["error"]["message"])
+
+ def test_caption_animate_fades_the_emoji_with_the_text(self):
+ """--animate fade gives the TEXT a \\fad; the PNG used to pop in against a fading line."""
+ cues = OUT / "cues_fade_emoji.txt"
+ cues.write_text("0:00-0:02 Hello \U0001F389 world\n", encoding="utf-8")
+ out = OUT / "emoji_fade.mp4"
+ doc = json.loads(script("caption.py", self.src, "--text", cues, "-o", out, "--json",
+ "--dry-run", "--animate", "fade",
+ "--emoji-assets", _emoji_assets()).stdout)
+ graph = [c for c in doc["commands"] if "overlay=" in c][-1]
+ self.assertIn("fade=t=in", graph)
+ self.assertIn("fade=t=out", graph)
+ self.assertIn("alpha=1", graph)
+ m = re.search(r"overlay=x=(\d+):y=(\d+)", graph)
+ x, y = int(m.group(1)) + 4, int(m.group(2)) + 4
+ script("caption.py", self.src, "--text", cues, "-o", out, "--animate", "fade",
+ "--emoji-assets", _emoji_assets())
+ orange = (255, 165, 0)
+
+ def dist(t):
+ return sum(abs(a - b) for a, b in zip(_pixel_at(out, t, x, y), orange))
+
+ self.assertLess(dist(1.0), 60, "the emoji never reached full opacity")
+ self.assertGreater(dist(0.02), dist(1.0), "the emoji did not fade in with the text")
+
+ def test_graphics_drawtext_route_never_reports_monochrome_emoji(self):
+ """drawtext loads ONE font file and has no fallback chain, so "whatever glyph the text
+ font has" is an empty box. Reporting `mode: mono` from that route is a claim the frame
+ does not keep: the run must route to libass (which does have a fallback chain) or strip."""
+ out = OUT / "emoji_gfx_mono.mp4"
+ doc = json.loads(script("graphics.py", self.src, "--template", "title",
+ "--title", "Ship it \U0001F389 now", "--start", "0", "--end", "2",
+ "-o", out, "--json", "--dry-run").stdout)
+ if doc.get("emoji", {}).get("mode") == "mono":
+ self.assertEqual(doc["text_renderer"], "ass",
+ "mode mono on the drawtext route draws tofu, not a glyph")
+ pinned = json.loads(script("graphics.py", self.src, "--template", "title",
+ "--title", "Ship it \U0001F389 now", "--start", "0", "--end", "2",
+ "--text-render", "drawtext", "-o", out, "--json", "--dry-run").stdout)
+ self.assertEqual(pinned["text_renderer"], "drawtext")
+ self.assertNotEqual(pinned.get("emoji", {}).get("mode"), "mono",
+ "a pinned drawtext run must not claim monochrome either")
+
+ def test_graphics_emoji_none_actually_strips_the_cluster(self):
+ """`--emoji none` only guarded the all-emoji case: the cluster stayed in the drawn text
+ and drawtext drew the same empty box it would have drawn anyway."""
+ with_emoji = OUT / "emoji_gfx_none.mp4"
+ without = OUT / "emoji_gfx_plain.mp4"
+ script("graphics.py", self.src, "--template", "title", "--title", "Ship it \U0001F389 now",
+ "--start", "0", "--end", "3", "--emoji", "none", "-o", with_emoji)
+ script("graphics.py", self.src, "--template", "title", "--title", "Ship it now",
+ "--start", "0", "--end", "3", "-o", without)
+ self.assertAlmostEqual(_frame_ink(with_emoji), _frame_ink(without),
+ delta=max(1, _frame_ink(without) // 500),
+ msg="--emoji none must draw the same frame as text with no emoji in it")
+
+ def test_drawn_text_temp_files_are_private_and_never_outlive_the_run(self):
+ """1.15.0 wrote every drawn label into a world-shared, predictable, never-cleaned
+ /tmp/ffmpeg-skill-text -- including under --dry-run and on the ASS route, which never
+ reads them."""
+ import glob
+ import tempfile as _tf
+ out = OUT / "textfile_life.mp4"
+ doc = json.loads(script("overlay.py", self.src, "--text", "Label", "-o", out,
+ "--json", "--dry-run").stdout)
+ m = re.search(r"textfile=(\S+?\.txt)", " ".join(doc["commands"]).replace("\\", ""))
+ self.assertTrue(m, "the plan must still name the path it would use")
+ self.assertFalse(os.path.exists(m.group(1)), "a dry run wrote a file")
+ self.assertFalse(os.path.isdir(os.path.dirname(m.group(1))), "a dry run created a directory")
+ self.assertEqual(glob.glob(os.path.join(_tf.gettempdir(), "ffmpeg-skill-text-*")), [],
+ "a drawn-text directory was left behind")
+ self.assertFalse(os.path.exists(os.path.join(_tf.gettempdir(), "ffmpeg-skill-text")),
+ "the shared world-writable directory must not be created at all")
+
+ def test_the_ass_route_writes_no_drawtext_textfile(self):
+ from _common import script_font_status
+ if script_font_status("hi") != "available":
+ self.skipTest("no font on this machine covers Devanagari; tests never install fonts")
+ import glob
+ import tempfile as _tf
+ out = OUT / "textfile_ass_route.mp4"
+ script("graphics.py", self.src, "--template", "title", "--title", "\u0915\u093f\u0924\u093e\u092c",
+ "--start", "0", "--end", "2", "-o", out)
+ self.assertEqual(glob.glob(os.path.join(_tf.gettempdir(), "ffmpeg-skill-text-*")), [],
+ "the ASS route wrote (and kept) a drawtext textfile it never reads")
+
+ def test_the_ass_route_keeps_braces_and_backslashes(self):
+ """The same title through drawtext and through libass must produce the same characters:
+ 1.15.0 deleted `{`, `}` and `\\` on the ASS route while drawtext kept them."""
+ from _ass_overlay import ass_escape
+ self.assertEqual(ass_escape("A {b} c \\ d"), "A \\{b\\} c \\ d")
+ out = OUT / "ass_braces.mp4"
+ doc = json.loads(script("graphics.py", self.src, "--template", "title",
+ "--title", "A {b} c \\ d", "--start", "0", "--end", "2",
+ "--text-render", "ass", "-o", out, "--json").stdout)
+ ass = Path(doc["ass"]).read_text(encoding="utf-8-sig")
+ dialogue = next(l for l in ass.splitlines() if l.startswith("Dialogue:"))
+ self.assertIn("A \\{b\\} c \\ d", dialogue)
+
+
+class ShapingTests(unittest.TestCase):
+ """1.15: drawtext does bidi and Arabic joining on a fribidi build but never reorders or
+ re-clusters. graphics.py routes what it cannot shape through libass; overlay.py refuses."""
+
+ @classmethod
+ def setUpClass(cls):
+ if not shutil.which("ffmpeg"):
+ if os.environ.get("CI"):
+ raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step")
+ raise unittest.SkipTest("ffmpeg not on PATH")
+ OUT.mkdir(parents=True, exist_ok=True)
+ cls.src = OUT / "emoji_src.mp4"
+ if not cls.src.exists():
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=25", "-t", "4",
+ "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", str(cls.src))
+
+ def _skip_without(self, script_code):
+ from _common import script_font_status
+ if script_font_status(script_code) != "available":
+ raise unittest.SkipTest("no font on this machine covers %r; tests never install fonts"
+ % script_code)
+
+ def test_graphics_devanagari_renders_through_libass_not_drawtext(self):
+ self._skip_without("hi")
+ out = OUT / "shape_hi.mp4"
+ doc = json.loads(script("graphics.py", self.src, "--template", "lower-third",
+ "--name", "\u092a\u094d\u0930\u093f\u092f\u093e \u0936\u0930\u094d\u092e\u093e",
+ "--title", "\u0928\u093f\u0930\u094d\u0926\u0947\u0936\u0915",
+ "--start", "0", "--end", "3", "-o", out, "--dry-run", "--json").stdout)
+ self.assertEqual(doc["text_renderer"], "ass")
+ self.assertEqual(doc["script"], "hi")
+ graph = " ".join(doc["commands"])
+ self.assertIn("ass=", graph)
+ self.assertNotIn("drawtext=", graph, "the text must not also go through drawtext")
+
+ def test_graphics_latin_still_renders_through_drawtext(self):
+ out = OUT / "shape_latin.mp4"
+ doc = json.loads(script("graphics.py", self.src, "--template", "title",
+ "--title", "Episode 12", "--start", "0", "--end", "3",
+ "-o", out, "--dry-run", "--json").stdout)
+ self.assertEqual(doc["text_renderer"], "drawtext")
+ self.assertNotIn("ass", doc)
+ self.assertIn("drawtext=", " ".join(doc["commands"]))
+
+ def test_graphics_drawtext_forced_with_an_indic_script_is_refused_naming_the_script(self):
+ self._skip_without("hi")
+ out = OUT / "shape_refuse.mp4"
+ doc = json.loads(script("graphics.py", self.src, "--template", "title",
+ "--title", "\u0915\u093f\u0924\u093e\u092c", "--start", "0", "--end", "3",
+ "--text-render", "drawtext", "-o", out, "--json",
+ expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("Devanagari", doc["error"]["message"])
+ self.assertIn("harfbuzz", doc["error"]["message"])
+
+ def test_graphics_arabic_is_not_rerouted_on_a_fribidi_build(self):
+ from _common import drawtext_shaping
+ if not drawtext_shaping()["fribidi"]:
+ raise unittest.SkipTest("this ffmpeg has no fribidi: Arabic legitimately needs the ASS route")
+ self._skip_without("ar")
+ out = OUT / "shape_ar.mp4"
+ doc = json.loads(script("graphics.py", self.src, "--template", "title",
+ "--title", "\u0645\u0631\u062d\u0628\u0627 \u0628\u0627\u0644\u0639\u0627\u0644\u0645",
+ "--start", "0", "--end", "3", "-o", out, "--dry-run", "--json").stdout)
+ self.assertEqual(doc["text_renderer"], "drawtext")
+
+ def test_graphics_font_file_override_survives_the_ass_route(self):
+ self._skip_without("hi")
+ font = font_for_script("hi")
+ out = OUT / "shape_fontfile.mp4"
+ proc = script("graphics.py", self.src, "--template", "title", "--title",
+ "\u0915\u093f\u0924\u093e\u092c", "--start", "0", "--end", "3",
+ "--font-file", font, "-o", out, "--json")
+ doc = json.loads(proc.stdout)
+ self.assertEqual(doc["text_renderer"], "ass")
+ self.assertIn("fontsdir=", " ".join(doc["commands"]))
+ from _common import font_family_of_file
+ family = font_family_of_file(font)
+ ass = Path(doc["ass"]).read_text(encoding="utf-8-sig")
+ self.assertIn(family, ass, "the --font-file's own family must reach the ASS Style line")
+
+ def test_overlay_text_refuses_a_shaping_script_naming_the_tools_that_render_it(self):
+ out = OUT / "shape_overlay.mp4"
+ doc = json.loads(script("overlay.py", self.src, "--text", "\u0915\u093f\u0924\u093e\u092c",
+ "-o", out, "--json", expect_fail=True).stdout)
+ self.assertEqual(doc["error"]["kind"], "input")
+ self.assertIn("caption.py", doc["error"]["message"])
+ self.assertIn("graphics.py", doc["error"]["message"])
+
+
+class ApostropheAndPercentTests(unittest.TestCase):
+ """1.15: `'` and `%` reach the picture. They used to be dropped outright by escape_drawtext."""
+
+ @classmethod
+ def setUpClass(cls):
+ if not shutil.which("ffmpeg"):
+ if os.environ.get("CI"):
+ raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step")
+ raise unittest.SkipTest("ffmpeg not on PATH")
+ OUT.mkdir(parents=True, exist_ok=True)
+ cls.src = OUT / "emoji_src.mp4"
+ if not cls.src.exists():
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=640x360:rate=25", "-t", "4",
+ "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", str(cls.src))
+
+ def test_drawtext_keeps_an_apostrophe_and_a_percent_sign(self):
+ out = OUT / "pct_overlay.mp4"
+ doc = json.loads(script("overlay.py", self.src, "--text", "it's 100% done",
+ "-o", out, "--json").stdout)
+ graph = " ".join(doc["commands"])
+ m = re.search(r"textfile=(\S+?\.txt)", graph.replace("\\", ""))
+ self.assertTrue(m, graph)
+ self.assertIn("expansion=none", graph)
+ self.assertTrue(Path(m.group(1)).parent.name.startswith("ffmpeg-skill-text-"),
+ "drawn text must go in a private per-run directory: " + m.group(1))
+ self.assertFalse(Path(m.group(1)).exists(), "the drawn-text temp file must not outlive the run")
+ self.assertEqual(doc["status"], "completed")
+ # the drawn ink differs from the same render with the two characters stripped
+ stripped = OUT / "pct_overlay_stripped.mp4"
+ script("overlay.py", self.src, "--text", "its 100 done", "-o", stripped)
+ self.assertNotEqual(_frame_ink(out), _frame_ink(stripped),
+ "the apostrophe and the percent sign left no ink on the frame")
+
+ def test_caption_keeps_apostrophe_and_percent_in_the_drawn_text(self):
+ cues = OUT / "cues_pct.txt"
+ cues.write_text("0:00-0:02 it's 100% done\n", encoding="utf-8")
+ out = OUT / "pct_caption.mp4"
+ script("caption.py", self.src, "--text", cues, "--animate", "fade", "-o", out)
+ srt = (OUT / "pct_caption.srt").read_text(encoding="utf-8")
+ ass = (OUT / "pct_caption.ass").read_text(encoding="utf-8-sig")
+ self.assertIn("it's 100% done", srt)
+ self.assertIn("it's 100% done", ass)
+
+
+class WrapReadabilityTests(unittest.TestCase):
+ """1.15: no one-character orphan line, and a balanced break for spaced scripts."""
+
+ def setUp(self):
+ sys.path.insert(0, str(SCRIPTS))
+ import importlib
+ self.caption = importlib.import_module("caption")
+
+ def test_caption_wrap_never_leaves_a_one_character_orphan_line(self):
+ C = self.caption
+ cases = [
+ # th1's Thai cue and dl3's Japanese cue, at sizes where greedy wrapping stranded one character
+ ("\u0e1a\u0e23\u0e23\u0e17\u0e31\u0e14\u0e17\u0e35\u0e48\u0e2a\u0e2d\u0e07\u0e02\u0e2d\u0e07\u0e04\u0e33\u0e1a\u0e23\u0e23\u0e22\u0e32\u0e22 "
+ "\u0e1a\u0e23\u0e23\u0e17\u0e31\u0e14\u0e19\u0e35\u0e49\u0e15\u0e31\u0e49\u0e07\u0e40\u0e27\u0e25\u0e32\u0e43\u0e2b\u0e49\u0e2d\u0e31\u0e15\u0e42\u0e19\u0e21\u0e31\u0e15\u0e34", 8),
+ ("\u3053\u3093\u306b\u3061\u306f\u3001\u4e16\u754c 2 \u884c\u76ee\u306e\u5b57\u5e55\u3067\u3059 "
+ "\u81ea\u52d5\u3067\u30bf\u30a4\u30df\u30f3\u30b0\u304c\u6c7a\u307e\u308b\u884c", 10),
+ ("\u3053\u3093\u306b\u3061\u306f\u3001\u4e16\u754c 2 \u884c\u76ee\u306e\u5b57\u5e55\u3067\u3059 "
+ "\u81ea\u52d5\u3067\u30bf\u30a4\u30df\u30f3\u30b0\u304c\u6c7a\u307e\u308b\u884c", 29),
+ ]
+ for text, max_em in cases:
+ with self.subTest(max_em=max_em):
+ greedy = C.wrap_text(text, max_em, balance=False)
+ self.assertTrue(len(C._atoms(greedy[-1])) == 1 and C.text_width_em(greedy[-1]) < C.ORPHAN_MIN_EM,
+ "the case no longer reproduces greedily: %r" % greedy)
+ lines = C.wrap_text(text, max_em)
+ self.assertGreater(C.text_width_em(lines[-1]), C.ORPHAN_MIN_EM, lines)
+ for line in lines:
+ self.assertLessEqual(C.text_width_em(line), max_em, lines)
+ self.assertEqual("".join(lines).replace(" ", ""), "".join(greedy).replace(" ", ""))
+
+ def test_caption_wrap_prefers_a_balanced_break_for_latin(self):
+ C = self.caption
+ text = "A third line the tool times for me"
+ greedy = C.wrap_text(text, 14, balance=False)
+ balanced = C.wrap_text(text, 14)
+ self.assertEqual(len(greedy), len(balanced))
+ self.assertLessEqual(max(C.text_width_em(l) for l in balanced),
+ max(C.text_width_em(l) for l in greedy))
+ self.assertEqual(" ".join(balanced), text)
+ self.assertNotEqual(greedy, balanced, "dl1's break did not move")
+
+ def test_caption_wrap_rebalance_never_changes_the_line_count(self):
+ C = self.caption
+ samples = ["A third line the tool times for me",
+ "Hello world", "one two three four five six seven eight nine ten",
+ "\u3053\u3093\u306b\u3061\u306f\u3001\u4e16\u754c\u306e\u5b57\u5e55\u3067\u3059",
+ "Shipping day \U0001F389 for everyone here"]
+ for text in samples:
+ for max_em in range(4, 30):
+ with self.subTest(text=text[:12], max_em=max_em):
+ self.assertEqual(len(C.wrap_text(text, max_em)),
+ len(C.wrap_text(text, max_em, balance=False)))
+
+
+if __name__ == "__main__":
+ unittest.main(verbosity=2)