Ace-Step-1.5-ScragVAE

ScragVAE — Improved VAE Decoder for ACE-Step 1.5

A fine-tuned AutoencoderOobleck decoder with an intent to improve audio fidelity for the ACE-Step 1.5 music generation pipeline. Drop-in compatible with all existing ACE-Step DiT checkpoints.

What is this?

ACE-Step 1.5 uses a VAE (Variational Autoencoder) to convert between audio waveforms and the latent space that the DiT diffusion model operates in. The original VAE decoder attenuates high-frequency content, resulting in audio with reduced clarity and detail above 6kHz.

ScragVAE retrains the decoder half of the VAE to better reconstruct upper harmonics, transient detail, and spectral "air" — while keeping the encoder frozen so all existing DiT models remain fully compatible.

Benchmarks

Objective spectral analysis comparing ScragVAE vs the original ACE-Step 1.5 VAE decoder on identical latents (same seed, same DiT output):

Summary: ScragVAE preserves significantly more high-frequency content (especially 10–20kHz) and has dramatically better dynamic range, resulting in clearer vocals, crisper transients, and more natural-sounding audio.

Files

Usage

Python / Diffusers

ScragVAE is a drop-in replacement for the ACE-Step VAE. Replace the VAE checkpoint path in your pipeline:

from diffusers import AutoencoderOobleck

# Load ScragVAE instead of the default VAE
vae = AutoencoderOobleck.from_pretrained("scragnog/Ace-Step-1.5-ScragVAE")

# Use with your existing ACE-Step pipeline
# (replace the vae in your pipeline config or checkpoint directory)

Or manually swap the decoder weights in an existing setup:

import torch
from safetensors.torch import load_file

# Load ScragVAE weights
scrag_weights = load_file("diffusion_pytorch_model.safetensors")

# Only decoder.* keys differ — encoder.* are identical to the original
decoder_keys = {k: v for k, v in scrag_weights.items() if k.startswith("decoder.")}
your_vae.load_state_dict(decoder_keys, strict=False)

acestep.cpp / HOT-Step CPP

Place scragvae-BF16.gguf in your models directory alongside the other GGUF files:

models/
├── acestep-v15-turbo-BF16.gguf    # DiT
├── acestep-5Hz-lm-BF16.gguf       # LM
├── Qwen3-Embedding-BF16.gguf      # Text encoder  
├── vae-BF16.gguf                  # Original VAE
└── scragvae-BF16.gguf             # ← ScragVAE (add this)

The engine auto-discovers all VAE GGUFs at startup. In HOT-Step CPP, select ScragVAE from the VAE Decoder dropdown in the Models & Adapters panel.

For acestep.cpp's built-in web UI or API, pass "vae_model": "scragvae-BF16.gguf" in your synth request JSON.

Converting from safetensors to GGUF yourself

If you need to reconvert (e.g. after further fine-tuning):

python engine/convert.py  # scans checkpoints/ and outputs to models/

Or use the converter directly:

from convert import convert_model
convert_model("scragvae", "/path/to/scragvae/", "scragvae-BF16.gguf", "vae")

Architecture

ScragVAE uses the same AutoencoderOobleck architecture as the original ACE-Step VAE — no structural changes. Only the decoder weights differ.

Compatibility

• ✅ All ACE-Step 1.5 DiT checkpoints (turbo, SFT, XL)
• ✅ All LoRA/adapter models
• ✅ Both Python (PyTorch/Diffusers) and C++ (ggml/acestep.cpp) runtimes
• ✅ Encoder weights are identical — no retraining of upstream models needed

Training

Strategy

Freeze encoder → train decoder only. The DiT operates in latent space; by only improving the decoder, all existing DiT checkpoints remain compatible without retraining.

Two-phase training

Key changes vs original training

• Disabled perceptual weighting in the spectral loss — the original's perceptual curve de-emphasizes high frequencies, actively suppressing HF reconstruction
• Increased adversarial weight (0.5 → 1.5) — forces the decoder to produce more realistic spectral detail
• Reduced feature matching (5.0 → 3.0) — less over-smoothing from discriminator feature constraints
• Added L1 time-domain loss (0.05) — preserves transient attacks and waveform fidelity
• Added 4096-point FFT to discriminator — gives the discriminator explicitly better resolution for harmonic content in the 2–8kHz range
• Added multi-resolution mel-spectrogram loss at 4 scales — captures perceptually relevant frequency content

Hardware

• GPU: NVIDIA RTX 5090 (32GB)
• Training time: ~8 hours total (Phase 1 + Phase 2)
• Framework: PyTorch + stable-audio-tools

License

MIT License — same as ACE-Step 1.5.

Citation

If you use ScragVAE in your work:

@misc{scragvae2026,
  title={ScragVAE: Improved VAE Decoder for ACE-Step 1.5},
  author={Scragnog},
  year={2026},
  url={https://huggingface.co/scragnog/Ace-Step-1.5-ScragVAE}
}

Acknowledgements

• ACE-Step 1.5 — the base model and VAE architecture
• stable-audio-tools — training framework
• acestep.cpp — C++ inference engine with GGUF support