README.md

---
title: abv1 sa3 engine
emoji: 🎛️
colorFrom: indigo
colorTo: pink
sdk: gradio
sdk_version: 6.14.0
app_file: app.py
pinned: false
license: other
short_description: Stable Audio 3 text/audio-to-audio + headless API
suggested_hardware: zero-a10g
models:
- stabilityai/stable-audio-3-medium
- stabilityai/stable-audio-3-small-music
---

# abv1 · SA3 engine

Shared Stable Audio 3 backend for the abv1 music-AI demo apps: interactive
text→audio and audio→audio for the demo pages, plus a headless API the
trend-radio cron uses to batch 15 tracks every 2 hours.

**Hardware: ZeroGPU** (set in Space settings → Hardware → ZeroGPU; the
`suggested_hardware` key above is only a hint).

## Models

| key | repo | max seconds | notes |
|---|---|---|---|
| `small-music` | `stabilityai/stable-audio-3-small-music` | 120 | 0.6B, seconds per gen — the batch default |
| `medium` | `stabilityai/stable-audio-3-medium` | 180 | general audio, higher quality |

Both repos are gated. The Space needs an `HF_TOKEN` secret from an account that
has accepted their licences.

## UI

- **Text → audio** — model, prompt, negative prompt, seconds, steps, CFG, seed.
- **Audio → audio** — upload a file, set how far to travel from it
  (`init_noise_level`: low = stay close, high = go wild), then the same params.

UI generations are **not** token-gated: visitors spend their own ZeroGPU quota.

## Headless API

Two endpoints, registered off hidden components. Both return
`[audio_file, meta_json]` where `meta` is
`{ok, seed, model_variant, seconds, steps, cfg_scale, sample_rate, gen_wall_s, stub}`.

```python
from gradio_client import Client, handle_file

c = Client("kalamishere/audiogen", token=HF_READ_TOKEN)

# text → audio
path, meta = c.predict(
    SA3_API_TOKEN, "small-music",
    "driving techno, rolling hats, acid arp, 132 BPM", "",
    30, 8, 1.0, -1,
    api_name="/generate",
)

# audio → audio
path, meta = c.predict(
    SA3_API_TOKEN, "small-music", handle_file("loop.wav"),
    "same groove but dubbier", "", 0.4,
    30, 8, 1.0, -1,
    api_name="/generate_a2a",
)
```

Argument order matters (positional):

- `/generate` — `token, model_variant, prompt, negative_prompt, seconds, steps, cfg_scale, seed`
- `/generate_a2a` — `token, model_variant, init_audio, prompt, negative_prompt, init_noise_level, seconds, steps, cfg_scale, seed`

`seed = -1` picks a random one; the seed actually used comes back in `meta`.
Inputs are clamped server-side (seconds per-model cap, steps 1–100, cfg 0–15).

### Token

Set the `SA3_API_TOKEN` secret to gate the API. **If it is unset the API is
open** — fine for dev, not for a public Space.

## Local development

No weights, no torch — stub mode synthesizes a placeholder WAV so the whole app
and both endpoints can be exercised on a laptop:

```bash
SA3_STUB=1 SA3_API_TOKEN=test python app.py   # needs only gradio, numpy, soundfile
```

## Deploying

See `DEPLOY.md`.

## Licence

Powered by Stability AI. Models under the Stability AI Community License — see
`NOTICE.md`. All output is AI-generated; it is not a real release by any artist.