Communitygithub.com

alecs5am/ralphy

HyperFrames CLI 開發循環 — 使用 `npx hyperframes` 進行初始化 (init)、驗證 (lint, inspect)、預覽 (preview)、渲染 (render) 與環境除錯 (doctor, browser, info, upgrade)。在執行這些指令或排除 HyperFrames 建置/渲染環境問題時使用。若需資產預處理指令 (`tts`, `transcribe`, `remove-background`),請改為呼叫 `hyperframes-media` 技能。

ralphy 是什麼?

此技能封裝了 HyperFrames CLI 的完整開發循環,讓 AI 代理能透過 `npx hyperframes` 命令引導使用者完成從專案初始化、撰寫 HTML 合成內容、程式碼檢查、視覺檢查、預覽到最終渲染的流程。它支援所有主要平台(需要 Node.js >= 22 和 FFmpeg)。透過 `init` 命令可建立專案結構、複製媒體檔案並選用 Whisper 轉錄音訊。`lint` 和 `inspect` 命令能分別捕捉結構性錯誤(如缺少 data-composition-id)與視覺問題(如文字溢出容器或畫布)。渲染命令支援多種品質與格式(MP4、WebM),並可透過 `--variables` 參數化渲染,讓同一個合成可在開發預覽與生產環境中無縫運作。此外,`doctor`、`browser`、`info` 和 `upgrade` 等除錯命令能協助診斷環境問題(如缺少 Chrome、FFmpeg、記憶體不足)。對於資產預處理(TTS、轉錄、去背),則需呼叫 `hyperframes-media` 技能。

相容平台~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. 檢查 — 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 技能。該初始化動作使用 Tailwind v4.2 的瀏覽器執行階段,而非 Studio 的 Tailwind v3 設定。

程式碼檢查

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 可讓警告也導致失敗。重複的靜態問題預設會被摺疊,讓 JSON 輸出保持簡潔以利 LLM 內容視窗。若溢出是為了入場/出場動畫而刻意為之,請在元素或祖先標記 data-layout-allow-overflow。若裝飾性元素不應被審計,請標記 data-layout-ignore。

npx hyperframes layout 仍然可作為相同視覺檢查的相容別名使用。

預覽

npx hyperframes preview                   # 提供目前目錄服務
npx hyperframes preview --port 4567       # 自訂連接埠(預設 3002)

檔案變更時會熱重新載入。瀏覽器會自動開啟 Studio。

將專案交回給使用者時,請使用 Studio 專案網址,而非原始 index.html 路徑:

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/name_timestamp.mp4輸出路徑
--fps24, 30, 603060fps 渲染時間加倍
--qualitydraft, standard, highstandarddraft 用於迭代
--formatmp4, webmmp4WebM 支援透明背景
--workers1-8 或 autoauto每個 worker 會啟動一個 Chrome
--docker布林標記關閉可重現的輸出
--gpu布林標記關閉GPU 加速編碼
--strict布林標記關閉遇到 lint 錯誤即失敗
--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 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.

相關技能