Suno-style web UI for a self-hosted MiniMax-Music3 inference server
TypeScript ai-musicdiffusersdockerexpressminimaxminimax-musicmusic-generationreactself-hostedsgl-omnisunotailwindcsstext-to-musictypescriptvite
"""MiniMax Music 3 on a single GPU, behind the same HTTP API MiniMax's own server exposes.
Upstream serves this model with `sgl-omni serve --model-path MiniMaxAI/MiniMax-Music3`, which
needs two CUDA GPUs. This script serves the identical request shape from the diffusers pipeline,
which fits on one card (~24 GB), so a client written against either works against both:
POST /v1/audio/speech
{"model": "minimax_ttm",
"input": "[Verse]\\n...", # lyrics, section tags on their own lines
"instructions": "Global Metadata: ...", # style description
"response_format": "wav",
"seed": 7,
"max_new_tokens": 750, # length in 25 fps frames; 9000 = 360 s cap
"stream": false}
-> 44.1 kHz stereo 16-bit WAV bytes
POST /v1/audio/speech with "stream": true (this server only; upstream rejects it)
-> text/event-stream: `progress` {stage: semantic|denoise, done, total, secondsRendered},
`audio` {pcm: base64 int16 stereo, samples, sampleRate, channels} per denoised window
(or once at the end when "stream_audio": false), then `done` {seed, sampleRate, channels}
or `error` {message}. Disconnecting cancels the job.
GET /v1/models -> the one model
GET /health -> 200 {"status":"ready","capabilities":["stream"]} once loaded, 503 while loading
Requests are rendered one at a time; generation is ~3x slower than realtime on an RTX 3090.
pip install -r requirements.txt
python server.py --host 127.0.0.1 --port 7862
"""
import argparse
import asyncio
import base64
import hmac
import io
import json
import queue
import threading
import time
import uuid
import soundfile as sf
import torch
from diffusers import ComponentsManager, ModularPipeline
from fastapi import FastAPI, Header, HTTPException, Request, Response
from fastapi.responses import StreamingResponse
from pydantic import BaseModel, Field
REPO = "MiniMaxAI/MiniMax-Music3"
FRAME_RATE = 25 # acoustic frames per second — the unit max_new_tokens counts in
MAX_FRAMES = 9_000 # the model's hard cap: 360 s
DEFAULT_FRAMES = 1_500 # 60 s, when a request omits max_new_tokens
STATE = {"ready": False, "status": "loading pipeline", "hooks": False}
QUEUE = queue.Queue()
PIPE = None
ARGS = None
CAPABILITIES = ["stream"] # extras beyond upstream's API; the UI probes /health for them
CURRENT = {"job": None} # the job on the GPU right now; the hooks below read it
SEMANTIC_EVERY = 25 # frames between semantic progress events (= 1 s of audio)
class _Cancelled(Exception):
"""Raised inside the pipeline when the streaming client went away."""
def _emit(job, event, payload):
if job is not None and job["events"] is not None:
job["events"].put((event, payload))
def _check_cancel(job):
if job is not None and job["cancelled"]:
raise _Cancelled()
def _cancel_job(job):
with job["lock"]:
if job["completed"]:
return False
job["cancelled"] = True
return True
def _install_progress_hooks(pipe):
"""Best-effort taps into the diffusers pipeline for real progress + per-window audio.
Cancellation checks run for all jobs; only streaming jobs receive progress and audio."""
from diffusers.modular_pipelines.minimax_music3 import decoders as _dec
from diffusers.modular_pipelines.minimax_music3 import denoise as _dn
def lm_hook(module, args, kwargs, output): # one call = prefill, then one per generated frame
job = CURRENT["job"]
if job is None:
return
_check_cancel(job)
job["frames"] += 1
n = job["frames"] - 1
if n % SEMANTIC_EVERY == 0 or n >= job["max_frames"]:
_emit(job, "progress", {"stage": "semantic", "done": min(n, job["max_frames"]),
"total": job["max_frames"], "secondsRendered": 0.0})
pipe.language_model.model.register_forward_hook(lm_hook, with_kwargs=True)
Loop = _dn.MiniMaxMusic3ChunkLoopWrapper
orig_progress_bar, orig_loop_step = Loop.progress_bar, Loop.loop_step
class _Bar: # stands in for tqdm: the denoise loop calls .update() once per step
def __init__(self, total):
self.n, self.total = 0, total
def __enter__(self):
return self
def __exit__(self, *exc):
return False
def update(self, k=1):
self.n += k
job = CURRENT["job"]
_emit(job, "progress", {"stage": "denoise", "done": self.n, "total": self.total,
"secondsRendered": job["seconds"] if job else 0.0})
def progress_bar(self, iterable=None, total=None):
job = CURRENT["job"]
if job is None or job["events"] is None or total is None:
return orig_progress_bar(self, iterable=iterable, total=total)
return _Bar(total)
def loop_step(self, components, block_state, k):
job = CURRENT["job"]
_check_cancel(job)
components, block_state = orig_loop_step(self, components, block_state, k=k)
if job is not None and job["events"] is not None and job["stream_audio"]:
latents = block_state.latent_chunks[-1]
last = k == len(block_state.chunk_starts) - 1
hop = components.latent_hop_length
with torch.no_grad():
wav = components.vocoder(latents.to(components.vocoder.dtype))
left = 0 if k == 0 else _dec._CROP_LEFT_LATENT * hop
right = 0 if last else _dec._CROP_RIGHT_LATENT * hop
wav = wav[..., left : wav.shape[-1] - right].float().clamp(-1.0, 1.0)[0] # (channels, samples)
pcm = (wav.T.cpu().numpy() * 32767.0).astype("<i2").tobytes()
job["seconds"] += wav.shape[-1] / components.sampling_rate
job["pcm"].append(pcm)
_emit(job, "audio", {"pcm": base64.b64encode(pcm).decode("ascii"), "samples": int(wav.shape[-1]),
"sampleRate": int(components.sampling_rate), "channels": int(wav.shape[0])})
return components, block_state
Loop.progress_bar, Loop.loop_step = progress_bar, loop_step
class SpeechRequest(BaseModel):
"""Upstream's request body. Unknown fields are ignored, so an OpenAI-shaped client that
sends `voice`, `speed` and friends still works."""
model: str = Field("minimax_ttm", description="Ignored; one model is served.")
input: str = Field(..., description="Lyrics. Section tags such as [Verse]/[Chorus] on their own lines.")
instructions: str = Field("", description="Music description: genre, BPM, key, vocals, arrangement.")
response_format: str = Field("wav", description="wav")
seed: int | None = Field(None, description="Omit for a random seed; the one used comes back in X-Seed.")
max_new_tokens: int | None = Field(
None, description="Length in 25 fps frames: 750 = 30 s, cap 9000 = 360 s. Default 1500 = 60 s."
)
stream: bool = Field(False, description="true (this server only) streams SSE progress + PCM windows; upstream accepts only false.")
stream_audio: bool = Field(True, description="With stream=true: false skips per-window audio events (progress only; the clip arrives in one `audio` event at the end).")
def _worker():
"""Loads the pipeline, then renders queued requests one at a time on the GPU."""
global PIPE
STATE["ready"], STATE["hooks"] = False, False
try:
print("loading pipeline (~30 s warm, minutes cold; holds ~24 GB VRAM) ...", flush=True)
if ARGS.offload:
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")
PIPE = ModularPipeline.from_pretrained(REPO, components_manager=manager)
else:
PIPE = ModularPipeline.from_pretrained(REPO)
PIPE.load_components(dtype=torch.bfloat16)
if not ARGS.offload:
PIPE.to("cuda")
_install_progress_hooks(PIPE)
STATE["hooks"] = True
STATE["ready"], STATE["status"] = True, "ready"
print("ready on http://%s:%d — %d Hz stereo" % (ARGS.host, ARGS.port, PIPE.sampling_rate), flush=True)
except BaseException as exc:
STATE["ready"], STATE["hooks"] = False, False
STATE["status"] = "load failed: %s" % exc
print("FATAL: pipeline load failed: %s" % exc, flush=True)
raise
while True:
job = QUEUE.get()
if job["cancelled"]: # client left while queued
with job["lock"]:
job["completed"] = True
job["event"].set()
QUEUE.task_done()
continue
CURRENT["job"] = job
try:
t0 = time.time()
print("[%s] %.0f s, seed %d%s" % (job["id"], job["duration"], job["seed"], " (stream)" if job["events"] else ""), flush=True)
audio = PIPE(
prompt=job["instructions"],
lyrics=job["lyrics"],
audio_duration=job["duration"],
generator=torch.Generator("cuda").manual_seed(job["seed"]),
output="audios",
)[0]
if hasattr(audio, "cpu"): # some builds return a tensor, others a numpy array
audio = audio.float().cpu().numpy()
if job["events"] is not None and not job["pcm"]: # progress-only stream, or hooks missing: whole clip in one event
pcm = (audio.T * 32767.0).astype("<i2").tobytes()
_emit(job, "audio", {"pcm": base64.b64encode(pcm).decode("ascii"), "samples": int(audio.shape[-1]),
"sampleRate": int(PIPE.sampling_rate), "channels": int(audio.shape[0])})
buf = io.BytesIO()
sf.write(buf, audio.T, PIPE.sampling_rate, format="WAV", subtype="PCM_16")
with job["lock"]:
if job["cancelled"]:
raise _Cancelled()
job["wav"] = buf.getvalue()
job["completed"] = True
_emit(job, "done", {"seed": job["seed"], "sampleRate": int(PIPE.sampling_rate), "channels": int(audio.shape[0])})
print("[%s] done in %.0f s" % (job["id"], time.time() - t0), flush=True)
except _Cancelled:
with job["lock"]:
job["error"] = "cancelled"
print("[%s] cancelled by client" % job["id"], flush=True)
except BaseException as exc:
with job["lock"]:
job["error"] = "%s: %s" % (type(exc).__name__, exc)
job["completed"] = True
_emit(job, "error", {"message": job["error"]})
print("[%s] failed: %s" % (job["id"], exc), flush=True)
finally:
CURRENT["job"] = None
if job["events"] is not None:
job["events"].put(None)
with job["lock"]:
job["completed"] = True
job["event"].set()
QUEUE.task_done()
app = FastAPI(title="MiniMax Music 3", description="Text-to-music on one GPU, upstream's API.")
@app.get("/health")
def health():
"""503 until the model is on the GPU, so process supervisors can wait it out."""
if not STATE["ready"]:
raise HTTPException(503, STATE["status"])
return {"status": "ready", "model": REPO, "capabilities": CAPABILITIES}
@app.get("/v1/models")
def list_models():
return {"object": "list", "data": [{"id": "minimax_ttm", "object": "model", "owned_by": "minimax"}]}
@app.post("/v1/audio/speech")
async def speech(req: SpeechRequest, request: Request, authorization: str = Header(None), x_api_key: str = Header(None)):
if ARGS.api_key:
supplied = x_api_key or (authorization or "").removeprefix("Bearer ").strip()
if not hmac.compare_digest(supplied.encode("utf-8"), ARGS.api_key.encode("utf-8")):
raise HTTPException(401, "bad or missing API key")
if req.response_format != "wav":
raise HTTPException(422, "response_format %r is not supported; only 'wav'" % req.response_format)
# the pipeline raises on either being blank — an instrumental still needs a [Instrumental] tag
if not req.input.strip():
raise HTTPException(422, "input (lyrics) is empty; use a bare [Instrumental] tag for no vocals")
if not req.instructions.strip():
raise HTTPException(422, "instructions (music description) is empty")
if not STATE["ready"]:
raise HTTPException(503, STATE["status"])
frames = max(1, min(int(req.max_new_tokens or DEFAULT_FRAMES), MAX_FRAMES))
job = {
"id": uuid.uuid4().hex[:8],
"instructions": req.instructions,
"lyrics": req.input,
"duration": frames / FRAME_RATE,
"seed": int(req.seed) if req.seed is not None else int(torch.randint(0, 2**31 - 1, (1,)).item()),
"wav": None,
"error": None,
"event": threading.Event(),
"lock": threading.Lock(),
"completed": False,
"events": queue.Queue() if req.stream else None,
"stream_audio": bool(req.stream_audio),
"cancelled": False,
"frames": 0,
"max_frames": frames,
"seconds": 0.0,
"pcm": [],
}
QUEUE.put(job)
if req.stream:
def events():
try:
while True:
try:
ev = job["events"].get(timeout=15)
except queue.Empty:
yield ": keepalive\n\n" # lets us notice a vanished client while queued
continue
if ev is None:
return
name, payload = ev
yield "event: %s\ndata: %s\n\n" % (name, json.dumps(payload))
finally:
_cancel_job(job)
return StreamingResponse(events(), media_type="text/event-stream",
headers={"X-Seed": str(job["seed"]), "Cache-Control": "no-cache"})
while not job["event"].is_set():
if await request.is_disconnected() and _cancel_job(job):
return Response(status_code=499)
await asyncio.sleep(0.1)
if job["error"]:
raise HTTPException(500, job["error"])
return Response(job["wav"], media_type="audio/wav", headers={"X-Seed": str(job["seed"])})
if __name__ == "__main__":
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument("--host", default="127.0.0.1", help="bind address; 0.0.0.0 exposes it beyond localhost")
ap.add_argument("--port", type=int, default=7862)
ap.add_argument("--api-key", help="require this key in Authorization: Bearer <key> or X-API-Key")
ap.add_argument("--offload", action="store_true", help="CPU-offload weights (~22 GB VRAM, slower)")
ARGS = ap.parse_args()
if ARGS.host != "127.0.0.1" and not ARGS.api_key:
print("WARNING: bound to %s with no --api-key; anyone who can reach this port can use the GPU" % ARGS.host)
threading.Thread(target=_worker, daemon=True).start()
import uvicorn
uvicorn.run(app, host=ARGS.host, port=ARGS.port, log_level="info")