dsh-drawai 0.3.3 → 0.4.0

package/lib/motion/audio.js

@@ -0,0 +1,103 @@
+// 音频轨：画面和声音共用一条时间轴。
+//
+// 为什么不是"渲染完再用 ffmpeg 混音"：混音只能调已有素材的音量，
+// 改不了画面；而卡点需要"这一帧的画面事件"和"这一拍的重音"同时成立。
+// 所以音频必须进 Remotion 的 plan，由 entry.jsx 在渲染时挂 <Audio>。
+//
+// 时间轴上的音频条目（timeline.json 的 audio[]）：
+//   { id, file, role, from, durationInFrames, gainDb, fadeIn, fadeOut, trimStart, loop, duck }
+// - file 相对 <工程>/assets/，渲染时用 staticFile(file)；
+// - from 是**全片帧坐标**，和 shots 同一坐标系（不写场景内相对帧）；
+// - gainDb 用 dB（0 = 原样，-6 = 一半），entry 里转成线性增益；
+// - duck=true 时，旁白区间自动压低（BGM 专用）。
+
+import { randomUUID } from 'node:crypto'
+import { OUTPUT_AUDIO_OFFSET_F } from './beats.js'
+
+export const AUDIO_ROLES = ['bgm', 'voice', 'sfx']
+export const DUCK_DB = -12
+export const DUCK_RAMP_FRAMES = 6
+
+/** 把一条音频条目规范成渲染能吃的形状；缺字段给默认值，越界直接拒绝。 */
+export function normalizeCue(raw, fps, totalFrames) {
+  if (!raw || typeof raw !== 'object') return null
+  const file = typeof raw.file === 'string' ? raw.file.replace(/\\/g, '/') : ''
+  if (!file || file.indexOf('..') >= 0) return null
+  const role = AUDIO_ROLES.includes(raw.role) ? raw.role : 'sfx'
+  const from = Math.max(0, Math.round(Number(raw.from) || 0))
+  const duration = Math.max(1, Math.round(Number(raw.durationInFrames) || Math.round(Number(raw.duration) * fps) || fps))
+  const gainDb = Number.isFinite(Number(raw.gainDb)) ? Number(raw.gainDb) : (role === 'bgm' ? -10 : 0)
+  return {
+    id: typeof raw.id === 'string' && raw.id ? raw.id : 'cue-' + randomUUID().slice(0, 8),
+    file,
+    role,
+    from: Math.min(from, Math.max(0, totalFrames - 1)),
+    durationInFrames: Math.min(duration, Math.max(1, totalFrames - from)),
+    gainDb,
+    fadeIn: Math.max(0, Math.round(Number(raw.fadeIn) || 0)),
+    fadeOut: Math.max(0, Math.round(Number(raw.fadeOut) || 0)),
+    trimStart: Math.max(0, Number(raw.trimStart) || 0),
+    loop: raw.loop === true || raw.loop === '1',
+    duck: role === 'bgm' ? raw.duck !== false : false,
+  }
+}
+
+export function readTrack(timeline) {
+  const fps = Number(timeline.fps) || 30
+  const total = Number(timeline.durationInFrames) || 0
+  const list = Array.isArray(timeline.audio) ? timeline.audio : []
+  return list.map((cue) => normalizeCue(cue, fps, total)).filter(Boolean)
+}
+
+export function writeTrack(timeline, cues) {
+  timeline.audio = cues
+  return timeline
+}
+
+export function addCue(timeline, cue) {
+  const cues = readTrack(timeline)
+  const next = normalizeCue(cue, Number(timeline.fps) || 30, Number(timeline.durationInFrames) || 0)
+  if (!next) throw new Error('音频条目缺少 file')
+  // 只替换「同一个文件 + 同一个角色 + 同一个位置」的那一条（重复调用是幂等的）；
+  // 同一个音效放在不同时间点是两条轨，不能互相顶掉。
+  const filtered = cues.filter((item) => !(item.file === next.file && item.role === next.role && item.from === next.from))
+  filtered.push(next)
+  filtered.sort((a, b) => a.from - b.from)
+  return writeTrack(timeline, filtered)
+}
+
+export function removeCue(timeline, id) {
+  const cues = readTrack(timeline).filter((cue) => cue.id !== id)
+  return writeTrack(timeline, cues)
+}
+
+/**
+ * 旁白区间（全片帧），给 ducking 用。
+ * 提前 4 帧起、延后 8 帧收，避免声音尾巴被"掐断"。
+ */
+export function voiceWindows(cues) {
+  return cues.filter((cue) => cue.role === 'voice').map((cue) => ({
+    from: Math.max(0, cue.from - 4),
+    to: cue.from + cue.durationInFrames + 8,
+  }))
+}
+
+/** dB → 线性增益。 */
+export function dbToGain(db) {
+  return Math.pow(10, Number(db || 0) / 20)
+}
+
+/**
+ * 把一条音频钉到某个"画面事件帧"上（原版 sound-design §4.6 的公式）。
+ * sourcePeakLagFrames 由 motion_audio analyze 给出（peakLag × fps）。
+ */
+export function cuePinnedAt(targetPeakFrame, sourcePeakLagFrames = 0) {
+  return Math.max(0, Math.round(targetPeakFrame - (sourcePeakLagFrames || 0) - OUTPUT_AUDIO_OFFSET_F))
+}
+
+/** 音频轨摘要：给工具返回值和 BRIEF 用。 */
+export function describeTrack(cues, fps) {
+  if (!cues.length) return '（无音频）'
+  return cues.map((cue) => '- ' + cue.role + ' ' + cue.file + ' @ ' + (cue.from / fps).toFixed(2) + 's · '
+    + (cue.durationInFrames / fps).toFixed(2) + 's · ' + cue.gainDb + 'dB' + (cue.duck ? ' · 旁白避让' : '')).join('\n')
+}

package/lib/motion/audiolevel.js

@@ -0,0 +1,63 @@
+// 音轨电平：加一条音轨的时候就算清楚它进混音会是什么样。
+//
+// 这不是混音器，只是把"要不要减一点增益"这件事从**渲完再发现**挪到**加的时候就知道**。
+// 两个依据：素材自带的样本峰值（ffmpeg volumedetect）和这条的增益。
+//
+// 为什么不能直接照抄 suggestedGainDb：
+//   那个建议是把 RMS 拉到 -16dB，对**短促的打击类音效**是错的 ——
+//   RMS 很低但峰值很高，照抄会把峰值推到 +5dBFS（实测 fs:615308 就是这样）。
+//   所以这里按峰值再夹一次：清单说多少都可以，但峰值不许过天花板。
+
+import { dbToGain } from './audio.js'
+
+/** 留出的天花板：峰值到 -1 dBFS 就当作"会顶"（编码器前端还有取样间过冲）。 */
+export const PEAK_CEILING_DB = -1
+
+/** 已知峰值时，这条最多还能加多少 dB。 */
+export function maxGainFor(peakDb, ceilingDb = PEAK_CEILING_DB) {
+  if (!Number.isFinite(Number(peakDb))) return null
+  return Math.floor((ceilingDb - Number(peakDb)) * 10) / 10
+}
+
+/** 增益从哪来：显式 > 音频清单的建议 > 角色默认；非显式的再按峰值夹一道。 */
+export function resolveGainDb({ explicitGain, manifestGain, role, peakDb } = {}) {
+  if (Number.isFinite(Number(explicitGain))) return { gainDb: Number(explicitGain), source: 'explicit' }
+  const suggested = Number.isFinite(Number(manifestGain))
+  const proposed = suggested ? Number(manifestGain) : (role === 'bgm' ? -10 : 0)
+  const source = suggested ? 'manifest' : 'role'
+  const limit = maxGainFor(peakDb)
+  if (limit !== null && proposed > limit) return { gainDb: limit, source, capped: proposed }
+  return { gainDb: proposed, source }
+}
+
+/** 音频清单里这个文件被建议的增益（motion_sfx get 量出来写进去的）。 */
+export function suggestedGainOf(manifest, file) {
+  const entry = (manifest?.assets || []).find((item) => item.file === file)
+  const gain = entry?.analysis?.suggestedGainDb
+  return Number.isFinite(Number(gain)) ? Number(gain) : null
+}
+
+/** 一个素材加完增益之后的峰值；素材测不出来时给 null（不假装知道）。 */
+export function cueLevel({ peakDb, gainDb } = {}) {
+  const known = peakDb !== null && peakDb !== undefined && Number.isFinite(Number(peakDb))
+  const peak = known ? Math.round((Number(peakDb) + Number(gainDb || 0)) * 10) / 10 : null
+  return { peakDb: peak, headroomDb: peak === null ? null : Math.round((PEAK_CEILING_DB - peak) * 10) / 10, clips: peak !== null && peak > PEAK_CEILING_DB }
+}
+
+/** 几条同时响的峰值做线性相加的保守估计（不是 LUFS，只是"会不会顶"）。 */
+export function mixPeakDb(cuePeaksDb) {
+  const sum = (cuePeaksDb || []).reduce((total, db) => (Number.isFinite(Number(db)) ? total + dbToGain(Number(db)) : total), 0)
+  return sum > 0 ? Math.round(20 * Math.log10(sum) * 10) / 10 : null
+}
+
+/** 给工具返回值用的人话。 */
+export function describeLevel({ cue, gain, level, overlaps }) {
+  const source = { explicit: '显式指定', manifest: '音频清单的 suggestedGainDb', role: '角色默认' }[gain.source] || gain.source
+  const lines = ['增益 ' + cue.gainDb + 'dB —— ' + source
+    + (gain.capped === undefined ? '' : '（原文建议 ' + gain.capped + 'dB，按峰值夹到 ' + cue.gainDb + 'dB，否则会削波）')]
+  if (level.peakDb === null) lines.push('素材量不出峰值（空的或格式没解析），电平只能靠听')
+  else if (level.clips) lines.push('这一条加完峰值约 ' + level.peakDb + ' dBFS，已经顶到天花板')
+  else lines.push('这一条加完峰值约 ' + level.peakDb + ' dBFS，余量 ' + level.headroomDb + 'dB')
+  if (overlaps > 0) lines.push('这个时间段已经有 ' + overlaps + ' 条音轨，叠加后峰值只会更高')
+  return lines.join('\n')
+}

package/lib/motion/audiomix.js

@@ -0,0 +1,144 @@
+// 混音后级：成片渲完再走一遍 loudnorm + alimiter。
+//
+// 为什么需要这一级：
+//   Remotion 把各条 <Audio> 直接相加编码成 AAC，**没有任何限幅**；
+//   而画布那条旧链路（audio-media.js）混音时一直带 alimiter。
+//   缺这一级的后果是可实测的：n1 那条片的真峰值一度 +1.8 dBFS（削波），
+//   只能靠帧检事后发现再回头手改每一条的增益。
+//
+// 用的是 loudnorm 的两遍法：
+//   第一遍只量（print_format=json 拿到 measured_*），
+//   第二遍把测得值喂回去并开 linear=true —— 能线性就线性（不动动态），
+//   线性会把真峰值顶穿时 loudnorm 自己退回动态模式。
+//   最后再挂一级 alimiter 兜底，防止编码器前端出现取样间过冲。
+
+import { existsSync, renameSync, rmSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { runFfmpeg } from './ffmpeg.js'
+
+/**
+ * 目标响度：交付规范是 −14 LUFS / 真峰值 ≤ −1 dBTP（网络平台上传标准）。
+ * 早先取 −16 / −1.5 是「保守一点」的折中；既然插件出的就是交付件，默认就该是交付值。
+ * 要旧行为可以在 timeline.json 的 audioMix 里显式写回。
+ */
+export const MIX_DEFAULTS = { normalize: true, lufs: -14, truePeak: -1, lra: 11 }
+
+/** 从 loudnorm 的 stderr 里取最后一段 JSON（前面还有滤镜的日志行）。 */
+export function parseLoudnormJson(text) {
+  const blocks = [...String(text || '').matchAll(/\{[^{}]*\}/g)]
+  for (let index = blocks.length - 1; index >= 0; index--) {
+    try {
+      const parsed = JSON.parse(blocks[index][0])
+      if (parsed && parsed.input_i !== undefined) return parsed
+    } catch { /* 不是 JSON，继续往前找 */ }
+  }
+  return null
+}
+
+/** 量整段的综合响度与真峰值（取 ebur128 结尾的 Summary 段）。没有音轨时返回 null 值。 */
+export async function measureLoudness(file, options = {}) {
+  const text = await runFfmpeg(['-i', file, '-af', 'ebur128=peak=true', '-f', 'null', '-'],
+    { cwd: options.cwd, log: options.log || 'mix-ebur128.log', allowFail: true, timeoutMs: options.timeoutMs })
+  // ebur128 每 100ms 打一行进度，开头那几行的 I 是 -70（还没攒够数据）；
+  // 只有结尾 Summary 段才是整段的结论，所以从 Summary 开始截，并取最后一个匹配。
+  const index = text.lastIndexOf('Summary:')
+  const summary = index >= 0 ? text.slice(index) : text
+  const grab = (pattern) => {
+    const matches = [...summary.matchAll(pattern)]
+    return matches.length ? Number(matches[matches.length - 1][1]) : null
+  }
+  return {
+    integratedLufs: grab(/I:\s*(-?[\d.]+)\s*LUFS/g),
+    truePeakDb: grab(/Peak:\s*(-?[\d.]+)\s*dBFS/g),
+  }
+}
+
+/**
+ * 把一条成片的音轨归一化到目标响度并限幅。
+ * 视频流用 -c:v copy 直接搬，不重编画面；只有 AAC 音频流被重编。
+ */
+export async function normalizeMix(file, options = {}) {
+  // 只认这四个字段：cwd/log/timeoutMs 是调用参数，不该跟着结果一起存进 job 记录。
+  const picked = {}
+  for (const key of ['normalize', 'lufs', 'truePeak', 'lra']) if (options[key] !== undefined) picked[key] = options[key]
+  const settings = { ...MIX_DEFAULTS, ...picked }
+  if (!existsSync(file)) throw new Error('找不到要归一化的成片：' + file)
+  const cwd = options.cwd || dirname(file)
+  const log = options.log || join(cwd, 'mix.log')
+  const before = await measureLoudness(file, { cwd, log: log.replace(/\.log$/, '-before.log') })
+  if (before.integratedLufs === null) {
+    return { applied: false, reason: '这条片子没有音轨，跳过响度归一', before, after: before, settings }
+  }
+  // 已经在目标附近就别再动它：反复归一化会有零点几 LU 的漂移。
+  const close = Math.abs(before.integratedLufs - settings.lufs) <= 0.5
+  const safe = before.truePeakDb === null || before.truePeakDb <= settings.truePeak + 0.35
+  if (close && safe) {
+    return { applied: false, reason: '响度已在目标附近（' + before.integratedLufs + ' LUFS）', before, after: before, settings }
+  }
+
+  const measureText = await runFfmpeg([
+    '-i', file,
+    '-af', 'loudnorm=I=' + settings.lufs + ':TP=' + settings.truePeak + ':LRA=' + settings.lra + ':print_format=json',
+    '-f', 'null', '-',
+  ], { cwd, log: log.replace(/\.log$/, '-measure.log'), timeoutMs: options.timeoutMs })
+  const measured = parseLoudnormJson(measureText)
+  if (!measured) throw new Error('loudnorm 没给出测量结果，无法归一化')
+
+  // 限幅器比目标再低 1dB：AAC 编码会在取样间造出新的过冲。
+  // 但过冲的大小取决于素材（-14 LUFS 比 -16 压得更狠，过冲也更大），
+  // 所以不能靠固定余量赌：编完量一次，还在目标之上就按实测差值再压一轮。
+  let limitDb = settings.truePeak - 1.0
+  let after = null
+  const temporary = join(dirname(file), basename(file, '.mp4') + '.mixing.mp4')
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    // 第一轮：loudnorm 归一到目标 + 限幅。第二轮只挂限幅器 ——
+    // 文件已经是目标响度了，再跑一遍 loudnorm 会拿上一轮的测量值再加一次增益（实测 +1.2 LU）。
+    const limiter = 'alimiter=limit=' + Math.pow(10, limitDb / 20).toFixed(4) + ':attack=5:release=50:level=0'
+    const filter = attempt === 0
+      ? [
+        'loudnorm=I=' + settings.lufs + ':TP=' + settings.truePeak + ':LRA=' + settings.lra,
+        'measured_I=' + measured.input_i,
+        'measured_TP=' + measured.input_tp,
+        'measured_LRA=' + measured.input_lra,
+        'measured_thresh=' + measured.input_thresh,
+        'offset=' + (measured.target_offset || 0),
+        'linear=true',
+        'print_format=summary',
+      ].join(':') + ',' + limiter
+      : limiter
+
+    try {
+      await runFfmpeg([
+        '-i', file,
+        '-map', '0:v:0',
+        '-map', '0:a:0',
+        '-af', filter,
+        '-c:v', 'copy',
+        '-c:a', 'aac', '-b:a', '192k', '-ar', '48000',
+        '-movflags', '+faststart',
+        temporary,
+      ], { cwd, log, timeoutMs: options.timeoutMs })
+      renameSync(temporary, file)
+    } catch (error) {
+      rmSync(temporary, { force: true })
+      throw error
+    }
+    after = await measureLoudness(file, { cwd, log: log.replace(/\.log$/, '-after.log') })
+    const overshoot = after.truePeakDb === null ? 0 : after.truePeakDb - settings.truePeak
+    if (overshoot <= 0) break
+    // 第二轮只压限幅器，不再重算 loudnorm 的测量值：响度已经到位了。
+    limitDb -= overshoot + 0.3
+  }
+  return { applied: true, before, after, settings, measured, limitDb }
+}
+
+/** 一行给人看的结论。 */
+export function describeMix(mix) {
+  if (!mix) return ''
+  if (!mix.applied) return '响度：' + (mix.reason || '未处理')
+  const before = mix.before.integratedLufs === null ? '—' : mix.before.integratedLufs + ' LUFS'
+  const after = mix.after.integratedLufs === null ? '—' : mix.after.integratedLufs + ' LUFS'
+  const peakBefore = mix.before.truePeakDb === null ? '—' : mix.before.truePeakDb + ' dBFS'
+  const peakAfter = mix.after.truePeakDb === null ? '—' : mix.after.truePeakDb + ' dBFS'
+  return '响度：' + before + ' → ' + after + '，真峰值 ' + peakBefore + ' → ' + peakAfter
+}

package/lib/motion/beats.js

@@ -0,0 +1,337 @@
+// 节拍检测：把音频解成单声道 PCM，用能量包络的瞬时差找重音，用自相关估 BPM，
+// 再用最小二乘把重音序列拟合成等距网格（原版 music-beat-sync 的核心一步）。
+//
+// 为什么必须拟合网格：beat_track 类的 BPM 标量常偏 2%+，直接按 BPM 推拍子，
+// 30 秒后会漂掉一整个拍。拿到重音时刻后再回归直线 t_i = t0 + i*T，
+// 才能真正拿到"可信网格"，残差就是自检指标（≤±15ms 才算机器鼓点）。
+//
+// 结果永远带 confidence / residualMs / reliable：
+// 置信度低、残差大时调用方应当只做参考，不要硬对。
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { existsSync } from 'node:fs'
+import { ffmpegBinary } from '../video-export.js'
+
+const exec = promisify(execFile)
+const SAMPLE_RATE = 22050
+const HOP = 512
+const WINDOW = 1024
+
+export async function decodePcm(file) {
+  if (!existsSync(file)) throw new Error('找不到音频文件：' + file)
+  const { stdout } = await exec(ffmpegBinary(), ['-hide_banner', '-loglevel', 'error', '-i', file, '-vn', '-ac', '1', '-ar', String(SAMPLE_RATE), '-f', 's16le', '-'], { encoding: 'buffer', windowsHide: true, timeout: 120000, maxBuffer: 256 * 1024 * 1024 })
+  return { pcm: stdout, sampleRate: SAMPLE_RATE, hop: HOP, window: WINDOW }
+}
+
+// 能量（对数）+ 半波整流差 = 重音包络。
+export function onsetEnvelope(pcm, sampleRate = SAMPLE_RATE, hop = HOP, window = WINDOW) {
+  const count = Math.max(0, Math.floor((pcm.length / 2 - window) / hop))
+  const energy = new Float64Array(count)
+  for (let index = 0; index < count; index++) {
+    let sum = 0
+    const start = index * hop * 2
+    for (let offset = 0; offset < window * 2; offset += 2) {
+      const sample = pcm.readInt16LE(start + offset) / 32768
+      sum += sample * sample
+    }
+    energy[index] = Math.log1p(Math.sqrt(sum / window) * 12)
+  }
+  const flux = new Float64Array(count)
+  for (let index = 1; index < count; index++) flux[index] = Math.max(0, energy[index] - energy[index - 1])
+  // 三点平滑，压掉单帧毛刺
+  const smooth = new Float64Array(count)
+  for (let index = 1; index < count - 1; index++) smooth[index] = (flux[index - 1] + flux[index] * 2 + flux[index + 1]) / 4
+  return { flux: smooth, framesPerSecond: sampleRate / hop, seconds: (count * hop) / sampleRate, energy }
+}
+
+/** RBJ 二阶带通（分频段看鼓件用；不分频段时 kick 会把 snare 埋掉）。 */
+function bandpassCoefficients(sampleRate, lo, hi) {
+  const f0 = Math.sqrt(lo * hi)
+  const q = Math.max(0.4, f0 / Math.max(1, hi - lo))
+  const w0 = (2 * Math.PI * f0) / sampleRate
+  const alpha = Math.sin(w0) / (2 * q)
+  const cos = Math.cos(w0)
+  const a0 = 1 + alpha
+  return {
+    b0: alpha / a0, b1: 0, b2: -alpha / a0, a1: (-2 * cos) / a0, a2: (1 - alpha) / a0,
+  }
+}
+
+function applyBiquad(samples, coefficients) {
+  const out = new Float64Array(samples.length)
+  let x1 = 0, x2 = 0, y1 = 0, y2 = 0
+  for (let index = 0; index < samples.length; index++) {
+    const x0 = samples[index]
+    const y0 = coefficients.b0 * x0 + coefficients.b1 * x1 + coefficients.b2 * x2 - coefficients.a1 * y1 - coefficients.a2 * y2
+    x2 = x1; x1 = x0; y2 = y1; y1 = y0
+    out[index] = y0
+  }
+  return out
+}
+
+function toSamples(pcm) {
+  const samples = new Float64Array(Math.floor(pcm.length / 2))
+  for (let index = 0; index < samples.length; index++) samples[index] = pcm.readInt16LE(index * 2) / 32768
+  return samples
+}
+
+/** 某个频段的能量包络（把整段 PCM 滤波后逐窗求 RMS）。 */
+function bandEnvelope(samples, sampleRate, lo, hi, hop = HOP, window = WINDOW) {
+  const filtered = applyBiquad(samples, bandpassCoefficients(sampleRate, lo, hi))
+  const count = Math.max(0, Math.floor((filtered.length - window) / hop))
+  const envelope = new Float64Array(count)
+  for (let index = 0; index < count; index++) {
+    let sum = 0
+    const start = index * hop
+    for (let offset = 0; offset < window; offset++) sum += filtered[start + offset] ** 2
+    envelope[index] = Math.sqrt(sum / window)
+  }
+  return envelope
+}
+
+function autocorrelation(values, minLag, maxLag) {
+  let bestLag = 0, bestScore = 0
+  for (let lag = Math.round(minLag); lag <= Math.round(maxLag); lag++) {
+    let score = 0
+    for (let index = lag; index < values.length; index++) score += values[index] * values[index - lag]
+    score /= values.length - lag
+    if (score > bestScore) { bestScore = score; bestLag = lag }
+  }
+  return { lag: bestLag, score: bestScore }
+}
+
+/**
+ * 最小二乘拟合等距网格：t_i = t0 + i*T。
+ *
+ * 先把每个重音时刻归到最近格点上，再对 (i, t) 做一次直线回归；
+ * 迭代两轮即可稳定（第一轮用 BPM 推的 T，第二轮用回归出的 T）。
+ */
+export function fitGrid(times, periodGuess, tolerance = 0.02) {
+  if (times.length < 4 || !(periodGuess > 0)) return null
+  let period = periodGuess
+  let t0 = times[0]
+  let inliers = times
+  // 两轮：用上一轮的"在格点上的重音"重新回归，把杂音（半拍、漏检）剔出去。
+  // 索引必须逐拍累加而不是全局 round((t-t0)/T)：BPM 初值偏 2% 时，
+  // 几十拍之后全局取整会整体错位一格，回归出来的残差全是假的。
+  for (let round = 0; round < 2; round++) {
+    const offsets = times.map((t) => {
+      const ratio = (t - t0) / period
+      return (ratio - Math.round(ratio)) * period
+    })
+    const picked = []
+    for (let index = 0; index < times.length; index++) if (Math.abs(offsets[index]) <= tolerance) picked.push(times[index])
+    if (picked.length < Math.max(4, times.length * 0.3)) return null
+    inliers = picked
+    const indices = [0]
+    for (let k = 1; k < inliers.length; k++) indices.push(indices[k - 1] + Math.max(1, Math.round((inliers[k] - inliers[k - 1]) / period)))
+    const n = indices.length
+    const sumI = indices.reduce((s, value) => s + value, 0)
+    const sumT = inliers.reduce((s, value) => s + value, 0)
+    const sumII = indices.reduce((s, value) => s + value * value, 0)
+    const sumIT = indices.reduce((s, value, k) => s + value * inliers[k], 0)
+    const denominator = n * sumII - sumI * sumI
+    if (!denominator) return null
+    period = (n * sumIT - sumI * sumT) / denominator
+    t0 = (sumT - period * sumI) / n
+    if (!(period > 0.2 && period < 2)) return null
+  }
+  let residual = 0
+  for (const t of inliers) {
+    const ratio = (t - t0) / period
+    residual = Math.max(residual, Math.abs(ratio - Math.round(ratio)) * period)
+  }
+  return { period, t0, residualMs: residual * 1000, bpm: 60 / period, coverage: inliers.length / times.length }
+}
+
+/** 0.5x / 1x / 2x 三个候选里选覆盖真实重音最多的那个（半倍帧歧义必查）。 */
+function bestGrid(times, bpm) {
+  const candidates = [bpm * 0.5, bpm, bpm * 2].filter((value) => value >= 55 && value <= 210)
+  let best = null
+  for (const value of candidates) {
+    const grid = fitGrid(times, 60 / value)
+    if (!grid) continue
+    const score = grid.coverage - Math.min(0.5, grid.residualMs / 200)
+    if (!best || score > best.score) best = { ...grid, score }
+  }
+  // 覆盖率太低说明"重音根本不在这条网格上"——宁可报 null，也不要给个假拍子。
+  if (!best || best.coverage < 0.45) return null
+  return best
+}
+
+/**
+ * 音源自身的峰值滞后：很多素材的能量峰不在文件头（渐强、前置气口），
+ * 按文件头对齐等于晚到。返回秒数，调用方换算成帧再扣。
+ */
+export function peakLagSeconds(pcm, sampleRate = SAMPLE_RATE) {
+  const samples = toSamples(pcm)
+  const hop = 256
+  const window = 1024
+  const count = Math.max(1, Math.floor((samples.length - window) / hop))
+  const envelope = new Float64Array(count)
+  for (let index = 0; index < count; index++) {
+    let sum = 0
+    const start = index * hop
+    for (let offset = 0; offset < window; offset++) sum += samples[start + offset] ** 2
+    envelope[index] = Math.sqrt(sum / window)
+  }
+  let max = 0
+  for (const value of envelope) if (value > max) max = value
+  if (max <= 0) return 0
+  for (let index = 0; index < count; index++) {
+    if (envelope[index] >= max * 0.35) return (index * hop) / sampleRate
+  }
+  return 0
+}
+
+/**
+ * 把包络上的重音帧细化到采样级。
+ *
+ * 能量包络的峰值天然比真实攻击早半个窗（窗口把声音"提前"看见了），
+ * 实测能差 20–40ms——在 30fps 下就是 1 帧多，足够毁掉卡点。
+ * 这里回到原始采样，找攻击上升沿的第一个显著点。
+ */
+function refineOnsets(pcm, sampleRate, frames, hop, window) {
+  const total = Math.floor(pcm.length / 2)
+  const out = []
+  for (const frame of frames) {
+    const start = Math.max(0, (frame - 2) * hop)
+    const end = Math.min(total, (frame + 2) * hop + window)
+    let peak = 0
+    for (let index = start; index < end; index++) peak = Math.max(peak, Math.abs(pcm.readInt16LE(index * 2) / 32768))
+    if (peak <= 0.002) { out.push((frame * hop) / sampleRate); continue }
+    let found = -1
+    for (let index = start; index < end; index++) {
+      if (Math.abs(pcm.readInt16LE(index * 2) / 32768) >= peak * 0.35) { found = index; break }
+    }
+    out.push(((found >= 0 ? found : frame * hop)) / sampleRate)
+  }
+  return out
+}
+
+export async function analyzeBeats(file, options = {}) {
+  const { pcm, sampleRate, hop, window } = await decodePcm(file)
+  const { flux, framesPerSecond, seconds, energy } = onsetEnvelope(pcm, sampleRate, hop, window)
+  if (!flux.length) return { bpm: null, confidence: 0, beats: [], duration: 0, method: 'onset-flux-v2' }
+
+  const minLag = framesPerSecond * 60 / (options.maxBpm || 200)
+  const maxLag = framesPerSecond * 60 / (options.minBpm || 60)
+  const { lag, score } = autocorrelation(flux, minLag, maxLag)
+  const roughBpm = lag ? (60 * framesPerSecond) / lag : null
+
+  let mean = 0
+  for (const value of flux) mean += value
+  mean /= flux.length
+  let variance = 0
+  for (const value of flux) variance += (value - mean) ** 2
+  variance /= flux.length
+  const threshold = mean + Math.sqrt(variance) * 0.9
+
+  const beats = [], minGap = Math.round(framesPerSecond * (options.minGap || 0.16))
+  for (let index = 1; index < flux.length - 1; index++) {
+    const value = flux[index]
+    if (value < threshold || value < flux[index - 1] || value < flux[index + 1]) continue
+    const frame = index
+    if (beats.length && frame - beats[beats.length - 1].frame < minGap) {
+      if (value > beats[beats.length - 1].strength) beats[beats.length - 1] = { frame, strength: value }
+      continue
+    }
+    beats.push({ frame, strength: value })
+  }
+
+  const strengths = beats.map((beat) => beat.strength)
+  const strengthMean = strengths.reduce((sum, value) => sum + value, 0) / Math.max(1, strengths.length)
+  const contrast = strengthMean > 0 ? Math.min(1, (strengthMean - mean) / (strengthMean || 1)) : 0
+  const expected = roughBpm ? Math.max(1, (seconds * roughBpm / 60) * 0.5) : Math.max(1, beats.length)
+  const coverage = Math.min(1, beats.length / expected)
+  const base = contrast * 0.6 + Math.min(1, score * 4) * 0.4
+  const confidence = Math.max(0, Math.min(1, base * (0.3 + 0.7 * coverage)))
+
+  // 拍点太少（氛围铺底、纯音效）时自相关也能凑出一个 BPM，但那是假的：
+  // 宁可报 null，也不要让上层拿一个 199 BPM 去对 15 秒里 4 个重音。
+  const reliable = beats.length >= 6 && confidence >= 0.35
+  const times = refineOnsets(pcm, sampleRate, beats.map((beat) => beat.frame), hop, window)
+  const grid = reliable && roughBpm ? bestGrid(times, roughBpm) : null
+
+  // 分频段把重音归类：kick 驱动"被砸"的一拍，snare 驱动"换一件事"，hihat 驱动微动。
+  let hits = []
+  if (beats.length) {
+    const samples = toSamples(pcm)
+    const bands = {
+      kick: bandEnvelope(samples, sampleRate, 40, 160),
+      snare: bandEnvelope(samples, sampleRate, 1200, 3000),
+      hihat: bandEnvelope(samples, sampleRate, 6000, 12000),
+    }
+    hits = beats.map((beat, order) => {
+      const index = Math.min(bands.kick.length - 1, Math.round((beat.frame * hop) / hop))
+      const kick = bands.kick[index] || 0
+      const snare = bands.snare[index] || 0
+      const hihat = bands.hihat[index] || 0
+      const kind = kick >= snare && kick >= hihat ? 'kick' : snare >= hihat ? 'snare' : 'hihat'
+      return { at: Number(times[order].toFixed(3)), strength: round3(beat.strength), kind, kick: round3(kick), snare: round3(snare), hihat: round3(hihat) }
+    })
+  }
+
+  // 结构表：每 4 拍的 RMS 能量，用来给分镜排"高能段/呼吸位"。
+  const structure = []
+  if (grid) {
+    const barFrames = 4 * grid.period
+    for (let at = 0; at + barFrames <= seconds + 0.5; at += barFrames) {
+      const from = Math.floor((at * sampleRate) / hop)
+      const to = Math.min(energy.length, Math.ceil(((at + barFrames) * sampleRate) / hop))
+      let sum = 0, count = 0
+      for (let index = from; index < to; index++) { sum += Math.expm1(energy[index]); count += 1 }
+      structure.push({ at: Number(at.toFixed(2)), rms: Number((count ? sum / count : 0).toFixed(3)) })
+    }
+  }
+
+  const peak = beats.length ? Math.max(...strengths) : 0
+  return {
+    bpm: grid ? Number(grid.bpm.toFixed(2)) : reliable && roughBpm ? Number(roughBpm.toFixed(2)) : null,
+    confidence: Number(confidence.toFixed(2)),
+    reliable,
+    duration: Number(seconds.toFixed(2)),
+    grid: grid ? { t0: Number(grid.t0.toFixed(4)), periodMs: Number((grid.period * 1000).toFixed(2)), residualMs: Number(grid.residualMs.toFixed(1)), coverage: Number(grid.coverage.toFixed(2)) } : null,
+    peakLag: Number(peakLagSeconds(pcm, sampleRate).toFixed(3)),
+    beats: beats.map((beat, order) => ({ at: Number(times[order].toFixed(3)), strength: Number(beat.strength.toFixed(3)) })),
+    hits,
+    structure,
+    strongest: peak,
+    method: 'onset-flux-v2',
+    note: reliable
+      ? (grid && grid.residualMs <= 15 ? '网格残差 ≤15ms，可以按格点卡点' : '残差偏大（可能有变速段），按 hits 的实测时刻卡，别按 BPM 推')
+      : '拍点太少，估不出可信 BPM；beats 只当"重音出现的大致位置"，不要硬吸附',
+  }
+}
+
+function round3(value) {
+  return Number(Number(value || 0).toFixed(3))
+}
+
+// 把 [start,start+duration] 的切点吸到最近的拍子上，越界就原样返回。
+export function snapFrame(frame, beats, fps, tolerance = 4) {
+  let best = frame, bestDistance = Infinity
+  for (const beat of beats) {
+    const target = Math.round(beat.at * fps)
+    const distance = Math.abs(target - frame)
+    if (distance < bestDistance) { bestDistance = distance; best = target }
+  }
+  return bestDistance <= tolerance ? best : frame
+}
+
+/**
+ * 钉帧公式（原版 sound-design §4.6）：
+ *   Sequence.from = 目标峰值帧 − 音源峰值滞后帧 − 输出音轨偏移帧
+ *
+ * 两个偏移都不补时会叠加，实测最重一击晚 0.27s——足够被读成"没卡上"。
+ */
+// 输出音轨的整体滞后（帧）：AAC 编码器 priming 让成片里的声音比画面晚约 1.3 帧。
+// 实测（tmp/test-audio.mjs，120 BPM 点击轨 → 渲染 → 抽回成片音轨量首拍）：
+// 源首拍 0.5000s，成片首拍 0.5430s，差 43ms = 1.29 帧@30fps。
+// 换帧率按 1.28 折算（原版实测 1.27–1.29）。
+export const OUTPUT_AUDIO_OFFSET_F = 1.29
+
+export function pinFrame(targetPeakFrame, sourcePeakLagFrames = 0, outputOffsetFrames = OUTPUT_AUDIO_OFFSET_F) {
+  return Math.max(0, Math.round(targetPeakFrame - (sourcePeakLagFrames || 0) - (outputOffsetFrames || 0)))
+}