Project Map

Project Map & Navigation — HOT-Step CPP

HOT-Step CPP is a desktop app for local AI music generation (caption + lyrics in, stereo 48 kHz audio out). It is a heavily-extended fork of acestep.cpp, a C++/GGML port of ACE-Step 1.5. Three tiers:

1. Engine — C++17/CUDA/GGML in engine/. Pipeline: LM (Qwen3 language model that emits audio_codes) → DiT (Diffusion Transformer, the flow-matching synth stage) → VAE (decodes latents to audio).
2. Server — Node/TypeScript/Express/better-sqlite3 in server/src/. Orchestrates the engine, owns SQLite and files, serves the UI.
3. UI — React 19/Vite/Zustand/Tailwind in ui/src/. One component folder per "studio" (feature area).

When to use this skill

• "Where is the code for X?" / "Which file handles Y?"
• Triaging a bug report: deciding whether the fault is UI, Node server, or C++ engine.
• Tracing a request end-to-end (browser → Express → ace-server → audio file).
• Onboarding to any unfamiliar feature before editing it.

Golden rules (hard constraints — each prevents expensive damage)

1. C++ changes: rebuild with .\dev-rebuild.bat at repo root, NEVER engine\build.cmd directly, under any circumstances. WHY: you cannot reliably tell whether the app is running; the Node server auto-respawns ace-server.exe on crash (server/src/index.ts:284-308); killing the engine mid-run causes an infinite respawn + file-lock loop that blocks the build. dev-rebuild.bat POSTs /api/shutdown, waits for the process (force-kills at 10 s), then builds. It does NOT relaunch — restart it yourself with .\dev.bat (detached) and work at http://localhost:3000. LAUNCH.bat is the end-user prod path; agents do not run it. Recompile immediately after editing any engine/src/ or engine/tools/ file.
2. NEVER cmake --build . --clean-first unless the GGML/CUDA layer itself changed. WHY: CUDA kernel recompilation takes 20+ minutes. For stale .obj issues delete only engine\build\acestep-core.dir\ and engine\build\Release\acestep-core.lib.
3. Engine HTTP/API changes go in engine/tools/hot-step-server.cpp, NOT engine/tools/ace-server.cpp. WHY: upstream ace-server.cpp is kept as reference and is NOT compiled — the ace-server binary is built from hot-step-server.cpp (engine/CMakeLists.txt:416-419). Edits to ace-server.cpp silently do nothing.
4. Don't npm run build during dev. Type-check with npx tsc --noEmit (run in server\ and ui\). Only build before user testing.
5. Git: all work on master, no branches. Never git add -A or git add -f (re-adds gitignored .agents/, checkpoints/, node_modules/). Stage explicit paths. Push requires explicit user approval. Commit locally often. Any pushed v* tag triggers a full multi-platform CI release build — use a -CI-Test suffix for throwaway tags.
6. Three fork-hook files break on upstream sync (see Failure signatures). After any sync run powershell -File engine\verify-hooks.ps1. The pipeline-synth-ops.cpp hook loss is SILENT — it compiles but all solvers/schedulers/guidance go dead.
7. Don't visually verify UI with a browser agent — ask the human user. Browser agent is fine for API-only checks.
8. Node 20 to 24 LTS, 24 recommended. The engines field enforces <25.
9. PowerShell is the shell: use ; not && (unless pwsh 7 chaining). Windows 11 environment.

Process / port topology

dev.bat (agents — run detached, app at http://localhost:3000)
  (LAUNCH.bat = end-user prod launcher; agents don't use it)
  └─ Node server  server/src/index.ts → Express :3001 (host 0.0.0.0, config.ts:186-187)
       ├─ serves prebuilt ui/dist/ with SPA fallback (index.ts:123-140)
       ├─ /api/* routes → SQLite server/data/hotstep.db
       ├─ /audio → server/data/audio/, /references → server/data/references/ (index.ts:98-121)
       └─ spawns child: ace-server.exe (C++ engine) on 127.0.0.1:8085 (config.ts:102-103)
Dev mode adds Vite on :3000 (HMR); vite.config.ts proxies /api, /audio, /references → 127.0.0.1:3001.
tsx watch auto-restarts the Node server on server-code changes.

• Engine spawn args built in index.ts:166-213: --models --host --port, plus conditional --adapters, --keep-loaded, --noise-profile, --draft-lm (deliberately disabled by default — config.ts:117-122), --vae-chunk, --vae-overlap.
• Crash respawn limiter (index.ts:284-308): abnormal exit → restart after 3 s; ≥3 crashes in 30 s → give up, engine marked not-ready ("check logs for missing DLLs").
• Portable-mode first launch downloads cuBLAS/cudart DLLs from HuggingFace before starting the engine (index.ts:318 onward).
• Config comes from .env at repo root, auto-bootstrapped from .env.example (config.ts:20-30). Settings UI can only edit whitelisted EXPOSED_ENV_KEYS (config.ts:265-286); keys in RESTART_REQUIRED_KEYS (config.ts:289-294) never hot-apply; the rest hot-reload via reloadEnvConfig() (config.ts:300).

Request path: browser → engine (main generation)

Key term: AceRequest — the JSON request object sent to the engine, typed at server/src/services/aceClient.ts:38-151 (caption/lyrics/bpm/seed, LM sampling params, DiT params like inference_steps/guidance_scale/scheduler, model routing, adapter fields, plugin_params, streaming fields). aceReq in code = the instance of this object for the current job.

1. UI: ui/src/components/create/CreatePanel.tsx + ui/src/stores/globalParamsStore.ts (Zustand store holding all generation params) → ui/src/services/api.ts (thin fetch wrapper, base /api) → POST /api/generate.
2. Orchestrator: server/src/routes/generate.ts (~1550 lines). Jobs live in an in-memory jobs Map (generate.ts:79) with a serial queue. Inside runGeneration (generate.ts:173):
   • translateParams (services/generation/translateParams.ts) converts UI params → AceRequest.
   • LM phase: aceClient.submitLm (generate.ts:303); results cached by seed+params in services/generation/lmCache.ts.
   • CRITICAL "sideband" gotcha (generate.ts:312-328): server-only fields (adapter_runtime_quant, rebase, plugin_params, …) — the "sideband" = params the Node server adds that are not part of the C++ LM struct — do NOT survive the /lm round trip. Synth requests are rebuilt from the original aceReq plus only the LM-generated fields (audio_codes, caption, lyrics, bpm, duration, keyscale, timesignature). Never whitelist-echo the LM response.
   • Source audio/latent loading for cover/repaint/seed tasks (generate.ts:449-478, services/generation/sourceAudio.ts, sourceLatentCache.ts).
   • Per-track synth: aceClient.submitSynth or submitSynthMultipart when binary latents/audio are attached (generate.ts:823-826).
   • Optional Whisper lyric transcription (generate.ts:940+, services/whisperTranscribe.ts); auto-trim silence (generate.ts:1057-1094, services/autoTrim.ts).
   • Post-processing chain runPostProcessingChain (services/generation/postProcessing.ts:70), fixed order: quality-check(unmastered) → PP-VAE re-encode → Spectral Lifter → Vocal Naturalizer → gain offset → VST chain → Mastering → LUFS normalize → quality-check(mastered) (postProcessing.ts:105-309).
3. Engine client: services/aceClient.ts wraps every engine endpoint. The engine is single-threaded httplib — during DiT/VAE/adapter compute it cannot answer HTTP at all. Timeouts are deliberately generous: 15 s quick / 30 s poll / 300 s result fetch (aceClient.ts:17-19). A "hung" health check mid-generation is normal.
4. Progress: UI polls GET /api/generate/status/:id; live log lines via routes/logs.ts (pushLog/subscribeLines, logs.ts:34,49).
5. Watchdogs in pollUntilDone (generate.ts:102-140): no progress for 2 min → cancel + fail as stalled; wall-clock timeout clamped 5–120 min, default 45.
6. Engine job model: POST /lm or /synth returns a job id; poll GET /job?id=; fetch result via POST /job. Node job ids ≠ engine job ids (mapped by the aceJobId field, generate.ts:47).

Engine HTTP endpoints (engine/tools/hot-step-server.cpp:2704-3535): POST /lm /synth /understand /vae /warm /job /models/unload /pp-vae-reencode /supersep/separate /supersep/recombine /spectral-lifter; GET /health /props /logs /jobs /job /plugins /vram /models/loaded /supersep/progress /supersep/result /supersep/serve / (embedded webui).

Feature → files map (route ⇄ service ⇄ UI ⇄ engine)

API mounts are all registered in server/src/index.ts:72-95. Route files in server/src/routes/, services in server/src/services/, UI folders in ui/src/components/.

UI views (ui/src/App.tsx:99-114): default create, plus insta-gen, lyric-studio, cover-studio, stem-studio, stem-builder, song-builder, repaint, library, settings; overlay panels for assistant and terminal. Zustand stores in ui/src/stores/: globalParamsStore, playbackStore, audioGenQueueStore, streamingStore, vstChainStore, abCompareStore, discoStore.

Engine source map: full per-subsystem table in reference.md. Fast rules: LM phase → engine/src/pipeline-lm.cpp / qwen3-lm.h; DiT synth → pipeline-synth*.cpp / dit.h; all solver/scheduler/guidance routing → hot-step-sampler.h (upstream dit-sampler.h is bypassed); adapters → adapter-merge.h / adapter-runtime.h; VAE → vae.h / vae-ort.h; HTTP server → engine/tools/hot-step-server.cpp.

Plugins: solvers (21) / schedulers (9) / guidance (7) are hot-loadable Lua files in engine/plugins/{solvers,schedulers,guidance}/; the registry also scans repo-root plugins/ as a project overlay (engine/src/lua-plugin-registry.h:35-50), which holds postprocess/ (md_audio_tiled). Drop a .lua in the right subdir → appears in UI next launch, no C++ rebuild. Adding a solver/scheduler/guidance = write a Lua plugin, never edit dit-sampler.h. Guide: docs/dev/plugins-authoring.md. Native headers in engine/src/solvers|schedulers|guidance/ are legacy — new work goes in Lua.