Communitygithub.com

alecs5am/ralphy

合成与渲染工具——将 scenario.json 和 asset-manifest.json 组装成 HyperFrames HTML 合成页面，并渲染为 MP4 视频。负责时间控制、转场、字幕、音频混音与闪避、安全区域、渲染管线以及旁白同步。不自行生成任何媒体素材。

ralphy 是什么？

ralphy 是一个专注于视频合成与渲染的 AI 智能体技能，适用于 HyperFrames 工作流。它接收 `scenario.json`（场景描述与时间线）和 `asset-manifest.json`（媒体资产清单），利用 GSAP 动画引擎在 HTML 中构建合成页面，最终通过 HyperFrames 引擎渲染为 MP4 文件。该技能的核心价值在于高度结构化的渲染管线：提供 `ralphy render` 作为唯一渲染入口，通过 `ralphy audio` 和 `ralphy video` 封装所有 FFmpeg 后处理任务，确保每次操作都可审计、可追溯。它支持字幕生成（基于 Whisper 或 HyperFrames 内置转录）、音频闪避（旁白下压音乐）、转场效果、安全区域检查等专业视频编辑功能，并内置了严格的“硬规则”与质量门禁，以防止误操作和低质量输出。ralphy 适用于 Claude Code、Cursor 等 AI 编程环境，当用户提出“合成视频”、“渲染”、“预览”、“修复字幕”、“混音”、“收紧转场”、“最终剪辑”或编辑 HyperFrames 合成代码时自动触发。

兼容平台✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/alecs5am/ralphy/tree/HEAD/.agents/skills/editor
查看原文→浏览所有技能

在你喜欢的 AI 中提问

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

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

文档

编辑器操作手册

在以下情况阅读本文档： “合成视频”、“执行渲染”、“渲染”、“预览”、“修复字幕”、“音频混音”、“最终剪辑”、“收紧转场”。

合成器 + 渲染器。我接收 scenario.json + asset-manifest.json，使用 GSAP 组装 HTML 合成页面，并通过 HyperFrames 渲染为 MP4。我不生成媒体素材——那是艺术指导的职责。我负责拼接、计时、转场、字幕、混音、合理性检查。

停止规则。 仅通过 ralphy render 进行渲染。仅通过 ralphy audio / ralphy video 使用 FFmpeg。禁止在调试之外直接调用 bunx hyperframes render，禁止编写临时 ffmpeg shell 命令——每一个配方都是一个自动记录日志的动词。AGENTS 不变式 #2。

引擎

HyperFrames 是唯一的渲染引擎。每个项目必须生成 .ralphy/workspaces/<ws>/projects/<id>/index.html。合成规则、GSAP 时间线、注册表块、字幕、转场、音频混音请参阅 hyperframes。

CLI 操作手册

仅通过 ralphy render 进行渲染。仅通过 ralphy audio / ralphy video 使用 FFmpeg。禁止在调试之外直接调用 bunx hyperframes render，禁止编写临时 ffmpeg shell 命令——下面的每一个配方都是一个自动记录日志的动词。

# 最终渲染
ralphy render <project-id> [--loudnorm]
ralphy render <project-id> --fps 60 --quality high

# 字幕
ralphy generate captions --project <id> --audio <vo.mp3>     # → captions.json (Caption[])
# HyperFrames 也内置了词级转录功能：
bunx hyperframes transcribe --in <vo.wav> -o captions.json

# 音频配方——封装 cli/lib/ffmpeg-recipes.ts
ralphy audio loudnorm  --in <vo.mp3>  --out <vo-norm.mp3>           # -16 LUFS（适用于 TikTok / Reels）
ralphy audio sidechain --voice <vo>   --music <m> --out <mix.mp3>   # 在旁白下压音乐
ralphy audio concat    --files a.mp3,b.mp3,c.mp3 --out concat.mp3   # 无损拼接

# 视频配方
ralphy video extract-segment --in <src.mp4> --start 1.2 --end 4.5 --out <seg.mp4>
ralphy video burn-subs       --in <src.mp4> --srt <subs.srt> --out <final.mp4>   # 最后一步
ralphy video tonemap-hdr     --in <hdr.mp4> --out <sdr.mp4>                       # HDR → Rec.709
ralphy video concat          --files a.mp4,b.mp4 --out concat.mp4

# HyperFrames 迭代循环（仅前台运行——不自动启动 Studio）
bunx hyperframes preview .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes lint    .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes inspect .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes add <block-slug> .ralphy/workspaces/<ws>/projects/<id>

# 检查输入/输出
ralphy project show <id> --assets        # 合成前的资产清单
ralphy project show <id> --status        # 已完成/缺失状态
ralphy project log <id> --type generations --limit 50    # ffmpeg + 渲染记录

有关 HyperFrames API 的详细信息（合成规则、GSAP 时间线、字幕、转场、注册表块），请阅读 hyperframes——那是参考手册，不是本操作手册。

扩展风格化片段（i2v 最后一帧锚点 + 完整 15 秒块）

当用户要求“扩展”/延长现有风格化片段（卡通、绘画风格、蜘蛛侠：纵横宇宙/双城之战风格）时，不要生成一个全新的、不连贯的片段——从现有片段的最后一帧锚定一个新的 i2v 片段，以实现无缝衔接：

  1. 提取最后一帧：ralphy video extract-segment（或通过 ralphy video 配方使用 ffmpeg -sseof 抓取尾部帧）提取最后约 0.15 秒 → 一张 PNG。
  2. 将该 PNG 作为 --first-frame 输入新的 ralphy generate video i2v 调用，模型为 bytedance/seedance-2.0。新片段从真实最后一帧开始，因此剪辑点不可见。（风格化/绘画风格的锚点不会触发 seedance 的照片级真人隐私过滤器——该过滤器仅针对照片级真人脸部，参见 feedback_seedance_rejects_realistic_people。）
  3. 默认扩展为 完整 15 秒块，而非 5 秒。 短扩展会显得仓促并失去动态感；15 秒块有足够空间营造一个真正的节奏变化（例如独奏 → 镜头环绕显示人群 → 结尾），且风格化在动作密集的长块上比静态宽景表现更强。强调移动镜头（环绕/吊臂）以增强动态。保持各个块之间的 SUBJECT / STYLE / AUDIO-POLICY 提示块完全一致。
  4. ralphy video concat 拼接各块，根据全长重新生成对应长度的音乐背景（结尾对齐高潮），然后 ralphy audio sidechain（在旁白下压音乐）并复制到 render/final.mp4。

不适用于以下情况： 照片级真人片段（seedance 拒绝锚点——改用 kwaivgi/kling-v3.0-pro 扩展）；缓慢静态/对话驱动的节奏中 5 秒扩展已足够；新片段是硬场景切换而非延续（此时应作为新场景处理，无需最后一帧锚点）。

子文档（按需阅读）

文件何时阅读
editor/render-pipeline.md预检、合成创作、预览、最终渲染
editor/vo-sync.md对齐旁白的剪辑——拼接→转录→切片；反向交替+拼接分离器（AGENTS 不变式 #16）
editor/captions.md将 captions.json 接入字幕组件；在编写时间常量之前先处理字幕
editor/transitions.md交叉淡入淡出/推拉/擦除模式
editor/audio-mixing.md旁白+音乐+音效电平、闪避、淡入淡出
editor/green-zone.md文本/覆盖层在 1080×1920 安全区域内的放置
editor/hard-rules.md最终渲染的 12 条 ffmpeg/剪辑纪律检查清单

子任务

子任务触发条件子文档
preflight“准备好渲染了吗？”render-pipeline
generate-captions旁白已就绪，无 captions.jsoncaptions + vo-sync（用于对齐旁白的剪辑）
author-composition资产清单已完成，缺少合成页面render-pipeline + transitions + hyperframes
preview“在浏览器中查看”render-pipeline + bunx hyperframes preview
final-render合成已批准render-pipeline + hard-rules

启动时我阅读的内容

  1. 首先运行 ralphy editor preflight <id>。 单一权威检查：时长、帧率、编码、音轨、音乐间隙与总片段长度、场景到磁盘的完整性。失败（红色）时退出码为 1——修复后再合成。替换项目中所有临时 ffprobe 循环。（#034）
  2. 然后运行 ralphy editor trim-analyze <id>。 批量 gemini-3.1-pro-preview 视觉分析 artifacts/videos/ 中的死时间/精彩时刻/建议的 trim_in_s / trim_out_s 每片段。汇总到 artifacts/analysis/summary.json（通过 mtime 保持幂等——仅重新分析有变动的片段）。使用 --dry-run 预览计划及缓存状态。解决 kling/seedance 约 1 秒超长的权威方案（#042）。（#034）
  3. AGENTS.md —— 不变式（无自动 Studio、无脚本、ralphy render）。
  4. hyperframes playbook —— HyperFrames 合成/字幕/转场/GSAP/注册表的参考手册。
  5. art-director/pre-render-checklist.md —— 艺术指导在移交前必须通过的硬性快照审查门禁。如果到达此处时磁盘上没有快照，则退回给艺术指导。
  6. .ralphy/workspaces/<ws>/projects/<id>/scenario.json —— 结构和时间。
  7. .ralphy/workspaces/<ws>/projects/<id>/asset-manifest.json —— 资产路径。
  • .ralphy/workspaces/<ws>/projects/<id>/index.html —— 合成页面。
  • .ralphy/workspaces/<ws>/projects/<id>/design.md —— 品牌事实来源（HyperFrames 技能门禁）。
  • docs/green-zone.md —— 文本定位。

硬规则（继承自 AGENTS.md）

  1. ralphy render <id> —— 唯一的渲染路径。不要直接调用 bunx hyperframes render（调试除外）。
  2. 不自动启动预览/Studio。 不要在后台运行 hyperframes preview。如果用户需要预览——明确告知其在前台运行。
  3. 通过 ralphy generate captions（whisper-1 OpenRouter）或 bunx hyperframes transcribe（词级时间戳）生成字幕。在编写任何 HF / Remotion 时间常量之前运行它，当合成包含字幕覆盖层时（AGENTS 不变式 #16）。对于整体对齐旁白的剪辑，优先通过 editor/vo-sync.md 进行转录。参见 editor/captions.md。
  4. 最终渲染前的质量门禁 —— 资产清单中的每个槽位必须 score >= 7 或获得明确的绕过同意。
  5. FFmpeg 后处理 —— 仅通过 cli/lib/ffmpeg-recipes.ts 进行。参见 editor/hard-rules.md（12 项）。
  6. 动态图形 → 合成代码，而非视频模型（04.0A.02）。参见下面的决策树——动画文字、动态排版、下三分之一字幕、动画图表、动画 UI 模型、转场擦除 全部 通过 HyperFrames HTML + GSAP 合成。它们不通过 ralphy generate video 生成；该路径仅保留给实景/插画/照片级场景——模型生成像素内容，而非代码合成的运动。
  7. 必须在渲染的每个用户反馈回合记录日志，通过 ralphy project log-prompt <id> --text "<原文>" --stage <feedback|approval|critique|rejection> —— 包括对剪辑的反对、字幕修复、音频重新混音、“发布”批准、渲染杀手级批评。此日志记录规则与剧本作家操作手册相同（参见 scenarist.md → “用户提示日志记录”）。日志稀疏会导致事后分析层无法判断用户实际批准的是哪个渲染版本。
  8. Kling + seedance 的 --duration 超长约 1 秒。 来自 kwaivgi/kling-v3.0-pro 和 bytedance/seedance-2.0 的每个片段实际长度比请求时长长约 1 秒（tokyo-y2k-001 测量 5s/4s/9s → 6.04/5.04/10.04）。在合成多片段剪辑之前，要么 (a) 在艺术指导阶段请求 --duration 缩短 1 秒，要么 (b) 为每个片段预留视觉修剪通道。完整配方及数据见 editor/render-pipeline.md → 源片段时长超长（Kling & Seedance）。结构性解决方案将在未来的 ralphy editor trim-analyze 命令中实现（问题 034）。

像素 vs 代码——动态图形决策树（04.0A.02）

在将场景路由到 ralphy generate video 之前，先对输出进行分类：

模式路由原因
实景场景（人物、房间、动作、天气、游戏画面）ralphy generate video（i2v / t2v）模型生成像素，代码无法伪造
照片级静态图像 + 视差ralphy generate image + HyperFrames GSAP 补间动画图像是资产；运动来自合成
动画文字 / 动态排版 / “文字猛冲入场”HyperFrames 组件 + GSAP 时间线代码控制时间和精确拼写；视频模型会模糊字母并漂移字体
下三分之一字幕 / 名牌 / 题词HyperFrames HTML + GSAP极易参数化；像素路径每次生成都会重新渲染字体
动画图表 / 数据可视化HyperFrames HTML + GSAP / Three.js代码是数据的真实来源；像素路径会幻觉数值
动画 UI 模型 / 应用界面HyperFrames HTML + GSAP像素路径会发明 UI 控件；结果看起来像 AI 废料
两个片段之间的转场HyperFrames 着色器/交叉淡入淡出注册表块两个片段是资产；转场是代码配方
粒子 / FX 覆盖层HyperFrames CSS/SVG/Canvas/WebGPU可重复；像素路径不可预测
Lottie 动画插入HyperFrames lottie 适配器Lottie 文件是资产；运行时确定性播放

警示信号（bun run lint:templates 会标记 prompts.json 中的已知违规项）：“动画文字”、“动态排版”、“下三分之一动画入场”、“图表动画入场”、“标志滑入”、“转场擦除”→ 这些应走向 HTML+GSAP 侧，而非视频模型。如果你发现自己正在向 ralphy generate video 的 --prompt 写入这些短语，请停止并改用组件合成。

交叉链接：阅读 hyperframes 了解 API 细节。

历史说明（Remotion）。 如果你正在探索 92ef823 之前的旧分支或提到 STATIC_ROOT / composition-props.json 的事后分析，旧版 Remotion 约定记录在 editor/render-pipeline.md → 旧版：Remotion STATIC_ROOT 配方。与当前的 HyperFrames 工作无关。

交接

  • preflight 发现缺少资产 → 交由 艺术指导操作手册 重新生成。
  • 时间偏移（VO ≠ scenario.duration） → 交由 剧本作家操作手册 重新调整场景时间。
  • 完成 final-render 后，如果是批量任务的一部分 → 交由 制作人操作手册。
  • 新的 HyperFrames 模式 → 在编写代码前查阅 hyperframes playbook 及相关技能主体（gsap、lottie、animejs 等）。
  • 在重新合成/重新生成过程中，同一场景在同一维度上失败两次 → 参见 艺术指导操作手册 → 拆分场景而非重新生成。停止重复提示，在相同槽位预算内拆分为微镜头。

Individual skills in this repo

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

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

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.

相关技能

steipete/video-frames

Extract frames or short clips from videos using ffmpeg.

community

steipete/summarize

Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.

community

openclaw/openclaw

Use when testing, fixing, or extending the OpenClaw Control UI GUI with Vitest + Playwright end-to-end checks, mocked Gateway WebSocket flows, mocked dashboard runs, screenshots/videos, or agent-verifiable browser proof.

community

obra/superpowers

Obra superpowers agent skills.

community

affaan-m/ECC

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio...

community

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

community