dsh-drawai 0.3.4 → 0.4.1

package/lib/motion/qa.js

@@ -0,0 +1,290 @@
+// 帧检：把"片子到底有没有毛病"变成一份带帧号的报告，而不是靠人眼逐帧看。
+//
+// 上游 template 里有一份 final-review.md 讲怎么验片，但没有脚本；这里把它
+// 落成可执行的四类检查（全部基于 ffmpeg，不引入新依赖）：
+//
+//   1. 结构   帧数 / 时长与 timeline 是否一致（硬错误）
+//   2. 黑场   整段纯黑（blackdetect）——通常是某镜没渲染出来
+//   3. 呆帧   画面静止多久（freezedetect）——设计留白还是漏了动画
+//   4. 闪烁   单帧亮度突变又立刻复原（手算 Y 均值序列）
+//   5. 空白   近乎纯色的帧（内容是"忘了放东西"）
+//   6. 越界   四边安全区里出现了墨色（文字压边）
+//   7. 响度   综合响度 / 真峰值 / 静音段（ebur128）
+//
+// 报告落 .out/qa/framecq/report.json，同时给一份能直接读的 markdown 摘要。
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, rmSync } from 'node:fs'
+import { join, resolve as resolvePath } from 'node:path'
+import { runFfmpeg } from './ffmpeg.js'
+import { pixelQuality } from './pixelqa.js'
+import { parseProjectJson } from './json.js'
+
+const DEFAULTS = {
+  freezeSeconds: 1.2,     // 静止超过这个时长就记一笔
+  flashDelta: 18,         // 单帧亮度突变阈值（0–255）
+  emptyDelta: 18,         // 亮度极差小于它就当空白帧
+  emptyFrames: 8,         // 连续多少帧算"一段空白"
+  marginRatio: 0.035,     // 四边安全区宽度（占画面宽/高）
+  marginDark: 170,        // 安全区里出现比这更暗的像素＝内容压边
+  blackPixThreshold: 0.10,
+}
+
+export function qaDir(dir) {
+  return join(dir, '.out', 'qa', 'framecq')
+}
+
+function parseStats(text) {
+  const rows = []
+  let row = null
+  for (const line of text.split(/\r?\n/)) {
+    const head = /^frame:(\d+)\s+pts:\S+\s+pts_time:([\d.]+)/.exec(line)
+    if (head) { row = { frame: Number(head[1]), t: Number(head[2]) }; rows.push(row); continue }
+    const kv = /^lavfi\.signalstats\.(\w+)=(-?[\d.]+)/.exec(line)
+    if (kv && row) row[kv[1].toLowerCase()] = Number(kv[2])
+  }
+  return rows
+}
+
+function runs(flags) {
+  const out = []
+  let start = -1
+  for (let i = 0; i <= flags.length; i += 1) {
+    if (i < flags.length && flags[i]) { if (start < 0) start = i; continue }
+    if (start >= 0) { out.push({ from: start, to: i - 1, length: i - start }); start = -1 }
+  }
+  return out
+}
+
+const second = (value) => Math.round(value * 100) / 100
+
+export async function runFrameQa({ dir, file, timeline, options = {} }) {
+  // 工具层会把没传的参数也写成 undefined 传进来，展开时会把默认值顶掉（freezeSeconds 变 undefined，
+  // 静止判定就整段失效）—— 所以先剔掉 undefined 再合。
+  const given = Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined))
+  const settings = { ...DEFAULTS, ...given }
+  const source = resolvePath(file || join(dir, '.out', 'film.mp4'))
+  if (!existsSync(source)) throw new Error('没有成片可检：先 motion_render start 出一版（' + source + '）')
+  if (!timeline || !Array.isArray(timeline.shots)) throw new Error('缺少 timeline，无法把发现问题归到镜头')
+  const fps = Number(timeline.fps) || 30
+  const work = qaDir(dir)
+  rmSync(work, { recursive: true, force: true })
+  mkdirSync(work, { recursive: true })
+  const call = (args, extra = {}) => runFfmpeg(args, { cwd: work, ...extra })
+  const read = (name) => existsSync(join(work, name)) ? readFileSync(join(work, name), 'utf8') : ''
+
+  // 缩成 480 宽再做统计：统计量对分辨率不敏感，解码却快一个量级。
+  await call(['-i', source, '-an', '-vf', 'scale=480:-2', '-c:v', 'libx264', '-crf', '30', '-preset', 'veryfast', 'scaled.mp4'])
+  await call(['-i', 'scaled.mp4', '-an', '-vf', 'signalstats,metadata=print:file=stats.txt', '-f', 'null', '-'])
+  const stats = parseStats(read('stats.txt'))
+  if (!stats.length) throw new Error('ffmpeg 没有输出逐帧统计，成片可能无法解码')
+
+  const bands = { left: '0:0', right: 'iw-iw*R:0', top: '0:0', bottom: '0:ih-ih*R' }
+  const cropOf = {
+    left: 'crop=iw*R:ih:0:0', right: 'crop=iw*R:ih:iw-iw*R:0',
+    top: 'crop=iw:ih*R:0:0', bottom: 'crop=iw:ih*R:0:ih-ih*R',
+  }
+  const margins = {}
+  for (const band of Object.keys(cropOf)) {
+    const filter = cropOf[band].replace(/R/g, String(settings.marginRatio)) + ',signalstats,metadata=print:file=m-' + band + '.txt'
+    await call(['-i', 'scaled.mp4', '-an', '-vf', filter, '-f', 'null', '-'])
+    margins[band] = parseStats(read('m-' + band + '.txt'))
+  }
+
+  const detected = await call(['-i', source, '-an', '-vf',
+    'blackdetect=d=0.10:pix_th=' + settings.blackPixThreshold + ',freezedetect=n=-55dB:d=' + Math.max(0.3, settings.freezeSeconds) / 2, '-f', 'null', '-'], { allowFail: true })
+    .catch((error) => String(error.stderr || error.message || ''))
+  const blacks = [...detected.matchAll(/black_start:([\d.]+)\s+black_end:([\d.]+)\s+black_duration:([\d.]+)/g)]
+    .map((match) => ({ from: Number(match[1]), to: Number(match[2]), seconds: Number(match[3]) }))
+  // freezedetect 三行分开打：start → duration → end。按出现顺序串起来。
+  const freezes = []
+  let open = null
+  for (const line of detected.split(/\r?\n/)) {
+    let match
+    if ((match = /freeze_start:\s*([\d.]+)/.exec(line))) { open = { from: Number(match[1]) }; freezes.push(open); continue }
+    if (open && (match = /freeze_duration:\s*([\d.]+)/.exec(line))) { open.seconds = Number(match[1]); continue }
+    if (open && (match = /freeze_end:\s*([\d.]+)/.exec(line))) { open.to = Number(match[1]); open = null }
+  }
+
+  const shotAt = (time) => {
+    const frame = Math.round(time * fps)
+    const shot = timeline.shots.find((item) => frame >= item.startFrame && frame < item.startFrame + item.durationFrames)
+    return shot ? shot.id : '(镜头之间)'
+  }
+
+  // 单帧突变：比前后两帧都跳、而前后两帧彼此接近 —— 那是闪，不是运动。
+  const flashes = []
+  for (let i = 1; i < stats.length - 1; i += 1) {
+    const before = stats[i - 1].yavg, here = stats[i].yavg, after = stats[i + 1].yavg
+    if (before === undefined || here === undefined || after === undefined) continue
+    if (Math.abs(here - before) > settings.flashDelta && Math.abs(here - after) > settings.flashDelta && Math.abs(before - after) < 8)
+      flashes.push({ frame: stats[i].frame, t: stats[i].t, yavg: here })
+  }
+
+  // 空白帧：亮度极差极小（既没有字也没有图）。
+  const flat = stats.map((row) => (row.ymax ?? 0) - (row.ymin ?? 0) < settings.emptyDelta)
+  const blanks = runs(flat).filter((run) => run.length >= settings.emptyFrames)
+    .map((run) => ({ from: stats[run.from].t, to: stats[run.to].t, frames: run.length }))
+
+  const marginHits = {}
+  for (const band of Object.keys(margins)) {
+    const rows = margins[band]
+    const dark = rows.map((row) => (row.ymin ?? 255) < settings.marginDark)
+    marginHits[band] = runs(dark).filter((run) => run.length >= 3)
+      .map((run) => ({ from: second(rows[run.from]?.t ?? 0), to: second(rows[run.to]?.t ?? 0), frames: run.length }))
+  }
+
+  // 像素级三项：色带、抗锯齿、字体。走原始灰度字节，所以能看见「这帧糊不糊」。
+  // 关掉它的方式：options.pixels === false（例如只想快速看结构问题）。
+  let pixels = null
+  if (settings.pixels !== false) {
+    try {
+      pixels = await pixelQuality({ source, work, timeline, dir, samples: settings.pixelSamples || 3 })
+    } catch (error) {
+      pixels = { error: error.message || String(error) }
+    }
+  }
+
+  const hasAudio = /Stream #\S+.*: Audio:/.test(await call(['-i', source], { allowFail: true }).catch(() => ''))
+  let audio = { hasAudio, checked: false }
+  if (hasAudio) {
+    const measured = await call(['-i', source, '-vn', '-af', 'ebur128=peak=true,silencedetect=noise=-50dB:d=0.5', '-f', 'null', '-'])
+      .catch((error) => String(error.stderr || ''))
+    const summary = measured.slice(measured.lastIndexOf('Summary:'))
+    const grab = (pattern) => { const found = pattern.exec(summary); return found ? Number(found[1]) : null }
+    audio = {
+      hasAudio, checked: true,
+      integratedLufs: grab(/I:\s*(-?[\d.]+) LUFS/), truePeakDb: grab(/Peak:\s*(-?[\d.]+) dBFS/),
+      silence: [...measured.matchAll(/silence_start:\s*([\d.]+)/g)].map((m) => Number(m[1])).slice(0, 12),
+    }
+  }
+
+  const durationSeconds = stats.length / fps
+  const expectedFrames = Number(timeline.durationInFrames)
+  const checks = []
+  const add = (level, id, message, detail) => checks.push({ level, id, message, ...(detail === undefined ? {} : { detail }) })
+
+  if (Math.abs(stats.length - expectedFrames) > 1)
+    add('fail', 'frames', '成片帧数 ' + stats.length + ' 与时间轴 ' + expectedFrames + ' 不一致（差 ' + (stats.length - expectedFrames) + ' 帧）')
+  else add('pass', 'frames', '帧数 ' + stats.length + ' 与时间轴一致')
+
+  for (const black of blacks) add('fail', 'black', '纯黑段 ' + second(black.from) + 's–' + second(black.to) + 's（' + second(black.seconds) + 's）', shotAt(black.from))
+  if (!blacks.length) add('pass', 'black', '没有纯黑段')
+
+  const longFreezes = freezes.filter((item) => item.seconds >= settings.freezeSeconds)
+  for (const freeze of longFreezes) {
+    const heavy = freeze.seconds >= settings.freezeSeconds * 2
+    add(heavy ? 'warn' : 'info', 'freeze',
+      '画面静止 ' + second(freeze.seconds) + 's（' + second(freeze.from) + 's–' + second(freeze.to ?? freeze.from + freeze.seconds) + 's）'
+      + (heavy ? '' : '，像是设计停留'), shotAt(freeze.from))
+  }
+  if (!longFreezes.length) add('pass', 'freeze', '没有超过 ' + settings.freezeSeconds + 's 的静止段')
+  else if (!longFreezes.some((item) => item.seconds >= settings.freezeSeconds * 2)) add('pass', 'freeze', '静止段都在设计停留的量级（<' + settings.freezeSeconds * 2 + 's）')
+
+  for (const flash of flashes.slice(0, 8)) add('warn', 'flash', '第 ' + flash.frame + ' 帧亮度突变（' + second(flash.t) + 's，Y≈' + second(flash.yavg) + '）', shotAt(flash.t))
+  if (!flashes.length) add('pass', 'flash', '没有单帧闪烁')
+
+  for (const blank of blanks) add('warn', 'blank', '近乎空白 ' + second(blank.from) + 's–' + second(blank.to) + 's（' + blank.frames + ' 帧）', shotAt(blank.from))
+  if (!blanks.length) add('pass', 'blank', '没有连续空白帧')
+
+  let marginCount = 0
+  for (const [band, hits] of Object.entries(marginHits)) {
+    if (!hits.length) continue
+    marginCount += hits.length
+    add('warn', 'margin-' + band, band + ' 侧安全区有内容 ' + hits.length + ' 段，最长起于 ' + hits[0].from + 's', hits.slice(0, 4))
+  }
+  if (!marginCount) add('pass', 'margin', '四边安全区干净')
+
+  if (pixels && !pixels.error) {
+    const worst = pixels.banding && pixels.banding.worst
+    const bandingSteps = settings.bandingSteps || 10
+    if (worst && worst.longest >= bandingSteps)
+      add('warn', 'banding', '渐变出现阶梯色带（最长 ' + worst.longest + ' 段、共 ' + worst.steps + ' 级，' + worst.time + 's 第 ' + worst.y + ' 行）—— 多半是 8bit 量化没配抖动', shotAt(worst.time))
+    else add('pass', 'banding', '没有检出色带阶梯' + (worst ? '（最长 ' + worst.longest + ' 段）' : ''))
+
+    const aaValue = pixels.aa ? pixels.aa.average : null
+    if (aaValue !== null) {
+      const aaMin = settings.aaMin === undefined ? 0.3 : settings.aaMin
+      if (aaValue < aaMin) add('warn', 'aa', '斜边过渡像素占比 ' + aaValue + '（低于 ' + aaMin + '）—— 边缘像台阶，考虑开累积或超采样')
+      else add('pass', 'aa', '斜边过渡像素占比 ' + aaValue)
+    } else {
+      // 测不出不等于没问题：整帧近乎单色时 Sobel 找不到过渡像素。
+      // 这时候报 pass 会让「平涂深色底 + 细线」这种最该检查的片子悄悄过关。
+      add('info', 'aa', '量不出斜边过渡（画面近乎单色或对比过低），AA 未验证；等有内容的帧再检一次')
+    }
+
+    const missing = (pixels.fonts && pixels.fonts.missing) || []
+    if (missing.length) add('fail', 'font', '场景声明了 ' + missing.length + ' 个没注册的字体（会静默退回系统字体）：' + missing.map((item) => item.family).join('、'), missing.map((item) => item.file))
+    else add('pass', 'font', '字体都有注册或字体文件' + (pixels.fonts && pixels.fonts.families && pixels.fonts.families.length ? '（' + pixels.fonts.families.join(' / ') + '）' : ''))
+  } else if (pixels && pixels.error) add('info', 'pixels', '像素级检查没跑成：' + pixels.error)
+
+  if (audio.checked) {
+    if (audio.truePeakDb !== null && audio.truePeakDb > -0.1) add('warn', 'audio-peak', '真峰值 ' + audio.truePeakDb + ' dBFS，已贴顶')
+    else if (audio.truePeakDb !== null) add('pass', 'audio-peak', '真峰值 ' + audio.truePeakDb + ' dBFS')
+    if (audio.integratedLufs !== null && audio.integratedLufs < -45) add('warn', 'audio-level', '综合响度 ' + audio.integratedLufs + ' LUFS，整片近乎无声')
+    else if (audio.integratedLufs !== null) add('pass', 'audio-level', '综合响度 ' + audio.integratedLufs + ' LUFS')
+    if (audio.silence.length > 2) add('info', 'audio-silence', '有 ' + audio.silence.length + ' 处静音起点（设计上的空拍请忽略）', audio.silence)
+  } else add('info', 'audio', '成片没有音轨')
+
+  const byShot = timeline.shots.map((shot) => {
+    const from = shot.startFrame / fps, to = (shot.startFrame + shot.durationFrames) / fps
+    const inside = (time) => time >= from - 0.02 && time < to - 0.02
+    return {
+      id: shot.id, from, to, seconds: second(shot.durationFrames / fps),
+      freeze: second(Math.max(0, ...freezes.filter((item) => inside(item.from)).map((item) => item.seconds || 0))),
+      black: blacks.filter((item) => inside(item.from)).length,
+      blank: blanks.filter((item) => inside(item.from)).length,
+      flash: flashes.filter((item) => inside(item.t)).length,
+      margin: Object.values(marginHits).flat().filter((item) => inside(item.from)).length,
+    }
+  })
+
+  const fails = checks.filter((item) => item.level === 'fail').length
+  const warns = checks.filter((item) => item.level === 'warn').length
+  const report = {
+    generatedAt: new Date().toISOString(), file: source, fps, frames: stats.length, durationSeconds: second(durationSeconds),
+    verdict: fails ? 'fail' : warns ? 'warn' : 'pass', summary: { fail: fails, warn: warns, pass: checks.length - fails - warns },
+    shots: byShot, checks, audio, pixels,
+    freezeSegments: freezes.map((item) => ({ from: second(item.from), to: item.to === undefined ? null : second(item.to), seconds: second(item.seconds || 0) })).filter((item) => item.seconds >= settings.freezeSeconds),
+    settings,
+  }
+  writeFileSync(join(work, 'report.json'), JSON.stringify(report, null, 2) + '\n', 'utf8')
+  // 统一入口：渲染期的 report（worker 写的渲染规格/采样帧）与帧检结论合成一份，
+  // 读报告的人不需要知道有两个目录。
+  try {
+    const merged = join(dir, '.out', 'qa', 'report.json')
+    const base = existsSync(merged) ? parseProjectJson(readFileSync(merged, 'utf8')) : {}
+    base.frameQa = { generatedAt: report.generatedAt, verdict: report.verdict, summary: report.summary, checks, audio, pixels }
+    writeFileSync(merged, JSON.stringify(base, null, 2) + '\n', 'utf8')
+  } catch { /* 合并失败不该影响帧检结论 */ }
+  for (const name of readdirSync(work)) if (/\.(raw|log)$/.test(name)) rmSync(join(work, name), { force: true })
+  for (const name of ['stats.txt', 'm-left.txt', 'm-right.txt', 'm-top.txt', 'm-bottom.txt', 'scaled.mp4', 'ff.log'])
+    rmSync(join(work, name), { force: true })
+  return report
+}
+
+export function readQaReport(dir) {
+  const file = join(qaDir(dir), 'report.json')
+  if (!existsSync(file)) return null
+  return parseProjectJson(readFileSync(file, 'utf8'))
+}
+
+export function renderMarkdown(report) {
+  const line = (item) => '- [' + item.level + '] ' + item.message + (typeof item.detail === 'string' ? '　→ ' + item.detail : '')
+  return [
+    '# 帧检报告',
+    '',
+    '结论：**' + report.verdict + '**　（fail ' + report.summary.fail + ' / warn ' + report.summary.warn + ' / pass ' + report.summary.pass + '）',
+    '成片：' + report.frames + ' 帧 · ' + report.durationSeconds + 's · ' + report.fps + 'fps',
+    '',
+    '## 逐镜',
+    '',
+    '| 镜头 | 时长 | 最长静止 | 黑场 | 空白 | 闪烁 | 越界 |',
+    '| --- | --- | --- | --- | --- | --- | --- |',
+    ...report.shots.map((shot) => '| ' + shot.id + ' | ' + shot.seconds + 's | ' + shot.freeze + 's | ' + shot.black + ' | ' + shot.blank + ' | ' + shot.flash + ' | ' + shot.margin + ' |'),
+    '',
+    '## 发现',
+    '',
+    ...report.checks.map(line),
+    '',
+  ].join('\n')
+}

package/lib/motion/reference-media.jsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import { Img, OffthreadVideo, staticFile } from 'remotion'
+export function ReferenceMedia({ referenceId, index = 0, assets, style = {}, region }) {
+  const asset = (assets[referenceId] || []).at(index)
+  if (!asset) throw new Error('场景缺少参考素材：' + referenceId + ':' + index)
+  if(region && (!Array.isArray(region)||region.length!==4||region.some(value=>!Number.isFinite(value))||region[0]<0||region[1]<0||region[2]<=0||region[3]<=0||region[0]+region[2]>1.001||region[1]+region[3]>1.001))throw new Error('参考素材裁切区域无效')
+  const props = { src: staticFile(asset.src), style: region ? {position:'absolute',objectFit:'fill',width:100/region[2]+'%',height:100/region[3]+'%',left:-region[0]/region[2]*100+'%',top:-region[1]/region[3]*100+'%'} : { objectFit: 'contain', ...style } }
+  const media=asset.kind === 'video' ? <OffthreadVideo {...props} muted /> : <Img {...props} />
+  return region?<div style={{...style,position:style.position||'relative',overflow:'hidden'}}>{media}</div>:media
+}

package/lib/motion/render-settings.js

@@ -0,0 +1,112 @@
+// 渲染规格：把「这一帧怎么变成文件」从散落的默认值里收成一份可校验、可记录、可复现的数据。
+//
+// 为什么要有这个文件：spec.js 说的是「这条片子是什么」（宽高 / 帧率 / 时长），
+// 这里说的是「它怎么落成文件」（编码、色彩标签、超采样、并发、超时）。
+// 两者混在一起，就会出现「想渲 3840 再缩 1920」这种根本表达不出来的事。
+//
+// 读取优先级：timeline.json 的 render → 调用参数 → RENDER_DEFAULTS。
+// 越界的值不静默接受，也不让整条渲染失败：夹到边界并把原因写进 warnings，
+// 由调用方决定是提示还是拒渲。
+
+export const RENDER_DEFAULTS = {
+  codec: 'h264',
+  crf: 14,                 // 交付级质量；18 是「看一眼」的档，不是母版
+  preset: 'slow',          // renderMedia 的 x264Preset
+  pixelFormat: 'yuv420p',
+  colorSpace: 'bt709',     // 淡紫底 #EEEAFC 不标 bt709 就会偏色 + 出色带
+  scale: 1,                // 2 = 渲 3840 再缩回 1920（超采样），只对成片生效
+  concurrency: 2,
+  audioBitrate: '320k',
+  sampleRate: 48000,
+  timeoutMs: 30 * 60 * 1000,
+  // 下面两个是场景层参数：插件不执行它们，只记录并把它们交给 scene-kit。
+  samples: 1,              // 同帧子渲染次数（GPU 内累积）
+  shutter: 0.5,            // 快门开角比例，1 = 360°
+}
+
+const LIMITS = {
+  codec: ['h264', 'h265', 'vp8', 'vp9'],
+  crf: [10, 18],
+  preset: ['ultrafast', 'superfast', 'veryfast', 'faster', 'fast', 'medium', 'slow', 'slower', 'veryslow'],
+  pixelFormat: ['yuv420p', 'yuv422p', 'yuv444p'],
+  colorSpace: ['bt709', 'bt2020-10', 'bt2020-12'],
+  scale: [1, 2],
+  concurrency: [1, 4],
+  samples: [1, 16],
+  shutter: [0, 1],
+  timeoutMs: [60000, 6 * 60 * 60 * 1000],
+}
+
+const NUMERIC = new Set(['crf', 'scale', 'concurrency', 'samples', 'shutter', 'timeoutMs', 'sampleRate'])
+
+function clean(input) {
+  if (!input || typeof input !== 'object') return {}
+  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined && value !== null && value !== ''))
+}
+
+export function resolveRenderSettings(timeline, overrides = {}) {
+  const stored = timeline && typeof timeline.render === 'object' ? timeline.render : {}
+  const merged = { ...RENDER_DEFAULTS, ...clean(stored), ...clean(overrides) }
+  const warnings = []
+  const settings = {}
+  for (const key of Object.keys(RENDER_DEFAULTS)) {
+    const value = merged[key]
+    const limit = LIMITS[key]
+    if (!limit) { settings[key] = value; continue }
+    if (NUMERIC.has(key)) {
+      const number = Number(value)
+      if (!Number.isFinite(number)) {
+        warnings.push(key + ' 不是数字（' + String(value) + '），用默认 ' + RENDER_DEFAULTS[key])
+        settings[key] = RENDER_DEFAULTS[key]
+        continue
+      }
+      if (number < limit[0] || number > limit[1]) {
+        const clamped = Math.min(Math.max(number, limit[0]), limit[1])
+        warnings.push(key + ' = ' + number + ' 超出允许范围 ' + limit[0] + '–' + limit[1] + '，已夹到 ' + clamped)
+        settings[key] = clamped
+        continue
+      }
+      settings[key] = Math.round(number * 1000) / 1000
+      continue
+    }
+    if (!limit.includes(value)) {
+      warnings.push(key + ' = ' + String(value) + ' 不在 ' + limit.join('/') + ' 里，用默认 ' + RENDER_DEFAULTS[key])
+      settings[key] = RENDER_DEFAULTS[key]
+      continue
+    }
+    settings[key] = value
+  }
+  // 超采样与累积是相乘的：scale² × samples。两条同时拉满能把单帧成本推到 64 倍，
+  // 那时不是「慢一点」，是必然撞超时，所以先算预算再开跑。
+  const pixels = Number(timeline?.width || 1920) * Number(timeline?.height || 1080)
+  const cost = settings.scale * settings.scale * settings.samples
+  const budget = 8 // 等效像素放大倍数的上限（1080p × 8）
+  settings.estimatedCost = Math.round(cost * 100) / 100
+  if (cost > budget) {
+    const suggestSamples = Math.max(1, Math.floor(budget / (settings.scale * settings.scale)))
+    warnings.push('scale=' + settings.scale + ' × samples=' + settings.samples + ' 相当于 ' + settings.estimatedCost
+      + ' 倍像素工作量（预算 ' + budget + '）；建议 samples 降到 ' + suggestSamples + ' 或关掉超采样')
+  }
+  settings.pixels = pixels
+  settings.warnings = warnings
+  return settings
+}
+
+// 超时按帧数放大：settings.timeoutMs 是 300 帧整片的预算，
+// 样片（几十帧）不该按整片等，长片（1200 帧）也不该被 30 分钟卡死。
+export function timeoutFor(settings, frames) {
+  const base = Number(settings?.timeoutMs) || RENDER_DEFAULTS.timeoutMs
+  const count = Number(frames) || 300
+  const scale = Math.max(0.25, Math.min(4, count / 300))
+  return Math.round(base * scale)
+}
+
+// 写进报告的一行字：出问题时要能一眼看出「这条片子是用什么参数渲的」。
+export function describeRenderSettings(settings) {
+  const s = settings || RENDER_DEFAULTS
+  return [
+    s.codec, 'crf=' + s.crf, 'preset=' + s.preset, s.pixelFormat, s.colorSpace,
+    'scale=' + s.scale, 'concurrency=' + s.concurrency,
+    'audio=' + s.audioBitrate + '/' + Math.round(s.sampleRate / 1000) + 'k',
+  ].join(' · ')
+}

package/lib/motion/render.js

@@ -0,0 +1,161 @@
+// 渲染入口：把"工程目录 + 一个操作"翻译成一次 worker 调用。
+//
+// 三条规则（对应之前 58 分钟里最贵的三个坑）：
+//   1. 永远异步：调用方拿到 jobId 就返回，不要把对话卡在 await 上；
+//   2. 永远复用 bundle：预览和全片共用 .out/bundle/.drawai-bundle-key；
+//   3. 永远先出图：预览走 renderStill，几秒钟，不跑全片。
+
+import { videoRuntimeDirectory } from './video-runtime.js'
+import { fork } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { buildComposition, readTimeline } from './project.js'
+import { assetsHash } from './assets.js'
+import { normalizeMix } from './audiomix.js'
+import { writeBundledFonts } from './fonts.js'
+import { syncRevision, filmHash } from './sync.js'
+import { resolveRenderSettings, timeoutFor, describeRenderSettings } from './render-settings.js'
+
+const WORKER = fileURLToPath(new URL('../motion-render-worker.js', import.meta.url))
+// entry.jsx 是打包入口：它改了（比如加了 <Audio>）也必须重建 bundle，
+// 否则会拿旧缓存渲染出一条没有声音的片子。
+const ENTRY = fileURLToPath(new URL('./entry.jsx', import.meta.url))
+
+export function outputPath(dir, name = 'film.mp4') {
+  return join(dir, '.out', name)
+}
+
+// bundle 的缓存键 = 所有场景源码 + 时间轴 + 尺寸 + 素材指纹。改任何一个字节就重建一次。
+export function bundleKey(composition, projectDir) {
+  const hash = createHash('sha256')
+  hash.update(JSON.stringify({
+    width: composition.width, height: composition.height, fps: composition.fps,
+    durationFrames: composition.durationFrames,
+    shots: composition.shots.map((shot) => [shot.id, shot.startFrame, shot.durationFrames]),
+    assets: projectDir ? assetsHash(projectDir) : '',
+  }))
+  for (const shot of composition.shots) hash.update(shot.sceneSource)
+  if (projectDir && existsSync(projectDir)) {
+    const walk = (rel = '') => {
+      for (const entry of readdirSync(join(projectDir, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.isDirectory() && ['.out', 'assets', 'node_modules', '.git'].includes(entry.name)) continue
+        const next = rel ? join(rel, entry.name) : entry.name
+        if (entry.isDirectory()) walk(next)
+        else if (entry.isSymbolicLink()) throw new Error('视频工程源码目录不支持符号链接：' + next)
+        else if (entry.isFile() && /\.(?:[cm]?[jt]sx?|css|json|svg|wasm)$/i.test(entry.name)) {
+          const content = readFileSync(join(projectDir, next))
+          hash.update(JSON.stringify([next.replace(/\\/g, '/'), content.length])).update(content)
+        }
+      }
+    }
+    walk()
+  }
+  hash.update(readFileSync(ENTRY))
+  hash.update(videoRuntimeDirectory())
+  return hash.digest('hex')
+}
+
+function prepare(dir, options) {
+  writeBundledFonts(dir)
+  const composition = options.composition || buildComposition(dir)
+  if (!options.composition) composition.bundledFonts = true
+  const outDirectory = join(dir, '.out')
+  mkdirSync(outDirectory, { recursive: true })
+  const publicDir = join(dir, 'assets')
+  return { composition, outDirectory, publicDir: existsSync(publicDir) ? publicDir : undefined }
+}
+
+// 起一个 render worker。返回 { promise, cancel }：
+// promise 在 done/error/exit 时结算，不阻塞调用方。
+export function renderProject(dir, options = {}) {
+  const { composition, outDirectory, publicDir } = prepare(dir, options)
+  const timeline = readTimeline(dir)
+  const syncReceipt = timeline.sync ? { revision: syncRevision(dir, timeline), fps: timeline.fps } : null
+  const operation = options.operation || 'still'
+  // 预览永远按 1× 渲：我们要看的是构图和字，不是锯齿；超采样留给成片。
+  const settings = resolveRenderSettings(timeline, options.render)
+  const render = operation === 'still' ? { ...settings, scale: 1, samples: 1, estimatedCost: 1 } : settings
+  const output = options.output || outputPath(dir, operation === 'still' ? 'still.mp4' : 'film.mp4')
+  // 场景拿到的 plan.render 必须是**夹取后的**值：只透传时间轴原值的话，
+  // 没写 render 的工程在场景里看到的是 {}，默认采样数就丢了。
+  composition.render = render
+  const bundleDir = join(outDirectory, 'bundle')
+  const request = {
+    composition,
+    projectDirectory: dir,
+    output,
+    publicDir,
+    bundleDir,
+    bundleKey: bundleKey(composition, dir),
+    reuseBundle: options.reuseBundle !== false,
+    keepBundle: true,
+    preserveSources: true,
+    operation,
+    assets: options.assets || {},
+    render,
+    frames: operation === 'still' ? (options.frames || []).map((frame) => Math.round(Number(frame))) : undefined,
+    frameRange: options.frameRange,
+    qaDirectory: join(outDirectory, 'qa'),
+    poster: join(outDirectory, 'poster.png'),
+  }
+  if (operation === 'still' && !request.frames.length) throw new Error('预览需要至少一帧，例如 frames:[0,60,120]')
+  if (operation === 'still' && request.frames.some((frame) => !Number.isInteger(frame) || frame < 0 || frame >= composition.durationFrames))
+    throw new Error('预览帧超出 0–' + (composition.durationFrames - 1))
+
+  const child = fork(WORKER, [], { windowsHide: true, stdio: ['ignore', 'ignore', 'pipe', 'ipc'], execArgv: [] })
+  let settled = false
+  let cancelTimer
+  const rendered = new Promise((resolve, reject) => {
+    const finish = (fn, value) => { if (settled) return; settled = true; clearTimeout(cancelTimer); fn(value) }
+    const timeout = setTimeout(() => { child.kill(); finish(reject, new Error('渲染超过 ' + Math.round(timeoutFor(render, composition.durationFrames) / 60000) + ' 分钟，请拆小场景或在 timeline.json 的 render.timeoutMs 里放大预算')) }, options.timeoutMs || (timeoutFor(render, composition.durationFrames) + 11 * 60000))
+    let stderr = ''
+    child.stderr.on('data', (bytes) => { stderr = (stderr + bytes).slice(-4000) })
+    child.on('message', (message) => {
+      if (message.type === 'progress') options.onProgress?.(message)
+      if (message.type === 'done') { clearTimeout(timeout); finish(resolve, { ...message, output, bundleDir }) }
+      if (message.type === 'error') { clearTimeout(timeout); finish(reject, new Error(message.error)) }
+    })
+    child.on('error', (error) => { clearTimeout(timeout); finish(reject, error) })
+    child.on('exit', (code) => {
+      clearTimeout(timeout)
+      if (!settled) finish(reject, new Error('渲染进程退出（' + code + '）：' + stderr))
+    })
+    child.send(request)
+  })
+  const cancel = () => {
+    if (child.connected) child.send({ type: 'cancel' })
+    cancelTimer = setTimeout(() => child.kill(), 5000)
+  }
+  // 渲完之后再过一遍响度归一 + 限幅。
+  // 只对整片做：切片渲染（frameRange）归一化会把片段当整条量，结果是错的。
+  // 归一化的目标可以在 timeline.json 的 audioMix 里改，也可以在调用时用 options.mix 覆盖。
+  const promise = rendered.then(async (result) => {
+    if (operation !== 'full' || options.frameRange) return result
+    if (!(composition.audio || []).length) return result
+    let config = {}
+    try { config = { ...(readTimeline(dir).audioMix || {}) } } catch { config = {} }
+    config = { ...config, ...(options.mix || {}) }
+    if (config.normalize === false) return result
+    options.onProgress?.({ type: 'progress', phase: 'mixing', progress: 0.97 })
+    try {
+      const mix = await normalizeMix(output, { ...config, cwd: outDirectory, log: join(outDirectory, 'mix.log'), timeoutMs: 180000 })
+      return { ...result, mix }
+    } catch (error) {
+      // 混音后级失败不该让一条已经渲好的片子作废：带着错误回去，由调用方提示。
+      return { ...result, mixError: error.message }
+    }
+  })
+  const completed = promise.then((result) => {
+    if (operation === 'full' && !options.frameRange && syncReceipt) writeFileSync(output + '.sync.json', JSON.stringify({ ...syncReceipt, filmHash: filmHash(output) }))
+    return { ...result, render, renderSummary: describeRenderSettings(render) }
+  })
+  return { promise: completed, cancel, output, bundleDir, render }
+}
+
+export function outputInfo(file) {
+  if (!existsSync(file)) return null
+  const stat = statSync(file)
+  return { path: file, bytes: stat.size, at: stat.mtime.toISOString() }
+}