Communitygithub.com

Army161/OpenMontage

为 HyperFrames 合成提供音频和媒体资产,由统一的音频引擎(`scripts/audio.mjs`)驱动——支持多提供商 TTS(HeyGen / ElevenLabs / Kokoro 本地)、背景音乐 + 音效(默认使用 HeyGen 音频库检索,本地 Lyria / MusicGen BGM 生成和捆绑的 SFX 库作为无凭据时的回退)、Whisper 转录、背景移除和字幕创作。用于配音 / TTS、BGM、SFX / 音效、转录、字幕 / 歌词 / 卡拉 OK / 逐词样式、语音 + 提供商选择以及音乐情绪提示。

OpenMontage 是什么?

Army161/OpenMontage 是一个为 HyperFrames 合成框架提供全面音频和媒体资产支持的技能。它围绕一个核心音频引擎 `scripts/audio.mjs` 构建,该引擎接收标准化的 `audio_request.json` 输入,并生成包含 TTS 语音、BGM、SFX 等资产的 `audio_meta.json` 输出。技能的核心亮点在于其智能的提供商链式回退机制:当检测到 HeyGen 凭据时,优先使用其高性能的 REST API 进行 TTS(含原生词时间戳)、BGM 检索和 SFX 检索;若无凭据,则自动降级到 ElevenLabs/Kokoro(本地)进行 TTS,使用 Lyria/MusicGen 本地生成 BGM,并使用捆绑的 21 个文件库提供 SFX。这使得用户即使在离线或没有 API 密钥的情况下也能流畅工作。该技能还集成了 Whisper 转录、背景移除和高级字幕创作功能,支持卡拉 OK 和逐词样式。最重要的是,它在尝试生成任何音频之前,会通过 `npx hyperframes auth status` 强制进行凭据预检,确保用户明确知晓并选择是否登录或离线工作,从而避免静默降级带来的意外。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

HyperFrames Media

创建合成所需的音频和媒体资产——配音(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 凭据不是静默回退到本地引擎的理由:首先建议登录,让用户决定。运行共享的预检并原样传递其输出——不要自作主张编写自己的“缺少密钥”提示,也不要提供将密钥写入每个仓库的 .env 文件:

npx hyperframes auth status
  • 已登录 → 它会打印帐户信息;继续进行。
  • 未登录(此处预期 exit 1——“未登录”是正常状态,而非失败)→ 它会打印注册优先的指导。建议登录:npx hyperframes auth login 是浏览器 OAuth——它登录并创建一个帐户(始终可通过此仓库的 CLI 使用)。要使用现有的 HeyGen API 密钥(来自 app.heygen.com/settings/api),运行 npx hyperframes auth login --api-key——它会保存到共享的 ~/.heygen(没有每个仓库的 .env)。输出还会列出语音/BGM 将回退到的本地引擎以及缺少依赖时的 pip 提示。原样传递此输出——不要用你自己的话改写它。 然后停下来等待用户选择——登录,或者说“继续”/“本地”以离线继续——然后再生成任何内容。 这是一个真正的决策点,而不是一个轻描淡写的说明:不要将其折叠到另一个问题中,也不要自行继续。(例外情况:在自主/非交互模式下,记录状态并离线继续。)
  • 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,以避免当用户环境更改时提供商发生静默漂移。
  • 始终向 transcribe 传递 --model。 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);无匹配跳过,从不阻塞渲染。SFX 在语音和 BGM 下的音量约为 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.

相关技能