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 <代码>(不要加.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 格式。关于字幕质量检查(每次转录后必须执行)、清洗 JavaScript、重试规则以及 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(编辑用)
npx 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/ 目录。
不要为带有白色轮廓的模切贴纸使用 u2net
remove-background(u2net)是显著对象分割——它会分割主体并切掉白色的模切轮廓,因为人物周围的白色描边不是“对象”。对于在平坦的已知颜色背景上渲染并带有白色轮廓的 Telegram/消息贴纸,请对背景进行抠像而不是分割主体:
- 对平坦背景进行泛洪填充。 使用 PIL
ImageDraw.floodfill,从所有四条边上的点(步长约为 24 像素)进行种子填充,将填充像素标记为 alpha 0,其他所有像素不透明。这可以保留白色轮廓、内部同色道具以及断开的小块(例如与身体分离的飞杯可以保留其自身的轮廓)。这要求生成提示中将主体放在平坦均匀的背景上,并明确要求白色模切轮廓。 - 无轮廓变体(比去除烘焙轮廓更干净): 对每张图像重新进行图生图——将完成的渲染图作为
--ref传入,并提示“重新创建相同的姿势/道具,但移除白色轮廓并将其放在平坦的纯色键控绿色(#00b140)背景上”,然后使用软键控(而非二值蒙版)对绿色进行抠像(alpha = clip((HIGH-(G-max(R,B)))/(HIGH-LOW),0,1),LOW≈30,HIGH≈95,加上全局去溢色G = min(G, max(R,B)))。二值泛洪填充加腐蚀会产生阶梯/锯齿边缘——使用高斯模糊(GaussianBlur(0.8))模糊二值 alpha 以获得平滑边缘,而不是进行腐蚀。 - 消息贴纸的尺寸: 裁剪到实体 alpha 边界框,并将长边缩放到精确的目标尺寸(例如 512)——不要填充到 512² 的正方形(这会使主体变小,周围留有空白空间)。
不适用于:用于视频叠加的人体抠像(u2net 在此处是正确的);没有模切轮廓的艺术作品;位于非均匀/复杂背景上的主体(泛洪填充需要平坦的键控色)。
图层分离(--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。应告知他们需要使用修复工具。
典型的图层合成(典型的打孔层用例):
<!-- 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)下你会看到微弱的颜色偏移或边缘光晕,但如果你只关心主体前的文本,这通常可以接受。 |