Communitygithub.com

shinyobjectz/reactable

HyperFrames 合成的资产预处理工具——文本转语音旁白(Kokoro)、音频/视频转录(Whisper)以及透明叠加层的背景去除(u2net)。用于从文本生成配音、将语音转录为字幕、去除视频或图像的背景以作为透明叠加层使用、选择 TTS 语音或 Whisper 模型,或将这些步骤串联起来(TTS → 转录 → 字幕)。每条命令在首次运行时都会下载自己的模型。

reactable 是什么?

此技能提供三个 CLI 命令,用于为 HyperFrames 合成生成预处理资产:tts(文本转语音)、transcribe(转录)和 remove-background(背景去除)。TTS 命令使用 Kokoro-82M 模型在本地生成语音音频,无需 API 密钥,支持 54 种语音和包括中文、日语、西班牙语在内的多种语言。转录命令使用 Whisper 模型生成带有词级时间戳的 transcript.json,支持从小型到大型的多种模型大小,并特别警告了不对应语言的 .en 模型的危险性。背景去除命令使用 u2net_human_seg 模型从视频或图像中去除背景,生成透明叠加层,支持 VP9 alpha WebM、ProRes 4444 和 PNG 格式,并允许通过 --background-output 进行层级分离。所有命令在首次运行时都会下载模型并缓存至 ~/.cache/hyperframes/。该技能适用于需要在合成中添加配音、字幕或透明叠加层的 HyperFrames 用户,并且 hf 技能配合使用以遵循音频/视频元素约定。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shinyobjectz/reactable/tree/HEAD/skill/vendored/hyperframes-media

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

预览

来自技能 README

文档

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)会翻译非英语音频为英语,而不是转录它。这会悄无声息地破坏原始语言。

  1. 语言已知且非英语 → --model small --language <code>(无 .en 后缀)
  2. 语言已知且为英语 → --model small.en
  3. 语言未知 → --model small(无 .en,无 --language)——whisper 会自动检测

默认模型是 small,而非 small.en。

模型大小

模型大小速度使用场景
tiny75 MB最快快速预览、测试流程
base142 MB快短片、清晰的音频
small466 MB一般默认——大多数内容
medium1.5 GB慢重要内容、嘈杂音频、音乐
large-v33.1 GB最慢生产质量

对于带人声的音乐:至少从 medium 开始;完成的作品通常需要手动导入 SRT/VTT。有关字幕质量检查(每次转录后必须执行)、清理 JS、重试规则以及 OpenAI/Groq API 导入路径,请参阅 hyperframes/references/transcript-guide.md。

输出格式

合成消费一个扁平的单词对象数组。id 字段(w0、w1...)在标准化过程中添加,用于在字幕覆盖中提供稳定引用;为了向后兼容,它是可选的。

[
  { "id": "w0", "text": "你好", "start": 0.0, "end": 0.5 },
  { "id": "w1", "text": "世界。", "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/。

图层分离 (--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使用场景
fast30迭代中,较小的文件,颜色匹配较宽松
balanced18默认。对于大多数用途,视觉上相同
best12母版/最终交付。最大文件,最精确的颜色匹配

合成模式——选择正确的方式

裁剪后的 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>

两条关键规则:

  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 hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav   # → transcript.json

然后生成的 transcript.json 可以与 hyperframes 播放器一起使用,以生成同步字幕(请参阅 hyperframes 技能文档中的文本轨道约定)。

相关技能