Communitygithub.com

9018/mychat

将音频文件或视频中的音频转为节拍同步的 HyperFrames 视频,支持从平静到强烈多种风格。音乐驱动一切:一次分析,编排帧布局,每个帧由一个子智能体构建。

mychat 是什么?

这是一个将音乐轨道转换为节拍同步的 HyperFrames 视频的 AI 智能体技能。它由一首音乐驱动:一个分析器读取一次音乐,编排器布局帧并填充每个帧的计划,然后一个子智能体构建每个帧。排版和模板是基础——完整视频无需任何资产——但用户提供的任何图像或视频都会被切割到同一节拍网格上(节拍切割/肯·伯恩斯)。流派(抒情视频、幻灯片、动态宣传)由每个帧的选择决定;管道从不分支。它支持 Claude Code、Codex 等平台。工作流程包括设置 BGM、分析音乐、创建骨架故事板、填充计划、构建帧、组装和渲染。其关键理念包括信任单一分析器,以及一个帧对应一个文件。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/9018/mychat/tree/HEAD/OpenMontage/.agents/skills/music-to-video

在你喜欢的 AI 中提问

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

文档

music-to-video — 一个基于音乐、节拍同步的视频工作流

使用此技能将音乐轨道转换为节拍同步的 HyperFrames 视频。您将分析一次音乐,布局帧,填充每个帧的计划,并将每个帧构建为一个合成。输入是一个音乐轨道,加上可选的用户图像或视频——没有旁白,也没有网页捕获。排版和模板是基础(完整视频无需任何资产);用户提供的任何媒体都会被切割到同一节拍网格上。

您是编排器。在 videos/<project>/ 中工作。按顺序执行步骤,并在继续之前通过每个关口。两个步骤需要用户:步骤 3(计划审批)和步骤 6(渲染审批)。除步骤 4 外,您自己执行所有步骤,在步骤 4 中,您为每个帧派遣一个子智能体。将设计和动画规则保留在此文件之外——它们位于 references/ 和 frame-worker 子智能体中。

SKILL_DIR = 此技能目录。PROJECT_DIR = videos/<project-name>/。

工作流:步骤 0 设置 → hyperframes.json + assets/bgm.mp3;步骤 1 分析 → audiomap.json;步骤 2 骨架 → STORYBOARD.md(帧,组 TBD);步骤 3 计划 → 完整的 STORYBOARD.md + frame.md;步骤 4 构建 → compositions/frames/NN-*.html;步骤 5 组装 → index.html;步骤 6 渲染 → renders/video.mp4。

塑造一切的两种理念

  • 一个分析器,并且您信任它。 analyze-beatgrid.py 是唯一的节拍分析器——切勿使用其他工具或凭耳朵重新测量节拍。它的能量/密度/卷/起始/静音始终可靠。其 bpm 和 beats_sec 仅在音乐真正有节奏时才可靠;在平静音乐上,网格是追踪器施加的节拍器,因此请改用乐句和能量来确定节奏,切勿硬性切割到它。判断您处于哪种情况是每个帧的 pacing(步骤 2)。
  • 一个帧 = 一个文件;组存在于内部。 步骤 2 将轨道切割为帧,每个帧成为一个合成文件 compositions/frames/NN-<frame_id>.html,由一个帧工作器构建。一个帧可以细分为组(每个组是一个模板或动画原语组合)。额外的密度应放在组内部,因此帧数量跟踪不同的处理方式,而不是节拍——快速轨道不会增加子智能体的数量。

步骤 0:设置、BGM 和输入

目标:确定音乐源,创建 HyperFrames 项目,并记录用户提供的任何媒体。

音乐是核心——在做其他任何事情之前先确定一个轨道。此技能针对快速、高能 BGM 进行了优化:强大的节拍网格驱动切割(平静轨道也可以,但根据乐句而不是节拍来确定节奏)。如果用户提供了音频(音乐文件或需要从中提取音频的视频),请使用它。如果没有,就生成一个:根据用户的描述(例如“动感合成波”、“陷阱节拍”、“欢快企业”)选择情绪,并通过 /hyperframes-media(references/bgm.md — 如果已认证则使用 HeyGen 检索,否则使用本地 Lyria / MusicGen;ElevenLabs 或其他生成器也可以)生成轨道。在生成之前,运行 npx hyperframes auth status 并逐字输出结果(不要解释或重写)——它显示 BGM 是来自 HeyGen 还是本地 MusicGen,以及如果未登录,如何登录。如果未登录,则停止并等待用户选择——登录,或继续使用本地 MusicGen 离线工作——然后再生成轨道;不要将密钥写入每个仓库的 .env。(在自主模式下,记录状态并继续离线。)请参阅 /hyperframes-media → 预检以获取规范指南。无论哪种方式,轨道最终都会位于 assets/bgm.mp3。暂存用户提供的任何图像或视频,以便帧可以在节拍网格上将它们编织进去;否则排版承载整个视频。

仅当 hyperframes.json 缺失时才初始化。根据简要说明以 kebab 大小写命名 <project>,例如 midnight-drive-loop——切勿使用时间戳。init 检查已安装的技能是否与 GitHub 上的最新版本一致,如果任何版本过时,则更新全局集。

npx hyperframes init "videos/<project>" --non-interactive --example=blank
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3"   # 如果需要,先从视频中提取
# 仅当用户提供了图像/视频时:
node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public

品牌(字体 + 调色板)在步骤 3 中选择,而不是在这里。不要提前选择流派或轨道类型——资产只是一个可选成分,流派从每个帧的选择中产生。

关口: hyperframes.json + assets/bgm.mp3 存在;宽高比/长度/fps 以及(如有)资产清单已记录。


步骤 1:分析音乐

目标:生成整个视频所基于的唯一规范定时分析。

analyze-beatgrid.py 是唯一的节拍分析器——切勿使用其他工具或凭耳朵重新测量节拍。它读取一次轨道并写入 audiomap.json:能量阶段(电平/密度/感觉)、起始 + onset_rate、卷、静音、hard_stops、key_moments、乐句、节奏/网格以及 audio.duration_sec。它是确定性的——同一文件始终生成相同的地图。对于任何音乐,大多数字段都是可靠的;bpm 和 beats_sec 仅在音乐真正有节奏时才可靠,判断这一点是您在步骤 2 中要做出的决定。

先决条件:Python 3 提供 librosa、numpy 和 soundfile。如果导入失败,请在运行分析器之前将它们安装到活动的 Python 环境中:

python3 -m pip install librosa numpy soundfile
python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" \
  -o "$PROJECT_DIR/audiomap.json" --print

关口: audiomap.json 存在;audio.duration_sec 已知。


步骤 2:帧骨架(仅结构)

目标:读取音乐并布局帧——STORYBOARD.md 的骨架。

阅读 references/frame-skeleton.md。自行将 audiomap.json 转换为 STORYBOARD.md 的骨架——没有中间 JSON。在真实的音乐变化处(hard_stops、SURGE / DROP key_moments、卷的边缘、没有起始的片段、大的能量跳跃)将轨道切割为帧,将每个边界对齐到音频地图锚点。为每个帧设置 span_sec、pacing(来自步骤 1 信任判断的结论——当网格为实时为 beat_cut,当网格是施加于平静音乐的节拍器时为 phrase_flow)、mood 和一行 feel(步骤 3 根据其匹配模板的纯音乐情况)。只在这里分类和布局:将每个帧的 ### Groups 保留为 TBD (Step 3),并将前导元数据的 style 留空——没有模板、文案、颜色或字体。预期大约 1-6 个帧。

关口: 帧覆盖整个轨道(第一个从 0 开始,最后一个到 duration_s);每个帧都带有 span_sec + pacing + mood + feel;每个 ### Groups 都是 TBD;没有任何内容。


步骤 3:填充计划(用户关口)

目标:将骨架转变为已批准的完整 STORYBOARD.md。

阅读 references/planning.md、storyboard-format.md、template-catalog.md、motion-primitive-catalog.md 和 montage.md(仅当用户提供了资产时)。在原地编辑同一文件,执行两项操作:

  1. 选择品牌。 使用 ../hyperframes-creative/references/design-spec.md 中的表格,从 ../hyperframes-creative/frame-presets/ 中选择一个预设(匹配轨道的情绪;只有其字体和颜色重要——模板拥有构图)。将其未修改地复制到 frame.md 中,并从中填充前导元数据的 style(字体 + 最多 4-6 个色块的调色板)。
  2. 填充每个帧。 决定其组,并为每个组赋予一个处理方式:来自目录的匹配模板(带有绑定参数和真实的音频地图锚点)、来自原语目录的自由构图,或遵守 pacing 的资产处理方式。编写文案。您拥有“什么”(模板/原语 + 内容 + 锚点);帧工作器拥有“如何”——切勿将毫秒级补间写入故事板。
node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
  --audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates

修复每个 ✗(硬错误:持续时间不匹配、帧未覆盖轨道、缺少 src);警告为尽力而为。然后向用户显示逐帧摘要并迭代,直到他们批准。

关口: frame.md 是未经修改的预设副本;validate-plan.mjs 以代码 0 退出;用户批准了计划。


步骤 4:根据计划构建帧

目标:将每个帧构建为独立的合成文件。

创建 compositions/frames/。阅读 sub-agents/frame-worker.md 和 ../hyperframes-core/references/subagent-dispatch.md。为每个帧派遣一个帧工作器,尽可能并行(否则分批进行)。每个工作器获得恰好一个帧和以下上下文:

PROJECT_DIR: <绝对路径>
frame_id: <NN-frame_id>              # = 帧文件名主干,例如 02-f2;合成 id
您的块:PROJECT_DIR/STORYBOARD.md 中的 `## Frame N — <frame_id>` 块
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
材料:对于每个组,<SKILL_DIR>/references/templates/<id>/index.html(模板)和
           <SKILL_DIR>/references/motion-primitives/<id>/(自由构图);暂存的 assets/(资产组)
合同:../hyperframes-core/references/sub-compositions.md + determinism-rules.md
画布:<宽>×<高>   节奏:<beat_cut|phrase_flow>
写入位置:PROJECT_DIR/compositions/frames/<frame_id>.html

工作器分叉引用的材料,将每个锚点转换为帧本地秒数(local_t = track_t − span_sec[0]),以 0ms 切割对其组进行门控,并写入一个安全的帧文件。工作器从不运行 hyperframes CLI——这些命令操作的是已组装的项目,该项目尚不存在,因此它们会报告错误的文件。工作器只写入合同并停止;您在组装后验证(步骤 6)。当每个工作器返回时,您可以确认其文件已写入磁盘。

关口: 每个帧的 compositions/frames/NN-*.html 都已写入磁盘。


步骤 5:组装

目标:将构建的帧 + BGM 连接到可播放的 index.html 中。

assemble-index.mjs 是确定性的——没有子智能体,没有判断。它在其累积的 data-start 处引用每个帧文件,将 assets/bgm.mp3 挂载到轨道 11 上,并进行帧到帧的硬切割(帧覆盖跟踪没有间隙,因此没有过渡注入器)。

node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
  --hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"

修复它报告的任何 ✗——缺失或空白的帧文件意味着该工作器写入了部分文件;重新派遣它(步骤 4)并重新组装。

关口: index.html 存在;总持续时间 == audiomap.audio.duration_sec。


步骤 6:验证并渲染

目标:验证组装的视频,获得用户批准,并渲染最终的 MP4。

在已组装的项目上运行 CLI——这是正确的单元(逐帧工作器无法运行它)。lint 检查结构,validate 运行无头 Chrome(捕获 JS 错误和缺失资产),inspect 捕获帧快照。

( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )

在 t=0、每个帧起始点、最强的 DROP / SURGE、每个 hard_stops[].t 以及最后一帧进行检查。如果失败,请自行执行最便宜的安全修复:编辑有问题的 compositions/frames/NN-*.html。切勿更改持续时间或音频计时来隐藏同步问题。一旦关口通过,暂停等待用户审核,然后仅在批准后渲染:

( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )

关口: lint / validate / inspect 通过;用户批准了;renders/video.mp4 存在,包含音频,持续时间 == audiomap.audio.duration_sec。最终回复说明 MP4 路径和持续时间。


恢复表

您拥有从何处继续
仅有 assets/bgm.mp3步骤 1
audiomap.json步骤 2
STORYBOARD.md(骨架)步骤 3
STORYBOARD.md(完整)步骤 4
所有帧文件步骤 5
index.html步骤 6

快速参考

格式: 默认横向 1920x1080;纵向 1080x1920;方形 1080x1080。在故事板前导元数据中设置一次画布(canvas: { w, h, fps })。

脚本位于 scripts/ 下:analyze-beatgrid.py(唯一的分析器)、validate-plan.mjs(计划检查)、assemble-index.mjs(索引组装)、stage-assets.mjs(暂存用户媒体)、lib/storyboard.mjs(附带的解析器)。其他所有内容都是 hyperframes CLI。

阅读时间
references/frame-skeleton.md步骤 2:读取音乐,布局帧,设置节奏
references/planning.md · storyboard-format.md步骤 3:选择品牌,填充每个帧,编写计划
references/template-catalog.md步骤 3:为每个组选择模板
references/motion-primitive-catalog.md步骤 3:为每个组选择动画原语
references/montage.md步骤 3:将用户资产切割到节拍网格上

Individual skills in this repo

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

9018/mychat

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, Gemini Omni). Supports gateways: HeyGen API, fal.ai API, Kling official direct API, and the Gemini API (Gemini Omni Flash).

9018/mychat

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.

9018/mychat

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

9018/mychat

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

9018/mychat

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

9018/mychat

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.

9018/mychat

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.

9018/mychat

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

9018/mychat

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.

9018/mychat

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

9018/mychat

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.

9018/mychat

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

9018/mychat

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.

9018/mychat

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

9018/mychat

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.

9018/mychat

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.

9018/mychat

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.

9018/mychat

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

9018/mychat

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

9018/mychat

Download video and audio from YouTube and 1000+ sites using yt-dlp. No API keys needed. Use when: (1) Downloading a video from YouTube or other sites, (2) Extracting audio from a video URL, (3) Downloading subtitles/captions from a video, (4) Getting video metadata without downloading.

相关技能