Skip to content

Commit 9f55224

Browse files
maaydinclaude
maaydin
and
claude
committed
Add the browser demo, engine docs and npm packaging
- Prepare npm packaging and GitHub Pages deployment - Add the browser music demo and developer API explorer with live checkpoint download progress, model cards and step-count defaults - Add engine usage documentation, system requirements and an in-page quick start - Present Zeon Studio beside the engine usage guide - Cache Qwen embedding rows in aligned blocks and ranges of any size, so the example caches the text encoder, VAE and LM as well as DiT - Require Node.js 22.20+ or 24.12+, update to ESLint 10 and record install-script approvals Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent b6e9dd4 commit 9f55224

78 files changed

Lines changed: 8650 additions & 1524 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/check.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Check
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
check:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
- uses: actions/setup-node@v4
17+
with:
18+
node-version-file: .node-version
19+
cache: npm
20+
- run: npm ci
21+
- run: npm run check
22+
- run: npm run package
23+
- run: npm pack ./build/package --dry-run

‎.github/workflows/pages.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Deploy studio
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
11+
concurrency:
12+
group: pages
13+
cancel-in-progress: false
14+
15+
jobs:
16+
build:
17+
runs-on: ubuntu-latest
18+
steps:
19+
- uses: actions/checkout@v4
20+
- uses: actions/setup-node@v4
21+
with:
22+
node-version-file: .node-version
23+
cache: npm
24+
- uses: actions/configure-pages@v5
25+
- run: npm ci
26+
- run: npm run typecheck
27+
- run: npm run build
28+
- uses: actions/upload-pages-artifact@v3
29+
with:
30+
path: example/dist
31+
32+
deploy:
33+
needs: build
34+
permissions:
35+
pages: write
36+
id-token: write
37+
environment:
38+
name: github-pages
39+
url: ${{ steps.deployment.outputs.page_url }}
40+
runs-on: ubuntu-latest
41+
steps:
42+
- name: Deploy
43+
id: deployment
44+
uses: actions/deploy-pages@v4

‎.github/workflows/publish.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Publish npm package
2+
3+
on:
4+
push:
5+
tags: ["v*.*.*"]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
id-token: write
11+
12+
concurrency:
13+
group: npm-publish
14+
cancel-in-progress: false
15+
16+
jobs:
17+
publish:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/checkout@v4
21+
- uses: actions/setup-node@v4
22+
with:
23+
node-version: 24
24+
cache: npm
25+
registry-url: https://registry.npmjs.org
26+
- name: Use npm with trusted publishing support
27+
run: npm install --global npm@11
28+
- name: Check the release version
29+
run: |
30+
version="$(node -p 'require("./package.json").version')"
31+
if [ "$GITHUB_REF_TYPE" = "tag" ] && [ "$GITHUB_REF_NAME" != "v$version" ]; then
32+
echo "Tag $GITHUB_REF_NAME does not match package.json version $version" >&2
33+
exit 1
34+
fi
35+
if [ "$GITHUB_REF_TYPE" != "tag" ] && [ "$GITHUB_REF_NAME" != "main" ]; then
36+
echo "Manual releases must run on main" >&2
37+
exit 1
38+
fi
39+
- run: npm ci
40+
- run: npm run check
41+
- run: npm run package
42+
- run: npm pack ./build/package --dry-run
43+
- name: Publish to npm
44+
working-directory: build/package
45+
run: npm publish --access public --registry=https://registry.npmjs.org

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,12 @@ coverage/
99
!/.env.example
1010

1111
# Model material is never committed. The canonical model is the publisher's
12-
# original checkpoint (see docs/PLAN.md §21).
12+
# original checkpoint.
1313
/reference/expected/**/*.bin
1414
/reference/expected/**/*.npy
1515
/reference/expected/**/*.safetensors
1616
/models/
1717
/.cache/
1818
dist-types/
19+
20+
/build/

‎.node-version‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
23.10.0
1+
22.23.3

‎.nvmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
22.23.3

‎.prettierignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,4 @@ dist
33
coverage
44
*.tsbuildinfo
55
package-lock.json
6-
docs/PLAN.md
76
dist-types

‎README.md‎

Lines changed: 63 additions & 177 deletions
Large diffs are not rendered by default.

‎docs/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Engine documentation
2+
3+
Use `@zeon.net/ace-step-webgpu` to generate and edit music in a browser with ACE-Step 1.5. The engine loads official checkpoints from Hugging Face, runs text conditioning and diffusion on your GPU through WebGPU, and decodes the result into 48 kHz stereo audio.
4+
5+
Start with [your first generation](getting-started.md), then choose the guide for your workflow:
6+
7+
| Guide | What you will learn |
8+
| -------------------------------------------------- | ------------------------------------------------------------------------------ |
9+
| [Getting started](getting-started.md) | Install, request a GPU device, generate a track, play it and release resources |
10+
| [Generation and lifecycle](generation.md) | Prompts, lyrics, schedules, progress, cancellation, WAV export and cleanup |
11+
| [Models and capabilities](models.md) | Select Turbo, SFT or Base checkpoints and check supported tasks |
12+
| [Audio editing](audio-editing.md) | Encode a WAV, create covers, repaint regions and work with stems |
13+
| [Language models and adapters](lm-and-adapters.md) | Load a 5 Hz LM, use audio codes, and apply LoRA/LoKr/DoRA adapters |
14+
| [API reference](api.md) | Engine methods, inputs, result formats and error handling |
15+
16+
The [interactive demo](https://ace-step-webgpu.zeon.net/) shows the inputs and TypeScript calls for each method. See the library in a music application with [Zeon Studio](https://zeon.net).

‎docs/api.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Engine API reference
2+
3+
Import the engine and GPU helpers from `@zeon.net/ace-step-webgpu`. Checkpoint sources, WAV utilities, schedule constructors, error classes and other CPU helpers are exported from `@zeon.net/ace-step-webgpu/core`.
4+
5+
## Setup and state
6+
7+
| API | Purpose |
8+
| ------------------------------------------------------- | ---------------------------------------------------------------------------- |
9+
| `inspectWebGpuSupport()` | Inspect adapter capabilities without creating the inference engine |
10+
| `requestAceDevice(options?)` | Request a GPU device and return its context, support report and loss promise |
11+
| `AceStepWebGpu.create({ device, sources?, revision? })` | Create an engine; default sources are the pinned Turbo bundle |
12+
| `engine.variant` | Detected model family |
13+
| `engine.capabilities` | Supported tasks for the selected checkpoint |
14+
| `engine.lmLoaded` | Whether a language model is loaded |
15+
| `engine.loras` / `engine.useLora` | Loaded inference adapters and whether they apply |
16+
| `engine.dispose()` / `context.destroy()` | Release engine resources, then the GPU device after active calls settle |
17+
18+
## Generation and audio
19+
20+
| Method | Inputs beyond generation options | Output |
21+
| ---------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------- |
22+
| `generate(input)` | `prompt`; optional lyrics, metadata and audio codes | `AceStepGenerationResult` |
23+
| `cover(input)` | `sourceLatents` or `audioCodes`; optional `noFsq` | Generation result |
24+
| `repaint(input)` | `sourceLatents`, `startSeconds`, `endSeconds`; optional `sourcePcm` and repaint settings | Generation result |
25+
| `repaintAudio(input)` | `audio`, `startSeconds`, `endSeconds`; optional PCM rate/channels and repaint settings | Generation result |
26+
| `extract(input)` | `sourceLatents`; optional `track`; Base model required | Generation result |
27+
| `lego(input)` | `sourceLatents`; optional `track`, range and mask settings; Base model required | Generation result |
28+
| `complete(input)` | `sourceLatents`; optional `trackClasses`; Base model required | Generation result |
29+
| `encodeAudio(audio, options?)` | WAV bytes or PCM; rate, channels, planar layout, sample, seed, signal | `Float32Array` latents |
30+
| `encodeAudioCodes(latents, { signal }?)` | Encoded latents | `Int32Array` audio codes |
31+
| `decodeAudioCodes(codes, signal?)` | Code string or number array | `Float32Array` latent hints |
32+
33+
Generation task inputs require `prompt` and support `lyrics`, `durationSeconds`, `seed`, `bpm`, `keyscale`, `timeSignature`, `language`, `metas`, `instruction`, `schedule`, `guidanceScale`, `guidance`, `dcw`, `onProgress`, and `signal`. Source tasks also accept `audioCoverStrength` and `coverNoiseStrength`. See [generation](generation.md) and [audio editing](audio-editing.md) for examples and defaults.
34+
35+
## Language models and adapters
36+
37+
| Method | Purpose |
38+
| ---------------------------------------------------------- | ------------------------------------------------------------------------ |
39+
| `loadLm({ source?, signal?, onProgress? }?)` | Load a resident 5 Hz LM; defaults to pinned 1.7B |
40+
| `planWithLm(input)` | Generate metadata and optionally audio codes from `caption` and `lyrics` |
41+
| `unloadLm()` | Free LM resources |
42+
| `addLora(source, options?)` / `loadLora(source, options?)` | Load an adapter and return its name |
43+
| `setLoraScale(name, scale)` / `setLoraScale(scale)` | Adjust a named or most recently added adapter |
44+
| `setUseLora(enabled)` | Enable or disable all loaded adapters |
45+
| `removeLora(name)` / `unloadLora()` | Free one or all adapters |
46+
47+
See [language models and adapters](lm-and-adapters.md) for detailed inputs. Exact optional fields are available in the package's TypeScript declarations and editor autocomplete.
48+
49+
## Generation result
50+
51+
A result includes planar `pcm`, frame-major `latents`, `sampleRate`, `audioChannels`, `samplesPerChannel`, `durationSeconds`, and `seed`. `lm` contains the optional LM output. `encodeWav(bitDepth?)`, `toBlob(bitDepth?)`, and `createAudioUrl(bitDepth?)` export WAV audio; supported depths are 16 and 32 bits.
52+
53+
## Error handling
54+
55+
```ts
56+
import { AceStepError } from "@zeon.net/ace-step-webgpu/core";
57+
58+
try {
59+
const result = await engine.generate({ prompt: "Gentle piano", seed: 42 });
60+
console.log(result.durationSeconds);
61+
} catch (error) {
62+
if (error instanceof AceStepError) {
63+
console.error(error.code, error.message);
64+
} else {
65+
console.error(error);
66+
}
67+
}
68+
```
69+
70+
Handle cancellation separately using the operation's `AbortSignal`. Not every failure is an `AceStepError`: device loss, allocation failures, fetch errors and invalid inputs may use other error types. Check capability flags before enabling Base-only tasks, show actionable download/GPU errors, and release resources in `finally` when your workflow ends.
71+
72+
[Documentation index](README.md) · [Getting started](getting-started.md)

0 commit comments

Comments
 (0)