flowocr 0.1.0__py3-none-any.whl

flowocr/output/export.py

@@ -0,0 +1,205 @@
+"""从富信息 JSON **投影**出 SRT，外加叠加 ASS 共用的工具（时间、转义、量字宽、定字号）。
+
+契约（`output-format-plan（已归档）`）：**导出器不做任何判断。**
+切分（cue）、常驻 UI 的判定、并带的结果都已经写在 `-tracks.json` 里了，
+这里只是按 flag 取舍、按 cue 排版。所以回抠、并带、剔 UI 的产物自动一致——
+audit-4 C6（`--srt-only` 绕过了输出过滤）在结构上不可能再发生。
+
+    python -m flowocr.output.export out/gs-gi-s2/gi-s2-tracks.json            # 每条轨一份 SRT
+
+叠加字幕（把字压回原位）分两步：阶段 3 的字幕稿在 `flowocr.output.script`，阶段 4 的特效在 `flowocr.typeset`，
+入口是 `render` 的预设（`script`，以及两步连跑的 `default` / `default_all` / `dev`；script-fx 计划）。
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from flowocr.artifacts import srtio            # noqa: E402
+from flowocr.artifacts import tracksio         # noqa: E402
+
+FONT_CN = "Microsoft YaHei"
+"""叠加 ASS 用的字体。**挑的是这台 Windows 上真有的**——写一个不存在的字体名，
+libass 会静默换一个替身，下面那个量出来的换算比例当场作废。"""
+
+FONT_H_RATIO = {FONT_CN: 1.35}
+"""框高 → `Fontsize` 的换算，**量出来的**（`output-format-plan（已归档）`）。
+
+`Fontsize` 不是像素高：字形高只有它的 0.58–0.81 倍，而且**随字体和是不是全角而变**
+（同一个 Fontsize 在 Meiryo 和 Yu Mincho 下差 20%）。一次性探针 `probe_ass_fontsize.py` 用 libass
+渲一条已知字号的 ASS、量白色字形的外接框高，`ratio = Fontsize / 字形高`，取 CJK 正文那一列；
+拉丁为主的素材偏小约 6%。换字体请重跑那个探针，别照抄。
+"""
+
+
+def h_ratio(font: str) -> float:
+    """`FONT_H_RATIO` 里查不到的字体（用户在字幕稿里换了字体）按 `FONT_CN` 的比例算；阶段 4 会打一行提示。"""
+    return FONT_H_RATIO.get(font, FONT_H_RATIO[FONT_CN])
+
+
+INK_REF_SIZE = 48
+"""量字宽用的参考字号。**墨迹宽和字号成正比**（2026-09-12 在 24/48/72 三档上量过，
+三种字体、六种文本，比例逐档相同到千分之五以内），所以渲一次就能反推任意字号的宽。"""
+INK_PAGE_H, INK_PAGE_W = 12_000, 4096
+"""一页多高。**行高按这一页里最大的字号定**：固定行高时，调用方传进来的大字号（核对探针用的是
+适配后的字号，最大过 100）会把字形伸进下一行，下一行量到的宽就成了上一行的（第一版的 31 倍"溢出"就是这个）。"""
+
+
+def ass_doc(W: int, H: int, styles: list[str], events: list[str], comment: str = "",
+            info: dict | None = None) -> str:
+    """一份 ASS。`info` 是另加进 `[Script Info]` 的键：要留得住就写成键，Aegisub 会丢掉 `;` 开头的注释行。"""
+    return "\n".join(
+        ["[Script Info]", *([f"; {comment}"] if comment else []),
+         "ScriptType: v4.00+", "WrapStyle: 2", "ScaledBorderAndShadow: yes",
+         f"PlayResX: {W}", f"PlayResY: {H}", *(f"{k}: {v}" for k, v in (info or {}).items()), "",
+         "[V4+ Styles]",
+         "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, "
+         "OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, "
+         "ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, "
+         "MarginL, MarginR, MarginV, Encoding", *styles, "",
+         "[Events]",
+         "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
+         *events]) + "\n"
+
+
+def render_ink(items: list[tuple[str, float, str]]) -> list[tuple[int, int]]:
+    """把 `(字体, 字号, 单行文本)` 逐条用 **libass 真渲**（ffmpeg 的 subtitles 滤镜），
+    返回每条白色墨迹的外接框 `(宽, 高)`；渲不出墨迹的记 `(0, 0)`。
+
+    为什么不拿字体文件的度量估（第一版就是这么做的，一次性探针 `probe_ass_fit.py` 量过）：
+    libass 的 `Fontsize` 不是 em、各字体缩放口径不同（Yu Mincho 估宽系统性偏大 17%），
+    而且**字体里没有的字会被 libass 回退到别的字体**（Consolas 渲日文 −15%～+40%）——
+    估不准的地方正好是最该量的地方。一页一次 ffmpeg，几百行一秒。"""
+    import subprocess
+    import tempfile
+    from PIL import Image
+    out: list[tuple[int, int]] = []
+    row_h = int(max((s for _, s, _ in items), default=INK_REF_SIZE) * 2)
+    per_page = max(1, INK_PAGE_H // row_h)
+    with tempfile.TemporaryDirectory(prefix="flowocr-ink-") as d:
+        for p0 in range(0, len(items), per_page):
+            page = items[p0:p0 + per_page]
+            H = row_h * len(page)
+            fonts = sorted({f for f, _, _ in page})
+            styles = [f"Style: s{i},{f},{INK_REF_SIZE},&H00FFFFFF,&H000000FF,&H00000000,"
+                      "&H00000000,0,0,0,0,100,100,0,0,1,0,0,7,0,0,0,1" for i, f in enumerate(fonts)]
+            events = [f"Dialogue: 0,0:00:00.00,0:00:01.00,s{fonts.index(f)},,0,0,0,,"
+                      + "{" + f"\\pos(8,{k * row_h + 4})\\fs{s:g}" + "}" + ass_text(t)
+                      for k, (f, s, t) in enumerate(page)]
+            (Path(d) / "ink.ass").write_text(ass_doc(INK_PAGE_W, H, styles, events), encoding="utf-8")
+            # 相对文件名 + cwd：filter 语法里 Windows 盘符那个冒号不好转义（同 probe_ass_fontsize）
+            r = subprocess.run(["ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i",
+                                f"color=c=black:s={INK_PAGE_W}x{H}:d=1", "-vf", "subtitles=ink.ass",
+                                "-frames:v", "1", "ink.png"], capture_output=True, text=True, cwd=d)
+            if r.returncode != 0:
+                raise SystemExit(f"字宽渲染失败（ffmpeg）：{r.stderr.strip()[:300]}")
+            img = Image.open(Path(d) / "ink.png").convert("L").point(lambda v: 255 if v > 128 else 0)
+            for k in range(len(page)):
+                bb = img.crop((0, k * row_h, INK_PAGE_W, (k + 1) * row_h)).getbbox()
+                out.append((bb[2] - bb[0], bb[3] - bb[1]) if bb else (0, 0))
+    return out
+
+
+def ink_widths(pairs, known: dict | None = None) -> dict[tuple[str, str], float]:
+    """`{(字体, 单行文本): 字号 1 时的墨迹宽}`。同一行文本只渲一次；`known` 里已经量过的不再渲
+    （叠加预设连跑阶段 3、4 时，阶段 4 用阶段 3 量好的）。返回的包含 `known` 里的。"""
+    known = known or {}
+    uniq = sorted({(f, ln) for f, t in pairs for ln in t.split("\n") if ln.strip()} - set(known))
+    got = render_ink([(f, INK_REF_SIZE, ln) for f, ln in uniq]) if uniq else []
+    return {**known, **{k: w / INK_REF_SIZE for k, (w, _) in zip(uniq, got)}}
+
+
+FIT_MIN_SIZE = 8
+
+
+def fit_size(text: str, font: str, box_w: float, box_h: float,
+             widths: dict[tuple[str, str], float]) -> int:
+    """给一条事件定字号：**框高和框宽各给一个上限，取小的**。
+
+    只按框高定（上一版）时，字体比屏幕上的字宽、或者 OCR 多读 / 读错了字，渲出来就冲出框外，
+    用途 1 的 overlay 会盖到邻居（2026-09-12 owner 看预览时指出）。
+    宽度上限拿 `ink_widths` 真渲出来的宽反推：`Fontsize = 框宽 / 字号 1 时的墨迹宽`。"""
+    lines = [ln for ln in text.split("\n") if ln.strip()] or [text]
+    by_h = box_h / len(lines) * h_ratio(font)
+    w1 = max(widths.get((font, ln), 0.0) for ln in lines)
+    by_w = box_w / w1 if w1 > 0 else by_h
+    return max(FIT_MIN_SIZE, int(min(by_h, by_w)))
+
+
+def ass_time(us: int, up: bool) -> str:
+    """µs → `H:MM:SS.cc`。ASS 只到厘秒：**起点向上取整、终点向下取整**，
+    免得两条相邻事件重叠出一个假的"同屏"（`output-format-plan（已归档）`）。"""
+    cs = -(-us // 10_000) if up else us // 10_000
+    cs = max(cs, 0)
+    h, cs = divmod(cs, 360_000)
+    m, cs = divmod(cs, 6_000)
+    s, cs = divmod(cs, 100)
+    return f"{h:d}:{m:02d}:{s:02d}.{cs:02d}"
+
+
+def ass_text(s: str) -> str:
+    """正文进 ASS：换行变 `\\N`，花括号会被当成覆盖标签，换成半角括号。"""
+    return s.replace("\\", "/").replace("{", "(").replace("}", ")").replace("\n", "\\N")
+
+
+def cue_start(doc: dict, cue: dict, evs: list[dict], start: str) -> int:
+    """这条 cue 用哪个起点。**这是投影，不是产物里的状态**（第二轮复审）：
+
+    `full`（"整条打完"）= 各成员 `t_full` 的**最大值**，夹在 cue 里。
+    逐行各算各的是错的：一条字幕里说话人名短、打完得早，台词长、打完得晚，
+    取最早那行会把起点拉回"首字出现"——整片实测起点误差 0.100 s 退回 0.400 s。
+
+    ⚠ **算完不许写回 `cue["t_start"]`**：写回去之后那个值就不再等于任何事件的
+    首字时间，下一次想切回 `first` 就配不上、**回不去了**。
+    两个起点口径必须都能从同一份 JSON 投影出来。
+    """
+    lo, hi = cue["t_start"], cue["t_end"]
+    if start != "full":
+        return lo
+    fulls = [e["t_full"] for e in evs if e.get("t_full") is not None]
+    return max(lo, min(max(fulls), hi - 1)) if fulls else lo
+
+
+def export_srt(doc: dict, outdir: Path, only: str = "",
+               suffix: str = "", start: str = "first") -> list[tuple[str, int]]:
+    """每条轨一份 SRT。**和 `build_tracks` 写出来的应当逐字节相同**——
+    两边都是"同一份 cue 表 + 同一份 ui_lines"的投影。
+
+    `start="full"` 只改这次导出的起点口径，**不改 JSON**（见 `cue_start`）。
+    """
+    out = []
+    for tr in doc["tracks"]:
+        if only and tr["id"] != only:
+            continue
+        blocks = []
+        for cue in tr["cues"]:
+            evs = tracksio.cue_lines(doc, tr, cue)
+            if evs:
+                blocks.append((cue_start(doc, cue, evs, start), cue["t_end"],
+                               [e["text"] for e in evs]))
+        name = tr["srt"][:-4] + suffix + ".srt" if suffix else tr["srt"]
+        n = srtio.write_srt_blocks(outdir / name, blocks)
+        out.append((name, n))
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="从 -tracks.json 导出每条轨的 SRT（叠加 ASS 走 flowocr.output.render）")
+    ap.add_argument("tracks")
+    ap.add_argument("--outdir", default="", help="默认写在 tracks.json 旁边")
+    ap.add_argument("--track", default="", help="只导某一条轨")
+    ap.add_argument("--start", choices=("first", "full"), default="first",
+                    help="cue 起点口径：first = 首字出现（默认，和建轨写的 SRT 相同）；full = 全字出现（贴合以稳定态计时的工具），"
+                         "文件名加 -full、不覆盖默认那份。起点口径只在导出时投影，不改 tracks.json")
+    a = ap.parse_args(argv)
+    src = Path(a.tracks)
+    doc = tracksio.load(src)
+    outdir = Path(a.outdir) if a.outdir else src.parent
+    outdir.mkdir(parents=True, exist_ok=True)
+    for name, n in export_srt(doc, outdir, a.track, suffix="-full" if a.start == "full" else "", start=a.start):
+        print(f"{name}  {n} 条 cue")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flowocr/output/layout.py

@@ -0,0 +1,210 @@
+"""叠加字幕的排版：字号、锚点、底板、画面边界、按轨迹逐段运动。阶段 3（字幕稿要写预览位置）和阶段 4（生成最终行）共用这一份。
+
+方案：overlay-style 计划（对齐、锚点、底板）、script-fx 计划（拆成字幕稿 + 特效渲染之后这些从 `overlay` 挪到这里）。
+这里只做几何，不做判断：对齐方式是阶段 2 判好的，效果时刻是阶段 3 判好的。
+"""
+from __future__ import annotations
+
+from flowocr.output import export
+
+OVERLAY_PAD = 6
+"""底板比 OCR 框外扩的像素：盖住原字笔画的边缘。也是字离画面边的最小距离。"""
+
+PLATE_MODES = ("box", "rows", "text")
+"""底板怎么画（owner 2026-09-12 要三种比观感）：
+* `box`：原字幕正文框的并集，一整块；
+* `rows`：逐行一块，每行宽 = max(原文这一行的区间, 译文这一行的区间)——多行字幕不填满矩形；
+* `text`：只有译文文字底下有底板。"""
+
+OVERLAY_MIN_SCALE = 0.75
+"""叠加字号不低于"按框高换算的字号"的这么多（owner 2026-09-12：第五个选项字被压得过小）。只给译文。"""
+
+ANCHOR = {"left": 4, "center": 5, "right": 6}
+"""对齐方式 → `\\an`（竖直居中，横向锚左沿 / 中心 / 右沿）。"""
+ALIGN_OF = {v: k for k, v in ANCHOR.items()}
+
+
+def text_span(axis: float, w: float, align: str) -> tuple[float, float]:
+    """锚在 `axis` 上、宽 `w` 的一行字占的横向区间。"""
+    if align == "left":
+        return axis, axis + w
+    if align == "right":
+        return axis - w, axis
+    return axis - w / 2, axis + w / 2
+
+
+def anchor_axis(rows: list[list[float]], align: str, common: bool) -> list[float]:
+    """每行的锚轴。`common`（matched 的多行）取整组的公共轴：居中用**最宽那行**的中心，左 / 右用最外的沿——
+    `rows_of` 的行框只是这一行**被收下的**事件的并集，一行被 det 切成两框、其中一个被剔时只剩半行，
+    拿它自己的中心当轴，这一行会歪半个行宽；缺了半截的那行不会是最宽的（两行时中位数就是平均，挡不住）。
+    不 `common`（tracks 一个事件一行）取这一行自己的框。"""
+    def own(r):
+        return r[0] if align == "left" else r[2] if align == "right" else (r[0] + r[2]) / 2
+    if not common:
+        return [own(r) for r in rows]
+    if align == "left":
+        a = min(r[0] for r in rows)
+    elif align == "right":
+        a = max(r[2] for r in rows)
+    else:
+        a = own(max(rows, key=lambda r: r[2] - r[0]))
+    return [a] * len(rows)
+
+
+def plate_rects(rows: list[list[float]], text_w: list[float], axis, mode: str,
+                align: str = "center") -> list[list[float]]:
+    """每行一个底板矩形 [x0, y0, x1, y1]（`box` 模式一整块）。`axis` 是锚轴（一个数 = 各行共用，或逐行一个）；
+    译文区间按锚点算（`text_span`）。上下相邻的两行外扩后会叠一条，半透明时叠的地方更黑，所以从中间劈开。"""
+    p = OVERLAY_PAD
+    if mode == "box":
+        return [[min(r[0] for r in rows) - p, rows[0][1] - p, max(r[2] for r in rows) + p, rows[-1][3] + p]]
+    axes = axis if isinstance(axis, list) else [axis] * len(rows)
+    out = []
+    for r, w, a in zip(rows, text_w, axes):
+        tx0, tx1 = text_span(a, w, align)
+        x0, x1 = (tx0, tx1) if mode == "text" else (min(r[0], tx0), max(r[2], tx1))
+        out.append([x0 - p, r[1] - p, x1 + p, r[3] + p])
+    for a, b in zip(out, out[1:]):
+        if b[1] < a[3]:
+            a[3] = b[1] = (a[3] + b[1]) / 2
+    return out
+
+
+def chunks(p: str, n: int = 24) -> list[str]:
+    """长段量字宽时切小块再加：`render_ink` 一页 4096 px 宽，整段渲会被截断。"""
+    return [p[i:i + n] for i in range(0, len(p), n)] or [p]
+
+
+def width_keys(lines: list[str], block: bool) -> list[str]:
+    """一条要量哪些字宽：普通条目量每一行（行里的换行拆开量），面板量每段切成的小块。"""
+    if block:
+        return [c for p in lines for c in chunks(p)]
+    return [x for ln in lines for x in ln.split("\n")]
+
+
+def line_width(font: str, text: str, widths: dict) -> float:
+    """字号 1 时一行（可能带换行、按最宽的那段算）的墨迹宽。"""
+    return max((widths.get((font, x), 0.0) for x in text.split("\n")), default=0.0)
+
+
+def fit_line(rows: list[list[float]], lines: list[str], font: str, widths: dict, translated: bool, W: int) -> int:
+    """普通条目的字号 = `export.fit_size`：框高按行数分、框宽按 libass 真渲的墨迹宽反推，取小的。
+    译文另有下限：框很窄（选项按钮 `「未着」` 日文括号窄、中文括号宽）时不许缩到框高换算字号的
+    `OVERLAY_MIN_SCALE` 以下，宁可让字超出框、底板跟着放宽；但不许超出画面。原文压回自己的框，只按框定
+    （框偏高时保底会把字撑出框，gi-s2 摆帧）。"""
+    box = [min(r[0] for r in rows), rows[0][1], max(r[2] for r in rows), rows[-1][3]]
+    size = export.fit_size("\n".join(lines), font, box[2] - box[0], box[3] - box[1], widths)
+    if not translated:
+        return size
+    # 保底按**看得见的行数**分框高：一个框里画几行（人在字幕稿里加了换行）时，保底不能按一行算，不然几行叠起来冲出框
+    n = sum(len([x for x in ln.split("\n") if x.strip()]) or 1 for ln in lines)
+    by_h = (box[3] - box[1]) / max(1, n) * export.h_ratio(font)
+    w1 = max((line_width(font, ln, widths) for ln in lines), default=0.0)
+    size = max(size, int(OVERLAY_MIN_SCALE * by_h))
+    return min(size, int((W - 4 * OVERLAY_PAD) / w1)) if w1 > 0 else size
+
+
+def expand_rows(rows: list[list[float]], k: int, H: int) -> list[list[float]]:
+    """正文比原文框装得下的多出 `k` 行：按原来一行的高度（几个框时取行距）往下扩出 `k` 行，往下会出画面就往上扩。
+    扩出的行横向取原文几行合起来的范围；压到别的字不管（owner 2026-09-27：一个框里分成两行时扩出一行，不为重叠做保证）。"""
+    rows = [list(r) for r in rows]
+    if k <= 0:
+        return rows
+    h = rows[-1][3] - rows[-1][1]
+    pitch = (rows[-1][1] - rows[0][1]) / (len(rows) - 1) if len(rows) > 1 else h
+    x0, x1 = min(r[0] for r in rows), max(r[2] for r in rows)
+    below = [[x0, rows[-1][1] + j * pitch, x1, rows[-1][1] + j * pitch + h] for j in range(1, k + 1)]
+    if below[-1][3] <= H - OVERLAY_PAD:
+        return rows + below
+    return [[x0, rows[0][1] - j * pitch, x1, rows[0][1] - j * pitch + h] for j in range(k, 0, -1)] + rows
+
+
+def expand_box(rect: list[float], cap: int, k: int, H: int) -> list[float]:
+    """一个框本来装着 `cap` 行（OCR 原文带换行），正文多出 `k` 行：框按一行的高度（框高 / `cap`）长出 `k` 行，方向同 `expand_rows`。"""
+    h = (rect[3] - rect[1]) / cap
+    grown = expand_rows([[rect[0], rect[1] + i * h, rect[2], rect[1] + (i + 1) * h] for i in range(cap)], k, H)
+    return [rect[0], grown[0][1], rect[2], grown[-1][3]]
+
+
+def same_size(boxes: list[tuple[int, int, list[float]]], sizes: list[int]) -> list[int]:
+    """同一栏、同时在屏的选项按钮字号取中位数：各按钮的框高、读法（整句 / 残读并进来的）不一，
+    各算各的就一个大一个小（hsr 0:23 摆帧：第二个选项比兄弟大一号）。`boxes[i]` = (起, 止, 第一行框)。"""
+    out = []
+    for s0, e0, bi in boxes:
+        peers = [sz for (s1, e1, bj), sz in zip(boxes, sizes)
+                 if s1 < e0 and s0 < e1
+                 and min(bi[2], bj[2]) - max(bi[0], bj[0]) > 0.5 * min(bi[2] - bi[0], bj[2] - bj[0])]
+        out.append(sorted(peers)[len(peers) // 2])
+    return out
+
+
+def axes_in_screen(rows: list[list[float]], text_w: list[float], align: str, common: bool, W: int) -> list[float]:
+    """锚轴，最宽那行放不进画面就把整组的轴往里推（左 / 右锚时译文比原文长会从一侧伸出去）。"""
+    axes = anchor_axis(rows, align, common)
+    spans = [text_span(a, w, align) for a, w in zip(axes, text_w)]
+    lo, hi = min(s for s, _ in spans), max(z for _, z in spans)
+    pad = OVERLAY_PAD
+    shift = pad - lo if lo < pad else (W - pad) - hi if hi > W - pad else 0
+    return [a + shift for a in axes]
+
+
+def block_layout(box: list[float], paras: list[str], row_h: int, font: str, widths: dict,
+                 size: int | None = None) -> tuple[int, list[str]]:
+    """长文本块：译文按段折行填进块里。字号从原文行高换算起，放不下就往小缩（`size` 给了就用它，只折行）；
+    折行按每段的平均字宽手算（libass 的自动折行只在空格处断，中文整段不会折）。返回（字号, 折好的行，段间空一行）。"""
+    bw, bh = box[2] - box[0], box[3] - box[1]
+    unit = [sum(widths.get((font, c), 0.0) for c in chunks(p)) / max(1, len(p)) for p in paras]
+
+    def layout(size: int) -> list[str]:
+        out = []
+        for p, u in zip(paras, unit):
+            k = max(1, int(bw / max(u * size, 1e-6)))
+            out += [p[i:i + k] for i in range(0, len(p), k)] + [""]
+        return out[:-1]
+    if size is not None:
+        return size, layout(size)
+    size = max(export.FIT_MIN_SIZE, int(row_h * export.h_ratio(font)))
+    while size > export.FIT_MIN_SIZE and len(layout(size)) * size > bh:
+        size -= 1
+    return size, layout(size)
+
+
+def motion_segments(boxes: list | None, s: int, e: int) -> list[tuple[int, int, tuple, tuple]]:
+    """在动的事件在 `[s, e]` 里**按轨迹逐段拆**，每段 = (起, 止, 起点框左上角, 止点框左上角)。
+
+    一条从首点到末点的 `\\move` 会把中间过程抹平（先静止后上移的字被画成从头匀速滑、步进滚动被画成平滑滚动），
+    所以同一位置的相邻两点是一段停顿，位置变了才是一段位移。轨迹段被 `[s, e]` 裁掉一半时端点**跟着插值**——
+    照搬原端点会把整段位移重播一遍。轨迹之外的尾巴停在最后一个位置。不动的（没有轨迹）返回一段、端点为 None。"""
+    if not boxes or len(boxes) < 2:
+        return [(s, e, None, None)]
+
+    def at(b0, b1, t0, t1, t):
+        f = 0.0 if t1 <= t0 else (t - t0) / (t1 - t0)
+        return (b0[0] + (b1[0] - b0[0]) * f, b0[1] + (b1[1] - b0[1]) * f)
+
+    out = []
+    for (t0, b0), (t1, b1) in zip(boxes, boxes[1:]):
+        a, z = max(s, t0), min(e, t1)
+        if z <= a:
+            continue
+        if b0[:2] == b1[:2]:
+            out.append((a, z, (b0[0], b0[1]), (b0[0], b0[1])))
+        else:
+            out.append((a, z, at(b0, b1, t0, t1, a), at(b0, b1, t0, t1, z)))
+    last_t, last_b = boxes[-1]
+    if e > max(s, last_t):
+        out.append((max(s, last_t), e, (last_b[0], last_b[1]), (last_b[0], last_b[1])))
+    return out or [(s, e, None, None)]
+
+
+def pos_tag(x: float, y: float, seg: tuple, base: tuple[float, float]) -> str:
+    """一个元素在一段里的位置标签：静止用 `\\pos`，位移用 `\\move`。`(x, y)` 是按 `base`（条目框的左上角）
+    排出来的静止位置，在动的段把它平移到轨迹上。"""
+    a, z, p0, p1 = seg
+    if p0 is None:
+        return "\\pos(%.0f,%.0f)" % (x, y)
+    x0, y0 = x + p0[0] - base[0], y + p0[1] - base[1]
+    if p0 == p1:
+        return "\\pos(%.0f,%.0f)" % (x0, y0)
+    x1, y1 = x + p1[0] - base[0], y + p1[1] - base[1]
+    return "\\move(%.0f,%.0f,%.0f,%.0f,0,%d)" % (x0, y0, x1, y1, max(z - a, 0) // 1000)

flowocr/output/presets/__init__.py

@@ -0,0 +1,6 @@
+"""内置输出预设。一个模块一个预设，入口是 `render(document, output_dir, options) -> list[Path]`（`flowocr.extensions`）。
+
+现在有：`srt_main`（主轨一份 SRT）、`matched_srt`（匹配产物拍平成 SRT）、`script`（只写字幕稿，阶段 3）、
+叠加三个 `default` / `default_all` / `dev`（字幕稿 + 阶段 4 的最终 ASS，`_overlay`）。
+用户自己写的预设不必放进来——`extensions.load("<路径或模块名>", "preset")` 同样能加载；可复制改的例子在仓库的 `examples/`。
+"""

flowocr/output/presets/_overlay.py

@@ -0,0 +1,40 @@
+"""三个叠加预设（`default` / `default_all` / `dev`）的共同实现：阶段 3 写字幕稿、阶段 4 接着生成最终 ASS，两份都留下。
+
+| 预设 | 阶段 3（留哪些） | 阶段 4（长什么样） |
+| --- | --- | --- |
+| `default` | `keep=main`：tracks 主轨 + 名牌轨 / matched 的 body、extra、name | `default`：底板 α 0x20 |
+| `default_all` | `keep=all`：全部区域轨 / 全部层 + 没叠译文的原文 | `default` |
+| `dev` | `keep=all`，另写 `why` | `dev`：底板 α 0x80、UI 黄字、非主轨浅蓝、区域号 |
+
+options 按键分给两个阶段：`keep` `why` `lang` `layers` `tracks` 给阶段 3（`flowocr.output.script.render_script`），
+`plate` `plate_alpha` `unknown` 给阶段 4（`flowocr.typeset.core`），`typewriter` `fade` 两边都给
+（阶段 3 的 off 是不判、不写，阶段 4 的 off 是不画；`typewriter=off` 时阶段 3 照原来的规矩改判淡入）。
+`name` 是最终 ASS 的文件名，字幕稿在它旁边、`.ass` 换成 `.script.ass`。
+阶段 3 量好的字宽直接交给阶段 4，不再起一遍 ffmpeg。返回 `[最终 ASS, 字幕稿]`（`dev_tools/preview.py`、`scriptmatch --ass` 靠这个顺序和后缀）。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from flowocr.output import script
+from flowocr.typeset import core
+
+PRESETS = {"default": ("main", "off", "default"), "default_all": ("all", "off", "default"), "dev": ("all", "on", "dev")}
+STAGE3 = ("keep", "why", "lang", "layers", "tracks", "typewriter", "fade")
+STAGE4 = ("plate", "plate_alpha", "unknown", "typewriter", "fade")
+
+
+def render(document: dict, output_dir, options: dict | None, preset: str) -> list[Path]:
+    o = dict(options or {})
+    keep, why, look = PRESETS[preset]
+    o3 = {"keep": keep, "why": why, **{k: v for k, v in o.items() if k in STAGE3}}
+    o4 = {k: v for k, v in o.items() if k in STAGE4}
+    core.look_of(look, o4)                          # 选项写错了在写字幕稿之前就报
+    final = None
+    if o.get("name"):
+        name = str(o["name"])
+        o3["name"] = (name[:-4] if name.endswith(".ass") else name) + ".script.ass"
+        final = Path(output_dir) / name             # 最终文件就叫给的名字（不以 .ass 结尾也不改）
+    draft, _n, _items, widths = script.render_script(document, output_dir, o3, suffix=preset)
+    final, _ts = core.typeset_file(draft, final, look, o4, widths=widths)
+    return [final, draft]

flowocr/output/presets/default.py

@@ -0,0 +1,21 @@
+"""内置预设 `default`（**生产默认**，owner 2026-09-24；`render` 不给 `--preset` 时就是它）：只留主轨的叠加字幕。
+
+* tracks 产物：主轨（和 `srt_main` 同一个行集，常驻 UI 按主轨自己的判定剔掉）+ 名牌轨；
+* matched 产物：`body` / `extra` / `name` 三层——认领上剧本的台词，不论在不在主轨（`--feed nonoise` 多出来的正是主轨外的台词）；
+* 样式：底板 `rows`、近黑、α 0x20；对齐按 `regions[].align`，效果检出即开。
+
+写两份：字幕稿 `<tag>[-<lang>]-default.script.ass`（阶段 3，能在 Aegisub 里编辑）和最终的 `<tag>[-<lang>]-default.ass`（阶段 4）。
+选项和实现见 `flowocr.output.presets._overlay`；方案见 script-fx 计划。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from flowocr.artifacts import matchedio, tracksio
+from flowocr.output.presets import _overlay
+
+ACCEPTS = (tracksio.SCHEMA, matchedio.SCHEMA)
+
+
+def render(document: dict, output_dir, options: dict | None = None) -> list[Path]:
+    return _overlay.render(document, output_dir, options, "default")

flowocr/output/presets/default_all.py

@@ -0,0 +1,20 @@
+"""内置预设 `default_all`（owner 2026-09-24）：同 `dev` 的保留范围，但成品的样子。
+
+* tracks 产物：全部区域轨的事件，常驻 UI 也照常画（删不删由用户自己判断）；matched 产物：全部六层，没叠译文的事件（没认领上剧本、或没这个语种的译文）照 tracks 画 OCR 原文；
+* 不标聚类编号、不改非主轨的字色；
+* 底板 `rows`，近黑、α 0x20（更不透明，盖住原文）；对齐按 `regions[].align`，效果检出即开。
+
+写两份：字幕稿 `…-default_all.script.ass` 和最终的 `…-default_all.ass`。选项和实现见 `flowocr.output.presets._overlay`；方案见 script-fx 计划。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from flowocr.artifacts import matchedio, tracksio
+from flowocr.output.presets import _overlay
+
+ACCEPTS = (tracksio.SCHEMA, matchedio.SCHEMA)
+
+
+def render(document: dict, output_dir, options: dict | None = None) -> list[Path]:
+    return _overlay.render(document, output_dir, options, "default_all")

flowocr/output/presets/dev.py

@@ -0,0 +1,21 @@
+"""内置预设 `dev`（开发默认，owner 2026-09-24）：**全部保留**的叠加字幕，看得出每条字属于哪个聚类。
+
+* tracks 产物：全部区域轨的事件（含常驻 UI，黄字 #ffe033）；matched 产物：全部六层，没叠译文的事件（没认领上剧本、或没这个语种的译文）照 tracks 画 OCR 原文；
+* 非主轨聚类的字用浅蓝（#73d7ff），每条字幕底板外接矩形内侧的右上角一个红字（#ff2d2d）区域号（不影响字幕本身的位置和对齐）；
+* 底板 `rows`，近黑、α 0x80（50%，看得见底下的原文）；对齐按阶段 2 判的 `regions[].align`，效果检出即开；
+* 字幕稿里每行的 `fo` 另带 `why`（效果判定的依据）。
+
+写两份：字幕稿 `…-dev.script.ass` 和最终的 `…-dev.ass`。选项和实现见 `flowocr.output.presets._overlay`；方案见 script-fx 计划。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from flowocr.artifacts import matchedio, tracksio
+from flowocr.output.presets import _overlay
+
+ACCEPTS = (tracksio.SCHEMA, matchedio.SCHEMA)
+
+
+def render(document: dict, output_dir, options: dict | None = None) -> list[Path]:
+    return _overlay.render(document, output_dir, options, "dev")

flowocr/output/presets/matched_srt.py

@@ -0,0 +1,32 @@
+"""内置预设：把**匹配产物**（`*-matched.json`）拍平成一份 SRT——匹配上的出剧本原文，没匹配上原样留 OCR。
+
+和 `scriptmatch --srt` 写的**逐字节相同**（同一份 `cues`、同一个 `matchedio.body`、同一个 `srtio` 写出；守卫钉着）。
+⚠ SRT 是**拍平投影，只出主 ref**：覆盖（ref ∪ extra）比这里出现的多，量覆盖看匹配产物本身（matcher 计划）。
+
+options：
+* `lang`：`jp`（默认）/ `cn`，正文取哪种语言；
+* `name`：文件名（默认 `<matched 的 stem 去掉 -matched>-<lang>.srt`）。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from flowocr.artifacts import matchedio, srtio
+
+ACCEPTS = (matchedio.SCHEMA,)
+"""这个预设吃哪几种阶段 2 产物（`flowocr.output.render` 按 `document["schema"]` 核）。"""
+
+
+def render(document: dict, output_dir, options: dict | None = None) -> list[Path]:
+    o = dict(options or {})
+    matchedio.validate(document)
+    lang = str(o.get("lang", "jp"))
+    if lang not in ("jp", "cn"):
+        raise ValueError(f"lang 只能是 jp / cn：{lang!r}")
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    stem = Path(matchedio.tracks_path(document) or "matched").stem.removesuffix("-tracks")
+    p = out / str(o.get("name") or f"{stem}-{lang}.srt")
+    srtio.write_srt_blocks(p, ((int(r["start"] * 1e6), int(r["end"] * 1e6), matchedio.body(r, lang))
+                               for r in document["cues"]))
+    return [p]

flowocr/output/presets/script.py

@@ -0,0 +1,20 @@
+"""内置预设 `script`：只跑阶段 3，写一份**字幕稿**（`*.script.ass`），在 Aegisub / mpv 里预览、编辑，改完再跑阶段 4：
+
+    python -m flowocr.output.render x-tracks.json --preset script --opt keep=all --outdir tmp/x
+    python -m flowocr.typeset tmp/x/x-all.script.ass
+
+options 见 `flowocr.output.script.render_script`（`keep` main / all、`why`、`lang`、`layers`、`tracks`、`typewriter`、`fade`、`name`）。
+字幕稿的格式见 artifacts.md 的字幕稿一节；方案见 script-fx 计划。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from flowocr.artifacts import matchedio, tracksio
+from flowocr.output import script
+
+ACCEPTS = (tracksio.SCHEMA, matchedio.SCHEMA)
+
+
+def render(document: dict, output_dir, options: dict | None = None) -> list[Path]:
+    return [script.render_script(document, output_dir, options)[0]]

flowocr/output/presets/srt_main.py

@@ -0,0 +1,33 @@
+"""内置预设：**只取主轨**的一份 SRT（project-structure："SRT 默认可以只取主轨"）。
+
+从 `*-tracks.json` 投影（`export.export_srt`），和 `build_tracks` 写在产物旁的那份主轨 SRT **逐字节相同**——
+同一份 cue 表、同一份 `ui_lines`，导出器不重新判断（docs/architecture/artifacts.md）。
+
+options：
+* `start`：cue 起点口径，`first`（默认，首字出现）/ `full`（全字出现）；
+* `name`：文件名（默认用 provenance 里的 `main_srt`，即 build_tracks 写的那个名字）。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from flowocr.artifacts import tracksio
+from flowocr.output import export
+
+ACCEPTS = (tracksio.SCHEMA,)
+"""这个预设吃哪几种阶段 2 产物（`flowocr.output.render` 按 `document["schema"]` 核）。"""
+
+
+def render(document: dict, output_dir, options: dict | None = None) -> list[Path]:
+    o = dict(options or {})
+    tid = document["provenance"].get("main_track") or ""
+    if not tid:
+        raise ValueError("这份产物没有主轨（provenance.main_track 为空）——挑不出主轨时用别的预设或自己写一个")
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    written = [out / name for name, _n in export.export_srt(document, out, only=tid, start=o.get("start", "first"))]
+    if o.get("name"):
+        target = out / str(o["name"])
+        written[0].replace(target)
+        written = [target]
+    return written