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

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

@@ -81,6 +81,10 @@ FLICKER_ISO = 1.5       # 孤立性比值：当前帧异常度 >= 1.5 x 前后
 # "回到原位"闸门：|F[t+1]-F[t-1]| 必须小于 1.6 x 中间帧偏离量。
 # 单帧闪烁 ≈ 0（前后几乎相同）；加速运动 ≈ 2 以上（前后差更多）→ 排除。
 FLICKER_RETURN_RATIO = 1.6
+# 符号一致度下限：块内像素"同向"变化的比例。真闪白/闪黑整块同向（0.75–1.0）；
+# 文字入场 / 母题动画 / 镜头缓推是有增有减的纹理变化（实测 0.42）。
+# 低于此值不判 error（降级 warning 供人复核）——v1.0.2 修掉零拷贝首片的 G9 误杀。
+FLICKER_AGREE_MIN = 0.60
 # 与已登记视觉事件（闪白/震屏/冲击环）重合多久内视为"设计好的重击"，不计 error
 FLICKER_EXPLAIN_WIN = 0.2
 # 转化为"可解释设计事件"的 event.kind（小写匹配；cues.json §4.2 的 events 由页面导出）
@@ -366,11 +370,16 @@ def sample_frames(path, w=160, h=90, from_s=0.0, to_s=None) -> np.ndarray:
     return np.stack(frames, axis=0)
 
 
-def _block_max(diff, block) -> tuple[float, tuple[int, int, int, int], float]:
-    """把 (h,w) 差异图按 block×block 分块取均值最大，返回 (最大均值, bbox, 该块中值)。
+def _block_max(diff, block, signed=None) -> tuple:
+    """把 (h,w) 差异图按 block×block 分块取均值最大，返回 (最大均值, bbox, 该块中值, 符号一致度)。
 
     中值是复核线索：整块一起变亮（真单帧事件）时中值也高；只有小块元素在动时
     均值被少数像素拉高、中值仍接近 0（见 references/frame-qa.md 的 16.933 s 案例）。
+
+    v1.0.2 加符号一致度（signed 传带符号的二阶差分时才算）：整块**同向**变亮/变暗
+    = 真闪白/闪黑；文字逐字入场、母题动画、镜头缓推产生的只是**有增有减**的纹理变化，
+    符号一致度低。实测（v1.0.2 零拷贝首片）：t=5.867s 被误报的块 score 51.5 / median 44.5，
+    但符号一致度只有 0.42；同一位置人为注入 +50 灰闪白后一致度 0.75。
     """
     h, w = diff.shape
     b = max(1, int(block))
@@ -387,7 +396,14 @@ def _block_max(diff, block) -> tuple[float, tuple[int, int, int, int], float]:
     bb = (x0, y0, x1, y1)
     blk = diff[y0:y1, x0:x1]
     med = float(np.median(blk)) if blk.size else 0.0
-    return float(means[r, c]), bb, med
+    agree = None
+    if isinstance(signed, np.ndarray) and signed.shape == diff.shape:
+        sblk = signed[y0:y1, x0:x1].astype(np.float64)
+        if sblk.size:
+            m = float(sblk.mean())
+            # 与"块内平均方向"同向的像素占比：整块同向变亮 ≈ 1.0，纹理/运动互有增减 ≈ 0.5
+            agree = float(np.mean(np.sign(sblk) == np.sign(m))) if m != 0 else 0.0
+    return float(means[r, c]), bb, med, agree
 
 
 def _block_peak(diff, block) -> float:
@@ -434,10 +450,11 @@ def _scan_full(path, w=SAMPLE_W, h=SAMPLE_H, block=FLICKER_BLOCK, fps=None):
         if len(history) > lag:
             history.pop(0)
         if prev2 is not None:
-            diff = np.abs(prev1 - (prev2 + fr) * 0.5) * 255.0
-            s, bb, med = _block_max(diff, block)
+            signed = (prev1 - (prev2 + fr) * 0.5) * 255.0
+            diff = np.abs(signed)
+            s, bb, med, agree = _block_max(diff, block, signed=signed)
             scores.append(float(s))
-            boxes.append((bb, med))
+            boxes.append((bb, med, agree))
             # 同一个块上算"前后两帧彼此差多少"，用于区分闪烁与加速运动
             if bb:
                 x0, y0, x1, y1 = bb
@@ -502,7 +519,9 @@ def _flicker_from_scores(scores, boxes, fps, thresh, returns=None, suppressed=No
             continue
         if s < FLICKER_ISO * max(p, q):
             continue
-        bb, med = boxes[t - 1] if 0 <= t - 1 < len(boxes) else ((0, 0, 0, 0), 0.0)
+        box = boxes[t - 1] if 0 <= t - 1 < len(boxes) else ((0, 0, 0, 0), 0.0, None)
+        bb, med = box[0], box[1]
+        agree = box[2] if len(box) > 2 else None
         r = None
         if returns is not None and t < len(returns):
             r = float(returns[t])
@@ -522,6 +541,7 @@ def _flicker_from_scores(scores, boxes, fps, thresh, returns=None, suppressed=No
                     "bbox": [int(v) for v in bb],
                     "ratio": round(s / max(p, q, 1e-9), 2),
                     "median": round(float(med), 2),
+                    **({"agree": round(float(agree), 2)} if agree is not None else {}),
                     **({"return": round(r, 2)} if r is not None and math.isfinite(r) else {})})
     return out
 
@@ -1079,13 +1099,28 @@ def report(film, *, cues_json=None, expect_duration=None, out_json=None, out_png
         fl["expected"] = any(abs(fl["t"] - te) <= FLICKER_EXPLAIN_WIN for te in explained_times)
 
     errors = []
+    textured = []
     for fl in flicker:
         if fl.get("expected"):
             continue
         bb = fl.get("bbox") or [0, 0, 0, 0]
-        errors.append("单帧闪烁 t=%.3fs score=%.1f（孤立比值 %.2f，块中值 %.2f，异常块 %d,%d–%d,%d，阈值 %.1f）"
-                      % (fl["t"], fl["score"], fl.get("ratio", 0.0), fl.get("median", 0.0),
-                         bb[0], bb[1], bb[2], bb[3], FLICKER_THRESH))
+        msg = ("t=%.3fs score=%.1f（孤立比值 %.2f，块中值 %.2f，异常块 %d,%d–%d,%d，阈值 %.1f）"
+               % (fl["t"], fl["score"], fl.get("ratio", 0.0), fl.get("median", 0.0),
+                  bb[0], bb[1], bb[2], bb[3], FLICKER_THRESH))
+        # v1.0.2：符号一致度 = 块内像素是否**同向**变亮/变暗。
+        # 真闪白/闪黑整块同向（实测 0.75–1.0）；文字逐字入场、母题动画、镜头缓推
+        # 是"有增有减"的纹理变化（实测 0.42）。后者以前会被判成闪烁，让新用户首片
+        # 就 fail 在 G9（零拷贝自测实测：t=5.867s 标题逐字入场被误判）。
+        # 处理：低于阈值不静默放过，降级为 warning 并保留全部数值，交给人工复核。
+        fl["sign_agree"] = fl.get("agree")
+        if fl.get("agree") is not None and float(fl["agree"]) < FLICKER_AGREE_MIN:
+            textured.append(msg + ("，符号一致度 %.2f < %.2f → 判为纹理/动画扰动"
+                                   % (float(fl["agree"]), FLICKER_AGREE_MIN)))
+            continue
+        errors.append("单帧闪烁 " + msg)
+    for msg in textured:
+        warnings.append("疑似非闪烁（块内像素有增有减，像是文字/母题动画）：" + msg
+                        + "；若画面确有单帧闪白，调低 FLICKER_AGREE_MIN 或登记设计事件")
     explained = sum(1 for fl in flicker if fl.get("expected"))
     if explained:
         warnings.append("已排除 %d 处与已登记视觉事件（闪白/震屏/冲击环）重合的单帧闪烁；"

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

@@ -458,7 +458,27 @@ def _looks_legacy(script) -> bool:
 
 
 def _style_plan(script) -> dict:
-    """解析剧本风格计划：优先复用 script["_style"]，否则调 stylekit（纯函数、确定性）。"""
+    """解析剧本风格计划：**design 优先**，其次 script["_style"]，最后 stylekit。
+
+    为什么必须先看 design：v1.0 之后"这一版长什么样"由 work/design.json 决定，
+    而 qavmaf 是**独立进程**——它拿到的 script 里没有 render 塞进去的 _style。
+    早先这里直接调 stylekit，于是 design 路径的片子会被解析成 tech-deep（默认风格），
+    参考帧用一套主题、成片用另一套：实测 VMAF 1.50、同源抽查 MAE=0.0384。
+    这不是"画质劣化"，是**参考帧根本不是同一部片**。
+    """
+    # ① design（与 render._plan_from_design 同一口径）
+    design = script.get("design") if isinstance(script, dict) else None
+    if isinstance(design, dict) and design:
+        import designkit as DK
+        bad = DK.validate_design(design)
+        if bad:
+            raise LookupError("design.json 没过校验，参考帧无法与成片同源：%s" % "；".join(bad[:3]))
+        return DK.design_to_plan(design)
+    # ② 调用方已经解析过（extract_frames 会塞进来）
+    cached = script.get("_style") if isinstance(script, dict) else None
+    if isinstance(cached, dict) and cached:
+        return cached
+    # ③ 老路径：stylekit
     try:
         import stylekit as ST
     except Exception as e:              # noqa: BLE001
@@ -563,10 +583,17 @@ def _prepare_script(script, tl):
     """
     sc = dict(script)                   # 浅拷贝：不改调用方的对象
     sc["_total"] = float(_f(tl.get("total"), 0.0))
-    plan = sc.get("_style")
-    if not isinstance(plan, dict):
+    # design 必须**优先于**缓存的 _style：调用方（render.st_qa）可能已经用一个
+    # 错误的 _style 污染过 script —— 它自己解析时没传 work、读不到 design.json，
+    # 于是 _style 是 stylekit 的 auto 结果。看到 _style 就直接用，等于沿用那个错误。
+    if isinstance(sc.get("design"), dict) and sc["design"]:
         plan = _style_plan(sc)
         sc["_style"] = plan
+    else:
+        plan = sc.get("_style")
+        if not isinstance(plan, dict):
+            plan = _style_plan(sc)
+            sc["_style"] = plan
     legacy = bool((plan or {}).get("legacy"))
     if legacy:
         return sc, None
@@ -577,22 +604,48 @@ def _prepare_script(script, tl):
     return sc, theme
 
 
-def _draw_subtitle_like_render(frame, text, theme, words):
-    """烧字幕，与 render.py 同口径（v0.8 起带 words 词边界折行）。
+def _sub_kw_for(script) -> dict:
+    """从已解析的风格计划里取字幕样式参数（v1.0.2，与 render.py:_sub_kw 同口径）。
+
+    ⚠ 为什么参考帧必须传这些参数（实测的**误杀好片**缺陷）：
+    render.py 的 frames / stills 阶段会传 design 的 visual.subtitle（size/align/
+    plate_alpha/radius/max_lines/family/y）；参考帧不传就永远是 filmkit 的模块
+    默认值（size=46 等）。同一部片（设计 size=52 / radius=14 / plate_alpha=180）
+    实测 VMAF 91.33 —— 被阈值 92 判 fail，而两条路径用同一份参数时 ≥96。
+    门禁误杀好片比漏查更有害，所以这里必须与主渲染路径吃同一份参数。
+
+    实现在 filmkit.subtitle_kwargs（**不复制第二份**：两份迟早漂移）；
+    老版 filmkit 没有这个函数时退回空 dict（= 旧行为，跨版本兼容）。
+    """
+    plan = script.get("_style") if isinstance(script, dict) else None
+    fn = getattr(_K, "subtitle_kwargs", None)
+    if fn is None:                      # 老 filmkit：还没有字幕样式参数
+        return {}
+    try:
+        kw = fn(plan)
+    except Exception:                   # noqa: BLE001 —— 样式解析失败不该挡住整片门禁
+        return {}
+    return kw if isinstance(kw, dict) else {}
+
 
-    ⚠ 参考帧为什么不传 words 是个**会误杀好片**的缺陷（实测）：
+def _draw_subtitle_like_render(frame, text, theme, words, kw=None):
+    """烧字幕，与 render.py 同口径（v0.8 带 words 词边界折行，v1.0.2 带设计字幕样式）。
+
+    ⚠ 参考帧不传 words 也是**会误杀好片**的缺陷（实测）：
     render.py 的 frames / stills 阶段调 draw_subtitle 时总会传 words，
     字幕会按词边界折行（"…整整 / 一句旁白"）；参考帧不传就退回字符折行
     （"…整整一 / 句旁白"）。38 字字幕只差一个断点、约 2% 像素不同，
     但近静态画面的 VMAF 从 99.95 掉到 8.55 —— 门禁会把同源的好片判 fail。
-    老版 filmkit 的 draw_subtitle 没有 words 形参，TypeError 时退回旧调用。
+    kw 是 design 的字幕样式（见 _sub_kw_for）；老版 filmkit 的 draw_subtitle
+    没有 words 形参，TypeError 时退回旧调用（保留）。
     """
+    kw = kw or {}
     if not words:
-        return _K.draw_subtitle(frame, text, theme=theme)
+        return _K.draw_subtitle(frame, text, theme=theme, **kw)
     try:
-        return _K.draw_subtitle(frame, text, theme=theme, words=words)
+        return _K.draw_subtitle(frame, text, theme=theme, words=words, **kw)
     except TypeError:                   # 老 filmkit：没有 words 形参（保持旧行为）
-        return _K.draw_subtitle(frame, text, theme=theme)
+        return _K.draw_subtitle(frame, text, theme=theme, **kw)
 
 
 def _draw_ref_frame(scenes, scenes_mod, script, theme, fi, fps, total):
@@ -625,7 +678,9 @@ def _draw_ref_frame(scenes, scenes_mod, script, theme, fi, fps, total):
             words = fn(scenes, t, hold) if fn is not None else None
         except Exception:               # noqa: BLE001 —— 词表异常不该让参考帧渲不出来
             words = None
-        frame = _draw_subtitle_like_render(frame, text, theme, words)
+        # 字幕样式也必须与主渲染路径同源（v1.0.2；见 _sub_kw_for 的实测说明）
+        frame = _draw_subtitle_like_render(frame, text, theme, words,
+                                           kw=_sub_kw_for(script))
     fade = 1.0
     if t < 0.5:
         fade *= _K.ease_out(t / 0.5)
@@ -1229,6 +1284,17 @@ def draw_frame(scene, t_local, dur, t_global, script, frame):
             fp.write(scenes_src)
         script = {"title": "qavmaf selftest", "lines": [
             {"id": "l01", "text": "一", "sub": "自检"}]}
+        # v1.0.1 起没有内置风格表：合成剧本也必须自带一份**现场生成**的设计，
+        # 否则 _style_plan() 解析不出主题（"不写 style 就走老外观"的兼容路径已移除），
+        # 参考帧无法渲染。这里用 designkit 现场采样（seed 固定 = 可复现）、
+        # design_to_plan 与 render 同一口径，**不引入任何写死主题/模板**。
+        try:
+            import designkit as _DK
+            _design = _DK.sample_designs({"topic": "qavmaf selftest"}, n=1, seed=1)[0]
+            script["_style"] = _DK.design_to_plan(_design)
+        except Exception as e:          # noqa: BLE001 —— 缺 designkit 也要给出可读的 FAIL
+            print("[FAIL] 自检需要 designkit.py 现场生成设计（v1.0.1 无内置风格）：%s" % e)
+            return 1
         scenes = [dict(script["lines"][0], start=0.0, end=n / float(fps),
                        dur=n / float(fps), voice_start=0.0, voice_end=n / float(fps))]
         tl = {"total": n / float(fps), "fps": fps, "frames": n, "scenes": scenes,