README.md

---
license: mit
library_name: mlx
pipeline_tag: text-to-audio
base_model:
  - ACE-Step/acestep-v15-base
  - ACE-Step/acestep-v15-sft
  - ACE-Step/Ace-Step1.5
  - ACE-Step/acestep-v15-xl-base
  - ACE-Step/acestep-v15-xl-sft
  - ACE-Step/acestep-v15-xl-turbo
tags:
  - mlx
  - ace-step
  - music-generation
  - text-to-audio
---

# ACE-Step 1.5 MLX artifacts

MLX-native decoder weights prepared by The Patch for fast cold loading on Apple
silicon. These artifacts are intended for Carey/gary4local's hard-unload workflow:
load for one generation job, generate, then release the model and MLX cache.

## Important compatibility note

This repository contains optimized **ACE-Step decoder and conditioning weights**,
not a standalone ACE-Step pipeline. A consumer still needs the matching VAE,
text encoder/tokenizer, scheduler, and runtime code. Tensor names and convolution
layouts are native to Carey's `MLXDiTDecoder`; they are not a drop-in replacement
for the upstream PyTorch checkpoint.

## Available artifacts

| Path | Upstream source | Source revision | Dtype | Tensor data |
| --- | --- | --- | --- | ---: |
| `MLX/acestep-v15-base-f16` | `ACE-Step/acestep-v15-base` | `e432212fec32b8965a14ffa57ae653438d6abd14` | FP16 decoder / source-dtype conditioning | 4,787,749,132 bytes |
| `MLX/acestep-v15-sft-f16` | `ACE-Step/acestep-v15-sft` | `c410d249e71ea9385a7b586865e65b1473e1098d` | FP16 decoder / source-dtype conditioning | 4,787,749,132 bytes |
| `MLX/acestep-v15-turbo-f16` | `ACE-Step/Ace-Step1.5` | `19671f406d603126926c1b7e2adc169acbcade22` | FP16 decoder / source-dtype conditioning | 4,787,749,132 bytes |
| `MLX/acestep-v15-xl-base-f16` | `ACE-Step/acestep-v15-xl-base` | `220c1166efbdd9583eafcb12eb160594bbfcb241` | FP16 decoder / source-dtype conditioning | 11,611,452,824 bytes |
| `MLX/acestep-v15-xl-sft-f16` | `ACE-Step/acestep-v15-xl-sft` | `d06de46b4622f781cf07f4a013a67d591ca52819` | FP16 decoder / source-dtype conditioning | 11,611,452,824 bytes |
| `MLX/acestep-v15-xl-turbo-f16` | `ACE-Step/acestep-v15-xl-turbo` | `d4a0b288b83ebb7e25a8c0b32c573c22e134e8ee` | FP16 decoder / source-dtype conditioning | 11,611,452,824 bytes |

Each variant directory contains:

- sharded MLX-native safetensors;
- a standard `model.safetensors.index.json`;
- a `conditioning/` component with the 201 decoder-free source tensors and
  `silence_latent.pt` needed by Carey's conditioning shell;
- the exact upstream `config.json`;
- `provenance.json`, including source revision, source LFS SHA-256 values,
  converter source hashes, output hashes, tensor counts, and format version.

`manifest.json` is the machine-readable repository catalog.

## Canary validation

All six FP16 artifacts were exported from the immutable upstream revisions shown
above and independently validated against their local source checkpoints:

- 476 regular or 628 XL decoder tensors plus 1 null-conditioning tensor;
- 201 conditioning tensors plus the source silence latent;
- 1 regular or 4 XL source shards checked;
- every converted decoder tensor and all 201 conditioning tensors exactly equal;
- artifact config, index, safetensors headers, sizes, and SHA-256 values checked;
- validation peak footprint: 6.97 GB with zero swaps on the test run.

The full per-file evidence is in the variant's `provenance.json`. Consumers should
verify those hashes after download and reject unknown `format_version` values.

## Format contract

- `format`: `thepatch-ace-step-mlx`
- `format_version`: `1`
- decoder keys use `MLXDiTDecoder` parameter names
- the null-conditioning tensor is stored as
  `__acestep__.null_condition_emb`
- floating-point tensors use the dtype declared by `provenance.json`

## License and attribution

The upstream model card declares the source checkpoint under the MIT License.
This repository preserves that license and identifies the exact upstream model
and revision for every artifact. ACE-Step is developed by the ACE-Step project;
these conversions are independently prepared by The Patch.