Skip to content

Add ACE-Step 1.5 as a separate music engine (acestep15) #4232

Description

@atomantic

Problem

The Music studio's ACE-Step backend is pinned to v1 (ACE-Step/ACE-Step-v1-3.5B, ACESTEP_MODELS in server/services/pipeline/musicGen.js). ACE-Step v1.5 shipped 2026-01-28 and is the vendor's current model, but it is not selectable in PortOS.

This is not a checkpoint swap. v1.5 is a different architecture, so customModels: false + a new repo string will not work:

v1 (shipped) v1.5
Entry point ACEStepPipeline from the acestep pip package transformers AutoModel + trust_remote_code (custom_code tag)
Weights one checkpoint dir, package auto-downloads to ~/.cache/ace-step HF repo ACE-Step/Ace-Step1.5 — a multi-component tree: acestep-5Hz-lm-1.7B/ (LLM), Qwen3-Embedding-0.6B/ (text encoder), acestep-v15-turbo/ (diffusion head, ships modeling_acestep_v15_turbo.py)
Upstream support acestep/pipeline_ace_step.py absent — the only v1.5 commit in ace-step/ACE-Step adds a README link (2026-01-28); the package still ships v1 only

Because the pip package has no v1.5 path, the existing sidecar (scripts/generate_acestep.py, which imports ACEStepPipeline) cannot host it.

Decision

Ship v1.5 as a separate engine entry, exactly the way MiniMax Music 3 was added — not as a model option under the existing acestep engine.

  • New engine id acestep15, name ACE-Step 1.5. Leave the acestep entry untouched.
    • Rationale: stored track renders persist engine in their metadata, so reusing the acestep id would silently re-point historical renders at a runtime that cannot reproduce them. A distinct id keeps old renders replayable and lets both engines coexist while v1.5 settles.
  • New sibling venv ~/.portos/venv-acestep15 + INSTALL_ACESTEP15 block in scripts/setup-image-video.sh. Do not add v1.5 deps to the existing venv-acestep — v1 pins its own torch stack via the acestep package.
  • New sidecar scripts/generate_acestep15.py loading the repo with trust_remote_code=True, same RESULT:{...} / STAGE: wire protocol as the other sidecars.
  • Registry field fixedModelInstall: true (single vendor repo, like minimax-music3) so the weights get the existing "Install model" HF-download flow rather than a free-text repo field. customModels: false.
  • Add healthProbe to the new entry — required by the ENGINES healthProbe parity test.
  • Once v1.5 is proven, a follow-up can deprecate v1 in the picker. Not part of this issue.

Affected files

  • server/services/pipeline/musicGen.jsACESTEP15_MODELS + ENGINES.acestep15 entry (healthProbe, lyrics: true, duration window, fixedModelInstall)
  • server/lib/pythonSetup.jsACESTEP15_VENV_CANDIDATES / resolveAcestep15Python / ACESTEP15_VENV_DEFAULT, mirroring the venv-acestep block
  • scripts/setup-image-video.shINSTALL_ACESTEP15 block; add to the ANY_BYOV list at the top
  • scripts/generate_acestep15.py — new sidecar
  • server/services/pipeline/musicGen.js#buildSidecarArgs — arg shape for the new engine
  • Tests: server/services/pipeline/musicGen.test.js, server/routes/music.test.js

Acceptance criteria

  • ACE-Step 1.5 appears in the Music studio engine picker with its own install-runtime + install-model affordances.
  • A clean install builds ~/.portos/venv-acestep15 and the health probe passes; /api/music/engines reports ready: true only once both the venv and the weights are present.
  • Generating with engine: 'acestep15' produces a WAV in the music library with lyrics conditioning applied.
  • Existing engine: 'acestep' renders still replay against v1 — no migration of stored render metadata.
  • npm test green in server/, including the ENGINES healthProbe parity test.

Notes

Duration window: v1.5's practical ceiling needs confirming during implementation. Start at the v1 window (1–240s) and widen only if the model card supports it.

Validation of output quality (does v1.5 actually sound better on this hardware) is a human judgment call and is explicitly out of scope for the acceptance criteria above — shipping the path is the deliverable.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area:songsSong/vocal/score systemenhancementNew feature or requestin-progressClaimed and being workedplanTracked by /do:replan

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions