framevideo-media

FrameVideo 媒体预处理

适用场景

在以下场景中使用此技能：

• 文本转语音（TTS） — 将文本生成为旁白（本地 Kokoro）
• 背景音乐（BGM） — 从 Chanjing 平台下载音乐曲目
• 音效（SFX） — 下载简短的音频提示音（点击声、呼啸声、撞击声）
• 转录 — 将音频／视频转换为带时间戳的字幕（Whisper）
• 背景移除 — 从视频／图像创建透明叠加素材（u2net）
• 音频工作流 — 串联命令（TTS → 转录 → 字幕）

不要使用

以下场景请勿使用此技能：

• 数字人视频 — 使用 chanjing-digital-human
• Chanjing OAuth 设置 — 使用 chanjing-auth
• SSML 发音控制 — 使用 framevideo-voiceover-ssml
• 合成 HTML — 使用 framevideo
• 在合成内容中播放音频 — 使用 framevideo（此技能仅用于生成素材）

---

快速入门

按 3 个步骤生成旁白和字幕：

# 1. Generate TTS audio
npx framevideo tts "Hello from FrameVideo" --output assets/narration.wav

# 2. Transcribe to get timestamps
npx framevideo transcribe assets/narration.wav --output assets/transcript.json

# 3. Reference in composition
# In index.html:
# <audio data-src="assets/narration.wav" data-start="0" data-track-index="10"></audio>

生成背景音乐：

# 1. Authenticate (one-time)
npx framevideo auth login

# 2. Browse music
npx framevideo chanjing music list --category <id> --compact

# 3. Download
npx framevideo chanjing music download --id <music-id> --output assets/music/bg.mp3

---

背景音乐与音效

有意区分并使用 Chanjing 的两种音频路径：

• 背景音乐（BGM）：chanjing music，完整曲目或副歌，assets/music/，默认 data-volume="0.12"，默认 data-track-index="20"。
• 音效（SFX）：chanjing sound-effect 或 chanjing sfx，简短的事件提示音，assets/sfx/，默认 data-volume="0.8"，默认 data-track-index="30"。
• 引用音频前，两者都必须先下载到本地项目素材中；绝不要在合成 HTML 中直接使用 Chanjing／OSS 远程 URL。

背景音乐（chanjing music）

当用户需要背景音乐、BGM、配乐，或从 Chanjing 曲库中提取副歌时，请使用基于 Chanjing OAuth 的平台音乐。该命令会将选定曲目下载到本地项目素材中，并输出 <audio> 片段；绝不要在合成 HTML 中直接放入 Chanjing／OSS 远程 URL。

npx framevideo auth status
npx framevideo chanjing music categories --json
npx framevideo chanjing music list --category <category-id> --compact
npx framevideo chanjing music download --id <music-id> --output assets/music/<name>.mp3 --volume 0.12
npx framevideo chanjing music download --id <music-id> --chorus --duration 10 --json

默认值：

• 若未指定 --output，素材将下载到 assets/music/。
• --output 支持 <name> 和 <id> 占位符。
• 建议背景音量默认为 0.12；仅在没有旁白时才调高至 0.22 左右。
• --chorus 会调用 Chanjing 副歌提取端点并下载返回的片段。

音效（chanjing sound-effect / chanjing sfx）

当用户需要 UI 点击声、呼啸声、转场声、撞击声、通知音或其他简短提示音时，请使用基于 Chanjing OAuth 的平台音效。该命令会将选定音效下载到本地项目素材中，并输出 <audio> 片段。

npx framevideo auth status
npx framevideo chanjing music categories --json     # shared audio category hints
npx framevideo chanjing sound-effect list --category <category-id> --compact
npx framevideo chanjing sound-effect download --id <effect-id> --output assets/sfx/<name>.mp3 --volume 0.8
npx framevideo chanjing sfx download --id <effect-id> --start 2.4 --json

默认值：

• 若未指定 --output，素材将下载到 assets/sfx/。
• --output 支持 <name> 和 <id> 占位符。
• 建议音效音量默认为 0.8；请根据提示音和整体混音在 0.6-1 之间调整。
• 音效不支持提取副歌。

文本转语音（tts）

使用 Kokoro-82M 在本地生成语音音频。无需 API 密钥。

由 Chanjing 提供支持的语音请求

如果用户要求使用 Chanjing 生成语音、平台语音、数字人旁白或任何由 Chanjing 提供的语音素材，请改为调用 chanjing-digital-human 技能，而不要默认使用本地 Kokoro TTS。只有当用户明确要求离线语音，或在 Chanjing 身份验证不可用时接受占位素材，才使用本地 npx framevideo tts。

npx framevideo tts "Text here" --voice af_nova --output narration.wav
npx framevideo tts script.txt --voice bf_emma --output narration.wav
npx framevideo tts --list                       # all 54 voices

语音选择

根据内容选择合适的语音。默认值为 af_heart。

内容类型	语音	原因
产品演示	af_heart/af_nova	温暖、专业
教程／操作指南	am_adam/bf_emma	中性、易于理解
营销／宣传	af_sky/am_michael	充满活力或权威
文档	bf_emma/bm_george	清晰的英式英语，正式
日常／社交	af_heart/af_sky	平易近人、自然

多语言

语音 ID 的首字母表示语言：a=美式英语，b=英式英语，e=西班牙语，f=法语，h=印地语，i=意大利语，j=日语，p=巴西葡萄牙语，z=普通话。CLI 会根据前缀自动检测音素转换器的区域设置——语音与文本匹配时，无需使用 --lang。

npx framevideo tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx framevideo tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav

仅在需要覆盖自动检测结果时（例如使用特殊口音），才使用 --lang。有效代码：en-us、en-gb、es、fr-fr、hi、it、pt-br、ja、zh。非英语音素转换需要在系统范围内安装 espeak-ng（brew install espeak-ng / apt-get install espeak-ng）。

语速

• 0.7-0.8 — 教程、复杂内容、无障碍内容
• 1.0 — 自然语速（默认）
• 1.1-1.2 — 开场、过渡、轻快内容
• 1.5+ — 通常不适用；请谨慎测试

长篇脚本

如果内容超过几段，请写入 .txt 文件并传入文件路径。对于超过约 5 分钟语音的输入，分段处理可能会有帮助。

要求

Python 3.8+，并安装 kokoro-onnx 和 soundfile（pip install kokoro-onnx soundfile）。模型会在首次使用时下载（约 311 MB + 约 27 MB 语音文件，缓存于 ~/.cache/framevideo/tts/）。

转录（transcribe）

生成带有词级时间戳的规范化 transcript.json。

npx framevideo transcribe audio.mp3
npx framevideo transcribe video.mp4 --model small --language es
npx framevideo transcribe subtitles.srt          # import existing
npx framevideo transcribe subtitles.vtt
npx framevideo transcribe openai-response.json

语言规则（不可妥协）

除非用户明确说明音频是英语，否则绝不要使用 .en 模型。 .en 模型（small.en、medium.en）会将非英语音频翻译成英语，而不是进行转录，这会在不显眼的情况下彻底破坏原始语言内容。

1. 已知语言且为非英语 → --model small --language <code>（不带 .en 后缀）
2. 已知语言且为英语 → --model small.en
3. 未知语言 → --model small（不带 .en，也不带 --language）——whisper 会自动检测

默认模型是 small，而不是 small.en。

模型大小

模型	大小	速度	使用场景
tiny	75 MB	最快	快速预览、测试流程
base	142 MB	快	短片段、清晰音频
small	466 MB	中等	默认 — 适用于大多数内容
medium	1.5 GB	慢	重要内容、嘈杂音频、音乐
large-v3	3.1 GB	最慢	生产级质量

带人声的音乐：至少从 medium 开始；制作完成的曲目通常需要手动导入 SRT/VTT。有关字幕质量检查（每次转录后都必须执行）、清理用 JS、重试规则以及 OpenAI/Groq API 导入方式，请参阅 framevideo/references/transcript-guide.md。

输出结构

组合会使用由词对象组成的扁平数组。id 字段（w0、w1……）会在规范化过程中添加，以便在字幕覆盖中稳定引用；为向后兼容，该字段是可选的。

[
  { "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },
  { "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }
]

背景移除（remove-background）

从视频或图像中移除背景，使主体（通常是人物——头像、演讲者、口播人像）在组合中作为透明叠加层显示。

npx framevideo remove-background subject.mp4 -o transparent.webm  # default: VP9 alpha WebM
npx framevideo remove-background subject.mp4 -o transparent.mov   # ProRes 4444 (editing)
npx framevideo remove-background portrait.jpg -o cutout.png       # single-image cutout
npx framevideo remove-background subject.mp4 -o subject.webm \
  --background-output plate.webm                                   # both layers in one pass
npx framevideo remove-background subject.mp4 -o transparent.webm --device cpu
npx framevideo remove-background --info                           # detected providers

使用 u2net_human_seg（MIT）。首次运行时，会将约 168 MB 的权重下载到 ~/.cache/framevideo/background-removal/models/。

图层分离（--background-output）

传入 --background-output（或 -b），即可在抠像视频之外额外输出第二个透明视频：RGB 与源视频相同，alpha 为 255 − mask，而不是 mask。抠像层是背景透明的主体；底片是背景透明、主体所在位置留有透明孔洞的原始环境。

文件	Alpha 表示……	用途
-o subject.webm	蒙版 — 主体不透明，背景透明	前景层，放在上方
--background-output plate.webm	反向 — 环境不透明，主体区域透明	底层；将文字或图形放在此层与主体之间

两个输出共享相同的 --quality 预设，并通过单次推理生成 — 编码开销大致翻倍，分割开销不变。仅适用于视频输入和 .webm/.mov 输出。

这是留有抠像孔洞的底片，不是经过修复的干净底片。 plate.webm 中的主体区域完全透明 — 在它下方合成不透明内容，才能填补这个孔洞。判断 --background-output 是否适用，只需问一个问题：主体原先所在的位置，透过主体轮廓是否会显示任何内容？

用例	适用工具
在抠像层与底片之间放置文字/图形（此命令存在的用途）	留孔底片（--background-output）
将主体叠加到无关场景中	只用 subject.webm；忽略底片
在没有其他内容的画面上单独展示_没有人物的房间_	干净底片 — 需要图像修复工具（LaMa、ProPainter、E2FGVI）。不是此命令。
将主体替换为另一个主体	干净底片 — 同上

如果用户要的是“移除人物后的房间”，并且打算单独展示，请不要使用 --background-output。告诉他们需要使用图像修复工具。

典型的分层合成（留孔底片的标准用例）：

<video
  src="plate.webm"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>


<h1 id="headline" style="z-index:2; ...">MAKE IT IN FRAMEVIDEO</h1>


<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
  <video
    src="subject.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

这在功能上等同于下文的文字置于主体后方模式，但项目中不需要原始 presenter.mp4 — 底片可以替代它。适用于只想交付两个透明图层，并让用户在两者之间放置任意内容的情况。

输出格式

格式	适用场景
.webm（VP9 + alpha）	默认格式。合成可直接通过 <video> 播放。
.mov（ProRes 4444）	在 DaVinci/Premiere/FCP 中编辑。文件较大。
.png	单图抠像（静态主体叠加在背景上）。

Chrome 原生支持解码 VP9 alpha，因此 .webm 可以像其他静音自动播放的视频一样直接用于合成 — 关于 <video> 轨道约定，请参阅 framevideo 技能。

质量预设

--quality fast|balanced|best 仅控制 VP9 编码器的 CRF，分割质量固定不变。

预设	CRF	适用场景
fast	30	迭代时使用，文件较小，颜色匹配较宽松
balanced	18	默认值。适用于大多数场景，视觉效果几乎无差别
best	12	母版／最终交付。文件最大，匹配最严格

合成模式——选择合适的模式

抠像 webm 是源 mp4 的 RGB 重新编码副本。根据叠加在它后面的内容，这种选择会带来不同影响：

模式	抠像后方的内容	效果
抠像叠加在不同场景上（最常见）	静态图像、渐变或无关视频	效果很好。主体的 RGB 仅来自抠像画面，不会出现重影或边缘光晕。这正是 remove-background 的用途。
抠像叠加在自身的源 mp4 上（文字置于主体后方）	生成抠像所用的同一个 mp4	同一个人的 RGB 来自两个来源。使用默认的 --quality balanced（crf 18）时，重影几乎看不出来；使用 --quality fast（crf 30）时，会看到轻微的色偏／边缘光晕。制作母版时请使用 --quality best（crf 12）。
抠像叠加在同一个人的_另一次拍摄_上	同一主体的影像	看起来会像两个人相互重叠。请勿这样做。

文字置于主体后方（标题位于演讲者后方）：

<video
  src="presenter.mp4"
  id="bg"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>
<h1 id="headline" style="z-index:2; ...">MAKE IT IN FRAMEVIDEO</h1>
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
  <video
    src="presenter.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

两条重要规则：

1. 将抠像视频包裹在非定时的 <div> 中，并为包裹元素而非视频元素设置透明度动画。框架会将活动片段（任何带有 data-start/data-duration 的元素）的透明度强制设为 1，因此直接为视频设置透明度动画会被静默覆盖。包裹元素没有 data-* 属性，因此由你的 CSS/GSAP 控制。
2. 两个视频都使用 data-start="0" 和 data-media-start="0"，这样框架就会从 t=0 开始同步解码。延迟挂载抠像（data-start=3.3）会引入跳转和预热，导致画面比基础 mp4 慢一帧——剪切点处会出现一帧可见的错位。

然后使用 GSAP 在剪切点切换包裹元素的透明度：tl.set(cutoutWrap, { opacity: 1 }, 3.3)。

TTS → 转录 → 字幕

如果没有预录的旁白，可以先生成旁白，再将其转录，以获取字幕所需的逐词时间戳：

npx framevideo tts script.txt --voice af_heart --output narration.wav
npx framevideo transcribe narration.wav   # → transcript.json

Whisper 会从生成的音频中提取精确的逐词边界，因此字幕时间可以匹配实际语速，无需手动调整。

---

验证

预处理资源后：

# Verify audio files
npx framevideo inspect   # Check audio levels and duration

# Test in preview
npx framevideo preview   # Verify audio plays correctly in composition

手动检查：

1. 文件路径——资源已保存到正确的目录（assets/music/、assets/sfx/ 等）
2. 音频电平——BGM 为 0.12-0.22，SFX 为 0.6-1.0，旁白保持默认值
3. 转录准确性——检查 transcript.json 中的词语边界
4. 背景移除质量——检查透明视频是否存在边缘瑕疵
5. 集成情况——确认资源已在合成 HTML 中正确引用

---

集成

此技能会生成以下工具使用的素材：

• framevideo — 在合成 HTML 中引用音频/视频
• framevideo-voiceover-ssml — 在 TTS 生成前应用 SSML 标记
• chanjing-digital-human — 作为本地 TTS 的语音旁白替代方案
• website-to-framevideo — 第 4 步使用此技能生成音频

---

致谢与参考资料

• Kokoro TTS：https://github.com/hexgrad/kokoro
• Whisper 转录：https://github.com/openai/whisper
• u2net 背景移除：https://github.com/xuebinqin/U-2-Net
• Chanjing 平台：https://www.chanjing.cc