HOT-Step CPP: Local AI Music Generation with C++ and GGML

Cloud music generators are convenient, but they introduce recurring costs, upload your creative material to external services, and often hide the underlying generation settings. HOT-Step CPP takes a different approach: it packages local AI music generation into a browser-based application backed by a native C++/GGML engine.

Describe a song with a caption and lyrics, select your generation parameters, and produce stereo 48 kHz audio entirely on your own hardware. There are no API keys, subscriptions, or cloud inference requirements.

The project extends acestep.cpp with more than 100 features covering generation, audio processing, stem separation, MIDI transcription, mastering, model management, and experimental training workflows.

Why HOT-Step CPP is interesting

HOT-Step CPP combines three advantages that are rarely available in one music-generation tool:

1. Local inference — your lyrics, prompts, and generated tracks remain on your machine.
2. Native performance — the inference engine is implemented in C++ and uses GGML backends such as CUDA, Vulkan, Metal, or CPU execution.
3. Production-oriented tooling — generation is only the beginning; the application includes covers, stems, MIDI, mastering, VST3 processing, lyric management, repainting, and quality evaluation.

The application is built around ACE-Step 1.5, with an experimental native MiniMax-Music3 backend also available. This makes it useful both as a creative workstation and as a testbed for local generative-audio engineering.

Main generation workflows

Auto-Gen

Auto-Gen is designed for users who want to start with an idea rather than a complete specification. Choose a genre, optionally provide a subject and language, and the integrated language model can generate:

• Lyrics
• A style caption
• Song metadata
• A title

You can choose fully generated lyrics, lyrics written from a subject, or an instrumental workflow. Preview mode lets you edit the generated lyrics before committing them to audio generation. A serial queue processes one job at a time and exposes live progress.

Custom-Gen

Custom-Gen provides direct access to the generation controls. You can supply your own lyrics and caption, select the title and artist, and configure:

• BPM
• Duration
• Key signature
• Time signature
• Solver and scheduler
• Guidance mode
• CFG scale and latent controls
• Post-processing options

This is the better workflow when reproducibility and parameter experimentation matter. Seeds and generation metadata are retained so that you can compare variations instead of relying on memory.

A flexible sampling and plugin system

The engine includes 17 solvers, 9 schedulers, and 7 guidance modes. Its Lua plugin architecture allows new ODE/SDE solvers, noise schedulers, guidance modes, and post-processing pipelines to be added without rebuilding the C++ engine.

To create a plugin, place a .lua file in:

engine/plugins/

The plugin becomes available in the UI after the next launch. Plugins can expose their own sliders, toggles, and dropdowns, which makes research-oriented sampling methods usable from the normal application interface. Included examples include CFG-MP, SMC-CFG, and CFG-Zero⋆.

This design is particularly valuable for developers: sampling experiments can be distributed as small scripts rather than requiring every user to compile a custom binary.

Audio production features beyond generation

HOT-Step CPP treats generated music as material to edit and refine rather than a final file.

Matchering and post-processing

The Matchering mastering engine matches loudness, equalization, and dynamics against a reference track. An instant mastered/unmastered A/B toggle makes it easy to judge whether processing improved the result. Processing operates at native 48 kHz, avoiding an unnecessary resampling round trip.

Additional processing includes a Wiener-filter spectral denoiser, a native C++ Spectral Lifter, PP-VAE neural polishing, Vocal Naturalizer DSP, duration buffering, automatic trimming, and configurable fade-outs. The internal pipeline remains WAV32, with export available as WAV, MP3, or FLAC.

StableStep

StableStep re-renders the instrumental portion of a finished track through Stable Audio 3 using partial re-noising. Its goal is to replace VAE fizz and other spectral artifacts with more convincing detail while leaving the lyrics and vocals intact.

The workflow separates lead and backing vocals with BS-RoFormer, processes the instrumental, and remixes the vocal material. Users can adjust refine strength and use a prompt derived from the original caption.

Two backends are available:

• GGML: approximately 5.8 GB of models
• ONNX/TensorRT: approximately 12 GB of models

The Stable Audio models are distributed under the Stability AI Community License.

Covers, stems, and MIDI

Cover Studio

Cover Studio analyzes a reference track using Essentia, extracting BPM, key, energy, and timbral information. It can generate a style-matched cover while preserving or transforming selected aspects of the source.

Useful controls include structure fidelity, source preservation, pitch shifting with key-transposition previews, tempo scaling, stem separation, recombination, and per-album adapter presets.

Stem Studio and Stem Builder

Stem Studio uses a four-stage separation pipeline:

1. BS-RoFormer for primary six-stem separation
2. Mel-Band RoFormer for lead and backing vocal isolation
3. MDX23C for drum sub-separation
4. HTDemucs for instrument refinement

Sequential VRAM management keeps peak usage under 3 GB during separation. The interactive mixer supports multi-solo, per-stem volume controls, and ZIP export.

Stem Builder works in the opposite direction: provide a source track and ask the DiT engine to generate complementary vocals, drums, bass, guitar, or piano stems. You can iteratively build an arrangement instead of regenerating the entire song.

MIDI Studio

MIDI Studio is a native C++/GGML port of MuScriptor from Kyutai and Mirelo. The project reports byte-for-byte validation against the reference implementation and GPU acceleration; a 3.5-minute track can be transcribed in under a minute.

The tool produces multi-track MIDI across 34 instrument groups plus drums. Small, medium, and large models are available, and the UI displays a live piano roll while transcription runs. Users can immediately compare the original audio with the MIDI rendition using a crossfade slider and per-instrument mute or solo controls.

The model weights are gated on Hugging Face and licensed CC BY-NC 4.0, so this feature is intended for non-commercial use.

Experimental model training

The Training Studio lets users train style adapters inside HOT-Step without Python or external preprocessing tools. Point the application at a folder of songs and it can guide the workflow through:

• Dataset creation
• Local BPM and key analysis
• Lyrics retrieval from Genius
• Audio-aware AI captions
• Tensor preprocessing
• Planner LM LoRA training
• DiT LoRA training

Planner models include 0.6B, 1.7B, and 4B variants. A pure-LM audition mode lets you compare what the planner learned against the base model without DiT influence.

This feature is explicitly experimental. A GPU with at least 16 GB of VRAM is recommended, while full-depth DiT training is better suited to systems with 24 GB or more. Expect high memory use and changing behavior.

MiniMax-Music3 backend

HOT-Step CPP also includes a rudimentary native C++/GGML port of MiniMax-Music3. The project describes it as an early implementation and, to its knowledge, the first version of the model outside Python.

After installing the MiniMax-Music3 pack through Model Manager, a backend switch appears in the global bar. The pack is approximately 24 GB and requires roughly 24 GB of VRAM at f16.

Current support is limited to text-to-music generation using:

• Caption
• Lyrics
• Duration
• Seed

Covers, repainting, stems, adapters, and training are not yet supported for this backend. Output is stored as raw 44.1 kHz WAV. Quantized, lower-VRAM variants are planned.

Hardware and platform support

Pre-built releases are available for:

Platform	Acceleration options
Windows x64	CUDA, Vulkan, CPU
Linux x64	CUDA, Vulkan, CPU
macOS Apple Silicon	Metal

For NVIDIA users, CUDA provides the best performance, with an RTX 2060 or newer recommended. Vulkan supports AMD, Intel, and older NVIDIA hardware. CPU mode works on any supported machine but is significantly slower.

Typical storage requirements are approximately 10 GB for the application and starter models. The standard ACE-Step model set requires roughly 7 GB to download through the application.

Quick start with a portable release

The simplest installation path is to download a release archive, extract it, and launch the platform-specific script.

Windows

1. Download and extract the archive for CUDA, Vulkan, or CPU.
2. Run HOT-Step.bat.
3. Open http://localhost:3001 if the browser does not open automatically.
4. Go to Models → Get More Models and download the approximately 7 GB starter model set.

Windows 10 or 11 64-bit is required. The CUDA variant needs compatible NVIDIA drivers, while the Vulkan variant requires Vulkan 1.1 or newer drivers.

Linux

./HOT-Step.sh

Use Ubuntu 22.04 or an equivalent x86_64 distribution. CUDA users need NVIDIA drivers 525 or newer; Vulkan users need Vulkan 1.1-capable drivers and libvulkan1.

macOS

On Apple Silicon systems running macOS 13 or newer:

./HOT-Step.sh

The release includes Node.js, so no separate Node installation is needed. If macOS blocks the unsigned binaries, remove the quarantine attribute once:

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

Building from source

Clone the repository with its submodules:

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

If the repository was cloned without --recursive, initialize the dependencies manually:

git submodule update --init --recursive

Windows with CUDA

Install Visual Studio 2022 Build Tools with Desktop development with C++, CUDA Toolkit 12.x or newer with Visual Studio integration, CMake 3.14+, Git, and Node.js 18–22 LTS. Node.js 24 is not supported.

The convenient build command is:

engine\build.cmd

For a manual CMake build:

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

macOS with Metal

Install Xcode Command Line Tools, CMake, Node.js 18–22 LTS, and Git. Then build with Metal enabled:

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

Embedding the Metal shader library means no external .metallib file is required at runtime.

Linux

CUDA builds use:

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

For Vulkan:

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

For CPU-only builds, omit the backend flag:

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

Install server and UI dependencies before launching:

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

On Windows, run LAUNCH.bat; on macOS and Linux, run ./launch.sh. Production mode listens on port 3001. Development mode uses the Vite frontend on port 3000.

Model layout

A source build expects the following files under 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

The recommended files are approximately:

Component	File	Size
Language model	acestep-5Hz-lm-4B-Q8_0.gguf	4.2 GB
Text encoder	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

Smaller 0.6B and 1.7B LM variants are available. Optional models include ScragVAE at 322 MB, PP-VAE at 644 MB, StableStep GGML assets at 5.8 GB, and StableStep ONNX assets at 12 GB.

The in-app Model Manager is usually easier: it provides curated starter packs and access to more than 100 GGUF models across five Hugging Face repositories, with resumable concurrent downloads.

Architecture for developers

The system is divided into three cooperating components:

Component	Technology	Responsibility
Engine	C++, CUDA, GGML	Runs model inference and native audio operations
Server	Node.js, TypeScript	Orchestrates jobs, manages songs, and serves the application
UI	React, Vite, TypeScript	Provides the browser-based creative interface

This separation makes the project approachable from several directions. C++ developers can work on inference and DSP, TypeScript developers can extend orchestration and APIs, and frontend developers can add creative workflows without changing the engine.

The engine supports GGUF and Hugging Face safetensors. Safetensors folders can be dropped into the models directory and are identified with a format badge in the UI. BF16 safetensors produce bit-perfect output compared with BF16 GGUF, and LoRA adapters work with both formats.

Common build problems

A few issues are especially common:

• Node.js 24 installation failures: switch to Node.js 22 LTS with nvm install 22 and nvm use 22.
• MSVC C2589 errors: define NOMINMAX and, if necessary, configure CMake with /DNOMINMAX /DWIN32_LEAN_AND_MEAN.
• Missing CUDA Toolkit directory: verify CUDA_PATH, install Visual Studio integration, and restart the terminal.
• Ninja binary location errors: Ninja places binaries directly in engine/build/, rather than engine/build/Release/.
• Stale CMake configuration: remove engine/build/ and configure again after changing CUDA versions or compiler settings.
• Windows path length errors: open a fresh terminal if repeated builds have expanded PATH through vcvars64.bat.
• macOS Gatekeeper blocks: use xattr -cr on the extracted release directory.

Who should try it?

HOT-Step CPP is a strong fit for developers, musicians, and technically inclined creators who want local control over AI music generation. It is more than a text-to-audio demo: the project provides an extensible native engine, a serious browser UI, experimental model ports, and a growing collection of tools for taking generated audio toward a finished production.

The trade-off is complexity. Large models can require substantial disk space and VRAM, some features are experimental, and the MiniMax-Music3 and Training Studio workflows are still evolving. For users comfortable with local AI tooling, however, that same openness is the appeal: you can inspect settings, swap models, write Lua plugins, build from source, and keep the entire creative pipeline on your own machine.

Source

scragnog/HOT-Step-CPP: Turn dials. Summon bangers! NOW WITH MORE C++! Local AI music generation powered by GGML