@remixmate/cli 0.9.50 → 0.9.52

package/skills/template-registry/video_dsl/runtime/narration_budget.py

@@ -0,0 +1,129 @@
+"""
+旁白时长预算 —— 规划期（写脚本时）估算「这段旁白念完、这一场实际会有多长」。
+
+为什么单独成模块：以前这个数有三份且互不一致 —— gen_script 的 ``CHARS_PER_SECOND = 5.0``
+（从没参与计算，只出现在注释里）、gen-script SKILL.md 的「3–4 字/秒」、timeline_compiler
+的 5.0（那份是没有 TTS 时间戳时估字幕时长的兜底，语义不同，不归这里管）。没有任何一环
+真的拿旁白字数去核对场景时长，于是 2026-09-27 线上一条会话：确认稿写 75s、每场 8–9s，
+每场却写了 45–58 字，成片 116.9s（+56%），用户确认的时长从一开始就不可能兑现。
+
+模型 = 语速 + 行间停顿 + 场景尾巴，三项都按那条会话的 9 条 TTS 实测标定：
+
+* 语速：纯整段旁白的场景 1.1× 下 ≈ 4.8–5.2 计数字/秒（汉字 + 英文词×2）→ 1.0× 取
+  ``PLAN_CHARS_PER_SEC_1X = 4.5``（略偏保守）；
+* 行间停顿：分行旁白（``narration.items`` / intro / outro）每多一行，TTS 按段合成，
+  段间约 0.9s 的静音 —— 逐项高亮版式同样字数要慢出 30–60%，主要就是它；
+* 场景尾巴：``render_video.adjust_timeline_to_audio`` 在每场音频后补的留白
+  （模板 ``capabilities.defaultTailPadSec``，缺省 1.5s）。9 场就是 13.5s，写脚本时
+  从没人算进去。
+
+样本只有一条会话，所以这些是**规划用**的估计，不是承诺；估不准的方向应当是偏保守
+（宁可让模型少写几个字）。英文语速未标定，先按常见 TTS 语速给。
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Optional
+
+# 语速（1.0× 下）。中文按「计数字」（见 count_speech_units），英文按词。
+PLAN_CHARS_PER_SEC_1X = 4.5
+PLAN_WORDS_PER_SEC_1X = 2.5  # 未标定
+
+# 分行旁白每一处换行带来的静音。
+LINE_PAUSE_SEC = 0.9
+
+# 必须与 render_video.adjust_timeline_to_audio 的缺省尾巴一致（int(fps * 1.5)）。
+DEFAULT_TAIL_PAD_SEC = 1.5
+
+# 估算总时长超出目标多少才告警。低于这个幅度属于估算误差本身的量级。
+OVERRUN_WARN_RATIO = 0.3
+
+_CJK = re.compile(r"[\u3400-\u9fff\uf900-\ufaff]")
+# 中文旁白里夹的英文词 / 数字组（"AI Agent"、"2026"）。一个英文词 TTS 念出来大约
+# 占两个汉字的时长。
+_LATIN_WORD = re.compile(r"[A-Za-z0-9]+(?:['’.-][A-Za-z0-9]+)*")
+
+
+def count_speech_units(text: str) -> tuple[float, str]:
+    """返回 (计数, 语言)。有汉字按中文计（汉字 + 英文词×2），否则按英文词计。"""
+    if not isinstance(text, str) or not text.strip():
+        return 0.0, "zh"
+    cjk = len(_CJK.findall(text))
+    words = len(_LATIN_WORD.findall(text))
+    if cjk:
+        return float(cjk + 2 * words), "zh"
+    return float(words), "en"
+
+
+def narration_lines(narration: object) -> list[str]:
+    """旁白按 TTS 实际合成的段拆开：分行形态 = intro + items + outro，否则整段 text。
+
+    与 render_video.extract_narration_lines 同口径：有 items 时 text 被整个忽略。
+    """
+    if not isinstance(narration, dict):
+        return []
+    items = narration.get("items")
+    lines: list[str] = []
+    if isinstance(items, list):
+        for x in items:
+            t = x.get("text", "") if isinstance(x, dict) else x
+            if isinstance(t, str) and t.strip():
+                lines.append(t.strip())
+    if lines:
+        for key, at_front in (("intro", True), ("outro", False)):
+            v = narration.get(key)
+            if isinstance(v, str) and v.strip():
+                if at_front:
+                    lines.insert(0, v.strip())
+                else:
+                    lines.append(v.strip())
+        return lines
+    text = narration.get("text")
+    return [text.strip()] if isinstance(text, str) and text.strip() else []
+
+
+def speech_rate(language: str, speed: float) -> float:
+    base = PLAN_CHARS_PER_SEC_1X if language == "zh" else PLAN_WORDS_PER_SEC_1X
+    return base * (speed if speed and speed > 0 else 1.0)
+
+
+def estimate_speech_sec(narration: object, speed: float = 1.0) -> float:
+    """念完这段旁白要多少秒（含分行停顿，不含场景尾巴）。"""
+    lines = narration_lines(narration)
+    if not lines:
+        return 0.0
+    units, language = count_speech_units("\n".join(lines))
+    return units / speech_rate(language, speed) + LINE_PAUSE_SEC * (len(lines) - 1)
+
+
+def template_tail_pad_sec(template_config: Optional[dict]) -> float:
+    """场景尾巴：模板声明的 capabilities.defaultTailPadSec，缺省 1.5s。"""
+    caps = (template_config or {}).get("capabilities") or {}
+    v = caps.get("defaultTailPadSec") if isinstance(caps, dict) else None
+    if isinstance(v, bool) or not isinstance(v, (int, float)) or v < 0:
+        return DEFAULT_TAIL_PAD_SEC
+    return float(v)
+
+
+def estimate_scene_sec(narration: object, speed: float = 1.0, tail_pad_sec: float = DEFAULT_TAIL_PAD_SEC) -> float:
+    """这一场按旁白估出来的时长。没有旁白返回 0（由调用方退回场景自己的 duration）。"""
+    speech = estimate_speech_sec(narration, speed)
+    return speech + tail_pad_sec if speech > 0 else 0.0
+
+
+def speech_budget(
+    duration_sec: float,
+    speed: float = 1.0,
+    language: str = "zh",
+    lines: int = 1,
+    tail_pad_sec: float = DEFAULT_TAIL_PAD_SEC,
+) -> int:
+    """一场 ``duration_sec`` 秒的场景，旁白最多写多少字（中文）/ 词（英文）。
+
+    ``lines`` > 1 时扣掉分行停顿 —— 逐项高亮的版式同样秒数能写的字明显更少。
+    至少返回 1：预算为 0 的场景说明秒数本身就不够，调用方应当提示加时长而不是写空旁白。
+    """
+    available = duration_sec - tail_pad_sec - LINE_PAUSE_SEC * max(lines - 1, 0)
+    return max(1, int(math.floor(available * speech_rate(language, speed))))

package/skills/template-registry/video_dsl/schema/video-dsl-v1alpha1.json

@@ -243,7 +243,7 @@
                 "items": {
                   "type": "array",
                   "items": { "type": "string" },
-                  "description": "每行一个卡片的叙述句。长度必须等于 templateData 里对应数组（concepts/pillars/eras/items）的长度"
+                  "description": "每行一个卡片的叙述句。长度必须等于 templateData 里对应数组的长度（数组键由模板的 lineSyncSlides[slideId] 声明）"
                 },
                 "outro": { "type": "string", "description": "可选：收尾句（此期间无卡片高亮）" },
                 "assetRef": { "type": "string", "description": "旁白音频 assetId" },

package/skills/template-registry/scripts/check_contracts.py

@@ -1,179 +0,0 @@
-#!/usr/bin/env python3
-"""Cross-module contract checker: template-library ↔ remotion-renderer.
-
-Verifies that every `compositionId` referenced from the @ab-templates/metadata
-registry.json is:
-  1. Registered in `<monorepo-root>/remotion-renderer/src/core/compositions/manifest.ts`
-  2. Mapped there to the SAME `templateId` as the template entry's
-     top-level `templateId` field
-
-Exit non-zero with a useful diff if the two sides disagree.
-
-Usage:
-    python3 scripts/check_contracts.py
-"""
-from __future__ import annotations
-
-import json
-import os
-import re
-import sys
-from typing import Iterator
-
-from template_paths import monorepo_registry_path, monorepo_root
-
-_REGISTRY_PATH = monorepo_registry_path()
-_MANIFEST_PATH = os.path.abspath(
-    os.path.join(
-        monorepo_root(),
-        "remotion-renderer",
-        "src",
-        "core",
-        "compositions",
-        "manifest.ts",
-    )
-)
-
-
-# Matches a single manifest row:
-#   SomeCompositionId: { component: Foo, templateId: "t-id", slot: "opening" },
-_MANIFEST_ROW_RE = re.compile(
-    r'^\s*(?P<cid>[A-Za-z0-9_]+)\s*:\s*\{\s*'
-    r'component\s*:\s*[A-Za-z0-9_]+\s*,\s*'
-    r'templateId\s*:\s*"(?P<tid>[^"]+)"\s*,\s*'
-    r'slot\s*:\s*"(?P<slot>[^"]+)"\s*\}\s*,?\s*$'
-)
-
-
-def parse_manifest(path: str) -> dict[str, dict[str, str]]:
-    """Parse manifest.ts and return {compositionId: {templateId, slot}}."""
-    if not os.path.isfile(path):
-        raise FileNotFoundError(f"manifest.ts not found at {path}")
-
-    with open(path, "r", encoding="utf-8") as f:
-        text = f.read()
-
-    start_marker = "// MANIFEST_ENTRIES:START"
-    end_marker = "// MANIFEST_ENTRIES:END"
-    start = text.find(start_marker)
-    end = text.find(end_marker)
-    if start == -1 or end == -1 or end < start:
-        raise ValueError(
-            f"manifest.ts is missing {start_marker} / {end_marker} markers"
-        )
-
-    block = text[start:end]
-    entries: dict[str, dict[str, str]] = {}
-    for line in block.splitlines():
-        m = _MANIFEST_ROW_RE.match(line)
-        if not m:
-            continue
-        entries[m.group("cid")] = {
-            "templateId": m.group("tid"),
-            "slot": m.group("slot"),
-        }
-
-    if not entries:
-        raise ValueError(
-            f"No manifest entries parsed from {path}. Did the format change?"
-        )
-    return entries
-
-
-def _iter_composition_ids(node: object) -> Iterator[str]:
-    """Walk an arbitrary JSON tree and yield every `compositionId` value."""
-    if isinstance(node, dict):
-        cid = node.get("compositionId")
-        if isinstance(cid, str):
-            yield cid
-        for v in node.values():
-            yield from _iter_composition_ids(v)
-    elif isinstance(node, list):
-        for v in node:
-            yield from _iter_composition_ids(v)
-
-
-def collect_template_references(registry_path: str) -> list[dict[str, str]]:
-    """Return a list of {templateId, compositionId, file} for every reference in the registry."""
-    refs: list[dict[str, str]] = []
-    if not os.path.isfile(registry_path):
-        print(f"WARN: registry.json not found at {registry_path}", file=sys.stderr)
-        return refs
-
-    with open(registry_path, "r", encoding="utf-8") as f:
-        data = json.load(f)
-
-    for tpl in data.get("templates", []):
-        tid = tpl.get("templateId")
-        if not tid:
-            continue
-        for cid in _iter_composition_ids(tpl):
-            refs.append({"templateId": tid, "compositionId": cid, "file": registry_path})
-    return refs
-
-
-def main() -> int:
-    try:
-        manifest = parse_manifest(_MANIFEST_PATH)
-    except (FileNotFoundError, ValueError) as e:
-        print(f"FAIL: {e}", file=sys.stderr)
-        return 2
-
-    refs = collect_template_references(_REGISTRY_PATH)
-
-    errors: list[str] = []
-    seen: set[str] = set()
-
-    for ref in refs:
-        cid = ref["compositionId"]
-        tid = ref["templateId"]
-        rel = os.path.relpath(ref["file"], monorepo_root())
-        seen.add(cid)
-
-        entry = manifest.get(cid)
-        if entry is None:
-            errors.append(
-                f"{rel}: compositionId '{cid}' is referenced but not in manifest.ts"
-            )
-            continue
-        if entry["templateId"] != tid:
-            errors.append(
-                f"{rel}: compositionId '{cid}' is registered under templateId "
-                f"'{entry['templateId']}' in manifest.ts, but template.json declares "
-                f"templateId '{tid}'"
-            )
-
-    # Warn (non-fatal) about manifest entries never referenced by any template.
-    unused = sorted(set(manifest.keys()) - seen)
-    for cid in unused:
-        print(
-            f"WARN: manifest.ts entry '{cid}' is not referenced by any "
-            f"template.json (templateId={manifest[cid]['templateId']})",
-            file=sys.stderr,
-        )
-
-    # 命名空间唯一性说明：compositionId 是否全库唯一，由 template-library 的
-    # generateManifest 在生成 manifest.ts 时保障（跨模板撞名直接抛
-    # DuplicateCompositionIdError、CI 失败）。manifest.ts 因此按构造即唯一，
-    # 本脚本读取的已是去重结果，无需再校验唯一性。
-    #
-    # （已移除早期 P1.1 的 `<templateId>/` 前缀 warning：权威 schema 的
-    # compositionId pattern 为 PascalCase `^[A-Z][A-Za-z0-9]*$`，本就禁止 `/`，
-    # 前缀建议与 schema 矛盾且非必需——唯一性已由上游硬保障。）
-
-    if errors:
-        print("FAIL: contract check found inconsistencies:", file=sys.stderr)
-        for e in errors:
-            print(f"  - {e}", file=sys.stderr)
-        return 1
-
-    print(
-        f"OK: {len(refs)} compositionId references across "
-        f"{len({r['templateId'] for r in refs})} templates match manifest.ts "
-        f"({len(manifest)} entries)."
-    )
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/skills/template-registry/scripts/sync_registry.py

@@ -1,44 +0,0 @@
-#!/usr/bin/env python3
-"""Write a local registry-cache.json from @ab-templates/metadata.
-
-Usage:
-    python3 scripts/sync_registry.py                    # write cache
-    python3 scripts/sync_registry.py --registry <path>  # use custom registry source
-
-The cache is a lightweight summary for LLM prompts and offline use.
-The authoritative source is template-library/packages/metadata/registry.json.
-"""
-from __future__ import annotations
-
-import argparse
-import sys
-import os
-
-# Make video_dsl.runtime importable regardless of CWD.
-_SKILL_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
-sys.path.insert(0, _SKILL_DIR)
-
-from video_dsl.runtime.template_binder import sync_registry  # noqa: E402
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    parser.add_argument(
-        "--registry",
-        default=None,
-        help="Path to @ab-templates/metadata registry.json (auto-detected if omitted)",
-    )
-    parser.add_argument(
-        "--output",
-        default=None,
-        help="Output path for the cache file (default: video_dsl/registry-cache.json)",
-    )
-    args = parser.parse_args()
-
-    out = sync_registry(output_path=args.output, registry_path=args.registry)
-    print(f"wrote {out}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/skills/template-registry/scripts/template_paths.py

@@ -1,72 +0,0 @@
-"""Centralized monorepo path resolution for template-library artifacts.
-
-Why this module exists
-----------------------
-Before this file landed, every caller that needed to reach into the
-monorepo's ``template-library/`` from inside ``apps/ab-skill/`` had to count
-``..`` segments by hand. The depth differs per call site:
-
-    skills/template-registry/scripts/registry_loader.py    → 5 × ".."
-    skills/template-registry/scripts/check_contracts.py    → 3 × ".."
-    skills/template-registry/video_dsl/runtime/template_binder → 6 × ".."
-    skills/gen-script/scripts/gen_script.py                → 5 × ".."
-    skills/render-video/scripts/render_video.py            → 4 × ".."
-
-Five copies, five chances for an off-by-one bug, and any future directory
-move silently breaks one site without touching the others. This module
-computes the monorepo root **once** from its own location and exposes
-helpers so callers no longer count.
-
-All sibling skills (including the ``list_templates.py`` CLI entry, via
-``registry_loader``) go through these helpers, so the monorepo-root
-computation lives in exactly one place.
-"""
-from __future__ import annotations
-
-import os
-from typing import Optional
-
-__all__ = ["monorepo_root", "monorepo_registry_path", "monorepo_template_src_dir"]
-
-# This file lives at:
-#   <repo>/apps/ab-skill/skills/template-registry/scripts/template_paths.py
-# So the monorepo root is 5 levels up.
-_HERE = os.path.dirname(os.path.abspath(__file__))
-_REPO_ROOT = os.path.normpath(os.path.join(_HERE, "..", "..", "..", "..", ".."))
-
-
-def monorepo_root() -> str:
-    """Absolute path to the ab-platform monorepo root.
-
-    Always returns a string; the caller is responsible for checking
-    ``os.path.isdir(...)`` if the root may genuinely be absent (e.g. when
-    the skill is consumed standalone via the npm package).
-    """
-    return _REPO_ROOT
-
-
-def monorepo_registry_path() -> str:
-    """Path to ``template-library/packages/metadata/registry.json``.
-
-    Always returns the computed path even when the file does not exist —
-    so callers can keep their existing ``os.path.exists(...)`` / try-load
-    branches unchanged. Mirrors the historical behavior of the 4 in-tree
-    helpers it replaces.
-    """
-    return os.path.join(_REPO_ROOT, "template-library", "packages", "metadata", "registry.json")
-
-
-def monorepo_template_src_dir(template_id: str) -> Optional[str]:
-    """Locate a template's source directory under ``template-library``.
-
-    Returns the absolute path **only when the directory exists**; returns
-    ``None`` for the standalone / npm-consumer case where there is no
-    monorepo to reach into. Matches ``gen_script._locate_template_dir``'s
-    historical contract (callers test the result for None).
-    """
-    if not template_id:
-        return None
-    tpl_dir = os.path.join(
-        _REPO_ROOT, "template-library", "packages", "templates", "src", template_id
-    )
-    return tpl_dir if os.path.isdir(tpl_dir) else None