HOT-Step CPP：使用 C++ 和 GGML 进行本地 AI 音乐生成

云端音乐生成器很方便，但它们会带来经常性成本，将您的创意素材上传到外部服务，并且通常会隐藏底层生成设置。HOT-Step CPP 采取了不同的方法：它将本地 AI 音乐生成打包到一个基于浏览器的应用程序中，由原生 C++/GGML 引擎驱动。

用标题和歌词描述一首歌曲，选择生成参数，并在您自己的硬件上完全生成立体声 48 kHz 音频。无需 API 密钥、订阅或云推理要求。

该项目扩展了 acestep.cpp，增加了 100 多项功能，涵盖生成、音频处理、人声分离、MIDI 转录、母带处理、模型管理以及实验性训练工作流。

为什么 HOT-Step CPP 有趣

HOT-Step CPP 结合了在音乐生成工具中很少同时具备的三个优势：

本地推理 — 您的歌词、提示和生成的曲目保留在您的机器上。
原生性能 — 推理引擎使用 C++ 实现，并使用 GGML 后端，如 CUDA、Vulkan、Metal 或 CPU 执行。
面向生产的工具 — 生成只是开始；该应用程序包括翻唱、人声分离、MIDI、母带处理、VST3 处理、歌词管理、重绘和质量评估。

该应用程序基于 ACE-Step 1.5 构建，并提供了实验性的原生 MiniMax-Music3 后端。这使其既可用作创意工作站，也可用作本地生成音频工程的测试平台。

主要生成工作流

自动生成

自动生成专为那些希望从想法而非完整规格开始的用户设计。选择流派，可选提供主题和语言，集成的语言模型可以生成：

歌词
风格标题
歌曲元数据
标题

您可以选择完全生成的歌词、根据主题编写的歌词或纯器乐工作流。预览模式允许您在提交音频生成之前编辑生成的歌词。串行队列一次处理一个作业，并显示实时进度。

自定义生成

自定义生成提供对生成控件的直接访问。您可以提供自己的歌词和标题，选择标题和艺术家，并配置：

BPM
时长
调号
拍号
求解器和调度器
引导模式
CFG 比例和潜在变量控制
后处理选项

当可重复性和参数实验很重要时，这是更好的工作流。种子和生成元数据会被保留，以便您可以比较变体，而不是依赖记忆。

灵活的采样和插件系统

引擎包括 17 个求解器、9 个调度器和 7 种引导模式。其 Lua 插件架构允许添加新的 ODE/SDE 求解器、噪声调度器、引导模式和后处理流水线，而无需重新构建 C++ 引擎。

要创建插件，请将 .lua 文件放在：

engine/plugins/

插件将在下次启动后在 UI 中可用。插件可以公开自己的滑块、开关和下拉菜单，这使得面向研究的采样方法可以从普通应用程序界面使用。包含的示例包括 CFG-MP、SMC-CFG 和 CFG-Zero⋆。

这种设计对开发人员特别有价值：采样实验可以作为小脚本分发，而不是要求每个用户编译自定义二进制文件。

超越生成的音频制作功能

HOT-Step CPP 将生成的音乐视为可编辑和精炼的材料，而不是最终文件。

匹配和后期处理

Matchering 母带引擎根据参考曲目匹配响度、均衡和动态。即时母带/未母带 A/B 切换使判断处理是否改善了结果变得容易。处理以原生 48 kHz 进行，避免了不必要的重采样往返。

其他处理包括维纳滤波频谱降噪器、原生 C++ 频谱提升器、PP-VAE 神经抛光、人声自然化 DSP、时长缓冲、自动修剪和可配置的淡出。内部流水线保持 WAV32，导出格式为 WAV、MP3 或 FLAC。

StableStep

StableStep 通过部分重新加噪，使用 Stable Audio 3 重新渲染已完成曲目的器乐部分。其目标是用更令人信服的细节替换 VAE 嘶嘶声和其他频谱伪影，同时保持歌词和人声不变。

工作流使用 BS-RoFormer 分离主唱和伴唱，处理器乐部分，并重新混音人声材料。用户可以调整细化强度，并使用从原始标题派生的提示。

有两个后端可用：

GGML：约 5.8 GB 模型
ONNX/TensorRT：约 12 GB 模型

Stable Audio 模型根据 Stability AI 社区许可证分发。

翻唱、人声分离和 MIDI

翻唱工作室

翻唱工作室使用 Essentia 分析参考曲目，提取 BPM、调性、能量和音色信息。它可以生成风格匹配的翻唱，同时保留或转换源曲目的选定方面。

有用的控制包括结构保真度、源保留、变调（带移调预览）、速度缩放、人声分离、重组和每专辑适配器预设。

人声分离工作室和构建器

人声分离工作室使用四阶段分离流水线：

BS-RoFormer 用于主要六轨分离
Mel-Band RoFormer 用于主唱和伴唱隔离
MDX23C 用于鼓子分离
HTDemucs 用于乐器细化

顺序 VRAM 管理使分离期间的峰值使用量低于 3 GB。交互式混音器支持多独奏、每轨音量控制和 ZIP 导出。

人声分离构建器则相反：提供源曲目，并要求 DiT 引擎生成互补的人声、鼓、贝斯、吉他或钢琴音轨。您可以迭代地构建编曲，而不是重新生成整首歌曲。

MIDI 工作室

MIDI 工作室是 Kyutai 和 Mirelo 的 MuScriptor 的原生 C++/GGML 移植。该项目报告与参考实现逐字节验证，并支持 GPU 加速；3.5 分钟的曲目可以在不到一分钟内转录。

该工具可生成跨 34 个乐器组（外加鼓）的多轨 MIDI。提供小、中、大模型，UI 在转录运行时显示实时钢琴卷帘。用户可以使用交叉淡化滑块和每乐器静音或独奏控件，立即将原始音频与 MIDI 演绎进行比较。

模型权重在 Hugging Face 上受门控，并根据 CC BY-NC 4.0 许可，因此此功能仅供非商业使用。

实验性模型训练

训练工作室允许用户在 HOT-Step 内部训练风格适配器，无需 Python 或外部预处理工具。将应用程序指向一个歌曲文件夹，它可以引导工作流完成：

数据集创建
本地 BPM 和调性分析
从 Genius 获取歌词
音频感知 AI 标题
张量预处理
Planner LM LoRA 训练
DiT LoRA 训练

Planner 模型包括 0.6B、1.7B 和 4B 变体。纯 LM 试听模式允许您在没有 DiT 影响的情况下比较 planner 学习的内容与基础模型。

此功能明确为实验性。建议使用至少 16 GB VRAM 的 GPU，而全深度 DiT 训练更适合 24 GB 或以上的系统。预计内存使用量高且行为会变化。

MiniMax-Music3 后端

HOT-Step CPP 还包含 MiniMax-Music3 的基础原生 C++/GGML 移植。该项目将其描述为早期实现，并且据其所知，是 Python 之外该模型的第一个版本。

通过 模型管理器 安装 MiniMax-Music3 包后，全局栏中会出现一个后端切换。该包约为 24 GB，在 f16 下需要大约 24 GB 的 VRAM。

当前支持仅限于使用以下内容的文本到音乐生成：

标题
歌词
时长
种子

此后端尚不支持翻唱、重绘、人声分离、适配器和训练。输出存储为原始 44.1 kHz WAV。计划推出量化、低 VRAM 变体。

硬件和平台支持

预构建版本可用于：

平台	加速选项
Windows x64	CUDA、Vulkan、CPU
Linux x64	CUDA、Vulkan、CPU
macOS Apple Silicon	Metal

对于 NVIDIA 用户，CUDA 提供最佳性能，建议使用 RTX 2060 或更新版本。Vulkan 支持 AMD、Intel 和较旧的 NVIDIA 硬件。CPU 模式适用于任何受支持的机器，但速度明显较慢。

典型存储要求约为 10 GB（应用程序和入门模型）。标准 ACE-Step 模型集通过应用程序下载约需 7 GB。

使用便携式版本快速入门

最简单的安装路径是下载发布存档，解压缩，然后启动特定于平台的脚本。

Windows

下载并解压缩 CUDA、Vulkan 或 CPU 的存档。
运行 HOT-Step.bat。
如果浏览器未自动打开，请打开 http://localhost:3001。
转到 模型 → 获取更多模型 并下载约 7 GB 的入门模型集。

需要 Windows 10 或 11 64 位。CUDA 变体需要兼容的 NVIDIA 驱动程序，而 Vulkan 变体需要 Vulkan 1.1 或更新的驱动程序。

Linux

./HOT-Step.sh

使用 Ubuntu 22.04 或等效的 x86_64 发行版。CUDA 用户需要 NVIDIA 驱动程序 525 或更新；Vulkan 用户需要支持 Vulkan 1.1 的驱动程序和 libvulkan1。

macOS

在运行 macOS 13 或更高版本的 Apple Silicon 系统上：

./HOT-Step.sh

该版本包含 Node.js，因此无需单独安装 Node。如果 macOS 阻止未签名的二进制文件，请一次性删除隔离属性：

xattr -cr /path/to/HOT-Step-CPP/

从源代码构建

克隆仓库及其子模块：

git clone --recursive https://github.com/scragnog/HOT-Step-CPP.git
cd HOT-Step-CPP

如果仓库未使用 --recursive 克隆，请手动初始化依赖项：

git submodule update --init --recursive

Windows 与 CUDA

安装 Visual Studio 2022 生成工具（包含 使用 C++ 的桌面开发）、CUDA Toolkit 12.x 或更新（带 Visual Studio 集成）、CMake 3.14+、Git 和 Node.js 18–22 LTS。不支持 Node.js 24。

便捷的构建命令是：

engine\build.cmd

对于手动 CMake 构建：

cd engine
mkdir build
cd build
cmake .. -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES=native
cmake --build . --config Release -j %NUMBER_OF_PROCESSORS%
cd ..\..

macOS 与 Metal

安装 Xcode 命令行工具、CMake、Node.js 18–22 LTS 和 Git。然后启用 Metal 构建：

cd engine
mkdir build && cd build
cmake .. -DGGML_METAL=ON -DGGML_METAL_EMBED_LIBRARY=ON -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release -j $(sysctl -n hw.ncpu)
cd ../..

嵌入 Metal 着色器库意味着运行时无需外部 .metallib 文件。

Linux

CUDA 构建使用：

cd engine
mkdir -p build && cd build
cmake .. -DGGML_CUDA=ON -DCMAKE_BUILD_TYPE=Release
cmake --build . -j $(nproc)

对于 Vulkan：

cmake .. -DGGML_VULKAN=ON -DCMAKE_BUILD_TYPE=Release
cmake --build . -j $(nproc)

对于仅 CPU 构建，省略后端标志：

cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j $(nproc)

在启动前安装服务器和 UI 依赖项：

cd server && npm install && cd ..
cd ui && npm install && cd ..

在 Windows 上，运行 LAUNCH.bat；在 macOS 和 Linux 上，运行 ./launch.sh。生产模式监听端口 3001。开发模式使用 Vite 前端，端口 3000。

模型布局

源代码构建期望以下文件位于 models/ 下：

models/
├── acestep-5Hz-lm-4B-Q8_0.gguf
├── Qwen3-Embedding-0.6B-Q8_0.gguf
├── acestep-v15-turbo-Q8_0.gguf
└── vae-BF16.gguf

推荐文件大约为：

组件	文件	大小
语言模型	`acestep-5Hz-lm-4B-Q8_0.gguf`	4.2 GB
文本编码器	`Qwen3-Embedding-0.6B-Q8_0.gguf`	748 MB
DiT	`acestep-v15-turbo-Q8_0.gguf`	2.4 GB
VAE	`vae-BF16.gguf`	322 MB

提供较小的 0.6B 和 1.7B LM 变体。可选模型包括 ScragVAE（322 MB）、PP-VAE（644 MB）、StableStep GGML 资源（5.8 GB）和 StableStep ONNX 资源（12 GB）。

应用内模型管理器通常更容易：它提供精选的入门包，并可访问五个 Hugging Face 仓库中的 100 多个 GGUF 模型，支持可恢复的并发下载。

面向开发者的架构

系统分为三个协作组件：

组件	技术	职责
引擎	C++、CUDA、GGML	运行模型推理和原生音频操作
服务器	Node.js、TypeScript	编排作业、管理歌曲并提供应用程序
UI	React、Vite、TypeScript	提供基于浏览器的创意界面

这种分离使项目可以从多个方向入手。C++ 开发人员可以处理推理和 DSP，TypeScript 开发人员可以扩展编排和 API，前端开发人员可以添加创意工作流而无需更改引擎。

引擎支持 GGUF 和 Hugging Face safetensors。safetensors 文件夹可以放入模型目录，并在 UI 中以格式徽章标识。BF16 safetensors 与 BF16 GGUF 相比产生逐位完美的输出，LoRA 适配器适用于两种格式。

常见构建问题

一些特别常见的问题：

Node.js 24 安装失败： 使用 nvm install 22 和 nvm use 22 切换到 Node.js 22 LTS。
MSVC C2589 错误： 定义 NOMINMAX，如有必要，使用 /DNOMINMAX /DWIN32_LEAN_AND_MEAN 配置 CMake。
缺少 CUDA Toolkit 目录： 验证 CUDA_PATH，安装 Visual Studio 集成，然后重新启动终端。
Ninja 二进制位置错误： Ninja 将二进制文件直接放在 engine/build/ 中，而不是 engine/build/Release/。
过时的 CMake 配置： 更改 CUDA 版本或编译器设置后，删除 engine/build/ 并重新配置。
Windows 路径长度错误： 如果重复构建通过 vcvars64.bat 扩展了 PATH，请打开一个新的终端。
macOS Gatekeeper 阻止： 对解压的发布目录使用 xattr -cr。

谁应该尝试？

HOT-Step CPP 非常适合开发人员、音乐家和技术倾向的创作者，他们希望本地控制 AI 音乐生成。它不仅仅是一个文本到音频演示：该项目提供了一个可扩展的原生引擎、一个严肃的浏览器 UI、实验性模型移植，以及越来越多的工具，用于将生成的音频推向成品制作。

权衡是复杂性。大型模型可能需要大量的磁盘空间和 VRAM，某些功能是实验性的，MiniMax-Music3 和训练工作室工作流仍在发展中。然而，对于熟悉本地 AI 工具的用户来说，同样的开放性正是吸引力所在：您可以检查设置、交换模型、编写 Lua 插件、从源代码构建，并将整个创意流水线保留在自己的机器上。

来源

scragnog/HOT-Step-CPP：转动旋钮。召唤神曲！现在更多 C++！由 GGML 驱动的本地 AI 音乐生成