@dsh-gis/dsh-video-studio-skill 0.4.0 → 0.7.2

package/tools/estimate.py

@@ -0,0 +1,657 @@
+# -*- coding: utf-8 -*-
+"""estimate.py — 成本/时长预演：跑 --stage all 之前，先算"要渲多久、占多少盘、怎么分块"。
+
+用法
+----
+    python tools/estimate.py --script film.json [--work work] [--jobs 4]
+                             [--engine pil|web] [--rerender 1.4] [--json]
+
+做四件事
+--------
+  1. 帧数 / 时长 / fps / 分辨率（分辨率 1920x1080 在本项目写死，见 filmkit.W/H）
+  2. 各阶段耗时：tts / layout / cues / score / sfx / audio / frames / mux / qa
+  3. 磁盘：work 下 raw 管道峰值 + 成片体积估算
+  4. 分块建议（与 render.py 的 chunk_frames 规则逐字一致）+ 最大瓶颈项
+
+输入口径
+--------
+  有 <work>/timeline.json（已排过轴）→ 用真实 total/frames，输出里注明"真实帧数"；
+  没有 → 按 lines 文本"等效字数 ÷ 4.2 字/秒 + lead/tail + hold"粗估，
+  并在输出里**明确标注这是估算**（排过轴再跑一次就会换成真实数字）。
+
+退出码
+------
+  0 正常；2 剧本不存在 / 不是合法 JSON（一句话错误，不甩 traceback）。
+  --json 时 stdout 只有 JSON（键名全英文），可直接 json.loads；警告走 stderr。
+
+基准来源
+--------
+  所有速度常量集中在下面"基准常量"一节，出处是 skills/video-studio/SKILL.md §12
+  （作者机器 2026-11-07 实测：Ryzen AI 9 HX 370 / 12C24T / 无 NVIDIA）。
+  换机后先重测再采信——这些数字决定预演准不准，别凭感觉调。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+import unicodedata
+from pathlib import Path
+
+# ============================================================================
+# 基准常量（v0.7.2 重新校准：换机请重测后回填，别把这里的数字当通用真理）
+# ============================================================================
+
+W, H, FPS = 1920, 1080, 30          # filmkit.W/H/FPS：本项目写死，film.json 改不了
+PIL_FPS = (40.0, 80.0)              # PIL 逐帧渲染速度：中等复杂度 40–54 fps / 模板片 68–82 fps
+PARALLEL_EFF = 0.5                  # 分块并行的**实测效率**：2 进程只快 1.5×，不是 2×（见 CALIBRATION）
+WEB_SEC_PER_FRAME = (0.080, 0.130)  # web 引擎：Edge 无头 PNG 截图 80–130 ms/帧
+WEB_STARTUP_SEC = 6.0               # 浏览器冷启动 + CDP 连接（12 s 片 28–30 s 含启动）
+X264_FPS = 141.0                    # libx264 -preset medium -crf 17 ≈ 4.7× 实时（仅 reencode_video 用）
+TTS_SEC_PER_LINE = (2.0, 4.0)       # edge-tts：每句每 worker 的墙钟（联网，波动大）：实测 2.2 s，留到 4.0
+SCORE_REFS = ((29.0, 3.6, 6.5), (58.0, 4.5, 6.5), (389.0, 8.0, 18.0))
+#           ^ (片长 s, 耗时低, 耗时高)：前两个点是本机实测（29 s / 58 s 各 3 次），
+#             第三个点是片长外推锚点（不是本机实测），只用来保证长片不会被系统性算小
+SFX_SEC_PER_CUE = 0.20              # 单条短音效 合成+落位（24 配方单次 ≤1.5 s 是上限口径）
+SFX_MIN_SEC = 0.8                   # 实测 18 条 cue 的模板片 sfx 墙钟 0.8 s（含 ffmpeg 写盘）
+LAYOUT_BASE, LAYOUT_PER_LINE = 0.05, 0.01  # 排轴 + srt/ass + 安全区/字形自查（实测 29 s 片 <0.15 s）
+CUES_BASE, CUES_PER_LINE = 0.05, 0.005     # 提示点落盘 + 排序（实测 29 s 片 <0.15 s）
+AUDIO_BASE, AUDIO_PER_SEC = 0.6, 0.012     # numpy 总线按采样点叠加 + 写 wav
+# mux 默认是 -c:v copy + 两遍 loudnorm：实测 29 s 片 1.7–1.9 s，与帧数无关、跟片长弱相关。
+MUX_BASE_SEC = 0.6                  # 起 ffmpeg 两遍 + 封装
+MUX_PER_SEC = 0.045                 # 每片长秒（两遍 loudnorm 解码音频）
+# QA：实测 29 s 片 6.2–6.8 s（含联系表 + 锐度参考帧重渲染 + 帧级深检）。原来的 1/30 把 qa 算了 6 倍小。
+QA_BASE_SEC = (1.0, 3.0)            # 固定开销：联系表 + 参考帧重渲染
+QA_SEC_PER_SEC = (0.12, 0.25)       # 随片长：帧级深检流式解码 + 响度曲线
+UNMEASURED_BAND = 0.30              # 没有实测的阶段（layout/cues/sfx/audio）给 ±30% 的区间，别假装精确
+
+# 校准出处：换成你自己的机器前，请按 SKILL.md §12 重测并回填——这些数字决定预演准不准。
+CALIBRATION = dict(
+    machine=("AMD64 Family 26 Model 36 Stepping 0（24 逻辑核）/ Windows；"
+             "SKILL.md §12 记录的作者机是 Ryzen AI 9 HX 370 / 12C24T / Radeon 890M"
+             "（是否同一台未核实，只保证这些数字是在上述 24 逻辑核机器上测的）"),
+    measured_at="2026-11-10",
+    sdk="video-studio v0.7.1 scripts（ffmpeg 自带 x264）",
+    film="29.011 s / 870 帧 / 模板片（assets/film.json + assets/scenes.py）",
+    method="render.py --stage all --jobs 2，逐 stage 取 [time] 行墙钟；同片重复 2 次",
+    observed=dict(tts=2.2, layout=0.0, cues=0.0, score=6.3, sfx=0.8, audio=0.7,
+                  frames=9.7, mux=1.9, qa=6.8, total=28.4),
+    extra="frames: 870 帧 jobs=1 14.37 s / jobs=2 9.53 s（并行效率 1.51×）;"
+          " score 58 s 片 4.5–5.0 s; qa 6.2–6.8 s",
+)
+CPS = 4.2                            # 每秒约 4.2 字（voicekit 校准 3.84–4.61 cps 的中位口径）
+DEFAULT_LEAD, DEFAULT_TAIL, DEFAULT_MIN_DUR = 0.62, 0.92, 3.0  # v0.5 body 基准
+CORES = 12                           # HX 370：12C/24T；jobs > 12 不再线性加速
+TTS_BYTES_PER_LINE = 32 * 1024       # 单句 mp3 缓存（4 s 语音约 24 KB，留余量）
+WAV_BYTES_PER_SEC = 48000 * 2 * 2    # 48 kHz 立体声 PCM16 = 192 KB/s
+VIDEO_MBPS = (1.2, 3.0)              # crf17 @1080p30 图文内容（暗底大字 0.5–1 Mbps 属正常）
+AUDIO_MBPS = 0.192                   # AAC 192 kbps
+QA_DISK_BYTES = 12 * 1024 * 1024     # 联系表 + 静帧 + deep.png
+BASELINE_NOTE = ("区间来自 v0.7.2 本机实测（机型/样本见下方 calibration；"
+                 "SKILL.md §12 记录的作者机是 Ryzen AI 9 HX 370 / 12C24T）；换机请先重测再采信")
+
+STAGE_LABELS = {
+    "tts": "旁白 edge-tts",
+    "layout": "排时间轴",
+    "cues": "画面提示点",
+    "score": "程序化配乐",
+    "sfx": "音效合成",
+    "audio": "三总线混音",
+    "frames": "逐帧渲染+编码",
+    "mux": "合成成片",
+    "qa": "质检+抽帧",
+}
+
+
+# ============================================================================
+# 小工具
+# ============================================================================
+
+def _setup_stdio():
+    """输出被管道/文件重定向时把 stdout/stderr 切到 UTF-8（与 render.py 同一口径）。
+
+    Windows 下 python tools/estimate.py ... | tee log 的 stdout 默认是 GBK 代码页，
+    中文会乱码；真实控制台保持系统编码，交互运行时中文照样正常。
+    """
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            if stream is not None and not stream.isatty():
+                stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:                                   # noqa: BLE001
+            pass
+
+
+def _die(msg, as_json=False):
+    """一句话错误 + 退出码 2（输入/用法错误，不是片子坏了）。"""
+    if as_json:
+        sys.stdout.write(json.dumps({"ok": False, "error": msg}, ensure_ascii=False) + "\n")
+    else:
+        sys.stderr.write("[estimate] %s\n" % msg)
+    raise SystemExit(2)
+
+
+def _warn(msg):
+    """预演不阻断：警告一律走 stderr，--json 时 stdout 仍然只有 JSON。"""
+    sys.stderr.write("[estimate][WARN] %s\n" % msg)
+
+
+def load_script(path, as_json=False):
+    """读剧本；坏输入给一句话错误（退出码 2），不甩 traceback。"""
+    p = Path(path).expanduser()
+    if not p.exists():
+        _die("找不到剧本 %s（--script 指到 film.json；模板在 skills/video-studio/assets/film.json）"
+             % p, as_json)
+    try:
+        raw = p.read_text(encoding="utf-8")
+    except OSError as e:
+        _die("读不了剧本 %s：%s" % (p, e), as_json)
+    except UnicodeDecodeError as e:
+        _die("%s 不是 UTF-8 文本（%s）：用 UTF-8 另存 film.json" % (p, e), as_json)
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        _die("%s 不是合法 JSON：第 %d 行第 %d 列 %s（先跑 python -m json.tool 看一眼）"
+             % (p, e.lineno, e.colno, e.msg), as_json)
+    if not isinstance(data, dict):
+        _die("%s 顶层必须是 JSON 对象（当前是 %s）" % (p, type(data).__name__), as_json)
+    return p, data
+
+
+def _num(v, default=0.0):
+    """宽容取数：film.json 里写成字符串/None 时退回默认值（估算不该被脏字段炸掉）。"""
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return float(default)
+
+
+def _weighted_chars(text):
+    """等效字数：汉字 1；英文/数字 0.6；标点 0.3（停顿）；空格 0。"""
+    n = 0.0
+    for ch in str(text or ""):
+        o = ord(ch)
+        if 0x3400 <= o <= 0x4DBF or 0x4E00 <= o <= 0x9FFF or 0xF900 <= o <= 0xFAFF:
+            n += 1.0
+        elif ch.isspace():
+            continue
+        elif ch.isascii() and ch.isalnum():
+            n += 0.6
+        else:
+            n += 0.3
+    return n
+
+
+def _dw(s):
+    """显示宽度（中文按 2 列算），只用于表格对齐。"""
+    return sum(2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1 for ch in str(s))
+
+
+def _pad(s, width):
+    s = str(s)
+    return s + " " * max(0, width - _dw(s))
+
+
+def _fmt_bytes(n):
+    """十进制单位（1 GB = 10^9 B）：和 SKILL.md §12 的口径一致（1080p30 的 30 s ≈5.6 GB）。"""
+    n = float(n)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if n < 1000.0 or unit == "TB":
+            if unit == "B":
+                return "%.0f B" % n
+            return "%.1f %s" % (n, unit)
+        n /= 1000.0
+
+
+def _fmt_span(lo, hi):
+    if abs(float(hi) - float(lo)) < 0.05:
+        return "%.1f s" % float(lo)
+    return "%.1f–%.1f s" % (float(lo), float(hi))
+
+
+# ============================================================================
+# 估算核心
+# ============================================================================
+
+def estimate_timeline(script):
+    """没有 timeline.json 时：按"等效字数 ÷ 4.2 字/秒 + lead/tail + hold"粗估。
+
+    与 filmkit.build_timeline 的公式同构：dur = max(min_dur, lead + voice + tail + hold)。
+    只能说"量级对"，误差通常 ±10–20%——这正是输出里必须标注"估算"的原因。
+    """
+    lines = [ln for ln in (script.get("lines") or []) if isinstance(ln, dict)]
+    lead = _num(script.get("lead", DEFAULT_LEAD), DEFAULT_LEAD)
+    tail = _num(script.get("tail", DEFAULT_TAIL), DEFAULT_TAIL)
+    min_dur = _num(script.get("min_dur", DEFAULT_MIN_DUR), DEFAULT_MIN_DUR)
+    ghold = _num(script.get("hold", 0.0))
+    scenes = []
+    for ln in lines:
+        voice = _weighted_chars(ln.get("text")) / CPS
+        hold = _num(ln.get("hold", ghold))
+        scenes.append(dict(id=str(ln.get("id") or ""), voice=voice, hold=hold,
+                           dur=max(min_dur, lead + voice + tail + hold)))
+    return sum(s["dur"] for s in scenes), scenes
+
+
+def read_timeline(work):
+    """读 <work>/timeline.json（已排轴的真实帧数）。缺失/坏文件返回 (None, 路径)。"""
+    p = Path(work) / "timeline.json"
+    if not p.exists():
+        return None, p
+    try:
+        tl = json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError) as e:
+        _warn("忽略 %s（读不了：%s），退回剧本粗估" % (p, e))
+        return None, p
+    if not isinstance(tl, dict) or "total" not in tl or "frames" not in tl:
+        _warn("忽略 %s（没有 total/frames 字段，不像本项目的 timeline），退回剧本粗估" % p)
+        return None, p
+    return tl, p
+
+
+def score_seconds(total):
+    """配乐耗时：以 60 s / 389 s 两个实测点线性折算（超出范围按最近一段斜率外推）。"""
+    pts = [(r[0], r[1], r[2]) for r in SCORE_REFS]
+    if total <= pts[0][0]:
+        (x0, l0, h0), (x1, l1, h1) = pts[0], pts[1]
+    elif total >= pts[-1][0]:
+        (x0, l0, h0), (x1, l1, h1) = pts[-2], pts[-1]
+    else:
+        (x0, l0, h0), (x1, l1, h1) = pts[0], pts[1]
+        for i in range(len(pts) - 1):
+            if pts[i][0] <= total <= pts[i + 1][0]:
+                (x0, l0, h0), (x1, l1, h1) = pts[i], pts[i + 1]
+                break
+    k = (float(total) - x0) / float(x1 - x0) if x1 != x0 else 0.0
+    lo = l0 + (l1 - l0) * k
+    hi = h0 + (h1 - h0) * k
+    return max(0.3, lo), max(0.5, hi)
+
+
+def _speedup(jobs):
+    """分块并行的**有效加速比**：不是 jobs 倍。
+
+    实测（870 帧模板片）：jobs=1 → 14.37 s、jobs=2 → 9.53 s，只有 1.51×。
+    原因很实在：父进程要 spawn 子进程、每段都要重新 import scenes.py / 解析主题、
+    落盘 mux 串行、磁盘写带宽争用。按 jobs 线性折算会持续低估长片（越长的片分块越多）。
+    这里用 1 + (jobs-1)*PARALLEL_EFF 的线性模型：比理论值保守，实测 2 进程刚好对上。
+    """
+    jobs_eff = max(1, min(int(jobs), CORES))
+    return 1.0 + (jobs_eff - 1) * PARALLEL_EFF
+
+
+def frames_seconds(frames, jobs, engine, rerender):
+    """frames 阶段墙钟（只算画面生成；不重编码时封装成本在 mux 行）。
+
+    PIL：帧数 ÷ 渲染 fps ÷ 有效加速比；web：启动开销 + 帧数 × 每帧截图耗时 ÷ 加速比。
+    render.py 的分块 worker 是边渲染边编码，所以这里的 fps 已经含了编码开销。
+    """
+    sp = _speedup(jobs)
+    if engine == "web":
+        base = [WEB_STARTUP_SEC + frames * spf / sp for spf in WEB_SEC_PER_FRAME]
+    else:
+        base = [frames / rfps / sp for rfps in PIL_FPS]
+    base = sorted(base)
+    return base[0] * rerender, base[-1] * rerender
+
+
+def mux_seconds_pair(frames, jobs, total, script):
+    """mux 阶段区间：默认 -c:v copy 只跟片长有关；reencode_video=true 才跟帧数有关。"""
+    reencode = bool(script.get("reencode_video", False))
+    if reencode:
+        v = frames / X264_FPS / _speedup(jobs)
+        return v * 0.8, v * 1.6
+    base = MUX_BASE_SEC + MUX_PER_SEC * max(0.0, float(total))
+    return base * 0.75, base * 1.35
+
+
+def mux_seconds(frames, jobs, total, reencode=False):
+    """mux 阶段墙钟。
+
+    默认 `-c:v copy` + 两遍 loudnorm：视频流不解码不重编码，成本 ≈ 起 ffmpeg + 按片长
+    解码音频跑两遍。实测 29 s 片 1.7–1.9 s。
+    reencode_video=true 时才要重编视频，那时才用 x264 速率并按有效加速比摊。
+    """
+    if reencode:
+        return frames / X264_FPS / _speedup(jobs)
+    return MUX_BASE_SEC + MUX_PER_SEC * max(0.0, float(total))
+
+
+def chunk_plan(frames, fps, jobs, explicit):
+    """逐字复刻 render.py 的分块规则（改了那边记得同步这里）。
+
+        chunk = script.chunk_frames or round(frames/jobs/fps/4)*4*fps
+        chunk = max(fps*2, round(chunk/fps)*fps)
+    """
+    fps = int(fps) or FPS
+    jobs = max(1, int(jobs))
+    if explicit:
+        chunk = int(explicit)
+    else:
+        chunk = int(round(frames / float(jobs) / float(fps) / 4.0)) * 4 * fps
+    chunk = max(fps * 2, int(round(chunk / float(fps))) * int(fps))
+    nseg = int(math.ceil(frames / float(chunk))) if frames and chunk else 0
+    return chunk, nseg
+
+
+def disk_estimate(frames, total, n_lines, n_cues, crf, music_on):
+    """磁盘：raw 管道峰值（不落盘但决定内存/管道带宽）+ work/ + out/。"""
+    try:
+        crf = int(crf)
+    except (TypeError, ValueError):
+        crf = 17
+    factor = 2.0 ** ((17.0 - crf) / 6.0)          # crf 每降 6 体积约翻倍（x264 经验值）
+    vlo = max(0.3, VIDEO_MBPS[0] * factor)
+    vhi = max(0.3, VIDEO_MBPS[1] * factor)
+    vid_lo = total * vlo * 1e6 / 8.0
+    vid_hi = total * vhi * 1e6 / 8.0
+    out_lo = total * (vlo + AUDIO_MBPS) * 1e6 / 8.0
+    out_hi = total * (vhi + AUDIO_MBPS) * 1e6 / 8.0
+    n_wav = 1 + (1 if music_on else 0) + (1 if n_cues else 0)
+    wav_bytes = total * WAV_BYTES_PER_SEC
+    segments = vid_hi                        # 分块文件合计 ≈ 整片视频体积
+    silent = vid_hi
+    tts = n_lines * TTS_BYTES_PER_LINE
+    qa = QA_DISK_BYTES if frames else 0
+    work = tts + segments + silent + n_wav * wav_bytes + qa
+    return dict(raw_peak_bytes=W * H * 3 * int(frames),
+                work_bytes=work,
+                out_bytes_lo=out_lo, out_bytes_hi=out_hi,
+                breakdown=dict(tts_bytes=tts, segments_bytes=segments,
+                               silent_bytes=silent, wav_bytes=n_wav * wav_bytes,
+                               qa_bytes=qa),
+                video_mbps=(vlo, vhi))
+
+
+def bottleneck_advice(stage, engine, jobs_eff):
+    if stage == "frames":
+        if engine == "web":
+            return ("换 engine=pil：同一画面语言下 PIL 比浏览器逐帧快 5–10 倍；"
+                    "确实需要 Canvas/WebGL 才留 web（--jobs 提到 %d 也压不动截图往返的瓶颈）"
+                    % CORES)
+        return ("把 --jobs 从 %d 提到 8–%d（本机 12 核）能把 frames 大致线性压下来；"
+                "再想快只能减帧或简化场景——1920x1080 是写死的，降分辨率不是选项"
+                % (jobs_eff, CORES))
+    if stage == "tts":
+        return "TTS 是网络等待：tts_workers 保持 4–6 就够，句子多先压台词，别靠并发硬堆"
+    if stage == "qa":
+        return "质检已是秒级；它随片长线性涨，是必要成本（不查等于没门禁）"
+    if stage == "score":
+        return "配乐是秒级纯 CPU 合成；片长再长也不该成为瓶颈"
+    return "该阶段占比高但绝对值不大：按上面的区间排期即可"
+
+
+# ============================================================================
+# 主流程
+# ============================================================================
+
+def build_report(script_path, script, args):
+    as_json = bool(args.as_json)
+    lines = [ln for ln in (script.get("lines") or []) if isinstance(ln, dict)]
+    if not lines:
+        _die("%s 的 lines 是空的：至少写一句（render.py 只接受非空数组）" % script_path, as_json)
+
+    engine = str(args.engine or script.get("engine") or "pil").lower()
+    if engine not in ("pil", "web"):
+        _warn("engine=%r 不认识（只能是 pil / web），按 pil 预演" % engine)
+        engine = "pil"
+
+    tl, tl_path = read_timeline(args.work)
+    if tl is not None:
+        total = _num(tl.get("total"))
+        fps = int(_num(tl.get("fps"), FPS)) or FPS
+        frames = int(_num(tl.get("frames"), round(total * fps)))
+        source = "timeline"
+        source_note = "真实帧数：%s" % tl_path
+    else:
+        total, _scenes = estimate_timeline(script)
+        fps = FPS
+        frames = int(round(total * fps))
+        source = "script_estimate"
+        source_note = ("粗估（等效字数 ÷ %.1f 字/秒 + lead/tail + hold；没有 %s）"
+                       % (CPS, tl_path))
+        if total <= 0:
+            _die("%s 的 lines 里没有可估算的 text：每句都要有朗读文本" % script_path, as_json)
+
+    jobs_req = int(args.jobs)
+    if jobs_req < 1:
+        _warn("--jobs %d 无效，按 1 算" % jobs_req)
+        jobs_req = 1
+    jobs_eff = max(1, min(jobs_req, CORES))
+    if jobs_req > CORES:
+        _warn("--jobs %d 超过本机 12 核：分块并行到 12 之后基本不再线性加速" % jobs_req)
+
+    rerender = max(0.1, float(args.rerender))
+    n = len(lines)
+    sfx_cfg = script.get("sfx") or {}
+    mus = script.get("music") or {}
+    if not isinstance(sfx_cfg, dict):
+        sfx_cfg = {}
+    if not isinstance(mus, dict):
+        mus = {}
+    n_cues = len(sfx_cfg.get("cues") or [])
+    sfx_on = bool(sfx_cfg.get("enabled", True)) and n_cues > 0
+    # 配乐口径对齐 filmkit.music_plan：mode=off/none 或 enabled=false 才算关；
+    # 只有 mode=score（或没写 mode 但写了 bpm）才会真跑 scorekit。
+    mode = str(mus.get("mode") or "").strip().lower()
+    has_bpm = "bpm" in mus or "bpm" in script
+    music_on = bool(mus.get("enabled", True)) and mode not in ("off", "none")
+    score_on = music_on and (mode == "score" or (not mode and has_bpm))
+    crf = script.get("crf", 17)
+    preset = script.get("preset", "medium")
+
+    # ---- 各阶段 ----
+    # 没有实测的阶段一律给区间（正负 UNMEASURED_BAND），别把经验公式输出当精确值。
+    def _band(v):
+        # 下界永远让它摸到 0：这些阶段实测常常 <0.1 s（render.py 的 [time] 行按 0.1 s 打印，
+        # 于是显示 0.0），下界写成正值会让"实测值落在区间外"这种假告警出现。
+        return min(0.0, v * (1.0 - UNMEASURED_BAND)), v * (1.0 + UNMEASURED_BAND)
+    workers = int(_num(script.get("tts_workers", 4), 4) or 4)
+    workers = max(1, min(workers, max(1, n)))
+    # TTS 按每句每 worker 摊：实测 4 句 / 4 workers = 2.2 s（串行口径 8.8 s）。
+    tts_lo = n * TTS_SEC_PER_LINE[0] / float(workers)
+    tts_hi = n * TTS_SEC_PER_LINE[1] / float(workers)
+    layout_lo, layout_hi = _band(LAYOUT_BASE + LAYOUT_PER_LINE * n)
+    cues_lo, cues_hi = _band(CUES_BASE + CUES_PER_LINE * n)
+    if score_on:
+        score_lo, score_hi = score_seconds(total)
+    else:
+        score_lo = score_hi = 0.0
+    sfx_lo, sfx_hi = _band(max(SFX_MIN_SEC, n_cues * SFX_SEC_PER_CUE)) if sfx_on else (0.0, 0.0)
+    audio_lo, audio_hi = _band(AUDIO_BASE + total * AUDIO_PER_SEC)
+    fr_lo, fr_hi = frames_seconds(frames, jobs_eff, engine, rerender)
+    mux_lo, mux_hi = mux_seconds_pair(frames, jobs_eff, total, script)
+    qa_lo = max(0.5, QA_BASE_SEC[0] + total * QA_SEC_PER_SEC[0])
+    qa_hi = max(qa_lo, QA_BASE_SEC[1] + total * QA_SEC_PER_SEC[1])
+
+    stages = [
+        dict(stage="tts", lo=tts_lo, hi=tts_hi, measured=True,
+             note=("%d 句 ÷ tts_workers=%d，每句每 worker %.1f–%.1f s（实测 2.2 s/4 句；"
+                   "需联网，edge-tts 免费端点波动大）"
+                   % (n, workers, TTS_SEC_PER_LINE[0], TTS_SEC_PER_LINE[1]))),
+        dict(stage="layout", lo=layout_lo, hi=layout_hi, measured=False,
+             note="排轴 + sub.srt/ass + 安全区/字形自查（经验模型，给 ±%d%% 区间）"
+                  % int(UNMEASURED_BAND * 100)),
+        dict(stage="cues", lo=cues_lo, hi=cues_hi, measured=False,
+             note="%d 条 sfx.cues 落位 + 排序（经验模型，给 ±%d%% 区间）"
+                  % (n_cues, int(UNMEASURED_BAND * 100))),
+        dict(stage="score", lo=score_lo, hi=score_hi, measured=bool(score_on),
+             note=("以实测点 29 s≈3.6–6.3 s / 58 s≈4.5–5.0 s 为锚（--stage all 里与其它阶段争 CPU 会更慢；389 s 只是外推锚点）"
+                   if score_on else
+                   ("mode=%s：不跑 scorekit（%s）"
+                    % (mode or "-", "外部配乐/和弦床/关掉配乐")))),
+        dict(stage="sfx", lo=sfx_lo, hi=sfx_hi, measured=False,
+             note=("%d 条音效（实测 18 条 0.8 s；单条上限口径 ≤1.5 s，长环境声 wind/rain 另计）"
+                   % n_cues if sfx_on else
+                   "没有 sfx.cues：跳过（whoosh 兼容路径除外）")),
+        dict(stage="audio", lo=audio_lo, hi=audio_hi, measured=False,
+             note="三总线混音 + 写 audio.wav（实测 29 s 片 0.7 s；模型 %.2f + %.3f×片长）"
+                  % (AUDIO_BASE, AUDIO_PER_SEC)),
+        dict(stage="frames", lo=fr_lo, hi=fr_hi, measured=True,
+             note=("%s：%s，--jobs %d → 有效加速比 %.2f×（实测 2 进程 1.51×），"
+                   "返工系数 %.2g；不重编码时封装成本在 mux 行"
+                   % (engine, "PIL 40–80 fps" if engine == "pil"
+                      else "web 80–130 ms/帧 + 启动 6 s", jobs_eff,
+                      _speedup(jobs_eff), rerender))),
+        dict(stage="mux", lo=mux_lo, hi=mux_hi, measured=True,
+             note=("-c:v copy + 两遍 loudnorm（实测 29 s 片 1.7–1.9 s，与帧数无关）；"
+                   "reencode_video=true 才走 x264 %.0f fps" % X264_FPS)),
+        dict(stage="qa", lo=qa_lo, hi=qa_hi, measured=True,
+             note=("联系表 + 锐度参考帧重渲染 + 帧级深检（实测 29 s 片 6.2–6.8 s，不是 1 s）")),
+    ]
+    total_lo = sum(s["lo"] for s in stages)
+    total_hi = sum(s["hi"] for s in stages)
+    worst = max(stages, key=lambda s: s["hi"])
+    share = worst["hi"] / total_hi if total_hi > 0 else 0.0
+
+    # ---- 磁盘 ----
+    disk = disk_estimate(frames, total, n, n_cues, crf, music_on)
+
+    # ---- 分块（render.py 规则）----
+    explicit = int(_num(script.get("chunk_frames"), 0))
+    chunk, nseg = chunk_plan(frames, fps, jobs_eff, explicit)
+    chunk = dict(jobs=jobs_eff, jobs_requested=jobs_req, chunk_frames=chunk,
+                 segments=nseg, explicit=bool(explicit),
+                 rule="chunk = chunk_frames 或 round(frames/jobs/fps/4)*4*fps，"
+                      "再按 fps 取整、最小 2×fps")
+
+    report = {
+        "ok": True,
+        "file": str(script_path),
+        "source": source,
+        "source_note": source_note,
+        "video": {"title": script.get("title"),
+                  "width": W, "height": H, "fps": fps, "frames": frames,
+                  "duration_s": round(total, 3), "engine": engine,
+                  "crf": crf, "preset": preset, "bpm": mus.get("bpm", script.get("bpm")),
+                  "style": script.get("style", None)},
+        "counts": {"lines": n, "cues": n_cues, "tts_workers": workers},
+        "jobs": {"requested": jobs_req, "effective": jobs_eff, "cores": CORES},
+        "rerender": rerender,
+        "stages": [dict(stage=s["stage"], label=STAGE_LABELS[s["stage"]],
+                        seconds_lo=round(s["lo"], 2), seconds_hi=round(s["hi"], 2),
+                        measured=s["measured"], note=s["note"]) for s in stages],
+        "total_seconds": {"lo": round(total_lo, 2), "hi": round(total_hi, 2)},
+        "disk": {"raw_peak_bytes": disk["raw_peak_bytes"],
+                 "raw_peak_human": _fmt_bytes(disk["raw_peak_bytes"]),
+                 "work_bytes": int(disk["work_bytes"]),
+                 "work_human": _fmt_bytes(disk["work_bytes"]),
+                 "out_bytes_lo": int(disk["out_bytes_lo"]),
+                 "out_bytes_hi": int(disk["out_bytes_hi"]),
+                 "out_human": "%s–%s" % (_fmt_bytes(disk["out_bytes_lo"]),
+                                         _fmt_bytes(disk["out_bytes_hi"])),
+                 "video_mbps": [round(v, 2) for v in disk["video_mbps"]]},
+        "chunk": chunk,
+        "bottleneck": {"stage": worst["stage"],
+                       "seconds_hi": round(worst["hi"], 2),
+                       "share": round(share, 3),
+                       "advice": bottleneck_advice(worst["stage"], engine, jobs_eff)},
+        "assumptions": [
+            "分辨率 1920x1080@%d 由 filmkit.W/H/FPS 写死，film.json 改不了" % FPS,
+            "lead=%.2f / tail=%.2f / min_dur=%.1f（v0.5 body 基准；剧本写了就以剧本为准）"
+            % (DEFAULT_LEAD, DEFAULT_TAIL, DEFAULT_MIN_DUR),
+            "tts 耗时按 %d 句 ÷ workers × %.1f–%.1f s（每句每 worker）；实际受网络波动影响"
+            % (n, TTS_SEC_PER_LINE[0], TTS_SEC_PER_LINE[1]),
+            "frames 的并行不是 jobs 倍：有效加速比 = 1 + (jobs-1)×%.2f，封顶 %d 核"
+            % (PARALLEL_EFF, CORES),
+            "mux 默认 -c:v copy，只跟片长有关；reencode_video=true 才按帧数重编",
+            "layout/cues/audio/sfx 给 ±%d%% 经验区间（无单阶段实测）" % int(UNMEASURED_BAND * 100),
+            "基准来源见 calibration 字段（机型/日期/样本）；换机请重测后回填顶部常量",
+        ],
+        "baseline": BASELINE_NOTE,
+        "calibration": dict(CALIBRATION),
+    }
+    return report
+
+
+def print_report(rep):
+    """人读表格（--json 时不走这里，stdout 保持纯 JSON）。"""
+    v = rep["video"]
+    d = rep["disk"]
+    ch = rep["chunk"]
+    print("[estimate] %s" % rep["file"])
+    if rep["source"] == "timeline":
+        print("  来源: %s（已排轴：用真实 total/frames）" % rep["source_note"])
+    else:
+        print("  来源: %s" % rep["source_note"])
+        print("        注意：这是**估算**，不是实测。跑过 --stage layout 后再跑本脚本，"
+              "会自动改用真实帧数。")
+    style = v.get("style")
+    if style is None:
+        style = "(没写 style 字段 = v0.4 legacy 行为)"
+    print("  《%s》  片长 %.1f s / %d 帧 / %dx%d@%d / engine=%s / crf=%s preset=%s / style=%s"
+          % (v.get("title") or "(未写 title)", v["duration_s"], v["frames"], v["width"], v["height"],
+             v["fps"], v["engine"], v["crf"], v["preset"], style))
+    print("  并行: --jobs %d（请求 %d；本机 12 核，>12 不再线性）  返工系数: %.2g"
+          % (ch["jobs"], ch["jobs_requested"], rep["rerender"]))
+    print()
+    print("  %s %s %s" % (_pad("阶段", 8), _pad("耗时", 16), "说明"))
+    for s in rep["stages"]:
+        span = _fmt_span(s["seconds_lo"], s["seconds_hi"])
+        tag = "" if s["measured"] else "[经验值] "
+        print("  %s %s %s"
+              % (_pad(s["stage"], 8), _pad(span, 16), tag + s["label"] + "：" + s["note"]))
+    total = _fmt_span(rep["total_seconds"]["lo"], rep["total_seconds"]["hi"])
+    print("  %s %s %s" % (_pad("合计", 8), _pad(total, 16), "--stage all 顺序跑完的墙钟（frames 并行）"))
+    print()
+    print("  磁盘")
+    print("    raw 管道峰值   %s   %d×%d×3 字节 × %d 帧（原始帧流式喂 x264，不落盘，"
+          "但决定内存/管道带宽）" % (_pad(d["raw_peak_human"], 10), W, H, v["frames"]))
+    print("    work/          %s   segments + silent.mp4 + wav + tts + qa"
+          "（分块并行时 segments 与 silent 会同时存在）" % _pad(d["work_human"], 10))
+    print("    out/           %s   成片（视频 %.1f–%.1f Mbps + AAC 192 kbps）"
+          % (_pad(d["out_human"], 10), d["video_mbps"][0], d["video_mbps"][1]))
+    print()
+    print("  分块建议（对齐 render.py：%s）" % ch["rule"])
+    print("    --jobs %d" % ch["jobs"])
+    print("    chunk_frames: %d   写进 film.json（render.py 没有 --chunk 参数，只从剧本读）"
+          % ch["chunk_frames"])
+    print("    预计分块 %d 段 × 约 %d 帧" % (ch["segments"], ch["chunk_frames"]))
+    if ch["explicit"]:
+        print("    （剧本里已显式写了 chunk_frames，这里按它算）")
+    print()
+    bn = rep["bottleneck"]
+    print("  最大瓶颈：%s ≈ %.1f s（占 %.0f%%）—— %s"
+          % (bn["stage"], bn["seconds_hi"], bn["share"] * 100, bn["advice"]))
+    print()
+    print("  基准说明：%s" % rep["baseline"])
+    cal = rep.get("calibration") or {}
+    if cal:
+        print("  校准出处（换机请重测后回填 tools/estimate.py 顶部常量）：")
+        print("    机型   %s" % cal.get("machine", "-"))
+        print("    实测   %s · 样本 %s" % (cal.get("measured_at", "-"), cal.get("film", "-")))
+        print("    方法   %s" % cal.get("method", "-"))
+        obs = cal.get("observed") or {}
+        if obs:
+            print("    实测值 " + " · ".join("%s %.1fs" % (k, v) for k, v in obs.items()))
+    print("  假设：")
+    for a in rep["assumptions"]:
+        print("    - %s" % a)
+
+
+def main(argv=None):
+    _setup_stdio()
+    ap = argparse.ArgumentParser(
+        description="video-studio 成本/时长预演：渲多久、占多少盘、怎么分块")
+    ap.add_argument("--script", default="film.json", help="剧本路径（默认 film.json）")
+    ap.add_argument("--work", default="work", help="工作目录（有 timeline.json 就用真实帧数）")
+    ap.add_argument("--jobs", type=int, default=4, help="frames 阶段并行进程数（默认 4，本机上限 12）")
+    ap.add_argument("--engine", default="", choices=("", "pil", "web"),
+                    help="覆盖 film.json 的 engine（空 = 按剧本，缺省 pil）")
+    ap.add_argument("--rerender", type=float, default=1.0,
+                    help="返工系数：画面预计重渲几遍（1.0 = 一遍过；1.4 = 预留 40%%）")
+    ap.add_argument("--json", action="store_true", dest="as_json",
+                    help="机读输出（stdout 只有 JSON，键名英文）")
+    args = ap.parse_args(argv)
+
+    script_path, script = load_script(args.script, bool(args.as_json))
+    rep = build_report(script_path, script, args)
+    if args.as_json:
+        sys.stdout.write(json.dumps(rep, ensure_ascii=False, indent=2) + "\n")
+    else:
+        print_report(rep)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())