AceDeck

The desktop studio & control deck for ACE-Step 1.5 — generate full songs with vocals locally on your own GPU. Now with a Wan 2.1 video studio.

One-click install · Generation queue & batches · Cover / Repaint / Stems · Text-to-video · Engine control · Stability check · Claude MCP

English · Русский

⬇ Download for Windows  ·  Features  ·  Screenshots  ·  Claude MCP  ·  FAQ

---

ACE-Step 1.5 is one of the best open music generation models — a local, free alternative to Suno and Udio. But out of the box it is a Python repo, a Gradio page and a REST API. AceDeck turns it into a real desktop app: it installs the model and all dependencies with one button, starts/stops/restarts the inference server for you, lets you queue dozens of songs, shows live progress, keeps a searchable library of everything you generated and can even check whether your setup runs stably. Claude can drive all of it through the bundled MCP server.

✨ Features

🎹 Full ACE-Step 1.5 studio	Simple mode (describe the song in any language — AceDeck turns it into the English style caption ACE-Step understands, shows what the engine will hear and keeps your genre with Exact style; the LM writes the lyrics), Custom mode (style tags + lyrics with [Verse]/[Chorus] helpers), Cover / remix, Repaint a section, Stems (extract / add / complete tracks). Every engine parameter is exposed: duration, BPM, key, time signature, vocal language, DiT & LM model, thinking, steps, guidance, seed, sampler, shift, ADG, CFG interval, LM temperature/CFG/top-k/top-p, negative prompt, output format (MP3/FLAC/WAV/Opus/AAC).
🎬 Video studio new	Text-to-video with Wan 2.1 rendered by a local ComfyUI that AceDeck installs (ComfyUI + PyTorch CUDA + ~10 GB of Wan models, one click), starts and feeds. Size presets, 1–7 s clips, steps / CFG / shift / sampler, negative prompt, up to 4 LoRAs, several clips per job with their own seeds, a video queue with live frame progress and ETA, and a Clips gallery with player. Add community Wan 2.1 1.3B fine-tunes and LoRAs by pasting a Hugging Face link. Music and video share one GPU: jobs take turns and the music engine is paused and restarted automatically when VRAM is short.
✍️ AI helpers	Write with AI turns an idea into caption, lyrics, tempo and key; Enhance polishes your lyrics; Surprise me fills in a random example.
📋 Generation queue	Queue any number of jobs, set how many songs each job should produce and how many are rendered per pass. Reorder, cancel, retry (resumes where it stopped), duplicate, pause. The queue survives restarts and parks itself if the engine goes down.
📈 Live progress	Progress ring with real engine stages (composing → planning melody → rendering → decoding), per-pass progress bar, ETA and the engine's live log line.
🎧 Library & player	Every song is saved to Music\AceDeck with a JSON sidecar (caption, lyrics, seed, BPM, key, model). Grid with generative cover art, search, favorites, waveform player with seeking, Save as…, Show in folder, Reuse settings, Make a cover, Repaint a part.
⚙️ Engine control	Start · Stop · Restart · Update (git pull + uv sync) the ACE-Step API server. Live GPU/VRAM, loaded models, uptime, port, PID and a filtered live log. Attaches to an engine that is already running.
🩺 Stability check	16 checks across system, install, engine and a real stress test (several generations with timing, VRAM peak and leak detection) → verdict Stable / Unstable / Not working, score and a copyable report.
📦 One-click installer	Detects existing installs, or installs everything with progress bars per step: uv, ACE-Step source (git or zip), Python 3.12 + PyTorch CUDA 12.8, ~10 GB of models, config and a GPU self-test. Repair mode finishes partial installs.
🧠 Model manager	Download extra DiT models (SFT, Base, XL 4B, turbo variants) and LM planners (0.6B / 4B) with progress, pick the defaults.
🤖 Claude MCP	12 MCP tools so Claude Desktop / Claude Code can generate songs, manage the queue, run diagnostics and control the engine. One click adds AceDeck to Claude Desktop.
🔌 Automation API	Token-protected local HTTP API (127.0.0.1) + scripts/ctl.mjs for your own scripts.
🔄 Updates in the app	AceDeck checks GitHub Releases on start, shows what's new and installs the new version in one click (Settings → Updates) — the portable build updates itself too. The installer puts an AceDeck icon on the desktop.
🌍 English & Русский	Full UI localization with proper plural forms; follows the system language.

📸 Screenshots

Queue — live progress, ETA, batches	Library — generative covers & waveform player
Custom mode — lyrics, song & model settings	Track details — save, reuse, cover, repaint
Engine — start / stop / restart / update	Stability check — stress test & verdict
Install — one click, or reuse an existing install	Claude & MCP — one-click setup
Models — download & choose defaults	Settings
Video studio — Wan 2.1 text-to-video with a live queue	Clips — gallery with hover previews & player

🚀 Quick start

1. Download AceDeck-Setup-x.y.z.exe (installer) or AceDeck-Portable-x.y.z.exe from Releases.
2. Run it. Windows SmartScreen may warn because the build is not code-signed → More info → Run anyway.
3. On first launch AceDeck looks for an existing ACE-Step 1.5 checkout. If none is found, open Install, pick a folder and press Install ACE-Step — it downloads ~3 GB of Python packages and ~10 GB of models (≈ 5–15 min depending on your connection).
4. Press Start in the sidebar, go to Create, describe a song and hit Create. Songs land in Music\AceDeck.
5. Video: open Video engine → Install video engine (ComfyUI + PyTorch + ~10 GB of Wan 2.1 models, ≈ 5–10 min), then describe a scene in Video studio. Clips land in Videos\AceDeck.
6. New versions arrive inside the app: a badge appears in the sidebar and Settings → Updates downloads and installs them (1.0.0/1.0.1 have no updater — install 1.0.2 once by hand).

Already have ACE-Step 1.5? AceDeck auto-detects common locations (e.g. %USERPROFILE%\ACE-Step-1.5) or you can point it to any folder in Install → Use an existing installation.

💻 System requirements

	Minimum	Recommended
OS	Windows 10 / 11 x64	Windows 11
GPU	NVIDIA, 6 GB VRAM (LM disabled)	NVIDIA RTX, 12–16 GB+ VRAM
Driver	CUDA 12.8 capable (RTX 50xx needs 570+)	latest Game Ready / Studio
RAM	16 GB	32 GB+
Disk	~25 GB free	SSD
Network	first install only (~13 GB)

Measured on an RTX 5060 Ti 16 GB: engine start + model load ≈ 30 s; a 30-second song with LM planning ≈ 40 s end-to-end; a 15-second instrumental ≈ 10–16 s. Full stress test: Stable, 100/100.

Video studio (optional): +~16 GB of disk, 8 GB VRAM minimum (12 GB+ recommended). On the same RTX 5060 Ti a 2-second 832×480 clip renders in ≈ 1.5 min including ComfyUI start, a 5-second one at 30 steps in ≈ 8 min; peak VRAM ≈ 12 GB.

🤖 Control it with Claude (MCP)

AceDeck ships an MCP server, so Claude can operate your local music studio in plain language — “make 10 chill lo-fi instrumentals for my stream, 2 minutes each, and tell me where the files are”. The MCP server talks to AceDeck (not directly to ACE-Step), so jobs show up in the queue, songs land in the library, and if AceDeck is closed the server launches it automatically.

Claude Desktop — open Claude & MCP in AceDeck and click Add to Claude Desktop, then restart Claude Desktop.

Claude Code — copy the command from the same page, it looks like:

claude mcp add acedeck --scope user -e ELECTRON_RUN_AS_NODE=1 -- "C:\Users\<you>\AppData\Local\Programs\AceDeck\AceDeck.exe" "C:\Users\<you>\AppData\Local\Programs\AceDeck\resources\mcp\server.cjs"

No separate Node.js is needed — the AceDeck executable doubles as the Node runtime (ELECTRON_RUN_AS_NODE=1).

Manual config (any MCP client)

{
  "mcpServers": {
    "acedeck": {
      "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\AceDeck\\AceDeck.exe",
      "args": ["C:\\Users\\<you>\\AppData\\Local\\Programs\\AceDeck\\resources\\mcp\\server.cjs"],
      "env": { "ELECTRON_RUN_AS_NODE": "1" }
    }
  }
}

Tool	What it does
acedeck_status	Engine state, GPU/VRAM, queue summary, library size
engine_control	start / stop / restart the ACE-Step engine
generate_music	Text-to-music from a description or caption + lyrics; count songs; waits and returns file paths
transform_audio	cover (remix in a new style) or repaint (regenerate a section) of a local audio file
draft_song	LM writes caption, lyrics, BPM, key and duration — no rendering
list_queue, get_job, job_control, queue_control	Inspect / cancel / retry jobs, pause / resume / clear the queue
list_tracks	Browse generated songs with metadata and file paths
run_diagnostics	Quick check or full stress test with verdict
engine_logs	Tail of the engine log

Is it worth it if Claude could call ACE-Step directly? ACE-Step's API is stateless: no process management, no persistent queue, no library, no install/repair, and simple mode silently overrides your duration. Through AceDeck, Claude gets a managed engine with the same guarantees as the UI — and you can watch and control everything it does.

🔌 Automation API

When enabled (Claude & MCP → Automation API), AceDeck listens on http://127.0.0.1:47815. The bearer token is written to %APPDATA%\AceDeck\control.json on every start.

node scripts/ctl.mjs GET status
node scripts/ctl.mjs POST engine/start
node scripts/ctl.mjs POST jobs '{"params":{"prompt":"lo-fi, rhodes, rain","instrumental":true,"audio_duration":60},"count":5,"batchSize":1}'
node scripts/ctl.mjs GET jobs
node scripts/ctl.mjs GET "tracks?limit=10"
node scripts/ctl.mjs POST diagnostics/run '{"mode":"full"}'

Endpoints: GET /status · POST /engine/{start|stop|restart} · GET /engine/logs · GET|POST /jobs · GET /jobs/:id · POST /jobs/:id/{cancel|retry} · POST /queue/{pause|resume|clear} · GET /tracks · GET /tracks/:id · GET /diagnostics · POST /diagnostics/run · GET /models · POST /models/:name/download · POST /ai/sample. Job params accept any field of the ACE-Step /release_task body.

🛠 Build from source

git clone https://github.com/DenisHumen/ace-step-deck.git
cd ace-step-deck
npm install
node node_modules/electron/install.js   # Electron 44 downloads its binary on demand
npm run dev                              # Vite + esbuild watch + Electron
npm test                                 # unit tests (vitest)
node tests/e2e.mjs                       # end-to-end suite against the real engine (needs `npm run dev`)
npm run dist                             # typecheck + build + NSIS installer & portable exe → release/

src/
├─ main/        Electron main: engine manager, installer, queue, library, diagnostics, models, automation API
├─ preload/     contextBridge IPC
├─ renderer/    React 19 + Tailwind 4 UI (pages, components, i18n en/ru)
├─ mcp/         MCP server (bundled to out/mcp/server.cjs)
└─ shared/      types, constants, pure logic shared by all of the above
scripts/        dev runner, esbuild build, icons, screenshots, ctl.mjs
tests/          vitest unit tests + MCP smoke test

flowchart LR
  subgraph App[AceDeck]
    UI[React UI] -- IPC --> Main[Electron main]
    Main --> Q[Queue]
    Main --> I[Installer]
    Main --> D[Stability check]
    Main --> C[Automation API :47815]
  end
  Claude[Claude Desktop / Code] -- stdio --> MCP[MCP server] -- HTTP + token --> C
  Main -- spawn / stop / restart --> API[ACE-Step 1.5 API :8001]
  Q -- REST --> API
  API --> GPU[(NVIDIA GPU)]
  Q --> L[(Music/AceDeck library)]

Loading

❓ FAQ

Windows SmartScreen blocks the installer

The builds are not code-signed yet. Click More info → Run anyway, or build from source.

“vLLM backend is unavailable on Windows because Triton is not installed”

Harmless. AceDeck automatically uses the PyTorch backend for the language model when Triton is missing (Settings → LM backend).

Generation is slower than expected on a 16 GB card

ACE-Step enables CPU offload below 16 GB and many 16 GB cards report 15.9 GB. Settings → CPU offload → Off keeps everything in VRAM (~1.5× faster in our test, peak ≈ 15 GB) — switch back to Auto if you hit out-of-memory on long songs.

Simple mode ignores my duration in the official UI

ACE-Step's own sample mode overwrites duration/BPM/key with the LM's choice. AceDeck composes first (/v1/create_sample) and then renders with your settings, so the duration you pick is respected.

Simple mode gives a different genre than I described

ACE-Step's music model understands English captions, and its language model tends to retell long non-English descriptions as generic pop/hip-hop. Since 1.0.2 AceDeck translates genres, instruments, mood and tempo from your description into a short English caption (see Engine hears under the prompt), stops the LM from rewriting it, and with Exact style on (default) the music model follows that caption directly. Name the genre and the main instruments; very niche sub-genres are still limited by what the model knows. Turn Exact style off to let the LM plan the arrangement (richer structure, looser style).

Hugging Face is blocked in my country

The ACE-Step downloader automatically falls back to ModelScope.

Port 8001 is already used

Change the API port in Settings. If another ACE-Step server is already running on that port, AceDeck simply attaches to it.

How do I uninstall?

Use “Add or remove programs”. The ACE-Step folder (with ~17 GB of Python packages and models) is yours — delete it manually if you no longer need it. Songs stay in Music\AceDeck.

Which video models can I use?

Any Wan 2.1 1.3B text-to-video checkpoint in ComfyUI format (a single .safetensors) and Wan 2.1 1.3B LoRAs. Paste the Hugging Face link on Video engine → Add a model or import a file you already have. Model licenses are the model authors' — check them before you use or share the output.

🗺 Roadmap

• macOS (Apple Silicon / MLX) and Linux builds
• LoRA training UI
• In-app updates
• Code signing
• Playlists, tags and export to DAW stems
• Multi-GPU / multi-slot model switching
• Text-to-video (Wan 2.1)
• Image-to-video and video MCP tools

🙏 Credits

• ACE-Step 1.5 by the ACE-Step team — the model and inference server that make all of this possible.
• Wan 2.1 by the Wan team and ComfyUI — the video model and the engine that runs it.
• Design inspired by Dribbble/Pinterest concepts: the “ElevMuse — AI music generator” dashboard and the “AI Mastering Engine” status panel.
• Built with Electron, React, Tailwind CSS, wavesurfer.js, Lucide, Motion and the MCP TypeScript SDK.

📄 License

MIT © 2026 DenisHumen. AceDeck is an independent project and is not affiliated with the ACE-Step team. Generated music and video are subject to the licenses of the models you use and your local laws.

_{If AceDeck saves you time, a ⭐ helps other people find it.}