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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
feat: fonts by script (ja zh ko ar he hi th ru el), doctor per-language fonts, captions that wrap and fit (#218)
Shogo Kajiyama32c6462d002f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 478739c..a9866ad 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,22 @@## Unreleased+### Added++- **Fonts by script.** `caption.py`, `graphics.py` and `overlay.py --text` detect the writing system of the text they are about to draw (Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari, Thai, Cyrillic, Greek) and resolve a font file that actually covers it — `fc-list :lang=xx` on Linux/macOS, the known system fonts on Windows — printing one line: `font: /usr/share/fonts/.../wqy-zenhei.ttc (covers ko)`. A machine where fontconfig reports no font for the script **fails the job** (`kind: input`, with per-OS install hints) instead of writing a video full of empty boxes that ffmpeg reports as a success; a machine with no working fontconfig at all is `unknown`, not `missing`, and the job runs with the font as given behind one info line. An explicit `--font`, an explicit `--font-file`, or a font your brand file itself names is always kept (a brand file that never mentions a font is not a choice — the script still picks one); when fontconfig says the stated font does not cover the text, one info line says so. `caption.py --fonts-dir` is searched first and checked with `fc-scan`: a directory that does not cover the script gets one line and a font resolved by script anyway.+- `--lang XX` on `caption.py` (an alias of the existing `--language`, which keeps tagging the subtitle stream under `--mode mux` and setting `--transcribe`'s language) and on `graphics.py`, plus `"lang"` in brand.json: the hint that says whether Han-only text is Chinese, Japanese or Korean. Everything else is read from the characters.+- `doctor`'s `fonts` capability gains `scripts`: `available` / `missing` / `unknown` per writing system with the font file it would use, so "can this machine render Korean captions" is answered before the job. The plain-text `doctor` summarises it on one line and stays short.+- **Captions people can read.** Every cue is wrapped to the safe area by measured width — a per-character table for Latin (read off DejaVu Sans, so a line of capitals measures as wide as it draws), a full em per CJK/Thai character, 0.6 for Arabic/Hebrew, 0.7 for Devanagari, and nothing at all for a combining mark, which never gets separated from the character it belongs to (Thai tone marks and vowel signs, Devanagari matras, Arabic and Hebrew points). Lines break between characters for CJK/Thai and at spaces otherwise. `--max-lines N` (default 2) splits a cue that needs more lines into consecutive cues sharing its time; `--min-duration S` (default 1.0) holds a flashed cue longer, never past the next cue's start; `--offset TIME` shifts every cue for `--text`, `--srt` and `--ass` and takes the skill's timestamp grammar (seconds, `mm:ss`, `hh:mm:ss.ms`, SMPTE `hh:mm:ss:ff`, with a leading `-` for earlier). One `cues:` line reports what changed, and a file you passed in is never edited in place — the adjusted copy is written next to the output and burned instead. Under `--dry-run`/`--plan` the planned command names that same copy and the plan records where it comes from, while nothing is written until the real run. `--min-duration`/`--offset` also work with `--write-srt` alone; `--max-lines` needs the input video, whose frame size sets the line width.+- `--karaoke` uses real per-word timings when the transcript has them (a whisper `<stem>.json` / `<stem>.words.json` next to the SRT), falling back to the existing energy or even split.+- brand.json `styles.caption` (`{font, size, colour, box, position}`, either spelling of colour) — one caption look shared by `caption.py` and, for `font` and `colour`, `graphics.py`. The older top-level `caption` block still works and still carries the burn-in-only defaults.+- `render.py` projects pass `lang`, `offset`, `max_lines` and `min_duration` through to the captions stage, and `lang` to a graphics entry.++### Changed++- `doctor`'s plain `fonts:` line carries the default font's `detail` in brackets when the status is not `available` and the detail is short enough to keep the line to one screen width; longer detail stays `--json` only.+- `references/gotchas.md` on RTL: `caption.py` shapes and reorders Arabic and Hebrew by construction (everything it draws goes through libass); `drawtext` (`overlay.py --text`, `graphics.py`) does too on a build with `--enable-libfribidi`/`--enable-libharfbuzz`, and only an older build draws unjoined logical order.+- `tests/fixtures/mcp_tools.json` regenerated: `caption` gains `language` (spelled `--lang` too), `offset`, `max_lines`, `min_duration`; `graphics` gains `lang`.+### Docs- Correction to the 1.11.1 entry: iteration 11's agents did not read `references/gotchas.md` or `references/scripts.md` (0 of 36 and 2 of 36 actual reads; the earlier counts matched the file names inside SKILL.md's own text). What 1.11.1 changed in practice, measured in iteration 12: `doctor` before a job 23 of 36 runs → 0, `--json-brief` on a writing step 4 of 36 → 23. Tokens per run are flat (72.2k → 71.8k) because about 64k of every run is the harness's own context, not the skill.diff --git a/README.md b/README.mdindex e1cde3e..0689576 100644--- a/README.md+++ b/README.md@@ -204,7 +204,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth| Tool | What it does ||---|---|-| `caption.py` | Burn SRT/ASS with font, size, colour, outline, position; build SRT from timed plain text; animated and word-by-word karaoke timed to the speech energy; optional local transcription |+| `caption.py` | Burn SRT/ASS with font, size, colour, outline, position; build SRT from timed plain text; wraps to the safe area by measured width with `--max-lines`/`--min-duration`/`--offset`; picks a font by script for non-Latin text (`--lang`); animated and word-by-word karaoke timed to the speech energy or real word timings; optional local transcription || `overlay.py` | Logos, watermarks and titles with position, time range, opacity, fades; `--video` for picture-in-picture, `--chromakey` for green-screen compositing || `graphics.py` | Lower-thirds, title cards, chapter chips, progress bars, countdowns, corner bugs drawn by FFmpeg from a brand kit || `color.py` | HDR10 / HLG / Dolby Vision → SDR BT.709 tone mapping, DV layer stripping, 3D LUT (.cube), colour-tag rewriting, typed primary correction (exposure/contrast/saturation/gamma/white balance/lift-gain/levels/curves) |@@ -319,7 +319,7 @@ npx ffmpeg-skill doctor # human-readablenpx ffmpeg-skill doctor --json # available / missing / missing_optional / unknown / detection / errors / tools / gpu_encoders```-`doctor` reads `ffmpeg -encoders`, `-filters` and `-bsfs` and resolves every capability the contract declares against this machine's build. Three states per capability: `available`, `missing`, `unknown`. Exit 0 when everything required is available, 1 when something required is missing, 2 when nothing is proven missing but a required capability is unknown. With detection on (the default), `contract --json` carries the same lists under `capabilities`. `doctor --json`'s `tools` field folds that down to one answer per tool — `{"caption": {"usable": "no", "missing": ["filter:subtitles"], "fix": "..."}, ...}` — so "is `doctor` overall `ok`" and "can I run `caption.py` on this machine" are answered separately: a plain Homebrew `ffmpeg` is `ok` for tools that don't need `subtitles`/`drawtext`/`zscale`, while `caption`'s own `usable` is `"no"`.+`doctor` reads `ffmpeg -encoders`, `-filters` and `-bsfs` and resolves every capability the contract declares against this machine's build. Three states per capability: `available`, `missing`, `unknown`. Exit 0 when everything required is available, 1 when something required is missing, 2 when nothing is proven missing but a required capability is unknown. With detection on (the default), `contract --json` carries the same lists under `capabilities`. `doctor` also reports fonts: the default drawtext family, and `fonts.scripts` — one `available`/`missing`/`unknown` per writing system (ja, zh, ko, ar, he, hi, th, ru, el) with the file it would use — so "can this machine render Korean captions" is answered before the job, not after. `doctor --json`'s `tools` field folds that down to one answer per tool — `{"caption": {"usable": "no", "missing": ["filter:subtitles"], "fix": "..."}, ...}` — so "is `doctor` overall `ok`" and "can I run `caption.py` on this machine" are answered separately: a plain Homebrew `ffmpeg` is `ok` for tools that don't need `subtitles`/`drawtext`/`zscale`, while `caption`'s own `usable` is `"no"`.`doctor --json`'s `gpu_encoders` reports which GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`, `vaapi`, `amf`) this ffmpeg *build* was compiled with — read from `-encoders` alone, so it proves the capability shipped, not that the GPU/driver on this machine will actually accept a job (that needs a real encode, which `doctor`'s introspection never runs). No tool here uses one yet — every tool still assumes CPU x264/x265 — so this is purely informational and never affects `ok` or any tool's `usable`. GPU-accelerated encoding stays deliberately off the roadmap until there's a real-hardware-verified design for it (build-presence alone is not proof a job will succeed) — not a promised feature, just an honest "not yet, and not without proof it actually works."@@ -333,7 +333,7 @@ The short list for humans. The agent-facing version, with the reasoning, is the- **Loudness targets.** −14 LUFS / −1 dBTP for YouTube and social platforms (the `loudness.py` default), `-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast. A clip measured at −40 LUFS or below is room tone, not content; raising it raises the noise. Check true peak as well as LUFS: `check.py file --platform podcast` measures both.- **Frame changes first, text second.** Captions and overlays burned before a crop or resize end up off-frame. Reframe, then caption.- **Cropping 16:9 to 9:16 discards 70 % of the width.** `fit.py --fit crop` centres by default; pass `--crop-x`/`--crop-y` toward the subject, or pad with `--fit pad --pad-fill blur`. Look at the contact sheet before deciding.-- **Non-Latin captions need a font with the glyphs.** Without one you get boxes, not an error. Name it (`caption.py --font "Noto Sans CJK JP"`) or point at the file (`overlay.py --font-file /path/to/NotoSansCJK-Regular.ttc`).+- **Non-Latin text picks a font by script (1.12).** Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari, Thai, Cyrillic and Greek cues, titles and overlays resolve a font file that covers them automatically, and a machine with no such font fails the job (`kind: input`) instead of rendering boxes. `doctor --json`'s `fonts.scripts` says which languages this machine can render; `--lang ja|ko` disambiguates Han-only text; an explicit `--font`/`--font-file` is always kept.- **Silence detection finds nothing?** The default threshold is −35 dBFS. The tool prints a hint with the track's measured level; raise the threshold (`silence.py --threshold -25`) or shorten `--min-silence`.- **Sync results carry a confidence.** Below 0.3, or an offset near the edge of the analysis window, is probably wrong: enlarge `--analyze-seconds` or find a clap. Recordings over ten minutes from separate devices need `sync.py --fix-drift`.- **Outputs are never overwritten silently.** An existing output path is warned about today and refused from 2.0; set `FFMPEG_SKILL_NO_OVERWRITE=1` (the recommended agent setting) to get the refusal now and pass `--overwrite` where a replacement is intended.diff --git a/SKILL.md b/SKILL.mdindex ddaf0a4..34c67c7 100644--- a/SKILL.md+++ b/SKILL.md@@ -7,13 +7,13 @@ description: 'Edit video and audio with local FFmpeg from natural-language requeScripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. This file is enough to do a job: the table below routes the request, the recipes give the flags, and `--help` on the one script you are about to run is the cheapest full flag list. The reference files cost as much to read as this file does, so open one only when it answers a question you actually have: `references/scripts.md` (every flag of all 42 scripts, for comparing tools), `references/devices.md` (iPhone HDR, GoPro, DJI, screen recordings, Zoom), `references/gotchas.md` (the long form of the one-line rules at the end of this file).-Shared flags, on every script: `--dry-run`; `--json` (output path, a probe of the output, the commands run); `--json-brief` (that document trimmed to status/output/verified, a compact `summary` and the command count — enough to confirm and report, so prefer it on every writing step and keep `--json` for when you need the full probe); `--fast` (preview quality); `--progress`; `--timeout SECONDS` (`kind: timeout`, default 1800); `--overwrite` (consent to replace an existing output — without it the tool warns today, refuses from 2.0); `--plan FILE` (the dry run as a plan document `render.py FILE` executes later, refusing if an input changed: "plan → user confirms → execute" in one round trip). Every re-encoding tool also takes `--codec h264|hevc|av1|prores` and `--quality N` (CRF scale, replaces the deprecated `--crf`): unset, SDR is x264 and HDR is x265 Main10; `prores` needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (run `color.py --to-sdr` first).+Shared flags, on every script: `--dry-run`; `--json` (output path, a probe of the output, the commands run); `--json-brief` (that document trimmed to status/output/verified, a compact `summary` and the command count — prefer it on every writing step, `--json` when you need the full probe); `--fast` (preview quality); `--progress`; `--timeout SECONDS` (`kind: timeout`, default 1800); `--overwrite` (consent to replace an existing output — without it the tool warns today, refuses from 2.0); `--plan FILE` (the dry run as a plan document `render.py FILE` executes later, refusing if an input changed: "plan → confirm → execute" in one round trip). Every re-encoding tool also takes `--codec h264|hevc|av1|prores` and `--quality N` (CRF scale, replaces the deprecated `--crf`): unset, SDR is x264 and HDR is x265 Main10; `prores` needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (run `color.py --to-sdr` first).Writing tools run nothing under `--dry-run`; `probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness` and `stabilize` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact (nor side files such as `--edl`, `--sheet` or a generated `.ass`); `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).## Workflow (always follow this order)-0. **Environment, only on failure.** Do not start a job with `doctor`: on a working machine it is a call that tells you nothing the job needs, and on a broken one the script fails on its own with `kind: missing_tool` (no ffmpeg) or an ffmpeg error naming the filter or encoder (`No such filter: 'subtitles'`). Run `python3 <skill-dir>/scripts/_contract.py doctor` (also `npx ffmpeg-skill doctor`; there is no doctor.py) after such a failure, or when the user asks what the machine can do. It queries `ffmpeg -filters`/`-encoders`, so it is not a per-job step. Read `ok` and the tool's `usable`; if `usable` isn't `yes`, report the missing capability (a missing `libass`, `zscale` or encoder is the common case, e.g. `caption.py`) instead of discovering it through a runtime failure. `contract --json`'s full tool schema is for a *planning* agent choosing a tool from an abstract goal, not for this per-job workflow.+0. **Environment, only on failure.** Do not start a job with `doctor`: on a working machine it is a call that tells you nothing the job needs, and on a broken one the script fails on its own with `kind: missing_tool` (no ffmpeg) or an ffmpeg error naming the filter or encoder (`No such filter: 'subtitles'`). Run `python3 <skill-dir>/scripts/_contract.py doctor` (also `npx ffmpeg-skill doctor`; there is no doctor.py) after such a failure, or when the user asks what the machine can do. Read `ok` and the tool's `usable`; if `usable` isn't `yes`, report the missing capability (a missing `libass`, `zscale` or encoder is the common case, e.g. `caption.py`) instead of discovering it through a runtime failure. `contract --json`'s full tool schema is for a *planning* agent choosing a tool from an abstract goal, not for this per-job workflow.1. **Probe what you must plan from.** Run `probe.py` on each input you plan the edit from — duration, fps, resolution, codecs, channels, `variable_frame_rate_suspected` — and whenever the user asks a question about a file. You do not need a separate probe before every edit: every writing tool's `--json` already carries its input and a probe of the output it wrote. Plan from real numbers, never assumptions.2. **Prefer lossless.** If the request can be met without re-encoding (plain cuts on keyframes, remuxing, audio-only changes), do not re-encode. `cut.py` and `loudness.py` stream-copy video by default; pass `--accurate` to `cut.py` only for frame-exact cuts.3. **Plan with `--dry-run --json`, then execute.** Trust `--json`, not a dry run's human-readable summary line, for any number after the plan (dimensions there can be a placeholder, not a computed preview — `docs/contract.md`). Use it to confirm a plan before long encodes and to report exact facts. `--fast` is preview quality (x264 veryfast), `--progress` prints percent/ETA on stderr. Never point `-o` at a file you did not create in this job unless the user asked for it to be replaced; pass `--overwrite` only then.@@ -34,7 +34,7 @@ Ask one short question only when the answer changes the output materially and th- **Duration** ("make it 60 s") without a method: speed up for ≤1.5× changes, trim otherwise, and say which you chose. Ask when the content is a talk (trimming loses words) and the change is large.- **Captions** without a text source: `--transcribe` if a local whisper exists, otherwise ask for the text or a timed file; never invent dialogue.- **Fonts and brand**: if the user mentions a brand, colours or "our font", ask for or create `brand.json` once and reuse it.-- **CJK / non-Latin text**: check a font exists before rendering (`fc-list :lang=ja file` / `:lang=ko` / `:lang=zh`) and pass it with `--font "Name"` or `--font-file /path.ttf`. Tofu boxes are a failed job, not a style.+- **CJK / non-Latin text**: let the tool pick the font by script (`--font` turns that off); `--lang ja|ko` for Han-only text. `doctor --json` `.fonts.scripts` says what renders here. Tofu is a failed job, not a style.- **Crop position** for `--fit crop`: centre by default, but when the request or the source names an off-centre subject ("keep the product on the right", "don't cut off my hands", someone visibly off-centre in the sheet) use `--crop-x`/`--crop-y` (0=left/top, 1=right/bottom) instead of a silent centre guess. Ask which edge to keep when the sheet shows the subject near an edge and the request doesn't say.- Anything else (transition type, caption style): pick the conventional default, say what you picked, offer the alternative in one line.@@ -137,12 +137,12 @@ Timestamp flags — `--start`, `--end`, `--at`, `--from`, `--duration`, `--offse## Audio-only files-Audio is a first-class input: `probe.py`, `cut.py`, `silence.py`, `loudness.py`, `audio.py`, `sync.py` and `check.py --platform podcast` take WAV, FLAC, MP3, M4A/AAC, OGG and Opus, and the output extension picks the format. `Look: not needed` in the report; `Check:` still applies (`check.py file.wav --platform podcast`). Scripts that need a picture (`fit`, `caption`, `overlay`, `graphics`, `color`, `export`, `scenes`, `look`) refuse an audio file with "input has no video stream" — say so instead of forcing a video wrapper. The same commands work with `talk.wav` in place of `talk.mp4` (see the table above); the audio-specific recipes, packet vs sample precision, joining and extracting one track: `references/gotchas.md#audio-only-files`.+Audio is a first-class input: `probe.py`, `cut.py`, `silence.py`, `loudness.py`, `audio.py`, `sync.py` and `check.py --platform podcast` take WAV, FLAC, MP3, M4A/AAC, OGG and Opus, and the output extension picks the format. `Look: not needed` in the report; `Check:` still applies (`check.py file.wav --platform podcast`). Scripts that need a picture (`fit`, `caption`, `overlay`, `graphics`, `color`, `export`, `scenes`, `look`) refuse an audio file with "input has no video stream" — say so instead of forcing a video wrapper. The same commands work with `talk.wav` in place of `talk.mp4`; audio-specific recipes, packet vs sample precision, joining and extracting one track: `references/gotchas.md#audio-only-files`.## Report format-Reply in the language the request itself is written in — the language of the user's own sentences, not a language the request talks about (a request for subtitles in another language is still answered in the language it was written in) and not the language of a tool's error text or file names. Keep the field labels (`Done:`, `Steps:`, `Check:`, `Look:`, `Notes:`) in English: they read like log fields and stay recognisable across languages. Everything around them — the sentences, any question, any explanation of a judgement call — is in the user's language. Never default to English because the tool names and flags are English, and never drift into another language because the job was short or the report is a failure: a one-line "file does not exist" is written in the request's language too. A mid-conversation switch follows the user's latest message, not the first one. This holds for a one-command job: a three-second audio trim answered with English labels, numbers and one Japanese word in `Notes:` is an English report — the `Done:` description (what was cut, from where) and `Steps:` are in the user's language even when the values are technical.+Reply in the language the request itself is written in — the user's own sentences, not a language the request talks about (a request for subtitles in another language is still answered in the language it was written in) and not the language of a tool's error text or file names. Chinese, Korean, Spanish, Portuguese, French, German, Arabic or any other language works exactly the same way. Keep the field labels (`Done:`, `Steps:`, `Check:`, `Look:`, `Notes:`) in English: they read like log fields and stay recognisable across languages. Everything around them — the sentences, any question, any explanation of a judgement call — is in the user's language. Never default to English because the tool names and flags are English, and never drift into another language because the job was short or the report is a failure: a one-line "file does not exist" is written in the request's language too. A mid-conversation switch follows the user's latest message, not the first one. This holds for a one-command job: a three-second audio trim with English `Done:`/`Steps:` sentences and one word of the user's language in `Notes:` is an English report — the descriptions (what was cut, from where) are in the user's language even when the values are technical.Finish every job with this shape (numbers from a tool's `--json` or `probe.py`/`check.py`, not memory):@@ -154,7 +154,7 @@ Look: final_sheet.png (captions inside the safe area, logo top-right)Notes: source was VFR, conformed to 30 fps; audio was mono, made stereo```-The same five lines for a Japanese request, prose in Japanese around the English labels (the shape a short job keeps too; English `Done:`/`Steps:` sentences with one Japanese word in `Notes:` is not a Japanese report):+The same five lines for a Japanese request:```Done: final.mp4 — 59.98 秒、1080x1920、30 fps、H.264、AAC ステレオ、-14.1 LUFS@@ -164,7 +164,9 @@ Look: final_sheet.png(字幕はセーフエリア内、ロゴは右上)Notes: 元は VFR だったので 30 fps に揃えた。音声はモノラルだったのでステレオにした```-Keep it to those five lines plus anything the user must decide. Attach the contact sheet when the edit touched the picture. Never report success without the probe of the output; never describe a fix you did not run.+Same shape in every other language, labels still English — zh: `Done: final.mp4 — 59.98 秒、1080x1920、30 fps、H.264` / `Steps: 0:12-1:12 剪切 -> 9:16 裁剪 -> 字幕 -> Reels 导出`; ko: `Done: final.mp4 — 59.98초, 1080x1920, 30 fps, H.264` / `Steps: 0:12-1:12 컷 -> 9:16 크롭 -> 자막 -> Reels 내보내기`.++Keep it to those five lines plus anything the user must decide. Attach the contact sheet when the edit touched the picture. Never report success without the output probe; never describe a fix you did not run.When a step fails, replace `Done:` with `Failed:` and keep the rest honest:@@ -176,9 +178,9 @@ Look: not needed (nothing written)Notes: send a valid .cube, or say if you want the clip left as is```-A refusal (a judgement this skill does not make, or something outside its scope) uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run (usually only probe), `Look: not needed`. Both keep the five labels so a failed report scans like a successful one — including the shortest failure: a missing input or an invalid LUT still gets all five lines, never prose headings in their place. When a failure JSON carries `error.hint`, quote it in `Notes:`: it is the flag change that would make the retry meaningful.+A refusal (a judgement this skill does not make, or something outside its scope) uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run (usually only probe), `Look: not needed`. Both keep the five labels so a failed report scans like a successful one — the shortest failure (a missing input, an invalid LUT) still gets all five lines, never prose headings in their place. When a failure JSON carries `error.hint`, quote it in `Notes:`: it is the flag change that makes a retry meaningful.-Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | output | missing_tool | timeout | verification | interrupted, "message": ...}}` with `--json` and exits non-zero; quote the message, do not paraphrase it into a success.+Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | output | missing_tool | timeout | verification | interrupted, "message": ...}}` with `--json` and exits non-zero; quote the message, never paraphrase it into a success.## Things that look right but are wrong@@ -190,7 +192,8 @@ One line each, and each line is enough to act on; open the linked `references/go- VFR phone/screen recordings: re-encodes conform to CFR, `cut.py` switches to `--accurate`; pick the rate with `fit.py --fps` when the average is odd. Details: [#variable-frame-rate](references/gotchas.md#variable-frame-rate)- Sync/multicam `confidence` under 0.3 (or a huge offset) is probably wrong — check every camera, and remember these align audio, never lip sync. Details: [#sync-multicam-and-drift](references/gotchas.md#sync-multicam-and-drift)- "Normalised" audio can still clip (check true peak), and ambience at -40 LUFS or below must never be raised to a speech target. Details: [#loudness-and-ambience](references/gotchas.md#loudness-and-ambience)-- Captions burned before a crop/resize land off-frame; burned small then upscaled by `export.py` they come out soft — fit to the delivery size first. Non-Latin text without a real font renders boxes, not an error. Details: [#captions-fonts-and-text-order](references/gotchas.md#captions-fonts-and-text-order)+- Captions burned before a crop/resize land off-frame; burned small then upscaled by `export.py` they come out soft — fit to the delivery size first. Details: [#captions-fonts-and-text-order](references/gotchas.md#captions-fonts-and-text-order)+- Non-Latin text picks a font by script since 1.12; `doctor --json` `fonts.scripts` says which languages this machine renders; no font = failed job, not tofu. Details: [#fonts-by-script](references/gotchas.md#fonts-by-script)- `--fit crop` 16:9 → 9:16 throws away 70 % of the width, 60→30 fps halves the motion, and "60 seconds" by speed or by trim are different answers — say which and why. Details: [#reframing-fps-and-duration](references/gotchas.md#reframing-fps-and-duration)- `yuv420p` needs even dimensions and phone rotation tags are honoured, both automatically. Details: [#dimensions-and-rotation](references/gotchas.md#dimensions-and-rotation)- `scenes.py --highlights` ranks by loudness (or duration), never by meaning: check the sheet before treating picks as final. Details: [#highlights](references/gotchas.md#highlights)diff --git a/docs/contract.md b/docs/contract.mdindex f2af8b5..feb80cd 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -319,6 +319,25 @@ when `fc-match` itself is not on PATH or fails. Like `gpu_encoders`, this is purand never affects `ok` or any tool's `usable` — a substituted font is not a broken tool, just atypeface the caller didn't ask for.+Since 1.12 the same field also carries `scripts`: one entry per writing system the tools detect,+`{"ja": {"status": "available"|"missing"|"unknown", "file": "/path/to/font.ttc"|null}, "zh": ...,+"ko": ..., "ar": ..., "he": ..., "hi": ..., "th": ..., "ru": ..., "el": ...}`. It answers "which+languages can this machine actually render", which no filter or encoder capability asks:+`available` means `fc-list :lang=<code>` (Linux/macOS) or a known system font file (Windows) covers+the script, `missing` means fontconfig knows none, `unknown` means there is no working fontconfig to+ask (no `fc-list` on PATH, or it failed). `caption.py`, `graphics.py` and `overlay.py --text` resolve+a font by script automatically and fail with `kind: input` rather than render boxes **only for+`missing`**: `unknown` is not `missing` here any more than anywhere else in this document — the job+runs with the font as given and one info line says the coverage could not be verified. So a+`missing` script here is a job that will not run until a font is installed — but, like the default+font, it never affects `ok` or any tool's+`usable` (the tool works, this machine just has no glyphs for that language). The plain-text+`doctor` summarises the whole map on one `fonts:` line, which also carries the default font's+`detail` in brackets when its status is not `available` and that detail is short enough to keep the+line to one screen width; a longer explanation, and the per-script files, are `--json` only.+`--lang`/`--language` (caption, graphics) is the hint that says whether Han-only text is Chinese,+Japanese or Korean.+## InvocationStructured arguments are the canonical way to call a tool, on the CLI or through MCP.diff --git a/docs/roadmap.md b/docs/roadmap.mdindex b7908dc..8a4f833 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -87,15 +87,27 @@ and the default MCP `tools/list` are unchanged except for additions.- **Eval iteration 11** measures tokens per run and keeps only the changes that hold routing,honesty, language, report format and look behaviour at iteration-10 levels (pending).-## 1.12.0 — captions people can read--- `caption.py` wraps by measured text width (fontconfig metrics, not character count) so- CJK and long Latin lines stop overflowing the safe area; `--max-lines` and `--min-duration`- per cue; `--offset SECONDS` shifts an SRT/cues file; word-level timings from whisper's own- word output drive `--karaoke` instead of even splitting.-- `brand.json` caption styles (`styles.caption.{font,size,colour,box,position}`) so one brand- file gives every project the same look; `graphics.py` reads the same block.-- Eval 11: the 8 caption prompts (JA/EN, CJK wrap, karaoke, SRT offset) run 3 times.+## 1.12.0 — captions people can read, in any script (shipped)++- **Fonts by script** (done): `caption.py`, `graphics.py` and `overlay.py --text` detect the+ writing system of the text (ja, zh, ko, ar, he, hi, th, ru, el) and resolve a font file that+ covers it from `fc-list :lang=xx` (Windows: the known system fonts), logging the one it chose.+ No font for the script is a failed job (`kind: input`) with per-OS install hints, never a+ silent page of boxes. `--lang` on caption/graphics and `"lang"` in brand.json break the+ Han-only Chinese/Japanese/Korean tie; an explicit font is always kept, with a warning when it+ does not cover the text.+- **`doctor` per language** (done): `fonts.scripts` reports available/missing/unknown plus the+ file per writing system; the plain-text `doctor` keeps it to one line.+- **Readable cues** (done): `caption.py` wraps by measured width (a per-character table for+ Latin, a per-script advance elsewhere, zero for combining marks, which stay with their base) so+ CJK, Thai and all-caps Latin lines stop overflowing the safe area; `--max-lines` (default 2)+ splits a cue that needs more, `--min-duration` (default 1.0) holds a flashed cue, `--offset+ TIME` shifts SRT, ASS and cue files in the skill's timestamp grammar. Word-level timings from a whisper JSON drive+ `--karaoke` when the transcript has them, instead of an even split.+- **brand.json caption styles** (done): `styles.caption.{font,size,colour,box,position}` gives+ every project the same look; `graphics.py` reads `font` and `colour` from the same block.+- Eval 11: the 8 caption prompts (JA/EN, CJK wrap, karaoke, SRT offset) run 3 times, plus the+ per-language act/refuse prompts added for zh, ko, es, pt, fr, de and ar (pending).## 1.13.0 — the audio beddiff --git a/references/gotchas.md b/references/gotchas.mdindex b5be2fa..1a16383 100644--- a/references/gotchas.md+++ b/references/gotchas.md@@ -83,18 +83,60 @@ come out soft (a 1280x720 source fit to 9:16 is 406x720 until export scales it t1080x1920) — fit to the delivery size first(`fit.py --width 1080 --height 1920`), then caption, then export.-CJK and other non-Latin text: libass and drawtext need a font that has the-glyphs. Check with `fc-list | grep -i cjk`. Then either name it-(`caption.py --font "Noto Sans CJK JP"`) or point at the file-(`overlay.py --font-file /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc`,-`caption.py --fonts-dir ./fonts --font "Noto Sans CJK JP"`). Without a matching-font you get boxes, not an error. Install: `apt install fonts-noto-cjk`,-`brew install --cask font-noto-sans-cjk`.+Cue length and timing are handled for you since 1.12: `caption.py` wraps every+cue to the safe area by measured width at the chosen `--size`, splits a cue past+`--max-lines` (default 2) into consecutive cues, holds a cue shorter than+`--min-duration` (default 1.0 s) — never past the next cue — and shifts+everything by `--offset SECONDS`. It reports what it changed on one `cues:` line+and writes the adjusted copy next to the output, never over the file you passed+in. Wrapping needs the input video (the line width comes from its real frame+size); with `--write-srt` alone only the timing flags apply.Windows drawtext crashes on some real builds (#100): the drawtext tools resolve aconcrete `--font-file` by default, which avoids it; if one still crashes, pass`--font-file` explicitly. Details: `references/ci-platform-pitfalls.md`.+### Fonts by script+libass and drawtext draw an empty box per character they have no glyph for, and+ffmpeg still exits 0 — a video full of tofu is the classic "it worked" failure.+Since 1.12 `caption.py`, `graphics.py` and `overlay.py --text` detect the script+of the text they are about to draw (Japanese, Chinese, Korean, Arabic, Hebrew,+Devanagari, Thai, Cyrillic, Greek) and resolve a font file that covers it,+printing one line — `font: /usr/share/fonts/.../wqy-zenhei.ttc (covers ko)`.+**No font for the script is a failed job** (`kind: input`), not a warning.++- What this machine can render: `python3 scripts/_contract.py doctor --json`,+ field `fonts.scripts` (`available` / `missing` / `unknown` per language, with+ the file it would use). The plain-text `doctor` says the same in one line.+- What fontconfig has: `fc-list ":lang=ja" file family` (`ja`, `zh-cn`, `ko`,+ `ar`, `he`, `hi`, `th`, `ru`, `el`).+- Install: `apt install fonts-noto-cjk fonts-noto-core`, or+ `brew install --cask font-noto-sans-cjk font-noto-sans-arabic`, or point at a+ file with `--font-file` (`overlay.py`, `graphics.py`) / `--fonts-dir`+ (`caption.py`).+- Han characters alone (no kana, no hangul) are read as Chinese. Japanese or+ Korean hanja text with no kana needs `--lang ja` / `--lang ko`+ (`caption.py --language` is the same flag), or `"lang"` in brand.json.+- An explicit `--font`, an explicit `--font-file`, or a font your brand file+ itself names is always kept, even when fontconfig says it does not cover the script: you get one info+ line saying so, not a silent substitution. A brand file that never names a+ font is not a choice — the script still picks one.+- `--fonts-dir` (`caption.py`) adds faces to the search, it does not switch the+ check off: if nothing in the directory covers the script, one line says so and+ a covering font is resolved as usual.+- **No fontconfig is `unknown`, not `missing`.** With no `fc-list` on PATH (or+ one that fails) coverage cannot be verified: the job runs with the font as+ given behind one info line, because libass and drawtext have font backends of+ their own. Only fontconfig answering "nothing covers this" fails the job.+- **RTL:** libass shapes and reorders Arabic and Hebrew correctly, so+ `caption.py` — which renders every subtitle through libass, `subtitles=` and+ `ass=` alike — is right for them by construction. `drawtext` (`overlay.py+ --text`, `graphics.py`) depends on the build: `ffmpeg -version` showing+ `--enable-libfribidi` (and `--enable-libharfbuzz`) shapes and reorders RTL+ correctly too; a build without them draws logical order with unjoined+ letterforms. Nothing in the tools checks this, so on an unknown machine a+ caption is the safe place for Arabic/Hebrew.+### Reframing, fps and duration`--fit crop` to reach 9:16 from 16:9 throws away 70 % of the width: a wide shotloses people at the edges. Check the sheet; pad (bars), `--crop-x`/`--crop-y`diff --git a/references/scripts.md b/references/scripts.mdindex 6d876ff..94eea57 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -465,21 +465,35 @@ Inside this skill, call the scripts directly; the server is for other hosts.### graphics.py — motion-graphics templates```graphics.py INPUT --template lower-third|title|chapter|progress|countdown|bug [--name] [--title] [--subtitle]- [--from N] [--start S] [--end E] [--position CORNER] [--brand brand.json] [--primary RRGGBB] [--scale 1.0] [-o OUT]+ [--from N] [--start S] [--end E] [--position CORNER] [--brand brand.json] [--primary RRGGBB] [--scale 1.0] [--lang XX] [-o OUT]```Drawn with drawbox/drawtext/overlay — no PNG assets needed. Sizes scale withthe frame's short side; colours, font and safe margin come from `--brand`.Lower-third slides in over 0.4 s and out over 0.3 s; title/chapter/bug fade.+Non-Latin `--name`/`--title`/`--subtitle` text picks a font file by script the+same way `caption.py` does (`--lang XX` disambiguates Han-only text; no font for+the script fails the job). RTL shaping in drawtext depends on the ffmpeg build+(`--enable-libfribidi`/`--enable-libharfbuzz` shape it correctly, a build without+them does not); `caption.py` always shapes, because it renders through libass:+`references/gotchas.md#fonts-by-script`.### brand.json — one file for fonts, colours, logo, margins```json{"font": "Noto Sans CJK JP", "font_file": "fonts/NotoSansCJK-Bold.ttc","colors": {"primary": "FF6A00", "text": "FFFFFF", "outline": "000000", "background": "0B1D2A"},"logo": "logo.png", "logo_position": "top-right", "logo_scale": 160, "logo_opacity": 0.9,- "safe_margin": 48, "caption": {"size": 28, "position": "bottom", "animate": "pop", "karaoke": true, "bold": true}}+ "safe_margin": 48, "lang": "ja",+ "styles": {"caption": {"font": "Noto Sans CJK JP", "size": 28, "colour": "FFFFFF", "box": false, "position": "bottom"}},+ "caption": {"size": 28, "position": "bottom", "animate": "pop", "karaoke": true, "bold": true}}````caption.py --brand`, `overlay.py --brand --logo`, `graphics.py --brand`, and-`"brand": "brand.json"` in a render project. Explicit flags still win. When a+`"brand": "brand.json"` in a render project. Explicit flags still win.+`styles.caption` (1.12) is the one caption look every project shares —+`{font, size, colour, box, position}`, British or American spelling of colour —+read by `caption.py` and, for `font` and `colour`, by `graphics.py`; it wins+over the older top-level `caption` block where both set the same key, and that+block still carries the burn-in-only defaults (`animate`, `karaoke`, `bold`,+`outline`). `"lang"` is the script hint `--lang` would give. When auser mentions brand guidelines, colours, "our font" or a logo, ask for orwrite a brand.json once and reuse it across every output.@@ -526,7 +540,8 @@ frame like an editor would. Use `--compare` to show before/after to the user.### caption.py — subtitles (static, animated, karaoke)```caption.py INPUT --srt FILE | --ass FILE | --text CUES.txt [--write-srt OUT.srt]- [--mode burn|mux] [--audio-stream N] [--fps N]+ [--mode burn|mux] [--audio-stream N] [--fps N] [--lang XX] [--offset TIME]+ [--max-lines N] [--min-duration S][--font NAME] [--fonts-dir DIR] [--size N] [--color RRGGBB] [--outline N] [--outline-color RRGGBB][--bold] [--box] [--position bottom|top|center|top-left|...] [--margin N][--animate none|fade|pop|slide] [--karaoke [--highlight-color RRGGBB]] [--write-ass OUT.ass] [-o OUT]@@ -543,6 +558,43 @@ word from `--color` to `--highlight-color` across the cue; `--karaoke-timingenergy` (default) follows the speech loudness in the audio, `even` splits thecue equally (word timing is derived, not transcribed). The ASS is kept next to theuser can hand-tune timings and re-run with `--ass`.+Readable by default (1.12): every cue is wrapped to the safe area (90 % of the+frame width) at the chosen `--size`, measured per script — CJK and Thai count a+full em per character, Latin per character from a table read off DejaVu Sans (so+an all-caps line measures as wide as it draws), Cyrillic/Greek about 0.55,+Arabic/Hebrew 0.6, Devanagari 0.7, and a combining mark nothing at all —+breaking between characters for CJK/Thai and at spaces otherwise, but never+between a character and the combining marks that belong to it (Thai tone marks+and vowel signs, Devanagari matras, Arabic and Hebrew points). A cue that would need more than `--max-lines` (default 2) is split+into consecutive cues sharing its time; a cue shorter than `--min-duration`+(default 1.0 s) is held longer, never past the next cue's start; `--offset+TIME` shifts every cue (seconds, `mm:ss`, `hh:mm:ss.ms` or `hh:mm:ss:ff`, a+leading `-` for earlier) for `--text`, `--srt` and `--ass`. One `cues:` info line reports what changed. A file you passed in is+never edited: the adjusted copy is written next to the output+(`<out>_adjusted.srt`, `<out>_offset.ass`) and burned instead — under `--dry-run`+/`--plan` the planned command names that same copy and the plan says where it+comes from, but nothing is written until the real run. `--min-duration` and+`--offset` also work with `--write-srt` alone; `--max-lines` does not, because+wrapping needs the input video's real frame size.++Fonts by script (1.12): with no `--font` and no font named in your brand file, the+script of the cue text (Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari,+Thai, Cyrillic, Greek) picks a font file that covers it, logged as `font: <file>+(covers ko)`. Han-only text is read as Chinese unless `--lang ja|ko` (or+brand.json `"lang"`) says otherwise; `--language` is the same flag, and still+tags the subtitle stream under `--mode mux` and sets `--transcribe`'s language.+No font for the script fails the job (`kind: input`) instead of rendering boxes+— but only when fontconfig answered: with no working `fc-list` the coverage is+`unknown`, and the job runs with the font as given behind one info line. An+explicit font is always kept, with an info line when it does not cover the text;+`--fonts-dir` is searched first and checked with `fc-scan`, and a directory that+does not cover the script gets one line and a font resolved by script anyway. `doctor --json` `fonts.scripts` lists what this machine can render. See+`references/gotchas.md#fonts-by-script` (RTL: use captions, not drawtext).++`--karaoke` uses real per-word timings when the transcript has them (a whisper+`<stem>.json` or `<stem>.words.json` next to the SRT, `{"segments": [{"words":+[{"word", "start", "end"}]}]}`); otherwise `--karaoke-timing` decides.+`--mode burn` (default) renders subtitles into the picture and alwaysre-encodes both streams. `--mode mux` copies video and audio untouched andadds the SRT as a separate, player-toggleable subtitle stream instead —diff --git a/scripts/_common.py b/scripts/_common.pyindex 3590871..8e5b867 100755--- a/scripts/_common.py+++ b/scripts/_common.py@@ -1604,6 +1604,20 @@ def time_arg(value: str, flag: str, fps: Optional[float] = None) -> float: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@@ -1710,6 +1724,334 @@ def default_font_file(font_name: str) -> Optional[str]: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", "th", "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",+}++# 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"}++# 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"],+ "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")],+ "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))),+ ("th", ((0x0E00, 0x0E7F),)),+ ("ru", ((0x0400, 0x04FF), (0x0500, 0x052F), (0x2DE0, 0x2DFF))),+ ("el", ((0x0370, 0x03FF), (0x1F00, 0x1FFF))),+)+++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)+ 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 == "latin":+ 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 `text` for use as a single-quoted drawtext option value (`text='<this>'`).@@ -2044,6 +2386,11 @@ BRAND_DEFAULTS: Dict[str, Any] = {"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},}@@ -2052,6 +2399,7 @@ 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 copybrand = copy.deepcopy(BRAND_DEFAULTS)+ brand["_stated"] = {}if not path:return brandif not os.path.exists(path):@@ -2070,9 +2418,39 @@ def load_brand(path: Optional[str]) -> Dict[str, Any]: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"] = datareturn 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("#")diff --git a/scripts/_contract.py b/scripts/_contract.pyindex 9e82401..06ac9a4 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -765,9 +765,53 @@ def doctor() -> Dict[str, Any]:def _fonts_capability() -> Dict[str, Any]:+ """The default drawtext family (issue #66) plus, since 1.12, one entry per script the tools+ can detect: which languages this machine can actually RENDER, not just which filters exist.++ Per script: available (a font file covers it, path in `file`), missing (fontconfig knows none),+ unknown (no fontconfig to ask -- the same "unknown is not missing" rule every other capability+ here follows). Informational like the default font and gpu_encoders: a machine with no Thai+ font is not a broken install, it is a machine that must not be asked to burn Thai captions.+ """+ from _common import SCRIPTS, font_for_script, script_font_status+font = _default_font()result = _font_available(font)- return {"default_font": font, "status": result["status"], "detail": result["detail"]}+ scripts: Dict[str, Any] = {}+ for script in SCRIPTS:+ if script == "latin":+ continue+ # script_font_status() is the one place that tells "fontconfig answered, nothing covers+ # this" (missing) apart from "there is no working fontconfig to ask" (unknown) -- the same+ # distinction the tools refuse or continue on.+ status = script_font_status(script)+ scripts[script] = {"status": status, "file": font_for_script(script) if status == "available" else None}+ return {"default_font": font, "status": result["status"], "detail": result["detail"], "scripts": scripts}+++def _fonts_summary_line(fonts: Dict[str, Any]) -> str:+ """One line for the plain-text doctor: which scripts render here, which do not."""+ scripts = fonts.get("scripts") or {}+ by_state: Dict[str, List[str]] = {"available": [], "missing": [], "unknown": []}+ for name, entry in scripts.items():+ by_state.setdefault(entry["status"], []).append(name)+ # the default font's `detail` (which family fontconfig substituted, or why it is unknown) is+ # the actionable half of a non-available status, and the line has room for it+ head = f"fonts: '{fonts['default_font']}' {fonts['status']}"+ detail = fonts.get("detail") or ""+ # The substituted family is the actionable half of a non-available status, so it goes on the+ # plain line -- but only while it stays short enough to keep doctor's one-line-per-capability+ # shape (the longest other line is ~85 chars). A long explanation is --json only.+ if detail and fonts["status"] != "available" and len(detail) <= 60:+ head += f" ({detail})"+ parts = [head]+ if by_state["available"]:+ parts.append("renders " + " ".join(by_state["available"]))+ if by_state["missing"]:+ parts.append("no font for " + " ".join(by_state["missing"]))+ if by_state["unknown"]:+ parts.append("unknown (no fontconfig) " + " ".join(by_state["unknown"]))+ return "; ".join(parts)def _capability_fix_hint(cap: str) -> str:@@ -795,6 +839,11 @@ def _capability_fix_hint(cap: str) -> str:return f"this ffmpeg build has no {cap[7:]} filter; {full_hint}"if cap.startswith("bsf:"):return f"this ffmpeg build has no {cap[4:]} bitstream filter; {full_hint}"+ if cap.startswith("font:"):+ from _common import LANGUAGE_NAMES, FONT_INSTALL_HINT+ script = cap[5:]+ return (f"no installed font covers {LANGUAGE_NAMES.get(script, script)} text on this machine; "+ f"{FONT_INSTALL_HINT} (doctor --json .fonts.scripts lists every script)")if cap == "external:whisper":return "install a local whisper (whisper-cli, whisper-cpp, faster-whisper or openai-whisper) for --transcribe"return f"'{cap}' is not available; see docs/contract.md"@@ -1152,9 +1201,7 @@ def main() -> int:gpu = d["gpu_encoders"]if gpu["status"] == "parsed":print(f"GPU-backed encoders in this build: {len(gpu['present'])} (no tool here uses one; names in doctor --json)")- fonts = d["fonts"]- print(f"default drawtext font '{fonts['default_font']}': {fonts['status']}"- + (f" ({fonts['detail']})" if fonts["status"] != "available" else ""))+ print(_fonts_summary_line(d["fonts"]))print("full detail: doctor --json (capability lists, per-tool `usable`, fix hints)")for err in d["errors"]:print(f"detection error: {err}", file=sys.stderr)diff --git a/scripts/caption.py b/scripts/caption.pyindex 024d76f..a071f36 100755--- a/scripts/caption.py+++ b/scripts/caption.py@@ -28,15 +28,19 @@ Examples:python3 caption.py input.mp4 --srt subs.srt --font "Noto Sans CJK JP" --size 28 --position toppython3 caption.py --text cues.txt --write-srt cues.srt # only produce the SRTpython3 caption.py input.mp4 --text cues.txt # generate + burn in one go+ python3 caption.py input.mp4 --text cues_ko.txt --lang ko # a font that covers the script is picked automatically+ python3 caption.py input.mp4 --srt subs.srt --offset -0.4 --max-lines 2 --min-duration 1.2"""import argparse+import jsonimport osimport reimport sys+import unicodedatafrom pathlib import Pathfrom typing import List, Optional, Tuple-from _common import STATE, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs+from _common import STATE, brand_states_font, char_script, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secsALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}@@ -293,6 +297,310 @@ def word_durations_from_audio(video: str, start: float, end: float, n_words: intreturn out+# --------------------------------------------------------------------------- readable cues (1.12)+# 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}+# How much of the frame width a caption line may use. libass's own default SRT margins are 10 of a+# 384-wide script (2.6 % a side); 5 % a side is the safe area every platform check in this repo uses.+SAFE_WIDTH_FRACTION = 0.9+# 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) == "Mn":+ return 0.0+ if 0x3000 <= cp <= 0x303F or 0xFF01 <= cp <= 0xFF60 or 0xFFE0 <= cp <= 0xFFE6:+ return 1.0+ script = char_script(ch)+ 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) -> float:+ """Width of `text` in em, from the per-script average advance table."""+ return sum(_char_em(ch) for ch in text)+++def _atoms(line: str) -> List[Tuple[str, bool]]:+ """Break a line into the smallest pieces a wrap may separate -- one atom per CJK/Thai+ character, one per whitespace-delimited word otherwise -- each with whether a space stood+ before it in the original. The flag is what puts the text back together exactly as written:+ "Hello 世界" keeps its space, "世界です" gains none."""+ out: List[Tuple[str, bool]] = []+ word = ""+ spaced = False # a space stands before the atom being built+ pending = False # a space stands before the NEXT atom+ attach_next = False # a leading Thai/Lao vowel is waiting for its base consonant+ for ch in line:+ if char_script(ch) in NO_SPACE_SCRIPTS:+ if word:+ out.append((word, spaced))+ word = ""+ if out and (attach_next or _is_mark(ch)):+ # never break between a base and the mark (or the leading vowel) that belongs to+ # it: the line would start with an orphaned tone mark or vowel sign+ out[-1] = (out[-1][0] + ch, out[-1][1])+ else:+ out.append((ch, pending))+ pending = False+ attach_next = ord(ch) in LEADING_VOWELS+ elif ch.isspace():+ if word:+ out.append((word, spaced))+ word = ""+ pending = True+ else:+ if not word:+ spaced, pending = pending, False+ word += ch+ if word:+ out.append((word, spaced))+ return out+++def _join(left: str, atom: str, spaced: bool) -> str:+ """Put an atom back on a line, restoring the space that stood before it."""+ if not left:+ return atom+ return left + (" " if spaced else "") + atom+++def wrap_text(text: str, max_em: float) -> List[str]:+ """Wrap `text` to lines no wider than `max_em` em, keeping the manual breaks it already has.++ An atom wider than the whole line (one very long word) is left alone on its line rather than+ cut mid-word: an over-long line is readable, a chopped word is not.+ """+ lines: List[str] = []+ for raw in text.split("\n"):+ if not raw.strip():+ continue+ current = ""+ for atom, spaced in _atoms(raw):+ candidate = _join(current, atom, spaced)+ if current and text_width_em(candidate) > max_em:+ lines.append(current)+ current = atom+ else:+ current = candidate+ if current:+ lines.append(current)+ return lines or [text]+++def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float], max_lines: int,+ min_duration: float, offset: float) -> Tuple[List[Tuple[float, float, str]], dict]:+ """Shift, wrap, split and lengthen cues so they can actually be read.++ `offset` moves every cue (a transcript that runs early/late); `max_em` wraps each cue to the+ safe area at the chosen size (None when no video geometry is known, e.g. --write-srt alone);+ a cue needing more than `max_lines` lines is split into consecutive cues sharing its time in+ proportion to their text; a cue shorter than `min_duration` is lengthened, never past the next+ cue's start. Returns the new cues and a count of what changed.+ """+ stats = {"shifted": 0, "wrapped": 0, "split": 0, "extended": 0, "dropped": 0}+ staged: List[Tuple[float, float, str]] = []+ for start, end, text in cues:+ if offset:+ start, end = start + offset, end + offset+ if end <= 0:+ stats["dropped"] += 1+ continue+ start = max(0.0, start)+ stats["shifted"] += 1+ if max_em and max_em > 0:+ lines = wrap_text(text, max_em)+ if lines != [l for l in text.split("\n") if l.strip()]:+ stats["wrapped"] += 1+ if len(lines) > max_lines:+ chunks = [lines[i:i + max_lines] for i in range(0, len(lines), max_lines)]+ weights = [max(1.0, sum(len(l) for l in c)) for c in chunks]+ total_w = sum(weights)+ t = start+ for chunk, weight in zip(chunks, weights):+ seg = (end - start) * weight / total_w+ staged.append((t, min(end, t + seg), "\n".join(chunk)))+ t += seg+ stats["split"] += len(chunks) - 1+ continue+ text = "\n".join(lines)+ staged.append((start, end, text))+ out: List[Tuple[float, float, str]] = []+ for i, (start, end, text) in enumerate(staged):+ if min_duration and end - start < min_duration:+ limit = staged[i + 1][0] if i + 1 < len(staged) else None+ new_end = start + min_duration if limit is None else min(start + min_duration, limit)+ if new_end > end:+ stats["extended"] += 1+ end = new_end+ out.append((start, end, text))+ return out, stats+++def report_layout(stats: dict) -> None:+ """One info line, only when a cue actually changed."""+ parts = [f"{stats[k]} {k}" for k in ("shifted", "wrapped", "split", "extended", "dropped") if stats.get(k)]+ if parts:+ info("cues: " + ", ".join(parts))+++def max_line_em(args, play_w: Optional[int], play_h: Optional[int]) -> Optional[float]:+ """How many em fit on one caption line at the chosen size, or None without video geometry.++ --size is in ASS points against a 288-line script (what libass's force_style uses), so the+ rendered pixel size is size * play_h / 288.+ """+ if not play_w or not play_h or not args.size:+ return None+ size_px = args.size * play_h / 288.0+ if size_px <= 0:+ return None+ return (play_w * SAFE_WIDTH_FRACTION) / size_px+++def parse_ass_dialogue(path: str) -> str:+ """The spoken text of an ASS file, for script detection -- style/override blocks stripped."""+ text = []+ for line in read_text_or_die(path, "--ass").lstrip("\ufeff").splitlines():+ if not line.startswith("Dialogue:"):+ continue+ fields = line.split(",", 9)+ if len(fields) == 10:+ text.append(re.sub(r"\{[^}]*\}", "", fields[9]))+ return "\n".join(text)+++def shift_ass_file(src: str, dst: str, offset: float) -> int:+ """Copy an ASS file with every Dialogue start/end moved by `offset` seconds."""+ def shift(stamp: str) -> str:+ h, m, rest = stamp.split(":")+ secs = int(h) * 3600 + int(m) * 60 + float(rest) + offset+ secs = max(0.0, secs)+ cs = int(round(secs * 100))+ hh, rem = divmod(cs, 360000)+ mm, rem = divmod(rem, 6000)+ ss, cc = divmod(rem, 100)+ return f"{hh}:{mm:02d}:{ss:02d}.{cc:02d}"++ n = 0+ out = []+ for line in Path(src).read_text(encoding="utf-8-sig").splitlines():+ if line.startswith("Dialogue:"):+ head, sep, rest = line.partition(":")+ fields = rest.split(",")+ if len(fields) >= 3:+ try:+ fields[1], fields[2] = shift(fields[1].strip()), shift(fields[2].strip())+ line = head + sep + ",".join(fields)+ n += 1+ except (ValueError, IndexError):+ pass+ out.append(line)+ Path(dst).write_text("\n".join(out) + "\n", encoding="utf-8-sig")+ return n+++def whisper_word_timings(srt_path: Optional[str]) -> List[Tuple[float, float, str]]:+ """Word timings from a whisper JSON transcript sitting next to the SRT, if there is one.++ whisper (and faster-whisper, and whisper.cpp's --output-json) can emit per-word start/end+ times; when they are there, --karaoke should follow the real speech instead of splitting the+ cue evenly. Looked for as <stem>.json and <stem>.words.json next to the SRT, in either the+ {"segments": [{"words": [{"word": ..., "start": ..., "end": ...}]}]} or a bare+ {"words": [...]} shape. Anything unreadable is simply "no word timings".+ """+ if not srt_path:+ return []+ stem = os.path.splitext(srt_path)[0]+ for cand in (stem + ".words.json", stem + ".json"):+ if not os.path.exists(cand):+ continue+ try:+ data = json.loads(Path(cand).read_text(encoding="utf-8"))+ except (OSError, ValueError):+ continue+ raw = []+ if isinstance(data, dict):+ raw = list(data.get("words") or [])+ for seg in data.get("segments") or []:+ raw.extend((seg or {}).get("words") or [])+ words = []+ for w in raw:+ try:+ text = str(w.get("word") or w.get("text") or "").strip()+ if text:+ words.append((float(w["start"]), float(w["end"]), text))+ except (AttributeError, KeyError, TypeError, ValueError):+ continue+ if words:+ info(f"karaoke: word timings from {os.path.basename(cand)} ({len(words)} words)")+ return sorted(words)+ return []+++def word_durations_from_timings(words: List[Tuple[float, float, str]], start: float, end: float,+ n_words: int) -> Optional[List[int]]:+ """Centiseconds per word for one cue, from real word timings; None when they don't cover it."""+ inside = [w for w in words if w[1] > start + 0.01 and w[0] < end - 0.01]+ if len(inside) != n_words or n_words <= 0:+ return None+ total_cs = max(1, int(round((end - start) * 100)))+ bounds = [max(start, inside[0][0])] + [max(start, min(end, w[1])) for w in inside]+ out = [max(1, int(round((bounds[i + 1] - bounds[i]) * 100))) for i in range(n_words)]+ out[-1] += total_cs - sum(out)+ if out[-1] < 1:+ return None+ return out++def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int, play_h: int, video: str = None) -> None:"""Write a styled ASS file with optional animation and word-by-word highlight."""def t(sec: float) -> str:@@ -341,11 +649,15 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: intdur_cs = max(1, int(round((end - start) * 100)))segments = body.split("\\N")words = [w for seg in segments for w in seg.split(" ") if w]- if getattr(args, "karaoke_timing", "even") == "energy" and video:- durs = word_durations_from_audio(video, start, end, len(words), getattr(args, "audio_stream", 0))- else:- per = max(1, dur_cs // max(1, len(words)))- durs = [per] * len(words)+ # real word timings from the transcript beat both the energy estimate and the even+ # split -- they are what the speaker actually did, not a proxy for it+ durs = word_durations_from_timings(getattr(args, "_word_timings", None) or [], start, end, len(words))+ if durs is None:+ if getattr(args, "karaoke_timing", "even") == "energy" and video:+ durs = word_durations_from_audio(video, start, end, len(words), getattr(args, "audio_stream", 0))+ else:+ per = max(1, dur_cs // max(1, len(words)))+ durs = [per] * len(words)it = iter(durs)out_segments = []for seg in segments:@@ -391,6 +703,23 @@ def ass_font_name(name: str) -> str:return name+def _glue_negative_offset(argv: List[str]) -> List[str]:+ """`--offset -0:00:02` reads as a flag to argparse, not a value: only bare negative NUMBERS+ are exempt from the "starts with -" rule, and a negative timecode is not one. Join the pair+ into `--offset=-0:00:02` so the documented grammar works in the shape people type it."""+ out: List[str] = []+ i = 0+ while i < len(argv):+ nxt = argv[i + 1] if i + 1 < len(argv) else ""+ if argv[i] == "--offset" and nxt.startswith("-") and not nxt.startswith("--"):+ out.append(f"--offset={nxt}")+ i += 2+ continue+ out.append(argv[i])+ i += 1+ return out++def main() -> int:ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)ap.add_argument("input", nargs="?", help="video to burn captions into (omit with --write-srt to only generate)")@@ -407,7 +736,11 @@ def main() -> int:src.add_argument("--ass", help="ASS file to burn (styles inside the file are used)")src.add_argument("--text", help="plain text cue file to convert into SRT (see format above)")src.add_argument("--transcribe", action="store_true", help="generate the SRT from the audio with a local speech-to-text engine if one is installed (whisper-cli / whisper / faster-whisper); never required")- src.add_argument("--language", help="language code for --transcribe (e.g. en, ja; default auto), also tagged on the subtitle stream with --mode mux")+ src.add_argument("--language", "--lang", help="language code (e.g. en, ja, zh, ko): the language for --transcribe (default auto), "+ "the tag on the subtitle stream with --mode mux, and the hint that says whether Han-only "+ "text is Chinese, Japanese or Korean when a font is picked by script")+ src.add_argument("--offset", default="0", help="shift every cue by TIME (seconds, mm:ss, hh:mm:ss.ms or "+ "hh:mm:ss:ff; a leading - shifts earlier); works for --text, --srt and --ass")src.add_argument("--model", default="base", help="whisper model name/path for --transcribe (default base)")src.add_argument("--write-srt", help="where to save the generated SRT (default: <text>.srt)")src.add_argument("--auto-seconds", type=float, default=3.0, help="duration for cues without timing (default 3)")@@ -428,6 +761,8 @@ def main() -> int:sty.add_argument("--position", choices=sorted(ALIGN), default=None, help="on-screen placement (default bottom)")sty.add_argument("--margin", type=int, default=30, help="vertical margin from the edge (default 30)")sty.add_argument("--box", action="store_true", help="draw an opaque box behind text instead of an outline")+ sty.add_argument("--max-lines", type=int, default=2, help="most lines one cue may occupy; a longer cue is split into consecutive cues (default 2)")+ sty.add_argument("--min-duration", type=float, default=1.0, help="shortest time a cue stays on screen in seconds, never past the next cue (default 1.0)")anim = ap.add_argument_group("animation (generates ASS; needs --text or --srt input)")anim.add_argument("--animate", choices=["none", "fade", "pop", "slide"], default=None, help="per-cue entrance animation (default none, or brand caption.animate)")anim.add_argument("--karaoke", action="store_true", help="word-by-word highlight (fills from --color to --highlight-color across each cue)")@@ -439,14 +774,21 @@ def main() -> int:enc.add_argument("--crf", type=int, default=18)enc.add_argument("--preset", default="medium", choices=X264_PRESETS)add_common(ap)- args = ap.parse_args()+ args = ap.parse_args(_glue_negative_offset(sys.argv[1:]))apply_common(args)brand = load_brand(args.brand)- bc, bcap = brand["colors"], brand["caption"]- args.font = args.font or brand.get("font") or "DejaVu Sans"+ bc, bcap = brand["colors"], brand_caption_style(brand)+ # A brand file that never names a font is not an explicit font: BRAND_DEFAULTS always+ # supplies one, so asking the merged document would turn font-by-script off for every job+ # that passes --brand at all.+ font_explicit = bool(args.font) or bool(args.brand and brand_states_font(brand))+ args.language = args.language or (brand.get("lang") if args.brand else None)+ if args.brand and bcap.get("box") and not args.box:+ args.box = True+ args.font = args.font or (bcap.get("font") if args.brand else None) or brand.get("font") or "DejaVu Sans"args.size = args.size if args.size is not None else (bcap.get("size", 24) if args.brand else 24)- args.color = color_hex(args.color or bc.get("text", "FFFFFF"))+ args.color = color_hex(args.color or (bcap.get("color") if args.brand else None) or bc.get("text", "FFFFFF"))args.outline_color = color_hex(args.outline_color or bc.get("outline", "000000"))args.outline = args.outline if args.outline is not None else (float(bcap.get("outline", 2)) if args.brand else 2.0)args.position = args.position or (bcap.get("position", "bottom") if args.brand else "bottom")@@ -469,6 +811,12 @@ def main() -> int:if args.animate != "none" or args.karaoke:die("--animate/--karaoke render pixels into the picture and require --mode burn")+ args.offset = signed_time_arg(str(args.offset), "--offset")+ if args.max_lines < 1:+ die("--max-lines must be at least 1")+ if args.min_duration < 0:+ die("--min-duration cannot be negative")+meta = Noneif args.input:meta = probe(args.input)@@ -483,6 +831,22 @@ def main() -> int:if fps_for_tc is None and meta is not None:fps_for_tc = meta.get("video", {}).get("fps")+ play_w = play_h = None+ if meta and meta.get("video"):+ play_w, play_h = meta["video"]["width"], meta["video"]["height"]+ if meta["video"].get("rotation") in (90, -90, 270, -270):+ play_w, play_h = play_h, play_w++ def lay_out(cue_list):+ """Wrap to the safe area, split past --max-lines, lengthen to --min-duration, shift by+ --offset -- the one place every cue source goes through, so an SRT, a cue file and a+ transcript all come out equally readable."""+ out, stats = layout_cues(cue_list, max_em=max_line_em(args, play_w, play_h),+ max_lines=args.max_lines, min_duration=args.min_duration,+ offset=args.offset)+ report_layout(stats)+ return out, any(stats.values())+srt_path = args.srtif args.transcribe:if not args.input:@@ -497,10 +861,15 @@ def main() -> int:if os.path.exists(srt_path) and not getattr(args, "overwrite", False):info(f"warning: {srt_path} already exists and will be replaced by the transcript (pass --overwrite to confirm)")cues = transcribe(args.input, srt_path, args.language, args.model, args.audio_stream)+ args._word_timings = whisper_word_timings(srt_path)+ cues, changed = lay_out(cues)+ if changed:+ write_srt(cues, srt_path)info(f"wrote {srt_path} ({len(cues)} cues)")args.text = Noneif args.text:cues = parse_text_cues(args.text, args.auto_seconds, args.gap, fps_for_tc)+ cues, _ = lay_out(cues)if args.write_srt:srt_path = args.write_srtelif args.input:@@ -522,8 +891,48 @@ def main() -> int:output = args.output or default_output(args.input, "captioned")+ # An SRT or ASS the caller wrote is never edited in place: when --offset/--max-lines/+ # --min-duration change it, the adjusted copy is written next to the output and burned instead.+ # The path is repointed in BOTH modes: --dry-run/--plan must describe the job the real run+ # executes, so the planned command names the adjusted copy the real run burns. Only the+ # WRITING waits for a real run (the rule every side file in this tool follows), which is why+ # the cues are kept in hand below for the font sample and the ASS generator.+ planned_cues: Optional[List[Tuple[float, float, str]]] = None+ side_notes: List[str] = []+ ass_sample_path = args.ass+ if args.srt and not (args.text or args.transcribe) and os.path.exists(srt_path or ""):+ adjusted, changed = lay_out(parse_srt(srt_path))+ if changed:+ new_srt = os.path.splitext(output)[0] + "_adjusted.srt"+ if STATE.dry_run:+ info(f"[dry-run] would write {new_srt} ({len(adjusted)} cues, adjusted from {os.path.basename(srt_path)})")+ else:+ write_srt(adjusted, new_srt)+ info(f"wrote {new_srt} ({len(adjusted)} cues, adjusted from {os.path.basename(srt_path)})")+ srt_path = new_srt+ planned_cues = adjusted+ side_notes.append(f"the burned subtitles are {new_srt}, the adjusted copy of "+ f"{os.path.basename(args.srt)} this run writes (--offset/--max-lines/--min-duration); "+ "re-run this command without --dry-run to produce it")+ if args.ass and args.offset and os.path.exists(args.ass):+ shifted = os.path.splitext(output)[0] + "_offset.ass"+ if STATE.dry_run:+ info(f"[dry-run] would write {shifted} (cues shifted by {args.offset:+g} s)")+ else:+ n = shift_ass_file(args.ass, shifted, args.offset)+ info(f"wrote {shifted} ({n} cues shifted by {args.offset:+g} s)")+ args.ass = shifted+ side_notes.append(f"the burned subtitles are {shifted}, the offset copy of "+ f"{os.path.basename(ass_sample_path)} this run writes; re-run this command "+ "without --dry-run to produce it")+ # a side file this run has planned but (under --dry-run) not written is still the file the+ # command names, so its absence must not be reported as a missing input+ planned_only = STATE.dry_run and planned_cues is not None+ planned_ass = STATE.dry_run and bool(args.ass) and args.ass != ass_sample_path+if args.mode == "mux":- if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and (args.text or args.transcribe))):+ if not srt_path or (not os.path.exists(srt_path) and not planned_only+ and not (STATE.dry_run and (args.text or args.transcribe))):die(f"SRT file not found: {srt_path}")codec = mux_subtitle_codec(output)# Keep any subtitle track(s) the input already has (e.g. chaining --mode mux once per@@ -550,8 +959,31 @@ def main() -> int:emit(output)return 0+ # A font that covers the text, before anything is rendered: non-Latin cues in a Latin-only+ # family come out as empty boxes, and ffmpeg exits 0 all the same (see references/gotchas.md).+ if args.ass:+ sample = parse_ass_dialogue(ass_sample_path) if ass_sample_path and os.path.exists(ass_sample_path) else ""+ elif args.text or args.transcribe:+ sample = "\n".join(t for _, _, t in cues)+ elif planned_cues is not None:+ sample = "\n".join(t for _, _, t in planned_cues)+ else:+ sample = "\n".join(t for _, _, t in parse_srt(srt_path)) if os.path.exists(srt_path or "") else ""+ _script, font_file, font_family = script_font_for_text(+ sample, lang=args.language, font=args.font, font_explicit=font_explicit,+ fonts_dir=args.fonts_dir)+ if font_file:+ args.font = font_family or args.font+ if not args.fonts_dir:+ args.fonts_dir = os.path.dirname(font_file)+if (args.animate != "none" or args.karaoke) and not args.ass:- cues_for_ass = cues if (args.text or args.transcribe) else parse_srt(srt_path)+ # both sources are already laid out: `cues` above, and srt_path was rewritten in place of+ # the caller's file when --offset/--max-lines/--min-duration changed anything+ cues_for_ass = cues if (args.text or args.transcribe) else (+ planned_cues if planned_cues is not None else parse_srt(srt_path))+ if args.karaoke and not getattr(args, "_word_timings", None):+ args._word_timings = whisper_word_timings(srt_path)ass_path = args.write_ass or os.path.splitext(output)[0] + ".ass"w, h = meta["video"]["width"], meta["video"]["height"]if meta["video"].get("rotation") in (90, -90, 270, -270):@@ -565,13 +997,14 @@ def main() -> int:generated_ass = Falseif args.ass:- if not generated_ass and not os.path.exists(args.ass):+ if not generated_ass and not os.path.exists(args.ass) and not planned_ass:die(f"ASS file not found: {args.ass}")vf = f"ass={escape_filter_path(args.ass)}"if args.fonts_dir:vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"else:- if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and (args.text or args.transcribe))):+ if not srt_path or (not os.path.exists(srt_path) and not planned_only+ and not (STATE.dry_run and (args.text or args.transcribe))):die(f"SRT file not found: {srt_path}")style = [f"FontName={ass_font_name(args.font)}",@@ -599,7 +1032,7 @@ def main() -> int:run(cmd)result = probe(output, role="output")info(f"wrote {output} ({fmt_secs(result.get('duration'))})")- emit(output)+ emit(output, **({"notes": side_notes} if side_notes else {}))return 0diff --git a/scripts/graphics.py b/scripts/graphics.pyindex 443b558..0f8f0cc 100755--- a/scripts/graphics.py+++ b/scripts/graphics.py@@ -15,13 +15,14 @@ Examples:python3 graphics.py talk.mp4 --template title --title "Episode 12" --subtitle "The math of video" --start 0 --end 4python3 graphics.py talk.mp4 --template progress --brand brand.jsonpython3 graphics.py intro.mp4 --template countdown --from 5 --start 1 --end 6+ python3 graphics.py talk.mp4 --template lower-third --name "김민준" --title "감독" --lang kopython3 graphics.py clip.mp4 --template chapter --title "Part 2 — Setup" --position top-left --start 0 --end 5"""import argparseimport sysfrom typing import List, Optional-from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderw, X264_PRESETS, time_arg, fmt_secs+from _common import aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderw, X264_PRESETS, time_arg, fmt_secsTEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug"]@@ -30,9 +31,11 @@ def ff_color(hex_rgb: str, alpha: float = 1.0) -> str:return f"0x{color_hex(hex_rgb)}@{alpha:g}"-def font_opts(brand: dict, font: Optional[str], font_file: Optional[str]) -> str:+def font_opts(brand: dict, font: Optional[str], font_file: Optional[str], script_file: Optional[str] = None) -> str:if font_file or brand.get("font_file"):return f"fontfile={escape_filter_path(font_file or brand['font_file'])}"+ if script_file: # a font picked by the script of the text itself (1.12)+ return f"fontfile={escape_filter_path(script_file)}"resolved = default_font_file(font or brand.get("font", "DejaVu Sans"))if resolved:return f"fontfile={escape_filter_path(resolved)}"@@ -60,6 +63,8 @@ def main() -> int:ap.add_argument("--text-color", help="override text colour RRGGBB")ap.add_argument("--font")ap.add_argument("--font-file")+ ap.add_argument("--lang", help="language code of the text (e.g. ja, zh, ko): the hint that says whether Han-only "+ "text is Chinese, Japanese or Korean when a font is picked by script")ap.add_argument("--scale", type=float, default=1.0, help="size multiplier (default 1)")ap.add_argument("--crf", type=int, default=18)ap.add_argument("--preset", default="medium", choices=X264_PRESETS)@@ -72,7 +77,17 @@ def main() -> int:text_c = color_hex(args.text_color or brand["colors"]["text"])bg = color_hex(brand["colors"].get("background", "101418"))margin = int(brand.get("safe_margin", 48))- fo = font_opts(brand, args.font, args.font_file)+ style = brand_caption_style(brand) # styles.caption is shared with caption.py+ if args.brand and style.get("font") and not args.font:+ args.font = style["font"]+ if args.brand and style.get("color") and not args.text_color:+ text_c = color_hex(style["color"])+ args.lang = args.lang or (brand.get("lang") if args.brand else None)+ # a font that covers the text before drawtext renders boxes instead of glyphs (1.12)+ _script, script_file, _family = script_font_for_text(+ " ".join(t for t in (args.name, args.title, args.subtitle) if t),+ lang=args.lang, font=args.font, font_explicit=bool(args.font), font_file=args.font_file or brand.get("font_file"))+ fo = font_opts(brand, args.font, args.font_file, script_file)meta = probe(args.input)if not meta.get("video"):diff --git a/scripts/overlay.py b/scripts/overlay.pyindex dd38bc4..24818ca 100755--- a/scripts/overlay.py+++ b/scripts/overlay.py@@ -24,7 +24,7 @@ import argparseimport sysfrom typing import List, Optional-from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs+from _common import STATE, script_font_for_text, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secsPOS = {"top-left": ("{m}", "{m}"),@@ -144,6 +144,14 @@ def main() -> int:args.font = brand.get("font", args.font)if not args.font_file and brand.get("font_file"):args.font_file = brand["font_file"]+ if args.text and not args.font_file:+ # 1.12: non-Latin overlay text picks a font by script, so a title in Japanese, Korean,+ # Arabic ... draws glyphs instead of boxes. drawtext does not shape or reorder RTL text --+ # see references/gotchas.md#fonts-by-script.+ _script, script_file, _family = script_font_for_text(+ args.text, font=args.font, font_explicit=args.font != ap.get_default("font"), font_file=args.font_file)+ if script_file:+ args.font_file = script_fileif not args.font_file:args.font_file = default_font_file(args.font)meta = probe(args.input)diff --git a/scripts/render.py b/scripts/render.pyindex 45de4a9..78c0890 100755--- a/scripts/render.py+++ b/scripts/render.py@@ -91,9 +91,10 @@ OBJECT_KEYS: Dict[str, frozenset] = {"transition": frozenset({"type", "duration"}),"silence": frozenset({"threshold", "min_silence", "margin"}),"captions": frozenset({"text", "srt", "ass", "font", "size", "color", "position", "margin",- "animate", "highlight_color", "outline", "karaoke", "bold", "box"}),+ "animate", "highlight_color", "outline", "karaoke", "bold", "box",+ "lang", "offset", "max_lines", "min_duration"}),"graphics[]": frozenset({"template", "name", "title", "subtitle", "start", "end", "position",- "from", "scale", "primary", "text_color"}),+ "from", "scale", "primary", "text_color", "lang"}),"overlays[]": frozenset({"logo", "image", "text", "position", "start", "end", "fade", "opacity","scale", "font_size", "font", "font_file", "margin", "box"}),"audio": frozenset({"music", "replace", "music_volume", "fade_in", "fade_out", "music_fade_out",@@ -418,7 +419,7 @@ def main() -> int:argv += ["--ass", rel(cap["ass"])]else:die("captions needs text, srt or ass")- for k, flag in (("font", "--font"), ("size", "--size"), ("color", "--color"), ("position", "--position"), ("margin", "--margin"), ("animate", "--animate"), ("highlight_color", "--highlight-color"), ("outline", "--outline")):+ for k, flag in (("font", "--font"), ("size", "--size"), ("color", "--color"), ("position", "--position"), ("margin", "--margin"), ("animate", "--animate"), ("highlight_color", "--highlight-color"), ("outline", "--outline"), ("lang", "--lang"), ("offset", "--offset"), ("max_lines", "--max-lines"), ("min_duration", "--min-duration")):if cap.get(k) is not None:argv += [flag, str(cap[k])]for k, flag in (("karaoke", "--karaoke"), ("bold", "--bold"), ("box", "--box")):@@ -437,7 +438,7 @@ def main() -> int:if not g.get("template"):die(f"graphics[{i}] needs a template")argv = [current, "-o", nxt, "--template", g["template"]]- for k, flag in (("name", "--name"), ("title", "--title"), ("subtitle", "--subtitle"), ("start", "--start"), ("end", "--end"), ("position", "--position"), ("from", "--from"), ("scale", "--scale"), ("primary", "--primary"), ("text_color", "--text-color")):+ for k, flag in (("name", "--name"), ("title", "--title"), ("subtitle", "--subtitle"), ("start", "--start"), ("end", "--end"), ("position", "--position"), ("from", "--from"), ("scale", "--scale"), ("primary", "--primary"), ("text_color", "--text-color"), ("lang", "--lang")):if g.get(k) is not None:argv += [flag, str(g[k])]sh("graphics.py", *(argv + brand_args))diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.jsonindex d6e922f..cd5d436 100644--- a/tests/fixtures/mcp_tools.json+++ b/tests/fixtures/mcp_tools.json@@ -155,8 +155,11 @@"karaoke_timing","language","margin",+ "max_lines",+ "min_duration","mode","model",+ "offset","outline","outline_color","output",@@ -478,6 +481,7 @@"input","json","json_brief",+ "lang","name","output","overwrite",diff --git a/tests/test_all.py b/tests/test_all.pyindex 13222c1..01d9617 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -3,6 +3,8 @@python3 tests/test_all.py # or: python3 -m unittest tests/test_all.py"""+import contextlib+import ioimport jsonimport platformimport re@@ -17,7 +19,7 @@ ROOT = Path(__file__).resolve().parent.parentSCRIPTS = ROOT / "scripts"OUT = Path(os.environ.get("OUT", ROOT / "tests" / "out"))sys.path.insert(0, str(SCRIPTS))-from _common import default_font_file, escape_drawtext, escape_filter_path, probe, shell_quote # noqa: E402+from _common import default_font_file, detect_script, font_for_script, font_family_for_script, escape_drawtext, escape_filter_path, probe, shell_quote # noqa: E402TONES = ("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)")@@ -1071,6 +1073,479 @@ class FFmpegSkillTests(unittest.TestCase):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)@@ -3588,5 +4063,87 @@ class FFmpegSkillTests(unittest.TestCase):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"))+++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(",")]++if __name__ == "__main__":unittest.main(verbosity=2)diff --git a/tests/test_contract.py b/tests/test_contract.pyindex c9cdf07..dd4d826 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -2649,6 +2649,47 @@ class DoctorDetectionTests(unittest.TestCase):self.assertEqual(d2["fonts"]["status"], "unknown")self.assertIn("fc-match", d2["fonts"]["detail"])+ def test_doctor_reports_a_font_status_for_every_script_it_can_detect(self):+ """1.12: `fonts.scripts` answers "which languages can this machine actually render", the+ question `filter:subtitles` never asked. Same three states as every other capability."""+ from _common import SCRIPTS as DETECTED_SCRIPTS+ proc = sh(sys.executable, SCRIPTS / "_contract.py", "doctor", "--json", check=False)+ d = json.loads(proc.stdout)+ expected = {s for s in DETECTED_SCRIPTS if s != "latin"}+ self.assertEqual(set(d["fonts"]["scripts"]), expected)+ self.assertEqual(len(expected), 9, "ja zh ko ar he hi th ru el")+ for name, entry in d["fonts"]["scripts"].items():+ with self.subTest(script=name):+ self.assertIn(entry["status"], ("available", "missing", "unknown"))+ self.assertEqual(set(entry), {"status", "file"})+ if entry["status"] == "available":+ self.assertTrue(os.path.exists(entry["file"]), entry)+ else:+ self.assertIsNone(entry["file"])+ self.assertTrue(d["ok"], "a script with no font is a machine fact, never a broken install")++ def test_doctor_plain_text_keeps_fonts_to_one_short_line(self):+ """The plain-text doctor was cut to ~520 bytes in 1.11.0; nine scripts must not undo that,+ so they are summarised on the single `fonts:` line and detailed only in --json."""+ out = sh(sys.executable, SCRIPTS / "_contract.py", "doctor", check=False).stdout+ font_lines = [l for l in out.splitlines() if l.startswith("fonts:")]+ self.assertEqual(len(font_lines), 1, out)+ self.assertLess(len(out.encode("utf-8")), 900, "the short doctor text must stay short")+ d = json.loads(sh(sys.executable, SCRIPTS / "_contract.py", "doctor", "--json", check=False).stdout)+ for name, entry in d["fonts"]["scripts"].items():+ if entry["status"] == "available":+ self.assertIn(name, font_lines[0])+ if entry["status"] == "missing":+ self.assertIn(name, font_lines[0])+ self.assertNotIn(str(entry["file"]), font_lines[0], "file paths belong in --json, not the summary")++ def test_font_fix_hint_names_the_language_and_how_to_install_one(self):+ hint = _contract._capability_fix_hint("font:ko")+ self.assertIn("Korean", hint)+ self.assertIn("fonts-noto-cjk", hint)+ self.assertIn("--font-file", hint)+ self.assertIn("Thai", _contract._capability_fix_hint("font:th"))+def test_font_capability_is_informational_like_gpu_encoders(self):"""fonts, like gpu_encoders, is reported but never gates ok/usable -- it answers a questionnone of the required/optional capabilities ask."""