Communitygithub.com

shengdabai/Tony-Claude-Code-Skills

HyperFrames CLI 開發循環 — 使用 `npx hyperframes` 進行專案初始化 (init)、驗證 (lint, inspect)、預覽、渲染及環境除錯 (doctor, browser, info, upgrade)。在執行上述任一命令或排除 HyperFrames 建置/渲染環境問題時使用。對於資產預處理命令(`tts`、`transcribe`、`remove-background`),請改為呼叫 `hyperframes-media` 技能。

Tony-Claude-Code-Skills 是什麼?

這個技能封裝了 HyperFrames CLI 的完整開發工作流程,讓 AI Agent(如 Claude Code)可以透過統一的 `npx hyperframes` 命令來建立、驗證、預覽和渲染基於 HTML 的影片合成。它的核心價值在於提供一個自動化且結構化的開發循環:從使用互動式精靈或預設模板初始化專案,到對 HTML 合成佈局進行靜態檢查(lint)與視覺檢測(inspect),再到啟動具備熱重載功能的本地預覽伺服器,最後產生標準的 MP4/WebM 影片檔案。此外,它還包含環境除錯工具(doctor、browser、info、upgrade),協助解決常見的依賴問題(如 FFmpeg、Chrome)。此技能支援 Node.js >= 22 和 FFmpeg,適用於 Claude Code、Coder、Cursor 等基於終端機的 AI 助手,是開發 HyperFrames 影片專案的必備工具集。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shengdabai/Tony-Claude-Code-Skills/tree/HEAD/skills/hyperframes-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 會捕捉缺少 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 專案 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每個會產生 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"}' 是一個以 id 為鍵的 JSON 物件,用於覆寫單次渲染的宣告預設值;缺少的鍵會回退,因此相同的合成在開發預覽和生產環境中運行不變。(子合成宿主也可以使用 data-variable-values 對每個實例進行覆寫 — 相同的物件結構,作用域為子合成的一次掛載。完整模式請參見 hyperframes 技能。)

資產預處理

npx hyperframes tts、transcribe 和 remove-background 會產生資產(旁白音訊、逐詞轉錄、透明影片),這些資產會被放入合成中。每個命令在首次執行時會下載自己的模型。有關語音選擇、Whisper 模型規則(.en 翻譯非英語的陷阱)、輸出格式選擇(VP9 alpha WebM 與 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 8 individual skills — each has its own dedicated page.

shengdabai/Tony-Claude-Code-Skills

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

shengdabai/Tony-Claude-Code-Skills

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

shengdabai/Tony-Claude-Code-Skills

Read-only queue dashboard for workspace-aware ship. (gstack)

shengdabai/Tony-Claude-Code-Skills

Anime.js adapter patterns for HyperFrames. Use when writing Anime.js animations or timelines inside HyperFrames compositions, registering animations on window.__hfAnime, making Anime.js seek-driven and deterministic, or translating Anime.js examples into render-safe HyperFrames HTML.

shengdabai/Tony-Claude-Code-Skills

Author a new HyperFrames registry block (caption style, VFX block, transition, lower third) or component (text effect, overlay, snippet) and ship it as an upstream PR to the hyperframes repo. Use ONLY when the user wants to CONTRIBUTE to the public catalog — for in-project caption/transition authoring use the `hyperframes` skill, for installing existing registry items use the `hyperframes-registry` skill.

shengdabai/Tony-Claude-Code-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.

shengdabai/Tony-Claude-Code-Skills

GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

shengdabai/Tony-Claude-Code-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.

相關技能