A feature-rich UI for acestep.cpp — local AI music generation powered by GGML, with native safetensors support.
Describe a song with a text caption and lyrics, and get stereo 48kHz audio generated entirely on your local hardware. No cloud, no API keys, no subscriptions.
Build a song section by section, Udio-style. Generate an intro, then generate several options for the next section (verse, pre-chorus, chorus…), audition them, pick your favourite, and extend — one piece at a time. You can prepend an intro after the fact, set per-section lyrics and bar counts, choose where each section attaches, and even seed a repeated section from an earlier one to follow its chords.
It's a new feature still in active development and testing, so expect rough edges — but we'd love for you to try it and share feedback. Find it in the sidebar as Song Builder.
Pre-built portable releases — no installation required. Extract, run, done.
📥 Download the latest release →
| Platform | Variants |
|---|---|
| Windows (x64) | CUDA (NVIDIA), Vulkan (AMD/Intel/NVIDIA), CPU |
| Linux (x64) | CUDA (NVIDIA), Vulkan (AMD/Intel/NVIDIA), CPU |
| macOS (Apple Silicon) | Metal (M1/M2/M3/M4) |
Which variant?
- CUDA — Best performance. Use this if you have an NVIDIA GPU (RTX 2060 or newer recommended).
- Vulkan — Cross-vendor GPU support. Use this if you have an AMD or Intel GPU, or an older NVIDIA card.
- CPU — No GPU needed. Works on any machine but generation will be significantly slower.
Windows:
- Download and extract the zip for your hardware
- Run
HOT-Step.bat - Your browser opens to
http://localhost:3001 - On first launch, go to Models → Get More Models to download the AI models (~7 GB)
Linux:
- Download and extract the
.tar.gzfor your hardware - Run
./HOT-Step.sh - Open
http://localhost:3001in your browser - On first launch, go to Models → Get More Models to download the AI models (~7 GB)
macOS:
- Download and extract the
.tar.gz - Open Terminal in the extracted folder and run
./HOT-Step.sh - Your browser opens to
http://localhost:3001 - On first launch, the Model Manager opens automatically — download the AI models (~7 GB)
Windows requirements: Windows 10/11 (64-bit), ~10 GB free disk space. CUDA variant needs NVIDIA drivers. Vulkan variant needs Vulkan 1.1+ capable drivers.
Linux requirements: Ubuntu 22.04+ or equivalent (x86_64), ~10 GB free disk space. CUDA variant needs NVIDIA drivers 525+. Vulkan variant needs Vulkan 1.1+ capable drivers and
libvulkan1.
macOS requirements: macOS 13+ (Apple Silicon M1/M2/M3/M4), ~10 GB free disk space. No other software needed — Node.js is bundled. If macOS blocks the app (unsigned binary), run:
xattr -cr /path/to/HOT-Step-CPP/
HOT-Step CPP extends the base acestep.cpp engine with 100+ features across inference, audio processing, and creative tooling. Here are the big ones:
🎛️ 17 Solvers, 9 Schedulers, 7 Guidance Modes, Postprocess Plugins — Fully extensible Lua plugin architecture for ODE/SDE solvers, noise schedulers, guidance modes, and postprocess pipelines. Drop a .lua file into engine/plugins/ and it appears in the UI at next launch — no C++ rebuild needed. Includes research-derived modes like CFG-MP (manifold projection), SMC-CFG (sliding mode control), and CFG-Zero⋆ (zero-init). Each plugin can expose its own user-facing parameters (sliders, toggles, dropdowns). Create your own →
🎸 LoRA Adapters with Runtime Mode — Per-group scale controls (self_attn, cross_attn, mlp, cond_embed), K-quant GPU support via custom CUDA kernels, and a runtime LoRA mode that applies deltas in the forward pass without permanently merging weights.
🎚️ Matchering Mastering Engine — Loudness, EQ, and dynamics matching to a reference track with instant mastered/unmastered A/B toggle. Operates at native 48kHz — no resample round-trip.
🤖 Auto-Gen — AI-driven song creation. Pick genres, optionally set a subject and language, and the LM handles everything — lyrics, style caption, metadata, and title. Three lyric modes: fully AI-generated, AI-written from your subject, or instrumental. Preview mode lets you review and edit AI-generated lyrics before committing to generation. Serial queue ensures one job at a time with live progress tracking.
🎹 Custom-Gen — Full manual control over every generation parameter. Write your own lyrics (or go instrumental), set a style caption, title, artist, BPM, duration, key signature, and time signature. Direct access to all engine settings with queue-based generation. The power-user mode for when you know exactly what you want.
🔌 VST3 Host — Scan, load, and run your existing VST3 plugins directly in the generation pipeline. Offline processing and real-time WASAPI monitor mode with transport controls. Note: VST plugins run in a single-input pipeline with no external sidechain bus. Plugins that require an external key signal (sidechain compressors, keyed gates, duckers) will not trigger — use plugins in their internal detection mode instead.
✍️ Lyric Studio — A complete AI-powered lyrics and music workspace. 7 LLM providers (Gemini, LM Studio, OpenAI-compatible), artist profiles with adapter presets, statistical lyric analysis, bulk generation with "Fill to N" mode, and full parameter parity with the Create page.
🎤 Cover Studio — Upload a reference track, get Essentia-based analysis (BPM, key, energy, timbre), and generate style-matched covers. Artist-optional workflow with editable style descriptions, pitch shift with key transposition preview, tempo scaling, stem separation + recombination, and per-album adapter presets.
🔪 Stem Studio — 4-stage neural stem separation powered by SuperSep. BS-RoFormer for primary 6-stem splits, Mel-Band RoFormer for lead/backing vocal isolation, MDX23C for drum sub-separation, and HTDemucs for instrument refinement. Interactive mixer with multi-solo, per-stem volume controls, and ZIP export. Sequential VRAM management keeps peak usage under 3 GB.
🧱 Stem Builder — Generatively create new instrument stems for source tracks using the DiT engine. Select a source audio file, choose which instrument layers to generate (vocals, drums, bass, guitar, piano), and the engine creates fresh stems that complement the original. Build up arrangements by iteratively adding AI-generated layers.
🎼 MIDI Studio — Audio-to-MIDI transcription on a native C++/GGML port of MuScriptor (Kyutai & Mirelo), validated byte-for-byte against the reference and GPU-accelerated — a 3.5-minute track transcribes in under a minute. Convert any library track or an uploaded WAV/MP3 into multi-track MIDI (34 instrument groups + drums), watch the piano roll fill in live while transcription runs, and hit play immediately with a crossfade slider between the original audio and the MIDI rendition, plus per-instrument mute/solo. Small/medium/large models with in-app weight download (gated on Hugging Face; weights CC BY-NC 4.0 — non-commercial).
✨ StableStep — Post-processing refiner that re-renders the instrumental of a finished track through Stable Audio 3 (SDEdit-style partial re-noising) to replace VAE fizz with genuine spectral detail. Vocals are split out via BS-RoFormer (lead + backing), cleaned with PP-VAE, and remixed untouched — lyrics stay intact. Adjustable refine strength, per-track prompt derived from the generation caption, and two engine backends: GGML (CUDA/Vulkan/CPU, ~5.8 GB, fastest in testing) or ONNX/TensorRT (~12 GB). Models download in-app under the Stability AI Community License. Powered by Stability AI.
🔊 Audio Post-Processing — Spectral denoiser (Wiener-filter), Spectral Lifter (native C++), PP-VAE neural audio polish, Vocal Naturalizer (5-stage DSP humanization, experimental — may affect downstream processing), duration buffer with auto-trim for clean endings, and configurable fade-out.
📊 Audio Quality Evaluator — Automatic post-generation quality scoring using spectral analysis. Three weighted metrics — metallic sound detection (spectral rolloff), word cut detection (spectral flux discontinuities), and noise/hiss analysis (zero-crossing rate) — produce a 0–100% score per track. Choose to evaluate unmastered, mastered, or both for direct comparison. Scores display as colour-coded badges in the Library. Ported from JK-AceStep-Nodes (MIT License).
🤖 AI Assistant — In-app LLM-powered assistant with full awareness of your current settings, lyrics, mode, and engine state. Ask it to review your configuration, write or rewrite lyrics, suggest optimizations, or directly apply setting changes — all via a streaming chat sidebar. Supports any configured LLM provider (local or cloud) with per-action apply controls and thinking/response separation.
🧪 Latent Space Controls — Latent shift, latent rescale, custom timestep scheduling, DCW (Differential Correction in Wavelet domain) sampling, and auto-shift for adaptive noise scaling.
📦 Lossless Pipeline — WAV32 throughout the processing chain, with export to WAV, MP3, or FLAC.
📥 In-App Model Manager — Browse 100+ GGUF models across 5 HuggingFace repos, download with curated starter packs, and manage your model library without leaving the app. Concurrent resumable downloads with real-time progress.
🧬 PP-VAE & ScragVAE — Two custom VAE models. PP-VAE runs a neural encode→decode polish pass on generated audio to smooth spectral artifacts. ScragVAE is a fine-tuned decoder with improved high-frequency energy and dynamic range — both selectable at runtime.
📦 Safetensors Model Support — Load HuggingFace-format safetensors models alongside GGUF. Drop a model folder into the models directory and it appears in the UI with a format badge. Supports DiT, LM, Text Encoder, and VAE. BF16 safetensors produce bit-perfect output vs BF16 GGUF. Adapters (LoRA) work with both base model formats.
🎨 Repaint Studio — Region-based audio regeneration. Select a section of a track via waveform click-drag, edit synchronized lyrics, and regenerate just that portion while preserving the rest. Fix problematic sections without re-generating the entire song.
🔄 A/B Comparison — Dual-track playback for comparing two generations side by side. Global A/B mini-bar above the player persists across views for quick cross-page comparison.
Browse your generated songs as a cover art grid with AI-generated artwork, quality scores, and audio metadata. The right sidebar shows a live playlist and engine terminal output. The bottom bar features a waveform visualizer with section markers (verse, chorus, bridge) and real-time synced lyrics.
AI-driven music creation — pick a genre, set a vocal mode, and the LLM handles everything else. The song details panel shows full generation metadata: models used, solver, scheduler, CFG scale, key signature, time signature, and duration.
A complete AI-powered lyrics workspace. Browse artists and albums on the left, view and edit AI-generated lyrics with structural section tags in the centre, and manage your generation queue on the right. Supports multiple LLM providers for lyric generation and refinement.
Upload a reference track for automatic BPM and key detection via Essentia analysis. The engine extracts style descriptions, lyrics, and structural metadata. Fine-tune cover settings including structure fidelity, source preservation, pitch shift with key transposition, and tempo scaling.
Browse curated starter packs tailored to different hardware tiers — from minimal setups to Blackwell-optimized configurations. Download individual GGUF models, stem separation networks, and CUDA/cuDNN runtime libraries directly from HuggingFace without leaving the app.
HOT-Step CPP is three components working together:
| Component | Tech | Purpose |
|---|---|---|
| Engine | C++ / CUDA / GGML | The acestep.cpp inference engine — runs the AI models |
| Server | Node.js / TypeScript | Orchestrates the engine, manages songs, serves the UI |
| UI | React / Vite / TypeScript | The browser-based frontend |
| Platform | Status |
|---|---|
| Windows + NVIDIA (CUDA) | ✅ Pre-built release available |
| Windows + AMD/Intel (Vulkan) | ✅ Pre-built release available |
| Windows CPU-only | ✅ Pre-built release available |
| macOS Apple Silicon (Metal) | ✅ Pre-built release available |
| Linux + NVIDIA (CUDA) | ✅ Pre-built release available |
| Linux + AMD/Intel (Vulkan) | ✅ Pre-built release available |
| Linux CPU-only | ✅ Pre-built release available |
If you prefer to build from source (or want to contribute), follow the instructions below. Most users should use the pre-built releases instead.
| Requirement | Version | Notes |
|---|---|---|
| Visual Studio 2022 Build Tools | 2022 | Select "Desktop development with C++" workload |
| CUDA Toolkit | 12.x+ | For NVIDIA GPU acceleration. Select "Visual Studio Integration" during install. |
| CMake | 3.14+ | Usually included with VS Build Tools |
| Node.js | 18–22 LTS | Node 24+ is not supported — use nvm to install 22 LTS if needed |
| Git | Any | For cloning |
git clone --recursive https://github.com/scragnog/HOT-Step-CPP.git
cd HOT-Step-CPPAlready cloned without
--recursive? Rungit submodule update --init --recursiveto fetch the ggml and vst3sdk submodules.
The easiest way:
engine\build.cmdThis automatically finds your Visual Studio installation (any edition) and builds with CUDA.
Alternatively, open a Developer Command Prompt for VS 2022 and build manually:
cd engine
mkdir build
cd build
cmake .. -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES=native
cmake --build . --config Release -j %NUMBER_OF_PROCESSORS%
cd ..\..Note: If you use Ninja as your CMake generator (
-G Ninja), binaries will be placed directly inengine/build/rather thanengine/build/Release/. The server auto-detects both locations.
Download four GGUF model files from Hugging Face and place them in a models/ directory at the repo root:
HOT-Step-CPP/
├── models/ ← create this, put GGUFs here
│ ├── acestep-5Hz-lm-4B-Q8_0.gguf
│ ├── Qwen3-Embedding-0.6B-Q8_0.gguf
│ ├── acestep-v15-turbo-Q8_0.gguf
│ └── vae-BF16.gguf
├── engine/
├── server/
└── ui/
| Type | Recommended File | Size |
|---|---|---|
| LM | 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 LM variants available: 0.6B (fast) and 1.7B (balanced).
| Type | File | Size | Source |
|---|---|---|---|
| ScragVAE | scragvae-BF16.gguf |
322 MB | scragnog/Ace-Step-1.5-ScragVAE |
| PP-VAE | pp-vae-F32.gguf |
644 MB | scragnog/HOT-Step-CPP-PP-VAE |
| StableStep (GGML) | sa3-*.gguf (4 files) |
5.8 GB | scragnog/HOT-Step-CPP-StableStep |
| StableStep (ONNX) | onnx/sa3/ (9 files) |
12 GB | scragnog/HOT-Step-CPP-StableStep |
ScragVAE is a fine-tuned VAE decoder with improved high-frequency energy and dynamic range — drop-in replacement for the standard VAE. PP-VAE enables neural audio polish via an encode→decode round-trip in the post-processing chain.
💡 Tip: You can also download models directly from the app! Click Models → Get More Models to browse 100+ models across 5 HuggingFace repos, with curated starter packs for quick setup.
install.batOr manually (PowerShell):
cd server; npm install; cd ..
cd ui; npm install; cd ..LAUNCH.batOpen http://localhost:3001 in your browser. That's it!
No
.envfile needed for the standard setup. The server automatically finds the engine binary (checksengine/build/Release/,engine/build/, andengine/build/Debug/) and models atmodels/. See.env.exampleif you need to override paths for a custom setup.
Development mode (with hot-reload):
dev.batThen open http://localhost:3000.
| Requirement | Version | Notes |
|---|---|---|
| Xcode Command Line Tools | 16+ | xcode-select --install |
| CMake | 3.14+ | brew install cmake |
| Node.js | 18–22 LTS | brew install node@22 — Node 24+ is not supported |
| Git | Any | Included with Xcode CLI tools |
Note: Xcode provides the Metal SDK and C++ compiler. No separate GPU toolkit is needed — Metal support is built into macOS.
git clone --recursive https://github.com/scragnog/HOT-Step-CPP.git
cd HOT-Step-CPPAlready cloned without
--recursive? Rungit submodule update --init --recursiveto fetch the ggml and vst3sdk submodules.
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 ../..This builds with Metal GPU acceleration. The Metal shader library is embedded into the binary so no external
.metallibfile is needed at runtime.
Same as Windows — place GGUF files in models/. See model list above. Or skip this and download from the in-app Model Manager on first launch.
cd server && npm install && cd ..
cd ui && npm install && cd .../launch.shOpen http://localhost:3001 in your browser.
No
.envfile needed for the standard setup. The server automatically finds the engine binary and models. See.env.exampleif you need to override paths.
Development mode (with hot-reload):
./launch.sh # In one terminal
cd ui && npx vite # In another terminalThen open http://localhost:3000.
| Requirement | Version | Notes |
|---|---|---|
| GCC / Clang | GCC 11+ | sudo apt install build-essential |
| CMake | 3.14+ | sudo apt install cmake |
| Node.js | 18–22 LTS | Node 24+ is not supported |
| Git | Any | sudo apt install git |
| CUDA Toolkit (optional) | 12.x+ | For NVIDIA GPU acceleration |
| Vulkan SDK (optional) | Latest | For AMD / Intel GPU acceleration |
git clone --recursive https://github.com/scragnog/HOT-Step-CPP.git
cd HOT-Step-CPPAlready cloned without
--recursive? Rungit submodule update --init --recursiveto fetch the ggml and vst3sdk submodules.
CUDA (NVIDIA GPU):
cd engine
mkdir -p build && cd build
cmake .. -DGGML_CUDA=ON -DCMAKE_BUILD_TYPE=Release
cmake --build . -j $(nproc)
cd ../..Vulkan (AMD / Intel / NVIDIA):
# Install Vulkan SDK first: https://vulkan.lunarg.com/sdk/home
cd engine
mkdir -p build && cd build
cmake .. -DGGML_VULKAN=ON -DCMAKE_BUILD_TYPE=Release
cmake --build . -j $(nproc)
cd ../..CPU-only:
cd engine
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j $(nproc)
cd ../..Same as Windows — place GGUF files in models/. See model list above. Or skip this and download from the in-app Model Manager on first launch.
cd server && npm install && cd ..
cd ui && npm install && cd .../launch.shOpen http://localhost:3001 in your browser.
No
.envfile needed for the standard setup. The server automatically finds the engine binary and models. See.env.exampleif you need to override paths.
You can package a self-contained, zero-prerequisite release for distribution. The resulting archive bundles everything — engine binaries, Node.js runtime, server, UI, and plugins — so end users just extract and run.
./package-release.shThis will:
- Build the C++ engine with Metal GPU acceleration
- Install production server dependencies
- Build the optimised production UI
- Download and bundle a Node.js 22 runtime (~40 MB)
- Package everything into a
.tar.gz
Options:
./package-release.sh --skip-build # Skip engine build (use existing binaries)
./package-release.sh --version=1.2.0 # Set version numberThe output archive is fully portable — no brew, no npm, no Xcode needed on the target machine. The bundled launch.sh auto-detects and uses the included Node.js runtime.
MSVC error C2589: illegal token on right side of '::'
This happens when Windows.h defines min/max as macros, which collide with std::min/std::max. The CMakeLists.txt should already define NOMINMAX — if you're seeing this, pull the latest version.
If building manually, add -DCMAKE_CXX_FLAGS="/DNOMINMAX /DWIN32_LEAN_AND_MEAN" to your cmake command.
npm install fails on Node.js 24+
Node.js 24 is too new for some dependencies. Use Node.js 22 LTS:
nvm install 22
nvm use 22build.cmd can't find vcvars64.bat
The build script uses vswhere.exe to find Visual Studio automatically. If it fails:
- Make sure you have Visual Studio 2022 (any edition) or Build Tools installed
- Ensure the "Desktop development with C++" workload is selected
- As a fallback, open a Developer Command Prompt for VS 2022 and build manually (see Build the Engine above)
"ace-server.exe not found" after building with Ninja
Ninja is a single-config generator — binaries go directly in engine/build/ instead of engine/build/Release/. The server auto-detects both locations. If you still see this error, pull the latest version or set ACESTEPCPP_EXE in your .env file to point to the binary.
CUDA error: "The CUDA Toolkit directory does not exist"
MSBuild can't find the CUDA Toolkit. Check:
- The
CUDA_PATHenvironment variable is set (e.g.C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.x) - You selected "Visual Studio Integration" during the CUDA Toolkit install — without this, MSBuild has no
$(CudaToolkitDir)macro - Restart your terminal after installing or modifying CUDA paths
"The input line is too long" when running build.cmd
Running build.cmd multiple times in the same terminal causes vcvars64.bat to append duplicate entries to %PATH% until it exceeds the Windows 8,192-character limit.
Fix: Close the terminal and open a fresh one. The build scripts now guard against this, but older versions don't — pull latest.
Build errors persist after fixing environment
If you changed CUDA versions, VS editions, or environment variables, the CMake cache may contain stale configuration:
rd /s /q engine\build
engine\build.cmdThe CMakeCache.txt is only generated once — build.cmd skips reconfiguration if it already exists.
macOS: "operation not permitted" or app blocked by Gatekeeper
Since the release binaries are unsigned, macOS may quarantine them. Remove the quarantine flag:
xattr -cr /path/to/HOT-Step-CPP-v1.0.0-macOS-arm64/This only needs to be done once after extraction.
macOS: Metal compilation errors during engine build
Ensure you have Xcode (not just Command Line Tools) and run the first-launch setup:
sudo xcodebuild -runFirstLaunchIf you see errors about Metal Toolchain, these can usually be ignored — the embedded Metal library (-DGGML_METAL_EMBED_LIBRARY=ON) does not require a separate Metal Toolchain download.
- ACE-Step 1.5 — The AI music generation model by ACE Studio and StepFun
- acestep.cpp — The C++ GGML inference engine by ServeurpersoCom
- HOT-Step 9000 — The Python-based sister project with full feature support
- Alexander Allan (MDMAchine) — STORM solver plugin (adaptive STORK/DPM++3M hybrid) and MD Audio Tiled Core postprocess plugin (advanced tiled VAE decode with OLA crossfading, dual-pass merge, and DSP chain)
- ComfyUI_MusicTools — Vocal Naturalizer DSP algorithm by Jean Kassio (MIT License)
- JK-AceStep-Nodes — Audio Quality Evaluator metrics by Jean Kassio (MIT License)
- Stability AI — Stable Audio 3 (diffusion transformer + SAME-L autoencoder + T5Gemma text encoder); powers the StableStep refiner via our native ONNX/GGML conversions, distributed under the Stability AI Community License. Powered by Stability AI.
- MuScriptor — Multi-instrument music transcription model by Kyutai and Mirelo (Simon Rouard, Michael Krause, Axel Roebel, Carl-Johann Simon-Gabriel, Alexandre Défossez — arXiv:2607.08168); powers MIDI Studio via our native GGML port (code MIT, model weights CC BY-NC 4.0)
The engine component (engine/) is licensed under MIT. See engine/LICENSE for details.
A heartfelt thank you to Alexander Allan (MDMAchine) for his ongoing and generous contributions to HOT-Step — from the STORM solver and MD Audio Tiled Core postprocess plugins to the real-time VST3 monitoring UX (chain presets, live monitor transport, pause/resume/restart) and a slew of JUCE VST3 hosting crash fixes in the engine. Your work has made this project meaningfully better. 🙏
If HOT-Step is useful to you, consider giving it a star — it really helps!