Communitygithub.com

alecs5am/ralphy

用于 HyperFrames 合成的资源预处理——文本转语音旁白(Kokoro)、音频/视频转录(Whisper)以及透明叠加层的背景移除(u2net)。

ralphy 是什么?

这是一个专为 HyperFrames 合成项目设计的资源预处理工具集,提供三个核心命令行工具:文本转语音(TTS)、音频/视频转录和背景移除。TTS 工具基于 Kokoro-82M 模型在本地生成语音,无需 API 密钥,支持 54 种声音和多种语言。转录工具使用 Whisper 模型生成带单词级时间戳的标准化 transcript.json 文件,默认使用 small 模型以避免对非英语音频进行错误翻译。背景移除工具基于 u2net_human_seg 模型,可将视频或图像中的主体(如人物)分离为透明叠加层,并支持同时输出主体和背景图层。所有工具首次运行时自动下载并缓存模型,适用于 Claude Code、Cursor 等 AI 代理平台,帮助开发者快速为多媒体内容生成语音旁白、字幕和透明前景素材。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/alecs5am/ralphy/tree/HEAD/.agents/skills/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 <代码>(不要加 .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 格式。关于字幕质量检查(每次转录后必须执行)、清洗 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适用场景
fast30迭代开发、较小文件、颜色匹配宽松
balanced18默认。在大多数使用场景下视觉上无差别
best12母版/最终交付。最大文件、最严格匹配

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

抠图的 webm 文件是源 mp4 RGB 的重新编码副本。这一选择根据你在其后面放置的内容会产生不同的后果:

模式抠图后面是什么结果
抠图置于不同场景上(最常见)静态图像、渐变或不相关视频效果很好。抠图的 RGB 是主体的唯一来源——无双重图像、无边缘光晕。这正是 remove-background 的用途。
抠图置于其自身的源 mp4 上(文字在主体之后)生成抠图的同一 mp4 文件同一人物有两个 RGB 来源。在默认的 --quality balanced(crf 18)下双重效果几乎不可见;在 --quality fast(crf 30)下你会看到微弱的颜色偏移或边缘光晕,但如果你只关心主体前的文本,这通常可以接受。

Individual skills in this repo

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

alecs5am/ralphy

>- Composition and render craft — assembles scenario.json plus asset-manifest.json into a HyperFrames HTML composition and renders the mp4. Owns timing, transitions, captions, audio mix and ducking, the green zone, the render pipeline, and VO sync. Generates no media of its own. USE WHEN the user asks to "compose the video", "render", "preview", "fix the captions", "mix the audio", "tighten the transitions", "final cut", or edits HyperFrames composition code. TRIGGER (EN): "render it", "compose the video", "captions", "audio mix", "transitions", "final cut", "preview the composition".

alecs5am/ralphy

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.

alecs5am/ralphy

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

alecs5am/ralphy

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.

alecs5am/ralphy

>- How to make a vivid, character-driven brand POSTER — a single still image, not a video. A generalized overlay on the art-director step: supplies the poster-as-landing architecture (top banner → massive beveled wordmark → chest-up hero photo → scattered vinyl-sticker collage → copy block → thin footer strip), the parameterized slot set (brand, exclamation word, hero, product, palette, original blob glyph, aesthetic register), the model stack (gpt-5.4-image-2 for crisp typography, gemini fallback), and the niche's failure modes. Works for ANY brand and ANY aesthetic the user names — Y2K streetwear, vaporwave, grunge zine, clean DTC — the skill supplies the layout know-how, the user supplies the subject + vibe. USE WHEN the user asks for a poster / flyer / drop poster / "poster-as-landing-page" / brand key-art / album-cover-style still / hype graphic, with no specific existing poster to reproduce. This is a content-niche craft-overlay SKILL (generalized), loaded on top of a poster-format template match — n...

alecs5am/ralphy

>- Compatibility shim for the legacy `/ralphy-remotion` skill name. Use when a saved Claude Code command, old project note, or user request still mentions Ralphy Remotion; redirect the task to HyperFrames and the current Ralphy render playbooks instead of authoring new Remotion code.

alecs5am/ralphy

>- Compatibility shim for the legacy `/remotion-to-hyperframes` skill name. Use when an old project, note, or user request asks to migrate Ralphy Remotion work; translate the intent into the current HyperFrames composition model and follow the editor and HyperFrames playbooks.

alecs5am/ralphy

The full extract → classify → blueprint → de-dup → publish pipeline for a finished `.ralphy/workspaces/<ws>/projects/<id>/`. Reads its `units/*/unit.json` (#069) as the Unit source of truth, then factors the project into ALL FIVE entities — Unit + the four typed blocks Template (structure), Style (look), Recipe (effect/treatment), Asset (reusable media). Applies the recipe-vs-tag split (#082/#083): a candidate is a Recipe only if it carries an extractable artifact (ffmpeg filtergraph / HyperFram

alecs5am/ralphy

>- How to make a realistic AI UGC ad for a product — generalized niche know-how that looks real and doesn't feel AI. A domain overlay on the standard pipeline: supplies the shooting-script shape (timestamp | VO | shot | mannerism), the creator-persona build, the problem-mirror hook, the trust-through-mannerisms rule, and the 9:16 ~15s UGC format defaults. Works for ANY product the user names — their skincare line, a no-name app, a gadget. The skill supplies the know-how; the user supplies the product. USE WHEN the user asks for a UGC ad / creator-style product ad / "make an ad that looks like a real person reviewing my product" / testimonial-style or problem-solution short for TikTok / Reels / Shorts, with no specific existing video to reproduce. This is a niche SKILL (generalized), not a remix TEMPLATE. For "remix this exact ad but swap the product/person", use the remix path (docs/skills-vs-templates.md). For swapping the creator in an existing clip, see /ugc-model-swap.

alecs5am/ralphy

When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' 'ideas to grow,' 'what else can I try,' 'I don't know how to market this,' 'brainstorm marketing,' or 'what marketing should I do.' Use this as a starting point whenever someone is stuck or looking for inspiration on how to grow. For specific channel execution, see the relevant skill (paid-ads, social-content, email-sequence, etc.).

alecs5am/ralphy

Full end-to-end workflow for generating a realistic AI UGC ad for a product. 15-second format. Looks real. Doesn't feel AI.

相关技能