HyperFrames 媒体预处理
三个 CLI 命令,用于生成合成作品所需的资源:tts(语音)、transcribe(时间戳)和 remove-background(透明视频)。每个命令在首次运行时下载模型,并将其缓存到 ~/.cache/hyperframes/。将输出文件放入项目后,即可在合成 HTML 中引用它——关于音视频元素的约定,请参阅 hyperframes 技能。
文字转语音 (tts)
使用 Kokoro-82M 在本地生成语音音频。无需 API 密钥。
npx hyperframes tts "这里写文本" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list # 列出全部 54 种语音
语音选择
根据内容匹配语音。默认为 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 # 导入现有字幕
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
语言规则(不容妥协)
除非用户明确声明音频是英语,否则切勿使用 .en 模型。 .en 模型(small.en、medium.en)会翻译非英语音频为英语,而不是进行转录。这会静默地破坏原始语言。
- 语言已知且非英语 →
--model small --language <code>(无.en后缀) - 语言已知且为英语 →
--model small.en - 语言未知 →
--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 # 默认:VP9 alpha WebM
npx hyperframes remove-background subject.mp4 -o transparent.mov # ProRes 4444(用于剪辑)
hyperframes remove-background portrait.jpg -o cutout.png # 单张图片抠图
npx hyperframes remove-background subject.mp4 -o subject.webm \
--background-output plate.webm # 一次处理输出两个图层
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info # 检测到的可用加速器
使用 u2net_human_seg 模型(MIT 许可证)。首次运行会下载约 168 MB 权重到 ~/.cache/hyperframes/background-removal/models/。
图层分离 (--background-output)
传入 --background-output(或 -b)来额外输出一个与抠图视频相伴的透明视频:RGB 内容相同,但 Alpha 通道使用 255 − 蒙版 而非 蒙版。抠图是主体带有透明背景;底板是原始环境,主体区域透明。
| 文件 | Alpha 通道是… | 用途 |
|---|---|---|
-o subject.webm | 蒙版 — 主体不透明,背景透明 | 前景图层,置于上层 |
--background-output plate.webm | 反转 — 环境不透明,主体区域透明 | 底层图层;在此层与主体层之间放置文字或图形 |
两个输出共享相同的 --quality 预设,并基于单次推理运行——编码成本大约翻倍,分割成本不变。仅对视频输入和 .webm/.mov 输出有效。
这是挖孔底板,而非补全的干净底板。 plate.webm 中的主体区域是完全透明的——在其下方合成一个不透明的内容来填充这个空洞。判断 --background-output 是否为正确工具的唯一标准是:在主体曾经所在的位置,是否会有任何内容透过主体的轮廓可见?
| 使用场景 | 正确的工具 |
|---|---|
| 在抠图层和底板之间放置文字/图形(此命令的存在理由) | 挖孔(--background-output) |
| 将主体放到无关的场景上 | 只需 subject.webm;忽略底板 |
| 单独显示去掉人物后的房间,不覆盖其他内容 | 干净底板——需要使用修复模型(如 LaMa、ProPainter、E2FGVI)。此命令无法做到。 |
| 将主体替换为不同的主体 | 干净底板——同上 |
如果用户要求“去掉人物后的房间”并打算单独展示,不要使用 --background-output。告诉他们需要一个修复模型。
典型的图层合成(挖孔的规范用法):
<!-- z=1 反相 Alpha 的底板填充除主体区域外的所有内容 -->
<video
src="plate.webm"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<!-- z=2 图形/文字位于两个图层之间 -->
<h1 id="headline" style="z-index:2; ...">在 HYPERFRAMES 中创作</h1>
<!-- z=3 抠图层将主体浮于标题之上 -->
<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; ...">在 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>
两个关键规则:
- 将抠图视频包裹在一个不含
data-start/data-duration属性的<div>中,并动画化这个包裹层的透明度,而不是直接动画化视频元素。框架会强制活动片段(任何带有data-start/data-duration属性的元素)的opacity: 1,因此直接动画化视频的透明度会被静默覆盖。由于包裹层没有data-*属性,它完全由您的 CSS/GSAP 控制。 - 两个视频都使用
data-start="0"和data-media-start="0",这样框架会从 t=0 开始同步解码它们。如果延迟挂载抠图(data-start=3.3),会导致一次 seek 和预热,使其帧位置与基础 MP4 相差一帧——在切换时会看到一帧的错位。
然后在使用 GSAP 在切换时刻翻转包裹层透明度: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
…