Communitygithub.com

alecs5am/ralphy

コンポジションとレンダリングを担当します。scenario.jsonとasset-manifest.jsonからHyperFrames HTMLコンポジションを組み立て、MP4をレンダリングします。タイミング、トランジション、キャプション、オーディオミックスとダッキング、グリーンゾーン、レンダーパイプライン、VO同期を管理します。メディア自体は生成しません。

ralphy とは？

ralphyは、HyperFramesエコシステムにおけるコンポーザー兼レンダラーエージェントです。`scenario.json`と`asset-manifest.json`からHTMLコンポジション（GSAPアニメーションを含む）をアセンブルし、最終的にMP4をレンダリングします。このエージェントは、タイミングの調整、トランジションの設定、キャプション生成、オーディオミキシング（ラウドネスノーマライズやサイドチェインなど）、ビデオクリップの結合とトリミング、そしてVO同期といった、ポストプロダクションの全工程を担当します。メディアアセット自体は生成せず、アートディレクターから提供された素材を「縫い合わせる」役割に特化しています。主なプラットフォームはHyperFramesであり、FFmpegを含むすべてのレンダリングと処理は、`ralphy render`、`ralphy audio`、`ralphy video`といった専用のCLIコマンドを介してのみ実行されます。エージェントは、`render it`や`compose the video`といったユーザーの要求に応じて起動し、一連のサブタスク（プリフライト、キャプション生成、コンポジション作成、プレビュー、最終レンダリング）を順次実行します。特に、スタイライズドクリップの延長やモーショングラフィックスと動画モデルの使い分けに関する詳細なガイドラインを持ち、高品質な最終出力を保証します。

対応✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/alecs5am/ralphy/tree/HEAD/.agents/skills/editor
オリジナルを見る→すべてのスキルを見る

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

ドキュメント

エディタープレイブック

これを読むタイミング： 「ビデオを構成する」、「レンダリングを実行する」、「レンダリング」、「プレビュー」、「キャプションを修正」、「オーディオミックス」、「最終カット」、「トランジションをタイトにする」。

コンポーザー兼レンダラーです。scenario.json + asset-manifest.json を受け取り、GSAPを使用してHTMLコンポジションをアセンブルし、HyperFramesを介してMP4をレンダリングします。メディアは生成しません。それはアートディレクターの役割です。私が行うのは、ステッチ、タイミング設定、トランジション、キャプション、ミキシング、健全性チェックです。

STOPルール。 ralphy render を介してのみレンダリングします。FFmpegは ralphy audio / ralphy video を介してのみ使用します。デバッグ以外で bunx hyperframes render を直接実行したり、アドホックな ffmpeg シェルを実行したりしないでください。すべてのレシピは自動ログ記録される動詞です。これエージェントの不変条件 #2 です。

エンジン

HyperFrames が唯一のレンダリングエンジンです。すべてのプロジェクトは .ralphy/workspaces/<ws>/projects/<id>/index.html を出力する必要があります。コンポジションルール、GSAPタイムライン、レジストリブロック、キャプション、トランジション、オーディオミキシングについては、hyperframes を参照してください。

CLIクックブック

レンダリングは ralphy render を介してのみ行います。FFmpeg は ralphy audio / ralphy video を介してのみ使用します。デバッグ以外で bunx hyperframes render を直接呼び出したり、アドホックな 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>           # TikTok / Reels 向け -16 LUFS
ralphy audio sidechain --voice <vo>   --music <m> --out <mix.mp3>   # VOに合わせて音楽をダッキング
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秒 → 1つのPNG。
  2. そのPNGを bytedance/seedance-2.0 への新しい ralphy generate video i2v 呼び出しの --first-frame として渡します。新しいクリップは実際の最終フレームから開始されるため、カットは見えなくなります（スタイライズド/ペインタリーアンカーはseedanceのフォトリアル人間プライバシーフィルターをトリガーしません。そのフィルターはフォトリアルな人間の顔にのみ作動します。feedback_seedance_rejects_realistic_people を参照）。
  3. 延長はデフォルトで5秒ではなく、フル15秒ブロックにします。短い延長は慌ただしく感じられ、ダイナミクスを失います。15秒ブロックには真のビート（例：ソロ → 群衆を明らかにするカメラオービット → フィナーレ）のための余地があり、スタイライズドレジスタは静的なワイドショットよりもアクションの多い長いブロックでより強く発揮されます。ダイナミクスのために動くカメラ（オービット/クレーン）を強調します。SUBJECT / STYLE / AUDIO-POLICY プロンプトブロックはブロック間でそのまま維持します。
  4. ralphy video concat でブロックを結合し、フル新しい長さに合わせた音楽ベッドをクライマックスがフィナーレに合うように再生成し、ralphy audio sidechain（VOの下で音楽をダッキング）を実行して render/final.mp4 にコピーします。

適用されないケース： フォトリアルな人間のクリップ（seedance はアンカーを拒否するため、代わりに kwaivgi/kling-v3.0-pro を使用して延長）。遅い静的/ダイアログ駆動のビートで5秒の延長が適切な長さである場合。新しいビートが継続ではなくハードなシーンチェンジである場合（その場合は延長ではなく新しいシーンであり、最終フレームアンカーは不要）。

サブドキュメント (オンデマンドで参照)

ファイル読むタイミング
editor/render-pipeline.mdプリフライト、コンポジション作成、プレビュー、最終レンダリング
editor/vo-sync.mdVOに合わせたカット — ステッチ → 書き起こし → スライス；リバースアリバース + concat demuxer (エージェントの不変条件 #16)
editor/captions.mdcaptions.json をキャプションコンポーネントに配線；タイミング定数を書く前にキャプションを先に
editor/transitions.mdクロスフェード / プッシュ / ワイプパターン
editor/audio-mixing.mdVO + 音楽 + SFX レベル、ダッキング、フェード
editor/green-zone.md1080×1920 セーフゾーン内でのテキスト/オーバーレイ配置
editor/hard-rules.md最終版のための12項目のffmpeg / カット規律チェックリスト

サブタスク

サブタスクタイミングサブドキュメント
preflight「レンダリングの準備はできていますか？」render-pipeline
generate-captionsVO準備完了、captions.jsonがないcaptions + vo-sync (VOに合わせたカット用)
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を返します — 修正してからコンポジションします。すべてのプロジェクトのアドホックな ffprobe ループを置き換えます（#034）。
  2. 次に ralphy editor trim-analyze <id> を実行します。 artifacts/videos/ に対してバッチの gemini-3.1-pro-preview ビジョンパスを実行し、クリップごとのデッドタイム/ホットモーメント/提案 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 — 引き継ぐ前にアートディレクターがクリアしなければならない 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 を介して。 コンポジションにキャプションオーバーレイがある場合（エージェントの不変条件 #16）、HF / Remotion のタイミング定数を書く前にこれを実行してください。VOに合わせたカット全体には、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 "<verbatim>" --stage <feedback|approval|critique|rejection> を介してログに記録する必要があります — カットへのプッシュバック、キャプション修正、オーディオリミックス、「出荷」承認、レンダリングを停止させる批評。シナリオライタープレイブック（scenarist.md → 「ユーザープロンプトログ記録」 を参照）と同じ MUST-log 規律に従います。ログがまばらだと、ポストモーテムレイヤーはユーザーが実際にどのレンダリングバージョンを承認したかを推測することになります。
  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 → Source-clip duration overshoot にあります。構造的な解決策は将来の ralphy editor trim-analyze 動詞にあります（issue 034）。

ピクセル vs コード — モーショングラフィックス決定木 (04.0A.02)

シーンを ralphy generate video にルーティングする前に、出力を分類します。

パターンルート理由
実写シーン（人物、部屋、アクション、天候、ゲームプレイキャプチャ）ralphy generate video (i2v / t2v)モデルがコードでは偽造できないピクセルを生成する
フォトリアル静止画 + パララックスralphy generate image + HyperFrames GSAP トゥイーン画像がアセットであり、モーションがコンポジションである
アニメーションテキスト / キネティックタイポグラフィ / 「WORDS SLAM IN」HyperFrames コンポーネント + GSAP タイムラインコードがタイミングと正確なスペルを制御する；ビデオモデルは文字をぼかし、フォントをドリフトさせる
ローワーサード / ネームカード / クロノHyperFrames HTML + GSAP簡単にパラメータ化可能；ピクセルルートでは生成のたびにフォントを再レンダリングすることになる
アニメーションチャート / データビジュアライゼーションHyperFrames HTML + GSAP / Three.jsコードがデータの信頼できる情報源である；ピクセルルートは値を幻覚させる
アニメーションUIモックアップ / アプリ画面HyperFrames HTML + GSAPピクセルルートはUIアフォーダンスをでっち上げる；結果はAIの粗悪品と読まれる
2つのクリップ間のトランジションHyperFrames シェーダー/クロスフェードレジストリブロック2つのクリップがアセットであり、トランジションはコードレシピである
パーティクル / FX オーバーレイHyperFrames CSS/SVG/Canvas/WebGPU繰り返し可能；ピクセルルートは非決定的である
Lottie アニメーションドロップインHyperFrames lottie アダプタLottie ファイルがアセットであり、ランタイムがそれを決定的に再生する

兆候（bun run lint:templates のリントは prompts.json 内の既知の違反をフラグ付けします）：「アニメーションテキスト」、「キネティックタイポグラフィ」、「ローワーサードがアニメーションイン」、「チャートがアニメーションイン」、「ロゴがスライドイン」、「トランジションワイプ」 → これらはHTML+GSAP側に送られ、ビデオモデルには送られません。これらのフレーズのいずれかを ralphy generate video への --prompt として書いていることに気づいたら、停止して代わりにコンポーネントをコンポーズしてください。

クロスリンク：APIの詳細については hyperframes を参照してください。

歴史的な余談（Remotion）。 92ef823 より前のブランチや STATIC_ROOT / composition-props.json に言及しているポストモーテムを調査している場合、レガシーな Remotion の慣習は editor/render-pipeline.md → Legacy: Remotion STATIC_ROOT recipe に文書化されています。現在の HyperFrames の作業には関係ありません。

引き継ぎ

  • preflight で不足しているアセットが見つかった場合 → アートディレクタープレイブックに従って再生成。
  • タイミングがずれている場合（VO ≠ scenario.duration） → シナリオライタープレイブックに従ってシーンを再タイミング。
  • final-render 後、それがバッチの一部である場合 → プロデューサープレイブック。
  • 新しい HyperFrames パターンの場合 → hyperframes playbook と関連スキル本文 (gsap、lottie、animejs、…) をコードを書く前に参照。
  • 再コンポーズ/再生成中に同じ軸でシーンが2回失敗した場合 → アートディレクタープレイブック → 再生成する代わりにシーンを分割する を参照。再プロンプトを停止し、同じスロット予算内でマイクロショットに分割します。

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