Communitygithub.com

alecs5am/ralphy

HyperFrames CLI 开发循环 — 使用 `npx hyperframes` 进行脚手架搭建(init)、验证(lint、inspect)、预览、渲染以及环境问题排查(doctor、browser、info、upgrade)。在运行这些命令或排查 HyperFrames 构建/渲染环境时调用此技能。对于资产预处理命令(`tts`、`transcribe`、`remove-background`),请改为调用 `hyperframes-media` 技能。

ralphy 是什么?

此技能封装了 HyperFrames CLI 的完整开发循环,这是一个基于 Node.js 的视频编程框架。它提供了一套端到端的命令行工具,用于创建 `npx hyperframes init`、编写 HTML 合成、通过 `lint` 和 `inspect` 进行 lint 检查和可视化布局验证(检测文本溢出和容器裁剪问题)、通过 `preview` 进行热重载预览,以及通过 `render` 进行最终渲染输出。该 CLI 支持多种质量预设(draft、standard、high)、可变帧率(24/30/60 fps)以及 MP4 或 WebM 格式,还支持 Docker 以实现可重现的构建和 GPU 加速编码。对于环境问题排查,`doctor`、`browser`、`info` 和 `upgrade` 命令可帮助诊断缺失的依赖项(如 FFmpeg、Chrome)。资产预处理命令(TTS、转录、背景去除)已被分离到 `hyperframes-media` 技能中,以保持关注点分离。此技能还支持参数化渲染,通过 `--variables` 或 `--variables-file` 覆盖在 HTML 根元素上声明的变量,从而实现从开发到生产的无改动工作流。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/alecs5am/ralphy/tree/HEAD/.agents/skills/hyperframes-cli

在你喜欢的 AI 中提问

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

文档

HyperFrames CLI

一切通过 npx hyperframes 运行。需要 Node.js >= 22 和 FFmpeg。

工作流程

  1. 脚手架搭建 — npx hyperframes init my-video
  2. 编写 — 创作 HTML 合成(参见 hyperframes 技能)
  3. Lint 检查 — npx hyperframes lint
  4. 可视化检查 — npx hyperframes inspect
  5. 预览 — npx hyperframes preview
  6. 渲染 — npx hyperframes render

在预览前先执行 lint 和 inspect。lint 可检测缺失的 data-composition-id、重叠的轨道以及未注册的时间线。inspect 在无头 Chrome 中打开渲染后的合成,扫描整个时间线,并报告文本溢出气泡/容器或画布的问题。

脚手架搭建

npx hyperframes init my-video                        # 交互式向导
npx hyperframes init my-video --example warm-grain   # 选择一个示例
npx hyperframes init my-video --video clip.mp4        # 使用视频文件
npx hyperframes init my-video --audio track.mp3       # 使用音频文件
npx hyperframes init my-video --example blank --tailwind # 使用 Tailwind v4 浏览器运行时
npx hyperframes init my-video --non-interactive       # 跳过提示(CI/代理)

模板:blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。

init 会创建正确的文件结构、复制媒体、使用 Whisper 转录音频,并安装 AI 编码技能。请使用它而不是手动创建文件。

当使用 --tailwind 时,在编辑类或主题 token 之前请调用 tailwind 技能。脚手架使用 Tailwind v4.2(通过浏览器运行时),而不是 Studio 的 Tailwind v3 设置。

Lint 检查

npx hyperframes lint                  # 当前目录
npx hyperframes lint ./my-project     # 特定项目
npx hyperframes lint --verbose        # 信息级别发现
npx hyperframes lint --json           # 机器可读

检查 index.html 和 compositions/ 中的所有文件。报告错误(必须修复)、警告(应该修复)和信息(使用 --verbose)。

可视化检查

npx hyperframes inspect                 # 检查时间线上的渲染布局
npx hyperframes inspect ./my-project    # 特定项目
npx hyperframes inspect --json          # 代理可读的发现
npx hyperframes inspect --samples 15    # 更密集的时间线扫描
npx hyperframes inspect --at 1.5,4,7.25 # 明确的 hero 帧时间戳

在 lint 和 validate 之后使用,特别是对于包含对话气泡、卡片、字幕或紧凑排版的合成。它会报告:

  • 文本延伸到最近的视觉容器或气泡之外
  • 文本被其自身的固定宽度/固定高度框裁剪
  • 文本延伸到合成画布之外
  • 子元素脱离裁剪容器

错误应在渲染前修复。警告将呈现给代理审查;添加 --strict 也会使警告失败。重复的静态问题默认折叠,以便 JSON 输出在 LLM 上下文窗口中保持紧凑。如果溢出是有意为之的入场/退场动画,请将元素或祖先标记为 data-layout-allow-overflow。如果装饰元素永远不应被审计,请将其标记为 data-layout-ignore。

npx hyperframes layout 仍然可用,作为相同可视化检查过程的兼容别名。

预览

npx hyperframes preview                   # 服务当前目录
npx hyperframes preview --port 4567       # 自定义端口(默认 3002)

文件更改时热重载。自动在浏览器中打开 Studio。

将项目交回给用户时,请使用 Studio 项目 URL,而不是源 index.html 路径:

http://localhost:<port>/#project/<project-name>

使用预览输出中的实际端口和项目目录名称。例如,在执行 npx hyperframes preview --port 3017 于 codex-openai-video 后,报告 http://localhost:3017/#project/codex-openai-video。

将 index.html 仅视为源代码上下文。将其链接为实现文件是可以的,但不要将其标记为项目或预览面。

渲染

npx hyperframes render                                # 标准 MP4
npx hyperframes render --output final.mp4             # 命名输出
npx hyperframes render --quality draft                # 快速迭代
npx hyperframes render --fps 60 --quality high        # 最终交付
npx hyperframes render --format webm                  # 透明 WebM
npx hyperframes render --docker                       # 字节一致
标志选项默认注释
--output路径renders/name_timestamp.mp4输出路径
--fps24, 30, 603060fps 渲染时间加倍
--qualitydraft, standard, highstandarddraft 用于迭代
--formatmp4, webmmp4WebM 支持透明度
--workers1-8 或 autoauto每个工作进程启动一个 Chrome
--docker标志off可重现的输出
--gpu标志offGPU 加速编码
--strict标志off遇到 lint 错误时失败
--strict-all标志off遇到错误和警告时都失败
--variablesJSON 对象—覆盖在 data-composition-variables 中声明的变量值
--variables-file路径—包含变量值的 JSON 文件(--variables 的替代方案)
--strict-variables标志off在 --variables 中遇到未声明的键或类型不匹配时渲染失败

质量指南: 迭代时使用 draft,审查时使用 standard,最终交付时使用 high。

参数化渲染: 合成在 <html> 根元素上使用 data-composition-variables 声明其变量——这是一个 JSON 声明数组(每个条目包含 {id, type, label, default}),定义了模式。内部的脚本通过 window.__hyperframes.getVariables() 读取解析后的值。CLI 的 --variables '{"title":"Q4 Report"}' 是一个按 id 键化的 JSON 对象,用于覆盖这些声明的默认值以进行单次渲染;缺失的键会回退到默认值,因此同一个可以在开发预览和生产环境中无改动运行。(子合成宿主也可以使用 data-variable-values 按实例覆盖——对象形状相同,范围限定于子合成的单个挂载点。完整模式请参见 hyperframes 技能。)

资产预处理

npx hyperframes tts、transcribe 和 remove-background 生成资产(旁白音频、词级转录、透明视频),这些资产会被放入合成中。每个命令在首次运行时都会下载自己的模型。有关语音选择、Whisper 模型规则(.en 会翻译非英语的陷阱)、输出格式选择(VP9 alpha WebM vs ProRes)以及 TTS → 转录 → 字幕链,请调用 hyperframes-media 技能。

故障排查

npx hyperframes doctor       # 检查环境(Chrome、FFmpeg、Node、内存)
npx hyperframes browser      # 管理捆绑的 Chrome
npx hyperframes info         # 版本和环境详细信息
npx hyperframes upgrade      # 检查更新

如果渲染失败,请先运行 doctor。常见问题:缺少 FFmpeg、缺少 Chrome、内存不足。

其他

npx hyperframes compositions   # 列出项目中的合成
npx hyperframes docs           # 打开文档
npx hyperframes benchmark .    # 基准测试渲染性能

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

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

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.

相关技能