Communitygithub.com

Army161/OpenMontage

音訊與媒體素材,用於 HyperFrames 合成作品。由單一音訊引擎 (`scripts/audio.mjs`) 驅動,支援多供應商 TTS、背景音樂、音效、語音轉錄、去背及字幕製作。

OpenMontage 是什麼?

這個技能提供了一個統一的音訊與媒體資產管線,專為 HyperFrames 合成系統設計。其核心是 `scripts/audio.mjs`,一個單一引擎,能處理語音合成、背景音樂、音效、語音轉錄與字幕製作,並輸出結構化的 `audio_meta.json`。它支援多種供應商,包括 HeyGen、ElevenLabs 與本地的 Kokoro TTS;背景音樂與音效預設從 HeyGen 資料庫檢索,若無憑證則優雅降級至本地的 Lyria/MusicGen 生成或內建音效庫。特別的是,它會在使用 HeyGen 時自動利用原生時間戳記,若無則串接 Whisper 轉錄以提供逐字時間資訊,確保字幕與卡拉 OK 效果的準確性。該技能包含一個強制性的預檢流程,要求使用者在生成任何內容前確認登入狀態或授予離線使用權限,並提供了詳細的供應商降級邏輯與參考文件。此技能專為需要產生語音旁白、背景音樂、音效與字幕的開發人員設計,且在資料夾存取、環境變數與 CLI 工具方面,可良好地與 Claude Code、Coder 或 Cursor 等開發環境整合。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Army161/OpenMontage/tree/HEAD/.agents/skills/hyperframes-media

在你喜歡的 AI 中提問

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

說明文件

HyperFrames 媒體

建立合成所需的音訊與媒體素材——語音旁白 (TTS)、背景音樂 + 音效、轉錄稿、字幕、去背——然後在 HTML 中使用並播放這些資料。關於將素材放置到合成中,請參閱 hyperframes-core。

音訊引擎——TTS、BGM、SFX 的單一來源

工作流程不會自行處理音訊或建立供應商的副本。只有一個引擎——scripts/audio.mjs——它接收一個中立格式的 audio_request.json,並寫入 audio_meta.json(以及 assets/voice|bgm|sfx 下的素材):

# <MEDIA_DIR> = 此技能所在的目錄
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json

所有三項能力都依賴於同一個開關——是否存在 HeyGen 憑證(從 $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen 解析,不是從 CLI 解析):

能力存在 HeyGen 憑證不存在
TTSHeyGen Starfish REST (原生逐字時間戳)→ ElevenLabs → Kokoro (串接 transcribe 取得逐字)
BGMHeyGen 音樂檢索Lyria → MusicGen 本地生成 (分離程序)
SFXHeyGen 音效檢索 (min_score 0.4)內建 21 個檔案庫 (assets/sfx/)
  • 請求 (audio_request.json):{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }。id 將每一行與呼叫者的模型(例如影格編號、場景 ID……)連結。bgm.mode = retrieve | generate | none;省略則為自動(有憑證時檢索,否則生成)。明確設定 retrieve 時是嚴格的——它會跳過而非啟動一個分離的生成程序(適用於沒有 wait-bgm 步驟的呼叫者)。
  • 輸出 (audio_meta.json,以 id 為鍵值):{ tts_provider, voice_id, bgm, bgm_pending, …, voices: [{ id, path, duration_s, words }], sfx: [{ id, name, file, source, offset_s, duration_s, volume }], total_duration_s }。
  • --only tts,bgm,sfx 執行子集並合併到已存在的 --out 檔案中(例如先 TTS+BGM,等提示有了再執行 SFX)。
  • BGM 生成是以分離方式啟動的 (bgm_pending: true)——在組裝前執行 scripts/wait-bgm.mjs。
  • scripts/heygen-tts.mjs 是一個基於相同程式碼的單次 CLI(一個文字 → wav + 逐字),適用於只需 HeyGen TTS 而無需請求檔案的情況。

完整旗標列表與 audio_meta.json 的結構定義在 scripts/audio.mjs 的開頭註解中。以下參考資料涵蓋了每個能力背後的供應商詳細資訊與邊際情況。

預檢——在生成任何音訊前顯示登入狀態

在生成語音或 BGM 之前,務必執行此步驟——無論是在完整工作流程中,還是在一次性「幫我生成 BGM/語音旁白」的請求中。 沒有 HeyGen 憑證並非要默默地回退到本地引擎:首先建議登入,讓使用者決定。執行共用的預檢指令,並直接轉述其輸出——不要自行編造「缺少 key」的提示,也不要提議將 key 寫入每個儲存庫的 .env:

npx hyperframes auth status
  • 已登入 → 它會列印帳戶資訊;繼續進行。
  • 未登入 (exit 1 在此是預期行為——「未登入」是正常狀態,並非失敗) → 它會列印引導註冊的資訊。建議登入:npx hyperframes auth login 是瀏覽器 OAuth——它會登入並建立帳戶(透過此儲存庫的 CLI 始終可用)。若要使用現有的 HeyGen API key(來自 app.heygen.com/settings/api),請執行 npx hyperframes auth login --api-key——它會儲存到共用的 ~/.heygen(無需每個儲存庫的 .env)。輸出中也會列出當缺少依賴時,語音/BGM 將回退到的本地引擎以及一個 pip 提示。直接轉述此輸出,不要用自己的話重新解釋。 然後停止並等待使用者選擇——登入,或說「go」/「local」以繼續離線操作——然後再生成任何內容。 這是一個真正的決策點,不是一個次要備註:不要把它摺疊到另一個問題中,也不要自行跳過它。(例外情況:在自主 / 非互動模式下,記錄狀態後繼續離線操作。)
  • npx hyperframes auth status --json 回傳 { configured, recommended_action, offline_engines },適用於確定性分支。
  • 如果無法執行 CLI(不在 PATH 上且 npx 無法取得它)→ 仍然建議登入 (npx hyperframes auth login) 並停止等待使用者選擇——不要將「沒有憑證」視為本地生成的安全綠燈。

憑證解析、完整金鑰優先順序以及本地依賴清單請參閱 references/requirements.md。

供應商鏈結(引擎背後的細節)

TTS —— 第一個可用的供應商勝出(引擎,或 npx hyperframes tts "..."):

順序供應商偵測條件逐字時間戳
1HeyGen (Starfish)$HEYGEN_API_KEY / hyperframes auth login是,原生——傳遞 --words narration.words.json 以擷取
2ElevenLabs$ELEVENLABS_API_KEY 已設定否——之後需串接 transcribe
3Kokoro-82M (本地, 54 種語音)始終可用(無需金鑰)否——之後需串接 transcribe

已發布的 hyperframes tts CLI 通常是僅本地的版本(其 --help 顯示「Kokoro-82M」,沒有 --provider/--words),即使已設定 $HEYGEN_API_KEY 也會默默地回退到 Kokoro。這就是為什麼引擎的 HeyGen 路徑使用自包含的 scripts/heygen-tts.mjs (REST),而不是 CLI;CLI 僅用於 Kokoro 路徑。請參閱 references/tts.md。

BGM 與 SFX —— 預設從 HeyGen 音訊庫檢索 (/v3/audio/sounds),使用的憑證與 HeyGen TTS 相同,若無憑證則依上述開關回退:

素材HeyGen type存放位置回退(無憑證)
BGMmusicassets/bgm/track.mp3 (檢索) · track.wav (生成)Lyria / MusicGen 生成
SFXsound_effects (min_score 0.4)assets/sfx/<slug>.mp3內建 21 個檔案庫 (assets/sfx/* + manifest.json)

請參閱 references/bgm.md 和 references/sfx.md。

路由

任務閱讀
音訊引擎——請求/中繼資料結構、--only、開關scripts/audio.mjs (開頭註解)
npx hyperframes tts / heygen-tts.mjs —— 供應商、語音、逐字references/tts.md
BGM —— HeyGen 檢索 + 本地 Lyria / MusicGen 生成references/bgm.md
SFX —— HeyGen 檢索 (min_score 0.4) + 內建本地庫references/sfx.md
npx hyperframes transcribe —— Whisper、模型規則、輸出結構references/transcribe.md
npx hyperframes remove-background —— 透明去背references/remove-background.md
TTS → 轉錄 → 字幕(無錄製的語音旁白)references/tts-to-captions.md
字幕創作——樣式偵測、佈局、分組、退出references/captions/authoring.md
轉錄稿處理——輸入格式、品質檢查、清理、APIreferences/captions/transcript-handling.md
字幕動畫——卡拉 OK、標記效果、音訊反應靈敏references/captions/motion.md
模型快取、系統依賴、故障排除references/requirements.md

不容妥協的規則

  • 單一引擎,無自製副本。 透過 scripts/audio.mjs(或一次性 HeyGen TTS 的 heygen-tts.mjs)產生音訊。不要在工作流程內部重新實作 TTS/BGM/SFX——撰寫一個 audio_request.json 轉接器並呼叫該引擎。
  • 「HeyGen 可用」= 可解析的憑證,不是 CLI。 整個開關取決於 heygenCredential();已發布的 hyperframes tts 可能僅是 Kokoro,且完全沒有 hyperframes bgm / hyperframes sfx 指令。
  • 語音 ID 是供應商特定的。 am_michael 僅屬於 Kokoro;HeyGen UUID 無法在 Kokoro 上使用。如果你傳遞 --voice,也請固定 --provider,以避免當使用者環境變更時供應商默默地漂移。
  • 始終傳遞 --model 給 transcribe。 CLI 預設值 small.en 會默默地翻譯非英文音訊。請參閱 references/transcribe.md → 「語言規則」。
  • HeyGen 回傳逐字時間戳;ElevenLabs / Kokoro 則否。 引擎會自動為後兩者串接 transcribe;若獨立使用,請傳遞 --words 給 HeyGen,或對音訊檔案執行 transcribe。
  • 字幕使用扁平化的逐字陣列格式,包含 { id, text, start, end }。請參閱 references/transcribe.md → 「輸出結構」。
  • remove-background --background-output 是挖洞,不是修復。 對於「不含人物的場景」,需要不同的工具。請參閱 references/remove-background.md → 「何時不是正確的工具」。
  • BGM/SFX 預設為 HeyGen 檢索;無憑證時回退為生成 (BGM) 或內建庫 (SFX)。 /audio/sounds 根據文字查詢排序——具體命名效果 (glass shatter,而不是 dramatic sound);無匹配則跳過,絕不阻擋渲染。在語音 + BGM 下,SFX 的音量約為 ~0.35。請參閱 references/sfx.md / references/bgm.md。
  • 將工作流程的字幕 HTML 視為生成的輸出。 對於預設支援的影片,可重複使用的皮膚原始碼位於 .hyperframes/caption-skin.html,工作流程腳本則寫入 compositions/captions.html;請勿編輯生成的 compositions/captions.html 來修復皮膚。請透過工作流程的 captions.mjs 重新建置,或在存在時使用該工作流程的明確覆寫機制。

Individual skills in this repo

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

Army161/OpenMontage

Generate AI videos from text prompts using multiple provider gateways. Use when: (1) Generating videos from text descriptions, (2) Creating AI-generated video clips for content production, (3) Image-to-video generation with a reference image, (4) Choosing between video generation providers (VEO, Kling, Sora, Runway, Seedance, MiniMax). Supports two gateways: HeyGen API and fal.ai API.

Army161/OpenMontage

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Army161/OpenMontage

Use p5.js/canvas for local procedural character effects: particles, weather, squash/stretch, walk cycles, and environmental motion.

Army161/OpenMontage

Review local character animation with schema checks, Playwright browser previews, frame sampling, and FFmpeg/ffprobe final output checks.

Army161/OpenMontage

Create videos from a text prompt using HeyGen's Video Agent. Use when: (1) Creating a video from a description or idea, (2) Generating explainer, demo, or marketing videos from a prompt, (3) Making a video without specifying exact avatars, voices, or scenes, (4) Quick video prototyping or drafts, (5) One-shot prompt-to-video generation, (6) User says "make me a video" or "create a video about X".

Army161/OpenMontage

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Army161/OpenMontage

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Army161/OpenMontage

Use when implementing Disney's 12 animation principles with Framer Motion in React applications

Army161/OpenMontage

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.

Army161/OpenMontage

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

Army161/OpenMontage

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.

Army161/OpenMontage

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`.

Army161/OpenMontage

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).

Army161/OpenMontage

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.

Army161/OpenMontage

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.

Army161/OpenMontage

Best practices for Remotion - Video creation in React

Army161/OpenMontage

Toolkit-specific Remotion patterns — custom transitions, shared components, and project conventions. For core Remotion framework knowledge (hooks, animations, rendering, etc.), see the `remotion-official` skill.

Army161/OpenMontage

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.

Army161/OpenMontage

Animate SVG character rigs with GSAP, CSS transforms, Remotion frame control, and HyperFrames-compatible browser previews.

Army161/OpenMontage

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

相關技能