dsh-drawai 0.4.0 → 0.4.2

package/lib/motion/sync.js

@@ -1,214 +1,214 @@
-// One source of truth: source-music seconds -> edit events -> source SFX peaks.
-import { createHash } from 'node:crypto'
-import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs'
-import { join, resolve, relative, isAbsolute } from 'node:path'
-import { decodePcm } from './beats.js'
-import { runFfmpeg } from './ffmpeg.js'
-import { parseProjectJson } from './json.js'
-
-const number = (value, name) => {
-  if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error(name + ' 必须是有限数字')
-  return value
-}
-export function assetPath(dir, file) {
-  const root = resolve(dir, 'assets'), path = resolve(root, file || '')
-  const rel = relative(root, path)
-  if (!rel || isAbsolute(rel) || rel === '..' || rel.startsWith('..' + (process.platform === 'win32' ? '\\' : '/'))) throw new Error('同步音频必须位于工程 assets 内')
-  return path
-}
-export const syncKey = (timeline) => createHash('sha256').update(JSON.stringify(timeline)).digest('hex')
-export function syncRevision(dir, timeline) {
-  const music = timeline.audio?.find((cue) => cue.id === timeline.sync?.musicCueId)
-  if (timeline.sync?.analysisSourceHash && (!music || timeline.sync.analysisSourceHash !== filmHash(assetPath(dir, music.file)))) throw new Error('音乐文件已变更，请重新 motion_sync bind 分析后绑定')
-  const hash = createHash('sha256').update(syncKey(timeline))
-  for (const shot of timeline.shots) {
-    const file = join(dir, shot.file || '')
-    if (shot.file && existsSync(file)) hash.update(readFileSync(file))
-  }
-  for (const cue of timeline.audio || []) hash.update(readFileSync(assetPath(dir, cue.file)))
-  const walk = (path) => {
-    if (!existsSync(path)) return
-    for (const entry of readdirSync(path, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      const file = join(path, entry.name)
-      if (entry.isDirectory()) walk(file)
-      else if (entry.isFile()) hash.update(entry.name).update(readFileSync(file))
-    }
-  }
-  walk(join(dir, 'components'))
-  walk(join(dir, 'assets'))
-  for (const entry of readdirSync(dir).sort()) if (/\.(tsx?|jsx?)$/.test(entry) && !/^index\./.test(entry)) hash.update(entry).update(readFileSync(join(dir, entry)))
-  return hash.digest('hex')
-}
-export const filmHash = (file) => createHash('sha256').update(readFileSync(file)).digest('hex')
-
-export function resolveSync(input) {
-  const timeline = structuredClone(input), sync = timeline.sync
-  if (!sync) return timeline
-  const fps = number(timeline.fps, 'fps')
-  if (sync.toleranceFrames !== undefined && (number(sync.toleranceFrames, 'toleranceFrames') < 0 || sync.toleranceFrames > 3)) throw new Error('toleranceFrames 必须在0–3内')
-  if (fps <= 0 || !Array.isArray(sync.anchors) || !sync.anchors.length || sync.anchors.length > 200) throw new Error('sync 需要 1–200 个 anchors')
-  const music = timeline.audio?.find((cue) => cue.id === sync.musicCueId)
-  if (!music || music.loop) throw new Error('sync.musicCueId 必须指向不循环的音乐轨')
-  const offset = sync.outputOffsetSeconds === undefined ? 0 : number(sync.outputOffsetSeconds, 'outputOffsetSeconds')
-  if (Math.abs(offset) > 1) throw new Error('输出偏移超出 ±1 秒')
-  const ids = new Set(), targets = new Set(), cueIds = new Set()
-  const rows = sync.anchors.map((anchor) => {
-    if (typeof anchor.id !== 'string' || !anchor.id || ids.has(anchor.id)) throw new Error('anchor.id 必须唯一')
-    ids.add(anchor.id)
-    if (anchor.visual) visualPeak(Buffer.alloc(0), 1, 1, 0, anchor.visual)
-    if (anchor.sfx !== undefined && !Array.isArray(anchor.sfx)) throw new Error('sfx 必须是绑定数组')
-    if (!['cut', 'action'].includes(anchor.type)) throw new Error('anchor.type 必须是 cut/action')
-    const shot = timeline.shots.find((item) => item.id === anchor.shotId)
-    if (!shot) throw new Error('锚点引用了不存在的镜头：' + anchor.shotId)
-    const targetKey = anchor.type + ':' + anchor.shotId + ':' + (anchor.type === 'action' ? anchor.name : '')
-    if (targets.has(targetKey)) throw new Error('同一个切镜或动作不能重复绑定')
-    targets.add(targetKey)
-    if (anchor.type === 'action' && (typeof anchor.name !== 'string' || !anchor.name)) throw new Error('动作锚点需要 name')
-    if ((anchor.at === undefined) === (anchor.beat === undefined)) throw new Error('锚点必须且只能给 at（源音乐秒）或 beat（0 起拍号）')
-    let sourceSeconds
-    if (anchor.at !== undefined) sourceSeconds = number(anchor.at, 'at')
-    else {
-      const grid = sync.analysis?.grid
-      if (!grid || ![grid.t0, grid.periodMs, grid.residualMs, grid.coverage].every(Number.isFinite) || grid.periodMs <= 0 || grid.residualMs > 15 || grid.coverage < 0.45) throw new Error('按拍号绑定需要通过验收的音乐网格；否则使用 at 实测瞬态')
-      const beat = number(anchor.beat, 'beat')
-      if (beat < 0) throw new Error('beat 必须从0起')
-      sourceSeconds = grid.t0 + beat * grid.periodMs / 1000
-    }
-    const musicLocal = sourceSeconds - (music.trimStart || 0)
-    if (musicLocal < 0 || musicLocal * fps >= music.durationInFrames) throw new Error('拍点超出音乐播放窗口：' + anchor.id)
-    const seconds = music.from / fps + musicLocal + offset
-    const frame = Math.round(seconds * fps)
-    if (frame < 0 || frame >= timeline.durationInFrames) throw new Error('锚点超出影片范围：' + anchor.id)
-    if (anchor.type === 'cut') shot.startFrame = frame
-    return { ...anchor, sourceSeconds, seconds, frame, quantizationMs: (frame / fps - seconds) * 1000 }
-  })
-  for (let i = 0; i < timeline.shots.length; i++) {
-    const shot = timeline.shots[i], end = timeline.shots[i + 1]?.startFrame ?? timeline.durationInFrames
-    if (shot.startFrame < 0 || end <= shot.startFrame) throw new Error('切镜绑定导致镜头倒序或长度为零')
-    shot.durationFrames = end - shot.startFrame
-    shot.anchors = Object.create(null)
-  }
-  for (const row of rows) {
-    const shot = timeline.shots.find((item) => item.id === row.shotId)
-    if (row.frame < shot.startFrame || row.frame >= shot.startFrame + shot.durationFrames) throw new Error('动作锚点不在所属镜头内：' + row.id)
-    if (row.type === 'action') shot.anchors[row.name] = row.frame - shot.startFrame
-    for (const sfx of row.sfx || []) {
-      if (cueIds.has(sfx.cueId) || sfx.cueId === music.id) throw new Error('音效轨不能重复绑定或绑定音乐自身')
-      cueIds.add(sfx.cueId)
-      const cue = timeline.audio.find((item) => item.id === sfx.cueId)
-      if (!cue || cue.loop) throw new Error('音效绑定需要存在且不循环的 cueId')
-      const lag = number(sfx.peakSeconds, 'peakSeconds') - (cue.trimStart || 0)
-      if (lag < 0 || lag * fps >= cue.durationInFrames) throw new Error('音效峰值超出裁剪窗口')
-      const from = Math.round(row.frame - (lag + offset) * fps)
-      if (from < 0 || from + cue.durationInFrames > timeline.durationInFrames) throw new Error('音效绑定超出影片范围，不会静默截断')
-      cue.from = from
-    }
-  }
-  sync.resolved = rows
-  return timeline
-}
-
-// Normalized waveform matching around an expected transient. Low/ambiguous
-// matches remain unverified; absence of evidence must never become a pass.
-export function matchTransient(source, output, sourceAt, expectedAt, sampleRate, searchSeconds = 0.2) {
-  const radius = Math.round(sampleRate * 0.025), center = Math.round(sourceAt * sampleRate)
-  const step = 4, template = []
-  for (let i = -radius; i <= radius; i += step) template.push(source[center + i] || 0)
-  const norm = Math.sqrt(template.reduce((sum, x) => sum + x * x, 0))
-  if (!norm) return null
-  let best = { score: -1, at: 0 }, second = -1
-  const scores = []
-  const start = Math.max(radius, Math.round((expectedAt - searchSeconds) * sampleRate)), end = Math.min(output.length - radius - 1, Math.round((expectedAt + searchSeconds) * sampleRate))
-  for (let at = start; at <= end; at++) {
-    let dot = 0, energy = 0
-    for (let i = 0; i < template.length; i++) { const x = output[at - radius + i * step]; dot += template[i] * x; energy += x * x }
-    const score = energy ? dot / (norm * Math.sqrt(energy)) : 0
-    scores.push({ at, score })
-    if (score > best.score) best = { at, score }
-  }
-  for (const candidate of scores) if (Math.abs(candidate.at - best.at) > sampleRate * 0.01) second = Math.max(second, candidate.score)
-  return best.score >= 0.45 && best.score - second >= 0.05 ? { at: best.at / sampleRate, confidence: best.score } : null
-}
-function samples(decoded) {
-  return Float64Array.from({ length: decoded.pcm.length / 2 }, (_, i) => decoded.pcm.readInt16LE(i * 2) / 32768)
-}
-
-export function visualPeak(bytes, width, height, firstFrame, visual = {}) {
-  if (visual.metric !== undefined && !['change', 'brightness'].includes(visual.metric)) throw new Error('visual.metric 必须为 change/brightness')
-  if (visual.minSignal !== undefined && (number(visual.minSignal, 'minSignal') <= 0 || visual.minSignal > 255)) throw new Error('minSignal 必须在0–255内')
-  const size = width * height, count = Math.floor(bytes.length / size), scores = []
-  const roi = visual.roi || { x: 0, y: 0, w: 1, h: 1 }
-  for (const key of ['x', 'y', 'w', 'h']) number(roi[key], 'visual.roi.' + key)
-  if (roi.x < 0 || roi.y < 0 || roi.w <= 0 || roi.h <= 0 || roi.x + roi.w > 1 || roi.y + roi.h > 1) throw new Error('ROI 必须在 0–1 内')
-  for (let f = 1; f < count; f++) {
-    let sum = 0, n = 0
-    for (let y = Math.floor(roi.y * height); y < Math.ceil((roi.y + roi.h) * height); y++) for (let x = Math.floor(roi.x * width); x < Math.ceil((roi.x + roi.w) * width); x++) {
-      const i = y * width + x
-      sum += visual.metric === 'brightness' ? bytes[f * size + i] : Math.abs(bytes[f * size + i] - bytes[(f - 1) * size + i]); n++
-    }
-    scores.push({ frame: firstFrame + f, score: sum / n })
-  }
-  scores.sort((a, b) => b.score - a.score)
-  const best = scores[0], other = scores.find((item) => Math.abs(item.frame - best?.frame) > 1)
-  return best && best.score >= (visual.minSignal ?? 8) && (!other || best.score > other.score * 1.15) ? best : null
-}
-
-export async function verifySync(dir, film, input) {
-  const timeline = resolveSync(input), sync = timeline.sync
-  if (!sync?.resolved?.length) throw new Error('尚未绑定锚点，先 motion_sync bind')
-  const revision = syncRevision(dir, timeline)
-  const receiptPath = film + '.sync.json'
-  const receipt = existsSync(receiptPath) ? parseProjectJson(readFileSync(receiptPath, 'utf8')) : null
-  if (receipt && receipt.revision !== revision) throw new Error('成片与当前绑定或场景版本不一致，请重新渲染后验收')
-  if (receipt && receipt.filmHash !== filmHash(film)) throw new Error('成片文件与渲染回执不一致，请重新渲染')
-  const out = join(dir, '.out', 'qa', 'sync'); mkdirSync(out, { recursive: true })
-  const decoded = await decodePcm(film), output = samples(decoded), rate = decoded.sampleRate
-  const cache = new Map()
-  const load = async (cue) => {
-    const path = assetPath(dir, cue.file)
-    if (!cache.has(path)) cache.set(path, samples(await decodePcm(path)))
-    return cache.get(path)
-  }
-  const music = timeline.audio.find((cue) => cue.id === sync.musicCueId), musicSource = await load(music)
-  const rows = [], offsets = []
-  for (const [index, anchor] of sync.resolved.entries()) {
-    const heard = matchTransient(musicSource, output, anchor.sourceSeconds, anchor.seconds, rate)
-    if (heard) offsets.push(heard.at - (music.from / timeline.fps + anchor.sourceSeconds - (music.trimStart || 0)))
-    let visual = null
-    // A cut is an observable frame difference. Continuous actions need an
-    // explicitly selected metric/ROI; do not infer their semantic peak.
-    if (anchor.type === 'cut' || anchor.visual) {
-      const first = Math.max(0, anchor.frame - 6), last = Math.min(timeline.durationInFrames - 1, anchor.frame + 6)
-      const path = join(out, 'anchor-' + index + '.gray')
-      try {
-        await runFfmpeg(['-loglevel', 'error', '-i', film, '-vf', 'select=between(n\\,' + first + '\\,' + last + '),scale=96:54,format=gray', '-vsync', '0', '-f', 'rawvideo', path], { cwd: dir, log: join(out, 'visual.log') })
-        visual = visualPeak(readFileSync(path), 96, 54, first, anchor.visual)
-        unlinkSync(join(out, 'visual.log'))
-      } finally {
-        if (existsSync(path)) unlinkSync(path)
-      }
-    }
-    const sfxRows = []
-    for (const binding of anchor.sfx || []) {
-      const cue = timeline.audio.find((item) => item.id === binding.cueId)
-      const match = await load(cue).then((source) => matchTransient(source, output, binding.peakSeconds, anchor.frame / timeline.fps, rate))
-      sfxRows.push({ cueId: cue.id, measuredSeconds: match?.at ?? null, confidence: match?.confidence ?? null,
-        errorFrames: match && heard ? (match.at - heard.at) * timeline.fps : null })
-    }
-    const error = heard && visual ? visual.frame - heard.at * timeline.fps : null
-    const tolerance = sync.toleranceFrames ?? 2
-    const status = error === null || sfxRows.some((item) => item.errorFrames === null) ? 'unverified'
-      : Math.abs(error) > tolerance || sfxRows.some((item) => Math.abs(item.errorFrames) > tolerance) ? 'fail' : 'pass'
-    rows.push({ id: anchor.id, type: anchor.type, plannedFrame: anchor.frame, quantizationMs: anchor.quantizationMs,
-      measuredMusicSeconds: heard?.at ?? null, musicConfidence: heard?.confidence ?? null, measuredVisualFrame: visual?.frame ?? null,
-      audiovisualErrorFrames: error, sfx: sfxRows, status })
-  }
-  offsets.sort((a, b) => a - b)
-  const report = { version: 1, film, timelineKey: revision, renderReceipt: !!receipt, fps: timeline.fps, generatedAt: new Date().toISOString(),
-    status: rows.some((row) => row.status === 'fail') ? 'fail' : rows.some((row) => row.status === 'unverified') ? 'unverified' : 'pass',
-    measuredOutputOffsetSeconds: offsets.length >= 3 && offsets.at(-1) - offsets[0] < 0.015 ? offsets[Math.floor(offsets.length / 2)] : null,
-    rows }
-  if (!receipt) report.status = report.status === 'fail' ? 'fail' : 'unverified'
-  writeFileSync(join(out, 'report.json'), JSON.stringify(report, null, 2))
-  return report
-}
+// One source of truth: source-music seconds -> edit events -> source SFX peaks.
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs'
+import { join, resolve, relative, isAbsolute } from 'node:path'
+import { decodePcm } from './beats.js'
+import { runFfmpeg } from './ffmpeg.js'
+import { parseProjectJson } from './json.js'
+
+const number = (value, name) => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error(name + ' 必须是有限数字')
+  return value
+}
+export function assetPath(dir, file) {
+  const root = resolve(dir, 'assets'), path = resolve(root, file || '')
+  const rel = relative(root, path)
+  if (!rel || isAbsolute(rel) || rel === '..' || rel.startsWith('..' + (process.platform === 'win32' ? '\\' : '/'))) throw new Error('同步音频必须位于工程 assets 内')
+  return path
+}
+export const syncKey = (timeline) => createHash('sha256').update(JSON.stringify(timeline)).digest('hex')
+export function syncRevision(dir, timeline) {
+  const music = timeline.audio?.find((cue) => cue.id === timeline.sync?.musicCueId)
+  if (timeline.sync?.analysisSourceHash && (!music || timeline.sync.analysisSourceHash !== filmHash(assetPath(dir, music.file)))) throw new Error('音乐文件已变更，请重新 motion_sync bind 分析后绑定')
+  const hash = createHash('sha256').update(syncKey(timeline))
+  for (const shot of timeline.shots) {
+    const file = join(dir, shot.file || '')
+    if (shot.file && existsSync(file)) hash.update(readFileSync(file))
+  }
+  for (const cue of timeline.audio || []) hash.update(readFileSync(assetPath(dir, cue.file)))
+  const walk = (path) => {
+    if (!existsSync(path)) return
+    for (const entry of readdirSync(path, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = join(path, entry.name)
+      if (entry.isDirectory()) walk(file)
+      else if (entry.isFile()) hash.update(entry.name).update(readFileSync(file))
+    }
+  }
+  walk(join(dir, 'components'))
+  walk(join(dir, 'assets'))
+  for (const entry of readdirSync(dir).sort()) if (/\.(tsx?|jsx?)$/.test(entry) && !/^index\./.test(entry)) hash.update(entry).update(readFileSync(join(dir, entry)))
+  return hash.digest('hex')
+}
+export const filmHash = (file) => createHash('sha256').update(readFileSync(file)).digest('hex')
+
+export function resolveSync(input) {
+  const timeline = structuredClone(input), sync = timeline.sync
+  if (!sync) return timeline
+  const fps = number(timeline.fps, 'fps')
+  if (sync.toleranceFrames !== undefined && (number(sync.toleranceFrames, 'toleranceFrames') < 0 || sync.toleranceFrames > 3)) throw new Error('toleranceFrames 必须在0–3内')
+  if (fps <= 0 || !Array.isArray(sync.anchors) || !sync.anchors.length || sync.anchors.length > 200) throw new Error('sync 需要 1–200 个 anchors')
+  const music = timeline.audio?.find((cue) => cue.id === sync.musicCueId)
+  if (!music || music.loop) throw new Error('sync.musicCueId 必须指向不循环的音乐轨')
+  const offset = sync.outputOffsetSeconds === undefined ? 0 : number(sync.outputOffsetSeconds, 'outputOffsetSeconds')
+  if (Math.abs(offset) > 1) throw new Error('输出偏移超出 ±1 秒')
+  const ids = new Set(), targets = new Set(), cueIds = new Set()
+  const rows = sync.anchors.map((anchor) => {
+    if (typeof anchor.id !== 'string' || !anchor.id || ids.has(anchor.id)) throw new Error('anchor.id 必须唯一')
+    ids.add(anchor.id)
+    if (anchor.visual) visualPeak(Buffer.alloc(0), 1, 1, 0, anchor.visual)
+    if (anchor.sfx !== undefined && !Array.isArray(anchor.sfx)) throw new Error('sfx 必须是绑定数组')
+    if (!['cut', 'action'].includes(anchor.type)) throw new Error('anchor.type 必须是 cut/action')
+    const shot = timeline.shots.find((item) => item.id === anchor.shotId)
+    if (!shot) throw new Error('锚点引用了不存在的镜头：' + anchor.shotId)
+    const targetKey = anchor.type + ':' + anchor.shotId + ':' + (anchor.type === 'action' ? anchor.name : '')
+    if (targets.has(targetKey)) throw new Error('同一个切镜或动作不能重复绑定')
+    targets.add(targetKey)
+    if (anchor.type === 'action' && (typeof anchor.name !== 'string' || !anchor.name)) throw new Error('动作锚点需要 name')
+    if ((anchor.at === undefined) === (anchor.beat === undefined)) throw new Error('锚点必须且只能给 at（源音乐秒）或 beat（0 起拍号）')
+    let sourceSeconds
+    if (anchor.at !== undefined) sourceSeconds = number(anchor.at, 'at')
+    else {
+      const grid = sync.analysis?.grid
+      if (!grid || ![grid.t0, grid.periodMs, grid.residualMs, grid.coverage].every(Number.isFinite) || grid.periodMs <= 0 || grid.residualMs > 15 || grid.coverage < 0.45) throw new Error('按拍号绑定需要通过验收的音乐网格；否则使用 at 实测瞬态')
+      const beat = number(anchor.beat, 'beat')
+      if (beat < 0) throw new Error('beat 必须从0起')
+      sourceSeconds = grid.t0 + beat * grid.periodMs / 1000
+    }
+    const musicLocal = sourceSeconds - (music.trimStart || 0)
+    if (musicLocal < 0 || musicLocal * fps >= music.durationInFrames) throw new Error('拍点超出音乐播放窗口：' + anchor.id)
+    const seconds = music.from / fps + musicLocal + offset
+    const frame = Math.round(seconds * fps)
+    if (frame < 0 || frame >= timeline.durationInFrames) throw new Error('锚点超出影片范围：' + anchor.id)
+    if (anchor.type === 'cut') shot.startFrame = frame
+    return { ...anchor, sourceSeconds, seconds, frame, quantizationMs: (frame / fps - seconds) * 1000 }
+  })
+  for (let i = 0; i < timeline.shots.length; i++) {
+    const shot = timeline.shots[i], end = timeline.shots[i + 1]?.startFrame ?? timeline.durationInFrames
+    if (shot.startFrame < 0 || end <= shot.startFrame) throw new Error('切镜绑定导致镜头倒序或长度为零')
+    shot.durationFrames = end - shot.startFrame
+    shot.anchors = Object.create(null)
+  }
+  for (const row of rows) {
+    const shot = timeline.shots.find((item) => item.id === row.shotId)
+    if (row.frame < shot.startFrame || row.frame >= shot.startFrame + shot.durationFrames) throw new Error('动作锚点不在所属镜头内：' + row.id)
+    if (row.type === 'action') shot.anchors[row.name] = row.frame - shot.startFrame
+    for (const sfx of row.sfx || []) {
+      if (cueIds.has(sfx.cueId) || sfx.cueId === music.id) throw new Error('音效轨不能重复绑定或绑定音乐自身')
+      cueIds.add(sfx.cueId)
+      const cue = timeline.audio.find((item) => item.id === sfx.cueId)
+      if (!cue || cue.loop) throw new Error('音效绑定需要存在且不循环的 cueId')
+      const lag = number(sfx.peakSeconds, 'peakSeconds') - (cue.trimStart || 0)
+      if (lag < 0 || lag * fps >= cue.durationInFrames) throw new Error('音效峰值超出裁剪窗口')
+      const from = Math.round(row.frame - (lag + offset) * fps)
+      if (from < 0 || from + cue.durationInFrames > timeline.durationInFrames) throw new Error('音效绑定超出影片范围，不会静默截断')
+      cue.from = from
+    }
+  }
+  sync.resolved = rows
+  return timeline
+}
+
+// Normalized waveform matching around an expected transient. Low/ambiguous
+// matches remain unverified; absence of evidence must never become a pass.
+export function matchTransient(source, output, sourceAt, expectedAt, sampleRate, searchSeconds = 0.2) {
+  const radius = Math.round(sampleRate * 0.025), center = Math.round(sourceAt * sampleRate)
+  const step = 4, template = []
+  for (let i = -radius; i <= radius; i += step) template.push(source[center + i] || 0)
+  const norm = Math.sqrt(template.reduce((sum, x) => sum + x * x, 0))
+  if (!norm) return null
+  let best = { score: -1, at: 0 }, second = -1
+  const scores = []
+  const start = Math.max(radius, Math.round((expectedAt - searchSeconds) * sampleRate)), end = Math.min(output.length - radius - 1, Math.round((expectedAt + searchSeconds) * sampleRate))
+  for (let at = start; at <= end; at++) {
+    let dot = 0, energy = 0
+    for (let i = 0; i < template.length; i++) { const x = output[at - radius + i * step]; dot += template[i] * x; energy += x * x }
+    const score = energy ? dot / (norm * Math.sqrt(energy)) : 0
+    scores.push({ at, score })
+    if (score > best.score) best = { at, score }
+  }
+  for (const candidate of scores) if (Math.abs(candidate.at - best.at) > sampleRate * 0.01) second = Math.max(second, candidate.score)
+  return best.score >= 0.45 && best.score - second >= 0.05 ? { at: best.at / sampleRate, confidence: best.score } : null
+}
+function samples(decoded) {
+  return Float64Array.from({ length: decoded.pcm.length / 2 }, (_, i) => decoded.pcm.readInt16LE(i * 2) / 32768)
+}
+
+export function visualPeak(bytes, width, height, firstFrame, visual = {}) {
+  if (visual.metric !== undefined && !['change', 'brightness'].includes(visual.metric)) throw new Error('visual.metric 必须为 change/brightness')
+  if (visual.minSignal !== undefined && (number(visual.minSignal, 'minSignal') <= 0 || visual.minSignal > 255)) throw new Error('minSignal 必须在0–255内')
+  const size = width * height, count = Math.floor(bytes.length / size), scores = []
+  const roi = visual.roi || { x: 0, y: 0, w: 1, h: 1 }
+  for (const key of ['x', 'y', 'w', 'h']) number(roi[key], 'visual.roi.' + key)
+  if (roi.x < 0 || roi.y < 0 || roi.w <= 0 || roi.h <= 0 || roi.x + roi.w > 1 || roi.y + roi.h > 1) throw new Error('ROI 必须在 0–1 内')
+  for (let f = 1; f < count; f++) {
+    let sum = 0, n = 0
+    for (let y = Math.floor(roi.y * height); y < Math.ceil((roi.y + roi.h) * height); y++) for (let x = Math.floor(roi.x * width); x < Math.ceil((roi.x + roi.w) * width); x++) {
+      const i = y * width + x
+      sum += visual.metric === 'brightness' ? bytes[f * size + i] : Math.abs(bytes[f * size + i] - bytes[(f - 1) * size + i]); n++
+    }
+    scores.push({ frame: firstFrame + f, score: sum / n })
+  }
+  scores.sort((a, b) => b.score - a.score)
+  const best = scores[0], other = scores.find((item) => Math.abs(item.frame - best?.frame) > 1)
+  return best && best.score >= (visual.minSignal ?? 8) && (!other || best.score > other.score * 1.15) ? best : null
+}
+
+export async function verifySync(dir, film, input) {
+  const timeline = resolveSync(input), sync = timeline.sync
+  if (!sync?.resolved?.length) throw new Error('尚未绑定锚点，先 motion_sync bind')
+  const revision = syncRevision(dir, timeline)
+  const receiptPath = film + '.sync.json'
+  const receipt = existsSync(receiptPath) ? parseProjectJson(readFileSync(receiptPath, 'utf8')) : null
+  if (receipt && receipt.revision !== revision) throw new Error('成片与当前绑定或场景版本不一致，请重新渲染后验收')
+  if (receipt && receipt.filmHash !== filmHash(film)) throw new Error('成片文件与渲染回执不一致，请重新渲染')
+  const out = join(dir, '.out', 'qa', 'sync'); mkdirSync(out, { recursive: true })
+  const decoded = await decodePcm(film), output = samples(decoded), rate = decoded.sampleRate
+  const cache = new Map()
+  const load = async (cue) => {
+    const path = assetPath(dir, cue.file)
+    if (!cache.has(path)) cache.set(path, samples(await decodePcm(path)))
+    return cache.get(path)
+  }
+  const music = timeline.audio.find((cue) => cue.id === sync.musicCueId), musicSource = await load(music)
+  const rows = [], offsets = []
+  for (const [index, anchor] of sync.resolved.entries()) {
+    const heard = matchTransient(musicSource, output, anchor.sourceSeconds, anchor.seconds, rate)
+    if (heard) offsets.push(heard.at - (music.from / timeline.fps + anchor.sourceSeconds - (music.trimStart || 0)))
+    let visual = null
+    // A cut is an observable frame difference. Continuous actions need an
+    // explicitly selected metric/ROI; do not infer their semantic peak.
+    if (anchor.type === 'cut' || anchor.visual) {
+      const first = Math.max(0, anchor.frame - 6), last = Math.min(timeline.durationInFrames - 1, anchor.frame + 6)
+      const path = join(out, 'anchor-' + index + '.gray')
+      try {
+        await runFfmpeg(['-loglevel', 'error', '-i', film, '-vf', 'select=between(n\\,' + first + '\\,' + last + '),scale=96:54,format=gray', '-vsync', '0', '-f', 'rawvideo', path], { cwd: dir, log: join(out, 'visual.log') })
+        visual = visualPeak(readFileSync(path), 96, 54, first, anchor.visual)
+        unlinkSync(join(out, 'visual.log'))
+      } finally {
+        if (existsSync(path)) unlinkSync(path)
+      }
+    }
+    const sfxRows = []
+    for (const binding of anchor.sfx || []) {
+      const cue = timeline.audio.find((item) => item.id === binding.cueId)
+      const match = await load(cue).then((source) => matchTransient(source, output, binding.peakSeconds, anchor.frame / timeline.fps, rate))
+      sfxRows.push({ cueId: cue.id, measuredSeconds: match?.at ?? null, confidence: match?.confidence ?? null,
+        errorFrames: match && heard ? (match.at - heard.at) * timeline.fps : null })
+    }
+    const error = heard && visual ? visual.frame - heard.at * timeline.fps : null
+    const tolerance = sync.toleranceFrames ?? 2
+    const status = error === null || sfxRows.some((item) => item.errorFrames === null) ? 'unverified'
+      : Math.abs(error) > tolerance || sfxRows.some((item) => Math.abs(item.errorFrames) > tolerance) ? 'fail' : 'pass'
+    rows.push({ id: anchor.id, type: anchor.type, plannedFrame: anchor.frame, quantizationMs: anchor.quantizationMs,
+      measuredMusicSeconds: heard?.at ?? null, musicConfidence: heard?.confidence ?? null, measuredVisualFrame: visual?.frame ?? null,
+      audiovisualErrorFrames: error, sfx: sfxRows, status })
+  }
+  offsets.sort((a, b) => a - b)
+  const report = { version: 1, film, timelineKey: revision, renderReceipt: !!receipt, fps: timeline.fps, generatedAt: new Date().toISOString(),
+    status: rows.some((row) => row.status === 'fail') ? 'fail' : rows.some((row) => row.status === 'unverified') ? 'unverified' : 'pass',
+    measuredOutputOffsetSeconds: offsets.length >= 3 && offsets.at(-1) - offsets[0] < 0.015 ? offsets[Math.floor(offsets.length / 2)] : null,
+    rows }
+  if (!receipt) report.status = report.status === 'fail' ? 'fail' : 'unverified'
+  writeFileSync(join(out, 'report.json'), JSON.stringify(report, null, 2))
+  return report
+}

package/lib/motion/video-runtime.js

@@ -0,0 +1,192 @@
+// Isolated video dependencies: no Remotion/esbuild is loaded or installed at plugin startup.
+import { spawn, spawnSync } from 'node:child_process'
+import { createHash, randomUUID } from 'node:crypto'
+import { createRequire } from 'node:module'
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join, relative, resolve, parse } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const localRequire = createRequire(import.meta.url)
+const MANIFEST = fileURLToPath(new URL('./runtime/package.json', import.meta.url))
+const LOCK = fileURLToPath(new URL('./runtime/package-lock.json', import.meta.url))
+const fingerprint = createHash('sha256').update(readFileSync(LOCK)).digest('hex')
+const spec = JSON.parse(readFileSync(MANIFEST, 'utf8'))
+const key = `v1-${process.platform}-${process.arch}-node${process.versions.node.split('.')[0]}-${fingerprint.slice(0, 12)}`
+const pending = new Map()
+
+function waitForInitialization(work, signal) {
+  if (!signal) return work
+  signal.throwIfAborted()
+  return new Promise((done, fail) => {
+    const abort = () => fail(signal.reason || new Error('已取消视频环境初始化'))
+    signal.addEventListener('abort', abort, { once: true })
+    work.then(done, fail).finally(() => signal.removeEventListener('abort', abort))
+  })
+}
+
+export function videoRuntimeDirectory() {
+  const directory = resolve(process.env.DRAWAI_VIDEO_RUNTIME_DIR || join(homedir(), '.dsh', 'drawai-video-runtime', key))
+  if ([parse(directory).root, resolve(homedir()), resolve(process.cwd())].includes(directory))
+    throw new Error('视频运行环境必须使用独立子目录')
+  return directory
+}
+
+export function videoRuntimeRequire(directory = videoRuntimeDirectory()) {
+  return createRequire(join(directory, 'package.json'))
+}
+
+function validate(directory, native = false) {
+  const require = videoRuntimeRequire(directory)
+  for (const [name, version] of Object.entries(spec.dependencies)) {
+    let file
+    try { file = require.resolve(name + '/package.json') } catch (error) {
+      if (error.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') throw error
+      let parent = dirname(require.resolve(name))
+      while (dirname(parent) !== parent) {
+        const candidate = join(parent, 'package.json')
+        if (existsSync(candidate) && JSON.parse(readFileSync(candidate, 'utf8')).name === name) { file = candidate; break }
+        parent = dirname(parent)
+      }
+      if (!file) throw new Error('缺少视频依赖清单：' + name)
+    }
+    const rel = relative(realpathSync(join(directory, 'node_modules')), realpathSync(file))
+    if (isAbsolute(rel) || rel === '..' || rel.startsWith('..' + (process.platform === 'win32' ? '\\' : '/')))
+      throw new Error('视频依赖未安装在独立目录：' + name)
+    if (JSON.parse(readFileSync(file, 'utf8')).version !== version) throw new Error('视频依赖版本不匹配：' + name)
+  }
+  if (!native) return
+  // Validate in a child so Windows DLL handles and cached module paths don't
+  // pin the staging directory while it is atomically renamed into the cache.
+  const checked = spawnSync(process.execPath, ['-e',
+    "const r=require('node:module').createRequire(process.argv[1]);const b=r('@remotion/bundler');r('@remotion/renderer');if(!b.BundlerInternals.esbuild.transformSync('const n: number = 1',{loader:'ts'}).code)process.exit(1)",
+    join(directory, 'package.json')], { windowsHide: true, encoding: 'utf8', timeout: 90000,
+    env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' } })
+  if (checked.status !== 0) throw new Error('视频二进制验证失败：' + (checked.error?.message || checked.stderr))
+}
+
+export function videoRuntimeState() {
+  const directory = videoRuntimeDirectory()
+  try {
+    const ready = JSON.parse(readFileSync(join(directory, '.ready.json'), 'utf8'))
+    if (ready.fingerprint !== fingerprint || ready.key !== key) return { ready: false, directory }
+    validate(directory)
+    return { ready: true, directory }
+  } catch { return { ready: false, directory } }
+}
+
+function install(directory, { signal, onProgress }) {
+  const cli = join(dirname(localRequire.resolve('npm/package.json')), 'bin', 'npm-cli.js')
+  const registry = process.env.DRAWAI_RUNTIME_REGISTRY || 'https://registry.npmjs.org'
+  const url = new URL(registry)
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new Error('视频依赖 registry 地址无效')
+  return new Promise((done, fail) => {
+    const child = spawn(process.execPath, [cli, 'ci', '--ignore-scripts', '--include=optional', '--no-audit', '--no-fund',
+      '--registry=' + url.href, '--fetch-retries=1', '--fetch-timeout=30000', '--loglevel=error'], {
+      cwd: directory, windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'],
+      env: { ...process.env, ELECTRON_RUN_AS_NODE: '1', NODE_ENV: 'production', npm_config_ignore_scripts: 'true' },
+    })
+    let stderr = '', settled = false
+    const abort = () => child.kill()
+    const timer = setTimeout(() => child.kill(), 10 * 60000)
+    const progress = setInterval(() => onProgress?.({ phase: 'runtime-installing', message: '正在下载和校验视频依赖，首次初始化可能需要数分钟' }), 5000)
+    const finish = error => {
+      if (settled) return
+      settled = true; clearTimeout(timer); clearInterval(progress); signal?.removeEventListener('abort', abort)
+      if (signal?.aborted) fail(signal.reason || new Error('已取消视频环境初始化'))
+      else if (error) fail(error)
+      else done()
+    }
+    child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-3000) })
+    child.on('error', finish)
+    child.on('close', code => finish(code === 0 ? null : new Error('视频依赖安装失败（' + code + '）：' + stderr)))
+    signal?.addEventListener('abort', abort, { once: true })
+    if (signal?.aborted) abort()
+  })
+}
+
+async function initialize({ signal, onProgress }) {
+  const directory = videoRuntimeDirectory(), lock = directory + '.lock'
+  if (existsSync(directory)) {
+    const previous = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8'))
+    if (previous.name !== spec.name) throw new Error('缓存位置包含其他文件，请指定独立目录')
+  }
+  mkdirSync(dirname(directory), { recursive: true })
+  // Coordinate independent render workers. A dead owner's lock is recoverable.
+  let ownsLock = false
+  const deadline = Date.now() + 11 * 60000
+  while (!ownsLock) {
+    signal?.throwIfAborted()
+    try {
+      mkdirSync(lock)
+      ownsLock = true
+      writeFileSync(join(lock, 'owner.json'), JSON.stringify({ pid: process.pid, at: Date.now() }))
+    } catch (error) {
+      if (ownsLock || error.code !== 'EEXIST') throw error
+      try {
+        const owner = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'))
+        if (!Number.isInteger(owner.pid) || owner.pid <= 0) throw new Error('invalid lock owner')
+        try { process.kill(owner.pid, 0) } catch (e) {
+          if (e.code === 'ESRCH') { rmSync(lock, { recursive: true, force: true }); continue }
+        }
+      } catch {
+        // Recover if the installer crashed between mkdir and writing its owner.
+        if (existsSync(lock) && Date.now() - statSync(lock).mtimeMs > 30000) {
+          rmSync(lock, { recursive: true, force: true }); continue
+        }
+      }
+      if (Date.now() > deadline) throw new Error('等待其他视频环境初始化超时，请重试')
+      onProgress?.({ phase: 'runtime-installing', message: '正在等待共享视频运行环境就绪' })
+      await new Promise(done => setTimeout(done, 500))
+    }
+  }
+  const staging = directory + '.tmp-' + randomUUID()
+  try {
+    if (videoRuntimeState().ready) return directory
+    onProgress?.({ phase: 'runtime-installing', message: '首次使用：正在初始化独立视频运行环境' })
+    signal?.throwIfAborted()
+    mkdirSync(staging)
+    writeFileSync(join(staging, 'package.json'), readFileSync(MANIFEST))
+    writeFileSync(join(staging, 'package-lock.json'), readFileSync(LOCK))
+    await install(staging, { signal, onProgress })
+    signal?.throwIfAborted()
+    onProgress?.({ phase: 'runtime-checking', message: '正在验证视频运行环境' })
+    validate(staging, true)
+    writeFileSync(join(staging, '.ready.json'), JSON.stringify({ fingerprint, key }))
+    // Only replace this cache after installation and native-binary validation succeed.
+    if (existsSync(directory)) {
+      const previous = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8'))
+      if (previous.name !== spec.name) throw new Error('缓存位置包含其他文件，请指定独立目录')
+      rmSync(directory, { recursive: true, force: true })
+    }
+    renameSync(staging, directory)
+    onProgress?.({ phase: 'runtime-ready', message: '视频运行环境已就绪，后续离线复用' })
+    return directory
+  } finally {
+    rmSync(staging, { recursive: true, force: true })
+    rmSync(lock, { recursive: true, force: true })
+  }
+}
+
+export async function ensureVideoRuntime(options = {}) {
+  options.signal?.throwIfAborted()
+  const state = videoRuntimeState()
+  if (state.ready) return state.directory
+  // A caller's cancellation must not cancel another caller's shared initialization.
+  if (pending.has(state.directory)) {
+    try { await waitForInitialization(pending.get(state.directory), options.signal) } catch { /* Another caller may have cancelled. */ }
+    options.signal?.throwIfAborted()
+    return ensureVideoRuntime(options)
+  }
+  const work = initialize({ ...options, onProgress: options.onProgress || (event => console.error('[drawai] ' + event.message)) }).catch(error => {
+    throw new Error('视频运行环境未就绪：' + error.message + '\n联网后重试当前操作即可重新初始化。可用 DRAWAI_RUNTIME_REGISTRY 设置镜像，DRAWAI_VIDEO_RUNTIME_DIR 设置缓存目录。', { cause: error })
+  }).finally(() => pending.delete(state.directory))
+  pending.set(state.directory, work)
+  return work
+}
+
+export async function loadVideoModule(name, options = {}) {
+  if (!Object.hasOwn(spec.dependencies, name)) throw new Error('不支持的视频模块：' + name)
+  const directory = await ensureVideoRuntime(options)
+  return videoRuntimeRequire(directory)(name)
+}