Communitygithub.com

alees5am/ralphy

HyperFrames CLI 開発ループ — `npx hyperframes` でスキャフォールディング (init)、検証 (lint、inspect)、プレビュー、レンダリング、環境トラブルシュート (doctor、browser、info、upgrade) を実行します。これらのコマンドを実行するときや、HyperFrames のビルド・レンダリング環境のトラブルシューティングを行う際に使用します。アセット前処理コマンド (`tts`、`transcribe`、`remove-background`) については、代わりに `hyperframes-media` スキルを呼び出してください。

ralphy とは?

HyperFrames CLI スキルは、HyperFrames フレームワークを使用してビデオコンポジションを構築・レンダリングするための包括的な開発ループを提供します。主なワークフローは、スキャフォールディング、作成、リント、ビジュアルインスペクト、プレビュー、レンダリングです。`npx hyperframes` コマンドラインツールを中心に設計されており、対話型ウィザードやテンプレート (blank、warm-grain、play-mode など) を使用したプロジェクトの初期化が可能で、Tailwind v4.2 ブラウザランタイムもサポートしています。リンティング機能では `index.html` と `compositions/` ディレクトリ内のファイルをチェックし、不足している `data-composition-id`、重複トラック、未登録タイムラインなどを検出します。ビジュアルインスペクトはヘッドレス Chrome でレンダリングコンポジションを分析し、吹き出しやコンテナからはみ出すテキスト、キャンバス外へのテキストあふれ、クリッピングコンテナをエスケープする子要素などを報告します。プレビューモードはホットリロードをサポートし、レンダリングは `--quality draft` から `--quality high` までの品質オプション、mp4 や透明 WebM などのフォーマット、docker による再現可能な出力を提供します。変数を使ったパラメトリックレンダリングも可能です。また、`doctor`、`browser`、`info`、`upgrade` コマンドによる環境トラブルシューティング機能も備えています。このスキルは Node.js >= 22 と FFmpeg を必要とします。

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

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

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

ドキュメント

HyperFrames CLI

すべての操作は npx hyperframes で実行します。Node.js >= 22 と FFmpeg が必要です。

ワークフロー

  1. スキャフォールディング — npx hyperframes init my-video
  2. 作成 — HTML コンポジションを記述 (hyperframes スキルを参照)
  3. リント — 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 を使用する場合は、クラスやテーマトークンを編集する前に tailwind スキルを呼び出してください。スキャフォールディングは Studio の Tailwind v3 セットアップではなく、ブラウザランタイムを介した Tailwind v4.2 を使用します。

リント

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 # 明示的なヒーローフレームのタイムスタンプ

lint と validate の後、特に吹き出し、カード、キャプション、タイトなタイポグラフィが含まれるコンポジションで使用します。以下を報告します。

  • 最も近いビジュアルコンテナまたは吹き出しの外側に延びているテキスト
  • 自身の固定幅/固定高さのボックスでクリップされているテキスト
  • コンポジションキャンバスの外側に延びているテキスト
  • クリッピングコンテナからエスケープしている子要素

エラーはレンダリング前に修正する必要があります。警告はエージェントによるレビューのために表示されます。警告でも失敗させるには --strict を追加します。繰り返し発生する静的問題はデフォルトで折りたたまれ、LLM のコンテキストウィンドウのために JSON 出力をコンパクトに保ちます。オーバーフローがエントランス/イグジットアニメーションで意図的である場合は、要素または祖先に data-layout-allow-overflow をマークします。装飾要素を監査対象から除外するには、data-layout-ignore をマークします。

npx hyperframes layout は、同じビジュアルインスペクションパスの互換性エイリアスとして引き続き使用できます。

プレビュー

npx hyperframes preview                   # カレントディレクトリを提供
npx hyperframes preview --port 4567       # カスタムポート (デフォルト 3002)

ファイルの変更時にホットリロードします。ブラウザで Studio が自動的に開きます。

プロジェクトをユーザーに引き渡すときは、ソースの index.html パスではなく、Studio プロジェクト URL を使用してください。

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

プレビュー出力の実際のポートとプロジェクトディレクトリ名を使用します。たとえば、codex-openai-video で npx hyperframes preview --port 3017 を実行した後、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/名前_タイムスタンプ.mp4出力パス
--fps24, 30, 603060fps はレンダリング時間が 2 倍になります
--qualitydraft, standard, highstandarddraft はイテレーション用
--formatmp4, webmmp4WebM は透明度をサポート
--workers1-8 または autoauto各ワーカーは Chrome を起動します
--dockerフラグオフ再現可能な出力
--gpuフラグオフGPU アクセラレーションによるエンコーディング
--strictフラグオフリントエラーで失敗
--strict-allフラグオフエラーと警告の両方で失敗
--variablesJSON オブジェクト—data-composition-variables で宣言された変数値を上書き
--variables-fileパス—変数値を含む JSON ファイル (--variables の代替)
--strict-variablesフラグオフ--variables で未宣言のキーや型の不一致がある場合にレンダリングを失敗

品質ガイダンス: イテレーション中は draft、レビュー用は standard、最終納品用は high。

パラメトリックレンダリング: コンポジションは <html> ルートで data-composition-variables を使用して変数を宣言します。これは宣言の JSON 配列 ({id, type, label, default} をエントリごとに) であり、スキーマを定義します。内部のスクリプトは window.__hyperframes.getVariables() を介して解決された値を読み取ります。CLI の --variables '{"title":"Q4 レポート"}' は id をキーとする JSON オブジェクト で、1 回のレンダリングのために宣言されたデフォルトを上書きします。欠落したキーはそのままになるため、同じコンポジションが開発プレビューと本番の両方で変更なしで実行されます。(サブコンポジションホストは、data-variable-values を使用してインスタンスごとに上書きすることもできます。これは同じオブジェクト形状で、サブコンポジションの 1 つのマウントにスコープされます。完全なパターンについては hyperframes スキルを参照してください。)

アセット前処理

npx hyperframes tts、transcribe、remove-background はアセット (ナレーション音声、単語レベルのトランスクリプト、透明動画) を生成し、コンポジションにドロップされます。各コマンドは初回実行時に独自のモデルをダウンロードします。音声選択、Whisper モデルのルール (.en が非英語を翻訳するという落とし穴)、出力形式の選択 (VP9 アルファ 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.

関連スキル