Communitygithub.com

alecs5am/ralphy

組合與渲染工匠——將 scenario.json 和 asset-manifest.json 組裝成 HyperFrames HTML 合成，並渲染為 MP4。負責時間安排、轉場、字幕、混音與側鏈壓縮、綠色安全區、渲染管線以及旁白同步。本身不產生任何媒體資產。

ralphy 是什麼？

「ralphy」技能是一個專業的影片組合與渲染工具，專為 AI 代理（如 Claude Code、Cursor、Codex）設計，用於處理從原始素材到最終 MP4 的完整後期製作管線。它接收 `scenario.json`（場景與時間結構）和 `asset-manifest.json`（資產路徑），並使用 HyperFrames 引擎（HTML + GSAP）進行合成，最終渲染產出。ralphy 本身不生成任何媒體（如 AI 影片或圖像），這部分由「藝術總監（art director）」技能負責；它專注於拼接、時間軸調整、轉場、字幕生成與樣式、音訊混音（包括人聲與音樂的側鏈壓縮）、以及最終渲染品管。支援 HyperFrames 和 Remotion（舊版）兩種渲染引擎，但明確規定僅透過 `ralphy render` 指令進行渲染，禁止直接呼叫 `bunx hyperframes render` 或臨時的 `ffmpeg` 指令，以確保日誌記錄與版本控制。此技能適用於 macOS/Linux 平台，並附帶詳細的子文件（如渲染管線、旁白同步、字幕、轉場、混音、綠色安全區與嚴格規則）作為隨需參考。其主要價值在於標準化後期工作流程，強制不修改渲染引擎或資產，並提供一系列 CLI 指令（如生成字幕、音訊正規化、側鏈壓縮、影片裁切與字幕燒錄）以確保產出品質與可重複性。

相容平台✓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 命令——每個操作都是一個會自動記錄的動詞。AGENTS 不變量 #2。

引擎

HyperFrames 是唯一的渲染引擎。每個專案都必須包含 .ralphy/workspaces/<ws>/projects/<id>/index.html。關於組合規則、GSAP 時間軸、註冊表區塊、字幕、轉場、混音的詳細資訊，請參閱 hyperframes。

CLI 操作手冊

僅透過 ralphy render 渲染。僅透過 ralphy audio / ralphy video 使用 FFmpeg。除除錯外，切勿直接呼叫 bunx hyperframes render，也切勿以 ad-hoc 方式執行 ffmpeg——以下每個配方都是一個會自動記錄的動詞。

# 最終渲染
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        # 組合前的 asset-manifest
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 作為新 ralphy generate video i2v 呼叫（使用 bytedance/seedance-2.0）的 --first-frame。新片段從真實的最後影格開始，因此剪接點是看不見的。（風格化/油畫風的錨點不會觸發 seedance 的照片級真實人物隱私篩選器——該篩選器僅會在照片級真實的人臉上觸發，詳見 feedback_seedance_rejects_realistic_people。）
  3. 預設將延伸設定為完整的 15 秒區塊，而非 5 秒。 短延伸會讓人感覺倉促且失去動態；一個 15 秒的區塊有足夠空間容納一個真正的節奏（例如，獨奏 → 鏡頭環繞揭示人群 → 結尾），而且風格化風格在動作密集的長區塊上的表現比靜態廣角更好。強調動態的移動鏡頭（環繞/吊臂）。保持主體/風格/音訊政策提示區塊在各區塊間完全一致。
  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>。 單一規範性檢查，針對持續時間、fps、編解碼器、音軌、音樂間隙與總片段長度之比、以及場景到磁碟的完整性。遇到紅燈則退出並回傳 1——在組合前修正。取代每個專案中 ad-hoc 的 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（透過修改時間保持冪等——僅重新分析有變動的片段）。使用 --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——藝術總監在移交前必須通過的 HARD 快照審查關卡。如果您到達此處時磁碟上沒有快照，請退回給藝術總監。
  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 → 來源片段持續時間超拍。結構性解決方案存在於未來的 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 著色器/淡入淡出註冊表區塊兩個片段是資產；轉場是程式碼配方
粒子 / 特效疊加層HyperFrames CSS/SVG/Canvas/WebGPU可重複；像素路線不確定
Lottie 動畫匯入HyperFrames lottie 轉接器Lottie 檔案是資產；執行時期會確定性地播放它

警訊（bun run lint:templates 會標記 prompts.json 中已知的違規者）：「動畫文字」、「動態排版」、「下方三分之一動畫進入」、「圖表動畫進入」、「標誌滑入」、「轉場擦除」→ 這些都應進入 HTML+GSAP 端，而非影片模型。如果您發現自己將這些短語之一作為 --prompt 寫入 ralphy generate video，請停止並改為組合元件。

交叉連結：閱讀 hyperframes 以獲取 API 細節。

歷史備註（Remotion）。 如果您在探索 92ef823 之前的舊分支或提及 STATIC_ROOT / composition-props.json 的事後檢討文件，舊版 Remotion 的慣例記錄於 editor/render-pipeline.md → 舊版：Remotion STATIC_ROOT 配方。與目前的 HyperFrames 工作無關。

交接

  • preflight 發現缺少資產 → 交給藝術總監手冊以重新產生。
  • 時間安排偏移（旁白 ≠ 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