MusiCue

在舞台演出、动态图形设计和互动装置中，让视觉元素精准跟随音乐节奏是一项耗时且精细的工作。MusiCue 是一个强大的本地化工具，它能将音频文件自动分析并转换为结构化的“提示表单”（Cue Sheet），直接驱动 After Effects、TouchDesigner、Unreal Engine、Houdini 等主流创作软件。

通过三层流水线架构，MusiCue 不仅能识别节拍和段落，还能提取鼓点、人声、能量曲线等细粒度特征，并将其映射为关键帧、OSC 信号或 DMX 指令。无论是复杂的演唱会视觉秀，还是简单的社交媒体视频特效，MusiCue 都能让你从繁琐的手动打点中解放出来，专注于创意本身。

核心亮点：智能分析、灵活编译、广泛兼容

1. Layer 1：深度音频分析

基于先进的 AI 模型与信号处理算法，精准提取音乐特征：

• 源分离：使用 Demucs 将音频分离为鼓、贝斯、人声、其他四个轨道。
• 节拍与段落检测：结合 All-In-One 模型与 librosa 库，精准识别强拍、弱拍及歌曲结构（Intro, Verse, Chorus 等）。
• 语义标签：可选集成 CLAP 模型，为音乐片段添加语义描述（如“高潮”、“低沉”）。
• 多维特征：提取 LUFS 响度、频谱亮度、立体声宽度、起音（Onset）等数据。
• GPU 加速：支持 NVIDIA CUDA 加速，大幅提升处理速度。

2. Layer 2：YAML DSL 编译引擎

将原始分析数据转化为可执行的逻辑指令：

• 自定义语法：内置四种预设语法（concert_visuals, character_animation, lighting, camera_edit），也可通过 YAML 编写自定义规则。
• 灵活过滤：支持复杂的过滤表达式，如 drum_class == 'kick'（仅选底鼓）、near_downbeat(0.05)（靠近强拍）、any_label('sub bass drop')（特定语义标签）。
• 智能加权：支持逐轨评分、层级权重、稀有度衰减和冷却时间设置，避免输出过于密集或稀疏。

3. Layer 3：多格式导出

无缝对接主流创作工具，支持九种目标格式：

• Adobe After Effects：生成 .jsx 脚本，自动创建空图层、滑动控制器关键帧及合成标记。
• TouchDesigner：输出 CHOP CSV 和 Events CSV，可直接接入 Table DAT 进行实时驱动。
• Unreal Engine：生成 Sequencer JSON，包含事件轨和带插值的浮点曲线。
• Houdini：输出 CHOP 兼容 CSV，含元数据头部。
• 其他格式：CSV、JSON、MIDI（GM 鼓音符/CC 控制）、OSC Bundle、Disguise/DMX 提示列表。

安装与使用

Windows 一键安装（推荐）

MusiCue 提供专为 Windows 优化的一键安装程序，自动配置 Python 环境、依赖库及模型权重。

1. 准备环境：
   • Windows 10/11。
   • NVIDIA GPU（RTX 或较新 GTX，用于加速；无 GPU 亦可运行但较慢）。
   • 约 6 GB 磁盘空间。
2. 获取代码：

   git clone https://github.com/cedarconnor/MusiCue.git
   

3. 运行安装：
   双击 install.bat。脚本将自动安装 uv、Python 3.11、PyTorch (CUDA)、Demucs 模型等。全程约 5-20 分钟。
4. 启动应用：
   双击 run.bat，在浏览器访问 http://127.0.0.1:8000/library。

macOS / Linux / 开发者模式

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# 安装核心依赖
pip install -e ".[dev,ui,midi,osc]" basic-pitch

# 可选：安装语义标签模型 (约 4GB)
pip install -e ".[clap]"

# 可选：安装段落检测模型 (Linux/Mac 更易安装)
pip install allin1

# 启动服务器
python -m uvicorn musicue.ui.server:create_app --factory

Web UI 功能概览

MusiCue 内置本地 Web 应用，提供直观的可视化编辑与预览体验：

• 库管理：拖拽导入音频或粘贴 URL（YouTube/SoundCloud 等），后台自动分析。支持搜索、过滤及回收站功能。
• 五轨编辑器：
  1. 混音波形：整体音频视图。
  2. 段落条：显示 Intro/Verse/Chorus 等结构块。
  3. 起音/节拍条：标记所有鼓点、起音及节拍位置。
  4. 源轨道：分别展示鼓、贝斯、人声、其他的波形与特征标记。
  5. 曲线面板：绘制响度、亮度等连续变化曲线。
• 实时预览：支持播放、缩放、循环区域设置，并可导出 QC 点击轨 WAV 进行听觉校验。

CLI 快速参考

# 一键渲染：将歌曲转换为 TouchDesigner 可用的 CSV
musicue render song.wav --target touchdesigner --out song_td.csv

# 分步执行：分析 -> 检查 -> 编译 -> 导出
musicue analyze song.wav --out runs/song/
musicue inspect runs/song/analysis.json
musicue compile runs/song/analysis.json --grammar concert_visuals --out cuesheet.json
musicue export cuesheet.json --target after_effects --out cuesheet.jsx

# 批量处理
musicue render ./music_folder --batch --workers 4