内容
# 流行音乐制作工作室
  
一款为流行音乐艺术家打造的原生 C++ 音乐视频和歌词视频编辑器。无需订阅。无需云服务。无需 Python 运行时环境。所有功能 — 包括转录、声乐分离、语音转换、背景移除、GPU 特效 — 都在您的机器上运行。
---
## 产品介绍
流行音乐制作工作室是一款专为音乐视频工作流程设计的非线性编辑器：导入您的音乐，立即获取逐字歌词，应用视觉特效，并导出为 MP4。它不是一款通用编辑器，带有附加的音乐功能。每一个设计决策 — 三层预览管道、字幕动画引擎、音频主时钟、玻璃特效系统、项目文件管理器 — 都是专门为此用例而做出的。
该应用程序是一个独立的可执行文件，除了标准 Linux 桌面环境附带的运行时依赖外，无需其他依赖。无需 Electron。无需 Python。无需 Node。无需框架。Dear ImGui 运行在 OpenGL 上，做着它被设计的事情。
---
## 机器学习管道
机器学习栈完全在本地运行。不会上传任何数据。
**声乐分离** 使用 Kim_Vocal_2，一种来自 UVR5 社区的经过充分测试的 MDX-Net 模型（约 64 MB）。STFT（FFTW3，n_fft=6144，hop=1024），分段 ONNX 推理，帧重叠率为 25%，iSTFT，以及乐器提取（`original − vocals`）均在 C++ 中使用 ONNX 运行时实现。无需 Python。无需 GPU。
**转录** 使用 whisper.cpp（`large-v3-turbo-q5_0`，约 584 MB），启用 DTW token 时间戳，借助 `WHISPER_AHEADS_LARGE_V3_TURBO`。BPE token 通过在 whisper token 流中检测前导空格被分组为单词。声乐存在门控（RMS 能量拉伸 ≥250 ms）在 MDX-Net 产生空声带时跳过 Whisper，因此 `[Music]` / `♪♪` token 永远不会污染缓存的转录。
**CTC 强制对齐** 将 Whisper 时间戳细化为帧级精度。停留/前进格子解码器（在 C++ 中手动编写，torchaudio 强制对齐算法）运行 wav2vec2-base-960h（Xenova ONNX 量化，约 94 MB）每个 Whisper 段。（T+1）×（L+1）格子在对数概率空间中构建；回溯产生每个目标 token 的一个字符跨度，将其合并为单词时间戳。单词时间戳被固定在 MJPEG 代理帧边界上，以便卡拉 OK 高亮显示在精确的视频帧上。
**背景移除** 使用 u2net_human_seg via ONNX。每个帧都被双线性缩放为 320×320 进行推理，输出掩模被双线性缩放回原始帧分辨率，一个可分离的高斯模糊（半径 ~1px）平滑掩模边缘。掩模作为灰度 MJPEG 流式传输，以便在模型处理时，画布实时更新。
**语音转换** 完全在 C++ 中运行，无需 Python 参与。该管道直接读取 PyTorch `.pth` 模型文件，无需 libtorch： zip 归档文件由系统 `unzip` 解压，然后手动编写的 pickle 虚拟机解析 `data.pkl` 以提取张量元数据和模型配置，并使用手动编写的 protobuf 序列化导出功能齐全的 ONNX 图。VITS 架构（TextEncoder → ResidualCouplingBlock 反向流动 → NSF-HiFiGAN 解码器）完全在 C++ 中重建。HuBERT 嵌入使用共享的 ONNX 模型。`.pth` 输入，语音转换音频输出，无需启动 Python 解释器。
---
## 视频预览
三层，每层可选择，透明升级为媒体可用：
**第 1 层 — 原生 libav 解码。** 当添加剪辑时，源文件直接使用 libav 打开，首帧立即显示。硬件解码在可用时自动附加（`-hwaccel auto` 遍历 VAAPI → CUDA → VDPAU → VideoToolbox）；软件降级运行在 `-threads 2` 每槽。顺序解码跳过 `av_seek_frame + avcodec_flush_buffers`，当下一个请求的帧是自然向前延续时 — 对于具有 2–5 秒 GOP 的 h264，这是解码 1 帧与大约 150 帧每步之间的区别。
**第 2 层 — MJPEG 代理。** 与原生解码并行，ffmpeg 转码四分之一分辨率的 MJPEG，带有二进制帧偏移表。在代理上搜索是 `fseek + libjpeg-turbo 解码 + GPU 上传` — 可测量地比在快速 GPU 上硬件解码原始文件更便宜，因此当转码完成时，每个槽的扫描循环切换到代理。转码器在与硬件加速解码和快速双线性缩放器并行时，以 `min(4, cores/2)` 工作线程运行，因此 20 个剪辑导入时间从 ~60–90 秒降至 ~10–20 秒。
**第 3 层 — 单帧静止图像。** 当 libav 无法打开文件时的备用方案。由 `proxy_ensure_still` 显示，一次生成并缓存在磁盘上。
每个槽位都保留一个 8 帧解码环。画布预先遍历为活动剪辑的每个轨道调度并行 JPEG 解码，以及 3 帧边界预热到即将到来的/前一个剪辑，当播放头在剪辑边界的 1 秒内时，这样在主线程上搜索剪辑边界时，不会命中同步解码。会话级 `proxy_is_ready` 缓存消除时间线绘制循环曾经制作的每帧状态系统调用洪水（每个可见视频剪辑每个帧调用一次）。
---
## 特效引擎
GPU 特效管道在每帧上运行 GLSL 片段着色器，将剪辑层合成到离屏 FBO 中，然后将像素传输到 ffmpeg。
**玻璃特效系统** 允许特效积木在合成整个场景之前应用于单个剪辑 — 或在合成后应用于整个合成帧，具体取决于轨道位置。无需模式切换。无需配置。将 Glitch 积木拖到视频剪辑上方，它仅应用于该剪辑。将它拖到单独的轨道，它将影响整个帧。
100 种特效在 JSON 注册表中定义，并在编译时生成：GLSL 着色器字符串、累积结构体、检查器 UI、序列化、项目版本控制和 MCP 工具描述 — 所有这些都由单个代码生成脚本 (`tools/codegen_effects.py`) 发出。添加新特效只需编写着色器主体和 JSON 条目。
**运行时特效** 可以作为 `.json` + `.glsl` 对放入 `effects/` 目录，并在一个帧内热加载 — 无需重新构建。
---
## 文本渲染
歌词和字幕剪辑支持每剪辑视觉样式：阴影（偏移、颜色）、描边（宽度、颜色）、发光（多通道径向模糊、半径、颜色）和背景框（颜色、填充、圆角）。所有层都按顺序渲染 — 发光 → 背景 → 阴影 → 描边 → 文本 — 通过共享的 `text_renderer` 模块，用于画布预览和导出渲染器，保证像素级对应。
字体样式预设直接连接到文本样式系统：霓虹预设启用热粉色发光；赛博朋克预设启用青色描边。
---
## 字幕系统
八种动画样式（渐入、故障、打字机、弹跳、缩放、滑动、堆叠、块状）和五种分组模式（单词、短语、行、段、自定义 N）。字体大小存储为画布高度的一小部分，而不是像素，因此预览和 1920×1080 导出在几何上是相同的。
---
## 音视频同步
播放头由音频回调位置驱动，并根据输出缓冲区延迟进行校正：
```
playhead = audio_position() - audio_latency()
```
音频时钟无条件推进。视频跟随其后。这在任何搜索位置都提供了高质量的唇同步，而无需轮询墙上时钟。
---
## 项目文件管理器
添加媒体文件和将其放置在时间线上是两回事。文件管理器是项目范围的媒体库，显示在右侧面板中；它保存了您添加到项目中的所有文件，带有缩略图、时长和使用计数。多文件拖放进入文件管理器而不会自动放置，因此拖放 5 个剪辑不会堆叠 5 个重叠轨道在播放头。单个文件拖放特定轨道仍然直接放置（并镜像到文件管理器中，以便面板反映项目中的所有内容）。从文件管理器拖放文件到轨道，当您准备提交放置时。
文件管理器在项目文件中持久保存。预文件管理器项目在加载时从现有剪辑路径回填，因此较旧的存档仍然显示其媒体。
---
## MCP 服务器
流行音乐工作室通过模型上下文协议向 Claude 公开其完整的编辑界面。应用程序启动时运行一个 Unix 套接字 IPC 服务器；Python MCP 桥接器（`mcp_server/server.py`）读取锁定文件，连接到套接字，并注册约 70 个工具，涵盖剪辑创建和操作、文本样式、字体生成、机器学习管道控制、特效应用、音频分析和提示检测、歌词/时刻搜索、播放、项目持久性和文件管理器。
**异步优先。** 长运行工具立即返回，并通过轮询公开状态。`trigger_pipeline` 返回 `stage="running"`，然后跟随 `get_pipeline_status` 直到 `stage="done"`。`analyze_audio`、`remove_background`、`find_and_add_clip` 遵循相同的模式。MCP 服务器不会通过 ML 工作阻塞聊天。
**自动批处理。** 单个突变被包装在一个名为方法名的隐式单调用批处理中，因此一次性 `set_clip_prop` 自动成为一个撤销步骤。仅当要将一系列突变作为单个步骤撤销时，才需要 `begin_batch`/`end_batch`（例如，`add_track` + `add_clip` + `set_clip_prop` 从头开始设置剪辑）。
**无需完整转录的歌词搜索。** `find_and_add_clip(path, query)` 运行窗口化 MDX-Net + Whisper，在第一次命中时停止，并自动提取匹配周围的片段 — 比转录整个歌曲以定位短语的效率高出几个数量级。
### 设置
```bash
pip install -r mcp_server/requirements.txt
```
首先启动流行音乐工作室（MCP 服务器读取 `/tmp/pop-maker-studio.lock` 以查找应用程序的套接字），然后单独运行桥接器：
```bash
python3 mcp_server/server.py
```
或将其连接到 Claude。**Claude 桌面版**（Linux 上的 `~/.config/claude/claude_desktop_config.json`，macOS 上的 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"pop-maker-studio": {
"command": "python3",
"args": ["/absolute/path/to/pop-maker-studio/mcp_server/server.py"]
}
}
}
```
**Claude 代码**（存储库根目录中的 `.mcp.json`）：
```json
{
"mcpServers": {
"pop-maker-studio": {
"command": "python3",
"args": ["mcp_server/server.py"]
}
}
}
```
线缆协议和每工具语义在 `MCP_SPEC.md` 中。工具描述本身位于 `mcp_server/server.py` 中，是规范参考 — 任何单独编写的内容都会在工具更改时立即过时。
---
## 嵌入式终端
一个真正的 PTY 支持终端位于时间线下方的可拖动条中。它运行您的登录 shell（vterm 解析转义代码；鼠标选择、右键复制/粘贴、双宽字符处理和实时调整大小均有效）。将文件路径拖放到终端面板会在提示符处注入文件路径，而不是触及时间线 — 在不离开应用程序的情况下运行临时 ffmpeg 或 ffprobe 有用。
---
## 导出
导出使用与预览相同的 OpenGL 管道。渲染到离屏 FBO 的每个帧在像素上与预览完全相同。原始 RGBA 帧被传输到 ffmpeg 进行 H.264/AAC 编码。导出路径不是单独的渲染器 — 它是实时渲染器，指向帧缓冲区而不是屏幕。
三种输出格式：垂直（9:16，1080×1920 — TikTok / Reels / Shorts），水平（16:9，1920×1080 — YouTube），方形（1:1，1080×1080 — Instagram）。
**示例**（9:16 TikTok 垂直，流行音乐工作室渲染）：
<div align="center"><table><tr>
<td valign="top"><img src="docs/export_example1.gif" width="284"><br><img src="docs/export_example2.gif" width="284"></td>
<td valign="middle"><img src="docs/export_example.gif" width="270"></td>
</tr></table></div>
---
## 平台
主要开发目标是 Linux。GitHub Actions 发布工作流在 Ubuntu 22.04 上构建，下载所有模型（Whisper、Kim_Vocal_2、u2net、HuBERT、wav2vec2、Piper 语音），并打包一个自包含的 tarball。
---
## 构建
```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
```
依赖项：OpenGL、GLFW、FFmpeg（avcodec/avformat/avutil/swresample/swscale）、libjpeg-turbo、FreeType、aubio、vterm、ONNX 运行时、whisper.cpp、fftw3f。
修改 `effects/registry.json` 后，重新生成代码生成头文件：
```bash
python3 tools/codegen_effects.py
```
