ACE-Step 1.5 WebGPU

An independent, browser-native TypeScript/WebGPU implementation of ACE-Step 1.5 inference. Generate 48 kHz stereo music directly in a browser using official Hugging Face checkpoints, without a converter or model mirror.

The runtime supports Turbo, SFT and Base models (2B and XL), Qwen text and lyric conditioning, Oobleck VAE encoding/decoding, repaint, cover, stem tasks, inference adapters, and optional 5 Hz LM planning.

Experimental: GPU arithmetic is covered by CPU and upstream fixtures, with opt-in real-checkpoint browser tests. Complete audio and latent parity with native inference remains unverified. Use a browser with WebGPU support and a capable GPU. Model downloads are several gigabytes; longer audio and larger model families need more memory.

Try it in production with Zeon Studio.

Read the system requirements before downloading a checkpoint: plan for at least 4 GB VRAM for 2B models and 12 GB for XL (4B) models. The runtime streams DiT weights one layer at a time and releases them after use.

Engine documentation

Start with getting started, or browse the engine documentation for generation, audio editing, model selection, language models, adapters and the API reference. The example page also includes a copyable quick-start guide.

Run the API explorer

Requires Node.js 22.20+ or 24.12+. Node.js 23 and Node.js 22 before 22.20 are unsupported: npm ci prints EBADENGINE warnings and the development tools may fail. Check your version with node -v before installing dependencies.

• With nvm, run nvm install and nvm use in this directory. The .nvmrc selects Node.js 22.23.3.
• With Homebrew, install Node.js 24 LTS with brew install node@24, then put it on your PATH with brew unlink node && brew link --overwrite --force node@24.

npm ci
npm run example

The example app lives in example/. Its download stage shows the active model file and live bytes for each request.

The developer API explorer exposes the methods and inputs supported by the package, with method tabs, parameter documentation, live TypeScript previews, PCM WAV uploads, source-region editing, LM planning, inference adapters, a local model cache, generation progress, cancellation, and WAV playback/download. Try the demo at ace-step-webgpu.zeon.net.

Use the npm package

npm install @zeon.net/ace-step-webgpu
# TypeScript applications also need WebGPU declarations:
npm install --save-dev @webgpu/types

import { AceStepWebGpu, requestAceDevice } from "@zeon.net/ace-step-webgpu";

const context = await requestAceDevice({ powerPreference: "high-performance" });
const engine = await AceStepWebGpu.create({ device: context.device });
try {
  const result = await engine.generate({
    prompt: "Warm acoustic piano with gentle lo-fi drums",
    lyrics: "[Instrumental]",
    durationSeconds: 5,
    seed: 42,
  });
  const audio = new Audio();
  const url = result.createAudioUrl();
  audio.src = url;
  // Connect playback to a user action in your application.
  document.querySelector("button")?.addEventListener("click", () => void audio.play());
  // Revoke the URL when your application no longer needs it.
} finally {
  engine.dispose();
  context.destroy();
}

Add @webgpu/types to your TypeScript compilerOptions.types. Core helpers such as huggingFaceSource, encodeWav, sftSchedule and turboSchedule are exported from @zeon.net/ace-step-webgpu/core.

The root export includes AceStepWebGpu, requestAceDevice, inspectWebGpuSupport, and lower-level GPU components. The engine supports generate, repaint, repaintAudio, cover, extract, lego, complete, encodeAudio, encodeAudioCodes, decodeAudioCodes, adapter loading, loadLm and planWithLm. See the TypeScript declarations for the complete inputs. The assembled package bundles the core and GPU workspaces and has no workspace imports at runtime.

Development

Use Node.js 22.20+ or 24.12+ (see Run the API explorer). The .nvmrc and .node-version files select Node.js 22.23.3.

npm ci
npm run check
npm run package
npm pack ./build/package --dry-run

npm run check runs formatting, lint, type checks, unit tests and the production studio build. npm run test:browser additionally requires Chrome and a real WebGPU device. The other test:browser:* scripts download official checkpoints and test individual inference paths.

License

MIT for the runtime. See LICENSE and NOTICE.md. Checkpoint licenses apply independently and remain the responsibility of their publishers.