hyperframes-media

HyperFrames 媒体预处理

用于为合成生成素材的 3 个 CLI 命令：tts（语音）、transcribe（时间戳）和 remove-background（透明视频）。首次运行时，每个命令都会下载一个模型，并将其缓存到 ~/.cache/hyperframes/。将输出文件放入项目中，然后在合成 HTML 中引用它 — 音频/视频元素的使用约定请参阅 hyperframes 技能。

文本转语音（tts）

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

npx hyperframes tts "Text here" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes 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 hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx hyperframes 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/hyperframes/tts/）。

转录（transcribe）

生成包含词级时间戳的标准化 transcript.json。

npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt          # import existing
npx hyperframes transcribe subtitles.vtt
npx hyperframes 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 导入方式，请参阅 hyperframes/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 hyperframes remove-background subject.mp4 -o transparent.webm  # default: VP9 alpha WebM
npx hyperframes remove-background subject.mp4 -o transparent.mov   # ProRes 4444 (editing)
npx hyperframes remove-background portrait.jpg -o cutout.png       # single-image cutout
npx hyperframes remove-background subject.mp4 -o subject.webm \
  --background-output plate.webm                                   # both layers in one pass
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info                           # detected providers

使用 u2net_human_seg（MIT）。首次运行时会将约 168 MB 的权重下载到 ~/.cache/hyperframes/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 HYPERFRAMES</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 可以像其他静音自动播放视频一样接入合成——请参阅 hyperframes 技能中的 <video> 轨道约定。

质量预设

--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 HYPERFRAMES</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> 中，并为包装元素设置动画，而不是为 video 元素设置。框架会强制激活片段（任何带有 data-start/data-duration 的元素）的 opacity:1，因此直接为 video 设置 opacity 动画会被静默覆盖。包装元素没有 data-* 属性，因此由你的 CSS/GSAP 控制。
2. 两个视频都使用 data-start="0" 和 data-media-start="0"，这样框架就会从 t=0 开始同步解码。延迟挂载抠像（data-start=3.3）会引入一次 seek 和预热，导致画面比基础 mp4 偏一帧——剪切处会出现一帧错位。

然后使用 GSAP 在剪切处翻转包装元素的 opacity：tl.set(cutoutWrap, { opacity: 1 }, 3.3)。

TTS → 转录 → 字幕

没有预录的旁白时，生成一段旁白并将其转录，以获取字幕的逐词时间戳：

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

Whisper 会从生成的音频中提取精确的逐词边界，因此字幕时间与语音节奏一致，无需手动调整。