dsh-motion 0.4.1 → 0.4.2

package/docs/performance-budget.md

@@ -45,8 +45,8 @@
 
 已完成：
 
-- [x] `motion_frames` 按场景 fps 取帧：各风格 `theme.py` 在模块层设置 `m.config.frame_rate`；
-- [x] post 强制 CFR，并校验成片时长（`tpad + CFR` 修正后复验）；
+- [x] 格式契约：`apply_config()` 只设背景色，不再覆盖分辨率/帧率；`motion_render` 的 `width/height/fps` 与 CLI 的 `-r/--fps` 生效；
+- [x] CFR：post 强制 CFR；所有成片按 `nb_read_frames` 对比期望帧数，少帧时用 `tpad + CFR` 补齐并复验；
 - [x] storyboard 顶部 caption 条加提示，避免误判“裁切”。
 
 明确不做：

package/lib/ops.js

@@ -106,7 +106,7 @@ export async function renderScene(config, args) {
 
   // post/ffmpeg 可能因 tmix/丢帧把时长压短；用 CFR 补齐并校验，避免"30s 变 27.4s"。
   if (summary.durationSec) {
-    const fixed = await ensureDuration(config, summary, fps)
+    const fixed = await ensureCfr(config, summary, fps)
     if (fixed) summary.normalized = true
   }
 
@@ -114,22 +114,25 @@ export async function renderScene(config, args) {
   return summary
 }
 
-/** 成片时长与渲染器报告的时长不一致时，用 tpad + CFR 修正；返回是否修过。 */
-async function ensureDuration(config, summary, fps) {
+/** 成片时长或帧数不对（VFR 少帧）时，用 tpad + CFR 修正；返回是否修过。 */
+async function ensureCfr(config, summary, fps) {
   const expected = Number(summary.durationSec)
   if (!Number.isFinite(expected) || expected <= 0) return false
   const file = summary.output
   const before = await probeOutput(config, file)
-  const delta = expected - before.durationSec
-  if (!Number.isFinite(delta) || Math.abs(delta) <= 0.08) return false
+  const expectedFrames = Math.round(expected * fps)
+  const frameGap = Number.isFinite(before.frames) ? Math.abs(before.frames - expectedFrames) : 0
+  const durationGap = Math.abs(expected - before.durationSec)
+  if (frameGap <= 1 && durationGap <= 0.08) return false
 
+  const delta = expected - before.durationSec
   const tmp = `${file}.cfr.mp4`
   const chain = []
   if (delta > 0.05) chain.push(`tpad=stop_mode=clone:stop_duration=${delta.toFixed(3)}`)
   chain.push(`fps=${fps}`)
   const args = [
     '-y', '-loglevel', 'error', '-i', file,
-    '-vf', chain.join(','), '-fps_mode', 'cfr',
+    '-vf', chain.join(','), '-fps_mode', 'cfr', '-r', String(fps),
     '-c:v', 'libx264', '-crf', '18', '-pix_fmt', 'yuv420p', '-an',
   ]
   if (delta < -0.05) args.push('-t', expected.toFixed(3))
@@ -137,8 +140,9 @@ async function ensureDuration(config, summary, fps) {
   await exec(binaryOf(config, 'ffmpeg'), args, { timeout: 900_000, maxBuffer: 8 * 1024 * 1024 })
 
   const after = await probeOutput(config, tmp)
-  if (!Number.isFinite(after.durationSec) || Math.abs(after.durationSec - expected) > 0.12) {
-    throw new Error(`CFR 修正后时长仍不对：期望 ${expected}s，实际 ${after.durationSec}s（${tmp}）`)
+  const afterGap = Number.isFinite(after.frames) ? Math.abs(after.frames - expectedFrames) : 0
+  if (afterGap > 1 || Math.abs(after.durationSec - expected) > 0.05) {
+    throw new Error(`CFR 修正后仍不对：期望 ${expectedFrames} 帧 / ${expected}s，实际 ${after.frames} 帧 / ${after.durationSec}s（${tmp}）`)
   }
   renameSync(tmp, file)
   Object.assign(summary, after)
@@ -348,10 +352,10 @@ export async function probeVideo(config, args) {
 /** 用 ffprobe 重新读成片参数（post 之后帧率、时长、体积都可能与中间产物不同）。 */
 export async function probeOutput(config, file) {
   const { stdout } = await exec(binaryOf(config, 'ffprobe'), [
-    '-v', 'error', '-select_streams', 'v:0',
-    '-show_entries', 'stream=width,height,r_frame_rate:format=duration,size',
+    '-v', 'error', '-count_frames', '-select_streams', 'v:0',
+    '-show_entries', 'stream=width,height,r_frame_rate,avg_frame_rate,nb_read_frames:format=duration,size',
     '-of', 'json', file,
-  ], { timeout: 60_000, maxBuffer: 1024 * 1024 })
+  ], { timeout: 120_000, maxBuffer: 4 * 1024 * 1024 })
   const data = JSON.parse(stdout)
   const stream = data.streams?.[0] ?? {}
   const [num, den = '1'] = String(stream.r_frame_rate ?? '0/1').split('/')
@@ -363,6 +367,10 @@ export async function probeOutput(config, file) {
     width: stream.width ?? null,
     height: stream.height ?? null,
     fps: Number.isFinite(rate) && rate > 0 ? Math.round(rate * 100) / 100 : null,
+    avgFps: Number.isFinite(Number(stream.avg_frame_rate?.split?.('/')[0]))
+      ? Math.round((Number(stream.avg_frame_rate.split('/')[0]) / Number(stream.avg_frame_rate.split('/')[1] ?? 1)) * 100) / 100
+      : null,
+    frames: Number.isFinite(Number(stream.nb_read_frames)) ? Number(stream.nb_read_frames) : null,
     megabytes: Number.isFinite(size) ? Math.round(size / 1e5) / 10 : null,
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-motion",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Code-generated math & science animations for DeepSeek Harness: frames-first preview, Manim clips, formula checks.",
   "license": "MIT",
   "type": "module",

package/styles/3b1b/theme.py

@@ -13,9 +13,6 @@ import manimgx as m
 
 TOKENS = json.loads(Path(__file__).with_name("tokens.json").read_text(encoding="utf-8"))
 
-# inspect 在 import 时读 config.frame_rate；必须放在模块层，不能只在 construct 里。
-m.config.frame_rate = int(TOKENS["motion"]["fps"])
-
 BG = TOKENS["colors"]["bg"]
 TEXT = TOKENS["colors"]["text"]
 LABEL = TOKENS["colors"]["label"]
@@ -30,11 +27,13 @@ AXIS = TOKENS["colors"]["axis"]
 LAYOUT = TOKENS["layout"]
 
 
-def apply_config(width: int = 1920, height: int = 1080, fps: int = 30) -> None:
-    m.config.pixel_width = width
-    m.config.pixel_height = height
-    m.config.frame_rate = fps
-    m.config.background_color = BG
+def apply_config(background: str = BG) -> None:
+    """只设背景色；分辨率/帧率由 CLI（-r / --fps）或调用方决定。
+
+    不要在场景里写死 1920x1080/30：那会覆盖 motion_render 的 width/height/fps，
+    也是 1280x720 崩溃与 --fps 60 静默变 5s 的根因。
+    """
+    m.config.background_color = background
 
 
 def backdrop() -> m.Rectangle:

package/styles/README.md

@@ -18,7 +18,7 @@
 - `STYLE.md` 是**改编**，必须在上游基础上写清楚差异；不复制 demo 代码；
 - 颜色、字体、时间表、音频以 `tokens.json` 为准；版面坐标与组件配方写在 `STYLE.md`；
 - 中文文本不做字符级 `ReplacementTransform` / `Transform`（会出字形碎片）；用 Fade/Write/Indicate，换词用 FadeOut+FadeIn；
-- `theme.py` 必须在**模块 import 时**设置 `m.config.frame_rate`（不能只在 `construct` 里），否则 `manimgx inspect` 会按默认 60fps 取帧，30fps 场景的后半段会报 no frame；
+- **不要在场景/`theme.py` 里写死 1920×1080 / fps**：`apply_config()` 只设背景色；分辨率与帧率交给 `motion_render` 的 `width/height/fps` 或 CLI 的 `-r/--fps`。写死会覆盖 CLI，导致 `-r 1280x720` 崩溃、`--fps 60` 静默变 5s；
 - 路由：`styles/registry.json` 是元数据，`node scripts/route-style.mjs "<题材>"` 打分；点名优先，低置信度/并列先问用户；
 - 新片在自己的项目目录写 `DESIGN.md`，头部 `style: <slug>` + `style_version: 1.0.0`；
 - 参考与示例统一用 HyperFrames 的 [examples](https://hyperframes.heygen.com/examples) / [catalog](https://hyperframes.heygen.com/catalog)，不在仓库里放样片（`showcase/` 只放可复现的演示）。

package/styles/blueprint/theme.py

@@ -15,9 +15,6 @@ import manimgx as m
 
 TOKENS = json.loads(Path(__file__).with_name("tokens.json").read_text(encoding="utf-8"))
 
-# inspect 在 import 时读 config.frame_rate；必须放在模块层，不能只在 construct 里。
-m.config.frame_rate = int(TOKENS["motion"]["fps"])
-
 TABLE = TOKENS["colors"]["table"]
 PAPER = TOKENS["colors"]["paper"]
 PAPER_LIGHT = TOKENS["colors"]["paper_light"]
@@ -27,11 +24,13 @@ STAMP = TOKENS["colors"]["stamp"]
 LAYOUT = TOKENS["layout"]
 
 
-def apply_config(width: int = 1920, height: int = 1080, fps: int = 30) -> None:
-    m.config.pixel_width = width
-    m.config.pixel_height = height
-    m.config.frame_rate = fps
-    m.config.background_color = TABLE
+def apply_config(background: str = TABLE) -> None:
+    """只设背景色；分辨率/帧率由 CLI（-r / --fps）或调用方决定。
+
+    不要在场景里写死 1920x1080/30：那会覆盖 motion_render 的 width/height/fps，
+    也是 1280x720 崩溃与 --fps 60 静默变 5s 的根因。
+    """
+    m.config.background_color = background
 
 
 def backdrop(seed: int = 11) -> m.ImageMobject:

package/styles/dataviz/theme.py

@@ -13,9 +13,6 @@ import manimgx as m
 
 TOKENS = json.loads(Path(__file__).with_name("tokens.json").read_text(encoding="utf-8"))
 
-# inspect 在 import 时读 config.frame_rate；必须放在模块层，不能只在 construct 里。
-m.config.frame_rate = int(TOKENS["motion"]["fps"])
-
 PAPER = TOKENS["colors"]["paper"]
 PAPER_SHADOW = TOKENS["colors"]["paper_shadow"]
 INK = TOKENS["colors"]["ink"]
@@ -28,11 +25,13 @@ MONO = TOKENS["typography"]["mono"]["family"]
 LAYOUT = TOKENS["layout"]
 
 
-def apply_config(width: int = 1920, height: int = 1080, fps: int = 30) -> None:
-    m.config.pixel_width = width
-    m.config.pixel_height = height
-    m.config.frame_rate = fps
-    m.config.background_color = PAPER
+def apply_config(background: str = PAPER) -> None:
+    """只设背景色；分辨率/帧率由 CLI（-r / --fps）或调用方决定。
+
+    不要在场景里写死 1920x1080/30：那会覆盖 motion_render 的 width/height/fps，
+    也是 1280x720 崩溃与 --fps 60 静默变 5s 的根因。
+    """
+    m.config.background_color = background
 
 
 def backdrop() -> m.Rectangle:

package/styles/swiss-motion/theme.py

@@ -13,9 +13,6 @@ import manimgx as m
 
 TOKENS = json.loads(Path(__file__).with_name("tokens.json").read_text(encoding="utf-8"))
 
-# inspect 在 import 时读 config.frame_rate；必须放在模块层，不能只在 construct 里。
-m.config.frame_rate = int(TOKENS["motion"]["fps"])
-
 GROUND = TOKENS["colors"]["ground"]
 PAPER = TOKENS["colors"]["paper"]
 INK = TOKENS["colors"]["ink"]
@@ -27,11 +24,13 @@ MOTION = TOKENS["motion"]
 LAYOUT = TOKENS["layout"]
 
 
-def apply_config(width: int = 1920, height: int = 1080, fps: int = 30) -> None:
-    m.config.pixel_width = width
-    m.config.pixel_height = height
-    m.config.frame_rate = fps
-    m.config.background_color = GROUND
+def apply_config(background: str = GROUND) -> None:
+    """只设背景色；分辨率/帧率由 CLI（-r / --fps）或调用方决定。
+
+    不要在场景里写死 1920x1080/30：那会覆盖 motion_render 的 width/height/fps，
+    也是 1280x720 崩溃与 --fps 60 静默变 5s 的根因。
+    """
+    m.config.background_color = background
 
 
 def backdrop() -> m.Rectangle:

package/styles/whiteboard/theme.py

@@ -15,9 +15,6 @@ import manimgx as m
 
 TOKENS = json.loads(Path(__file__).with_name("tokens.json").read_text(encoding="utf-8"))
 
-# inspect 在 import 时读 config.frame_rate；必须放在模块层，不能只在 construct 里。
-m.config.frame_rate = int(TOKENS["motion"]["fps"])
-
 BOARD = TOKENS["colors"]["board"]
 BOARD_EDGE = TOKENS["colors"]["board_edge"]
 INK = TOKENS["colors"]["ink"]
@@ -28,11 +25,13 @@ GHOST = TOKENS["colors"]["ghost"]
 LAYOUT = TOKENS["layout"]
 
 
-def apply_config(width: int = 1920, height: int = 1080, fps: int = 30) -> None:
-    m.config.pixel_width = width
-    m.config.pixel_height = height
-    m.config.frame_rate = fps
-    m.config.background_color = BOARD
+def apply_config(background: str = BOARD) -> None:
+    """只设背景色；分辨率/帧率由 CLI（-r / --fps）或调用方决定。
+
+    不要在场景里写死 1920x1080/30：那会覆盖 motion_render 的 width/height/fps，
+    也是 1280x720 崩溃与 --fps 60 静默变 5s 的根因。
+    """
+    m.config.background_color = background
 
 
 def backdrop(seed: int = 5) -> m.ImageMobject: