Communitygithub.com

shengdabai/Tony-Claude-Code-Skills

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

Tony-Claude-Code-Skills 是什么?

这个技能为 HyperFrames 合成作品提供三项核心的本地媒体预处理 CLI 命令。`tts` 命令使用 Kokoro-82M 模型生成语音,无需 API 密钥,支持 54 种语音和多种语言,并自动检测音素化区域设置。`transcribe` 命令使用 Whisper 生成包含单词级时间戳的标准化的 `transcript.json` 文件,并强调不要对非英语音频使用 `.en` 模型以避免意外翻译。`remove-background` 命令使用 u2net_human_seg 模型移除视频或图像的背景,生成支持 Alpha 通道的透明 WebM 或 MOV 文件,并可通过 `--background-output` 参数输出“底板”画面,以便在主体和背景之间插入文本或图形。该技能支持在 Cursor、Windsurf 以及任何兼容 Claude Code 风格的平台(如 Codex、Aider、Continue)上使用。所有命令的模型文件在首次运行时下载并缓存到 `~/.cache/hyperframes/` 目录下。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shengdabai/Tony-Claude-Code-Skills/tree/HEAD/skills/hyperframes-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": "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使用场景
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. 将抠图视频包裹在一个不含 data-start/data-duration 属性的 <div> 中,并动画化这个包裹层的透明度,而不是直接动画化视频元素。框架会强制活动片段(任何带有 data-start/data-duration 属性的元素)的 opacity: 1,因此直接动画化视频的透明度会被静默覆盖。由于包裹层没有 data-* 属性,它完全由您的 CSS/GSAP 控制。
  2. 两个视频都使用 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

…

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

shengdabai/Tony-Claude-Code-Skills

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

shengdabai/Tony-Claude-Code-Skills

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

shengdabai/Tony-Claude-Code-Skills

Read-only queue dashboard for workspace-aware ship. (gstack)

shengdabai/Tony-Claude-Code-Skills

Anime.js adapter patterns for HyperFrames. Use when writing Anime.js animations or timelines inside HyperFrames compositions, registering animations on window.__hfAnime, making Anime.js seek-driven and deterministic, or translating Anime.js examples into render-safe HyperFrames HTML.

shengdabai/Tony-Claude-Code-Skills

Author a new HyperFrames registry block (caption style, VFX block, transition, lower third) or component (text effect, overlay, snippet) and ship it as an upstream PR to the hyperframes repo. Use ONLY when the user wants to CONTRIBUTE to the public catalog — for in-project caption/transition authoring use the `hyperframes` skill, for installing existing registry items use the `hyperframes-registry` skill.

shengdabai/Tony-Claude-Code-Skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

shengdabai/Tony-Claude-Code-Skills

GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

shengdabai/Tony-Claude-Code-Skills

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

相关技能