@dsh-gis/dsh-video-studio-skill 0.6.0 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/CHANGELOG.md +951 -0
  2. package/README.md +89 -21
  3. package/THIRD_PARTY_NOTICES.md +1 -0
  4. package/index.js +23 -7
  5. package/package.json +7 -3
  6. package/schemas/film.schema.json +235 -4
  7. package/skills/video-studio/SKILL.md +299 -27
  8. package/skills/video-studio/assets/film.json +7 -14
  9. package/skills/video-studio/assets/golden_frames.json +65 -0
  10. package/skills/video-studio/assets/scenes.py +115 -10
  11. package/skills/video-studio/assets/web/engine.js +81 -3
  12. package/skills/video-studio/assets/web/film.js +249 -101
  13. package/skills/video-studio/assets/web/index.html +9 -2
  14. package/skills/video-studio/assets/web/qa_text.js +36 -8
  15. package/skills/video-studio/references/audio-variation.md +159 -0
  16. package/skills/video-studio/references/audio.md +67 -5
  17. package/skills/video-studio/references/change-impact.md +2 -2
  18. package/skills/video-studio/references/quality-gates.md +25 -3
  19. package/skills/video-studio/references/style-packs.md +7 -3
  20. package/skills/video-studio/references/v08-quality.md +256 -0
  21. package/skills/video-studio/references/web-engine.md +19 -2
  22. package/skills/video-studio/references/word-timeline.md +147 -0
  23. package/skills/video-studio/requirements.txt +16 -1
  24. package/skills/video-studio/scripts/filmcheck.py +202 -12
  25. package/skills/video-studio/scripts/filmkit.py +792 -56
  26. package/skills/video-studio/scripts/gates.py +161 -14
  27. package/skills/video-studio/scripts/preflight.py +774 -0
  28. package/skills/video-studio/scripts/qa_frames.py +154 -23
  29. package/skills/video-studio/scripts/qaasr.py +1563 -0
  30. package/skills/video-studio/scripts/qavmaf.py +1442 -0
  31. package/skills/video-studio/scripts/render.py +1134 -78
  32. package/skills/video-studio/scripts/scorekit.py +305 -76
  33. package/skills/video-studio/scripts/selfcheck.py +576 -2
  34. package/skills/video-studio/scripts/sfxkit.py +262 -44
  35. package/skills/video-studio/scripts/stagewatch.py +159 -36
  36. package/skills/video-studio/scripts/stylekit.py +137 -18
  37. package/skills/video-studio/scripts/voicekit.py +23 -7
  38. package/skills/video-studio/scripts/webengine.py +1186 -85
  39. package/tools/audio_similarity.py +279 -0
  40. package/tools/ci_check.py +310 -59
  41. package/tools/estimate.py +251 -61
  42. package/tools/golden_frames.py +664 -0
  43. package/tools/selftest_noscipy.py +70 -0
@@ -213,6 +213,7 @@ def _probe(path) -> dict:
213
213
  path = str(path)
214
214
  info = {"fps": FPS_FALLBACK, "duration": 0.0, "width": None, "height": None,
215
215
  "has_audio": False, "sample_rate": None, "duration_source": "none"}
216
+ fps_parsed = False # ffprobe 已经给出合法帧率?(拿它判要不要跑 ffmpeg -i 兜底)
216
217
  p = subprocess.run(
217
218
  [_ffprobe(), "-v", "error",
218
219
  "-show_entries",
@@ -247,6 +248,7 @@ def _probe(path) -> dict:
247
248
  fps = _parse_rate(st.get("avg_frame_rate"))
248
249
  if fps and 1.0 <= fps <= 240.0:
249
250
  info["fps"] = float(fps)
251
+ fps_parsed = True
250
252
  if not info["duration"]:
251
253
  try:
252
254
  vd = float(st.get("duration") or 0.0)
@@ -262,7 +264,10 @@ def _probe(path) -> dict:
262
264
  info["sample_rate"] = int(st.get("sample_rate") or 0) or None
263
265
  except Exception: # noqa: BLE001
264
266
  pass
265
- if info["width"] is None or info["fps"] == FPS_FALLBACK or not info["duration"]:
267
+ # 只在 ffprobe 真的没给全信息时才回退到 ffmpeg -i。
268
+ # 旧条件写的是 info["fps"] == FPS_FALLBACK,于是**所有 30 fps 成片**都会白跑一次
269
+ # ffmpeg -i(实测每片多一次进程 + 全文件解析),而 30fps 恰恰是本项目最常见情况。
270
+ if info["width"] is None or not fps_parsed or not info["duration"]:
266
271
  txt = ""
267
272
  try:
268
273
  q = subprocess.run([_ffmpeg(), "-hide_banner", "-i", path], capture_output=True)
@@ -624,6 +629,30 @@ def _event_kind(ev) -> str:
624
629
  return str(ev.get("kind") or ev.get("type") or "").strip().lower()
625
630
 
626
631
 
632
+ def _src_of(obj) -> str:
633
+ """取 cue / event 的来源标记(web / pil / file / …);没写返回空串。"""
634
+ try:
635
+ return str(obj.get("src") or "").strip().lower()
636
+ except AttributeError: # noqa: BLE001 —— 坏条目当"没写"
637
+ return ""
638
+
639
+
640
+ def _src_compatible(cue, ev) -> bool:
641
+ """两个条目能不能做同步配对:只有**双方都明确标了来源且不同**时才认为时间基准不同。
642
+
643
+ v0.7.1 起 render.py 在 engine=web 时把三路 cue 合并(film.json / scenes.py / 页面),
644
+ 其中 scenes.py 的 cue 按 PIL 时间轴、页面事件按页面时间轴——跨基准配对会报假 FAIL
645
+ (实测:cue ui_blip @7.725s 配 页面事件 @9.550s,dt=+1.825s)。
646
+ 没标 src 的条目(手写 events / 老版本 cues.json)一律视作兼容,保持向后兼容。
647
+ """
648
+ cs, es = _src_of(cue), _src_of(ev)
649
+ return not (cs and es and cs != es)
650
+
651
+
652
+ def _compatible_events(cue, events) -> list:
653
+ return [e for e in (events or []) if isinstance(e, dict) and _src_compatible(cue, e)]
654
+
655
+
627
656
  def _match_cue(cue, events, tol) -> tuple[dict | None, float | None, str]:
628
657
  """给一个 cue 找对应视觉事件。
629
658
 
@@ -640,6 +669,8 @@ def _match_cue(cue, events, tol) -> tuple[dict | None, float | None, str]:
640
669
  """
641
670
  ct = float(cue.get("t") or 0.0)
642
671
  typ = str(cue.get("type") or "").strip().lower()
672
+ # 只在**同时间基准**的事件里找(跨源配对会报假 FAIL,见 _src_compatible)
673
+ events = _compatible_events(cue, events)
643
674
  same = [e for e in events if _event_kind(e) == typ]
644
675
  if same:
645
676
  ev = min(same, key=lambda e: abs(float(e.get("t") or 0.0) - ct))
@@ -677,6 +708,9 @@ def sync_check(cues, events, tol=SYNC_TOL) -> list[dict]:
677
708
  超过容差就不配对——跨 kind 的"最近事件"不是"预期事件",据此判超差会制造假 FAIL。
678
709
  配不上的 cue 视为"没有对应视觉事件",不判超差(很多音效本来就没有画面事件)。
679
710
  ⚠ 命名约定见 references/frame-qa.md §2.5:events 与 cue 不同名时本检查会静默全过。
711
+ ⚠ 来源(src)过滤(v0.7.1 起):cue 与事件**双方都标了 src 且不同**时不配对——web 引擎
712
+ 三路合并时 PIL 时间轴的 cue 与页面事件基准不同,跨基准配对会报假 FAIL。跳过数量由
713
+ _sync_coverage().src_skipped 计数并在 _load_cues 里转成 warning(不静默)。
680
714
  """
681
715
  out = []
682
716
  cues = [c for c in (cues or []) if isinstance(c, dict)]
@@ -739,23 +773,50 @@ def _cue_anchor(cue) -> float | None:
739
773
  return None
740
774
 
741
775
 
742
- def _sync_coverage(cues, events) -> dict:
743
- """统计"音画同步到底查了多少条":返回 {"cues","anchors","same","judged"}。
744
-
745
- judged = 能给出 dt 判定的 cue 数 = 自带锚点的 cue + 至少存在同名 kind 事件的 cue。
746
- 这是防"静默全过"的量化指标:judged == 0 而 cues > 0 时,sync 为空没有意义。
776
+ def _sync_coverage(cues, events, tol=SYNC_TOL) -> dict:
777
+ """统计"音画同步到底查了多少条":返回 {"cues","anchors","same","judged","src_skipped"}。
778
+
779
+ judged = **按命名约定真的判过 dt** 的 cue 数 = 自带视觉锚点的 cue + 同 kind 且落在
780
+ SYNC_SAME_WIN 搜索窗内、src 同基准的 cue。这是防"静默全过"的量化指标:
781
+ judged == 0 而 cues > 0 时,sync 为空没有意义。
782
+ ⚠ 不能只数"存在同名 kind 的 cue":同名事件若都离 cue 超过 SYNC_SAME_WIN 的搜索窗,
783
+ sync_check 一条也不会判,judged 却会记成"查过了"——require_sync 的"没查"守卫
784
+ 就被这个虚高计数骗过去(实测 cues=[impact@0.5] / events=[impact@100]
785
+ -> judged=1、errors=[],门禁根本没判)。所以这里用与 sync_check 同一个 _match_cue 判。
786
+ ⚠ 也**不**把"异 kind 就近确认"(mode="near")算进 judged:它只在 |dt|<=tol 时认可,
787
+ 是运气不是约定;把它算成"判过"会让命名约定失效的场景显示成"已判 1 条"。
788
+ 另外记 judged_any(含异 kind 佐证)只作诊断,不进报告口径。
789
+ src_skipped = 因为"cue 与事件时间基准不同"(src 不同)而无法参与对照的 cue 数:
790
+ web 引擎三路合并(film.json/scenes.py 用 PIL 时间轴、页面事件用页面时间轴)时会有,
791
+ 这种情况不能算"同步失败",但也不能静默跳过 —— 由 _load_cues 转成 warning 点名。
747
792
  """
748
793
  cues = [c for c in (cues or []) if isinstance(c, dict)]
794
+ events = [e for e in (events or []) if isinstance(e, dict)]
749
795
  anchors = sum(1 for c in cues if _cue_anchor(c) is not None)
750
- ev_kinds = {_event_kind(e) for e in (events or []) if isinstance(e, dict)}
751
796
  same = 0
797
+ judged = 0
798
+ judged_any = 0
799
+ src_skipped = 0
752
800
  for c in cues:
753
801
  if _cue_anchor(c) is not None:
802
+ judged += 1
803
+ judged_any += 1
804
+ continue
805
+ compat = _compatible_events(c, events)
806
+ if not compat and events:
807
+ src_skipped += 1
754
808
  continue
755
- if str(c.get("type") or "").strip().lower() in ev_kinds:
809
+ typ = str(c.get("type") or "").strip().lower()
810
+ if typ in {_event_kind(e) for e in compat}:
756
811
  same += 1
812
+ matched = _match_cue(c, compat, tol)[1] is not None
813
+ if matched:
814
+ judged_any += 1
815
+ # 只有"同名 kind 配对成功"才算按约定判过(锚点上面已单独计入)
816
+ if matched and any(_event_kind(e) == typ for e in compat):
817
+ judged += 1
757
818
  return {"cues": len(cues), "anchors": anchors, "same": same,
758
- "judged": anchors + same}
819
+ "judged": judged, "judged_any": judged_any, "src_skipped": src_skipped}
759
820
 
760
821
 
761
822
  def _load_cues(cues_json):
@@ -789,7 +850,27 @@ def _load_cues(cues_json):
789
850
  info["blockers"].append("cues.json 结构不是对象")
790
851
  return [], [], ["cues.json 结构不是对象,跳过音画同步对照"], info
791
852
  cues = [c for c in (data.get("cues") or []) if isinstance(c, dict)]
792
- events = [e for e in (data.get("events") or []) if isinstance(e, dict)]
853
+ raw_events = [e for e in (data.get("events") or []) if isinstance(e, dict)]
854
+ # 只认"带有限数值 t"的事件:sync_check 内部本来就这么过滤(e.get("t") is not None),
855
+ # 但 _sync_coverage / 命名约定守卫以前拿的是**未过滤**的列表 —— 于是 events 里只要有
856
+ # {"kind": "impact"} 这种缺 t 的条目,judged 就会被算成 1,命名约定守卫也被骗过,
857
+ # 结果是"门禁看起来在查、实际一条都没判"且不报警(实测:cues=1/events=[{kind:impact}]
858
+ # -> coverage judged=1,report errors=[] warnings=[])。
859
+ events = []
860
+ dropped_t = 0
861
+ for e in raw_events:
862
+ t = e.get("t")
863
+ try:
864
+ tv = float(t)
865
+ except (TypeError, ValueError):
866
+ dropped_t += 1
867
+ continue
868
+ if not math.isfinite(tv):
869
+ dropped_t += 1
870
+ continue
871
+ ev = dict(e)
872
+ ev["t"] = tv
873
+ events.append(ev)
793
874
  bad_anchor = []
794
875
  for c in cues:
795
876
  for k in CUE_ANCHOR_KEYS:
@@ -800,8 +881,19 @@ def _load_cues(cues_json):
800
881
  else:
801
882
  c["_anchor_t"] = a
802
883
  break
884
+ if dropped_t:
885
+ warns.append("cues.json 有 %d 个 event 缺数值 t(秒),已忽略;"
886
+ "音画同步只看得到带时间的视觉事件" % dropped_t)
803
887
  cov = _sync_coverage(cues, events)
804
888
  info.update(cov)
889
+ if cov.get("src_skipped"):
890
+ msg = ("有 %d 条 cue 因时间基准不同未参与音画同步对照(cue 与事件的 src 不是同一来源):"
891
+ "web 引擎会把 film.json / scenes.py / 页面 cue 三路合并,其中 scenes.py 的 cue 按 "
892
+ "PIL 时间轴、页面事件按页面时间轴 —— 跨基准配对会报假 FAIL,所以跳过并在这里计数。"
893
+ "要让这些 cue 也参与对照,给 cue 写数值 visual_at(见 references/frame-qa.md §2.5)。"
894
+ % cov["src_skipped"])
895
+ warns.append(msg)
896
+ info.setdefault("notes", []).append(msg)
805
897
  if bad_anchor:
806
898
  warns.append("有 %d 条 cue 的 %s 不是数值秒,已忽略(只认数字,如 12.42):%s"
807
899
  % (len(bad_anchor), "/".join(CUE_ANCHOR_KEYS),
@@ -819,18 +911,40 @@ def _load_cues(cues_json):
819
911
  warns.append(msg)
820
912
  info["blockers"].append(msg)
821
913
  elif cues and events:
822
- # 门禁静默失效的最后一道保险:同 kind 配对要求 events.kind == cue.type。
823
- # 若一个都对不上,sync_check 会"零超差"通过——看起来干净,其实一条都没在查。
914
+ # 门禁静默失效的最后两道保险,分别覆盖两种"零超差但一条没查":
915
+ # ① 命名约定失效:cue.type 与任何事件的 kind 都不同名(cov["same"] == 0);
916
+ # ② 同名事件全落在 SYNC_SAME_WIN 搜索窗之外,一条 dt 都算不出来(cov["judged"] == 0)。
917
+ # 两者都会让 sync_check 返回空列表——看起来干净,其实一条都没在查。
918
+ # 判据用 cov["judged"](按约定真的配对成功)而不是 cov["same"](只是同名)。
824
919
  cue_types = {str(c.get("type") or "").strip().lower() for c in cues}
825
920
  ev_kinds = {_event_kind(e) for e in events}
826
- paired = cue_types & ev_kinds
827
- if not paired and cov["anchors"] == 0:
828
- msg = ("音画同步检查可能没生效:%d 个 cue 的 type 与 %d 个事件的 kind 没有任何同名项"
829
- "(同 kind 配对要求 events.kind == cue 的配方名)。"
921
+ if cov["same"] == 0 and cov["anchors"] == 0:
922
+ # 命名约定失效:cue.type 与任何事件的 kind 都不同名。这时 sync_check 可能靠
923
+ # 异 kind 的"就近确认"蒙到几条(dt 恰好在容差内),但**没有任何一条是照约定
924
+ # 配出来的**——对齐了是巧合,错位了也不会报。所以这条与 judged 无关,永远报。
925
+ msg = ("音画同步检查可能没生效:%d 个 cue 的 type 与 %d 个事件的 kind 没有任何可配对的同名项"
926
+ "(同 kind 配对要求 events.kind == cue 的配方名,且双方 src 需属同一时间基准)。"
830
927
  "sync 为空不代表同步正确——请按 references/frame-qa.md §2.5 的命名约定登记事件,"
831
928
  "或把某个 cue 故意改错 0.3 s 重跑做反证。" % (len(cue_types), len(ev_kinds)))
832
929
  warns.append(msg)
833
930
  info["blockers"].append(msg)
931
+ elif cov["judged"] == 0 and cov.get("judged_any", 0) == 0:
932
+ # 同名 kind 有,但一条 dt 都算不出来:事件全落在 SYNC_SAME_WIN 搜索窗之外,
933
+ # 或全被 src 过滤掉了。sync_check 同样"零超差"通过——必须让人看见。
934
+ msg = ("音画同步检查可能没生效:%d 条 cue 里没有一条能判定 dt"
935
+ "(同名事件都不在 %.1f s 搜索窗内,或 src 时间基准不同)。"
936
+ "sync 为空不代表同步正确——请核对 events 的时间基准与时刻,"
937
+ "或给 cue 写数值 visual_at。" % (len(cues), SYNC_SAME_WIN))
938
+ warns.append(msg)
939
+ info["blockers"].append(msg)
940
+ else:
941
+ # 「有 cues.json 但里面既没有 cues 也没有 events」:文件解析成功、对照却无从做起。
942
+ # 不记 blocker 的话 require_sync 也拦不住:report() 里把"没查"升级成 error 的条件
943
+ # 要求 cues 非空,而这里 cues 为空 —— 于是空 cues.json 会静默通过整道同步门禁。
944
+ msg = ("cues.json 里既没有 cues 也没有 events:音画同步对照没有执行"
945
+ "(文件是空对象、只写了 version 字段?按 §4.2 补 cues / events)")
946
+ warns.append(msg)
947
+ info["blockers"].append(msg)
834
948
  return cues, events, warns, info
835
949
 
836
950
 
@@ -1010,6 +1124,11 @@ def report(film, *, cues_json=None, expect_duration=None, out_json=None, out_png
1010
1124
  exp = float(expect_duration)
1011
1125
  except Exception: # noqa: BLE001
1012
1126
  exp = None
1127
+ if exp is not None and not math.isfinite(exp):
1128
+ # nan 会让 abs(duration - nan) > 0.5 恒为 False —— 也就是"传了预期时长,校验静默失效"。
1129
+ # 这属于调用方写错,不当作通过:记 warning 说明这次没查,别让它假扮成 PASS。
1130
+ warnings.append("expect_duration 不是有限数字(%r),本次不做预期时长校验" % (expect_duration,))
1131
+ exp = None
1013
1132
  if exp is not None and abs(duration - exp) > 0.5:
1014
1133
  errors.append("时长 %.3fs 与预期 %.3fs 不符(差 %+.3fs,容差 ±0.5s)"
1015
1134
  % (duration, exp, duration - exp))
@@ -1026,7 +1145,10 @@ def report(film, *, cues_json=None, expect_duration=None, out_json=None, out_png
1026
1145
  warnings.extend(_static_warnings(drift, fps, blacks=blacks))
1027
1146
 
1028
1147
  rep = {"flicker": flicker, "black_windows": blacks, "luma": luma, "loudness": loud,
1029
- "sync": sync, "errors": errors, "warnings": warnings}
1148
+ "sync": sync, "errors": errors, "warnings": warnings,
1149
+ # sync_info:同步门禁到底查了多少(render.py:1172 一直在读 deep["sync_info"]["judged"],
1150
+ # 但 report() 以前从来不写这个键 —— 所以 QC 报告的 G9 永远显示"同步未判")。
1151
+ "sync_info": dict(sync_info)}
1030
1152
  if out_json:
1031
1153
  _write_json(rep, out_json)
1032
1154
  if out_png:
@@ -1302,9 +1424,12 @@ def _print_summary(rep, film, out_json=None, out_png=None):
1302
1424
  print(" 成片:", film)
1303
1425
  n_sup = sum(1 for w in (rep.get("warnings") or []) if "高分异常被判为运动" in str(w))
1304
1426
  n_static = sum(1 for w in (rep.get("warnings") or []) if "画面长时间静止" in str(w))
1305
- print(" 闪烁 %d(其中与已登记视觉事件重合 %d) / 空窗 %d / 同步超差 %d%s%s"
1427
+ si = rep.get("sync_info") or {}
1428
+ n_src = int(si.get("src_skipped") or 0)
1429
+ print(" 闪烁 %d(其中与已登记视觉事件重合 %d) / 空窗 %d / 同步超差 %d%s%s%s"
1306
1430
  % (len(fl), explained, len(rep.get("black_windows") or []),
1307
1431
  len(rep.get("sync") or []),
1432
+ (" / 跨基准未对照 %d" % n_src) if n_src else "",
1308
1433
  (" / 静止段 %d" % n_static) if n_static else "",
1309
1434
  (" / 高分异常待复核 %d" % n_sup) if n_sup else ""))
1310
1435
  print(" 亮度采样 %d 点 / 响度采样 %d 点"
@@ -1729,8 +1854,13 @@ def selftest() -> int:
1729
1854
  out_json=out_json, out_png=out_png)
1730
1855
  keys = {"flicker", "black_windows", "luma", "loudness", "sync",
1731
1856
  "errors", "warnings"}
1732
- if set(rep) != keys:
1733
- return False, "顶层字段 %s 不符 §4.5" % sorted(rep)
1857
+ # sync_info 是 v0.7.2 的**增量**字段(render.py 的 G9 从 deep["sync_info"]["judged"]
1858
+ # 读"同步到底判了几条",以前 report() 不写它 -> QC 报告永远显示"同步未判")。
1859
+ # 契约 §4.5 的 7 个键必须齐全,允许额外的只读统计键。
1860
+ if not keys.issubset(set(rep)):
1861
+ return False, "顶层字段 %s 缺 §4.5 键" % sorted(keys - set(rep))
1862
+ if not isinstance(rep.get("sync_info"), dict):
1863
+ return False, "sync_info 缺失或不是 dict:%r" % (rep.get("sync_info"),)
1734
1864
  if len(rep["flicker"]) != 1 or rep["flicker"][0].get("expected") is not False:
1735
1865
  return False, "flicker=%s" % (rep["flicker"],)
1736
1866
  if len(rep["black_windows"]) != 1:
@@ -1776,9 +1906,10 @@ def selftest() -> int:
1776
1906
  return False, "deep.png 缺失或过小"
1777
1907
  with open(out_json, encoding="utf-8") as fp:
1778
1908
  data = json.load(fp)
1779
- if set(data) != {"flicker", "black_windows", "luma", "loudness", "sync",
1780
- "errors", "warnings"}:
1781
- return False, "JSON 字段不符"
1909
+ need = {"flicker", "black_windows", "luma", "loudness", "sync",
1910
+ "errors", "warnings"}
1911
+ if not need.issubset(set(data)):
1912
+ return False, "JSON 字段不符(缺 %s)" % sorted(need - set(data))
1782
1913
  img = Image.open(out_png)
1783
1914
  img.load()
1784
1915
  if img.width < 1000 or img.height < 600: