Communitygithub.com

delorenj/skills (HyperFrames CLI 技能)

HyperFrames CLI 開發循環 — 使用 `npx hyperframes` 進行專案初始化 (init)、驗證 (lint, inspect)、預覽、渲染以及環境問題排除 (doctor, browser, info, upgrade)。

skills (HyperFrames CLI 技能) 是什麼?

這是一個專為 HyperFrames 框架設計的 CLI 技能,整合了從專案初始化到最終渲染的完整開發工作流程。開發者可以透過 `npx hyperframes` 指令執行 scaffolding、linting、視覺檢查、預覽以及渲染。它支援 Node.js >= 22 和 FFmpeg,並提供 Docker 模式以確保渲染結果的一致性。此技能特別適合需要快速迭代影片或動畫組合的開發者,能有效減少手動設定的錯誤。此外,它還包含完整的環境檢測工具 (doctor) 和升級指令,幫助開發者快速診斷常見問題。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/delorenj/skills/tree/HEAD/hyperframes-cli

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

HyperFrames CLI

所有操作都透過 npx hyperframes 執行。需要 Node.js >= 22 和 FFmpeg。

工作流程

  1. Scaffold — npx hyperframes init my-video
  2. 撰寫 — 編寫 HTML 組合(請參閱 hyperframes 技能)
  3. Lint — npx hyperframes lint
  4. 視覺檢查 — npx hyperframes inspect
  5. 預覽 — npx hyperframes preview
  6. 渲染 — npx hyperframes render

請在預覽前先進行 Lint 和檢查。lint 會捕捉遺失的 data-composition-id、重疊的軌道以及未註冊的時間軸。inspect 會在無頭 Chrome 中開啟渲染的組合,在時間軸上搜尋,並回報文字溢出氣泡/容器或畫布的情況。

Scaffolding

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 時,請在編輯類別或主題 token 之前調用 tailwind 技能。脚手架使用 Tailwind v4.2 的瀏覽器執行環境,而非 Studio 的 Tailwind v3 設定。

Linting

npx hyperframes lint                  # 目前目錄
npx hyperframes lint ./my-project     # 特定專案
npx hyperframes lint --verbose        # 資訊層級的發現
npx hyperframes lint --json           # 機器可讀

Lint 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 專案 URL,而非來源 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標誌off可重複的輸出
--gpu標誌offGPU 加速編碼
--strict標誌off在 lint 錯誤時失敗
--strict-all標誌off在錯誤和警告時皆失敗
--variablesJSON 物件—覆寫 data-composition-variables 中宣告的變數值
--variables-file路徑—包含變數值的 JSON 檔案(--variables 的替代方案)
--strict-variables標誌off若 --variables 中有未宣告的鍵或型別不符,則渲染失敗

品質指引: 迭代時使用 draft,審查時使用 standard,最終交付時使用 high。

參數化渲染: 組合在 <html> 根元素上使用 data-composition-variables 宣告其變數 — 這是一個 JSON 宣告陣列(每個條目包含 {id, type, label, default}),定義了結構描述。內部的腳本透過 window.__hyperframes.getVariables() 讀取解析後的值。CLI 的 --variables '{"title":"Q4 Report"}' 是一個 JSON 以 id 為鍵的物件,會覆寫針對一次渲染宣告的預設值;遺漏的鍵會回退,因此同一個組合在開發預覽和生產環境中都能不變地運作。(子組合宿主也可以使用 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 14 individual skills — each has its own dedicated page.

delorenj/skills

Plan and generate terminal ASCII animations/screensaver-style output (FPS, refresh rules, loop policy, low-flicker guidance), with a static poster frame and an optional local demo script.

delorenj/skills

ASCII video: convert video/audio to colored ASCII MP4/GIF.

delorenj/skills

Plan, build and quality-check a premium short commercial for a real business (roofing, property, ecommerce, B2B software) using AI-generated footage, code-built motion (HTML/GSAP), selective Three.js and an independent-critic "Gauntlet" loop. Use when asked to make a launch-style / SaaS-style video, business ad, explainer, sample reel or pitch video, or to review and improve one. Encodes motion principles distilled from 28 professional launch films, a quality bar, audio rules and a business-offer playbook.

delorenj/skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

delorenj/skills

Generate professional voiceovers using ElevenLabs AI. Use when the user needs to create voiceovers for videos, audio narration, or text-to-speech content. Supports multiple voices with character presets (narrator, salesperson, expert) for natural delivery. Includes single scene regeneration for fine-tuning.

delorenj/skills

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.

delorenj/skills

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.

delorenj/skills

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.

delorenj/skills

Manim CE animations: 3Blue1Brown math/algo videos.

delorenj/skills

Join a Google Meet or Zoom call as a video meeting agent via PikaStreaming. Trigger: user drops a Google Meet or Zoom link, or asks to join a meeting.

delorenj/skills

Translate an existing Remotion (React-based) video composition into a HyperFrames HTML composition. Use ONLY when the user explicitly asks to port, convert, migrate, translate, or rewrite a Remotion composition as HyperFrames (e.g. "port my Remotion project to HyperFrames"). Do NOT use when (a) authoring a NEW HyperFrames composition (even if A/B-testing a Remotion video); (b) Remotion is mentioned in passing; (c) Remotion code is shared as reference, not for translation; (d) the user wants "the same video as my Remotion one" without explicitly asking to migrate the source — treat as a fresh HyperFrames build. When in doubt, default to the `hyperframes` skill. Detects unsupported patterns (useState, useEffect side effects, async calculateMetadata, third-party React component libraries, `@remotion/lambda`) and recommends the runtime interop escape hatch instead of a lossy translation.

delorenj/skills

Generate speech using the self-hosted voxxy (vox) TTS service at https://vox.delo.sh. Use when the user asks to speak, say, narrate, synthesize speech, clone a voice, create a voice, add or register a voice, pipe TTS, or control voice qualities by description (e.g. "a young woman with a cheerful voice"). Handles HTTP API usage, voice profile management, description-based voice design, cloning, MCP registration, and integration patterns for new platforms.

delorenj/skills

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

delorenj/skills

YouTube transcripts to summaries, threads, blogs.

相關技能