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

package/skills/video-studio/scripts/filmcheck.py

@@ -42,6 +42,17 @@ HERE = Path(__file__).resolve().parent
 # ============================================================================
 
 KINDS = ("hook", "body", "quote", "outro", "emphasis", "calm")   # 也是 voicekit 的语气 id
+
+# 视觉场景类型（v0.9）：决定"这段画面长成什么构图"，与叙事 kind **正交**——
+#   kind 管声线/语气/配乐能量（voicekit / scorekit 读它）；
+#   type 只管构图（assets/scenes.py 的 _DRAWERS 读它）。
+# 所以**不新增 kind 值**：hero/stat/... 不是语气，硬塞进 KINDS 会撞 voicekit 的 tone id
+# （TONE_IDS 与 KINDS 是同一组 6 个）。缺省（不写 lines[].type）= 由 grammar.py 按内容推导。
+SCENE_TYPES = ("hero", "statement", "list", "stat", "compare", "process",
+               "quote", "chapter", "chart", "outro")
+# 与 assets/scenes.py 的 _DRAWERS 键对齐，改一边必须改另一边。
+# （grammar.SCENE_TYPES 是同一组 10 个值，但那份顺序用于"平手取位"；这里只做成员校验，
+#  本元组的顺序只影响报错信息里的枚举列举，不影响判定。三处不要再各写一份新名单。）
 PRESETS = ("ultrafast", "superfast", "veryfast", "faster", "fast",
            "medium", "slow", "slower", "veryslow")
 MUSIC_MODES = ("score", "bed", "file", "off")
@@ -200,6 +211,59 @@ LINE_ITEM_SPEC = {
     },
 }
 
+# ---- v0.9 视觉场景字段的嵌套结构（写法照抄 LINE_ITEM_SPEC）----
+# 这些对象的键由 scenes.py 的 10 个绘制器读：拼错就是"写了不生效"，所以**不**用
+# open=True（那是留给 sfx 配方参数那种真·透传的）。每层列全 props，才能把拼错报成
+# unknown_key（WARN + "是不是想写 X"），把类型写错报成 ERROR。
+# required 与 schema 表里的问号标记一致：必填 = 绘制器没有它就没法画。
+LINE_STAT_SPEC = {                   # type=stat 的数字卡
+    "t": "dict", "required": ["value"],
+    "props": {
+        # 数字或字符串（"92"、">3x"、"1/2" 这类写法只能当字符串）
+        "value": {"t": ("num", "str"), "nonempty": True},
+        "unit": {"t": "str"},
+        "label": {"t": "str"},
+        "note": {"t": "str"},
+    },
+}
+
+LINE_SERIES_SPEC = {                 # type=chart 的数据条
+    "t": "dict", "required": ["label", "value"],
+    "props": {
+        "label": {"t": "str", "nonempty": True},
+        "value": {"t": ("num", "str"), "nonempty": True},
+        "unit": {"t": "str"},
+    },
+}
+
+LINE_STEP_SPEC = {                   # type=process 的流程节点
+    "t": "dict", "required": ["label"],
+    "props": {
+        "label": {"t": "str", "nonempty": True},
+        "note": {"t": "str"},
+    },
+}
+
+# 对比卡的一侧：items 每项可以写字符串，也可以写 {text}（短条目直接写字符串更省事，两种都认）
+LINE_SIDE_SPEC = {
+    "t": "dict",
+    "props": {
+        "head": {"t": "str"},
+        "items": {"t": "list", "item": {
+            "t": ("str", "dict"), "required": ["text"],
+            "props": {"text": {"t": "str", "nonempty": True}},
+        }},
+    },
+}
+
+LINE_SIDES_SPEC = {                  # type=compare 的左右对比（left/right 都可省略）
+    "t": "dict",
+    "props": {
+        "left": LINE_SIDE_SPEC,
+        "right": LINE_SIDE_SPEC,
+    },
+}
+
 LINE_SPEC = {
     "t": "dict", "required": ["text"],
     "props": {
@@ -218,6 +282,16 @@ LINE_SPEC = {
         "persona": {"t": "str"},
         "tone": {"t": "str", "enum": KINDS},
         "voice": {"t": "str"},
+        # ---- v0.9 视觉场景字段（7 个全可选）----
+        # type 缺省由 grammar.py 按内容推导；其余字段是给绘制器的原料，不写就不画。
+        # 注意这些字段与 kind **正交**，不是新 kind：kind 仍只有上面 6 个（voicekit 的语气 id）。
+        "type": {"t": "str", "enum": SCENE_TYPES},
+        "quote": {"t": "str"},
+        "by": {"t": "str"},
+        "stats": {"t": "list", "item": LINE_STAT_SPEC},
+        "series": {"t": "list", "item": LINE_SERIES_SPEC},
+        "steps": {"t": "list", "item": LINE_STEP_SPEC},
+        "sides": LINE_SIDES_SPEC,
     },
 }
 
@@ -315,6 +389,46 @@ SCRIPT_SPEC = {
         "web": {"t": "dict", "props": {
             "entry": {"t": "str"},
             "chunk_s": {"t": "num", "min": 0.0}}},
+        # ---- v0.8 ----
+        # 词级时间戳开关（字幕按词折行 / cue 词锚点 / G10 门禁都依赖它）
+        "words": {"t": "bool"},
+        # TTS 后端选择（v0.8 接口化；默认 edge，其它后端需先 register_tts_backend）
+        "tts": {"t": "dict", "props": {
+            "backend": {"t": "str"},
+            "voice": {"t": ("str", "dict")}}},
+        # 画幅与帧率：只允许 16:9 横屏 + 下采样输出（见 filmkit.video_plan 的取舍说明）
+        "video": {"t": "dict", "props": {
+            "width": {"t": "int", "min": 2},
+            "height": {"t": "int", "min": 2},
+            "out_width": {"t": "int", "min": 2},
+            "out_height": {"t": "int", "min": 2},
+            "fps": {"t": "int", "min": 1, "max": 120}}},
+        # 质检门禁参数（全片 VMAF/SSIM 阻断 + ASR 回读）
+        "qa": {"t": "dict", "props": {
+            "vmaf": {"t": "dict", "props": {
+                # enabled / require_vmaf 是 v0.8 起草时留下的**惰性键**：schema 与这里都认，
+                # 但 render.py / qavmaf.py 全仓没有读取点——写了它门禁照跑，用户以为自己关掉了。
+                # 真正生效的是 mode=off（或命令行 --vmaf off）。这里标 inert 让 filmcheck 报 WARN，
+                # 因为本项目的立场是"写对了却不生效"比"报未知键"更坏。
+                "enabled": {"t": "bool", "inert": "写它不生效；要跳过 G11 请写 qa.vmaf.mode=\"off\"（或 --vmaf off）"},
+                "mode": {"t": "str", "enum": ("full", "sample", "off")},
+                "pass": {"t": "num", "min": 0.0},
+                "warn": {"t": "num", "min": 0.0},
+                # v0.8.1：键名对齐 schemas/film.schema.json 与 qavmaf.report(sample_step=...)。
+                # 这里以前写的是 sample_s —— 全仓没有任何消费者（render 不读、qavmaf 只认
+                # sample_step），于是"写对了却完全没生效"，而 schema 里合法写完还会被本脚本
+                # 报成未知键。别再兼容 sample_s：它从来没生效过，留着只会让人以为能用。
+                "sample_step": {"t": "int", "min": 1}}},
+            "ssim": {"t": "dict", "props": {
+                "enabled": {"t": "bool", "inert": "写它不生效；SSIM 本来就只是诊断项（不单独阻断）"},
+                "pass": {"t": "num", "min": 0.0, "max": 1.0},
+                "warn": {"t": "num", "min": 0.0, "max": 1.0}}},
+            "asr": {"t": "dict", "props": {
+                "enabled": {"t": "bool"},
+                "model": {"t": "str"},
+                "recall_pass": {"t": "num", "min": 0.0, "max": 1.0},
+                "recall_warn": {"t": "num", "min": 0.0, "max": 1.0}}},
+            "require_vmaf": {"t": "bool", "inert": "写它不生效；要强制 G11 别记 skipped 请用 --strict-gates"}}},
     },
 }
 
@@ -350,6 +464,12 @@ def _check(val, rule, path, rep, ctx):
         return
 
     enum = rule.get("enum")
+    # 惰性键：schema 与 filmcheck 都认它，但代码里没有任何读取点。
+    # 报 WARN 而不是 ERROR —— 老剧本里写了它不该变成硬失败；但也绝不能静默通过，
+    # 否则"写对了却不生效"会一路带到交付（本项目历史上最贵的一类缺陷）。
+    if rule.get("inert"):
+        rep.warn(path, "这个键**当前不生效**：%s" % rule["inert"], "inert_key")
+
     if rule.get("enum_dynamic") == "style":
         styles = ctx.get("styles")
         if styles is None:
@@ -453,6 +573,13 @@ def _cue_ref(at):
             float(off)
         except ValueError:
             return "bad", "偏移 %r 不是数字（写 l03+0.35 或 l03-0.2）" % off
+    # v0.8 词锚点：<id>:w<N>[+/-秒]。把 ":wN" 剥掉再做 id 存在性检查，
+    # 否则合法写法会被报成"场景 id 不存在"（假失败比不校验更糟）。
+    if ":w" in sid:
+        head, _sep, tail = sid.partition(":w")
+        if not tail.isdigit() or int(tail) < 1:
+            return "bad", "词锚点要写成 l03:w2（词序号从 1 开始），收到 %r" % sid
+        return "id", head
     return "id", sid
 
 
@@ -485,6 +612,27 @@ def check_cross(script, script_path, rep, ctx):
         ids.append(lid)
     idset = set(ids)
 
+    # ---- lines[].persona / lines[].tone 拼错会静默回落：枚举从 voicekit 单向读取 ----
+    personas, tones = _load_personas()
+    if personas:
+        for i, ln in enumerate(lines):
+            raw = ln.get("persona")
+            if raw in (None, ""):
+                continue
+            name = str(raw).strip()
+            # 原始 edge-tts voice id（zh-CN-YunxiNeural）也允许写在 persona 位
+            if name in personas or ("-" in name and name.endswith("Neural")):
+                continue
+            near = _suggest(name, personas)
+            rep.warn("lines[%d].persona" % i,
+                     "未知 persona %r —— voicekit 会**静默回落**到 kind 默认声线"
+                     "（成片换人，且不会有任何报错）%s。可用：%s"
+                     % (name, ("；是不是想写 %r？" % near) if near else "",
+                        " / ".join(personas[:9])), "unknown_persona")
+    # tone 不在这里查：LINE_SPEC 里已经有 enum（KINDS 与 voicekit.TONE_IDS 是同一组 6 个），
+    # 那是 ERROR 而不是 WARN。这里只补 persona —— 它没有静态枚举，拼错会静默换声线。
+    _ = tones
+
     # ---- lines[].tail 当前不生效（保留字段）：写了会静默无效，必须说出来 ----
     for i, ln in enumerate(lines):
         if _f(ln.get("tail", 0.0)) > 0:
@@ -497,6 +645,55 @@ def check_cross(script, script_path, rep, ctx):
                 "tail_map）。例如 %s: 1.4" % lid),
                 "inert_line_tail")
 
+    # ---- v0.9 场景语法：绘制器的容量上限（超了会被静默截断） ----
+    # 这是本项目最忌讳的一类坑：作者写对了、跑得通、但画面上少了几条，而没有任何提示。
+    # 容量由 assets/scenes.py 的实现决定（stats 取前 3 条、series 前 6 条、steps 前 5 条、
+    # sides 每侧前 3 条），改那边要同步改这里。
+    _CAP = (("stats", 3), ("series", 6), ("steps", 5))
+    for i, ln in enumerate(lines):
+        for fld, cap in _CAP:
+            v = ln.get(fld)
+            if isinstance(v, list) and len(v) > cap:
+                rep.warn("lines[%d].%s" % (i, fld),
+                         "%s 有 %d 条，但 %s 构图只画前 %d 条（其余不会出现在画面上）。"
+                         "要全画请拆成多段，或减到 %d 条以内"
+                         % (fld, len(v), fld, cap, cap), "scene_capacity")
+        sides = ln.get("sides")
+        if isinstance(sides, dict):
+            for side in ("left", "right"):
+                blk = sides.get(side)
+                its = blk.get("items") if isinstance(blk, dict) else None
+                if isinstance(its, list) and len(its) > 3:
+                    rep.warn("lines[%d].sides.%s.items" % (i, side),
+                             "sides.%s 有 %d 条，但左右对比构图每侧只画前 3 条"
+                             % (side, len(its)), "scene_capacity")
+
+    # ---- v0.8 video 块：只支持 16:9 横屏 + 下采样输出 ----
+    # **不要在这里重写一遍规则**：允许列表 / 宽高比 / 上采样拒绝的权威实现在
+    # filmkit.video_plan()。以前这里是第二套手写判据，于是"1600x900"能过 filmcheck
+    # （0 error 0 warning）却在 render 的 st_layout 被 video_plan 拒片——校验器放行、
+    # 渲染器拒收，用户只会觉得门禁在骗人。这里改成直接调用权威实现，只做错误翻译。
+    vv = script.get("video") if isinstance(script.get("video"), dict) else None
+    if vv:
+        try:
+            import filmkit as _K
+        except Exception:                                   # noqa: BLE001
+            _K = None
+        if _K is not None:
+            try:
+                _K.video_plan(script)
+            except ValueError as e:
+                rep.err("video", "%s（filmkit.video_plan 会在渲染时拒片，这里提前拦）" % e,
+                        "bad_video")
+            except Exception as e:                          # noqa: BLE001
+                rep.err("video", "画幅解析失败：%s" % e, "bad_video")
+        else:
+            # filmkit 不可用（拷出来只带了 filmcheck）时退回最小校验：只查 fps 枚举，
+            # 并明说"完整校验需要 filmkit.py"，避免让人以为已经全查过。
+            rep.warn("video", "找不到 filmkit.py：只做了 fps 枚举校验，"
+                              "画幅/上采样规则未校验（完整校验请把 filmkit.py 放在同目录）",
+                     "video_partial")
+
     # ---- sfx.cues[].at 引用的场景 id 必须在 lines 里 ----
     sfx = script.get("sfx") if isinstance(script.get("sfx"), dict) else {}
     cues = sfx.get("cues") if isinstance(sfx.get("cues"), list) else []
@@ -629,6 +826,27 @@ def _load_styles():
         return None
 
 
+def _load_personas():
+    """从 voicekit 单向读取 persona 名与 tone id；拿不到返回 (None, None) 降级成不查。
+
+    为什么要查：voicekit 对写错的 persona/tone 是**静默回落**（reason 里留
+    unknown_persona:xxx，但不报错、不告警），于是"拼错一个声线名"的后果是整片
+    静默换成 kind 默认声线——听感变了，却没有任何一处提示。schema 层只校验 t=str，
+    拦不住；这里补上（规则仍然只有一份：枚举从 voicekit 读，不复制）。
+    """
+    try:
+        if str(HERE) not in sys.path:
+            sys.path.insert(0, str(HERE))
+        import voicekit                                  # noqa: F401  （只读枚举，不复制）
+        personas = list(getattr(voicekit, "PERSONA_IDS", ()) or
+                        getattr(voicekit, "VOICE_PERSONAS", {}).keys())
+        tones = list(getattr(voicekit, "TONE_IDS", ()) or
+                     getattr(voicekit, "VOICE_TONES", {}).keys())
+        return (personas or None), (tones or None)
+    except Exception:                                    # noqa: BLE001
+        return None, None
+
+
 def _classify(data):
     """film = 像剧本；artifact = 其他产物（配乐报告等），跳过；unknown = 判不了。"""
     if not isinstance(data, dict):