HyperFrames 媒体预处理
三个 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 # 全部 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 avatar.mp4 -o transparent.webm # 默认:VP9 alpha WebM
npx hyperframes remove-background avatar.mp4 -o transparent.mov # ProRes 4444(编辑用)
px hyperframes remove-background portrait.jpg -o cutout.png # 单张图像抠图
npx hyperframes remove-background avatar.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info # 检测到的提供者
使用 u2net_human_seg(MIT 协议)。首次运行时将约 168 MB 的权重下载到 ~/.cache/hyperframes/background-removal/models/。
输出格式
| 格式 | 使用场景 |
|---|---|
.webm(VP9 + alpha 通道) | 默认。合成直接通过 <video> 播放。 |
.mov(ProRes 4444) | 在 DaVinci/Premiere/FCP 中编辑。文件较大。 |
.png | 单张图像抠图(静态主体,叠加在背景之上)。 |
Chrome 浏览器原生解码 VP9 alpha 通道,因此 .webm 可以像其他静音自动播放视频一样嵌入合成中——<video> 轨道相关约定请参见 hyperframes 技能。
TTS → 转录 → 字幕
当没有预先录制的配音时,先生成配音再将其转录回来,以获得字幕所需的词级时间戳:
npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav # → transcript.json
Whisper 从生成的音频中提取精确的词边界,因此字幕时间与配音完全匹配,无需手动调整。