dsh-drawai 0.3.3 → 0.4.0

package/lib/motion/edge-speech.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+# edge-tts 说话（一次一句）：拿音频 + 词级时间戳。
+#
+# 为什么要这个脚本，而不是直接调 `py -m edge_tts`：
+#   1) CLI 没有 --words-in-cue（7.3.1 只有 text/voice/rate/volume/pitch/write-media/write-subtitles），
+#      词级边界只能从 Communicate.stream() 的 WordBoundary 事件拿；
+#   2) 走文件传参，不开管道 —— 受限环境里 spawn + pipe 会直接 EPERM。
+#
+# 用法：python edge-speech.py <job.json>
+#   job.json  { "text", "voice", "rate", "pitch", "out": "<mp3 绝对路径>" }
+# 产物：<mp3> 与 <job.json 去掉 .json>+".result.json"
+#   结果 JSON { ok, file, seconds, words:[{text, offsetMs, durMs}], voice }
+#
+# 时长按 CBR 算：edge 输出固定 48kbps 单声道，字节数 / 6000 = 秒，比再起一个 ffmpeg 便宜。
+
+import asyncio
+import json
+import os
+import sys
+
+TICKS_PER_MS = 10000
+
+
+async def run(job):
+    import edge_tts
+
+    out = job["out"]
+    os.makedirs(os.path.dirname(out), exist_ok=True)
+    # boundary 默认是 SentenceBoundary —— 想要词级就必须显式要 WordBoundary，
+    # 否则 stream() 里永远不会出现词边界（中文也一样，是引擎侧的切分）。
+    communicate = edge_tts.Communicate(
+        job["text"],
+        job.get("voice") or "zh-CN-XiaoxiaoNeural",
+        rate=job.get("rate") or "+0%",
+        pitch=job.get("pitch") or "+0Hz",
+        boundary=job.get("boundary") or "WordBoundary",
+    )
+
+    audio = bytearray()
+    words = []
+    sentences = []
+    async for chunk in communicate.stream():
+        kind = chunk.get("type")
+        if kind == "audio":
+            audio.extend(chunk["data"])
+        elif kind in ("WordBoundary", "SentenceBoundary"):
+            entry = {
+                "text": chunk["text"],
+                "offsetMs": round(chunk["offset"] / TICKS_PER_MS),
+                "durMs": round(chunk["duration"] / TICKS_PER_MS),
+                "kind": "word" if kind == "WordBoundary" else "sentence",
+            }
+            (words if kind == "WordBoundary" else sentences).append(entry)
+
+    if not audio:
+        raise RuntimeError("edge-tts 没有返回音频（凭据被拒或文本为空）")
+
+    with open(out, "wb") as handle:
+        handle.write(audio)
+
+    return {
+        "ok": True,
+        "file": out,
+        "seconds": round(len(audio) * 8 / 48000, 3),
+        # 词边界拿不到就退回句边界：至少字幕还能按句落点，不是全空。
+        "words": words or sentences,
+        "sentences": sentences,
+        "voice": job.get("voice") or "zh-CN-XiaoxiaoNeural",
+    }
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("需要 job.json 路径", file=sys.stderr)
+        return 2
+    job_path = sys.argv[1]
+    with open(job_path, "r", encoding="utf-8") as handle:
+        job = json.load(handle)
+    result_path = os.path.splitext(job_path)[0] + ".result.json"
+    try:
+        result = asyncio.run(run(job))
+    except Exception as error:  # 交给调用方决定换 provider，不在这里退出码定生死
+        result = {"ok": False, "error": "%s: %s" % (type(error).__name__, error)}
+    with open(result_path, "w", encoding="utf-8") as handle:
+        json.dump(result, handle, ensure_ascii=False)
+    return 0 if result.get("ok") else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/motion/entry.jsx

@@ -0,0 +1,73 @@
+import React from 'react'
+import { registerRoot, Composition, AbsoluteFill, Sequence, Audio, staticFile, delayRender, continueRender, cancelRender } from 'remotion'
+const defaults = { plan: { width: 1280, height: 720, fps: 30, durationFrames: 90, shots: [], audio: [] }, assets: {} }
+
+// 音频条目的增益曲线：dB → 线性，再叠淡入淡出。
+// volume 回调收到的是"本条 Audio 自己的局部帧"（从 0 开始）。
+function gainOf(cue, local) {
+  let gain = Math.pow(10, (Number(cue.gainDb) || 0) / 20)
+  if (cue.fadeIn > 0) gain *= Math.min(1, local / cue.fadeIn)
+  if (cue.fadeOut > 0) gain *= Math.min(1, (cue.durationInFrames - local) / cue.fadeOut)
+  return Math.max(0, Math.min(4, gain))
+}
+
+// 旁白避让：进入旁白区间压到 -12dB，两端各留 6 帧斜坡。
+function duckFactor(local, windows, depthDb, ramp) {
+  const depth = Math.pow(10, depthDb / 20)
+  let factor = 1
+  for (const window of windows) {
+    if (local >= window.from && local <= window.to) factor = Math.min(factor, depth)
+    else if (local >= window.from - ramp && local < window.from) {
+      factor = Math.min(factor, 1 - (1 - depth) * ((local - (window.from - ramp)) / ramp))
+    } else if (local > window.to && local <= window.to + ramp) {
+      factor = Math.min(factor, depth + (1 - depth) * ((local - window.to) / ramp))
+    }
+  }
+  return factor
+}
+
+export function registerMotionRoot(scenes) {
+  function Movie({ plan, assets }) {
+    const [fontWait] = React.useState(() => plan.bundledFonts ? delayRender('加载内置中文字体') : null)
+    React.useEffect(() => {
+      if (fontWait === null) return
+      Promise.all([document.fonts.load('400 16px "Noto Sans SC"'), document.fonts.load('400 16px "Noto Serif SC"')])
+        .then(() => document.fonts.ready).then(() => continueRender(fontWait)).catch(error => cancelRender(error))
+    }, [fontWait])
+    const fps = plan.fps || 30
+    const audio = Array.isArray(plan.audio) ? plan.audio : []
+    const voices = audio.filter((cue) => cue.role === 'voice')
+      .map((cue) => ({ from: Math.max(0, cue.from - 4), to: cue.from + cue.durationInFrames + 8 }))
+    return (
+      <AbsoluteFill>
+        {plan.bundledFonts && <style>{(plan.fontFaces || []).map(face => `@font-face{font-family:${JSON.stringify(face.family)};src:url(${JSON.stringify(staticFile('fonts/' + face.file))}) format("truetype");font-weight:${face.weight};font-style:${face.style};font-display:block}`).join('\n')}</style>}
+        {plan.shots.map((shot) => {
+          const Component = scenes[shot.id]
+          if (shot.recipeId !== 'scene' || !Component) throw new Error('场景组件缺失：' + shot.id)
+          const allowed = Object.fromEntries(shot.referenceIds.map((id) => [id, assets[id] || []]))
+          // render 是这条片子的渲染规格（samples / shutter / scale）：场景按它决定
+          // 累积几个子帧、开多久快门，不要自己写死数字——写死了改规格就没人跟着改。
+          return <Sequence key={shot.id} from={shot.startFrame} durationInFrames={shot.durationInFrames ?? shot.durationFrames}><Component shot={shot} anchors={shot.anchors || {}} assets={allowed} render={plan.render || {}} /></Sequence>
+        })}
+        {audio.map((cue) => {
+          const local = cue.duck ? voices.map((window) => ({ from: window.from - cue.from, to: window.to - cue.from })) : []
+          return (
+            <Sequence key={cue.id} from={cue.from} durationInFrames={cue.durationInFrames}>
+              <Audio
+                src={staticFile(cue.file)}
+                startFrom={Math.max(0, Math.round((Number(cue.trimStart) || 0) * fps))}
+                loop={cue.loop === true}
+                volume={(frame) => gainOf(cue, frame) * (cue.duck ? duckFactor(frame, local, -12, 6) : 1)}
+              />
+            </Sequence>
+          )
+        })}
+      </AbsoluteFill>
+    )
+  }
+  function Root() {
+    return <Composition id="DrawAiMotion" component={Movie} width={1280} height={720} fps={30} durationInFrames={90} defaultProps={defaults}
+      calculateMetadata={({ props }) => ({ width: props.plan.width, height: props.plan.height, fps: props.plan.fps, durationInFrames: props.plan.durationFrames })} />
+  }
+  registerRoot(Root)
+}

package/lib/motion/export.js

@@ -0,0 +1,200 @@
+// 导出：把一条成片拆成"能在剪映里继续剪"的素材包。
+//
+// 上游 references/jianying-export.md 讲的就是这件事（逐镜头 clip + 独立
+// 字幕轨 + 独立的 SFX/BGM 轨），但仓库里没有实现。这里按文件落地的版本：
+//
+//   clips/shot-N.mp4      逐镜头、无声、按时间轴精确切
+//   audio/bgm-1.mp3       原音轨原文件（带 cue 时间点与增益记录）
+//   subtitles.srt         有字幕数据时写出，剪映可直接导入
+//   shots.json            顺序、进出点、帧号 —— 重建时间轴靠它
+//   README.md             怎么在剪映里拼回去
+//   draft_content.json    draft:true 时的剪映草稿（结构草案，未在剪映里验证）
+//
+// 切镜头用"输入侧 -ss + 重编码"，不是 -c copy：copy 只能从关键帧切，
+// 边界会偏 1–2 秒，而这里必须帧对帧。
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { basename, extname, join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { runFfmpeg } from './ffmpeg.js'
+
+export function exportRoot(dir) {
+  return join(dir, '.out', 'export')
+}
+
+export function exportFolder(dir, name = 'jianying') {
+  return join(exportRoot(dir), name)
+}
+
+const round = (value, digits = 3) => Math.round(value * 10 ** digits) / 10 ** digits
+
+function srtTime(seconds) {
+  const total = Math.max(0, seconds)
+  const pad = (value, size = 2) => String(Math.floor(value)).padStart(size, '0')
+  const hours = Math.floor(total / 3600), minutes = Math.floor((total % 3600) / 60), secs = Math.floor(total % 60)
+  const ms = Math.round((total - Math.floor(total)) * 1000)
+  return pad(hours) + ':' + pad(minutes) + ':' + pad(secs) + ',' + pad(ms, 3)
+}
+
+function subtitleRows(timeline, extra) {
+  const list = Array.isArray(extra) ? extra : Array.isArray(timeline.subtitles) ? timeline.subtitles : []
+  const fps = Number(timeline.fps) || 30
+  return list.map((row, index) => {
+    const fromFrame = Number(row.startFrame ?? row.from ?? 0)
+    const toFrame = Number(row.endFrame ?? row.to ?? fromFrame + Math.round(fps * 2.5))
+    return { index: index + 1, from: fromFrame / fps, to: toFrame / fps, text: String(row.text ?? row.copy ?? '').trim() }
+  }).filter((row) => row.text && row.to > row.from)
+}
+
+function srtSource(rows) {
+  return rows.map((row) => row.index + '\n' + srtTime(row.from) + ' --> ' + srtTime(row.to) + '\n' + row.text + '\n').join('\n')
+}
+
+// 剪映草稿：按 360000 这一版的结构摆出视频/音频/文本三条轨。
+// 只保证结构自洽（材料 id 对得上、时长对得上），不保证剪映各版本都认。
+function jianyingDraft({ timeline, shots, stems, subtitles, folder }) {
+  const fps = Number(timeline.fps) || 30
+  const us = (seconds) => Math.round(seconds * 1e6)
+  const videoMaterials = shots.map((shot) => ({
+    id: randomUUID().toUpperCase(), type: 'video', path: join(folder, 'clips', shot.id + '.mp4'),
+    width: timeline.width, height: timeline.height, duration: us(shot.seconds), has_audio: false, reverse: false,
+  }))
+  const audioMaterials = stems.map((stem) => ({
+    id: randomUUID().toUpperCase(), type: 'extract_music', path: join(folder, stem.source),
+    duration: us(stem.seconds), name: basename(stem.source),
+  }))
+  const textMaterials = subtitles.map((row) => ({
+    id: randomUUID().toUpperCase(), type: 'subtitle', content: row.text, alignment: 1,
+    font_size: 6, text_color: '#2A2724',
+  }))
+  const videoSegments = shots.map((shot, index) => ({
+    id: randomUUID().toUpperCase(), material_id: videoMaterials[index].id, volume: 1, speed: 1,
+    source_timerange: { start: 0, duration: us(shot.seconds) },
+    target_timerange: { start: us(shot.from), duration: us(shot.seconds) },
+  }))
+  const audioSegments = stems.map((stem, index) => ({
+    id: randomUUID().toUpperCase(), material_id: audioMaterials[index].id,
+    volume: round(10 ** (Number(stem.gainDb || 0) / 20), 3), speed: 1,
+    source_timerange: { start: 0, duration: us(stem.seconds) },
+    target_timerange: { start: us(stem.at), duration: us(stem.seconds) },
+  }))
+  const textSegments = subtitles.map((row, index) => ({
+    id: randomUUID().toUpperCase(), material_id: textMaterials[index].id,
+    target_timerange: { start: us(row.from), duration: us(row.to - row.from) },
+  }))
+  return {
+    id: randomUUID().toUpperCase(),
+    version: 360000,
+    fps,
+    duration: us(Number(timeline.durationInFrames) / fps),
+    canvas_config: { width: timeline.width, height: timeline.height, ratio: 'original' },
+    materials: { videos: videoMaterials, audios: audioMaterials, texts: textMaterials },
+    tracks: [
+      { id: randomUUID().toUpperCase(), type: 'video', attribute: 0, segments: videoSegments },
+      { id: randomUUID().toUpperCase(), type: 'audio', attribute: 0, segments: audioSegments },
+      { id: randomUUID().toUpperCase(), type: 'text', attribute: 0, segments: textSegments },
+    ],
+  }
+}
+
+function readmeOf({ timeline, shots, stems, subtitles, missing }) {
+  const fps = Number(timeline.fps) || 30
+  const total = Number(timeline.durationInFrames) / fps
+  const lines = [
+    '# 剪映素材包',
+    '',
+    '这条片子是 ' + timeline.width + '×' + timeline.height + ' / ' + fps + 'fps / ' + total.toFixed(2) + ' 秒，拆成了 '
+      + shots.length + ' 个镜头 + ' + stems.length + ' 条音轨。',
+    '',
+    '## 里面有什么',
+    '',
+    '- `clips/` 逐镜头画面，无声，按时间轴精确切（首尾帧与时间轴一致）。',
+    '- `audio/` 原音轨文件（BGM 与音效分开），时间点与增益见 `audio.json`。',
+    '- `shots.json` 镜头顺序、进出点、帧号。',
+    '- `film.mp4` 完整成片，用来对照。',
+    subtitles ? '- `subtitles.srt` 字幕，剪映里可直接导入为字幕轨。' : '- 没有字幕数据（时间轴里没有 subtitles）。',
+    '',
+    '## 在剪映里拼回去',
+    '',
+    '1. 新建项目，画布设为 ' + timeline.width + '×' + timeline.height + '、' + fps + 'fps。',
+    '2. 按 `shots.json` 的顺序把 `clips/` 拖上主轨，首尾相接——它们是按顺序切好的，中间不要留空。',
+    '3. 按 `audio.json` 的 `at` 秒把 `audio/` 里的文件放到对应位置；BGM 那条是整条铺满的，音效是点。',
+    subtitles
+      ? '4. 字幕：拖入 `subtitles.srt`，剪映会按时间码落到字幕轨。'
+      : '4. 这条片子没有字幕数据；要字幕就回工程里补 subtitles 再导出一次。',
+    '5. 需要改节奏就拖 clip 边界；画面内容要改，回工程里改场景代码重新导出，不要在这边抠图。',
+    '',
+    '## 来源',
+    '',
+    '',
+  ]
+  if (missing.length) lines.splice(lines.indexOf('## 来源'), 0, '## 缺失', '', '这些音轨文件在工程里找不到：' + missing.join('、'), '')
+  return lines.join('\n')
+}
+
+export async function exportPackage({ dir, timeline, name, draft = false, subtitles, film, onProgress }) {
+  if (!timeline || !Array.isArray(timeline.shots) || !timeline.shots.length) throw new Error('时间轴里没有镜头')
+  const source = film || join(dir, '.out', 'film.mp4')
+  if (!existsSync(source)) throw new Error('没有成片可导出：先 motion_render start 出一版（' + source + '）')
+  const fps = Number(timeline.fps) || 30
+  const folder = exportFolder(dir, name)
+  rmSync(folder, { recursive: true, force: true })
+  mkdirSync(join(folder, 'clips'), { recursive: true })
+  mkdirSync(join(folder, 'audio'), { recursive: true })
+
+  const shots = []
+  for (const [index, shot] of timeline.shots.entries()) {
+    const from = shot.startFrame / fps, to = (shot.startFrame + shot.durationFrames) / fps
+    const clip = join(folder, 'clips', shot.id + '.mp4')
+    await runFfmpeg(['-ss', from.toFixed(3), '-to', to.toFixed(3), '-i', source, '-an',
+      '-c:v', 'libx264', '-crf', '18', '-preset', 'veryfast', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', clip],
+      { cwd: folder, timeoutMs: 300000, log: join(exportRoot(dir), 'ff.log') })
+    if (!existsSync(clip)) throw new Error('第 ' + (index + 1) + ' 镜切失败：' + shot.id)
+    shots.push({ id: shot.id, card: shot.card || null, from: round(from), to: round(to), seconds: round(to - from),
+      startFrame: shot.startFrame, durationFrames: shot.durationFrames, clip: 'clips/' + shot.id + '.mp4' })
+    onProgress?.({ stage: 'clips', index: index + 1, total: timeline.shots.length })
+  }
+
+  const stems = []
+  const missing = []
+  for (const cue of (Array.isArray(timeline.audio) ? timeline.audio : [])) {
+    if (!cue.file) continue
+    const from = join(dir, 'assets', cue.file)
+    if (!existsSync(from)) { missing.push(cue.file); continue }
+    const target = join(folder, 'audio', cue.role + '-' + (stems.length + 1) + (extname(cue.file) || '.mp3'))
+    copyFileSync(from, target)
+    stems.push({
+      role: cue.role || 'sfx', source: 'audio/' + basename(target), at: round(Number(cue.from || 0) / fps),
+      seconds: round(Number(cue.durationInFrames || 0) / fps), gainDb: Number(cue.gainDb || 0),
+      fadeIn: round(Number(cue.fadeIn || 0) / fps), fadeOut: round(Number(cue.fadeOut || 0) / fps),
+      loop: Boolean(cue.loop), duck: Boolean(cue.duck),
+    })
+  }
+
+  const rows = subtitleRows(timeline, subtitles)
+  if (rows.length) writeFileSync(join(folder, 'subtitles.srt'), srtSource(rows), 'utf8')
+  copyFileSync(source, join(folder, 'film.mp4'))
+  writeFileSync(join(folder, 'shots.json'), JSON.stringify({
+    width: timeline.width, height: timeline.height, fps,
+    durationInFrames: timeline.durationInFrames, seconds: round(Number(timeline.durationInFrames) / fps), shots,
+  }, null, 2) + '\n', 'utf8')
+  writeFileSync(join(folder, 'audio.json'), JSON.stringify({ fps, cues: stems, missing }, null, 2) + '\n', 'utf8')
+
+  let draftFile = null
+  if (draft) {
+    const content = jianyingDraft({ timeline, shots, stems, subtitles: rows, folder })
+    draftFile = join(folder, 'draft_content.json')
+    writeFileSync(draftFile, JSON.stringify(content, null, 2) + '\n', 'utf8')
+  }
+  writeFileSync(join(folder, 'README.md'), readmeOf({ timeline, shots, stems, subtitles: rows.length, missing }), 'utf8')
+  rmSync(join(folder, 'ff.log'), { force: true })
+  return { folder, shots, stems, subtitles: rows.length, draft: draftFile, missing,
+    seconds: round(Number(timeline.durationInFrames) / fps), files: 2 + shots.length + stems.length + (rows.length ? 1 : 0) + (draftFile ? 1 : 0) }
+}
+
+export function listExports(dir) {
+  const root = exportRoot(dir)
+  if (!existsSync(root)) return []
+  return readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory())
+    .map((entry) => ({ name: entry.name, folder: join(root, entry.name), at: statSync(join(root, entry.name)).mtime.toISOString() }))
+}

package/lib/motion/ffmpeg.js

@@ -0,0 +1,42 @@
+// ffmpeg 调用：stderr 写文件，不走管道。
+//
+// 受限环境下 spawn + pipe 会直接 EPERM（拿不到匿名管道），而文件描述符不受
+// 影响；顺带也绕开了 execFile 的 maxBuffer 上限。帧检和导出都走这一个入口。
+
+import { existsSync, openSync, closeSync, readFileSync } from 'node:fs'
+import { join, isAbsolute } from 'node:path'
+import { spawn } from 'node:child_process'
+import { ffmpegBinary } from '../video-export.js'
+
+export function runFfmpeg(args, options = {}) {
+  const cwd = options.cwd || process.cwd()
+  const logPath = isAbsolute(options.log || '') ? options.log : join(cwd, options.log || 'ff.log')
+  return new Promise((resolve, reject) => {
+    let fd
+    try {
+      fd = openSync(logPath, 'w')
+    } catch (error) {
+      reject(error)
+      return
+    }
+    const child = spawn(ffmpegBinary(), ['-hide_banner', '-nostdin', '-y', ...args], {
+      cwd, windowsHide: true, stdio: ['ignore', 'ignore', fd],
+    })
+    const timer = setTimeout(() => child.kill(), options.timeoutMs || 300000)
+    const finish = (code, error) => {
+      clearTimeout(timer)
+      try { closeSync(fd) } catch { /* 已关 */ }
+      let stderr = ''
+      try { stderr = readFileSync(logPath, 'utf8') } catch { /* 没有日志 */ }
+      if (error) reject(Object.assign(error, { stderr }))
+      else if (code === 0 || options.allowFail) resolve(stderr)
+      else reject(Object.assign(new Error('ffmpeg 退出码 ' + code + '：' + stderr.trim().split('\n').slice(-2).join(' ')), { stderr }))
+    }
+    child.on('error', (error) => finish(-1, error))
+    child.on('close', (code) => finish(code))
+  })
+}
+
+export function ffmpegAvailable() {
+  return existsSync(ffmpegBinary())
+}

package/lib/motion/fonts.js

@@ -0,0 +1,71 @@
+// Fonts copied into a video project's public assets.
+//
+// 字体不在 npm 包里（约 135MB），由 asset-pack.js 解析：开发目录里直接用，安装版从
+// `~/.dsh/drawai-assets/` 读（首次使用自动下载）。所以这里**不能在模块导入期读文件**，
+// 一律走 fontFaces() 之类的函数，缺素材时由调用方 catch 并提示用户。
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { fontsDir } from './asset-pack.js'
+
+const BASIC_FAMILIES = new Set(['Noto Sans SC', 'Noto Serif SC'])
+let cachedFaces = null
+
+/** 内置字体清单（font-faces.json）。素材没装好时返回空数组。 */
+export function fontFaces() {
+  if (cachedFaces) return cachedFaces
+  const dir = fontsDir()
+  if (!dir) return []
+  const file = join(dir, 'font-faces.json')
+  if (!existsSync(file)) return []
+  cachedFaces = JSON.parse(readFileSync(file, 'utf8')).faces || []
+  return cachedFaces
+}
+
+/** 字体文件名列表（缺素材时为空）。 */
+export function bundledFontNames() {
+  return fontFaces().map(face => face.file)
+}
+
+function referencedFamilies(projectDir) {
+  let text = ''
+  function visit(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!['assets', '.out', 'node_modules', '.git'].includes(entry.name)) visit(join(dir, entry.name))
+      } else if (entry.isFile() && /\.(?:[cm]?[jt]sx?|css)$/i.test(entry.name)) {
+        text += '\n' + readFileSync(join(dir, entry.name), 'utf8')
+      }
+    }
+  }
+  visit(projectDir)
+  const normalized = text.toLowerCase().replace(/[^a-z0-9]/g, '')
+  return new Set(fontFaces().filter(face => normalized.includes(face.family.toLowerCase().replace(/[^a-z0-9]/g, ''))).map(face => face.family))
+}
+
+export function writeBundledFonts(projectDir) {
+  const root = fontsDir()
+  if (!root) throw new Error('动效素材包还没就绪（缺字体目录）：请先让插件下载素材包')
+  const dest = join(projectDir, 'assets', 'fonts')
+  mkdirSync(dest, { recursive: true })
+  const needed = referencedFamilies(projectDir)
+  for (const face of fontFaces()) {
+    if (!BASIC_FAMILIES.has(face.family) && !needed.has(face.family)) continue
+    const name = face.file
+    const source = join(root, name), target = join(dest, name)
+    if (!existsSync(source)) throw new Error('插件缺少内置字体：' + name)
+    if (!existsSync(target)) copyFileSync(source, target)
+  }
+  const notices = fileURLToPath(new URL('../../LICENSE', import.meta.url))
+  const targetNotice = join(dest, 'DRAWAI-NOTICES.txt')
+  if (existsSync(notices) && !existsSync(targetNotice)) copyFileSync(notices, targetNotice)
+}
+
+export function hasBundledFonts(projectDir) {
+  return fontFaces().filter(face => BASIC_FAMILIES.has(face.family)).every(face => existsSync(join(projectDir, 'assets', 'fonts', face.file)))
+}
+
+export function availableBundledFontFaces(projectDir) {
+  return fontFaces().filter(face => existsSync(join(projectDir, 'assets', 'fonts', face.file)))
+}

package/lib/motion/jobs.js

@@ -0,0 +1,113 @@
+// 异步任务表：让"开始渲染"立刻返回，把等待交给下一次工具调用。
+//
+// 之前 58 分钟里有 24.8 分钟是一次次 `Start-Sleep 100` 睡出来的。
+// 规矩很简单：任何超过 5 秒的动作都返回 jobId，绝不 await 到结束。
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { parseProjectJson } from './json.js'
+
+let sequence = 0
+
+export class RenderJobs {
+  constructor() {
+    this.jobs = new Map()
+  }
+
+  file(dir) {
+    return join(dir, '.out', 'jobs.json')
+  }
+
+  load(dir) {
+    try {
+      if (!existsSync(this.file(dir))) return []
+      const raw = parseProjectJson(readFileSync(this.file(dir), 'utf8'))
+      return Array.isArray(raw) ? raw : []
+    } catch { return [] }
+  }
+
+  save(job) {
+    const dir = job.dir
+    if (!dir) return
+    mkdirSync(join(dir, '.out'), { recursive: true })
+    const list = this.load(dir).filter((item) => item.id !== job.id)
+    list.push(job)
+    writeFileSync(this.file(dir), JSON.stringify(list.slice(-40), null, 2) + '\n', 'utf8')
+  }
+
+  create(init) {
+    sequence += 1
+    const job = {
+      id: 'job-' + Date.now().toString(36) + '-' + sequence,
+      kind: init.kind || 'render',
+      dir: init.dir,
+      nodeId: init.nodeId,
+      status: 'queued',
+      phase: 'queued',
+      progress: 0,
+      createdAt: new Date().toISOString(),
+      endedAt: null,
+      output: null,
+      error: null,
+    }
+    this.jobs.set(job.id, job)
+    this.save(job)
+    return job
+  }
+
+  update(job, patch) {
+    Object.assign(job, patch)
+    this.save(job)
+    return job
+  }
+
+  // 进度只在内存里刷：每 1% 写一次盘既慢又没意义。
+  progress(job, phase, value) {
+    if (phase) job.phase = phase
+    if (Number.isFinite(value)) job.progress = value
+    return job
+  }
+
+  // 把一次 renderProject 的句柄挂到 job 上，状态变化全部写回表。
+  attach(job, handle) {
+    job._cancel = handle.cancel
+    this.update(job, { status: 'running', phase: 'bundling' })
+    handle.promise.then(
+      (result) => this.update(job, { status: 'done', phase: 'done', progress: 1, endedAt: new Date().toISOString(), output: handle.output, frames: result.frames || null,
+        mix: result.mix || null, mixError: result.mixError || null }),
+      (error) => this.update(job, { status: 'failed', phase: 'failed', endedAt: new Date().toISOString(), error: error.message || String(error) }),
+    )
+    return job
+  }
+
+  get(id) {
+    return this.jobs.get(id) || null
+  }
+
+  list(dir) {
+    const fromDisk = this.load(dir)
+    const height = new Map(fromDisk.map((item) => [item.id, item]))
+    for (const job of this.jobs.values()) if (job.dir === dir) height.set(job.id, { ...job, _cancel: undefined })
+    return [...height.values()].sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
+  }
+
+  cancel(id) {
+    const job = this.jobs.get(id)
+    if (!job) return false
+    job._cancel?.()
+    this.update(job, { status: 'canceled', phase: 'canceled', endedAt: new Date().toISOString() })
+    return true
+  }
+}
+
+/**
+ * 回填时该取哪一种任务。主视频节点（建过工程的）等的是整片 film；
+ * 另建的「样片」节点等的是 pilot。调用方显式给了 source 就以它为准。
+ *
+ * 以前没有这个区分：apply 只找"最新一版 film"，而样片 range 渲染写的也是 film.mp4，
+ * 于是 4 秒样片会被当成整片写进主节点。
+ */
+export function applyJobKind({ source, targetHasProject }) {
+  if (source === 'pilot' || source === 'film') return source
+  return targetHasProject ? 'film' : 'pilot'
+}

package/lib/motion/json.js

@@ -0,0 +1,4 @@
+// UTF-8 editors on Windows may prepend a BOM; it is not part of JSON content.
+export function parseProjectJson(text) {
+  return JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text)
+}

package/lib/motion/media-catalog.js

@@ -0,0 +1,59 @@
+// Bundled upstream media. Only requested files are copied into a project.
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { mediaLibraryRoot } from './asset-pack.js'
+import { captureAsset, readAssets, writeAssets } from './assets.js'
+
+// 素材库不在 npm 包里，位置由 asset-pack 解析；没装好时这些查询返回空。
+const root = () => mediaLibraryRoot()
+const indexPath = () => join(root() || '', 'upstream-files.json')
+const checksumPath = () => join(root() || '', 'checksums.sha256.json')
+const commit = '49052d80bfaf9fa8412cc9710530e5e95a3b8d8c'
+const labels = { paper:'纸张', grain:'颗粒', dust:'灰尘', washi:'胶带', piano:'钢琴', harp:'竖琴', glock:'钟琴', marimba:'马林巴', kalimba:'拇指琴', vibraphone:'颤音琴', timpani:'定音鼓', woodblock:'木鱼', crash:'镲', suscymbal:'吊镲', cabasa:'卡巴萨', guiro:'刮胡', slapstick:'拍板', vibraslap:'颤响器', wineglass:'酒杯' }
+
+export function listMediaLibrary({ query = '', category = '' } = {}) {
+  if (!existsSync(indexPath())) return []
+  const index = JSON.parse(readFileSync(indexPath(), 'utf8'))
+  if (index.commit !== commit || !Array.isArray(index.files)) throw new Error('内置素材库索引无效')
+  const q = String(query).trim().toLowerCase(), cat = String(category).trim().toLowerCase()
+  return index.files.map(item => {
+    if (typeof item.path !== 'string' || item.path.split('/').some(part => !part || part === '.' || part === '..' || part.includes('\\'))) throw new Error('内置素材库路径无效')
+    const image = item.path.startsWith('assets/textures/')
+    const audio = item.path.startsWith('lib/audio/samples/') && item.path.endsWith('.flac')
+    if (!image && !audio) throw new Error('内置素材库路径无效')
+    const group = item.path.split('/')[image ? 2 : 3], name = item.path.split('/').at(-1)
+    return { id: item.path, name, category: group, categoryName: labels[group] || group,
+      kind: image ? 'image' : 'audio', bytes: item.size, gitSha: item.sha,
+      license: audio || name === 'Paper001_4K_color.jpg' ? 'CC0-1.0' : '上游未逐项列明',
+      source: 'https://github.com/Vincentwei1021/mg-styles-15/blob/' + commit + '/' + item.path.split('/').map(encodeURIComponent).join('/') }
+  }).filter(item => existsSync(join(root() || '', ...item.id.split('/'))))
+    .filter(item => (!cat || [item.category, item.categoryName, item.kind].some(v => v.toLowerCase() === cat))
+    && (!q || [item.name, item.category, item.categoryName, item.id].some(v => v.toLowerCase().includes(q))))
+}
+
+export async function importMediaLibrary(projectDir, id) {
+  const item = listMediaLibrary().find(entry => entry.id === id)
+  if (!item) throw new Error('未找到内置素材，请先使用 motion_assets library 获取 id')
+  const file = join(root() || '', ...item.id.split('/'))
+  if (!existsSync(file)) throw new Error('插件素材文件缺失：' + item.id)
+  const data = readFileSync(file)
+  const hash = createHash('sha1').update(`blob ${data.length}\0`).update(data).digest('hex')
+  const sha256 = createHash('sha256').update(data).digest('hex')
+  const upstreamMatches = data.length === item.bytes && hash === item.gitSha
+  let expectedSha256 = null
+  try { expectedSha256 = JSON.parse(readFileSync(checksumPath(), 'utf8')).files[item.id]?.sha256 || null } catch { /* optional diagnostic manifest */ }
+  const warnings = []
+  if (!upstreamMatches) warnings.push('素材与上游 Git SHA-1 或大小不一致，已按本地实际文件导入')
+  if (expectedSha256 && expectedSha256 !== sha256) warnings.push('素材与插件 SHA-256 校验清单不一致，已按本地实际文件导入')
+  if (!expectedSha256) warnings.push('插件 SHA-256 校验清单缺少该素材')
+  const license = upstreamMatches ? item.license : '未确认（本地内容与上游记录不一致）'
+  const source = upstreamMatches ? item.source : '插件内置文件（上游参考：' + item.source + '）'
+  const entry = await captureAsset(projectDir, file, { source, license,
+    caption: `${item.categoryName}: ${item.name}（${license}）` })
+  const integrity = { sha256, expectedSha256, gitSha1: hash, expectedGitSha1: item.gitSha, warnings }
+  const manifest = readAssets(projectDir)
+  const saved = manifest.items.find(value => value.file === entry.file)
+  if (saved) { saved.libraryId = item.id; saved.integrity = integrity; saved.source = source; saved.license = license; writeAssets(projectDir, manifest) }
+  return { ...entry, source, libraryId: item.id, license, integrity }
+}