Communitygithub.com

starter-nextjs

HyperFrames CLI 開發循環。用於執行 npx hyperframes 初始化、新增、目錄、擷取、語法檢查、驗證、檢查、佈局、快照、預覽、播放、渲染、發布、Lambda、診斷、瀏覽器、資訊、升級、技能、組合、文件、基準測試、遙測、轉錄、TTS 或移除背景,或對 HyperFrames 建構/渲染環境進行故障排除。AWS Lambda 雲端渲染的進入點。

starter-nextjs 是什麼?

此技能作為 HyperFrames CLI 的全面參考與操作介面,HyperFrames 是一個用於建立和渲染影片組合的工具。它需要 Node.js >= 22 和 FFmpeg,主要透過 `npx hyperframes` 命令執行。其工作流程引導使用者從初始化專案、編寫 HTML 組合、使用 `lint`、`validate` 和 `inspect` 等命令進行靜態和視覺檢查,到最終使用 `render` 命令進行呈現。此技能支援多種渲染方式,包括使用 `--quality draft` 進行快速迭代、使用 `--quality high` 進行高畫質交付、使用 `--docker` 實現跨主機可重現性,以及透過 `hyperframes lambda` 子命令進行雲端渲染。此技能也定義了代理商慣例,包括在 CI/代理商情境中使用 `--json` 輸出、`doctor` 命令的非零退出碼處理、非 TTY 模式的自動偵測,以及渲染前的使用者批准閘道。它與其他技能(如 `hyperframes-core`、`hyperframes-registry` 和 `hyperframes-media`)無縫整合,以處理 Tailwind 專案、註冊表區塊和資產預處理,使其成為 HyperFrames 生態系統中開發者和 AI 代理商的核心工具。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1345AbhishekKumar/starter-nextjs/tree/HEAD/.agents/skills/hyperframes-cli

在你喜歡的 AI 中提問

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

說明文件

HyperFrames CLI

所有操作都透過 npx hyperframes 執行,除非專案說明指定了本地包裝器。必須完全遵循本地包裝器的指示。需要 Node.js >= 22 和 FFmpeg。

工作流程

  1. 搭建 — npx hyperframes init my-video(或從 URL capture)
  2. 編寫 — 撰寫 HTML 組合(參見 hyperframes-core 技能)
  3. 語法檢查 — npx hyperframes lint
  4. 驗證 — npx hyperframes validate(執行時期錯誤 + 對比度)
  5. 視覺檢查 — npx hyperframes inspect
  6. 預覽 — npx hyperframes preview 會開啟Studio,這是一個時間軸編輯器,使用者可以在其中手動編輯任何內容(不僅是觀看)。在那裡審查,然後在渲染前詢問。
  7. 渲染 — 選擇變體:
    • 迭代:npx hyperframes render --quality draft
    • 交付:npx hyperframes render --quality high --output out.mp4
    • CI / 跨主機重現:npx hyperframes render --docker --strict --output out.mp4
    • 雲端(長時間/大型):npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(參見下方的 Lambda)

在預覽前執行語法檢查、驗證和檢查。lint 會捕捉遺失的 data-composition-id、重疊的軌道和未註冊的時間軸。validate 會在無頭 Chrome 中載入組合,並報告執行時期控制台錯誤以及 WCAG 對比度問題。inspect 會在時間軸中搜尋,並報告文字溢出氣泡/容器或畫布的情況 — 此外,當存在 *.motion.json 側車檔案時,它會根據相同的搜尋時間軸驗證動畫意圖(在搜尋下觸發動畫、交錯順序、在畫面內、活躍度)。

對於動畫繁重的工作,建議使用快照驅動的迭代和 *.motion.json 側車檔案 — 請參閱 references/lint-validate-inspect.md 了解紀律和動畫驗證規範。

代理商慣例

適用於每個命令的跨領域規則:

  • 除了 render、preview 和 play 之外,每個命令都提供 --json。 將其用於支援的命令的任何代理商/CI 呼叫;輸出包含一個 _meta 封套(cli 版本、最新可用版本、更新建議)。render 僅透過 stdout + 退出碼報告狀態 — 使用下面的渲染後檢查驗證成功;preview / play 是伺服器,無 JSON。
  • doctor --json 總是退出 0,即使環境有問題。檢查 payload 的 ok 欄位:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。這使管道免受 CLI 版本更新的影響。
  • 非 TTY 模式會自動偵測。 當 stdout 不是 TTY 時(CI、代理商、管道輸出),CLI 會自動切換到非互動模式;此時 init 需要 --example。傳遞 --non-interactive 以強制在 TTY 上啟用此模式。
  • CI 渲染閘道:--strict 在出現 lint 錯誤時失敗,--strict-all 在出現警告時也失敗,--strict-variables 在出現未宣告的 --variables 鍵時失敗。
  • --json 中的路徑會被修飾 — $HOME 會變成字面上的 $HOME,這樣輸出就可以安全地貼到錯誤報告和代理商上下文中。
  • 渲染需要使用者批准。 檢查通過後,永遠不要自動渲染。在 preview 時暫停,告訴使用者影片可在 Studio 中編輯,並在他們批准後才進行渲染。
  • 渲染後驗證。 在 render 返回退出碼 0 後,確認輸出檔案存在且大小合理,然後再報告成功:[ -s "$OUTPUT" ] || echo "渲染未產生輸出"。CLI 在成功時會列印 ◇ <path>;對於長時間渲染,也使用 ffprobe -i "$OUTPUT" -show_format -v error 檢查持續時間是否合理。

路由

想要…閱讀
搭建專案(init、capture、skills)references/init-and-scaffold.md
檢查正確性(lint、validate、inspect、snapshot)references/lint-validate-inspect.md
預覽或渲染(preview、play、render、publish)references/preview-render.md
診斷環境(doctor、browser)references/doctor-browser.md
在 AWS Lambda 上雲端渲染(lambda deploy / sites / render / progress / destroy / policies)references/lambda.md
其他所有功能(info、upgrade、compositions、docs、benchmark、telemetry、資產預處理)references/upgrade-info-misc.md

跨技能交接

  • Tailwind 專案(init --tailwind)→ 在編輯類別或主題令牌之前,使用 hyperframes-core(Tailwind 參考)。
  • 註冊表區塊/元件(hyperframes add、hyperframes catalog)→ 使用 hyperframes-registry 處理安裝路徑、子組合接線和程式碼片段合併。
  • 資產預處理(tts、transcribe、remove-background)→ 使用 hyperframes-media 處理語音選擇、Whisper 模型規則、字幕和 TTS 轉字幕鏈。
  • 參數化渲染(--variables)→ 在 <html> 上透過 data-composition-variables 宣告;完整的架構請參見 hyperframes-core。

Lambda(雲端渲染)

hyperframes lambda 將分散式渲染部署到 AWS Lambda,並從您的筆記型電腦或 CI 驅動渲染。端到端是三個命令:

npx hyperframes lambda deploy                                             # 佈建 SAM 堆疊(Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # 拆除(S3 儲存桶會被保留)

當渲染對單一主機來說時間太長或規模太大(多分鐘影片、4K、大型平行批次)且您已配置 AWS 憑證時,請使用 Lambda。對於開發循環迭代,請保持使用本地 render。

請參閱 references/lambda.md 了解先決條件、全部 6 個子命令(deploy、sites create、render、progress、destroy、policies)、IAM 政策驗證、狀態檔案以及成本/清理規則。

最低完成閘道

靜態閘道

npx hyperframes lint
npx hyperframes validate

對於佈局敏感的工作,請加入 inspect;在 CI 中,加入 render --strict 以便在 lint 錯誤時失敗。

視覺冒煙測試 — 當專案使用子組合時必須

lint / validate / inspect 單獨評估每個組合。它們永遠不會載入 index.html 並透過 data-composition-src 掛載子組合,因此它們無法捕捉跨檔案掛載失敗(請參閱 hyperframes-core → references/sub-compositions.md 中的「常見陷阱」)。唯一能捕捉到它們的閘道是實際載入 index.html 並在時間軸中搜尋的閘道。

使用 hyperframes snapshot — 它載入專案的方式與 render 相同(因此它執行相同的掛載路徑),但只捕捉您請求的時間戳的幀,因此只需要幾秒鐘,而不是完整的渲染:

# 在每個子組合的中點捕捉一幀。
# 中點 = index.html 中每個主機插槽的 data-start + data-duration/2。
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# 或者,如果您不需要逐場景定位,可以取均勻間隔的樣本:
npx hyperframes snapshot --frames 9

輸出會放在 snapshots/frame-NN-at-Xs.png。對照場景計畫目視檢查每個幀。

每個幀的警示訊號(每個都對應到靜態閘道遺漏的特定失敗模式):

您看到的內容根本原因
文字在左上角以微小且未套用樣式的形式顯示<style> 區塊留在 <head> 中的 <template> 外部(陷阱 1)— 沒有 CSS 到達實際 DOM
SVG/圖示元素放大到畫布大小同上 — 未應用任何寬度/高度約束
場景的主要元素完全遺失;只有背景和浮水印可見Host-id ≠ template id(陷阱 2)— 時間軸從未執行,幀在初始狀態下捕捉
快照命令記錄 Sub-composition timelines not registered after 45000ms陷阱 2 — 直接確認

snapshots/ 可以在目視檢查後刪除;最終使用者面向的渲染是使用 npx hyperframes render 進行的單獨傳遞。

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

1345AbhishekKumar/starter-nextjs

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

1345AbhishekKumar/starter-nextjs

The fallback workflow for authoring custom HyperFrames video compositions at any length or format — longer or multi-scene pieces, brand / sizzle reels, montages, title cards, static loops, and freeform compositions. Input- and length-agnostic. If a specialized workflow clearly fits the input — a marketed product, a website, a topic explainer, a GitHub PR, existing footage, a short motion graphic, or a Remotion port — prefer it (see /hyperframes); use this only as the general fallback when none fit.

1345AbhishekKumar/starter-nextjs

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

1345AbhishekKumar/starter-nextjs

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

1345AbhishekKumar/starter-nextjs

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

1345AbhishekKumar/starter-nextjs

Audio and media assets for HyperFrames compositions, produced by one shared audio engine (`scripts/audio.mjs`) — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), background music + sound effects (HeyGen audio-library retrieval by default, with local Lyria / MusicGen BGM generation and a bundled SFX library as the no-credential fallback), Whisper transcription, background removal, and caption authoring. Use for voiceover / TTS, BGM, SFX / sound effects, transcription, captions / subtitles / lyrics / karaoke / per-word styling, voice + provider selection, and music-mood prompting.

1345AbhishekKumar/starter-nextjs

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, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

1345AbhishekKumar/starter-nextjs

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (website-to-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

1345AbhishekKumar/starter-nextjs

Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it.

1345AbhishekKumar/starter-nextjs

turn a product or marketing URL, pasted script, or brief into a product launch video, including SaaS promos, feature reveals, app launches, company promos, and product marketing videos. Use this skill when the user wants to market, launch, promote, or reveal a product. Do not use it for general non-launch website tours, non-product topic explainers, GitHub pull requests, captioning existing footage, or short unnarrated motion graphics. If the intent is unclear, route through /hyperframes first. This is the new shot-sequence architecture: every visual frame is authored as a time-coded shot sequence picked from a menu of golden blueprints, so frames develop over their full duration instead of freezing after entrance.

1345AbhishekKumar/starter-nextjs

turn a GitHub pull request (a PR URL like github.com/<owner>/<repo>/pull/<N>, an <owner>/<repo>#<N> ref, or 'this PR' in a checked-out repo) into a code-change explainer video, up to ~3 min (sweet spot 30-90s) — changelog, feature reveal, fix, or refactor walkthrough, rendered from the diff / commits / files. The input is a CODE CHANGE read via the gh CLI; there is no website capture. Use this skill for a GitHub PR. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /website-to-video), a topic explainer with no PR (use /faceless-explainer), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first.

1345AbhishekKumar/starter-nextjs

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

1345AbhishekKumar/starter-nextjs

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

相關技能