Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: add the Music studio with song, sound effect and edit modes (#12609)

Etherlc601438cde02
diff --git a/studio/backend/core/inference/audio_cpp_backend.py b/studio/backend/core/inference/audio_cpp_backend.py
index 19e801bcd9d..2f6b6e354d9 100644
--- a/studio/backend/core/inference/audio_cpp_backend.py
+++ b/studio/backend/core/inference/audio_cpp_backend.py
@@ -23,10 +23,13 @@ import re
import threading
import wave
from dataclasses import replace
+from pathlib import Path
from typing import Any, Optional, Tuple
from core.inference import audio_cpp_files
+from core.inference import audio_cpp_music as cm
from core.inference.audio_cpp_models import (
+ MUSIC_MAX_VARIATIONS,
AudioCppModel,
AudioCppModelError,
CloneSpec,
@@ -42,6 +45,8 @@ from core.inference.audio_cpp_server import (
AudioCppServer,
AudioCppStartCancelledError,
)
+from core.inference.audio_cpp_music import music_rules
+from core.inference.audio_task_outputs import task_outputs, wav_header
from loggers import get_logger
from utils.gpu_memory_events import invalidates_gpu_memory as _invalidates_gpu_memory
@@ -60,6 +65,12 @@ def _raise_if_cancelled(cancel_event) -> None:
raise AudioGenerationCancelledError("Audio generation cancelled")
+def _wav_seconds(path: str) -> float:
+ with wave.open(str(path)) as w:
+ rate = w.getframerate()
+ return round(w.getnframes() / rate, 3) if rate else 0.0
+
+
def _wav_sample_rate(wav_bytes: bytes) -> int:
with wave.open(io.BytesIO(wav_bytes)) as w:
return int(w.getframerate())
@@ -108,6 +119,7 @@ def model_info_fields(model: AudioCppModel) -> dict[str, Any]:
"audio_reference_text": model.clone.reference_text if model.clone else None,
"audio_required_inputs": list(model.required_inputs),
"audio_clone": clone_rules(model),
+ "audio_music": music_rules(model),
}
@@ -169,6 +181,9 @@ class AudioCppBackend:
self._model: Optional[AudioCppModel] = None
self._server: Optional[AudioCppServer] = None
self._server_lock = threading.RLock()
+ # Request-raised session options (Stable Audio max_batch); cleared when another model loads.
+ self._session_overrides: dict[str, str] = {}
+ self._status_patch: Optional[dict[str, Any]] = None
# Loading
@@ -216,6 +231,8 @@ class AudioCppBackend:
self.loading_models.add(model_name)
try:
self._ensure_downloaded(model, hf_token)
+ self._session_overrides = {}
+ self._status_patch = None
self._start_server(model)
self._model = model
self.models = {
@@ -270,7 +287,7 @@ class AudioCppBackend:
with self._server_lock:
self._stop_server_locked()
model_path = audio_cpp_files.materialize(model)
- served = _with_companions(model)
+ served = _with_session_overrides(_with_companions(model), self._session_overrides)
try:
self._server = AudioCppServer.start(
served, model_path, force_cpu = self._force_cpu, cancel_event = cancel_event
@@ -314,6 +331,8 @@ class AudioCppBackend:
audio_inputs: Optional[dict] = None,
reference_text: Optional[str] = None,
speed: Optional[float] = None,
+ music: Optional[dict] = None,
+ output_dir: Optional[str] = None,
) -> Tuple[bytes, int]:
del top_k, min_p, repetition_penalty, use_adapter
if not self.active_model_name or self.active_model_name not in self.models:
@@ -322,6 +341,17 @@ class AudioCppBackend:
if model is None:
raise RuntimeError("No active audio model")
_raise_if_cancelled(cancel_event)
+ if workflow == "music" and music is not None:
+ options = validate_options(model.options, audio_options)
+ return self._run_music(
+ model,
+ music,
+ (audio_inputs or {}).get("source"),
+ options,
+ seed,
+ output_dir,
+ cancel_event,
+ )
cloning = workflow == "clone" or bool(audio_inputs)
if cloning and model.clone is None:
raise RuntimeError(f"{model.display_name} cannot clone a voice.")
@@ -527,46 +557,12 @@ class AudioCppBackend:
options: dict,
cancel_event,
) -> bytes:
- # The Audio page's music form sends the description as instructions and the lyrics as text (the MiniMax
- # convention).
- description = str(instructions or "").strip()
- lyrics = str(text or "").strip()
- seconds = _music_seconds(max_new_tokens)
- request: dict[str, Any] = {}
- request_options: dict[str, Any] = dict(options)
- if model.family == "minimax_music3":
- if not lyrics:
- raise RuntimeError("MiniMax Music 3 needs lyrics.")
- # The caption is the input. The task route maps duration_seconds onto the duration_sec
- # option; sending both is refused as "conflicting option values", even when equal.
- request.update(
- {"text": description or lyrics, "lyrics": lyrics, "duration_seconds": seconds}
+ try:
+ request = cm.legacy_song_request(
+ model, text, instructions, _music_seconds(max_new_tokens), options, seed
)
- request_options["lyrics"] = lyrics
- elif model.family == "yue2":
- if not description:
- raise RuntimeError("YuE2 needs a style description.")
- request["text"] = lyrics or description
- request_options["style"] = description
- if lyrics:
- request_options["lyrics"] = lyrics
- # YuE2's length is its semantic token budget at 25 frames per second (default 9000, six
- # minutes), and its default floor of 200 frames would outlast a short request.
- frames = int(round(seconds * 25))
- request_options["semantic_max_tokens"] = frames
- request_options["semantic_min_tokens"] = min(200, frames)
- else:
- # A lone prompt with no description is the description.
- if not description:
- description, lyrics = lyrics, ""
- request["text"] = description
- request["duration_seconds"] = seconds
- if lyrics and model.family != "stable_audio":
- request["lyrics"] = lyrics
- if request_options:
- request["options"] = request_options
- if seed is not None:
- request["seed"] = str(int(seed))
+ except cm.MusicRequestError as exc:
+ raise RuntimeError(str(exc)) from exc
ctype, data = server.post_json(
"/v1/tasks/run",
{"model": server.model_id, "request": request},
@@ -575,6 +571,143 @@ class AudioCppBackend:
)
return _audio_from_task_response(ctype, data)
+ def take_status_patch(self) -> Optional[dict[str, Any]]:
+ patch, self._status_patch = self._status_patch, None
+ return patch
+
+ def _max_batch(self) -> int:
+ try:
+ return max(1, int(self._session_overrides.get(_MAX_BATCH_OPTION, "1")))
+ except ValueError:
+ return 1
+
+ def _server_for_batch(self, model: AudioCppModel, batch: int, cancel_event) -> AudioCppServer:
+ """The running server, restarted once with max_batch raised to the cap, so later batches
+ never reload."""
+ with self._server_lock:
+ if batch <= self._max_batch():
+ return self._running_server(model, cancel_event)
+ logger.info(
+ "audio.cpp: reloading %s with %s=%d for %d variations",
+ model.id,
+ _MAX_BATCH_OPTION,
+ MUSIC_MAX_VARIATIONS,
+ batch,
+ )
+ previous = dict(self._session_overrides)
+ self._session_overrides[_MAX_BATCH_OPTION] = str(MUSIC_MAX_VARIATIONS)
+ try:
+ self._start_server(model, cancel_event)
+ except BaseException:
+ self._session_overrides = previous
+ raise
+ rules = music_rules(model, self._max_batch())
+ if self.active_model_name in self.models:
+ self.models[self.active_model_name]["audio_music"] = rules
+ self._status_patch = {"audio_music": rules}
+ return self._server
+
+ def _run_music(
+ self,
+ model: AudioCppModel,
+ music: dict,
+ source: Optional[str],
+ options: dict,
+ seed: Optional[int],
+ output_dir: Optional[str],
+ cancel_event,
+ ) -> Tuple[bytes, int]:
+ """Every output goes to ``output_dir`` with an ``outputs.json`` manifest; the first is
+ returned."""
+ if model.task != "music" or model.music is None:
+ raise RuntimeError(f"{model.display_name} does not make music in the Music studio.")
+ mode_id = str(music.get("mode") or "song")
+ try:
+ mode = cm.song_mode(model, mode_id)
+ except cm.MusicRequestError as exc:
+ raise RuntimeError(str(exc)) from exc
+ variations = int(music.get("variations") or 1) if mode_id != "edit" else 1
+ if variations > 1 and (not mode.variations or variations > MUSIC_MAX_VARIATIONS):
+ raise RuntimeError(
+ f"{model.display_name} makes at most "
+ f"{MUSIC_MAX_VARIATIONS if mode.variations else 1} variation(s) at a time."
+ )
+ if seed is None and model.music.fixed_seed:
+ seed = cm.random_seed()
+ batch = variations if mode.variations == "batch" else 1
+ if mode_id == "edit":
+ if not source:
+ raise RuntimeError("Add a clip to edit.")
+ seconds = _wav_seconds(source)
+ else:
+ seconds = cm.clamp_seconds(mode, music.get("duration_s"))
+ try:
+ if mode_id == "edit":
+ requests = [
+ cm.edit_request(
+ model,
+ text = music.get("text") or "",
+ edit = music.get("edit") or {},
+ source = source,
+ source_seconds = seconds,
+ duration_s = music.get("duration_s"),
+ options = options,
+ seed = seed,
+ )
+ ]
+ else:
+ instrumental = bool(music.get("instrumental")) and mode.instrumental != "never"
+ takes = 1 if batch > 1 else variations
+ requests = [
+ cm.song_request(
+ model,
+ description = music.get("text") or "",
+ lyrics = "" if mode.lyrics == "unused" else (music.get("lyrics") or ""),
+ seconds = seconds,
+ options = options,
+ seed = cm.take_seed(seed, index),
+ instrumental = instrumental or mode.instrumental == "always",
+ batch = batch,
+ )
+ for index in range(takes)
+ ]
+ except cm.MusicRequestError as exc:
+ raise RuntimeError(str(exc)) from exc
+ server = self._server_for_batch(model, batch, cancel_event)
+ # The route sizes the wait from the full work (extend, continue length); the orchestrator
+ # outlasts that same budget.
+ timeout = float(music.get("timeout_s") or 0) or cm.timeout_seconds(
+ model.family, seconds, variations, server.backend == "cpu"
+ )
+ outputs: list[tuple[str, bytes, Optional[int]]] = []
+ try:
+ for index, request in enumerate(requests):
+ _raise_if_cancelled(cancel_event)
+ ctype, data = server.post_json(
+ "/v1/tasks/run",
+ {"model": server.model_id, "request": request},
+ timeout = timeout,
+ cancel_event = cancel_event,
+ )
+ take_seed = cm.take_seed(seed, index)
+ for output_id, wav in task_outputs(ctype, data):
+ name = output_id if len(requests) == 1 else f"take_{index}"
+ outputs.append((name, wav, take_seed))
+ except AudioCppRequestCancelledError:
+ self._restart_after_cancel()
+ _raise_if_cancelled(cancel_event)
+ raise
+ except AudioCppRequestError as exc:
+ from core.inference.audio_errors import AudioRuntimeError
+ raise AudioRuntimeError(
+ f"The audio runtime could not generate audio: {exc.detail}", status = exc.status
+ ) from exc
+ _raise_if_cancelled(cancel_event)
+ if output_dir:
+ _write_outputs(output_dir, outputs)
+ first = outputs[0][1]
+ return first, _wav_sample_rate(first)
+
# Unloading
@_invalidates_gpu_memory("audio unload")
@@ -616,8 +749,45 @@ def _with_companions(model: AudioCppModel) -> AudioCppModel:
return replace(model, model_options = {**model.model_options, "session_options": session})
+_MAX_BATCH_OPTION = "stable_audio.max_batch"
+_MANIFEST = "outputs.json"
+
+
+def _with_session_overrides(model: AudioCppModel, overrides: dict[str, str]) -> AudioCppModel:
+ if not overrides:
+ return model
+ session = dict((model.model_options or {}).get("session_options") or {})
+ session.update(overrides)
+ return replace(model, model_options = {**model.model_options, "session_options": session})
+
+
+def _write_outputs(output_dir: str, outputs) -> None:
+ """Bare file names only: the route refuses any path outside ``output_dir``."""
+ directory = Path(output_dir)
+ directory.mkdir(parents = True, exist_ok = True)
+ manifest = []
+ for index, (output_id, wav, seed) in enumerate(outputs):
+ name = f"{index:02d}.wav"
+ (directory / name).write_bytes(wav)
+ rate, duration = wav_header(wav)
+ manifest.append(
+ {
+ "id": str(output_id),
+ "file": name,
+ "sample_rate": rate,
+ "duration_s": duration,
+ "seed": seed,
+ }
+ )
+ (directory / _MANIFEST).write_text(json.dumps(manifest), encoding = "utf-8")
+
+
def _audio_from_task_response(content_type: str, data: bytes) -> bytes:
"""WAV bytes from ``/v1/tasks/run``: raw audio, or JSON carrying base64 audio."""
+ try:
+ return task_outputs(content_type, data)[0][1]
+ except RuntimeError:
+ pass
if content_type.startswith("audio/") or data[:4] == b"RIFF":
return data
try:
diff --git a/studio/backend/core/inference/audio_cpp_models.py b/studio/backend/core/inference/audio_cpp_models.py
index 5547499ca49..48ac7efa5c6 100644
--- a/studio/backend/core/inference/audio_cpp_models.py
+++ b/studio/backend/core/inference/audio_cpp_models.py
@@ -106,6 +106,158 @@ class CompanionModel:
session_option: str
+MUSIC_MAX_VARIATIONS = 4
+
+
+@dataclass(frozen = True)
+class MusicMode:
+ id: str # song | sfx | edit
+ lyrics: str = "unused" # required | optional | unused
+ description: str = "required" # required | optional
+ instrumental: str = "always" # toggle | always | never
+ section_case: Optional[str] = None # lower ([verse]) | title ([Verse])
+ # (min, max, default) seconds, narrowed to the spec's bounds at resolve time.
+ duration: tuple[float, float, float] = (5.0, 240.0, 30.0)
+ approximate: bool = False
+ # "batch" (one call) | "sequential" (one call each) | None (one take).
+ variations: Optional[str] = None
+ actions: tuple[str, ...] = ()
+ max_ranges: int = 0
+ max_source_s: float = 240.0
+
+
+@dataclass(frozen = True)
+class MusicSpec:
+ modes: tuple[MusicMode, ...]
+ description_option: Optional[str] = None
+ instrumental_lyrics: Optional[str] = None
+ edit_rate: Optional[int] = None
+ # The runtime's default seed is fixed, so repeat runs would be identical.
+ fixed_seed: bool = True
+ rtf: float = 4.0
+
+ def mode(self, mode_id: Optional[str]) -> Optional[MusicMode]:
+ return next((m for m in self.modes if m.id == mode_id), None)
+
+
+_STABLE_AUDIO_SONG = MusicMode("song", duration = (1.0, 120.0, 30.0), variations = "batch")
+_STABLE_AUDIO_SFX = MusicMode("sfx", duration = (1.0, 120.0, 8.0), variations = "batch")
+# Small's runtime window is 120 s (sample_size / sample_rate): a longer edit comes back cut.
+_STABLE_AUDIO_EDIT = MusicMode(
+ "edit", actions = ("inpaint", "restyle"), max_ranges = 8, max_source_s = 120.0
+)
+MUSIC_SPECS: dict[str, MusicSpec] = {
+ "ace_step": MusicSpec(
+ (
+ MusicMode("song", lyrics = "optional", instrumental = "toggle", section_case = "lower"),
+ # "continue" (the runtime's "complete") is base-only upstream; with_variant adds it.
+ MusicMode("edit", actions = ("repaint", "extend", "cover"), max_ranges = 1),
+ ),
+ instrumental_lyrics = "[Instrumental]",
+ edit_rate = 48000,
+ rtf = 2.0,
+ ),
+ "stable_audio": MusicSpec(
+ (_STABLE_AUDIO_SONG, _STABLE_AUDIO_EDIT),
+ edit_rate = 44100,
+ fixed_seed = False,
+ rtf = 1.0,
+ ),
+ "heartmula": MusicSpec(
+ (MusicMode("song", lyrics = "required", instrumental = "never"),),
+ description_option = "tags",
+ ),
+ "midashenglm_gen": MusicSpec(
+ # The spec allows 163.84 s, but the runtime drops the connection past ~81 s (2048 frames).
+ (
+ MusicMode("song", duration = (1.0, 80.0, 30.0), variations = "sequential"),
+ MusicMode("sfx", duration = (1.0, 80.0, 10.0), variations = "sequential"),
+ ),
+ rtf = 2.0,
+ ),
+ "controlfoley": MusicSpec(
+ (MusicMode("sfx", duration = (1.0, 60.0, 8.0), variations = "sequential"),),
+ rtf = 2.0,
+ ),
+ "minimax_music3": MusicSpec(
+ (
+ MusicMode(
+ "song",
+ lyrics = "required",
+ instrumental = "never",
+ section_case = "lower",
+ approximate = True,
+ ),
+ ),
+ ),
+ "yue2": MusicSpec(
+ (
+ MusicMode(
+ "song",
+ lyrics = "optional",
+ instrumental = "toggle",
+ section_case = "title",
+ approximate = True,
+ ),
+ ),
+ description_option = "style",
+ # Empty lyrics still sing; only this tag stays wordless.
+ instrumental_lyrics = "[Instrumental]",
+ rtf = 6.0,
+ ),
+}
+
+
+def _stable_audio_music(names: Iterable[str]) -> MusicSpec:
+ spec = MUSIC_SPECS["stable_audio"]
+ text = " ".join(names).lower()
+ if re.search(r"(^|[-_ /.])sfx([-_ /.]|$)", text):
+ return replace(spec, modes = (_STABLE_AUDIO_SFX,), edit_rate = None)
+ if "medium" in text:
+ # Medium generates far past Small's window; keep Studio's 240 s cap.
+ return replace(
+ spec,
+ modes = (
+ replace(_STABLE_AUDIO_SONG, duration = (1.0, 240.0, 30.0)),
+ replace(_STABLE_AUDIO_SFX, duration = (1.0, 240.0, 8.0)),
+ replace(_STABLE_AUDIO_EDIT, max_source_s = 240.0),
+ ),
+ )
+ return spec
+
+
+def _is_number(value: Any) -> bool:
+ return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def music_with_spec_bounds(
+ music: Optional[MusicSpec], raw_options: Sequence[Any]
+) -> Optional[MusicSpec]:
+ if music is None:
+ return None
+ low = high = None
+ for item in raw_options:
+ if isinstance(item, dict) and item.get("name") == "duration_sec":
+ low, high = item.get("min"), item.get("max")
+ break
+ if not _is_number(low) and not _is_number(high):
+ return music
+ modes = []
+ for mode in music.modes:
+ if mode.id == "edit":
+ modes.append(mode)
+ continue
+ lo, hi, default = mode.duration
+ if _is_number(low):
+ lo = max(lo, float(low))
+ if _is_number(high):
+ hi = min(hi, float(high))
+ if hi < lo:
+ hi = lo
+ modes.append(replace(mode, duration = (lo, hi, min(hi, max(lo, default)))))
+ return replace(music, modes = tuple(modes))
+
+
_CLONE_INPUTS = ("text", "reference", "reference_text", "language")
@@ -171,6 +323,7 @@ class AudioCppFamily:
speaks: bool = True
clone: Optional[CloneSpec] = None
companions: tuple[CompanionModel, ...] = ()
+ music: Optional[MusicSpec] = field(default = None, hash = False, compare = False)
@property
def default_server_task(self) -> str:
@@ -402,13 +555,68 @@ _FAMILY_LIST: tuple[AudioCppFamily, ...] = (
},
),
# Music generation.
+ AudioCppFamily(
+ "ace_step",
+ "music",
+ music = MUSIC_SPECS["ace_step"],
+ # The spec declares no request options; these are the ones loader.cpp reads.
+ options = (
+ _opt("bpm", "int", "Tempo in beats per minute.", min = 30, max = 300),
+ _opt("keyscale", "string", "Key and scale, e.g. A minor."),
+ _opt(
+ "timesignature",
+ "enum",
+ "Beats per bar.",
+ values = ["2", "3", "4", "6"],
+ ),
+ _opt("negative_prompt", "string", "What to avoid."),
+ _opt("sampler_mode", "enum", "Diffusion sampler.", values = ["euler", "heun"]),
+ _opt(
+ "num_inference_steps",
+ "int",
+ "Diffusion denoising steps.",
+ min = 1,
+ max = 20,
+ default = 8,
+ ),
+ _opt("guidance_scale", "float", "Diffusion guidance scale.", min = 0.0),
+ _opt("shift", "float", "Timestep shift.", min = 1.0, max = 5.0),
+ ),
+ ),
+ AudioCppFamily(
+ "stable_audio",
+ "music",
+ music = MUSIC_SPECS["stable_audio"],
+ options = (
+ _opt(
+ "sampler",
+ "enum",
+ "Diffusion sampler.",
+ values = ["pingpong", "euler"],
+ ),
+ _opt(
+ "num_inference_steps",
+ "int",
+ "Diffusion denoising steps.",
+ min = 1,
+ max = 100,
+ default = 8,
+ ),
+ _opt(
+ "guidance_scale", "float", "Classifier-free guidance scale.", min = 0.0, default = 1.0
+ ),
+ _opt("apg_scale", "float", "Adaptive projected guidance scale.", min = 0.0, default = 1.0),
+ _opt("negative_prompt", "string", "What to avoid."),
+ ),
+ ),
*(
- AudioCppFamily(name, "music")
- for name in ("ace_step", "stable_audio", "heartmula", "midashenglm_gen", "controlfoley")
+ AudioCppFamily(name, "music", music = MUSIC_SPECS[name])
+ for name in ("heartmula", "midashenglm_gen", "controlfoley")
),
AudioCppFamily(
"minimax_music3",
"music",
+ music = MUSIC_SPECS["minimax_music3"],
package = (
_minimax_package("Q4_0", "q4_0", "q8_0", "q4_0"),
_minimax_package("Q8_0", "q8_0", "q8_0", "q8_0"),
@@ -449,6 +657,7 @@ _FAMILY_LIST: tuple[AudioCppFamily, ...] = (
AudioCppFamily(
"yue2",
"music",
+ music = MUSIC_SPECS["yue2"],
package = (
_yue2_package("Q8_0", "q8_0"),
_yue2_package("BF16", "bf16"),
@@ -677,6 +886,8 @@ def family_policy(
)
if "base" in text:
return _QWEN3_BASE
+ if family == "stable_audio" and policy.music is not None:
+ return replace(policy, music = _stable_audio_music(names))
if family == "fireredtts3" and re.search(r"(^|[-_ /])base([-_ ./]|$)", " ".join(names).lower()):
return replace(policy, server_task = "clon")
return policy
@@ -1328,7 +1539,33 @@ _STUDIO_DRIVEN_OPTIONS = frozenset(
)
# The music form fills these from its lyrics, description and duration fields.
_MUSIC_DRIVEN_OPTIONS = frozenset(
- {"lyrics", "style", "caption", "prompt", "tags", "duration", "duration_sec", "duration_seconds"}
+ {
+ "lyrics",
+ "style",
+ "caption",
+ "prompt",
+ "tags",
+ "duration",
+ "duration_sec",
+ "duration_seconds",
+ "route",
+ "task_route",
+ "repainting_start",
+ "repainting_end",
+ "repaint_mode",
+ "repaint_strength",
+ "audio_cover_strength",
+ "cover_noise_strength",
+ "init_noise_level",
+ "inpaint_mask_start_seconds",
+ "inpaint_mask_end_seconds",
+ "inpaint_start",
+ "inpaint_end",
+ "audio_input_kind",
+ "batch_size",
+ "semantic_max_tokens",
+ "semantic_min_tokens",
+ }
)
_RENDERABLE_TYPES = frozenset({"bool", "int", "float", "string", "enum"})
_MAX_STRING_OPTION = 4000
@@ -1550,6 +1787,9 @@ class AudioCppModel:
clone: Optional[CloneSpec] = None
companions: tuple[CompanionModel, ...] = ()
required_inputs: tuple[str, ...] = ()
+ music: Optional[MusicSpec] = field(default = None, hash = False, compare = False)
+ # A strict spec (``schema_version``) makes the runtime refuse any undeclared option.
+ request_keys: Optional[frozenset[str]] = field(default = None, hash = False, compare = False)
@property
def is_package(self) -> bool:
@@ -1604,15 +1844,34 @@ class AudioCppModel:
return f"{self.id}:{self.variant.key}"
def with_variant(self, variant: AudioCppVariant) -> "AudioCppModel":
- from dataclasses import replace
-
model_options = dict(self.model_options)
if variant.session_options:
model_options["session_options"] = {
**dict(model_options.get("session_options") or {}),
**variant.session_options,
}
- return replace(self, variant = variant, model_options = model_options)
+ changes = _ace_step_variant(self, variant) if self.family == "ace_step" else {}
+ return replace(self, variant = variant, model_options = model_options, **changes)
+
+
+def _ace_step_variant(model: "AudioCppModel", variant: AudioCppVariant) -> dict[str, Any]:
+ """Base takes 1-200 steps (32-64 recommended) and the "complete" task; turbo 1-20 and no
+ "complete" (ACE-Step-1.5 acestep/constants.py TASK_TYPES_TURBO vs TASK_TYPES_BASE)."""
+ base = bool(re.search(r"(^|/)base(/|$)", f"{variant.key} {variant.primary}".lower()))
+ steps = {"max": 200, "default": 32} if base else {"max": 20, "default": 8}
+ options = tuple(
+ {**o, **steps} if o.get("name") == "num_inference_steps" else o for o in model.options
+ )
+ music = model.music
+ if music is not None:
+ modes = []
+ for m in music.modes:
+ if m.id == "edit":
+ actions = tuple(a for a in m.actions if a != "continue")
+ m = replace(m, actions = (*actions, "continue") if base else actions)
+ modes.append(m)
+ music = replace(music, modes = tuple(modes))
+ return {"options": options, "music": music}
class AudioCppModelError(ValueError):
@@ -1898,10 +2157,34 @@ def _resolve_uncached(
clone = policy.clone,
companions = policy.companions,
required_inputs = _required_inputs(spec, embedded, policy),
+ music = music_with_spec_bounds(policy.music, _raw_request_options(spec, embedded)),
+ request_keys = _request_keys(spec, embedded),
)
return model.with_variant(chosen)
+def _request_source(spec: Optional[dict], embedded: Optional[dict]) -> dict:
+ if spec is None or not ((spec.get("options") or {}).get("request")):
+ spec = embedded
+ return spec if isinstance(spec, dict) else {}
+
+
+def _raw_request_options(spec: Optional[dict], embedded: Optional[dict]) -> list:
+ raw = (_request_source(spec, embedded).get("options") or {}).get("request") or []
+ return raw if isinstance(raw, list) else []
+
+
+def _request_keys(spec: Optional[dict], embedded: Optional[dict]) -> Optional[frozenset[str]]:
+ if _request_source(spec, embedded).get("schema_version") is None:
+ return None
+ names = frozenset(
+ str(item.get("name")).strip()
+ for item in _raw_request_options(spec, embedded)
+ if isinstance(item, dict) and str(item.get("name") or "").strip()
+ )
+ return names or None
+
+
# Spec options Studio fills from request fields, so a required one is a field the user must give.
_REQUIRED_INPUT_NAMES = ("instruct", "reference_text")
diff --git a/studio/backend/core/inference/audio_cpp_music.py b/studio/backend/core/inference/audio_cpp_music.py
new file mode 100644
index 00000000000..2e19537e6d7
--- /dev/null
+++ b/studio/backend/core/inference/audio_cpp_music.py
@@ -0,0 +1,330 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""audio.cpp music request bodies for ``/audio/generate`` and ``/audio/run``.
+
+A strict spec (``schema_version``) refuses undeclared options, so the CLI's top-level shortcuts
+(``duration_seconds``, ``lyrics``) are sent to it only as declared options. MiniMax keeps its old
+body: its session reads both duration keys.
+"""
+
+from __future__ import annotations
+
+import math
+import secrets
+from typing import Any, Optional
+
+from core.inference.audio_cpp_models import (
+ MUSIC_MAX_VARIATIONS,
+ MUSIC_SPECS,
+ AudioCppModel,
+ MusicMode,
+)
+from loggers import get_logger
+
+logger = get_logger(__name__)
+
+_TIMEOUT_FLOOR = 300.0
+_TIMEOUT_CEILING = 4 * 3600.0
+_CPU_FACTOR = 10.0
+# MiDashengLM's spec caps seeds at 2**31 - 1.
+_SEED_LIMIT = 2**31 - 1
+
+
+class MusicRequestError(ValueError):
+ """Message shown to the user as is."""
+
+
+def random_seed() -> int:
+ return secrets.randbelow(_SEED_LIMIT)
+
+
+def take_seed(seed: Optional[int], index: int) -> Optional[int]:
+ """Seed of the ``index``-th sequential take; wraps so a valid seed never overflows the spec."""
+ if seed is None:
+ return None
+ return (seed + index) % (_SEED_LIMIT + 1) if 0 <= seed <= _SEED_LIMIT else seed + index
+
+
+def seconds_text(value: float) -> str:
+ return f"{float(value):.3f}".rstrip("0").rstrip(".")
+
+
+def timeout_seconds(family: Optional[str], seconds: float, variations: int, cpu: bool) -> float:
+ music = MUSIC_SPECS.get(str(family or ""))
+ rtf = music.rtf if music is not None else 4.0
+ work = rtf * max(0.0, float(seconds)) * max(1, int(variations)) * (_CPU_FACTOR if cpu else 1.0)
+ return max(_TIMEOUT_FLOOR, min(_TIMEOUT_CEILING, _TIMEOUT_FLOOR + work))
+
+
+def frames_for(seconds: float, variations: int = 1) -> int:
+ return int(math.ceil(max(0.0, float(seconds)) * 25 * max(1, int(variations))))
+
+
+def music_rules(model: AudioCppModel, max_batch: int = 1) -> Optional[dict[str, Any]]:
+ music = model.music
+ if music is None or model.task != "music":
+ return None
+ modes: list[dict[str, Any]] = []
+ for mode in music.modes:
+ if mode.id == "edit":
+ modes.append(
+ {
+ "id": "edit",
+ "actions": list(mode.actions),
+ "max_ranges": mode.max_ranges,
+ "max_source_s": mode.max_source_s,
+ }
+ )
+ continue
+ entry: dict[str, Any] = {"id": mode.id}
+ if mode.id == "song":
+ entry.update(
+ {
+ "lyrics": mode.lyrics,
+ "description": mode.description,
+ "instrumental": mode.instrumental,
+ "section_case": mode.section_case,
+ }
+ )
+ low, high, default = mode.duration
+ entry["duration"] = {
+ "min": low,
+ "max": high,
+ "default": default,
+ "approximate": mode.approximate,
+ }
+ entry["variations"] = (
+ {
+ "max": MUSIC_MAX_VARIATIONS,
+ "how": mode.variations,
+ # Variations one request makes without a reload.
+ "loaded": max(1, int(max_batch))
+ if mode.variations == "batch"
+ else MUSIC_MAX_VARIATIONS,
+ }
+ if mode.variations
+ else None
+ )
+ modes.append(entry)
+ return {"modes": modes}
+
+
+def _declared(model: AudioCppModel, name: str) -> bool:
+ return model.request_keys is None or name in model.request_keys
+
+
+def _put_option(model: AudioCppModel, request: dict, options: dict, name: str, value: Any) -> None:
+ if model.request_keys is None:
+ request[name] = value
+ elif name in model.request_keys:
+ options[name] = value
+ else:
+ logger.info("audio.cpp: %s does not declare %s; not sending it", model.family, name)
+
+
+def _put_duration(model: AudioCppModel, request: dict, options: dict, seconds: float) -> None:
+ keys = model.request_keys
+ if keys is None:
+ request["duration_seconds"] = seconds
+ elif "duration_sec" in keys:
+ options["duration_sec"] = seconds
+ elif "duration_seconds" in keys:
+ options["duration_seconds"] = seconds
+ else:
+ logger.info("audio.cpp: %s declares no duration; not sending one", model.family)
+
+
+def _finish(model: AudioCppModel, request: dict, options: dict, seed: Optional[int]) -> dict:
+ if model.request_keys is not None:
+ dropped = sorted(name for name in options if name not in model.request_keys)
+ if dropped:
+ logger.info(
+ "audio.cpp: %s does not declare %s; not sending them", model.family, dropped
+ )
+ options = {k: v for k, v in options.items() if k in model.request_keys}
+ if options:
+ request["options"] = options
+ if seed is not None:
+ request["seed"] = str(int(seed))
+ return request
+
+
+def song_request(
+ model: AudioCppModel,
+ *,
+ description: str,
+ lyrics: str,
+ seconds: float,
+ options: dict,
+ seed: Optional[int] = None,
+ instrumental: bool = False,
+ batch: int = 1,
+) -> dict[str, Any]:
+ description = str(description or "").strip()
+ lyrics = str(lyrics or "").strip()
+ music = model.music
+ request: dict[str, Any] = {}
+ request_options: dict[str, Any] = dict(options)
+ if model.family == "minimax_music3":
+ if not lyrics:
+ raise MusicRequestError("MiniMax Music 3 needs lyrics.")
+ # Sending duration_seconds and duration_sec together is refused as conflicting, even equal.
+ request.update(
+ {"text": description or lyrics, "lyrics": lyrics, "duration_seconds": seconds}
+ )
+ request_options["lyrics"] = lyrics
+ if request_options:
+ request["options"] = request_options
+ if seed is not None:
+ request["seed"] = str(int(seed))
+ return request
+ if model.family == "yue2":
+ if not description:
+ raise MusicRequestError("YuE2 needs a style description.")
+ # Missing or empty lyrics still sing; only "[Instrumental]" comes back wordless.
+ if instrumental or not lyrics:
+ lyrics = (
+ music.instrumental_lyrics
+ if music and music.instrumental_lyrics
+ else "[Instrumental]"
+ )
+ request["text"] = lyrics
+ request_options["style"] = description
+ request_options["lyrics"] = lyrics
+ # Length is the semantic token budget (25 fps); the default 200-frame floor outlasts short asks.
+ frames = int(round(seconds * 25))
+ request_options["semantic_max_tokens"] = frames
+ request_options["semantic_min_tokens"] = min(200, frames)
+ return _finish(model, request, request_options, seed)
+ if instrumental and music is not None and music.instrumental_lyrics is not None:
+ lyrics = music.instrumental_lyrics
+ request["text"] = description
+ if music is not None and music.description_option:
+ request_options[music.description_option] = description
+ _put_duration(model, request, request_options, seconds)
+ if lyrics and model.family != "stable_audio":
+ _put_option(model, request, request_options, "lyrics", lyrics)
+ if batch > 1:
+ request_options["batch_size"] = str(int(batch))
+ return _finish(model, request, request_options, seed)
+
+
+def legacy_song_request(
+ model: AudioCppModel,
+ text: str,
+ instructions: Optional[str],
+ seconds: float,
+ options: dict,
+ seed: Optional[int],
+) -> dict[str, Any]:
+ """Description = instructions, lyrics = text; a lone prompt is the description."""
+ description = str(instructions or "").strip()
+ lyrics = str(text or "").strip()
+ if model.family not in ("minimax_music3", "yue2") and not description:
+ description, lyrics = lyrics, ""
+ # MiDashengLM crashes past 81 s.
+ mode = model.music.modes[0] if model.music is not None and model.music.modes else None
+ if mode is not None:
+ seconds = min(seconds, mode.duration[1])
+ return song_request(
+ model,
+ description = description,
+ lyrics = lyrics,
+ seconds = seconds,
+ options = options,
+ seed = seed,
+ )
+
+
+def merge_ranges(ranges: list[tuple[float, float]], limit: float) -> list[tuple[float, float]]:
+ clamped = sorted(
+ (max(0.0, float(s)), min(float(limit), float(e)))
+ for s, e in ranges
+ if min(float(limit), float(e)) > max(0.0, float(s))
+ )
+ merged: list[tuple[float, float]] = []
+ for start, end in clamped:
+ if merged and start <= merged[-1][1]:
+ merged[-1] = (merged[-1][0], max(merged[-1][1], end))
+ else:
+ merged.append((start, end))
+ return merged
+
+
+def edit_request(
+ model: AudioCppModel,
+ *,
+ text: str,
+ edit: dict,
+ source: str,
+ source_seconds: float,
+ duration_s: Optional[float],
+ options: dict,
+ seed: Optional[int] = None,
+) -> dict[str, Any]:
+ mode = model.music.mode("edit") if model.music is not None else None
+ action = str(edit.get("action") or "")
+ if mode is None or action not in mode.actions:
+ raise MusicRequestError(f"{model.display_name} cannot {action or 'edit'} a clip.")
+ text = str(text or "").strip()
+ if not text:
+ raise MusicRequestError("Describe the change.")
+ ranges = [(float(r["start_s"]), float(r["end_s"])) for r in edit.get("ranges") or []]
+ strength = edit.get("strength")
+ request: dict[str, Any] = {"text": text, "audio": str(source)}
+ request_options: dict[str, Any] = dict(options)
+ if model.family == "ace_step":
+ if action in ("repaint", "extend"):
+ if action == "extend":
+ start, end = source_seconds, source_seconds + float(edit.get("extend_s") or 0.0)
+ else:
+ (start, end) = ranges[0]
+ # The window may pass the clip's end: ACE-Step pads it, extending the song.
+ request_options.update(
+ {"route": "repaint", "repainting_start": start, "repainting_end": end}
+ )
+ if strength is not None and action == "repaint":
+ request_options["repaint_strength"] = float(strength)
+ elif action == "cover":
+ request_options["route"] = "cover"
+ if strength is not None:
+ # strength is how much to change; audio_cover_strength is the share of steps
+ # conditioned on the source (diffusion.cpp), so higher keeps more of it.
+ request_options["audio_cover_strength"] = 1.0 - float(strength)
+ else: # continue: ACE-Step's "complete" adds parts across the whole track.
+ request_options["route"] = "complete"
+ request_options["duration_seconds"] = float(duration_s or source_seconds)
+ return _finish(model, request, request_options, seed)
+ if model.family == "stable_audio":
+ if action == "inpaint":
+ merged = merge_ranges(ranges, source_seconds)
+ if not merged:
+ raise MusicRequestError("Pick a part of the clip to change.")
+ request_options.update(
+ {
+ "audio_input_kind": "inpaint_audio",
+ "inpaint_mask_start_seconds": ",".join(seconds_text(s) for s, _ in merged),
+ "inpaint_mask_end_seconds": ",".join(seconds_text(e) for _, e in merged),
+ }
+ )
+ else: # restyle
+ request_options["audio_input_kind"] = "init_audio"
+ if strength is not None:
+ request_options["init_noise_level"] = float(strength)
+ _put_duration(model, request, request_options, source_seconds)
+ return _finish(model, request, request_options, seed)
+ raise MusicRequestError(f"{model.display_name} cannot edit a clip.")
+
+
+def song_mode(model: AudioCppModel, mode_id: str) -> MusicMode:
+ mode = model.music.mode(mode_id) if model.music is not None else None
+ if mode is None:
+ raise MusicRequestError(f"{model.display_name} does not offer {mode_id}.")
+ return mode
+
+
+def clamp_seconds(mode: MusicMode, seconds: Optional[float]) -> float:
+ low, high, default = mode.duration
+ value = default if seconds is None else float(seconds)
+ return max(low, min(high, value))
diff --git a/studio/backend/core/inference/audio_cpp_server.py b/studio/backend/core/inference/audio_cpp_server.py
index 7190284f3d9..add4f60e1f1 100644
--- a/studio/backend/core/inference/audio_cpp_server.py
+++ b/studio/backend/core/inference/audio_cpp_server.py
@@ -644,7 +644,9 @@ class AudioCppServer:
process.wait(timeout = 10)
except subprocess.TimeoutExpired:
process.kill()
- process.wait(timeout = 10)
+ # A killed server can sit in GPU context teardown well past 10 s on a busy card;
+ # the music reload restarts it mid-session and must not fail on that.
+ process.wait(timeout = 120)
forget_pid(process.pid)
shutil.rmtree(self._config_dir, ignore_errors = True)
diff --git a/studio/backend/core/inference/audio_inputs.py b/studio/backend/core/inference/audio_inputs.py
index f004844e166..4c117baebd1 100644
--- a/studio/backend/core/inference/audio_inputs.py
+++ b/studio/backend/core/inference/audio_inputs.py
@@ -11,6 +11,7 @@ from __future__ import annotations
import hashlib
import json
import os
+import shutil
import threading
import time
import uuid
@@ -137,11 +138,12 @@ def transcode(
*,
rate: Optional[int] = None,
mono: bool = False,
+ stereo: bool = False,
max_seconds: Optional[float] = None,
cut: bool = False,
) -> dict[str, Any]:
- """Decode ``src`` into a 16-bit WAV at ``dst``: at ``rate`` (default the source's), mono or at
- most two channels. Past ``max_seconds`` it is cut when ``cut``, else refused with 413.
+ """Decode ``src`` into a 16-bit WAV at ``dst``: at ``rate`` (default the source's), mono, two
+ channels (``stereo``) or at most two channels. Past ``max_seconds`` it is cut when ``cut``, else refused with 413.
Streams frame by frame through FFmpeg's resampler (a voice reference must not alias) into a
temporary file renamed in at the end."""
@@ -181,7 +183,11 @@ def transcode(
if rate <= 0:
raise AudioInputError(400, "This audio has no sample rate.")
channels = (
- 1 if mono else max(1, min(_MAX_CHANNELS, len(frame.layout.channels)))
+ 1
+ if mono
+ else 2
+ if stereo
+ else max(1, min(_MAX_CHANNELS, len(frame.layout.channels)))
)
layout = "stereo" if channels == 2 else "mono"
resampler = av.AudioResampler(format = "s16", layout = layout, rate = rate)
@@ -413,6 +419,12 @@ def sweep(
path.unlink(missing_ok = True)
elif name.startswith(("c-", "v-")) and name.endswith(".wav") and age > ttl:
path.unlink(missing_ok = True)
+ # Music run folders a crash left behind.
+ runs = directory / "runs"
+ if runs.is_dir():
+ for run in runs.iterdir():
+ if run.is_dir() and now - _mtime(run) > _STALE_TMP_SECONDS:
+ shutil.rmtree(run, ignore_errors = True)
return removed
except Exception as exc: # noqa: BLE001 - housekeeping never fails a request
logger.warning("audio_inputs.sweep_failed: %s", exc)
@@ -487,25 +499,47 @@ def prepared_path(
source: Source,
rate: int,
max_seconds: Optional[float] = None,
+ stereo: bool = False,
) -> Path:
- """A cached mono copy of ``source`` at ``rate``, cut to ``max_seconds``, in this account's inputs.
+ """A cached copy of ``source`` at ``rate`` (mono, or stereo for music edits), cut to
+ ``max_seconds``, in this account's inputs.
- An input's copies sit beside it as ``{id}.{rate}.mono[.m{n}].wav`` and go when it goes; a
- clip's or voice's as ``c-``/``v-`` files the sweep removes after the TTL."""
+ An input's copies sit beside it as ``{id}.{rate}.{mono|stereo}[.m{n}].wav`` and go when it
+ goes; a clip's or voice's as ``c-``/``v-`` files the sweep removes after the TTL."""
prefix = {"input": "", "clip": "c-", "voice": "v-"}[source.kind]
cap = f".m{max_seconds:g}" if max_seconds is not None else ""
- dst = inputs_dir() / f"{prefix}{source.id}.{int(rate)}.mono{cap}.wav"
+ layout = "stereo" if stereo else "mono"
+ dst = inputs_dir() / f"{prefix}{source.id}.{int(rate)}.{layout}{cap}.wav"
if dst.is_file() and _mtime(dst) >= _mtime(source.path):
if source.kind != "input":
os.utime(dst)
return dst
- transcode(source.path, dst, rate = rate, mono = True, max_seconds = max_seconds, cut = True)
+ transcode(
+ source.path,
+ dst,
+ rate = rate,
+ mono = not stereo,
+ stereo = stereo,
+ max_seconds = max_seconds,
+ cut = True,
+ )
if source.kind != "input":
# Cloning from history or a saved voice may never upload, so expired copies go here too.
sweep()
return dst
+def wav_info(path: Path) -> dict[str, Any]:
+ with wave.open(str(path)) as w:
+ rate = w.getframerate()
+ return {
+ "sample_rate": rate,
+ "channels": w.getnchannels(),
+ "frames": w.getnframes(),
+ "duration_s": round(w.getnframes() / rate, 3) if rate else 0.0,
+ }
+
+
def prepare_reference(ref: dict[str, Any]) -> tuple[Source, Path]:
"""A voice reference ready for the runtime: 24 kHz mono, at most 30 s."""
source = resolve_source(ref)
diff --git a/studio/backend/core/inference/audio_task_outputs.py b/studio/backend/core/inference/audio_task_outputs.py
new file mode 100644
index 00000000000..7f81c84f8db
--- /dev/null
+++ b/studio/backend/core/inference/audio_task_outputs.py
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Every WAV a ``/v1/tasks/run`` reply carries. With ``named_audio_outputs`` present the
+top-level ``audio`` repeats the first one, so it is not counted twice."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import io
+import json
+import wave
+from typing import Any
+
+_EMPTY = "The audio runtime returned no audio for this request."
+
+
+def _decode(value: Any) -> bytes | None:
+ if not isinstance(value, str) or not value:
+ return None
+ try:
+ data = base64.b64decode(value.split(",", 1)[-1], validate = False)
+ except (binascii.Error, ValueError):
+ return None
+ return data if data[:4] == b"RIFF" else None
+
+
+def task_outputs(content_type: str, data: bytes) -> list[tuple[str, bytes]]:
+ if (content_type or "").startswith("audio/") or data[:4] == b"RIFF":
+ return [("audio", data)]
+ try:
+ payload = json.loads(data.decode("utf-8"))
+ except (UnicodeDecodeError, ValueError) as exc:
+ raise RuntimeError("The audio runtime returned an unreadable response.") from exc
+ if not isinstance(payload, dict):
+ raise RuntimeError(_EMPTY)
+ named = payload.get("named_audio_outputs")
+ if isinstance(named, list) and named:
+ outputs: list[tuple[str, bytes]] = []
+ for index, item in enumerate(named):
+ if not isinstance(item, dict):
+ continue
+ wav = _decode(item.get("audio"))
+ if wav is not None:
+ outputs.append((str(item.get("id") or f"audio_{index}"), wav))
+ if outputs:
+ return outputs
+ wav = _decode(payload.get("audio"))
+ if wav is not None:
+ return [("audio", wav)]
+ raise RuntimeError(_EMPTY)
+
+
+def wav_header(wav_bytes: bytes) -> tuple[int, float]:
+ with wave.open(io.BytesIO(wav_bytes)) as w:
+ rate = int(w.getframerate())
+ frames = int(w.getnframes())
+ return rate, (round(frames / rate, 3) if rate else 0.0)
diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index c81d3a4c4e1..f24b03694dc 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -391,6 +391,8 @@ def _mirrored_model_entry(model_info: dict, model_name: str) -> dict:
"audio_reference_text": model_info.get("audio_reference_text"),
"audio_required_inputs": model_info.get("audio_required_inputs"),
"audio_clone": model_info.get("audio_clone"),
+ "audio_music": model_info.get("audio_music"),
+ "audio_cpp_backend": model_info.get("audio_cpp_backend"),
}
@@ -3351,6 +3353,8 @@ class InferenceOrchestrator:
audio_inputs: Optional[dict[str, str]] = None,
reference_text: Optional[str] = None,
speed: Optional[float] = None,
+ music: Optional[dict] = None,
+ output_dir: Optional[str] = None,
stats_holder: Optional[dict] = None,
) -> Tuple[bytes, int]:
"""Generate TTS audio. Returns (wav_bytes, sample_rate). Blocking: sends the command and
@@ -3432,6 +3436,16 @@ class InferenceOrchestrator:
cmd["reference_text"] = reference_text
if speed is not None:
cmd["speed"] = float(speed)
+ if music is not None:
+ cmd["music"] = dict(music)
+ try:
+ music_wait = float(music.get("timeout_s") or 0.0)
+ except (TypeError, ValueError):
+ music_wait = 0.0
+ # Outlast the worker's wait so its error, not the watchdog, reaches the caller.
+ generation_timeout = max(generation_timeout, music_wait + 60.0)
+ if output_dir is not None:
+ cmd["output_dir"] = str(output_dir)
# Same shared-queue hazard as _generate_inner: see _direct_reader.
read_one, _drain, release_mailbox = self._direct_reader(request_id, cancel_event)
@@ -3493,6 +3507,11 @@ class InferenceOrchestrator:
raise AudioGenerationCancelledError("Audio generation cancelled")
wav_bytes = base64.b64decode(resp["wav_base64"])
sample_rate = resp["sample_rate"]
+ status_patch = resp.get("status_patch")
+ if isinstance(status_patch, dict):
+ live = self.models.get(expected_model)
+ if live is not None and "audio_music" in status_patch:
+ live["audio_music"] = status_patch["audio_music"]
if stats_holder is not None:
stats_holder["stats"] = resp.get("stats")
return wav_bytes, sample_rate
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index 926bd5f4279..67bffd721b4 100644
--- a/studio/backend/core/inference/worker.py
+++ b/studio/backend/core/inference/worker.py
@@ -794,6 +794,8 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
"audio_reference_text",
"audio_required_inputs",
"audio_clone",
+ "audio_music",
+ "audio_cpp_backend",
)
if k in _entry
}
@@ -1612,6 +1614,9 @@ def _handle_generate_audio(backend, cmd: dict, resp_queue: Any, cancel_event) ->
extra[key] = cmd[key]
elif key == "audio_inputs":
raise AudioRuntimeError("This model cannot clone a voice.", status = 400)
+ for key in ("music", "output_dir"):
+ if cmd.get(key) is not None:
+ extra[key] = cmd[key]
wav_bytes, sample_rate = backend.generate_audio_response(
text = cmd["text"],
temperature = cmd.get("temperature", 0.6),
@@ -1629,16 +1634,18 @@ def _handle_generate_audio(backend, cmd: dict, resp_queue: Any, cancel_event) ->
)
# Send WAV bytes as base64 (bytes can't go through mp.Queue directly).
- _send_response(
- resp_queue,
- {
- "type": "audio_done",
- "request_id": request_id,
- "wav_base64": base64.b64encode(wav_bytes).decode("ascii"),
- "sample_rate": sample_rate,
- "stats": getattr(backend, "last_generation_stats", None),
- },
- )
+ done = {
+ "type": "audio_done",
+ "request_id": request_id,
+ "wav_base64": base64.b64encode(wav_bytes).decode("ascii"),
+ "sample_rate": sample_rate,
+ "stats": getattr(backend, "last_generation_stats", None),
+ }
+ take_status_patch = getattr(backend, "take_status_patch", None)
+ status_patch = take_status_patch() if callable(take_status_patch) else None
+ if isinstance(status_patch, dict) and status_patch:
+ done["status_patch"] = status_patch
+ _send_response(resp_queue, done)
logger.info("Finished audio generation for request_id=%s", request_id)
except Exception as exc:
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index ea3c0d0f548..e428447ec2f 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -1387,6 +1387,15 @@ class _InferenceRuntimeFields(BaseModel):
"description sent as instructions)."
),
)
+ audio_music: Optional[Dict[str, Any]] = Field(
+ None,
+ description = (
+ "Music studio capabilities of an audio.cpp music model: {modes: [{id: song|sfx|edit, "
+ "...}]} with lyrics, description, instrumental, section_case, duration and "
+ "variations for song and sfx, and actions, max_ranges and max_source_s for edit. "
+ "None for a model the Music studio does not drive (and native MiniMax)."
+ ),
+ )
@model_validator(mode = "after")
def derive_audio_workflows(self):
@@ -5146,6 +5155,7 @@ class AudioGalleryItem(BaseModel):
None,
description = "Unpinned sort key (epoch-second scale): the manual key once dragged, else the file mtime",
)
+ group_id: Optional[str] = Field(None, description = "Clips made by one run share this id")
role: Optional[str] = Field(None, description = "The clip's part in its run, e.g. output")
source_clip_id: Optional[str] = Field(
None, description = "History clip the run took its reference from"
@@ -5196,6 +5206,29 @@ class AudioRunInputs(BaseModel):
reference: Optional[AudioSourceRef] = None
reference_text: Optional[str] = Field(None, max_length = 4000)
emotion: Optional[AudioSourceRef] = None
+ source: Optional[AudioSourceRef] = None
+
+
+class AudioMusicRange(BaseModel):
+ model_config = ConfigDict(extra = "forbid")
+
+ start_s: float = Field(..., ge = 0, le = 24 * 3600)
+ end_s: float = Field(..., gt = 0, le = 24 * 3600)
+
+ @model_validator(mode = "after")
+ def _ordered(self):
+ if self.end_s <= self.start_s:
+ raise ValueError("A range must end after it starts.")
+ return self
+
+
+class AudioMusicEdit(BaseModel):
+ model_config = ConfigDict(extra = "forbid")
+
+ action: Literal["repaint", "extend", "cover", "continue", "inpaint", "restyle"]
+ ranges: List[AudioMusicRange] = Field(default_factory = list, max_length = 8)
+ strength: Optional[float] = Field(None, ge = 0, le = 1)
+ extend_s: Optional[float] = Field(None, gt = 0, le = 600)
class AudioRunRequest(BaseModel):
@@ -5203,11 +5236,17 @@ class AudioRunRequest(BaseModel):
model_config = ConfigDict(extra = "forbid")
- workflow: Literal["clone", "speak"]
- text: str = Field(..., min_length = 1)
+ workflow: Literal["clone", "speak", "music"]
+ text: str
language: Optional[str] = Field(None, max_length = 64)
instructions: Optional[str] = Field(None, max_length = 4000)
inputs: AudioRunInputs = Field(default_factory = AudioRunInputs)
+ mode: Optional[Literal["song", "sfx", "edit"]] = None
+ lyrics: Optional[str] = Field(None, max_length = 20000)
+ instrumental: bool = False
+ duration_s: Optional[float] = Field(None, ge = 0.5, le = 600)
+ variations: int = Field(1, ge = 1, le = 4)
+ edit: Optional[AudioMusicEdit] = None
options: Optional[Dict[str, Any]] = Field(
None, description = "Per-model options, as listed in audio_options or by a tool panel"
)
@@ -5227,6 +5266,16 @@ class AudioRunRequest(BaseModel):
raise ValueError(f"Option '{name}' must be a single value.")
return value
+ @model_validator(mode = "after")
+ def _workflow_fields(self):
+ if self.workflow == "music":
+ if self.mode is None:
+ raise ValueError("Pick a music mode: song, sfx or edit.")
+ else:
+ if not self.text:
+ raise ValueError("text must not be empty.")
+ return self
+
class AudioRunClip(BaseModel):
id: str
@@ -5245,6 +5294,7 @@ class AudioRunAudio(BaseModel):
class AudioRunResponse(BaseModel):
clips: List[AudioRunClip] = Field(default_factory = list)
+ group_id: Optional[str] = None
model: str
audio: Optional[AudioRunAudio] = Field(
None, description = "The audio inline, only when saving it to history failed"
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 6aa9d2b53a8..e716568fbda 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -8252,6 +8252,7 @@ def _llama_runtime_fields(llama_backend: LlamaCppBackend) -> dict:
audio_workflows = None,
audio_reference_text = None,
audio_required_inputs = None,
+ audio_music = None,
# Older/custom backend doubles predate this additive runtime field.
preserve_thinking_default = bool(getattr(llama_backend, "preserve_thinking_default", False)),
speculative_type = llama_backend.requested_spec_mode,
@@ -19166,6 +19167,7 @@ async def _load_model_impl(
audio_workflows = _model_info.get("audio_workflows"),
audio_reference_text = _model_info.get("audio_reference_text"),
audio_required_inputs = _model_info.get("audio_required_inputs"),
+ audio_music = _model_info.get("audio_music"),
is_mlx = bool(_model_info.get("is_mlx", False)),
mlx_kv_quant = _model_info.get("mlx_kv_quant"),
mlx_kv_quant_requested = _model_info.get("mlx_kv_quant_requested"),
@@ -21848,6 +21850,7 @@ async def _slot_status(current_subject: str):
audio_workflows = model_info.get("audio_workflows"),
audio_reference_text = model_info.get("audio_reference_text"),
audio_required_inputs = model_info.get("audio_required_inputs"),
+ audio_music = model_info.get("audio_music"),
gguf_variant = model_info.get("gguf_variant"),
is_mlx = bool(model_info.get("is_mlx", False)),
mlx_kv_quant = model_info.get("mlx_kv_quant"),
@@ -21997,6 +22000,9 @@ def _audio_cpp_music_request_problem(
return "MiniMax Music 3 needs lyrics."
if family == "yue2" and not str(description or "").strip():
return "YuE2 needs a style description."
+ if family == "heartmula":
+ if not str(lyrics or "").strip() or not str(description or "").strip():
+ return "HeartMuLa needs lyrics and a description of the style."
return None
@@ -22018,6 +22024,11 @@ def _audio_request_problem(
workflows = model_info.get("audio_workflows")
label = _audio_model_label(model_name)
inputs = (run_inputs or {}).get("audio_inputs") or {}
+ if run_inputs and run_inputs.get("workflow") == "music":
+ # The model may have changed since the route checked the mode.
+ if not model_info.get("audio_music"):
+ return _audio_music_unavailable(label)
+ return None
cloning = bool(run_inputs) and (run_inputs.get("workflow") == "clone" or bool(inputs))
if cloning:
if not workflows or "clone" not in workflows:
@@ -22158,7 +22169,8 @@ async def _generate_tts_wav(
**{
key: value
for key, value in (run_inputs or {}).items()
- if key in ("workflow", "audio_inputs", "reference_text", "speed")
+ if key
+ in ("workflow", "audio_inputs", "reference_text", "speed", "music", "output_dir")
and value is not None
},
stats_holder = stats_holder,
@@ -22176,7 +22188,7 @@ async def _generate_tts_wav(
raise HTTPException(status_code = 400, detail = _request_problem)
if audio_type == "minimax_music3" and not str(payload.audio_instructions or "").strip():
raise HTTPException(status_code = 400, detail = _MINIMAX_NEEDS_DESCRIPTION)
- if audio_type == "audiocpp_music":
+ if audio_type == "audiocpp_music" and (run_inputs or {}).get("workflow") != "music":
_music_request_problem = _audio_cpp_music_request_problem(
audio_family, text, payload.audio_instructions
)
@@ -22415,18 +22427,346 @@ def _audio_run_settings(body: AudioRunRequest, reference_text_used: bool) -> dic
}
+_REPAINT_BEYOND_END_S = 30.0
+_MUSIC_ONLY_FIELDS = ("mode", "lyrics", "instrumental", "duration_s", "variations", "edit")
+_MUSIC_MODE_NAMES = {"song": "songs", "sfx": "sound effects", "edit": "edits"}
+
+
+def _audio_music_unavailable(label: str) -> str:
+ return f"{label} does not work in the Music studio. Load an audio.cpp music model."
+
+
+def _music_mode_rules(rules: Optional[dict], mode: Optional[str]) -> Optional[dict]:
+ for entry in (rules or {}).get("modes") or []:
+ if isinstance(entry, dict) and entry.get("id") == mode:
+ return entry
+ return None
+
+
+def _audio_music_body_problem(
+ body: AudioRunRequest, rules: Optional[dict], label: str
+) -> Optional[str]:
+ """User-facing reason the loaded model cannot run this request, else None."""
+ if body.inputs.reference or body.inputs.emotion or body.inputs.reference_text:
+ return "Music takes a clip to edit, not a voice reference. Remove the reference."
+ if not rules:
+ return _audio_music_unavailable(label)
+ mode = _music_mode_rules(rules, body.mode)
+ if mode is None:
+ return f"{label} does not make {_MUSIC_MODE_NAMES.get(body.mode, body.mode)}."
+ text = body.text.strip()
+ if body.mode != "edit":
+ if body.edit is not None or body.inputs.source is not None:
+ return "A source clip and edit settings apply to Edit only."
+ variations = mode.get("variations")
+ if body.variations > 1 and not variations:
+ return f"{label} makes one take at a time. Set variations to 1."
+ if variations and body.variations > int(variations.get("max") or 1):
+ return f"{label} makes at most {variations.get('max')} variations at a time."
+ if body.mode == "sfx":
+ return None if text else "Describe the sound to make."
+ lyrics = (body.lyrics or "").strip()
+ if body.instrumental and mode.get("instrumental") == "never":
+ return f"{label} always sings. Turn off Instrumental and add lyrics."
+ if mode.get("lyrics") == "required" and not lyrics:
+ return f"{label} needs lyrics."
+ if mode.get("description") == "required" and not text:
+ return f"{label} needs a description of the music."
+ if not text and not lyrics:
+ return "Describe the music or add lyrics."
+ return None
+ if body.variations > 1:
+ return "An edit makes one take at a time. Set variations to 1."
+ source = body.inputs.source
+ if source is None:
+ return "Add a clip to edit."
+ if source.voice_id:
+ return "Edit an upload or a clip from history. Saved voices cannot be edited."
+ edit = body.edit
+ if edit is None:
+ return "Choose what to do to the clip."
+ if edit.action not in (mode.get("actions") or []):
+ return f"{label} cannot {edit.action} a clip."
+ if edit.action in ("repaint", "inpaint") and not edit.ranges:
+ return "Select the part of the clip to change."
+ if edit.action in ("extend", "cover", "continue", "restyle") and edit.ranges:
+ return f"{edit.action.capitalize()} changes the whole clip; clear the selected parts."
+ if len(edit.ranges) > int(mode.get("max_ranges") or 0):
+ return f"{label} changes at most {mode.get('max_ranges')} part(s) of a clip at a time."
+ if edit.action == "extend" and not edit.extend_s:
+ return "Choose how many seconds to add."
+ if not text:
+ return "Describe the change."
+ return None
+
+
+def _audio_music_source_problem(
+ body: AudioRunRequest, rules: dict, source_s: float, song_max: float
+) -> Optional[str]:
+ mode = _music_mode_rules(rules, "edit") or {}
+ max_source = float(mode.get("max_source_s") or 240.0)
+ if source_s > max_source + 0.05:
+ return f"Edit clips up to {_music_length_words(max_source)}. Trim it first."
+ edit = body.edit
+ for r in edit.ranges:
+ if r.start_s >= source_s:
+ return "A selected part starts after the clip ends. Select inside the clip."
+ if edit.action == "repaint" and r.end_s > song_max:
+ return f"A repaint can reach at most {_music_length_words(song_max)} into the song."
+ # The page draws at most this much tail past the clip; extend covers longer additions.
+ if edit.action == "repaint" and r.end_s > source_s + _REPAINT_BEYOND_END_S + 0.05:
+ return f"A repaint can reach at most {_REPAINT_BEYOND_END_S:g} s past the end."
+ if edit.action == "extend" and source_s + float(edit.extend_s or 0) > song_max + 0.05:
+ return f"The extended clip would pass {_music_length_words(song_max)}. Add fewer seconds."
+ return None
+
+
+def _music_length_words(seconds: float) -> str:
+ if seconds >= 60 and float(seconds) % 60 == 0:
+ minutes = int(seconds // 60)
+ return f"{minutes} minute{'s' if minutes != 1 else ''}"
+ return f"{seconds:g} s"
+
+
+def _audio_music_settings(
+ body: AudioRunRequest,
+ duration_s: Optional[float],
+ seed: Optional[int],
+ variation: Optional[int],
+ song: Optional[dict] = None,
+) -> dict[str, Any]:
+ """Scalars only: never a file or server path. Records what ran: an always-instrumental model
+ is instrumental and takes no lyrics, whatever the request said."""
+ instrumental = lyrics = None
+ if body.mode == "song":
+ how = (song or {}).get("instrumental")
+ instrumental = how == "always" or (body.instrumental and how != "never")
+ if (song or {}).get("lyrics") != "unused":
+ lyrics = body.lyrics
+ settings = _audio_run_settings(body, False)
+ settings.update(
+ {
+ "mode": body.mode,
+ "variation": variation,
+ "seed": seed,
+ "duration_s": duration_s,
+ "instrumental": instrumental,
+ "lyrics": lyrics,
+ }
+ )
+ if body.edit is not None:
+ settings["edit"] = {
+ "action": body.edit.action,
+ "ranges": [{"start_s": r.start_s, "end_s": r.end_s} for r in body.edit.ranges],
+ "strength": body.edit.strength,
+ "extend_s": body.edit.extend_s,
+ }
+ return settings
+
+
+def _read_music_outputs(run_dir: Path) -> list[tuple[bytes, int, Optional[int]]]:
+ """A listed file outside ``run_dir`` is never read."""
+ from core.inference.audio_task_outputs import wav_header
+
+ try:
+ manifest = json.loads((run_dir / "outputs.json").read_text(encoding = "utf-8"))
+ except (OSError, ValueError):
+ return []
+ root = run_dir.resolve()
+ outputs: list[tuple[bytes, int, Optional[int]]] = []
+ for entry in manifest if isinstance(manifest, list) else []:
+ if not isinstance(entry, dict) or not isinstance(entry.get("file"), str):
+ continue
+ path = (run_dir / entry["file"]).resolve()
+ if path.parent != root or not path.is_file():
+ logger.warning("audio.music: ignoring an output outside the run folder")
+ continue
+ data = path.read_bytes()
+ try:
+ rate = wav_header(data)[0]
+ except Exception: # noqa: BLE001 - not a WAV
+ continue
+ seed = entry.get("seed")
+ outputs.append((data, rate, seed if isinstance(seed, int) else None))
+ return outputs
+
+
+async def _run_music_workflow(
+ body: AudioRunRequest, request: Request, current_subject: str
+) -> AudioRunResponse:
+ import base64
+ import shutil
+
+ from core.inference import audio_inputs
+ from core.inference.audio_cpp_models import MUSIC_SPECS
+ from core.inference.audio_cpp_music import frames_for, timeout_seconds
+
+ await _maybe_auto_switch_model(
+ _RELOAD_ONLY_MODEL,
+ request,
+ current_subject,
+ claim_resident = False,
+ require_speech = True,
+ )
+ backend = await asyncio.to_thread(get_inference_backend)
+ if not backend.active_model_name:
+ raise HTTPException(status_code = 400, detail = "Load a music model first.")
+ model_info = backend.models.get(backend.active_model_name, {}) or {}
+ label = _audio_model_label(_orchestrator_public_model_id(backend))
+ rules = model_info.get("audio_music")
+ problem = _audio_music_body_problem(body, rules, label)
+ if problem:
+ raise HTTPException(status_code = 400, detail = problem)
+ family = model_info.get("audio_family")
+ song = _music_mode_rules(rules, "song") or {}
+ song_max = float((song.get("duration") or {}).get("max") or 240.0)
+
+ run_dir = audio_inputs.inputs_dir() / "runs" / uuid.uuid4().hex
+ try:
+ source_path = None
+ source = None
+ seconds: Optional[float] = None
+ if body.mode == "edit":
+ spec = MUSIC_SPECS.get(str(family or ""))
+ rate = spec.edit_rate if spec is not None else None
+ if not rate:
+ raise HTTPException(status_code = 400, detail = f"{label} cannot edit a clip.")
+ try:
+ source = await asyncio.to_thread(
+ audio_inputs.resolve_source, body.inputs.source.model_dump(exclude_none = True)
+ )
+ source_s = float(
+ (await asyncio.to_thread(audio_inputs.wav_info, source.path))["duration_s"]
+ )
+ problem = _audio_music_source_problem(body, rules, source_s, song_max)
+ if problem:
+ raise HTTPException(status_code = 400, detail = problem)
+ source_path = await asyncio.to_thread(
+ audio_inputs.prepared_path, source, rate, None, True
+ )
+ except audio_inputs.AudioInputError as exc:
+ raise _audio_source_error(exc) from None
+ work_s = source_s + float(body.edit.extend_s or 0.0)
+ # A repaint range past the end pads the source out to it.
+ work_s = max([work_s, *(r.end_s for r in body.edit.ranges)])
+ if body.edit.action == "continue" and body.duration_s:
+ seconds = min(song_max, float(body.duration_s))
+ work_s = max(work_s, seconds)
+ else:
+ mode = _music_mode_rules(rules, body.mode) or {}
+ bounds = mode.get("duration") or {}
+ low = float(bounds.get("min") or 1.0)
+ high = float(bounds.get("max") or 240.0)
+ wanted = body.duration_s if body.duration_s is not None else bounds.get("default")
+ seconds = max(low, min(high, float(wanted if wanted is not None else low)))
+ work_s = seconds
+ variations = body.variations if body.mode != "edit" else 1
+ cpu = model_info.get("audio_cpp_backend") == "cpu"
+ music = {
+ "mode": body.mode,
+ "text": body.text,
+ "lyrics": body.lyrics,
+ "instrumental": body.instrumental,
+ "duration_s": seconds,
+ "variations": variations,
+ "edit": body.edit.model_dump() if body.edit is not None else None,
+ "timeout_s": timeout_seconds(family, work_s, variations, cpu),
+ }
+ run_dir.mkdir(parents = True, exist_ok = True)
+ payload = ChatCompletionRequest(
+ messages = [{"role": "user", "content": body.text or body.lyrics or ""}],
+ # Only scales the orchestrator's deadline.
+ max_tokens = max(1, min(8192, frames_for(work_s, variations))),
+ audio_options = body.options,
+ seed = body.seed,
+ )
+ wav_bytes, sample_rate, model_name, audio_type = await _generate_tts_wav(
+ body.text,
+ payload,
+ request,
+ current_subject,
+ run_inputs = {
+ "workflow": "music",
+ "audio_inputs": {"source": str(source_path)} if source_path else None,
+ "music": music,
+ "output_dir": str(run_dir),
+ },
+ )
+ outputs = await asyncio.to_thread(_read_music_outputs, run_dir)
+ finally:
+ await asyncio.to_thread(shutil.rmtree, run_dir, ignore_errors = True)
+ if not outputs:
+ outputs = [(wav_bytes, sample_rate, body.seed)]
+ group_id = uuid.uuid4().hex if len(outputs) > 1 else None
+ role = "edit" if body.mode == "edit" else ("variation" if len(outputs) > 1 else "output")
+ prompt = body.text.strip() or " ".join((body.lyrics or "").split())[:200]
+ clips = []
+ for index, (wav, rate, seed) in enumerate(outputs):
+ extra_meta: dict[str, Any] = {
+ "role": role,
+ "group_id": group_id,
+ "settings": _audio_music_settings(
+ body, seconds, seed, index + 1 if len(outputs) > 1 else None, song
+ ),
+ }
+ if source is not None:
+ extra_meta["reference_name"] = source.name
+ if source.kind == "clip":
+ extra_meta["source_clip_id"] = source.id
+ record = await asyncio.to_thread(
+ _persist_tts_clip, wav, rate, prompt, model_name, audio_type, extra_meta, "music"
+ )
+ if record is None:
+ if not clips:
+ return AudioRunResponse(
+ clips = [],
+ model = model_name,
+ audio = {
+ "data": base64.b64encode(wav).decode("ascii"),
+ "format": "wav",
+ "sample_rate": rate,
+ },
+ )
+ continue
+ clips.append(
+ {
+ "id": record["id"],
+ "role": role,
+ "url": record["url"],
+ "sample_rate": record["sample_rate"],
+ "duration_s": record["duration_s"],
+ "workflow": record["workflow"],
+ }
+ )
+ return AudioRunResponse(clips = clips, group_id = group_id, model = model_name)
+
+
@router.post("/audio/run", response_model = AudioRunResponse)
async def run_audio_workflow(
body: AudioRunRequest,
request: Request,
current_subject: str = Depends(get_current_subject),
):
- """Clone, or Speak in a saved voice, and save the clip to history. Audio is named by id and
- resolved here in the caller's account; the worker gets a prepared copy's path, never bytes."""
+ """Run one Audio page workflow (Clone, Speak in a saved voice, or Music); clips go to history.
+ Audio is named by id and resolved here in the caller's account; the worker gets a prepared
+ copy's path, never bytes."""
import base64
from core.inference import audio_inputs
+ if body.workflow == "music":
+ return await _run_music_workflow(body, request, current_subject)
+ music_fields = sorted(
+ name
+ for name in _MUSIC_ONLY_FIELDS
+ if name in body.model_fields_set and getattr(body, name) not in (None, False, 1)
+ )
+ if music_fields or body.inputs.source is not None:
+ raise HTTPException(
+ status_code = 400,
+ detail = "A music mode, lyrics, variations, a source clip and edits apply to Music only.",
+ )
+
if body.workflow == "clone" and body.inputs.reference is None:
raise HTTPException(status_code = 400, detail = "Add a reference clip to clone.")
prepared = {}
diff --git a/studio/backend/tests/test_audio_cpp_models.py b/studio/backend/tests/test_audio_cpp_models.py
index 7c9366af912..c93555cf05e 100644
--- a/studio/backend/tests/test_audio_cpp_models.py
+++ b/studio/backend/tests/test_audio_cpp_models.py
@@ -1660,7 +1660,7 @@ def test_package_mixes_show_only_the_studio_option_list():
"semantic_top_k",
]
# Other families still follow the runtime's spec.
- assert [o["name"] for o in acm.option_schema(acm.FAMILIES["ace_step"], runtime, None)] == [
+ assert [o["name"] for o in acm.option_schema(acm.FAMILIES["heartmula"], runtime, None)] == [
"cot",
"abc_temperature",
"semantic_penalty_window",
diff --git a/studio/backend/tests/test_audio_cpp_music_requests.py b/studio/backend/tests/test_audio_cpp_music_requests.py
new file mode 100644
index 00000000000..7dfd5e3ab21
--- /dev/null
+++ b/studio/backend/tests/test_audio_cpp_music_requests.py
@@ -0,0 +1,650 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Music studio requests to audiocpp_server, per family and mode, against a recording fake server.
+
+Strict specs (schema_version) refuse undeclared options, so their bodies carry only declared keys:
+MiDashengLM and ControlFoley take ``duration_sec``, never ``duration_seconds`` (finding 7).
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import wave
+from dataclasses import replace
+from pathlib import Path
+
+import pytest
+
+from core.inference import audio_cpp_backend, audio_cpp_files, audio_cpp_music as cm
+from core.inference import audio_cpp_models as acm
+from core.inference.audio_cpp_models import AUDIO_CPP_REPO, AudioCppVariant, RepoFile
+
+STRICT_KEYS = {
+ "heartmula": frozenset(
+ {
+ "lyrics",
+ "tags",
+ "duration_sec",
+ "temperature",
+ "top_k",
+ "guidance_scale",
+ "codec_duration_sec",
+ "num_inference_steps",
+ "codec_guidance_scale",
+ "infinite_mode",
+ "text_chunk_size",
+ "infinite_chunk_audio_duration_ms",
+ "seed",
+ }
+ ),
+ "midashenglm_gen": frozenset(
+ {"duration_sec", "guidance_scale", "stop_threshold", "min_stop_step", "seed"}
+ ),
+ "controlfoley": frozenset(
+ {
+ "duration_sec",
+ "num_inference_steps",
+ "guidance_scale",
+ "negative_prompt",
+ "video",
+ "mask_away_clip",
+ "seed",
+ }
+ ),
+ "minimax_music3": frozenset(
+ {
+ "lyrics",
+ "duration_sec",
+ "num_inference_steps",
+ "guidance_scale",
+ "ar_guidance_scale",
+ "top_k",
+ "seed",
+ }
+ ),
+ "yue2": frozenset(
+ {
+ "style",
+ "lyrics",
+ "cot",
+ "guidance_scale",
+ "seed",
+ "num_inference_steps",
+ "semantic_temperature",
+ "semantic_top_p",
+ "semantic_top_k",
+ "semantic_min_tokens",
+ "semantic_max_tokens",
+ }
+ ),
+}
+FOLDERS = {
+ "ace_step": "ACE-Step1.5-GGUF",
+ "stable_audio": "Stable-Audio-3-Small-Music-GGUF",
+ "heartmula": "HeartMuLa-GGUF",
+ "midashenglm_gen": "MiDashengLM-Gen-GGUF",
+ "controlfoley": "ControlFoley-GGUF",
+ "minimax_music3": "MiniMax-Music3-GGUF",
+ "yue2": "Yue2-3B-GGUF",
+}
+
+
+def _wav(
+ seconds = 0.1,
+ rate = 44100,
+ channels = 2,
+ fill = 0,
+) -> bytes:
+ buf = io.BytesIO()
+ with wave.open(buf, "wb") as w:
+ w.setnchannels(channels)
+ w.setsampwidth(2)
+ w.setframerate(rate)
+ w.writeframes(bytes([fill, 0]) * int(seconds * rate) * channels)
+ return buf.getvalue()
+
+
+def _reply(n = 1):
+ takes = [_wav(fill = i + 1) for i in range(n)]
+ body = {
+ "audio": base64.b64encode(takes[0]).decode(),
+ "named_audio_outputs": [
+ {"id": f"audio_{i}", "audio": base64.b64encode(t).decode()} for i, t in enumerate(takes)
+ ],
+ }
+ return "application/json", json.dumps(body).encode()
+
+
+def _model(
+ family,
+ folder = None,
+ strict = True,
+ spec_options = (),
+):
+ folder = folder or FOLDERS[family]
+ policy = acm.family_policy(family, None, (folder,))
+ files = (RepoFile(f"{folder}/{folder.lower()}-q8_0.gguf", 4),)
+ variant = AudioCppVariant("Q8_0", files, files[0].path)
+ return acm.AudioCppModel(
+ id = f"{AUDIO_CPP_REPO}/{folder}",
+ repo_id = AUDIO_CPP_REPO,
+ folder = folder,
+ display_name = folder,
+ family = family,
+ task = "music",
+ server_task = "gen",
+ variant = variant,
+ variants = (variant,),
+ default_variant = "Q8_0",
+ options = acm.option_schema(policy, {"options": {"request": list(spec_options)}}, None),
+ music = acm.music_with_spec_bounds(policy.music, list(spec_options)),
+ request_keys = STRICT_KEYS.get(family) if strict else None,
+ )
+
+
+class _Server:
+ def __init__(
+ self,
+ model,
+ replies = None,
+ backend = "cuda",
+ ):
+ self.model = model
+ self.model_id = "studio-test"
+ self.backend = backend
+ self.replies = list(replies or [])
+ self.calls: list[tuple[str, dict, dict]] = []
+
+ def alive(self):
+ return True
+
+ def post_json(self, path, payload, **kwargs):
+ self.calls.append((path, json.loads(json.dumps(payload)), kwargs))
+ return self.replies.pop(0) if self.replies else _reply()
+
+ def stop(self):
+ pass
+
+
+def starts(monkeypatch):
+ """Server (re)starts, recorded with the session options each was given."""
+ started: list[dict] = []
+
+ def start(served, model_path, **_kw):
+ started.append(dict((served.model_options or {}).get("session_options") or {}))
+ return _Server(served)
+
+ monkeypatch.setattr(audio_cpp_backend.AudioCppServer, "start", staticmethod(start))
+ monkeypatch.setattr(audio_cpp_files, "materialize", lambda model: "/models/x.gguf")
+ return started
+
+
+def _backend(
+ model,
+ replies = None,
+ backend = "cuda",
+):
+ b = audio_cpp_backend.AudioCppBackend()
+ b._server = _Server(model, replies, backend)
+ b._model = model
+ b.models = {model.id: {"is_audio": True, "audio_type": model.audio_type}}
+ b.active_model_name = model.id
+ return b
+
+
+def _run(
+ b,
+ seed = 7,
+ output_dir = None,
+ options = None,
+ source = None,
+ **music,
+):
+ music.setdefault("mode", "song")
+ return b.generate_audio_response(
+ music.get("text", ""),
+ seed = seed,
+ workflow = "music",
+ music = music,
+ audio_options = options,
+ audio_inputs = {"source": source} if source else None,
+ output_dir = output_dir,
+ )
+
+
+def _request(b, index = 0):
+ path, body, _kw = b._server.calls[index]
+ assert path == "/v1/tasks/run" and body["model"] == "studio-test"
+ return body["request"]
+
+
+def _keys(node):
+ """Every key anywhere in a request body."""
+ if isinstance(node, dict):
+ for key, value in node.items():
+ yield key
+ yield from _keys(value)
+
+
+def test_each_music_family_offers_its_modes():
+ modes = lambda family, folder = None: [m.id for m in _model(family, folder).music.modes]
+ assert modes("ace_step") == ["song", "edit"]
+ assert modes("stable_audio") == ["song", "edit"]
+ assert modes("stable_audio", "Stable-Audio-3-Small-SFX-GGUF") == ["sfx"]
+ assert modes("stable_audio", "Stable-Audio-3-Medium-GGUF") == ["song", "sfx", "edit"]
+ assert modes("heartmula") == ["song"]
+ assert modes("midashenglm_gen") == ["song", "sfx"]
+ assert modes("controlfoley") == ["sfx"]
+ assert modes("minimax_music3") == ["song"]
+ assert modes("yue2") == ["song"]
+ assert acm.family_policy("kokoro_tts").music is None
+
+
+def test_spec_duration_bounds_narrow_the_table():
+ mida = _model(
+ "midashenglm_gen",
+ spec_options = [{"name": "duration_sec", "type": "float", "min": 0.04, "max": 163.84}],
+ )
+ assert mida.music.mode("song").duration == (1.0, 80.0, 30.0)
+ assert mida.music.mode("sfx").duration == (1.0, 80.0, 10.0)
+ foley = _model(
+ "controlfoley",
+ spec_options = [{"name": "duration_sec", "type": "float", "min": 0.64, "max": 60.0}],
+ )
+ assert foley.music.mode("sfx").duration == (1.0, 60.0, 8.0)
+ narrow = _model("ace_step", spec_options = [{"name": "duration_sec", "type": "float", "max": 20}])
+ assert narrow.music.mode("song").duration == (5.0, 20.0, 20.0)
+
+
+def test_request_keys_come_from_strict_specs_only():
+ strict = {
+ "schema_version": 1,
+ "options": {"request": [{"name": "duration_sec"}, {"name": "seed"}]},
+ }
+ assert acm._request_keys(strict, None) == frozenset({"duration_sec", "seed"})
+ assert acm._request_keys({"tasks": ["music"]}, None) is None
+ assert acm._request_keys(None, None) is None
+ assert acm._request_keys({"schema_version": 1, "options": {"request": []}}, None) is None
+ assert acm._request_keys(None, strict) == frozenset({"duration_sec", "seed"})
+
+
+def test_status_reports_the_music_studio_rules():
+ ace = audio_cpp_backend.model_info_fields(_model("ace_step", strict = False))["audio_music"]
+ song, edit = ace["modes"]
+ assert song == {
+ "id": "song",
+ "lyrics": "optional",
+ "description": "required",
+ "instrumental": "toggle",
+ "section_case": "lower",
+ "duration": {"min": 5.0, "max": 240.0, "default": 30.0, "approximate": False},
+ "variations": None,
+ }
+ assert edit == {
+ "id": "edit",
+ "actions": ["repaint", "extend", "cover"],
+ "max_ranges": 1,
+ "max_source_s": 240.0,
+ }
+ # Upstream ACE-Step 1.5 offers "complete" and 1-200 steps on base only; turbo keeps 1-20.
+ base = _ace_base()
+ assert audio_cpp_backend.model_info_fields(base)["audio_music"]["modes"][1]["actions"] == [
+ "repaint",
+ "extend",
+ "cover",
+ "continue",
+ ]
+ steps = {o["name"]: o for o in base.options}["num_inference_steps"]
+ assert (steps["max"], steps["default"]) == (200, 32)
+ turbo = base.with_variant(AudioCppVariant("turbo/Q8_0", (), "ACE-Step1.5-GGUF/turbo/t.gguf"))
+ assert "continue" not in turbo.music.mode("edit").actions
+ assert {o["name"]: o for o in turbo.options}["num_inference_steps"]["max"] == 20
+ stable = cm.music_rules(_model("stable_audio", "Stable-Audio-3-Medium-GGUF", strict = False))
+ assert [m["id"] for m in stable["modes"]] == ["song", "sfx", "edit"]
+ assert stable["modes"][0]["variations"] == {"max": 4, "how": "batch", "loaded": 1}
+ assert stable["modes"][1]["duration"]["default"] == 8.0
+ assert stable["modes"][2]["actions"] == ["inpaint", "restyle"]
+ assert stable["modes"][2]["max_ranges"] == 8
+ # Medium keeps Studio's 240 s; Small cannot return more than its ~120 s window.
+ assert stable["modes"][0]["duration"]["max"] == 240.0
+ assert stable["modes"][2]["max_source_s"] == 240.0
+ small = cm.music_rules(_model("stable_audio", "Stable-Audio-3-Small-Music-GGUF", strict = False))
+ assert small["modes"][0]["duration"]["max"] == 120.0
+ assert small["modes"][1]["max_source_s"] == 120.0
+ assert cm.music_rules(_model("controlfoley"))["modes"][0]["variations"] == {
+ "max": 4,
+ "how": "sequential",
+ "loaded": 4,
+ }
+ minimax = cm.music_rules(_model("minimax_music3"))["modes"][0]
+ assert minimax["duration"]["approximate"] and minimax["lyrics"] == "required"
+ yue = cm.music_rules(_model("yue2"))["modes"][0]
+ assert (yue["section_case"], yue["instrumental"]) == ("title", "toggle")
+ assert cm.music_rules(_model("heartmula"))["modes"][0]["instrumental"] == "never"
+ speech = replace(_model("ace_step"), task = "tts", music = None)
+ assert audio_cpp_backend.model_info_fields(speech)["audio_music"] is None
+
+
+def test_midashenglm_and_controlfoley_send_duration_sec_never_duration_seconds():
+ for family, mode in (
+ ("midashenglm_gen", "sfx"),
+ ("controlfoley", "sfx"),
+ ("midashenglm_gen", "song"),
+ ):
+ b = _backend(_model(family))
+ _run(b, mode = mode, text = "rain on a tin roof", duration_s = 12, lyrics = "la la")
+ request = _request(b)
+ assert "duration_seconds" not in set(_keys(request)), family
+ assert "lyrics" not in set(_keys(request)), family
+ assert request == {
+ "text": "rain on a tin roof",
+ "options": {"duration_sec": 12.0},
+ "seed": "7",
+ }, family
+
+
+def test_undeclared_and_edit_only_options_never_reach_a_strict_spec():
+ b = _backend(_model("controlfoley"))
+ _run(
+ b,
+ mode = "sfx",
+ text = "glass",
+ options = {"foo": 1, "route": "repaint", "batch_size": "4", "guidance_scale": 3.0},
+ )
+ assert _request(b) == {"text": "glass", "options": {"duration_sec": 8.0}, "seed": "7"}
+
+
+def test_heartmula_takes_its_description_as_tags():
+ b = _backend(_model("heartmula"))
+ _run(b, text = "pop, female vocal", lyrics = "[verse] hi", duration_s = 20)
+ assert _request(b) == {
+ "text": "pop, female vocal",
+ "options": {"tags": "pop, female vocal", "duration_sec": 20.0, "lyrics": "[verse] hi"},
+ "seed": "7",
+ }
+
+
+def test_yue2_instrumental_sends_the_instrumental_tag_not_its_style():
+ b = _backend(_model("yue2"))
+ _run(b, text = "ambient piano", lyrics = "[Verse] words", instrumental = True, duration_s = 20)
+ request = _request(b)
+ assert request["text"] == "[Instrumental]"
+ assert request["options"]["lyrics"] == "[Instrumental]"
+ assert request["options"]["style"] == "ambient piano"
+ assert request["options"]["semantic_max_tokens"] == 500
+
+
+def test_minimax_gguf_keeps_its_body_through_the_studio():
+ b = _backend(_model("minimax_music3"))
+ _run(b, text = "lofi", lyrics = "[verse] hi", duration_s = 20, seed = 3)
+ request = _request(b)
+ assert request == {
+ "text": "lofi",
+ "lyrics": "[verse] hi",
+ "duration_seconds": 20.0,
+ "options": {"lyrics": "[verse] hi"},
+ "seed": "3",
+ }
+ assert "duration_sec" not in set(_keys(request))
+
+
+def test_ace_step_song_and_instrumental():
+ b = _backend(_model("ace_step", strict = False))
+ _run(
+ b,
+ text = "synth pop",
+ lyrics = "[verse] la",
+ duration_s = 45,
+ options = {"bpm": 100, "timesignature": "3"},
+ )
+ assert _request(b) == {
+ "text": "synth pop",
+ "duration_seconds": 45.0,
+ "lyrics": "[verse] la",
+ "options": {"bpm": 100, "timesignature": "3"},
+ "seed": "7",
+ }
+ _run(b, text = "synth pop", lyrics = "[verse] la", instrumental = True)
+ request = _request(b, 1)
+ assert request["lyrics"] == "[Instrumental]" and request["duration_seconds"] == 30.0
+
+
+def test_durations_clamp_to_the_mode():
+ b = _backend(_model("stable_audio", strict = False))
+ _run(b, text = "house", duration_s = 500)
+ assert _request(b)["duration_seconds"] == 120.0
+
+
+def test_stable_audio_batches_variations_as_a_string(starts, tmp_path):
+ model = _model("stable_audio", strict = False)
+ b = _backend(model)
+ run = tmp_path / "run"
+ run.mkdir()
+ wav, rate = _run(b, text = "house", duration_s = 6, variations = 3, seed = None, output_dir = str(run))
+ request = b._server.calls[0][1]["request"]
+ assert request["options"] == {"batch_size": "3"} and "seed" not in request
+ assert rate == 44100 and wav[:4] == b"RIFF"
+ manifest = json.loads((run / "outputs.json").read_text())
+ assert [m["id"] for m in manifest] == ["audio_0"] # the fake answers one take
+ assert manifest[0]["file"] == "00.wav" and manifest[0]["sample_rate"] == 44100
+
+
+def test_max_batch_reloads_once_and_only_when_needed(starts):
+ model = _model("stable_audio", strict = False)
+ b = _backend(model)
+ _run(b, text = "house", variations = 1)
+ assert starts == [] and b.take_status_patch() is None
+ _run(b, text = "house", variations = 3)
+ assert starts == [{"stable_audio.max_batch": "4"}]
+ patch = b.take_status_patch()
+ assert patch["audio_music"]["modes"][0]["variations"]["loaded"] == 4
+ assert b.models[model.id]["audio_music"] == patch["audio_music"]
+ assert b.take_status_patch() is None
+ _run(b, text = "house", variations = 2)
+ _run(b, text = "house", variations = 1)
+ assert len(starts) == 1 and b.take_status_patch() is None
+ b._server.alive = lambda: False
+ _run(b, text = "house", variations = 4)
+ assert starts[-1] == {"stable_audio.max_batch": "4"}
+ assert b.take_status_patch() is None
+
+
+def test_too_many_variations_fail_before_any_call(starts):
+ b = _backend(_model("stable_audio", strict = False))
+ with pytest.raises(RuntimeError, match = "at most 4"):
+ _run(b, text = "house", variations = 5)
+ assert b._server.calls == [] and starts == []
+ one = _backend(_model("ace_step", strict = False))
+ with pytest.raises(RuntimeError, match = "at most 1"):
+ _run(one, text = "x", variations = 2)
+
+
+def test_sequential_variations_call_once_per_take_with_consecutive_seeds(tmp_path):
+ b = _backend(_model("controlfoley"))
+ run = tmp_path / "run"
+ _run(b, mode = "sfx", text = "door", variations = 3, seed = 40, output_dir = str(run))
+ assert [_request(b, i)["seed"] for i in range(3)] == ["40", "41", "42"]
+ manifest = json.loads((run / "outputs.json").read_text())
+ assert [(m["id"], m["seed"], m["file"]) for m in manifest] == [
+ ("take_0", 40, "00.wav"),
+ ("take_1", 41, "01.wav"),
+ ("take_2", 42, "02.wav"),
+ ]
+ assert all((run / m["file"]).is_file() for m in manifest)
+ # The top valid seed wraps instead of passing MiDashengLM's 2**31 - 1 limit.
+ top = _backend(_model("midashenglm_gen"))
+ _run(top, mode = "sfx", text = "rain", variations = 2, seed = 2**31 - 1)
+ assert [_request(top, i)["seed"] for i in range(2)] == [str(2**31 - 1), "0"]
+
+
+def test_a_fixed_seed_family_gets_a_recorded_random_seed(tmp_path):
+ b = _backend(_model("heartmula"))
+ _run(b, text = "pop", lyrics = "la", seed = None, output_dir = str(tmp_path))
+ seed = int(_request(b)["seed"])
+ assert 0 <= seed < 2**31
+ assert json.loads((tmp_path / "outputs.json").read_text())[0]["seed"] == seed
+ sa = _backend(_model("stable_audio", strict = False))
+ _run(sa, text = "house", seed = None)
+ assert "seed" not in _request(sa)
+
+
+def test_the_wait_grows_with_the_audio_asked_for_and_is_capped():
+ t = lambda s, n = 1, cpu = False: cm.timeout_seconds("yue2", s, n, cpu)
+ assert t(10) < t(60) < t(60, 3) < t(60, 3, cpu = True)
+ assert t(0) == 300.0 and t(240, 4, cpu = True) == 4 * 3600.0
+ assert cm.timeout_seconds("stable_audio", 10, 1, False) == 310.0
+ b = _backend(_model("yue2"))
+ _run(b, text = "rock", lyrics = "x", duration_s = 60)
+ assert b._server.calls[0][2]["timeout"] == t(60)
+ # The route's budget covers work the backend cannot see (extend, continue length).
+ b = _backend(_model("yue2"))
+ _run(b, text = "rock", lyrics = "x", duration_s = 60, timeout_s = 1234.0)
+ assert b._server.calls[0][2]["timeout"] == 1234.0
+
+
+def source(tmp_path) -> str:
+ path = tmp_path / "source.48000.stereo.wav"
+ path.write_bytes(_wav(seconds = 10.0, rate = 48000))
+ return str(path)
+
+
+def test_ace_step_repaint_has_no_duration_and_may_pass_the_end(source):
+ b = _backend(_model("ace_step", strict = False))
+ _run(
+ b,
+ mode = "edit",
+ text = "brighter",
+ source = source,
+ edit = {"action": "repaint", "ranges": [{"start_s": 5.0, "end_s": 14.0}], "strength": 0.4},
+ )
+ request = _request(b)
+ assert request == {
+ "text": "brighter",
+ "audio": source,
+ "options": {
+ "route": "repaint",
+ "repainting_start": 5.0,
+ "repainting_end": 14.0,
+ "repaint_strength": 0.4,
+ },
+ "seed": "7",
+ }
+ assert "duration_seconds" not in set(_keys(request))
+
+
+def _ace_base():
+ return _model("ace_step", strict = False).with_variant(
+ AudioCppVariant("base/Q8_0", (), "ACE-Step1.5-GGUF/base/b.gguf")
+ )
+
+
+def test_ace_step_extend_cover_and_continue(source):
+ b = _backend(_ace_base())
+ _run(b, mode = "edit", text = "outro", source = source, edit = {"action": "extend", "extend_s": 12.0})
+ assert _request(b, 0)["options"] == {
+ "route": "repaint",
+ "repainting_start": 10.0,
+ "repainting_end": 22.0,
+ }
+ # strength is how much to change, so a light cover keeps most source-conditioned steps.
+ _run(b, mode = "edit", text = "jazz", source = source, edit = {"action": "cover", "strength": 0.25})
+ assert _request(b, 1)["options"] == {"route": "cover", "audio_cover_strength": 0.75}
+ _run(
+ b, mode = "edit", text = "add drums", source = source, duration_s = 30, edit = {"action": "continue"}
+ )
+ assert _request(b, 2)["options"] == {"route": "complete", "duration_seconds": 30.0}
+
+
+def test_stable_audio_inpaint_sorts_and_merges_ranges(source):
+ b = _backend(_model("stable_audio", strict = False))
+ ranges = [
+ {"start_s": 5.0, "end_s": 6.5},
+ {"start_s": 1.0, "end_s": 2.0},
+ {"start_s": 1.5, "end_s": 1.8},
+ {"start_s": 9.5, "end_s": 30.0},
+ ]
+ _run(
+ b,
+ mode = "edit",
+ text = "add birds",
+ source = source,
+ edit = {"action": "inpaint", "ranges": ranges},
+ )
+ request = _request(b)
+ assert request["options"] == {
+ "audio_input_kind": "inpaint_audio",
+ "inpaint_mask_start_seconds": "1,5,9.5",
+ "inpaint_mask_end_seconds": "2,6.5,10",
+ }
+ assert request["duration_seconds"] == 10.0 and request["audio"] == source
+
+
+def test_stable_audio_restyle_sends_init_noise(source):
+ b = _backend(_model("stable_audio", strict = False))
+ _run(b, mode = "edit", text = "lofi", source = source, edit = {"action": "restyle", "strength": 0.45})
+ assert _request(b)["options"] == {"audio_input_kind": "init_audio", "init_noise_level": 0.45}
+
+
+def test_an_edit_the_family_does_not_offer_fails_before_any_call(source):
+ b = _backend(_model("stable_audio", strict = False))
+ with pytest.raises(RuntimeError, match = "cannot repaint"):
+ _run(b, mode = "edit", text = "x", source = source, edit = {"action": "repaint", "ranges": []})
+ with pytest.raises(RuntimeError, match = "does not offer"):
+ _run(_backend(_model("heartmula")), mode = "edit", text = "x", source = source, edit = {})
+ assert b._server.calls == []
+
+
+def test_merge_ranges():
+ assert cm.merge_ranges([(3, 4), (1, 2), (1.5, 3.5)], 10) == [(1.0, 4.0)]
+ assert cm.merge_ranges([(-1, 2), (8, 12), (12, 13)], 10) == [(0.0, 2.0), (8.0, 10.0)]
+
+
+def test_the_runtime_refusal_is_typed_for_the_route():
+ from core.inference.audio_cpp_server import AudioCppRequestError
+ from core.inference.audio_errors import AudioRuntimeError
+
+ b = _backend(_model("controlfoley"))
+
+ def refuse(path, payload, **kwargs):
+ raise AudioCppRequestError(400, "unknown controlfoley request option: foo")
+
+ b._server.post_json = refuse
+ with pytest.raises(AudioRuntimeError, match = "unknown controlfoley"):
+ _run(b, mode = "sfx", text = "door")
+
+
+def test_legacy_requests_keep_their_bodies_with_the_finding_7_fixes():
+ b = _backend(_model("midashenglm_gen"))
+ b.generate_audio_response("wind", max_new_tokens = 250)
+ assert _request(b) == {"text": "wind", "options": {"duration_sec": 10.0}}
+ hm = _backend(_model("heartmula"))
+ hm.generate_audio_response("[verse] hi", instructions = "pop", max_new_tokens = 500)
+ assert _request(hm) == {
+ "text": "pop",
+ "options": {"tags": "pop", "duration_sec": 20.0, "lyrics": "[verse] hi"},
+ }
+ yue = _backend(_model("yue2"))
+ yue.generate_audio_response("", instructions = "ambient")
+ assert _request(yue)["options"]["lyrics"] == "[Instrumental]"
+ assert "ambient" not in _request(yue)["text"]
+
+
+def test_paths_in_the_manifest_are_bare_names(tmp_path):
+ b = _backend(_model("controlfoley"))
+ _run(b, mode = "sfx", text = "door", variations = 2, output_dir = str(tmp_path))
+ for entry in json.loads((tmp_path / "outputs.json").read_text()):
+ assert Path(entry["file"]).name == entry["file"]
+
+
+def test_legacy_music_never_asks_past_the_page_maximum():
+ b = _backend(_model("midashenglm_gen"))
+ b.generate_audio_response("relaxing piano", instructions = "relaxing piano", max_new_tokens = 2048)
+ assert _request(b)["options"]["duration_sec"] == 80.0
+ medium = _backend(_model("stable_audio", "Stable-Audio-3-Medium-GGUF", strict = False))
+ medium.generate_audio_response("ambient", instructions = "ambient", max_new_tokens = 4500)
+ assert _request(medium)["duration_seconds"] == 180.0
diff --git a/studio/backend/tests/test_audio_run_route.py b/studio/backend/tests/test_audio_run_route.py
index e3dd4cb6e94..dba276d82af 100644
--- a/studio/backend/tests/test_audio_run_route.py
+++ b/studio/backend/tests/test_audio_run_route.py
@@ -217,7 +217,6 @@ def test_a_clone_run_hands_the_worker_an_account_path_and_saves_the_clip(stub, t
{"options": {"video": "/etc/passwd"}}, # ControlFoley
{"options": {"reference_image": "/etc/passwd"}},
{"options": {"nested": {"a": 1}}},
- {"workflow": "music"},
{"workflow": "transcribe"},
{"text": ""},
],
@@ -471,6 +470,424 @@ def test_the_worker_forwards_clone_fields_only_when_present():
assert not CLONE_FIELDS & set(seen[1])
+def _alice_sources():
+ input_id = _input(ALICE)
+ clip = run_as(
+ ALICE,
+ audio_gallery.save,
+ _wav(),
+ {
+ "prompt": "alice said",
+ "model": "m",
+ "audio_type": "audiocpp_tts",
+ "sample_rate": 24000,
+ "duration_s": 0.1,
+ "created_at": "2026-10-02T00:00:00Z",
+ },
+ )
+ voice = _voice(ALICE, input_id)
+ return {"input_id": input_id, "clip_id": clip["id"], "voice_id": voice["id"]}
+
+
+STABLE_AUDIO = "audio-cpp/audio.cpp-gguf/Stable-Audio-3-Small-Music-GGUF"
+ACE_STEP = "audio-cpp/audio.cpp-gguf/ACE-Step1.5-GGUF"
+
+
+def _music_info(family = "stable_audio", folder = "Stable-Audio-3-Small-Music-GGUF"):
+ from types import SimpleNamespace
+
+ from core.inference import audio_cpp_music
+ from core.inference.audio_cpp_models import family_policy
+
+ policy = family_policy(family, None, (folder,))
+ model = SimpleNamespace(music = policy.music, task = "music")
+ return {
+ "is_audio": True,
+ "audio_type": "audiocpp_music",
+ "audio_family": family,
+ "audio_workflows": ["music"],
+ "audio_reference_text": None,
+ "audio_required_inputs": [],
+ "audio_music": audio_cpp_music.music_rules(model),
+ "audio_cpp_backend": "cuda",
+ }
+
+
+class _MusicBackend(_Backend):
+ """Writes ``takes`` outputs and the manifest into the run folder, as the worker does."""
+
+ def __init__(
+ self,
+ name,
+ info,
+ takes = 1,
+ ):
+ super().__init__(name, info)
+ self.takes = takes
+ self.run_dirs: list[Path] = []
+
+ def generate_audio_response(self, **kwargs):
+ self.calls.append(kwargs)
+ out = Path(kwargs["output_dir"])
+ self.run_dirs.append(out)
+ manifest = []
+ for index in range(self.takes):
+ name = f"{index:02d}.wav"
+ (out / name).write_bytes(_wav(rate = 44100, frames = 4410 * (index + 1)))
+ manifest.append(
+ {"id": f"audio_{index}", "file": name, "sample_rate": 44100, "seed": 40 + index}
+ )
+ (out / "outputs.json").write_text(json.dumps(manifest), encoding = "utf-8")
+ return _wav(rate = 44100), 44100
+
+
+def _music(client, **body):
+ payload = {"workflow": "music", "mode": "song", "text": "uplifting house", **body}
+ return client.post("/api/inference/audio/run", json = payload)
+
+
+def test_music_variations_are_saved_as_one_group(stub, tmp_path):
+ backend = stub["use"](STABLE_AUDIO, _music_info())
+ backend.__class__ = _MusicBackend
+ backend.takes, backend.run_dirs = 3, []
+ with _client(ALICE) as client:
+ response = _music(client, duration_s = 10, variations = 3, options = {"sampler": "euler"})
+ assert response.status_code == 200, response.text
+ listing = client.get("/api/inference/audio/gallery").json()
+ body = response.json()
+ assert len(body["clips"]) == 3 and body["group_id"]
+ assert [c["role"] for c in body["clips"]] == ["variation"] * 3
+ assert {c["workflow"] for c in body["clips"]} == {"music"}
+ (call,) = backend.calls
+ assert call["workflow"] == "music" and "audio_inputs" not in call
+ music = call["music"]
+ assert (music["mode"], music["duration_s"], music["variations"]) == ("song", 10.0, 3)
+ assert music["timeout_s"] >= 300 and call["max_new_tokens"] >= 750
+ (run_dir,) = backend.run_dirs
+ inputs_root = tmp_path / "accounts" / ALICE.account_id / "audio" / "inputs"
+ assert run_dir.parent == inputs_root / "runs" and not run_dir.exists()
+ metas = [json.loads(_sidecar(tmp_path, c["id"])) for c in body["clips"]]
+ assert {m["group_id"] for m in metas} == {body["group_id"]}
+ assert [m["settings"]["variation"] for m in metas] == [1, 2, 3]
+ assert [m["settings"]["seed"] for m in metas] == [40, 41, 42]
+ assert metas[0]["settings"]["mode"] == "song" and metas[0]["settings"]["duration_s"] == 10.0
+ assert metas[0]["settings"]["options"] == {"sampler": "euler"}
+ # Stable Audio always plays instrumental and ignores lyrics; history says what ran.
+ assert (metas[0]["settings"]["instrumental"], metas[0]["settings"]["lyrics"]) == (True, None)
+ items = {i["id"]: i for i in listing["audio"]}
+ for clip in body["clips"]:
+ assert items[clip["id"]]["group_id"] == body["group_id"]
+ assert items[clip["id"]]["role"] == "variation"
+ assert items[clip["id"]]["settings"]["mode"] == "song"
+ assert str(tmp_path) not in json.dumps(listing)
+ for clip in body["clips"]:
+ sidecar = _sidecar(tmp_path, clip["id"])
+ assert str(tmp_path) not in sidecar and "runs" not in sidecar
+
+
+def test_a_single_take_is_an_output_with_no_group(stub, tmp_path):
+ backend = stub["use"](STABLE_AUDIO, _music_info())
+ backend.__class__ = _MusicBackend
+ backend.takes, backend.run_dirs = 1, []
+ with _client(ALICE) as client:
+ response = _music(client)
+ body = response.json()
+ assert response.status_code == 200 and body["group_id"] is None
+ assert [c["role"] for c in body["clips"]] == ["output"]
+ assert backend.calls[0]["music"]["duration_s"] == 30.0
+
+
+def test_a_manifest_entry_outside_the_run_folder_is_never_read(stub, tmp_path):
+ backend = stub["use"](STABLE_AUDIO, _music_info())
+ secret = tmp_path / "secret.wav"
+ secret.write_bytes(_wav(rate = 8000))
+
+ def escape(**kwargs):
+ backend.calls.append(kwargs)
+ out = Path(kwargs["output_dir"])
+ manifest = [{"id": "x", "file": "../../../../secret.wav"}, {"id": "y", "file": str(secret)}]
+ (out / "outputs.json").write_text(json.dumps(manifest), encoding = "utf-8")
+ return _wav(rate = 44100), 44100
+
+ backend.generate_audio_response = escape
+ with _client(ALICE) as client:
+ response = _music(client)
+ body = response.json()
+ assert response.status_code == 200 and len(body["clips"]) == 1
+ assert body["clips"][0]["sample_rate"] == 44100
+
+
+def _edit(
+ client,
+ source,
+ action = "inpaint",
+ ranges = None,
+ **body,
+):
+ edit = {
+ "action": action,
+ "ranges": ranges if ranges is not None else [{"start_s": 0.02, "end_s": 0.08}],
+ }
+ edit.update(body.pop("edit", {}))
+ return _music(
+ client, mode = "edit", text = "add birds", inputs = {"source": source}, edit = edit, **body
+ )
+
+
+def test_an_edit_prepares_the_source_at_the_family_rate(stub, tmp_path):
+ backend = stub["use"](STABLE_AUDIO, _music_info())
+ backend.__class__ = _MusicBackend
+ backend.takes, backend.run_dirs = 1, []
+ sources = _alice_sources()
+ with _client(ALICE) as client:
+ response = _edit(client, {"clip_id": sources["clip_id"]})
+ assert response.status_code == 200, response.text
+ (call,) = backend.calls
+ source = Path(call["audio_inputs"]["source"])
+ assert source.parent == tmp_path / "accounts" / ALICE.account_id / "audio" / "inputs"
+ info = audio_inputs.wav_info(source)
+ assert (info["sample_rate"], info["channels"]) == (44100, 2)
+ clip = response.json()["clips"][0]
+ assert clip["role"] == "edit"
+ meta = json.loads(_sidecar(tmp_path, clip["id"]))
+ assert meta["source_clip_id"] == sources["clip_id"]
+ assert meta["settings"]["edit"]["action"] == "inpaint"
+ assert meta["settings"]["edit"]["ranges"] == [{"start_s": 0.02, "end_s": 0.08}]
+
+
+ "body, detail",
+ [
+ ({"mode": "sfx"}, "does not make sound effects"),
+ ({"variations": 5}, None),
+ ({"inputs": {"reference": {"input_id": "a" * 32}}}, "not a voice reference"),
+ ({"inputs": {"reference_text": "hi"}}, "not a voice reference"),
+ ({"edit": {"action": "inpaint"}}, "apply to Edit only"),
+ ({"mode": "edit"}, "Add a clip to edit"),
+ ({"text": ""}, "needs a description"),
+ ],
+)
+def test_music_refusals_name_the_fix(stub, body, detail):
+ stub["use"](STABLE_AUDIO, _music_info())
+ with _client(ALICE) as client:
+ response = _music(client, **body)
+ if detail is None:
+ assert response.status_code == 422
+ else:
+ assert response.status_code == 400, response.text
+ assert detail in response.json()["detail"]
+ assert stub["backend"].calls == []
+
+
+def test_edit_refusals_need_the_source(stub):
+ stub["use"](STABLE_AUDIO, _music_info())
+ sources = _alice_sources()
+ clip = {"clip_id": sources["clip_id"]} # 0.1 s long
+ with _client(ALICE) as client:
+ past = _edit(client, clip, ranges = [{"start_s": 0.2, "end_s": 0.4}])
+ assert past.status_code == 400 and "after the clip ends" in past.json()["detail"]
+ empty = _edit(client, clip, ranges = [])
+ assert empty.status_code == 400 and "Select the part" in empty.json()["detail"]
+ backwards = _edit(client, clip, ranges = [{"start_s": 0.05, "end_s": 0.01}])
+ assert backwards.status_code == 422
+ repaint = _edit(client, clip, action = "repaint")
+ assert repaint.status_code == 400 and "cannot repaint" in repaint.json()["detail"]
+ voice = _edit(client, {"voice_id": sources["voice_id"]})
+ assert voice.status_code == 400 and "Saved voices" in voice.json()["detail"]
+ assert stub["backend"].calls == []
+
+
+def test_a_source_longer_than_the_model_can_return_is_refused(stub, monkeypatch):
+ stub["use"](STABLE_AUDIO, _music_info())
+ sources = _alice_sources()
+ real = audio_inputs.wav_info
+ monkeypatch.setattr(audio_inputs, "wav_info", lambda path: {**real(path), "duration_s": 121.0})
+ with _client(ALICE) as client:
+ response = _edit(client, {"clip_id": sources["clip_id"]})
+ assert response.status_code == 400
+ # Stable Audio Small returns at most ~120 s, so a longer edit would come back cut.
+ assert response.json()["detail"] == "Edit clips up to 2 minutes. Trim it first."
+ assert stub["backend"].calls == []
+
+
+def test_ace_step_extend_past_the_song_limit_is_refused(stub):
+ stub["use"](ACE_STEP, _music_info("ace_step", "ACE-Step1.5-GGUF"))
+ sources = _alice_sources()
+ with _client(ALICE) as client:
+ response = _edit(
+ client,
+ {"clip_id": sources["clip_id"]},
+ action = "extend",
+ ranges = [],
+ edit = {"extend_s": 300},
+ )
+ assert response.status_code == 400 and "Add fewer seconds" in response.json()["detail"]
+
+
+def test_ace_step_repaint_reaches_at_most_30_s_past_the_end(stub):
+ stub["use"](ACE_STEP, _music_info("ace_step", "ACE-Step1.5-GGUF"))
+ sources = _alice_sources()
+ with _client(ALICE) as client:
+ response = _edit(
+ client,
+ {"clip_id": sources["clip_id"]},
+ action = "repaint",
+ ranges = [{"start_s": 0.02, "end_s": 40.0}],
+ )
+ assert response.status_code == 400
+ assert response.json()["detail"] == "A repaint can reach at most 30 s past the end."
+
+
+def test_another_accounts_clip_is_404_for_an_edit(stub):
+ stub["use"](STABLE_AUDIO, _music_info())
+ sources = _alice_sources()
+ with _client(BOB) as client:
+ response = _edit(client, {"clip_id": sources["clip_id"]})
+ upload = _edit(client, {"input_id": sources["input_id"]})
+ assert response.status_code == 404 and upload.status_code == 404
+ assert stub["backend"].calls == []
+
+
+def test_music_on_a_speech_model_or_native_minimax_is_a_400(stub):
+ with _client(ALICE) as client:
+ response = _music(client)
+ assert response.status_code == 400 and "Music studio" in response.json()["detail"]
+ stub["use"](
+ "MiniMax/Music3",
+ {"is_audio": True, "audio_type": "minimax_music3", "audio_workflows": ["music"]},
+ )
+ with _client(ALICE) as client:
+ native = _music(client, lyrics = "la")
+ assert native.status_code == 400 and "Music studio" in native.json()["detail"]
+ assert stub["backend"].calls == []
+
+
+def test_music_fields_on_clone_or_speak_are_a_400(stub):
+ input_id = _input(ALICE)
+ with _client(ALICE) as client:
+ for extra in (
+ {"mode": "song"},
+ {"lyrics": "la"},
+ {"variations": 2},
+ {"edit": {"action": "cover"}},
+ {"inputs": {"reference": {"input_id": input_id}, "source": {"input_id": input_id}}},
+ ):
+ response = _run(client, **extra)
+ assert response.status_code == 400, extra
+ assert "Music only" in response.json()["detail"]
+ assert stub["backend"].calls == []
+
+
+def test_a_music_runtime_refusal_keeps_the_runtime_reason(stub):
+ from core.inference.audio_errors import AudioRuntimeError
+
+ backend = stub["use"](STABLE_AUDIO, _music_info())
+
+ def refuse(**_kwargs):
+ raise AudioRuntimeError(
+ "The audio runtime could not generate audio: Stable Audio inpaint regions must be finite and ordered",
+ status = 400,
+ )
+
+ backend.generate_audio_response = refuse
+ with _client(ALICE) as client:
+ response = _music(client)
+ assert response.status_code == 400
+ assert "inpaint regions must be finite" in response.json()["detail"]
+
+
+def test_the_worker_and_orchestrator_carry_music_fields_only_when_present(monkeypatch):
+ from core.inference.worker import _handle_generate_audio
+
+ seen = []
+
+ class _Backend2:
+ patch = {"audio_music": {"modes": []}}
+
+ def generate_audio_response(self, **kwargs):
+ seen.append(kwargs)
+ return _wav(), 24000
+
+ def take_status_patch(self):
+ patch, self.patch = self.patch, None
+ return patch
+
+ responses: queue.Queue = queue.Queue()
+ music = {"mode": "song", "variations": 3}
+ backend = _Backend2()
+ _handle_generate_audio(
+ backend,
+ {
+ "request_id": "r1",
+ "text": "hi",
+ "workflow": "music",
+ "music": music,
+ "output_dir": "/x/runs/1",
+ },
+ responses,
+ threading.Event(),
+ )
+ _handle_generate_audio(
+ backend, {"request_id": "r2", "text": "hi"}, responses, threading.Event()
+ )
+ assert seen[0]["music"] == music and seen[0]["output_dir"] == "/x/runs/1"
+ assert not {"music", "output_dir"} & set(seen[1])
+ sent = []
+ while not responses.empty():
+ sent.append(responses.get())
+ done = [m for m in sent if m.get("type") == "audio_done"]
+ assert done[0]["status_patch"] == {"audio_music": {"modes": []}}
+ assert "status_patch" not in done[1]
+
+
+def test_the_orchestrator_sends_music_and_merges_the_reload_status(monkeypatch):
+ from core.inference.orchestrator import InferenceOrchestrator
+
+ orchestrator = InferenceOrchestrator.__new__(InferenceOrchestrator)
+ sent = []
+ wav = base64.b64encode(_wav()).decode()
+ reloaded = {"modes": [{"id": "song", "variations": {"max": 4, "how": "batch", "loaded": 4}}]}
+
+ def read_one(*, timeout):
+ return {
+ "type": "audio_done",
+ "request_id": sent[-1]["request_id"],
+ "wav_base64": wav,
+ "sample_rate": 24000,
+ "status_patch": {"audio_music": reloaded, "is_audio": False},
+ }
+
+ class _Null:
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *_exc):
+ return False
+
+ for name, value in {
+ "_ensure_subprocess_alive": lambda: True,
+ "_send_cmd": lambda cmd: sent.append(cmd),
+ "_direct_reader": lambda _rid, _cancel = None: (read_one, lambda **_k: None, lambda: None),
+ "_reserve_worker": lambda _why: _Null(),
+ "_wait_worker_idle": lambda **_k: True,
+ "_claim_worker": lambda _cancel: None,
+ "_release_worker": lambda *_a, **_k: None,
+ }.items():
+ monkeypatch.setattr(orchestrator, name, value, raising = False)
+ orchestrator.active_model_name = "m"
+ orchestrator.models = {"m": {"is_audio": True, "audio_music": {"modes": []}}}
+ orchestrator._gen_lock = threading.Lock()
+ orchestrator._send_order_lock = threading.Lock()
+ orchestrator._unload_pending = False
+ music = {"mode": "song", "variations": 3, "timeout_s": 900.0}
+ orchestrator.generate_audio_response(
+ "", workflow = "music", music = music, output_dir = "/acct/audio/inputs/runs/abc"
+ )
+ (cmd,) = sent
+ assert cmd["music"] == music and cmd["output_dir"] == "/acct/audio/inputs/runs/abc"
+ assert orchestrator.models["m"] == {"is_audio": True, "audio_music": reloaded}
+
+
def test_the_worker_keeps_run_fields_off_a_backend_without_them():
from core.inference.worker import _handle_generate_audio
@@ -504,3 +921,21 @@ def test_the_worker_keeps_run_fields_off_a_backend_without_them():
error = replies.get_nowait()
assert error["type"] == "audio_error" and error["status"] == 400
assert seen == ["hi"]
+
+
+def test_a_repaint_past_the_end_sizes_its_work_to_the_range_end(stub):
+ backend = stub["use"](ACE_STEP, _music_info("ace_step", "ACE-Step1.5-GGUF"))
+ backend.__class__ = _MusicBackend
+ backend.takes, backend.run_dirs = 1, []
+ sources = _alice_sources()
+ with _client(ALICE) as client:
+ short = _edit(client, {"clip_id": sources["clip_id"]}, action = "repaint")
+ long = _edit(
+ client,
+ {"clip_id": sources["clip_id"]},
+ action = "repaint",
+ ranges = [{"start_s": 0.02, "end_s": 25.0}],
+ )
+ assert short.status_code == 200 and long.status_code == 200, long.text
+ first, second = backend.calls
+ assert second["music"]["timeout_s"] > first["music"]["timeout_s"]
diff --git a/studio/backend/tests/test_audio_task_outputs.py b/studio/backend/tests/test_audio_task_outputs.py
new file mode 100644
index 00000000000..9cc03ac057d
--- /dev/null
+++ b/studio/backend/tests/test_audio_task_outputs.py
@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Every WAV in a /v1/tasks/run reply, counted once (S3: top-level audio repeats audio_0)."""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import wave
+
+import pytest
+
+from core.inference import audio_cpp_backend
+from core.inference.audio_task_outputs import task_outputs, wav_header
+
+
+def _wav(
+ rate = 44100,
+ frames = 441,
+ channels = 2,
+ fill = 0,
+) -> bytes:
+ buf = io.BytesIO()
+ with wave.open(buf, "wb") as w:
+ w.setnchannels(channels)
+ w.setsampwidth(2)
+ w.setframerate(rate)
+ w.writeframes(bytes([fill, 0]) * frames * channels)
+ return buf.getvalue()
+
+
+def _b64(data: bytes) -> str:
+ return base64.b64encode(data).decode()
+
+
+def _json(payload) -> tuple[str, bytes]:
+ return "application/json", json.dumps(payload).encode()
+
+
+def test_a_batch_reply_gives_each_variation_once():
+ takes = [_wav(fill = i + 1) for i in range(3)]
+ reply = {
+ "audio": _b64(takes[0]),
+ "sample_rate": 44100,
+ "named_audio_outputs": [
+ {"id": f"audio_{i}", "audio": _b64(take), "sample_rate": 44100}
+ for i, take in enumerate(takes)
+ ],
+ }
+ outputs = task_outputs(*_json(reply))
+ assert [o[0] for o in outputs] == ["audio_0", "audio_1", "audio_2"]
+ assert [o[1] for o in outputs] == takes
+
+
+def test_audio_only_named_only_and_raw():
+ one = _wav()
+ assert task_outputs(*_json({"audio": _b64(one)})) == [("audio", one)]
+ stems = {"named_audio_outputs": [{"id": n, "audio": _b64(one)} for n in ("drums", "bass")]}
+ assert [o[0] for o in task_outputs(*_json(stems))] == ["drums", "bass"]
+ assert task_outputs("audio/wav", one) == [("audio", one)]
+ assert task_outputs("application/octet-stream", one) == [("audio", one)]
+
+
+ "reply",
+ [
+ ("application/json", b"not json"),
+ ("application/json", b'{"text": "x"}'),
+ ("application/json", b"[1, 2]"),
+ _json({"audio": _b64(b"not a wav at all")}),
+ _json({"named_audio_outputs": []}),
+ ],
+)
+def test_a_reply_without_audio_is_an_error(reply):
+ with pytest.raises(RuntimeError, match = "no audio|unreadable"):
+ task_outputs(*reply)
+
+
+def test_the_sample_rate_comes_from_the_wav_header():
+ data = _wav(rate = 48000, frames = 24000)
+ ((_id, wav),) = task_outputs(*_json({"audio": _b64(data), "sample_rate": 16000}))
+ assert wav_header(wav) == (48000, 0.5)
+
+
+def test_the_legacy_single_audio_reader_keeps_its_answer():
+ takes = [_wav(fill = 1), _wav(fill = 2)]
+ reply = {
+ "audio": _b64(takes[0]),
+ "named_audio_outputs": [
+ {"id": f"audio_{i}", "audio": _b64(t)} for i, t in enumerate(takes)
+ ],
+ }
+ assert audio_cpp_backend._audio_from_task_response(*_json(reply)) == takes[0]
+ nested = {"result": {"wav": _b64(takes[1])}}
+ assert audio_cpp_backend._audio_from_task_response(*_json(nested)) == takes[1]
diff --git a/studio/backend/tests/test_gguf_load_cache_reuse.py b/studio/backend/tests/test_gguf_load_cache_reuse.py
index 7a507df87ca..2b2d03db36f 100644
--- a/studio/backend/tests/test_gguf_load_cache_reuse.py
+++ b/studio/backend/tests/test_gguf_load_cache_reuse.py
@@ -1080,6 +1080,7 @@ class TestLoadHubDownloadExclusion:
"audio_workflows",
"audio_reference_text",
"audio_required_inputs",
+ "audio_music",
}
unresolved = sorted(
name
diff --git a/studio/backend/tests/test_pr7699_worker_audio_mirror.py b/studio/backend/tests/test_pr7699_worker_audio_mirror.py
index 9e7d1068e9c..9a52cf0c2e0 100644
--- a/studio/backend/tests/test_pr7699_worker_audio_mirror.py
+++ b/studio/backend/tests/test_pr7699_worker_audio_mirror.py
@@ -127,6 +127,9 @@ def test_audio_cpp_workflow_fields_cross_the_worker_and_the_parent(monkeypatch):
"audio_reference_text": "required",
"audio_required_inputs": ["instruct"],
"audio_clone": {"reference_text": "required", "emotion_audio": False},
+ "audio_music": {"modes": [{"id": "song", "variations": None}]},
+ # The /audio/run route sizes CPU waits from it.
+ "audio_cpp_backend": "cpu",
}
entry = {"is_audio": True, "audio_type": "audiocpp_tts", "has_audio_input": False, **fields}
info = _drive_handle_load(monkeypatch, mc, entry, device = "cuda")
diff --git a/studio/frontend/src/features/audio/api.ts b/studio/frontend/src/features/audio/api.ts
index 55a1a71d64c..9d5352c8e9f 100644
--- a/studio/frontend/src/features/audio/api.ts
+++ b/studio/frontend/src/features/audio/api.ts
@@ -107,6 +107,8 @@ export interface AudioGalleryClip {
order_at?: number | null;
/** The Audio workflow that made the clip. Older servers omit it; read it through clipWorkflow. */
workflow?: string | null;
+ /** Clips one run made together share a group. */
+ group_id?: string | null;
reference_name?: string | null;
}
diff --git a/studio/frontend/src/features/audio/audio-cpp-catalog.ts b/studio/frontend/src/features/audio/audio-cpp-catalog.ts
index 0b6dafa0aff..3dcd4a8b5eb 100644
--- a/studio/frontend/src/features/audio/audio-cpp-catalog.ts
+++ b/studio/frontend/src/features/audio/audio-cpp-catalog.ts
@@ -62,6 +62,8 @@ export const AUDIO_CPP_MODELS: readonly AudioCppModel[] = [
{ id: "audio-cpp/Yue2-3B-GGUF", task: "music" },
{ id: folder("ACE-Step1.5-GGUF"), task: "music" },
{ id: folder("Stable-Audio-3-Small-Music-GGUF"), task: "music" },
+ { id: folder("Stable-Audio-3-Small-SFX-GGUF"), task: "music" },
+ { id: folder("ControlFoley-GGUF"), task: "music" },
{ id: folder("Qwen3-ASR-0.6B-GGUF"), task: "asr" },
{ id: folder("Qwen3-ASR-1.7B-GGUF"), task: "asr" },
{ id: folder("Parakeet-TDT-0.6B-v3-GGUF"), task: "asr" },
diff --git a/studio/frontend/src/features/audio/audio-page.tsx b/studio/frontend/src/features/audio/audio-page.tsx
index 9118e80b8c1..b58af08426c 100644
--- a/studio/frontend/src/features/audio/audio-page.tsx
+++ b/studio/frontend/src/features/audio/audio-page.tsx
@@ -39,7 +39,11 @@ import {
} from "./audio-page-policy";
import { clipReference } from "./audio-run-request";
import { AudioActiveProvider } from "./components/audio-source-input";
-import { type CreateMode, deviceSizeBytes } from "./audio-workspace-utils";
+import {
+ audioModelLabel,
+ type CreateMode,
+ deviceSizeBytes,
+} from "./audio-workspace-utils";
import {
audioCapabilityLine,
audioModelsForTask,
@@ -61,6 +65,7 @@ import {
adoptReference,
clonePageModels,
} from "./pages/clone-page";
+import { useMusicGeneration } from "./hooks/use-music-generation";
import { MusicOutput, MusicRail, musicPageModels } from "./pages/music-page";
import { SpeakOutput, SpeakRail, speakPageModels } from "./pages/speak-page";
import { type GenerateBlocker, TtsFooter } from "./pages/tts-workspace";
@@ -101,6 +106,8 @@ const HUB_TASKS_BY_MODE = {
transcribe: ["automatic-speech-recognition"],
} as const;
+const RECOMMENDED_MUSIC_MODELS = ["ACE-Step1.5-GGUF", "Stable-Audio-3-Small-Music-GGUF"];
+
export function AudioPage({
active = true,
onInitialReady,
@@ -402,7 +409,7 @@ export function AudioPage({
audioOptionValues,
handleAudioOptionChange,
handleAudioOptionsReset,
- handleGenerate,
+ handleGenerate: handleSpeechGenerate,
generationError,
setGenerationError,
toolContext,
@@ -410,6 +417,9 @@ export function AudioPage({
handleToolValueChange,
toolBlocker,
claimedOptions,
+ setAudioInstructions,
+ advancedOptionSpecs,
+ toolOptions,
} = useSpeechGeneration({
workflow: ttsWorkflow === "music" ? "music" : "speak",
status,
@@ -430,6 +440,35 @@ export function AudioPage({
replayQueuedTtsPick,
});
+ const music = useMusicGeneration({
+ status,
+ busyRef,
+ setBusy,
+ updateGenerationPhase,
+ generateAbort,
+ setMode,
+ setAdvancedOpen,
+ refreshStatus,
+ activeRef,
+ modeRef,
+ refreshGallery,
+ selectClip: selectGeneratedClip,
+ setFallbackClip,
+ setSelectedId,
+ pendingTranscribeRelease,
+ replayQueuedTtsPick,
+ lyrics: prompt,
+ description: audioInstructions,
+ advancedOptionSpecs,
+ audioOptionValues,
+ toolOptions,
+ toolBlocker,
+ modelName: status?.active_model ? audioModelLabel(status.active_model) : null,
+ musicLoaded: ttsLoaded && musicGeneration,
+ });
+ const musicStudio = ttsWorkflow === "music" && music.studio;
+ const handleGenerate = musicStudio ? music.handleGenerate : handleSpeechGenerate;
+
// Clone's Transcribe uses Transcribe's model, else one on disk, so it works without Settings.
const lastSttDownloaded =
lastSttRepo !== null &&
@@ -577,6 +616,23 @@ export function AudioPage({
);
const openSelector = useCallback(() => setSelectorOpen(true), []);
const chooseModelAction = { label: "Choose a model", onClick: openSelector };
+ const handlePickRecommended = useCallback(
+ (id: string) => void pickRecommendedModel(id),
+ [pickRecommendedModel],
+ );
+ const recommendedMusicActions = musicPageModels(MODELS_BY_MODE.speak, isMac)
+ .filter((model) =>
+ RECOMMENDED_MUSIC_MODELS.some((name) => model.id.endsWith(`/${name}`)),
+ )
+ .sort(
+ (a, b) =>
+ RECOMMENDED_MUSIC_MODELS.findIndex((name) => a.id.endsWith(`/${name}`)) -
+ RECOMMENDED_MUSIC_MODELS.findIndex((name) => b.id.endsWith(`/${name}`)),
+ )
+ .map((model) => ({
+ label: `use ${model.name}`,
+ onClick: () => handlePickRecommended(model.id),
+ }));
const recommendedCloneActions = clonePageModels(MODELS_BY_MODE.speak, isMac)
.slice(0, 2)
.map((model) => ({
@@ -599,7 +655,9 @@ export function AudioPage({
actions:
ttsWorkflow === "clone"
? [chooseModelAction, ...recommendedCloneActions]
- : [chooseModelAction],
+ : ttsWorkflow === "music"
+ ? [chooseModelAction, ...recommendedMusicActions]
+ : [chooseModelAction],
}
: !pageModelLoaded && ttsWorkflow === "clone"
? {
@@ -640,6 +698,7 @@ export function AudioPage({
reason: "The loaded model makes speech.",
actions: [
{ label: "Choose a music model", onClick: openSelector },
+ ...recommendedMusicActions,
{
label: "open Speak",
onClick: () => transitionWorkflow("speak"),
@@ -648,6 +707,8 @@ export function AudioPage({
}
: ttsWorkflow === "clone"
? clone.blocker
+ : musicStudio
+ ? music.blocker
: !prompt.trim() && !lyricsOptional
? {
reason:
@@ -664,7 +725,11 @@ export function AudioPage({
? { reason: toolBlocker }
: null;
const pageGenerationError =
- ttsWorkflow === "clone" ? clone.generationError : generationError;
+ ttsWorkflow === "clone"
+ ? clone.generationError
+ : musicStudio
+ ? music.generationError
+ : generationError;
const generateFailure: GenerateBlocker | null = pageGenerationError
? {
reason: /[.!?]$/.test(pageGenerationError)
@@ -674,14 +739,22 @@ export function AudioPage({
}
: null;
const setCloneGenerationError = clone.setGenerationError;
+ const setMusicGenerationError = music.setGenerationError;
useEffect(() => {
setGenerationError(null);
setCloneGenerationError(null);
- }, [status?.active_model, setGenerationError, setCloneGenerationError]);
+ setMusicGenerationError(null);
+ }, [
+ status?.active_model,
+ setGenerationError,
+ setCloneGenerationError,
+ setMusicGenerationError,
+ ]);
useEffect(() => {
if (busy === "generating") setGenerationError(null);
if (busy === "generating") setCloneGenerationError(null);
- }, [busy, setGenerationError, setCloneGenerationError]);
+ if (busy === "generating") setMusicGenerationError(null);
+ }, [busy, setGenerationError, setCloneGenerationError, setMusicGenerationError]);
const [elapsedSeconds, setElapsedSeconds] = useState<number | null>(null);
useEffect(() => {
if (busy !== "generating") {
@@ -1157,7 +1230,15 @@ export function AudioPage({
handleAudioOptionsReset,
};
return ttsWorkflow === "music" ? (
- <MusicRail {...railProps} />
+ <AudioActiveProvider value={active}>
+ <MusicRail
+ {...railProps}
+ music={music}
+ historyClips={clips}
+ description={audioInstructions}
+ setDescription={setAudioInstructions}
+ />
+ </AudioActiveProvider>
) : ttsWorkflow === "clone" ? (
<AudioActiveProvider value={active}>
<CloneRail
@@ -1205,13 +1286,17 @@ export function AudioPage({
) : (
<TtsFooter
busy={busy}
- generationPresentation={generationPresentation}
+ generationPresentation={
+ musicStudio && music.runStatus && generationPresentation?.canStop
+ ? { ...generationPresentation, status: music.runStatus }
+ : generationPresentation
+ }
handleStopGeneration={handleStopGeneration}
handleGenerate={handleGenerate}
ttsLoaded={pageModelLoaded}
prompt={prompt}
- lyricsOptional={lyricsOptional}
- musicNeedsDescription={musicNeedsDescription}
+ lyricsOptional={musicStudio || lyricsOptional}
+ musicNeedsDescription={!musicStudio && musicNeedsDescription}
audioInstructions={audioInstructions}
blocker={generateBlocker}
shortcutLabel={shortcutLabel}
diff --git a/studio/frontend/src/features/audio/audio-run-request.ts b/studio/frontend/src/features/audio/audio-run-request.ts
index 55e48b8d62f..5f9e5051425 100644
--- a/studio/frontend/src/features/audio/audio-run-request.ts
+++ b/studio/frontend/src/features/audio/audio-run-request.ts
@@ -83,8 +83,26 @@ export function selectionExpired(
return Number.isFinite(expires) && expires <= nowMs;
}
+export type AudioOptionScalar = boolean | number | string;
+
+export interface AudioMusicRunFields {
+ mode: "song" | "sfx" | "edit";
+ lyrics?: string | null;
+ instrumental?: boolean;
+ duration_s?: number | null;
+ variations?: number | null;
+ edit?: {
+ action: "repaint" | "extend" | "cover" | "continue" | "inpaint" | "restyle";
+ ranges?: { start_s: number; end_s: number }[];
+ strength?: number | null;
+ extend_s?: number | null;
+ } | null;
+ source?: AudioSourceRef | null;
+}
+
export interface AudioRunRequest {
- workflow: "clone" | "speak";
+ workflow: "clone" | "speak" | "music";
+ music?: AudioMusicRunFields;
text: string;
language?: string | null;
instructions?: string | null;
@@ -150,9 +168,65 @@ export function buildAudioRunBody(
body.seed = request.seed;
if (typeof request.max_tokens === "number" && request.max_tokens > 0)
body.max_tokens = request.max_tokens;
+ if (request.workflow === "music" && request.music) {
+ Object.assign(body, musicRunFields(request.music));
+ }
return body;
}
+function finiteSeconds(value: number | null | undefined): number | null {
+ return typeof value === "number" && Number.isFinite(value) && value >= 0
+ ? value
+ : null;
+}
+
+function musicRunFields(music: AudioMusicRunFields): Record<string, unknown> {
+ const out: Record<string, unknown> = { mode: music.mode };
+ if (music.mode === "song") {
+ const lyrics = music.lyrics?.trim();
+ if (lyrics) out.lyrics = lyrics;
+ if (music.instrumental) out.instrumental = true;
+ }
+ if (music.mode !== "edit" || music.edit?.action === "continue") {
+ const duration = finiteSeconds(music.duration_s);
+ if (duration !== null && duration > 0) out.duration_s = duration;
+ }
+ if (music.mode !== "edit") {
+ const variations = music.variations;
+ if (
+ typeof variations === "number" &&
+ Number.isInteger(variations) &&
+ variations > 1
+ )
+ out.variations = variations;
+ return out;
+ }
+ const source = cleanRef(music.source);
+ if (source && !("voice_id" in source)) {
+ out.inputs = { source };
+ }
+ if (music.edit) {
+ const edit: Record<string, unknown> = { action: music.edit.action };
+ const ranges = (music.edit.ranges ?? [])
+ .filter(
+ (range) =>
+ finiteSeconds(range.start_s) !== null &&
+ Number.isFinite(range.end_s) &&
+ range.end_s > range.start_s,
+ )
+ .map((range) => ({ start_s: range.start_s, end_s: range.end_s }));
+ if (ranges.length > 0) edit.ranges = ranges;
+ const strength = music.edit.strength;
+ if (typeof strength === "number" && Number.isFinite(strength))
+ edit.strength = Math.min(1, Math.max(0, strength));
+ const extend = finiteSeconds(music.edit.extend_s);
+ if (music.edit.action === "extend" && extend !== null && extend > 0)
+ edit.extend_s = extend;
+ out.edit = edit;
+ }
+ return out;
+}
+
export interface AudioVoiceCreateRequest {
source: AudioSourceRef;
name: string;
diff --git a/studio/frontend/src/features/audio/components/audio-source-input.tsx b/studio/frontend/src/features/audio/components/audio-source-input.tsx
index fb25488046b..b89e5358a59 100644
--- a/studio/frontend/src/features/audio/components/audio-source-input.tsx
+++ b/studio/frontend/src/features/audio/components/audio-source-input.tsx
@@ -61,6 +61,13 @@ const SOURCE_LABEL: Record<AudioSourceSelection["kind"], string> = {
voice: "Saved voice",
};
+export interface AudioSourcePreviewView {
+ peaks: number[] | null;
+ durationS: number | null;
+ src: string | null;
+ label: string;
+}
+
export interface AudioSourceInputHandle {
focus: () => void;
browse: () => void;
@@ -93,6 +100,7 @@ export function AudioSourceInput({
allowSavedVoice = true,
handleRef,
onStatusChange,
+ renderWaveform,
maxRecordSeconds,
expiredMessage = REFERENCE_EXPIRED_MESSAGE,
usesFirstSeconds = REFERENCE_MAX_SECONDS,
@@ -108,6 +116,7 @@ export function AudioSourceInput({
allowSavedVoice?: boolean;
handleRef?: Ref<AudioSourceInputHandle>;
onStatusChange?: (status: AudioSourceStatus) => void;
+ renderWaveform?: (preview: AudioSourcePreviewView) => ReactNode;
maxRecordSeconds?: number;
/** The card's copy defaults to a clone reference; other pages pass their own. */
expiredMessage?: string;
@@ -273,12 +282,21 @@ export function AudioSourceInput({
</span>
) : null}
</div>
- <Waveform
- peaks={preview.peaks}
- durationS={durationS}
- src={preview.url}
- label={name || label}
- />
+ {renderWaveform ? (
+ renderWaveform({
+ peaks: preview.peaks,
+ durationS,
+ src: preview.url,
+ label: name || label,
+ })
+ ) : (
+ <Waveform
+ peaks={preview.peaks}
+ durationS={durationS}
+ src={preview.url}
+ label={name || label}
+ />
+ )}
{status.phase === "uploading" ? (
<div className="grid gap-1">
<Progress
diff --git a/studio/frontend/src/features/audio/components/lyrics-editor.tsx b/studio/frontend/src/features/audio/components/lyrics-editor.tsx
new file mode 100644
index 00000000000..c3a711ac417
--- /dev/null
+++ b/studio/frontend/src/features/audio/components/lyrics-editor.tsx
@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Button } from "@/components/ui/button";
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { Textarea } from "@/components/ui/textarea";
+import { Add01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useRef } from "react";
+import { insertSectionTag, sectionTags } from "../music/music-policy";
+import type { MusicModeRule } from "../music/music-types";
+
+export function LyricsEditor({
+ id,
+ label,
+ value,
+ onChange,
+ sectionCase,
+ disabled,
+ placeholder,
+ describedBy,
+}: {
+ id: string;
+ label: string;
+ value: string;
+ onChange: (next: string) => void;
+ sectionCase: MusicModeRule["section_case"];
+ disabled: boolean;
+ placeholder?: string;
+ describedBy?: string;
+}) {
+ const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+ const inserted = useRef(false);
+ const tags = sectionTags(sectionCase);
+ const insert = (tag: string) => {
+ const textarea = textareaRef.current;
+ const cursor = textarea ? textarea.selectionStart : value.length;
+ const next = insertSectionTag(value, cursor, tag);
+ inserted.current = true;
+ onChange(next.text);
+ // Move the caret once React has written the value.
+ requestAnimationFrame(() => {
+ const current = textareaRef.current;
+ if (!current) return;
+ current.focus();
+ current.setSelectionRange(next.cursor, next.cursor);
+ });
+ };
+ return (
+ <div className="grid gap-1.5">
+ <div className="flex min-w-0 items-center justify-between gap-2">
+ <label htmlFor={id} className="text-ui-13 font-medium text-foreground">
+ {label}
+ </label>
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild={true}>
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ disabled={disabled}
+ className="-me-2 h-auto px-2 py-1 text-ui-11p5"
+ >
+ <HugeiconsIcon icon={Add01Icon} className="size-3" />
+ Add section
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent
+ align="end"
+ className="w-auto min-w-40"
+ onCloseAutoFocus={(event) => {
+ // After a pick the caret goes back into the lyrics, not to this button.
+ if (inserted.current) event.preventDefault();
+ inserted.current = false;
+ }}
+ >
+ {tags.map((section) => (
+ <DropdownMenuItem
+ key={section.tag}
+ onSelect={() => insert(section.tag)}
+ >
+ {section.name}
+ <span className="ms-auto text-muted-foreground">
+ {section.tag}
+ </span>
+ </DropdownMenuItem>
+ ))}
+ </DropdownMenuContent>
+ </DropdownMenu>
+ </div>
+ <Textarea
+ ref={textareaRef}
+ id={id}
+ value={value}
+ disabled={disabled}
+ onChange={(event) => onChange(event.target.value)}
+ placeholder={placeholder}
+ aria-describedby={describedBy}
+ className="min-h-36 font-normal"
+ />
+ </div>
+ );
+}
diff --git a/studio/frontend/src/features/audio/components/music-edit-inputs.tsx b/studio/frontend/src/features/audio/components/music-edit-inputs.tsx
new file mode 100644
index 00000000000..93a37ee96c8
--- /dev/null
+++ b/studio/frontend/src/features/audio/components/music-edit-inputs.tsx
@@ -0,0 +1,257 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Textarea } from "@/components/ui/textarea";
+import { ParamSlider } from "@/features/chat";
+import { PillTabs } from "@/features/model-picker/components/model-selector/pill-tabs";
+import { type JSX, type Ref, useEffect } from "react";
+import type { AudioSourceStatus } from "../hooks/audio-source-state";
+import {
+ EXTEND_MAX_S,
+ EXTEND_MIN_S,
+ MUSIC_EDIT_ACTION_HINT,
+ MUSIC_EDIT_ACTION_LABEL,
+ MUSIC_EDIT_DEFAULT_STRENGTH,
+ editActions,
+ editBeyondEndS,
+ editMaxRanges,
+ editRangeProblem,
+ editSourceTooLong,
+ editUsesRanges,
+ editUsesStrength,
+ formatEditLimit,
+} from "../music/music-edit-rules";
+import type {
+ MusicEditAction,
+ MusicEditDraft,
+ MusicModeRule,
+} from "../music/music-types";
+import {
+ AudioSourceInput,
+ type AudioSourceInputHandle,
+} from "./audio-source-input";
+import { Waveform } from "./waveform";
+import { secondsBeyondEnd } from "./waveform-range";
+import { WaveformRangeSelect } from "./waveform-range-select";
+
+export { musicEditProblem } from "../music/music-edit-rules";
+
+const SOURCE_ID = "music-edit-source";
+const PROMPT_ID = "music-edit-prompt";
+
+export interface MusicEditInputsProps {
+ rule: MusicModeRule;
+ draft: MusicEditDraft;
+ onChange: (patch: Partial<MusicEditDraft>) => void;
+ disabled: boolean;
+ onSourceStatusChange?: (status: AudioSourceStatus) => void;
+ sourceHandleRef?: Ref<AudioSourceInputHandle>;
+}
+
+export function MusicEditInputs({
+ rule,
+ draft,
+ onChange,
+ disabled,
+ onSourceStatusChange,
+ sourceHandleRef,
+}: MusicEditInputsProps): JSX.Element {
+ const actions = editActions(rule);
+ const action: MusicEditAction | null =
+ draft.action && actions.includes(draft.action) ? draft.action : null;
+ const sourceDurationS = draft.source?.durationS ?? null;
+
+ // The tabs always show a choice, so a missing or stale action takes the first one.
+ const firstAction = actions[0] ?? null;
+ useEffect(() => {
+ if (action === null && firstAction !== null)
+ onChange({ action: firstAction });
+ }, [action, firstAction, onChange]);
+
+ const usesRanges = editUsesRanges(action);
+ const maxRanges = editMaxRanges(rule, action);
+ const beyondEndS = editBeyondEndS(action);
+ const tooLong = editSourceTooLong(rule, sourceDurationS);
+ const rangeProblem =
+ draft.source && !tooLong
+ ? editRangeProblem(
+ rule,
+ { action, ranges: draft.ranges },
+ sourceDurationS,
+ )
+ : null;
+ const extendedBy =
+ action === "repaint" && sourceDurationS !== null && draft.ranges[0]
+ ? secondsBeyondEnd(draft.ranges[0], sourceDurationS)
+ : 0;
+ const defaultStrength = action
+ ? MUSIC_EDIT_DEFAULT_STRENGTH[action]
+ : undefined;
+
+ return (
+ <div className="grid gap-4">
+ <AudioSourceInput
+ id={SOURCE_ID}
+ label="Clip to edit"
+ hint={
+ rule.max_source_s
+ ? `Up to ${formatEditLimit(rule.max_source_s)} of music.`
+ : undefined
+ }
+ value={draft.source}
+ onChange={(next) =>
+ onChange({
+ source: next,
+ // Parts picked on another clip point at the wrong audio.
+ ranges: next && next.id === draft.source?.id ? draft.ranges : [],
+ })
+ }
+ disabled={disabled}
+ allowHistory={true}
+ allowSavedVoice={false}
+ usesFirstSeconds={null}
+ expiredMessage="This clip expired. Add it again."
+ recordHint="Play or sing the part you want to change."
+ handleRef={sourceHandleRef}
+ onStatusChange={onSourceStatusChange}
+ renderWaveform={(preview) =>
+ usesRanges ? (
+ <WaveformRangeSelect
+ peaks={preview.peaks}
+ durationS={preview.durationS}
+ src={preview.src}
+ label={preview.label}
+ ranges={draft.ranges}
+ onChange={(ranges) => onChange({ ranges })}
+ maxRanges={maxRanges}
+ beyondEndS={beyondEndS}
+ disabled={disabled}
+ />
+ ) : (
+ <Waveform
+ peaks={preview.peaks}
+ durationS={preview.durationS}
+ src={preview.src}
+ label={preview.label}
+ tailS={action === "extend" ? draft.extendS : 0}
+ />
+ )
+ }
+ />
+ {tooLong ? (
+ <p
+ role="alert"
+ className="-mt-2 text-ui-11p5 leading-snug text-foreground"
+ >
+ {tooLong}
+ </p>
+ ) : null}
+
+ {actions.length > 0 ? (
+ <div className="grid gap-1.5">
+ <span className="text-ui-13 font-medium text-foreground">
+ What to do
+ </span>
+ <PillTabs
+ ariaLabel="What to do with the clip"
+ value={action ?? ""}
+ onValueChange={(next) => {
+ const nextAction = next as MusicEditAction;
+ if (nextAction === action) return;
+ // Repaint keeps one part; inpaint can keep several.
+ const keep = editMaxRanges(rule, nextAction);
+ onChange({
+ action: nextAction,
+ ranges: draft.ranges.slice(0, keep),
+ });
+ }}
+ disabled={disabled}
+ fit={true}
+ compact={true}
+ className="[&>button]:px-3"
+ tabs={actions.map((value) => ({
+ value,
+ label: MUSIC_EDIT_ACTION_LABEL[value],
+ }))}
+ />
+ {action ? (
+ <p className="text-ui-11p5 leading-snug text-muted-foreground">
+ {MUSIC_EDIT_ACTION_HINT[action]}
+ </p>
+ ) : null}
+ {usesRanges && rangeProblem ? (
+ <p className="text-ui-11p5 leading-snug text-foreground">
+ {draft.ranges.length === 0
+ ? `${rangeProblem} Drag across it, or use Select a part.`
+ : rangeProblem}
+ </p>
+ ) : extendedBy > 0 ? (
+ <p className="text-ui-11p5 leading-snug text-muted-foreground">
+ Extends the clip by{" "}
+ <span className="font-mono tabular-nums">
+ {extendedBy.toFixed(1)}
+ </span>{" "}
+ s.
+ </p>
+ ) : null}
+ </div>
+ ) : (
+ <p className="text-ui-12 leading-snug text-muted-foreground">
+ This model cannot edit clips. Load ACE-Step or Stable Audio to edit.
+ </p>
+ )}
+
+ {editUsesStrength(action) && defaultStrength !== undefined ? (
+ <ParamSlider
+ label="How much to change"
+ value={draft.strength ?? defaultStrength}
+ min={0}
+ max={1}
+ step={0.05}
+ onChange={(strength) => onChange({ strength })}
+ displayValue={(draft.strength ?? defaultStrength).toFixed(2)}
+ disabled={disabled}
+ info="Lower keeps more of the original."
+ />
+ ) : null}
+
+ {action === "extend" ? (
+ <ParamSlider
+ label="Add seconds"
+ value={Math.min(EXTEND_MAX_S, Math.max(EXTEND_MIN_S, draft.extendS))}
+ min={EXTEND_MIN_S}
+ max={EXTEND_MAX_S}
+ step={1}
+ onChange={(extendS) => onChange({ extendS })}
+ disabled={disabled}
+ info="New music is added after the clip's end."
+ />
+ ) : null}
+
+ {action ? (
+ <div className="grid gap-1.5">
+ <label
+ htmlFor={PROMPT_ID}
+ className="text-ui-13 font-medium text-foreground"
+ >
+ {editUsesStrength(action)
+ ? "What should it sound like?"
+ : "What should the new part sound like?"}
+ </label>
+ <Textarea
+ id={PROMPT_ID}
+ value={draft.prompt}
+ onChange={(event) => onChange({ prompt: event.target.value })}
+ disabled={disabled}
+ placeholder={
+ editUsesStrength(action)
+ ? "Lo-fi jazz, warm piano, brushed drums…"
+ : "A soaring guitar solo over the same groove…"
+ }
+ className="min-h-20 rounded-xl"
+ />
+ </div>
+ ) : null}
+ </div>
+ );
+}
diff --git a/studio/frontend/src/features/audio/components/music-send-to.tsx b/studio/frontend/src/features/audio/components/music-send-to.tsx
new file mode 100644
index 00000000000..4066d5045d0
--- /dev/null
+++ b/studio/frontend/src/features/audio/components/music-send-to.tsx
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { DropdownMenuItem } from "@/components/ui/dropdown-menu";
+import {
+ PencilEdit02Icon,
+ TimeQuarterPassIcon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import type { AudioGalleryClip } from "../api";
+import { type SendAction, sendActionsFor } from "../music/music-edit-rules";
+import { useAudioMusicStore } from "../stores/audio-music-store";
+import { useAudioWorkspaceStore } from "../stores/audio-workspace-store";
+import { clipWorkflow } from "../workflows";
+
+// History is per page, so these only ever show on Music itself.
+const SEND_LABEL: Record<SendAction, string> = {
+ edit: "Edit",
+ extend: "Extend",
+};
+
+const SEND_ICON = {
+ edit: PencilEdit02Icon,
+ extend: TimeQuarterPassIcon,
+} as const;
+
+export function sendClipToMusic(
+ clip: AudioGalleryClip,
+ action: SendAction,
+): void {
+ useAudioMusicStore.getState().pushClipToEdit(
+ {
+ kind: "clip",
+ id: clip.id,
+ name: clip.prompt || "Generated clip",
+ durationS: clip.duration_s,
+ transcript: null,
+ language: null,
+ },
+ action === "extend" ? "extend" : null,
+ );
+ const workspace = useAudioWorkspaceStore.getState();
+ if (workspace.workflow !== "music") workspace.requestWorkflow("music");
+}
+
+export function canSendToMusic(clip: AudioGalleryClip): boolean {
+ return clipWorkflow(clip) === "music";
+}
+
+function useSendActions(clip: AudioGalleryClip): readonly SendAction[] {
+ const editActions = useAudioMusicStore((state) => state.loadedEditActions);
+ return canSendToMusic(clip) ? sendActionsFor(editActions) : [];
+}
+
+export function MusicSendToMenuItems({ clip }: { clip: AudioGalleryClip }) {
+ const actions = useSendActions(clip);
+ if (actions.length === 0) return null;
+ return (
+ <>
+ {actions.map((action) => (
+ <DropdownMenuItem
+ key={action}
+ onClick={() => sendClipToMusic(clip, action)}
+ >
+ <HugeiconsIcon
+ icon={SEND_ICON[action]}
+ strokeWidth={1.75}
+ className="size-icon"
+ />
+ {SEND_LABEL[action]}
+ </DropdownMenuItem>
+ ))}
+ </>
+ );
+}
diff --git a/studio/frontend/src/features/audio/components/variation-history.tsx b/studio/frontend/src/features/audio/components/variation-history.tsx
new file mode 100644
index 00000000000..c03f464eaeb
--- /dev/null
+++ b/studio/frontend/src/features/audio/components/variation-history.tsx
@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { cn } from "@/lib/utils";
+import { ArrowDown01Icon, ArrowRight01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import type { AudioGalleryClip } from "../api";
+import { audioModelLabel, formatClipDuration } from "../audio-workspace-utils";
+import { variationLabel } from "../music/variation-groups";
+
+export function VariationGroupRow({
+ clips,
+ open,
+ selected,
+ onToggle,
+}: {
+ clips: readonly AudioGalleryClip[];
+ open: boolean;
+ selected: boolean;
+ onToggle: () => void;
+}) {
+ const first = clips[0];
+ if (!first) return null;
+ return (
+ <button
+ type="button"
+ aria-expanded={open}
+ onClick={onToggle}
+ className={cn(
+ "flex w-full min-w-0 items-center gap-2 rounded-md px-2 py-1.5 text-left text-ui-13 transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+ selected && !open && "bg-muted",
+ )}
+ >
+ <HugeiconsIcon
+ icon={open ? ArrowDown01Icon : ArrowRight01Icon}
+ className="size-3.5 shrink-0 text-muted-foreground"
+ />
+ <span className="min-w-0 flex-1 truncate">{first.prompt}</span>
+ <span className="shrink-0 rounded-4xl bg-muted px-2 py-0.5 text-ui-11 text-muted-foreground">
+ {variationLabel(clips.length)}
+ </span>
+ <span
+ title={first.model}
+ className="max-w-[30%] shrink-0 truncate text-ui-11p5 text-muted-foreground"
+ >
+ {audioModelLabel(first.model)}
+ </span>
+ <span className="shrink-0 text-ui-11p5 text-muted-foreground">
+ {formatClipDuration(first.duration_s)}
+ </span>
+ </button>
+ );
+}
+
+export function VariationChips({
+ siblings,
+ selectedId,
+ onSelect,
+}: {
+ siblings: readonly AudioGalleryClip[];
+ selectedId: string;
+ onSelect: (id: string) => void;
+}) {
+ if (siblings.length < 2) return null;
+ return (
+ <fieldset
+ aria-label="Variations"
+ className="m-0 flex min-w-0 flex-wrap items-center gap-1 border-0 p-0"
+ >
+ <span className="mr-1 text-ui-11p5 text-muted-foreground">
+ {variationLabel(siblings.length)}
+ </span>
+ {siblings.map((clip, index) => {
+ const current = clip.id === selectedId;
+ return (
+ <button
+ key={clip.id}
+ type="button"
+ aria-pressed={current}
+ aria-label={`Variation ${index + 1} of ${siblings.length}`}
+ onClick={() => onSelect(clip.id)}
+ className={cn(
+ "flex size-[calc(24px*var(--ui-space-scale,1))] items-center justify-center rounded-full font-mono text-ui-11p5 tabular-nums transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+ current
+ ? "bg-foreground text-background"
+ : "bg-muted text-muted-foreground hover:text-foreground",
+ )}
+ >
+ {index + 1}
+ </button>
+ );
+ })}
+ </fieldset>
+ );
+}
diff --git a/studio/frontend/src/features/audio/components/waveform-range-select.tsx b/studio/frontend/src/features/audio/components/waveform-range-select.tsx
new file mode 100644
index 00000000000..dfaee50a722
--- /dev/null
+++ b/studio/frontend/src/features/audio/components/waveform-range-select.tsx
@@ -0,0 +1,356 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import { Add01Icon, Cancel01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import {
+ type KeyboardEvent,
+ type PointerEvent,
+ useMemo,
+ useRef,
+ useState,
+} from "react";
+import { Waveform } from "./waveform";
+import {
+ type RangeEdge,
+ type RangeLimits,
+ type WaveRange,
+ addRange,
+ dragToRange,
+ formatRange,
+ formatRangeTime,
+ moveRange,
+ nextFreeRange,
+ normalizeRanges,
+ nudgeStep,
+ pxToSeconds,
+ rangeLabel,
+ removeRange,
+ secondsBeyondEnd,
+ secondsToFraction,
+ timelineEnd,
+} from "./waveform-range";
+
+// A press that moves less than this is a click (seek), not a drag.
+const DRAG_THRESHOLD_PX = 4;
+
+type Drag =
+ | {
+ kind: "create";
+ pointerId: number;
+ startX: number;
+ anchorS: number;
+ active: boolean;
+ }
+ | {
+ kind: "edge";
+ pointerId: number;
+ index: number;
+ edge: RangeEdge;
+ grabS: number;
+ base: WaveRange[];
+ };
+
+export function WaveformRangeSelect({
+ peaks,
+ durationS,
+ src,
+ label,
+ ranges,
+ onChange,
+ maxRanges,
+ beyondEndS = 0,
+ disabled = false,
+ className,
+}: {
+ peaks: readonly number[] | null;
+ durationS: number | null;
+ src: string | null;
+ label: string;
+ ranges: readonly WaveRange[];
+ onChange: (next: WaveRange[]) => void;
+ maxRanges: number;
+ beyondEndS?: number;
+ disabled?: boolean;
+ className?: string;
+}) {
+ const duration = durationS && durationS > 0 ? durationS : 0;
+ const limits: RangeLimits = useMemo(
+ () => ({ durationS: duration, maxRanges, beyondEndS }),
+ [duration, maxRanges, beyondEndS],
+ );
+ const timeline = timelineEnd(limits);
+ const areaRef = useRef<HTMLDivElement | null>(null);
+ const listRef = useRef<HTMLUListElement | null>(null);
+ const drag = useRef<Drag | null>(null);
+ const suppressClick = useRef(false);
+ const [preview, setPreview] = useState<WaveRange[] | null>(null);
+ const [focused, setFocused] = useState<number | null>(null);
+ const shown = preview ?? ranges;
+ const ready = duration > 0 && !disabled;
+ const canAdd = ready && nextFreeRange(ranges, limits) !== null;
+
+ const secondsAt = (clientX: number) => {
+ const box = areaRef.current?.getBoundingClientRect();
+ if (!box) return 0;
+ return pxToSeconds(clientX - box.left, box.width, timeline);
+ };
+
+ const commit = (next: WaveRange[]) => onChange(normalizeRanges(next, limits));
+
+ const focusChip = (index: number) => {
+ const chips =
+ listRef.current?.querySelectorAll<HTMLElement>("[data-range-chip]");
+ if (!chips || chips.length === 0) return;
+ chips[Math.max(0, Math.min(index, chips.length - 1))]?.focus();
+ };
+
+ const remove = (index: number) => {
+ commit(removeRange(ranges, index));
+ setFocused(null);
+ requestAnimationFrame(() => focusChip(index));
+ };
+
+ const onRangeKey = (
+ event: KeyboardEvent<HTMLElement>,
+ index: number,
+ edge: RangeEdge,
+ ) => {
+ if (disabled) return;
+ if (event.key === "Delete" || event.key === "Backspace") {
+ event.preventDefault();
+ remove(index);
+ return;
+ }
+ const step = nudgeStep(event);
+ if (step === null) return;
+ event.preventDefault();
+ commit(moveRange(ranges, index, edge, step, limits));
+ };
+
+ const onPointerDown = (event: PointerEvent<HTMLDivElement>) => {
+ if (!ready || event.button !== 0) return;
+ const area = areaRef.current?.parentElement;
+ if (!area?.contains(event.target as Node)) return;
+ drag.current = {
+ kind: "create",
+ pointerId: event.pointerId,
+ startX: event.clientX,
+ anchorS: secondsAt(event.clientX),
+ active: false,
+ };
+ };
+
+ const onPointerMove = (event: PointerEvent<HTMLDivElement>) => {
+ const current = drag.current;
+ if (!current || current.pointerId !== event.pointerId) return;
+ const at = secondsAt(event.clientX);
+ if (current.kind === "create") {
+ if (!current.active) {
+ if (Math.abs(event.clientX - current.startX) < DRAG_THRESHOLD_PX)
+ return;
+ current.active = true;
+ // Captured only once it is a drag, so a plain click still seeks.
+ event.currentTarget.setPointerCapture(event.pointerId);
+ }
+ const range = dragToRange(current.anchorS, at, limits);
+ setPreview(range ? addRange(ranges, range, limits) : [...ranges]);
+ return;
+ }
+ setPreview(
+ moveRange(
+ current.base,
+ current.index,
+ current.edge,
+ at - current.grabS,
+ limits,
+ ),
+ );
+ };
+
+ const endDrag = (event: PointerEvent<HTMLDivElement>, cancelled: boolean) => {
+ const current = drag.current;
+ if (!current || current.pointerId !== event.pointerId) return;
+ drag.current = null;
+ const moved = current.kind === "edge" || current.active;
+ if (moved) {
+ // The click ending a drag must not seek; a touch drag may send none, so it lapses.
+ suppressClick.current = true;
+ window.setTimeout(() => {
+ suppressClick.current = false;
+ }, 0);
+ }
+ if (!cancelled && moved && preview) commit(preview);
+ setPreview(null);
+ };
+
+ const startEdgeDrag = (
+ event: PointerEvent<HTMLElement>,
+ index: number,
+ edge: RangeEdge,
+ ) => {
+ if (!ready || event.button !== 0) return;
+ event.stopPropagation();
+ event.preventDefault();
+ const root = event.currentTarget.closest<HTMLElement>("[data-range-root]");
+ root?.setPointerCapture(event.pointerId);
+ drag.current = {
+ kind: "edge",
+ pointerId: event.pointerId,
+ index,
+ edge,
+ grabS: secondsAt(event.clientX),
+ base: [...ranges],
+ };
+ focusChip(index);
+ };
+
+ const overlay =
+ duration > 0 ? (
+ <div ref={areaRef} className="pointer-events-none absolute inset-0">
+ {shown.map((range, index) => {
+ const left = secondsToFraction(range.start_s, timeline) * 100;
+ const width = secondsToFraction(range.end_s, timeline) * 100 - left;
+ return (
+ <div
+ // biome-ignore lint/suspicious/noArrayIndexKey: ranges are kept sorted; the index is their name.
+ key={index}
+ className={cn(
+ "absolute inset-y-0 rounded-md bg-[color-mix(in_oklab,var(--foreground)_calc(10%*var(--contrast-wash-gain,1)),transparent)] ring-1 ring-[color-mix(in_oklab,var(--foreground)_calc(45%*var(--contrast-edge-gain,1)),transparent)]",
+ focused === index && "ring-2 ring-ring",
+ ready && "pointer-events-auto cursor-grab",
+ )}
+ style={{ left: `${left}%`, width: `${width}%` }}
+ onPointerDown={(event) => startEdgeDrag(event, index, "both")}
+ >
+ {(["start", "end"] as const).map((edge) => {
+ const value = edge === "start" ? range.start_s : range.end_s;
+ return (
+ <div
+ key={edge}
+ role="slider"
+ tabIndex={ready ? 0 : -1}
+ aria-label={`${edge === "start" ? "Start" : "End"} of range ${index + 1}`}
+ aria-valuemin={0}
+ aria-valuemax={Math.round(timeline * 10) / 10}
+ aria-valuenow={Math.round(value * 10) / 10}
+ aria-valuetext={`${formatRangeTime(value)}`}
+ aria-disabled={!ready}
+ className={cn(
+ "absolute inset-y-0 flex w-[calc(12px*var(--ui-space-scale,1))] cursor-ew-resize items-center justify-center outline-none focus-visible:ring-2 focus-visible:ring-ring",
+ edge === "start"
+ ? "left-0 -translate-x-1/2 rounded-l-md"
+ : "right-0 translate-x-1/2 rounded-r-md",
+ )}
+ onPointerDown={(event) => startEdgeDrag(event, index, edge)}
+ onKeyDown={(event) => onRangeKey(event, index, edge)}
+ onFocus={() => setFocused(index)}
+ onBlur={() => setFocused(null)}
+ >
+ <span className="h-1/2 w-[3px] rounded-full bg-foreground" />
+ </div>
+ );
+ })}
+ </div>
+ );
+ })}
+ </div>
+ ) : undefined;
+
+ return (
+ <div className={cn("grid gap-2", className)}>
+ <div
+ data-range-root=""
+ className={cn(ready && "touch-none select-none")}
+ onPointerDown={onPointerDown}
+ onPointerMove={onPointerMove}
+ onPointerUp={(event) => endDrag(event, false)}
+ onPointerCancel={(event) => endDrag(event, true)}
+ onClickCapture={(event) => {
+ if (!suppressClick.current) return;
+ suppressClick.current = false;
+ event.stopPropagation();
+ event.preventDefault();
+ }}
+ >
+ <Waveform
+ peaks={peaks}
+ durationS={durationS}
+ src={src}
+ label={label}
+ tailS={duration > 0 ? beyondEndS : 0}
+ overlay={overlay}
+ />
+ </div>
+ <div className="flex flex-wrap items-center gap-1.5">
+ <ul
+ ref={listRef}
+ aria-label={`Selected parts of ${label}`}
+ className="contents"
+ >
+ {ranges.map((range, index) => {
+ const beyond = secondsBeyondEnd(range, duration);
+ return (
+ <li
+ // biome-ignore lint/suspicious/noArrayIndexKey: ranges are kept sorted; the index is their name.
+ key={index}
+ className="flex items-center rounded-4xl bg-muted"
+ >
+ <button
+ type="button"
+ data-range-chip=""
+ disabled={disabled}
+ aria-label={`${rangeLabel(index, range)}${beyond > 0 ? `, ${beyond} seconds past the end` : ""}`}
+ aria-keyshortcuts="Delete Backspace ArrowLeft ArrowRight"
+ title="Arrow keys move it, Shift+arrow by a second, Delete removes it"
+ className={cn(
+ "rounded-l-4xl py-0.5 pl-2.5 pr-1 font-mono text-ui-11p5 tabular-nums text-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring",
+ focused === index && "underline underline-offset-2",
+ )}
+ onKeyDown={(event) => onRangeKey(event, index, "both")}
+ onFocus={() => setFocused(index)}
+ onBlur={() => setFocused(null)}
+ >
+ {formatRange(range)}
+ </button>
+ <button
+ type="button"
+ disabled={disabled}
+ aria-label={`Remove range ${index + 1}`}
+ className="flex items-center rounded-r-4xl py-1 pl-0.5 pr-2 text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+ onClick={() => remove(index)}
+ >
+ <HugeiconsIcon icon={Cancel01Icon} className="size-3" />
+ </button>
+ </li>
+ );
+ })}
+ </ul>
+ {maxRanges > 0 && ranges.length < maxRanges ? (
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ className="h-auto px-2 py-1 text-ui-11p5"
+ disabled={!canAdd}
+ onClick={() => {
+ const next = nextFreeRange(ranges, limits);
+ if (!next) return;
+ const updated = addRange(ranges, next, limits);
+ commit(updated);
+ const at = updated.findIndex(
+ (range) => range.start_s === next.start_s,
+ );
+ requestAnimationFrame(() => focusChip(at));
+ }}
+ >
+ <HugeiconsIcon icon={Add01Icon} className="size-3" />
+ {ranges.length === 0 ? "Select a part" : "Add a part"}
+ </Button>
+ ) : null}
+ </div>
+ </div>
+ );
+}
diff --git a/studio/frontend/src/features/audio/components/waveform-range.ts b/studio/frontend/src/features/audio/components/waveform-range.ts
new file mode 100644
index 00000000000..e92b0bbd203
--- /dev/null
+++ b/studio/frontend/src/features/audio/components/waveform-range.ts
@@ -0,0 +1,231 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export interface WaveRange {
+ start_s: number;
+ end_s: number;
+}
+
+export interface RangeLimits {
+ durationS: number;
+ maxRanges: number;
+ beyondEndS?: number;
+}
+
+export const MIN_RANGE_S = 0.25;
+export const NUDGE_S = 0.1;
+export const NUDGE_LARGE_S = 1;
+
+const round = (seconds: number) => Math.round(seconds * 100) / 100;
+
+export function timelineEnd(limits: RangeLimits): number {
+ const duration = Math.max(0, limits.durationS);
+ return duration + Math.max(0, limits.beyondEndS ?? 0);
+}
+
+export function pxToSeconds(
+ px: number,
+ widthPx: number,
+ timelineS: number,
+): number {
+ if (!(widthPx > 0) || !(timelineS > 0)) return 0;
+ return Math.min(timelineS, Math.max(0, (px / widthPx) * timelineS));
+}
+
+export function secondsToPx(
+ seconds: number,
+ widthPx: number,
+ timelineS: number,
+): number {
+ if (!(timelineS > 0)) return 0;
+ return (seconds / timelineS) * widthPx;
+}
+
+export function secondsToFraction(seconds: number, timelineS: number): number {
+ if (!(timelineS > 0)) return 0;
+ return Math.min(1, Math.max(0, seconds / timelineS));
+}
+
+export function clampRange(
+ range: WaveRange,
+ limits: RangeLimits,
+): WaveRange | null {
+ const end = timelineEnd(limits);
+ if (!(end >= MIN_RANGE_S)) return null;
+ if (!(Number.isFinite(range.start_s) && Number.isFinite(range.end_s)))
+ return null;
+ let start = Math.min(range.start_s, range.end_s);
+ let stop = Math.max(range.start_s, range.end_s);
+ start = Math.min(Math.max(0, start), end);
+ stop = Math.min(Math.max(0, stop), end);
+ if (stop - start < MIN_RANGE_S) {
+ stop = start + MIN_RANGE_S;
+ if (stop > end) {
+ stop = end;
+ start = end - MIN_RANGE_S;
+ }
+ }
+ return { start_s: round(start), end_s: round(stop) };
+}
+
+export function mergeRanges(
+ ranges: readonly WaveRange[],
+ limits: RangeLimits,
+): WaveRange[] {
+ const clamped = ranges
+ .map((range) => clampRange(range, limits))
+ .filter((range): range is WaveRange => range !== null)
+ .sort((a, b) => a.start_s - b.start_s || a.end_s - b.end_s);
+ const merged: WaveRange[] = [];
+ for (const range of clamped) {
+ const last = merged[merged.length - 1];
+ if (last && range.start_s <= last.end_s) {
+ last.end_s = Math.max(last.end_s, range.end_s);
+ } else {
+ merged.push({ ...range });
+ }
+ }
+ return merged;
+}
+
+export function normalizeRanges(
+ ranges: readonly WaveRange[],
+ limits: RangeLimits,
+): WaveRange[] {
+ return mergeRanges(ranges, limits).slice(
+ 0,
+ Math.max(0, Math.floor(limits.maxRanges)),
+ );
+}
+
+export function addRange(
+ ranges: readonly WaveRange[],
+ range: WaveRange,
+ limits: RangeLimits,
+): WaveRange[] {
+ if (limits.maxRanges <= 0) return [];
+ if (limits.maxRanges === 1) return normalizeRanges([range], limits);
+ const next = mergeRanges([...ranges, range], limits);
+ return next.length > limits.maxRanges
+ ? normalizeRanges(ranges, limits)
+ : next;
+}
+
+export function removeRange(
+ ranges: readonly WaveRange[],
+ index: number,
+): WaveRange[] {
+ return ranges.filter((_, at) => at !== index);
+}
+
+export type RangeEdge = "start" | "end" | "both";
+
+export function moveRange(
+ ranges: readonly WaveRange[],
+ index: number,
+ edge: RangeEdge,
+ deltaS: number,
+ limits: RangeLimits,
+): WaveRange[] {
+ const range = ranges[index];
+ if (!range) return [...ranges];
+ const end = timelineEnd(limits);
+ let next: WaveRange;
+ if (edge === "both") {
+ const width = range.end_s - range.start_s;
+ const start = Math.min(
+ Math.max(0, range.start_s + deltaS),
+ Math.max(0, end - width),
+ );
+ next = { start_s: start, end_s: start + width };
+ } else if (edge === "start") {
+ next = {
+ start_s: Math.min(range.start_s + deltaS, range.end_s - MIN_RANGE_S),
+ end_s: range.end_s,
+ };
+ } else {
+ next = {
+ start_s: range.start_s,
+ end_s: Math.max(range.end_s + deltaS, range.start_s + MIN_RANGE_S),
+ };
+ }
+ const rest = ranges.map((item, at) => (at === index ? next : item));
+ return normalizeRanges(rest, limits);
+}
+
+export function nudgeStep(event: { key: string; shiftKey?: boolean }):
+ | number
+ | null {
+ const size = event.shiftKey ? NUDGE_LARGE_S : NUDGE_S;
+ switch (event.key) {
+ case "ArrowRight":
+ case "ArrowUp":
+ return size;
+ case "ArrowLeft":
+ case "ArrowDown":
+ return -size;
+ default:
+ return null;
+ }
+}
+
+export function dragToRange(
+ anchorS: number,
+ currentS: number,
+ limits: RangeLimits,
+): WaveRange | null {
+ if (Math.abs(currentS - anchorS) < MIN_RANGE_S / 2) return null;
+ return clampRange({ start_s: anchorS, end_s: currentS }, limits);
+}
+
+export function defaultRange(limits: RangeLimits): WaveRange | null {
+ const duration = Math.max(0, limits.durationS);
+ const width = Math.max(MIN_RANGE_S, duration / 5);
+ return clampRange(
+ { start_s: (duration - width) / 2, end_s: (duration + width) / 2 },
+ limits,
+ );
+}
+
+export function nextFreeRange(
+ ranges: readonly WaveRange[],
+ limits: RangeLimits,
+): WaveRange | null {
+ const duration = Math.max(0, limits.durationS);
+ if (duration < MIN_RANGE_S || ranges.length >= limits.maxRanges) return null;
+ if (ranges.length === 0) return defaultRange(limits);
+ const sorted = [...ranges].sort((a, b) => a.start_s - b.start_s);
+ let best: { start: number; end: number } | null = null;
+ let cursor = 0;
+ for (const range of [...sorted, { start_s: duration, end_s: duration }]) {
+ const end = Math.min(range.start_s, duration);
+ if (end - cursor > (best ? best.end - best.start : 0))
+ best = { start: cursor, end };
+ cursor = Math.max(cursor, range.end_s);
+ }
+ if (!best || best.end - best.start < MIN_RANGE_S + 0.2) return null;
+ const gap = best.end - best.start - 0.2;
+ const width = Math.max(MIN_RANGE_S, Math.min(gap, duration / 5));
+ const start = best.start + 0.1 + (gap - width) / 2;
+ return clampRange({ start_s: start, end_s: start + width }, limits);
+}
+
+export function secondsBeyondEnd(range: WaveRange, durationS: number): number {
+ return Math.max(0, round(range.end_s - durationS));
+}
+
+export function formatRangeTime(seconds: number): string {
+ const tenths = Math.max(0, Math.round(seconds * 10));
+ const minutes = Math.floor(tenths / 600);
+ const rest = (tenths % 600) / 10;
+ return `${minutes}:${rest.toFixed(1).padStart(4, "0")}`;
+}
+
+export function formatRange(range: WaveRange): string {
+ return `${formatRangeTime(range.start_s)}–${formatRangeTime(range.end_s)}`;
+}
+
+export function rangeLabel(index: number, range: WaveRange): string {
+ const say = (seconds: number) => String(Math.round(seconds * 10) / 10);
+ return `Range ${index + 1}, ${say(range.start_s)} to ${say(range.end_s)} seconds`;
+}
diff --git a/studio/frontend/src/features/audio/components/waveform.tsx b/studio/frontend/src/features/audio/components/waveform.tsx
index e4b89847c4c..24f5acbc0ff 100644
--- a/studio/frontend/src/features/audio/components/waveform.tsx
+++ b/studio/frontend/src/features/audio/components/waveform.tsx
@@ -6,6 +6,7 @@ import { cn } from "@/lib/utils";
import { PauseIcon, PlayIcon } from "@hugeicons/core-free-icons";
import { HugeiconsIcon } from "@hugeicons/react";
import {
+ type ReactNode,
type Ref,
useCallback,
useEffect,
@@ -29,6 +30,8 @@ export function Waveform({
src,
label,
className,
+ tailS = 0,
+ overlay,
controlRef,
onPositionChange,
}: {
@@ -38,6 +41,8 @@ export function Waveform({
src: string | null;
label: string;
className?: string;
+ tailS?: number;
+ overlay?: ReactNode;
controlRef?: Ref<WaveformControl>;
onPositionChange?: (seconds: number, playing: boolean) => void;
}) {
@@ -100,6 +105,72 @@ export function Waveform({
onPositionChange?.(position, playing);
}, [onPositionChange, position, playing]);
+ const slider = (
+ <div
+ role="slider"
+ tabIndex={src ? 0 : -1}
+ aria-label={`${label} playback position`}
+ aria-valuemin={0}
+ aria-valuemax={Math.round(duration)}
+ aria-valuenow={Math.round(position)}
+ aria-valuetext={`${formatSeconds(position)} of ${formatSeconds(duration)}`}
+ aria-disabled={!src}
+ style={tailS > 0 ? { flexGrow: duration > 0 ? duration : 1 } : undefined}
+ className="relative h-[calc(32px*var(--ui-space-scale,1))] min-w-0 flex-1 cursor-pointer rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ onKeyDown={(event) => {
+ if (event.key === " ") {
+ event.preventDefault();
+ toggle();
+ } else if (event.key === "ArrowRight") {
+ event.preventDefault();
+ seekTo(position + SEEK_STEP_SECONDS);
+ } else if (event.key === "ArrowLeft") {
+ event.preventDefault();
+ seekTo(position - SEEK_STEP_SECONDS);
+ } else if (event.key === "Home") {
+ event.preventDefault();
+ seekTo(0);
+ }
+ }}
+ onClick={(event) => {
+ const box = event.currentTarget.getBoundingClientRect();
+ if (box.width <= 0) return;
+ seekTo(((event.clientX - box.left) / box.width) * duration);
+ }}
+ >
+ <svg
+ aria-hidden="true"
+ className="size-full"
+ viewBox={`0 0 ${count * 3} 32`}
+ preserveAspectRatio="none"
+ >
+ {Array.from({ length: count }, (_, index) => {
+ const peak = bars ? (bars[index] ?? 0) : 0;
+ const height = Math.max(2, peak * 30);
+ const played = (index + 0.5) / count <= fraction;
+ return (
+ <rect
+ // biome-ignore lint/suspicious/noArrayIndexKey: bars are positional and never reorder.
+ key={index}
+ x={index * 3 + 0.5}
+ y={(32 - height) / 2}
+ width={2}
+ height={height}
+ rx={1}
+ className={cn(
+ "fill-current",
+ played && position > 0
+ ? "text-foreground"
+ : "text-muted-foreground",
+ bars ? "opacity-100" : "opacity-40",
+ )}
+ />
+ );
+ })}
+ </svg>
+ </div>
+ );
+
return (
<div className={cn("flex items-center gap-2", className)}>
<Button
@@ -116,68 +187,21 @@ export function Waveform({
className="size-3.5"
/>
</Button>
- <div
- role="slider"
- tabIndex={src ? 0 : -1}
- aria-label={`${label} playback position`}
- aria-valuemin={0}
- aria-valuemax={Math.round(duration)}
- aria-valuenow={Math.round(position)}
- aria-valuetext={`${formatSeconds(position)} of ${formatSeconds(duration)}`}
- aria-disabled={!src}
- className="relative h-[calc(32px*var(--ui-space-scale,1))] min-w-0 flex-1 cursor-pointer rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
- onKeyDown={(event) => {
- if (event.key === " ") {
- event.preventDefault();
- toggle();
- } else if (event.key === "ArrowRight") {
- event.preventDefault();
- seekTo(position + SEEK_STEP_SECONDS);
- } else if (event.key === "ArrowLeft") {
- event.preventDefault();
- seekTo(position - SEEK_STEP_SECONDS);
- } else if (event.key === "Home") {
- event.preventDefault();
- seekTo(0);
- }
- }}
- onClick={(event) => {
- const box = event.currentTarget.getBoundingClientRect();
- if (box.width <= 0) return;
- seekTo(((event.clientX - box.left) / box.width) * duration);
- }}
- >
- <svg
- aria-hidden="true"
- className="size-full"
- viewBox={`0 0 ${count * 3} 32`}
- preserveAspectRatio="none"
- >
- {Array.from({ length: count }, (_, index) => {
- const peak = bars ? (bars[index] ?? 0) : 0;
- const height = Math.max(2, peak * 30);
- const played = (index + 0.5) / count <= fraction;
- return (
- <rect
- // biome-ignore lint/suspicious/noArrayIndexKey: bars are positional and never reorder.
- key={index}
- x={index * 3 + 0.5}
- y={(32 - height) / 2}
- width={2}
- height={height}
- rx={1}
- className={cn(
- "fill-current",
- played && position > 0
- ? "text-foreground"
- : "text-muted-foreground",
- bars ? "opacity-100" : "opacity-40",
- )}
- />
- );
- })}
- </svg>
- </div>
+ {overlay !== undefined || tailS > 0 ? (
+ <div className="relative flex h-[calc(32px*var(--ui-space-scale,1))] min-w-0 flex-1">
+ {slider}
+ {tailS > 0 ? (
+ <div
+ aria-hidden="true"
+ className="h-full min-w-0 basis-0 rounded-md border border-dashed border-border bg-muted/40"
+ style={{ flexGrow: tailS }}
+ />
+ ) : null}
+ {overlay}
+ </div>
+ ) : (
+ slider
+ )}
<span className="shrink-0 font-mono text-ui-11p5 tabular-nums text-muted-foreground">
{position > 0 ? `${formatSeconds(position)} / ` : ""}
{formatSeconds(duration)}
diff --git a/studio/frontend/src/features/audio/hooks/use-clone-generation.ts b/studio/frontend/src/features/audio/hooks/use-clone-generation.ts
index e8b81b0ea7d..c27df39901c 100644
--- a/studio/frontend/src/features/audio/hooks/use-clone-generation.ts
+++ b/studio/frontend/src/features/audio/hooks/use-clone-generation.ts
@@ -55,7 +55,7 @@ export async function showRunResult({
}: {
response: AudioRunResponse;
text: string;
- workflow: "speak" | "clone";
+ workflow: "speak" | "clone" | "music";
} & Pick<
AudioGallery,
"refreshGallery" | "selectClip" | "setFallbackClip" | "setSelectedId"
diff --git a/studio/frontend/src/features/audio/hooks/use-music-generation.ts b/studio/frontend/src/features/audio/hooks/use-music-generation.ts
new file mode 100644
index 00000000000..3d08860c553
--- /dev/null
+++ b/studio/frontend/src/features/audio/hooks/use-music-generation.ts
@@ -0,0 +1,324 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { toast } from "@/lib/toast";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { runAudio } from "../api";
+import {
+ type AudioOptionSpec,
+ type AudioOptionValues,
+ audioOptionLabel,
+ audioOptionsForRequest,
+ missingRequiredAudioOptions,
+} from "../audio-options";
+import { selectionExpired } from "../audio-run-request";
+import type { AudioSourceInputHandle } from "../components/audio-source-input";
+import { musicEditProblem } from "../components/music-edit-inputs";
+import {
+ buildMusicRunRequest,
+ effectiveMusicMode,
+ musicBlocker,
+ reloadNotice,
+ variationsFor,
+} from "../music/music-policy";
+import { parseMusicCapabilities } from "../music/music-types";
+import type {
+ MusicCapabilities,
+ MusicMode,
+ MusicModeRule,
+} from "../music/music-types";
+import type { GenerateBlocker } from "../pages/tts-workspace";
+import { useAudioMusicStore } from "../stores/audio-music-store";
+import type { AudioHostState } from "./audio-host-state";
+import type { AudioSourceStatus } from "./audio-source-state";
+import { REFERENCE_EXPIRED_MESSAGE } from "./audio-source-state";
+import type { AudioGallery } from "./use-audio-gallery";
+import type { AudioModelSlot } from "./use-audio-model-slot";
+import { showRunResult } from "./use-clone-generation";
+
+const MUSIC_PREVIEW_CAPABILITIES: MusicCapabilities = {
+ modes: [
+ {
+ id: "song",
+ lyrics: "optional",
+ description: "optional",
+ instrumental: "toggle",
+ section_case: "lower",
+ duration: { min: 5, max: 240, default: 30, approximate: false },
+ variations: null,
+ },
+ ],
+};
+
+function requestedVariations(
+ rule: MusicModeRule,
+ song: { variations: number },
+ sfx: { variations: number },
+): number {
+ if (rule.id === "song") return variationsFor(rule, song.variations);
+ if (rule.id === "sfx") return variationsFor(rule, sfx.variations);
+ return 1;
+}
+
+export function useMusicGeneration({
+ status,
+ busyRef,
+ setBusy,
+ updateGenerationPhase,
+ generateAbort,
+ setMode,
+ setAdvancedOpen,
+ refreshStatus,
+ activeRef,
+ modeRef,
+ refreshGallery,
+ selectClip,
+ setFallbackClip,
+ setSelectedId,
+ pendingTranscribeRelease,
+ replayQueuedTtsPick,
+ lyrics,
+ description,
+ advancedOptionSpecs,
+ audioOptionValues,
+ toolOptions,
+ toolBlocker,
+ modelName,
+ musicLoaded,
+}: Pick<
+ AudioHostState,
+ | "status"
+ | "busyRef"
+ | "setBusy"
+ | "updateGenerationPhase"
+ | "generateAbort"
+ | "setMode"
+ | "setAdvancedOpen"
+ | "refreshStatus"
+ | "activeRef"
+ | "modeRef"
+> &
+ Pick<
+ AudioGallery,
+ "refreshGallery" | "selectClip" | "setFallbackClip" | "setSelectedId"
+ > &
+ Pick<AudioModelSlot, "pendingTranscribeRelease" | "replayQueuedTtsPick"> & {
+ lyrics: string;
+ description: string;
+ advancedOptionSpecs: AudioOptionSpec[];
+ audioOptionValues: AudioOptionValues;
+ toolOptions: AudioOptionValues | undefined;
+ toolBlocker: string | null;
+ modelName: string | null;
+ musicLoaded: boolean;
+ }) {
+ const capabilities = useMemo(
+ () =>
+ parseMusicCapabilities(status?.audio_music) ??
+ (musicLoaded ? null : MUSIC_PREVIEW_CAPABILITIES),
+ [status?.audio_music, musicLoaded],
+ );
+ const pickedMode = useAudioMusicStore((state) => state.mode);
+ const song = useAudioMusicStore((state) => state.song);
+ const sfx = useAudioMusicStore((state) => state.sfx);
+ const edit = useAudioMusicStore((state) => state.edit);
+ const rule = capabilities
+ ? effectiveMusicMode(capabilities, pickedMode)
+ : null;
+ const [generationError, setGenerationError] = useState<string | null>(null);
+ const [runStatus, setRunStatus] = useState<string | null>(null);
+ const [sourceStatus, setSourceStatus] = useState<AudioSourceStatus>({
+ phase: "idle",
+ });
+ const sourceHandle = useRef<AudioSourceInputHandle | null>(null);
+
+ const editActions = useMemo(
+ () => capabilities?.modes.find((mode) => mode.id === "edit")?.actions ?? [],
+ [capabilities],
+ );
+ useEffect(() => {
+ useAudioMusicStore.getState().setLoadedEditActions(editActions);
+ }, [editActions]);
+
+ const setMusicMode = useCallback((mode: MusicMode) => {
+ useAudioMusicStore.getState().setMode(mode);
+ }, []);
+
+ const variations = rule ? requestedVariations(rule, song, sfx) : 1;
+ const notice = rule ? reloadNotice(rule, variations, modelName) : null;
+
+ const sourceExpired =
+ sourceStatus.phase === "expired" ||
+ selectionExpired(edit.source, Date.now());
+ const editProblem =
+ rule?.id === "edit"
+ ? sourceStatus.phase === "uploading" || sourceStatus.phase === "recording"
+ ? "Waiting for the clip to finish uploading."
+ : sourceStatus.phase === "error"
+ ? sourceStatus.message
+ : sourceExpired
+ ? REFERENCE_EXPIRED_MESSAGE
+ : musicEditProblem(rule, edit, edit.source?.durationS ?? null)
+ : null;
+ const pageProblem = rule
+ ? musicBlocker({ rule, description, lyrics, song, sfx, edit, editProblem })
+ : null;
+ const blocker: GenerateBlocker | null = !rule
+ ? null
+ : pageProblem
+ ? {
+ reason: pageProblem,
+ ...(rule.id === "edit" && !edit.source
+ ? {
+ actions: [
+ {
+ label: "Add a clip",
+ onClick: () => sourceHandle.current?.browse(),
+ },
+ ],
+ }
+ : {}),
+ }
+ : toolBlocker
+ ? { reason: toolBlocker }
+ : null;
+
+ const handleGenerate = useCallback(async () => {
+ if (!rule || blocker) return;
+ if (busyRef.current) return;
+ busyRef.current = "generating";
+ setBusy("generating");
+ updateGenerationPhase("preparing");
+ const releaseInFlight = pendingTranscribeRelease.current;
+ if (releaseInFlight && !(await releaseInFlight)) {
+ updateGenerationPhase(null);
+ busyRef.current = null;
+ setBusy(null);
+ setMode("transcribe");
+ return;
+ }
+ const missingOptions = missingRequiredAudioOptions(
+ advancedOptionSpecs,
+ audioOptionValues,
+ );
+ if (missingOptions.length > 0) {
+ updateGenerationPhase(null);
+ busyRef.current = null;
+ setBusy(null);
+ setAdvancedOpen(true);
+ toast.error(
+ `Set ${missingOptions.map((spec) => audioOptionLabel(spec.name)).join(", ")} in Advanced before generating.`,
+ );
+ return;
+ }
+ const request = buildMusicRunRequest({
+ rule,
+ description,
+ lyrics,
+ song,
+ sfx,
+ edit,
+ // Panel options override Advanced: panels own their options.
+ options: {
+ ...audioOptionsForRequest(advancedOptionSpecs, audioOptionValues),
+ ...toolOptions,
+ },
+ });
+ const reloads = notice !== null;
+ setRunStatus(
+ reloads
+ ? `Reloading ${modelName ?? "the model"} for ${variations} variations…`
+ : rule.id === "edit"
+ ? "Editing the clip…"
+ : variations > 1
+ ? `Making ${variations} variations…`
+ : rule.id === "sfx"
+ ? "Making the sound…"
+ : "Making the music…",
+ );
+ const controller = new AbortController();
+ generateAbort.current = controller;
+ updateGenerationPhase("generating");
+ try {
+ const response = await runAudio(request, controller.signal);
+ updateGenerationPhase("finishing");
+ await showRunResult({
+ response,
+ text: request.text || request.music?.lyrics || "",
+ workflow: "music",
+ refreshGallery,
+ selectClip,
+ setFallbackClip,
+ setSelectedId,
+ });
+ if (reloads) await refreshStatus();
+ } catch (error) {
+ if (!controller.signal.aborted) {
+ updateGenerationPhase("finishing");
+ const message =
+ error instanceof Error ? error.message : "Music generation failed.";
+ setGenerationError(message);
+ toast.error(message);
+ await refreshStatus();
+ }
+ } finally {
+ setRunStatus(null);
+ generateAbort.current = null;
+ updateGenerationPhase(null);
+ busyRef.current = null;
+ setBusy(null);
+ if (activeRef.current && modeRef.current === "speak")
+ replayQueuedTtsPick();
+ }
+ }, [
+ rule,
+ blocker,
+ busyRef,
+ setBusy,
+ updateGenerationPhase,
+ pendingTranscribeRelease,
+ setMode,
+ advancedOptionSpecs,
+ audioOptionValues,
+ setAdvancedOpen,
+ description,
+ lyrics,
+ song,
+ sfx,
+ edit,
+ toolOptions,
+ notice,
+ modelName,
+ variations,
+ generateAbort,
+ refreshGallery,
+ selectClip,
+ setFallbackClip,
+ setSelectedId,
+ refreshStatus,
+ activeRef,
+ modeRef,
+ replayQueuedTtsPick,
+ ]);
+
+ return {
+ studio: capabilities !== null,
+ capabilities,
+ rule,
+ setMusicMode,
+ song,
+ sfx,
+ edit,
+ variations,
+ reloadNotice: notice,
+ blocker,
+ handleGenerate,
+ generationError,
+ setGenerationError,
+ runStatus,
+ setSourceStatus,
+ sourceHandle,
+ };
+}
+
+export type MusicGeneration = ReturnType<typeof useMusicGeneration>;
diff --git a/studio/frontend/src/features/audio/hooks/use-speech-generation.ts b/studio/frontend/src/features/audio/hooks/use-speech-generation.ts
index 61914b217d1..63c3035d84c 100644
--- a/studio/frontend/src/features/audio/hooks/use-speech-generation.ts
+++ b/studio/frontend/src/features/audio/hooks/use-speech-generation.ts
@@ -548,6 +548,7 @@ export function useSpeechGeneration({
toolValues,
handleToolValueChange,
toolBlocker: toolRequest.error,
+ toolOptions: toolRequest.patch.options,
claimedOptions,
advancedOptionSpecs,
};
diff --git a/studio/frontend/src/features/audio/music/music-edit-rules.ts b/studio/frontend/src/features/audio/music/music-edit-rules.ts
new file mode 100644
index 00000000000..83a047621a8
--- /dev/null
+++ b/studio/frontend/src/features/audio/music/music-edit-rules.ts
@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { MIN_RANGE_S } from "../components/waveform-range";
+import type {
+ MusicEditAction,
+ MusicEditDraft,
+ MusicModeRule,
+} from "./music-types";
+
+export const MUSIC_EDIT_ACTION_LABEL: Record<MusicEditAction, string> = {
+ repaint: "Repaint",
+ extend: "Extend",
+ cover: "Cover",
+ continue: "Add parts",
+ inpaint: "Inpaint",
+ restyle: "Restyle",
+};
+
+export const MUSIC_EDIT_ACTION_HINT: Record<MusicEditAction, string> = {
+ repaint:
+ "Regenerate the selected part, keep the rest. Drag past the end to make it longer.",
+ extend: "Add new music after the end.",
+ cover: "Same structure, new style.",
+ continue: "Adds new parts across the whole track.",
+ inpaint: "Regenerate the selected parts.",
+ restyle: "Re-render the whole clip in a new style.",
+};
+
+export const REPAINT_BEYOND_END_S = 30;
+
+export const EXTEND_MIN_S = 5;
+export const EXTEND_MAX_S = 120;
+
+export const MUSIC_EDIT_DEFAULT_STRENGTH: Partial<
+ Record<MusicEditAction, number>
+> = {
+ cover: 0.5,
+ restyle: 0.45,
+};
+
+export function editUsesRanges(action: MusicEditAction | null): boolean {
+ return action === "repaint" || action === "inpaint";
+}
+
+export function editUsesStrength(action: MusicEditAction | null): boolean {
+ return action === "cover" || action === "restyle";
+}
+
+export function editMaxRanges(
+ rule: MusicModeRule,
+ action: MusicEditAction | null,
+): number {
+ if (action === "repaint") return 1;
+ if (action === "inpaint") return Math.max(1, rule.max_ranges ?? 1);
+ return 0;
+}
+
+export function editBeyondEndS(action: MusicEditAction | null): number {
+ return action === "repaint" ? REPAINT_BEYOND_END_S : 0;
+}
+
+export function editActions(rule: MusicModeRule): MusicEditAction[] {
+ return rule.actions ?? [];
+}
+
+export function formatEditLimit(seconds: number): string {
+ if (seconds >= 60 && seconds % 60 === 0) {
+ const minutes = seconds / 60;
+ return `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+ }
+ return `${Math.round(seconds)} s`;
+}
+
+export function editSourceTooLong(
+ rule: MusicModeRule,
+ sourceDurationS: number | null,
+): string | null {
+ if (rule.max_source_s === undefined || sourceDurationS === null) return null;
+ return sourceDurationS > rule.max_source_s
+ ? `Edit clips up to ${formatEditLimit(rule.max_source_s)}. Trim it first.`
+ : null;
+}
+
+// Times come back rounded to a hundredth; allow that much slack.
+const EPSILON = 0.011;
+
+export function editRangeProblem(
+ rule: MusicModeRule,
+ draft: Pick<MusicEditDraft, "action" | "ranges">,
+ sourceDurationS: number | null,
+): string | null {
+ const { action, ranges } = draft;
+ if (!editUsesRanges(action)) return null;
+ if (ranges.length === 0) {
+ return action === "inpaint"
+ ? "Select the parts to change on the waveform."
+ : "Select the part to change on the waveform.";
+ }
+ const max = editMaxRanges(rule, action);
+ if (ranges.length > max) {
+ return max === 1
+ ? "Select one part to change."
+ : `Select up to ${max} parts.`;
+ }
+ for (const range of ranges) {
+ if (
+ !(Number.isFinite(range.start_s) && Number.isFinite(range.end_s)) ||
+ range.start_s < 0 ||
+ range.end_s - range.start_s < MIN_RANGE_S - EPSILON
+ ) {
+ return `Make each selected part at least ${MIN_RANGE_S} s long.`;
+ }
+ if (sourceDurationS === null) continue;
+ if (range.start_s >= sourceDurationS) {
+ return "A selected part starts after the clip ends. Move it inside the clip.";
+ }
+ if (range.end_s > sourceDurationS + editBeyondEndS(action) + EPSILON) {
+ return action === "repaint"
+ ? `A repaint can reach at most ${REPAINT_BEYOND_END_S} s past the end.`
+ : "A selected part runs past the end of the clip.";
+ }
+ }
+ return null;
+}
+
+export function musicEditProblem(
+ rule: MusicModeRule,
+ draft: MusicEditDraft,
+ sourceDurationS: number | null,
+): string | null {
+ if (!draft.source) return "Pick a clip to edit.";
+ const actions = editActions(rule);
+ if (actions.length === 0) return "This model cannot edit clips.";
+ if (!(draft.action && actions.includes(draft.action))) {
+ return "Pick what to do with the clip.";
+ }
+ const tooLong = editSourceTooLong(rule, sourceDurationS);
+ if (tooLong) return tooLong;
+ const rangeProblem = editRangeProblem(rule, draft, sourceDurationS);
+ if (rangeProblem) return rangeProblem;
+ if (
+ draft.action === "extend" &&
+ !(draft.extendS >= EXTEND_MIN_S && draft.extendS <= EXTEND_MAX_S)
+ ) {
+ return `Add between ${EXTEND_MIN_S} and ${EXTEND_MAX_S} seconds.`;
+ }
+ if (!draft.prompt.trim()) {
+ return editUsesStrength(draft.action)
+ ? "Describe the new style."
+ : "Describe what the new part should sound like.";
+ }
+ return null;
+}
+
+export type SendAction = "edit" | "extend";
+
+export function sendActionsFor(
+ editActions: readonly string[],
+): readonly SendAction[] {
+ if (editActions.length === 0) return [];
+ return editActions.includes("extend") ? ["edit", "extend"] : ["edit"];
+}
diff --git a/studio/frontend/src/features/audio/music/music-policy.ts b/studio/frontend/src/features/audio/music/music-policy.ts
new file mode 100644
index 00000000000..d4e64ab8640
--- /dev/null
+++ b/studio/frontend/src/features/audio/music/music-policy.ts
@@ -0,0 +1,351 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// No app imports: the node test runner loads this directly.
+
+import type {
+ AudioOptionScalar,
+ AudioRunRequest,
+ AudioSourceSelection,
+} from "../audio-run-request";
+import { sourceRefOf } from "../audio-run-request";
+import { MUSIC_EDIT_DEFAULT_STRENGTH } from "./music-edit-rules";
+import type {
+ MusicCapabilities,
+ MusicEditDraft,
+ MusicMode,
+ MusicModeRule,
+ MusicSfxDraft,
+ MusicSongDraft,
+} from "./music-types";
+
+export const MUSIC_MODE_LABELS: Record<MusicMode, string> = {
+ song: "Song",
+ sfx: "Sound effect",
+ edit: "Edit",
+};
+
+export const MUSIC_MODE_HINTS: Record<MusicMode, string> = {
+ song: "A song or an instrumental from a description and lyrics.",
+ sfx: "A short sound from a description.",
+ edit: "Change part of a clip, extend it, or give it a new style.",
+};
+
+export function musicModeLabel(rule: MusicModeRule): string {
+ return rule.id === "song" && rule.instrumental === "always"
+ ? "Instrumental"
+ : MUSIC_MODE_LABELS[rule.id];
+}
+
+export function musicModeHint(rule: MusicModeRule): string {
+ return rule.id === "song" && rule.instrumental === "always"
+ ? "Music without vocals, from a description."
+ : MUSIC_MODE_HINTS[rule.id];
+}
+
+export const MUSIC_MAX_VARIATIONS = 4;
+
+export function effectiveMusicMode(
+ capabilities: MusicCapabilities,
+ picked: MusicMode,
+): MusicModeRule {
+ return (
+ capabilities.modes.find((rule) => rule.id === picked) ??
+ capabilities.modes[0]
+ );
+}
+
+const SECTION_NAMES = [
+ "Intro",
+ "Verse",
+ "Pre-chorus",
+ "Chorus",
+ "Bridge",
+ "Outro",
+] as const;
+
+export interface SectionTag {
+ name: string;
+ tag: string;
+}
+
+export function sectionTags(
+ sectionCase: MusicModeRule["section_case"],
+): SectionTag[] {
+ return SECTION_NAMES.map((name) => ({
+ name,
+ tag:
+ sectionCase === "title"
+ ? `[${name.replace(/(^|-)([a-z])/g, (_m, dash: string, ch: string) => dash + ch.toUpperCase())}]`
+ : `[${name.toLowerCase()}]`,
+ }));
+}
+
+export function insertSectionTag(
+ text: string,
+ cursor: number,
+ tag: string,
+): { text: string; cursor: number } {
+ const at = Math.max(0, Math.min(cursor, text.length));
+ const before = text.slice(0, at);
+ const after = text.slice(at);
+ const lead =
+ before.length === 0
+ ? ""
+ : before.endsWith("\n\n")
+ ? ""
+ : before.endsWith("\n")
+ ? "\n"
+ : "\n\n";
+ const tail = after.startsWith("\n") ? "" : "\n";
+ const inserted = `${lead}${tag}${tail}`;
+ return {
+ text: before + inserted + after,
+ cursor: before.length + lead.length + tag.length + 1,
+ };
+}
+
+export interface InstrumentalChoice {
+ shown: boolean;
+ enabled: boolean;
+ value: boolean;
+ reason: string | null;
+}
+
+export function instrumentalChoice(
+ rule: MusicModeRule,
+ picked: boolean,
+): InstrumentalChoice {
+ switch (rule.instrumental) {
+ case "toggle":
+ return { shown: true, enabled: true, value: picked, reason: null };
+ case "always":
+ return {
+ shown: false,
+ enabled: false,
+ value: true,
+ reason: "This model makes instrumentals only.",
+ };
+ case "never":
+ return {
+ shown: true,
+ enabled: false,
+ value: false,
+ reason: "This model always sings the lyrics.",
+ };
+ default:
+ return { shown: false, enabled: false, value: false, reason: null };
+ }
+}
+
+export function lyricsShown(
+ rule: MusicModeRule,
+ instrumental: boolean,
+): boolean {
+ if (rule.id !== "song") return false;
+ if (rule.lyrics === "unused" || rule.lyrics === undefined) return false;
+ return !instrumental;
+}
+
+export function durationLabel(rule: MusicModeRule): string {
+ return rule.duration?.approximate
+ ? "Length (seconds, approximate)"
+ : "Length (seconds)";
+}
+
+export function musicDurationFor(
+ rule: MusicModeRule,
+ picked: number | null,
+): number | null {
+ const duration = rule.duration;
+ if (!duration) return null;
+ if (picked === null || !Number.isFinite(picked)) return duration.default;
+ return Math.min(duration.max, Math.max(duration.min, picked));
+}
+
+export function variationsMax(rule: MusicModeRule): number | null {
+ const variations = rule.variations;
+ if (!variations || variations.max < 2) return null;
+ return Math.min(variations.max, MUSIC_MAX_VARIATIONS);
+}
+
+export function variationsFor(rule: MusicModeRule, picked: number): number {
+ const max = variationsMax(rule);
+ if (max === null) return 1;
+ return Math.max(1, Math.min(max, Math.floor(picked) || 1));
+}
+
+export function reloadNotice(
+ rule: MusicModeRule,
+ variations: number,
+ modelName: string | null,
+): string | null {
+ const rules = rule.variations;
+ if (!rules || rules.how !== "batch" || variations <= rules.loaded)
+ return null;
+ const name = modelName?.trim() || "the model";
+ return `Reloads ${name} to make ${variations} variations at once, about 15 s the first time.`;
+}
+
+export const MUSIC_EXAMPLES = {
+ description: [
+ {
+ label: "Acoustic pop",
+ text: "Upbeat acoustic pop, bright female vocals, guitar and light drums, 100 BPM",
+ },
+ {
+ label: "Lo-fi hip hop",
+ text: "Lo-fi hip hop beat, warm vinyl crackle, mellow piano, relaxed",
+ },
+ {
+ label: "Orchestral",
+ text: "Epic orchestral trailer music, big drums, rising strings",
+ },
+ ],
+ instrumental: [
+ {
+ label: "Lo-fi",
+ text: "Warm lo-fi hip hop beat, vinyl crackle, mellow piano, relaxed",
+ },
+ {
+ label: "House",
+ text: "Uplifting house music with bright synths, 124 BPM",
+ },
+ {
+ label: "Orchestral",
+ text: "Epic orchestral trailer music, big drums, rising strings",
+ },
+ ],
+ lyrics: [
+ {
+ label: "River song",
+ text: "Sunlight on the river, golden in the morning\nWe walk along the water, singing as we go\n\nOh, oh, the river runs\nOh, oh, into the sun",
+ },
+ ],
+ sfx: [
+ { label: "Rain", text: "Heavy rain on a tin roof with distant thunder" },
+ { label: "Footsteps", text: "Footsteps on gravel, slow walk" },
+ { label: "Creaky door", text: "A door creaking open in an empty hall" },
+ ],
+ edit: [
+ "Same melody with a saxophone lead",
+ "Softer, with only piano and strings",
+ ],
+} as const;
+
+export function exampleLyrics(
+ sectionCase: MusicModeRule["section_case"],
+ text: string,
+): string {
+ const [verse, chorus] = text.split("\n\n");
+ const tags = sectionTags(sectionCase);
+ const tag = (name: string) => tags.find((item) => item.name === name)?.tag;
+ return chorus
+ ? `${tag("Verse")}\n${verse}\n\n${tag("Chorus")}\n${chorus}`
+ : `${tag("Verse")}\n${verse}`;
+}
+
+export interface MusicInputs {
+ rule: MusicModeRule;
+ description: string;
+ lyrics: string;
+ song: MusicSongDraft;
+ sfx: MusicSfxDraft;
+ edit: MusicEditDraft;
+ editProblem?: string | null;
+}
+
+export function musicBlocker(inputs: MusicInputs): string | null {
+ const { rule } = inputs;
+ if (rule.id === "song") {
+ const instrumental = instrumentalChoice(
+ rule,
+ inputs.song.instrumental,
+ ).value;
+ const description = inputs.description.trim();
+ const lyrics = inputs.lyrics.trim();
+ if (rule.description === "required" && !description)
+ return "Describe the music. This model needs a description.";
+ if (rule.lyrics === "required" && !instrumental && !lyrics)
+ return "Write the lyrics. This model sings them.";
+ if (!description && (!lyrics || instrumental))
+ return instrumental
+ ? "Describe the music you want."
+ : "Describe the music or write lyrics.";
+ return null;
+ }
+ if (rule.id === "sfx") {
+ return inputs.sfx.prompt.trim() ? null : "Describe the sound you want.";
+ }
+ return inputs.editProblem ?? null;
+}
+
+export function buildMusicRunRequest(
+ inputs: MusicInputs & {
+ options?: Record<string, AudioOptionScalar>;
+ seed?: number | null;
+ },
+): AudioRunRequest {
+ const { rule } = inputs;
+ const base = {
+ workflow: "music" as const,
+ options: inputs.options,
+ seed: inputs.seed ?? null,
+ };
+ if (rule.id === "song") {
+ const instrumental = instrumentalChoice(
+ rule,
+ inputs.song.instrumental,
+ ).value;
+ const sendLyrics = lyricsShown(rule, instrumental);
+ return {
+ ...base,
+ text: inputs.description.trim(),
+ music: {
+ mode: "song",
+ lyrics: sendLyrics ? inputs.lyrics : null,
+ instrumental: rule.instrumental === "toggle" ? instrumental : false,
+ duration_s: musicDurationFor(rule, inputs.song.durationS),
+ variations: variationsFor(rule, inputs.song.variations),
+ },
+ };
+ }
+ if (rule.id === "sfx") {
+ return {
+ ...base,
+ text: inputs.sfx.prompt.trim(),
+ music: {
+ mode: "sfx",
+ duration_s: musicDurationFor(rule, inputs.sfx.durationS),
+ variations: variationsFor(rule, inputs.sfx.variations),
+ },
+ };
+ }
+ const edit = inputs.edit;
+ const action = edit.action ?? rule.actions?.[0] ?? "repaint";
+ const usesRanges = action === "repaint" || action === "inpaint";
+ return {
+ ...base,
+ text: edit.prompt.trim(),
+ music: {
+ mode: "edit",
+ source: editSourceRef(edit.source),
+ duration_s: action === "continue" ? musicDurationFor(rule, null) : null,
+ edit: {
+ action,
+ ranges: usesRanges ? edit.ranges : [],
+ // Send the value the slider shows; the runtime defaults (1.0) differ.
+ strength:
+ action === "cover" || action === "restyle"
+ ? (edit.strength ?? MUSIC_EDIT_DEFAULT_STRENGTH[action] ?? null)
+ : null,
+ extend_s: action === "extend" ? edit.extendS : null,
+ },
+ },
+ };
+}
+
+function editSourceRef(source: AudioSourceSelection | null) {
+ if (!source || source.kind === "voice") return null;
+ return sourceRefOf(source);
+}
diff --git a/studio/frontend/src/features/audio/music/music-types.ts b/studio/frontend/src/features/audio/music/music-types.ts
new file mode 100644
index 00000000000..f9774e4406b
--- /dev/null
+++ b/studio/frontend/src/features/audio/music/music-types.ts
@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// No app imports: the node test runner loads this directly.
+
+import type { AudioSourceSelection } from "../audio-run-request";
+
+export type MusicMode = "song" | "sfx" | "edit";
+
+export const MUSIC_MODES: readonly MusicMode[] = ["song", "sfx", "edit"];
+
+export type MusicEditAction =
+ | "repaint"
+ | "extend"
+ | "cover"
+ | "continue"
+ | "inpaint"
+ | "restyle";
+
+export const MUSIC_EDIT_ACTIONS: readonly MusicEditAction[] = [
+ "repaint",
+ "extend",
+ "cover",
+ "continue",
+ "inpaint",
+ "restyle",
+];
+
+export interface MusicRange {
+ start_s: number;
+ end_s: number;
+}
+
+export interface MusicDurationRule {
+ min: number;
+ max: number;
+ default: number;
+ approximate: boolean;
+}
+
+export interface MusicVariationsRule {
+ max: number;
+ how: "batch" | "sequential";
+ loaded: number;
+}
+
+export interface MusicModeRule {
+ id: MusicMode;
+ lyrics?: "required" | "optional" | "unused";
+ description?: "required" | "optional";
+ instrumental?: "toggle" | "always" | "never";
+ section_case?: "lower" | "title" | null;
+ duration?: MusicDurationRule | null;
+ variations?: MusicVariationsRule | null;
+ actions?: MusicEditAction[];
+ max_ranges?: number;
+ max_source_s?: number;
+}
+
+export interface MusicCapabilities {
+ modes: MusicModeRule[];
+}
+
+export interface MusicSongDraft {
+ instrumental: boolean;
+ durationS: number | null;
+ variations: number;
+}
+
+export interface MusicSfxDraft {
+ prompt: string;
+ durationS: number | null;
+ variations: number;
+}
+
+export interface MusicEditDraft {
+ source: AudioSourceSelection | null;
+ action: MusicEditAction | null;
+ ranges: MusicRange[];
+ strength: number | null;
+ extendS: number;
+ prompt: string;
+}
+
+export interface MusicDrafts {
+ song: MusicSongDraft;
+ sfx: MusicSfxDraft;
+ edit: MusicEditDraft;
+}
+
+export function parseMusicCapabilities(
+ value: unknown,
+): MusicCapabilities | null {
+ if (!value || typeof value !== "object") return null;
+ const modes = (value as { modes?: unknown }).modes;
+ if (!Array.isArray(modes)) return null;
+ const parsed: MusicModeRule[] = [];
+ for (const raw of modes) {
+ if (!raw || typeof raw !== "object") continue;
+ const mode = raw as Record<string, unknown>;
+ if (!MUSIC_MODES.includes(mode.id as MusicMode)) continue;
+ if (parsed.some((rule) => rule.id === mode.id)) continue;
+ parsed.push(parseModeRule(mode));
+ }
+ return parsed.length > 0 ? { modes: parsed } : null;
+}
+
+function oneOf<T extends string>(
+ value: unknown,
+ allowed: readonly T[],
+): T | undefined {
+ return allowed.includes(value as T) ? (value as T) : undefined;
+}
+
+function finite(value: unknown): number | null {
+ return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function parseDuration(value: unknown): MusicDurationRule | null {
+ if (!value || typeof value !== "object") return null;
+ const raw = value as Record<string, unknown>;
+ const min = finite(raw.min);
+ const max = finite(raw.max);
+ if (min === null || max === null || max < min) return null;
+ const fallback = finite(raw.default);
+ return {
+ min,
+ max,
+ default:
+ fallback === null
+ ? Math.min(max, Math.max(min, 30))
+ : Math.min(max, Math.max(min, fallback)),
+ approximate: raw.approximate === true,
+ };
+}
+
+function parseVariations(value: unknown): MusicVariationsRule | null {
+ if (!value || typeof value !== "object") return null;
+ const raw = value as Record<string, unknown>;
+ const max = finite(raw.max);
+ if (max === null || max < 2) return null;
+ const loaded = finite(raw.loaded);
+ return {
+ max: Math.floor(max),
+ how: raw.how === "batch" ? "batch" : "sequential",
+ loaded: loaded === null ? 1 : Math.max(1, Math.floor(loaded)),
+ };
+}
+
+function parseModeRule(mode: Record<string, unknown>): MusicModeRule {
+ const id = mode.id as MusicMode;
+ const actions = Array.isArray(mode.actions)
+ ? mode.actions.filter((action): action is MusicEditAction =>
+ MUSIC_EDIT_ACTIONS.includes(action as MusicEditAction),
+ )
+ : undefined;
+ const maxRanges = finite(mode.max_ranges);
+ const maxSource = finite(mode.max_source_s);
+ return {
+ id,
+ lyrics: oneOf(mode.lyrics, ["required", "optional", "unused"] as const),
+ description: oneOf(mode.description, ["required", "optional"] as const),
+ instrumental: oneOf(mode.instrumental, [
+ "toggle",
+ "always",
+ "never",
+ ] as const),
+ section_case: oneOf(mode.section_case, ["lower", "title"] as const) ?? null,
+ duration: parseDuration(mode.duration),
+ variations: parseVariations(mode.variations),
+ ...(actions ? { actions } : {}),
+ ...(maxRanges !== null
+ ? { max_ranges: Math.max(0, Math.floor(maxRanges)) }
+ : {}),
+ ...(maxSource !== null ? { max_source_s: maxSource } : {}),
+ };
+}
diff --git a/studio/frontend/src/features/audio/music/variation-groups.ts b/studio/frontend/src/features/audio/music/variation-groups.ts
new file mode 100644
index 00000000000..c23979091a7
--- /dev/null
+++ b/studio/frontend/src/features/audio/music/variation-groups.ts
@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export interface GroupableClip {
+ id: string;
+ group_id?: string | null;
+ settings?: Record<string, unknown> | null;
+}
+
+export type HistoryEntry<T extends GroupableClip> =
+ | { kind: "clip"; clip: T }
+ | { kind: "group"; groupId: string; clips: T[] };
+
+function variationIndex(clip: GroupableClip): number | null {
+ const value = clip.settings?.variation;
+ return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function orderGroup<T extends GroupableClip>(clips: readonly T[]): T[] {
+ return clips
+ .map((clip, at) => ({ clip, at, index: variationIndex(clip) }))
+ .sort((a, b) =>
+ a.index !== null && b.index !== null && a.index !== b.index
+ ? a.index - b.index
+ : a.at - b.at,
+ )
+ .map((item) => item.clip);
+}
+
+function groupsOf<T extends GroupableClip>(
+ clips: readonly T[],
+): Map<string, T[]> {
+ const groups = new Map<string, T[]>();
+ for (const clip of clips) {
+ if (!clip.group_id) continue;
+ const members = groups.get(clip.group_id);
+ if (members) members.push(clip);
+ else groups.set(clip.group_id, [clip]);
+ }
+ for (const [id, members] of groups) {
+ if (members.length < 2) groups.delete(id);
+ else groups.set(id, orderGroup(members));
+ }
+ return groups;
+}
+
+export function groupHistory<T extends GroupableClip>(
+ clips: readonly T[],
+): HistoryEntry<T>[] {
+ const groups = groupsOf(clips);
+ const placed = new Set<string>();
+ const entries: HistoryEntry<T>[] = [];
+ for (const clip of clips) {
+ const members = clip.group_id ? groups.get(clip.group_id) : undefined;
+ if (!(members && clip.group_id)) {
+ entries.push({ kind: "clip", clip });
+ continue;
+ }
+ if (placed.has(clip.group_id)) continue;
+ placed.add(clip.group_id);
+ entries.push({ kind: "group", groupId: clip.group_id, clips: members });
+ }
+ return entries;
+}
+
+export function variationLabel(count: number): string {
+ return count === 1 ? "1 variation" : `${count} variations`;
+}
+
+export function variationSiblings<T extends GroupableClip>(
+ clips: readonly T[],
+ selectedId: string | null,
+): T[] {
+ if (!selectedId) return [];
+ const selected = clips.find((clip) => clip.id === selectedId);
+ if (!selected?.group_id) return [];
+ const members = clips.filter((clip) => clip.group_id === selected.group_id);
+ return members.length > 1 ? orderGroup(members) : [];
+}
+
+export type HistoryRow<T extends GroupableClip> =
+ | { clip: T; header?: undefined; nested: boolean }
+ | {
+ clip: T;
+ header: { groupId: string; clips: T[]; open: boolean };
+ nested: false;
+ };
+
+export function historyRows<T extends GroupableClip>(
+ clips: readonly T[],
+ openGroups: ReadonlySet<string>,
+): HistoryRow<T>[] {
+ const rows: HistoryRow<T>[] = [];
+ for (const entry of groupHistory(clips)) {
+ if (entry.kind === "clip") {
+ rows.push({ clip: entry.clip, nested: false });
+ continue;
+ }
+ const open = openGroups.has(entry.groupId);
+ rows.push({
+ clip: entry.clips[0],
+ header: { groupId: entry.groupId, clips: entry.clips, open },
+ nested: false,
+ });
+ if (open) for (const clip of entry.clips) rows.push({ clip, nested: true });
+ }
+ return rows;
+}
diff --git a/studio/frontend/src/features/audio/pages/music-page.tsx b/studio/frontend/src/features/audio/pages/music-page.tsx
index ee859425faa..adbba6edc46 100644
--- a/studio/frontend/src/features/audio/pages/music-page.tsx
+++ b/studio/frontend/src/features/audio/pages/music-page.tsx
@@ -1,11 +1,42 @@
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-import type { ComponentProps } from "react";
+import { Button } from "@/components/ui/button";
+import { Switch } from "@/components/ui/switch";
+import { Textarea } from "@/components/ui/textarea";
+import { ParamSlider } from "@/features/chat";
+import { PillTabs } from "@/features/model-picker/components/model-selector/pill-tabs";
import type { ModelOption } from "@/features/model-picker/components/model-selector/types";
-import { isMusicGenerationModel, macTtsCatalogChoiceIsRunnable } from "../catalog";
+import type { ComponentProps } from "react";
+import type { AudioGalleryClip } from "../api";
+import {
+ isMusicGenerationModel,
+ macTtsCatalogChoiceIsRunnable,
+} from "../catalog";
+import { AudioHistoryProvider } from "../components/audio-source-input";
+import { Field } from "../components/field";
+import { LyricsEditor } from "../components/lyrics-editor";
+import { MusicEditInputs } from "../components/music-edit-inputs";
+import type { MusicGeneration } from "../hooks/use-music-generation";
+import {
+ MUSIC_EXAMPLES,
+ durationLabel,
+ exampleLyrics,
+ instrumentalChoice,
+ lyricsShown,
+ musicDurationFor,
+ musicModeHint,
+ musicModeLabel,
+ variationsMax,
+} from "../music/music-policy";
+import type { MusicMode, MusicModeRule } from "../music/music-types";
+import { useAudioMusicStore } from "../stores/audio-music-store";
import { TtsOutput, TtsRailFields } from "./tts-workspace";
+export const MUSIC_DESCRIPTION_FIELD_ID = "music-description";
+export const MUSIC_LYRICS_FIELD_ID = "music-lyrics";
+export const MUSIC_SFX_FIELD_ID = "music-sfx-prompt";
+
export function musicPageModels(
models: ModelOption[],
isMac: boolean,
@@ -17,20 +48,438 @@ export function musicPageModels(
);
}
-export function MusicRail(
- props: Omit<ComponentProps<typeof TtsRailFields>, "musicGeneration">,
-) {
- return <TtsRailFields {...props} musicGeneration={true} />;
+/** One line under a prompt: example picks while it is empty, the hint once it has text. */
+function ExamplesOrHint({
+ label,
+ examples,
+ empty,
+ hint,
+ onPick,
+ disabled,
+}: {
+ label: string;
+ examples: readonly { label: string; text: string }[];
+ empty: boolean;
+ hint: string;
+ onPick: (text: string) => void;
+ disabled: boolean;
+}) {
+ if (!empty) {
+ return (
+ <p className="text-ui-11p5 leading-snug text-muted-foreground">{hint}</p>
+ );
+ }
+ return (
+ <fieldset
+ className="m-0 flex min-w-0 flex-wrap items-center gap-1 border-0 p-0"
+ aria-label={label}
+ >
+ <span className="me-0.5 text-ui-11p5 text-muted-foreground">Try</span>
+ {examples.map((example) => (
+ <Button
+ key={example.label}
+ type="button"
+ variant="muted"
+ size="sm"
+ disabled={disabled}
+ className="h-[calc(24px*var(--ui-space-scale,1))] px-2.5 text-ui-11p5 font-normal"
+ title={example.text}
+ onClick={() => onPick(example.text)}
+ >
+ {example.label}
+ </Button>
+ ))}
+ </fieldset>
+ );
+}
+
+function SecondsSlider({
+ rule,
+ value,
+ onChange,
+ disabled,
+}: {
+ rule: MusicModeRule;
+ value: number | null;
+ onChange: (next: number) => void;
+ disabled: boolean;
+}) {
+ const duration = rule.duration;
+ if (!duration) return null;
+ const seconds = musicDurationFor(rule, value) ?? duration.default;
+ return (
+ <ParamSlider
+ label={durationLabel(rule)}
+ value={seconds}
+ min={duration.min}
+ max={duration.max}
+ step={1}
+ valueSize={6}
+ disabled={disabled}
+ onChange={onChange}
+ info={
+ duration.approximate
+ ? "This model aims for the length; the song may end a little earlier or later."
+ : `Between ${duration.min} and ${duration.max} seconds.`
+ }
+ />
+ );
+}
+
+function VariationsSlider({
+ rule,
+ value,
+ onChange,
+ disabled,
+ notice,
+}: {
+ rule: MusicModeRule;
+ value: number;
+ onChange: (next: number) => void;
+ disabled: boolean;
+ notice: string | null;
+}) {
+ const max = variationsMax(rule);
+ if (max === null) return null;
+ return (
+ <div className="grid gap-1.5">
+ <ParamSlider
+ label="Variations"
+ value={Math.min(max, Math.max(1, value))}
+ min={1}
+ max={max}
+ step={1}
+ valueSize={2}
+ disabled={disabled}
+ onChange={onChange}
+ info="Several takes of the same request, kept together in history."
+ />
+ {notice ? (
+ <p className="text-ui-11p5 leading-snug text-muted-foreground">
+ {notice}
+ </p>
+ ) : null}
+ </div>
+ );
+}
+
+function SongInputs({
+ rule,
+ music,
+ lyrics,
+ setLyrics,
+ description,
+ setDescription,
+ disabled,
+}: {
+ rule: MusicModeRule;
+ music: MusicGeneration;
+ lyrics: string;
+ setLyrics: (next: string) => void;
+ description: string;
+ setDescription: (next: string) => void;
+ disabled: boolean;
+}) {
+ const patch = useAudioMusicStore.getState().patchDraft;
+ const instrumental = instrumentalChoice(rule, music.song.instrumental);
+ const showLyrics = lyricsShown(rule, instrumental.value);
+ return (
+ <>
+ <div className="grid min-w-0 grid-cols-[minmax(0,1fr)] gap-1.5">
+ <Field
+ label={
+ rule.description === "required"
+ ? "Description"
+ : "Description (optional)"
+ }
+ htmlFor={MUSIC_DESCRIPTION_FIELD_ID}
+ >
+ <Textarea
+ id={MUSIC_DESCRIPTION_FIELD_ID}
+ value={description}
+ disabled={disabled}
+ onChange={(event) => setDescription(event.target.value)}
+ placeholder={
+ instrumental.value
+ ? "Genre, mood, instruments and tempo…"
+ : "Genre, mood, instruments, voice and tempo…"
+ }
+ className="min-h-16"
+ />
+ </Field>
+ <ExamplesOrHint
+ label="Example descriptions"
+ examples={
+ instrumental.value
+ ? MUSIC_EXAMPLES.instrumental
+ : MUSIC_EXAMPLES.description
+ }
+ empty={!description.trim()}
+ hint={
+ instrumental.value
+ ? "Genre, mood, instruments and tempo."
+ : "Genre, mood, instruments, voice and tempo."
+ }
+ onPick={setDescription}
+ disabled={disabled}
+ />
+ </div>
+ {instrumental.shown ? (
+ <div className="grid gap-1">
+ <label
+ htmlFor="music-instrumental"
+ className="flex items-center justify-between gap-3 text-ui-13 font-medium text-foreground"
+ >
+ Instrumental
+ <Switch
+ id="music-instrumental"
+ checked={instrumental.value}
+ disabled={disabled || !instrumental.enabled}
+ onCheckedChange={(checked) =>
+ patch("song", { instrumental: checked })
+ }
+ />
+ </label>
+ <p className="text-ui-11p5 leading-snug text-muted-foreground">
+ {instrumental.reason ?? "No vocals; the lyrics are kept for later."}
+ </p>
+ </div>
+ ) : null}
+ {showLyrics ? (
+ <div className="grid gap-1.5">
+ <LyricsEditor
+ id={MUSIC_LYRICS_FIELD_ID}
+ label={rule.lyrics === "required" ? "Lyrics" : "Lyrics (optional)"}
+ value={lyrics}
+ onChange={setLyrics}
+ sectionCase={rule.section_case}
+ disabled={disabled}
+ describedBy="music-lyrics-hint"
+ placeholder={exampleLyrics(
+ rule.section_case,
+ "Morning light through the pines…\n\n…",
+ )}
+ />
+ {lyrics.trim() ? (
+ <p
+ id="music-lyrics-hint"
+ className="text-ui-11p5 leading-snug text-muted-foreground"
+ >
+ Section tags shape the song.
+ </p>
+ ) : (
+ <p
+ id="music-lyrics-hint"
+ className="text-ui-11p5 leading-snug text-muted-foreground"
+ >
+ Section tags shape the song.{" "}
+ <Button
+ type="button"
+ variant="link"
+ disabled={disabled}
+ className="h-auto p-0 text-ui-11p5 font-medium text-foreground"
+ onClick={() =>
+ setLyrics(
+ exampleLyrics(
+ rule.section_case,
+ MUSIC_EXAMPLES.lyrics[0].text,
+ ),
+ )
+ }
+ >
+ Try example lyrics
+ </Button>
+ </p>
+ )}
+ </div>
+ ) : null}
+ <SecondsSlider
+ rule={rule}
+ value={music.song.durationS}
+ onChange={(durationS) => patch("song", { durationS })}
+ disabled={disabled}
+ />
+ <VariationsSlider
+ rule={rule}
+ value={music.song.variations}
+ onChange={(variations) => patch("song", { variations })}
+ disabled={disabled}
+ notice={music.reloadNotice}
+ />
+ </>
+ );
+}
+
+function SfxInputs({
+ rule,
+ music,
+ disabled,
+}: {
+ rule: MusicModeRule;
+ music: MusicGeneration;
+ disabled: boolean;
+}) {
+ const patch = useAudioMusicStore.getState().patchDraft;
+ return (
+ <>
+ <div className="grid min-w-0 grid-cols-[minmax(0,1fr)] gap-1.5">
+ <Field label="Sound" htmlFor={MUSIC_SFX_FIELD_ID}>
+ <Textarea
+ id={MUSIC_SFX_FIELD_ID}
+ value={music.sfx.prompt}
+ disabled={disabled}
+ onChange={(event) => patch("sfx", { prompt: event.target.value })}
+ placeholder="What you want to hear, and where…"
+ className="min-h-16"
+ />
+ </Field>
+ <ExamplesOrHint
+ label="Example sounds"
+ examples={MUSIC_EXAMPLES.sfx}
+ empty={!music.sfx.prompt.trim()}
+ hint="What you want to hear, and where."
+ onPick={(prompt) => patch("sfx", { prompt })}
+ disabled={disabled}
+ />
+ </div>
+ <SecondsSlider
+ rule={rule}
+ value={music.sfx.durationS}
+ onChange={(durationS) => patch("sfx", { durationS })}
+ disabled={disabled}
+ />
+ <VariationsSlider
+ rule={rule}
+ value={music.sfx.variations}
+ onChange={(variations) => patch("sfx", { variations })}
+ disabled={disabled}
+ notice={music.reloadNotice}
+ />
+ </>
+ );
+}
+
+export function MusicStudioInputs({
+ music,
+ lyrics,
+ setLyrics,
+ description,
+ setDescription,
+ historyClips,
+ disabled,
+}: {
+ music: MusicGeneration;
+ lyrics: string;
+ setLyrics: (next: string) => void;
+ description: string;
+ setDescription: (next: string) => void;
+ historyClips: readonly AudioGalleryClip[];
+ disabled: boolean;
+}) {
+ const { capabilities, rule } = music;
+ if (!capabilities || !rule) return null;
+ const modes = capabilities.modes.map((mode) => mode.id);
+ return (
+ <AudioHistoryProvider value={historyClips}>
+ {modes.length > 1 ? (
+ <div className="grid gap-1.5">
+ <PillTabs
+ ariaLabel="What to make"
+ value={rule.id}
+ onValueChange={(mode) => music.setMusicMode(mode as MusicMode)}
+ disabled={disabled}
+ fit={true}
+ compact={true}
+ className="self-start [&>button]:px-3"
+ tabs={capabilities.modes.map((mode) => ({
+ value: mode.id,
+ label: musicModeLabel(mode),
+ }))}
+ />
+ <p className="text-ui-11p5 leading-snug text-muted-foreground">
+ {musicModeHint(rule)}
+ </p>
+ </div>
+ ) : (
+ <div className="grid gap-0.5">
+ <span className="text-ui-13 font-medium text-foreground">
+ {musicModeLabel(rule)}
+ </span>
+ <p className="text-ui-11p5 leading-snug text-muted-foreground">
+ {musicModeHint(rule)}
+ </p>
+ </div>
+ )}
+ {rule.id === "song" ? (
+ <SongInputs
+ rule={rule}
+ music={music}
+ lyrics={lyrics}
+ setLyrics={setLyrics}
+ description={description}
+ setDescription={setDescription}
+ disabled={disabled}
+ />
+ ) : rule.id === "sfx" ? (
+ <SfxInputs rule={rule} music={music} disabled={disabled} />
+ ) : (
+ <MusicEditInputs
+ rule={rule}
+ draft={music.edit}
+ onChange={(patch) =>
+ useAudioMusicStore.getState().patchDraft("edit", patch)
+ }
+ disabled={disabled}
+ onSourceStatusChange={music.setSourceStatus}
+ sourceHandleRef={music.sourceHandle}
+ />
+ )}
+ </AudioHistoryProvider>
+ );
+}
+
+export function MusicRail({
+ music,
+ historyClips,
+ description,
+ setDescription,
+ ...props
+}: Omit<ComponentProps<typeof TtsRailFields>, "musicGeneration"> & {
+ music?: MusicGeneration;
+ historyClips?: readonly AudioGalleryClip[];
+ description?: string;
+ setDescription?: (next: string) => void;
+}) {
+ if (!music?.studio || !setDescription) {
+ return <TtsRailFields {...props} musicGeneration={true} />;
+ }
+ return (
+ <TtsRailFields
+ {...props}
+ // Length lives in the page's fields, so Advanced keeps only the model's options.
+ musicGeneration={false}
+ samplingControls={false}
+ inputs={
+ <MusicStudioInputs
+ music={music}
+ lyrics={props.prompt}
+ setLyrics={props.setPrompt}
+ description={description ?? ""}
+ setDescription={setDescription}
+ historyClips={historyClips ?? []}
+ disabled={props.busy === "generating"}
+ />
+ }
+ />
+ );
}
-export function MusicOutput(
- {
- modelReady,
- ...props
- }: Omit<ComponentProps<typeof TtsOutput>, "emptyText"> & {
- modelReady: boolean;
- },
-) {
+export function MusicOutput({
+ modelReady,
+ ...props
+}: Omit<ComponentProps<typeof TtsOutput>, "emptyText"> & {
+ modelReady: boolean;
+}) {
return (
<TtsOutput
{...props}
diff --git a/studio/frontend/src/features/audio/pages/tts-workspace.tsx b/studio/frontend/src/features/audio/pages/tts-workspace.tsx
index 7134ae4e10a..5b939992c5d 100644
--- a/studio/frontend/src/features/audio/pages/tts-workspace.tsx
+++ b/studio/frontend/src/features/audio/pages/tts-workspace.tsx
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-import type { ReactNode } from "react";
+import { type ReactNode, useState } from "react";
import { AdvancedDisclosure } from "@/components/advanced-disclosure";
import {
GalleryItemMenu,
@@ -43,10 +43,16 @@ import {
PendingClipCard,
} from "../components/clip-card";
import { Field } from "../components/field";
+import { MusicSendToMenuItems } from "../components/music-send-to";
+import {
+ VariationChips,
+ VariationGroupRow,
+} from "../components/variation-history";
import type { AudioHostState } from "../hooks/audio-host-state";
import type { AudioGallery } from "../hooks/use-audio-gallery";
import type { AudioModelSlot } from "../hooks/use-audio-model-slot";
import type { SpeechGeneration } from "../hooks/use-speech-generation";
+import { historyRows, variationSiblings } from "../music/variation-groups";
import type { AudioWorkflowId } from "../workflows";
export interface GenerateAction {
@@ -508,6 +514,16 @@ export function TtsOutput({
announcement: string;
clipBadge?: (clip: AudioGalleryClip) => string | null;
}) {
+ const [openGroups, setOpenGroups] = useState<ReadonlySet<string>>(
+ () => new Set(),
+ );
+ const toggleGroup = (groupId: string) =>
+ setOpenGroups((open) => {
+ const next = new Set(open);
+ if (!next.delete(groupId)) next.add(groupId);
+ return next;
+ });
+ const siblings = variationSiblings(clips, selectedClip?.id ?? null);
const clipMenu = (clip: AudioGalleryClip, variant: "row" | "toolbar") => (
<GalleryItemMenu
variant={variant}
@@ -539,6 +555,7 @@ export function TtsOutput({
/>
Copy text
</DropdownMenuItem>
+ <MusicSendToMenuItems clip={clip} />
</>
}
/>
@@ -552,25 +569,32 @@ export function TtsOutput({
{pending ? (
<PendingClipCard {...pending} />
) : selectedClip ? (
- <ClipCard
- // Keyed per clip: a reused player kept the old clip's position.
- key={selectedClip.id}
- title={selectedClip.prompt}
- model={selectedClip.model}
- createdAt={selectedClip.created_at}
- durationS={selectedClip.duration_s}
- src={selectedClipSrc ?? null}
- peaks={peaksById.get(selectedClip.id) ?? null}
- onDownload={
- srcById[selectedClip.id]
- ? () => handleDownloadClip(selectedClip)
- : null
- }
- menu={clipMenu(selectedClip, "row")}
- status={clipBadge?.(selectedClip) ?? undefined}
- focusOnMount={selectedClip.id === freshClipId}
- onFocused={onFreshClipFocused}
- />
+ <div className="flex w-full flex-col gap-2">
+ <VariationChips
+ siblings={siblings}
+ selectedId={selectedClip.id}
+ onSelect={selectClip}
+ />
+ <ClipCard
+ // Keyed per clip: a reused player kept the old clip's position.
+ key={selectedClip.id}
+ title={selectedClip.prompt}
+ model={selectedClip.model}
+ createdAt={selectedClip.created_at}
+ durationS={selectedClip.duration_s}
+ src={selectedClipSrc ?? null}
+ peaks={peaksById.get(selectedClip.id) ?? null}
+ onDownload={
+ srcById[selectedClip.id]
+ ? () => handleDownloadClip(selectedClip)
+ : null
+ }
+ menu={clipMenu(selectedClip, "row")}
+ status={clipBadge?.(selectedClip) ?? undefined}
+ focusOnMount={selectedClip.id === freshClipId}
+ onFocused={onFreshClipFocused}
+ />
+ </div>
) : fallbackClip ? (
<ClipCard
title={fallbackClip.prompt}
@@ -619,50 +643,63 @@ export function TtsOutput({
}
}}
>
- {clips.map((clip) => (
- // Shell, not a button: the pin badge and dots menu are buttons and cannot nest.
- <div
- key={clip.id}
- {...historyReorder.tileProps(clip.id)}
- className={cn(
- "group relative flex items-center gap-1 rounded-md pr-1 transition-colors hover:bg-muted",
- clip.id === selectedId && "bg-muted",
- historyReorder.draggingId === clip.id && "opacity-40",
- )}
- >
- {historyReorder.cue?.id === clip.id && (
- <StripDropLine axis="y" edge={historyReorder.cue.edge} />
- )}
- <button
- type="button"
- onClick={() => selectClip(clip.id)}
- aria-current={clip.id === selectedId ? "true" : undefined}
- className="flex min-w-0 flex-1 items-center gap-2 px-2 py-1.5 text-left text-ui-13"
+ {historyRows(clips, openGroups).map(({ clip, header, nested }) =>
+ header ? (
+ <VariationGroupRow
+ key={`group:${header.groupId}`}
+ clips={header.clips}
+ open={header.open}
+ selected={header.clips.some((item) => item.id === selectedId)}
+ onToggle={() => toggleGroup(header.groupId)}
+ />
+ ) : (
+ // Shell, not a button: the pin badge and dots menu are buttons and cannot nest.
+ <div
+ key={clip.id}
+ {...historyReorder.tileProps(clip.id)}
+ className={cn(
+ "group relative flex items-center gap-1 rounded-md pr-1 transition-colors hover:bg-muted",
+ clip.id === selectedId && "bg-muted",
+ historyReorder.draggingId === clip.id && "opacity-40",
+ nested && "ml-4",
+ )}
>
- <HugeiconsIcon
- icon={AudioWave01Icon}
- className="size-3.5 shrink-0 text-muted-foreground"
- />
- <span className="min-w-0 flex-1 truncate">{clip.prompt}</span>
- <ClipBadge text={clipBadge?.(clip)} />
- <span className="hidden min-w-0 max-w-[45%] shrink truncate text-ui-11p5 text-muted-foreground @[30rem]:block">
- {audioModelLabel(clip.model)} ·{" "}
- {formatRelativeShort(clip.created_at)}
- </span>
- <span className="shrink-0 font-mono text-ui-11p5 tabular-nums text-muted-foreground">
- {formatClipDuration(clip.duration_s)}
- </span>
- </button>
- {clip.pinned && (
- <GalleryPinBadge
- noun="clip"
- className="static shrink-0"
- onUnpin={() => void handleTogglePin(clip.id, false)}
- />
- )}
- {clipMenu(clip, "row")}
- </div>
- ))}
+ {historyReorder.cue?.id === clip.id && (
+ <StripDropLine axis="y" edge={historyReorder.cue.edge} />
+ )}
+ <button
+ type="button"
+ onClick={() => selectClip(clip.id)}
+ aria-current={clip.id === selectedId ? "true" : undefined}
+ className="flex min-w-0 flex-1 items-center gap-2 px-2 py-1.5 text-left text-ui-13"
+ >
+ <HugeiconsIcon
+ icon={AudioWave01Icon}
+ className="size-3.5 shrink-0 text-muted-foreground"
+ />
+ <span className="min-w-0 flex-1 truncate">
+ {clip.prompt}
+ </span>
+ <ClipBadge text={clipBadge?.(clip)} />
+ <span className="hidden min-w-0 max-w-[45%] shrink truncate text-ui-11p5 text-muted-foreground @[30rem]:block">
+ {audioModelLabel(clip.model)} ·{" "}
+ {formatRelativeShort(clip.created_at)}
+ </span>
+ <span className="shrink-0 font-mono text-ui-11p5 tabular-nums text-muted-foreground">
+ {formatClipDuration(clip.duration_s)}
+ </span>
+ </button>
+ {clip.pinned && (
+ <GalleryPinBadge
+ noun="clip"
+ className="static shrink-0"
+ onUnpin={() => void handleTogglePin(clip.id, false)}
+ />
+ )}
+ {clipMenu(clip, "row")}
+ </div>
+ ),
+ )}
</div>
</div>
) : null}
diff --git a/studio/frontend/src/features/audio/stores/audio-music-store.ts b/studio/frontend/src/features/audio/stores/audio-music-store.ts
new file mode 100644
index 00000000000..0a8c37d1725
--- /dev/null
+++ b/studio/frontend/src/features/audio/stores/audio-music-store.ts
@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import type { AudioSourceSelection } from "../audio-run-request";
+import type {
+ MusicDrafts,
+ MusicEditAction,
+ MusicEditDraft,
+ MusicMode,
+ MusicSfxDraft,
+ MusicSongDraft,
+} from "../music/music-types";
+
+export const AUDIO_MUSIC_STORAGE_KEY = "unsloth_audio_music_v1";
+
+export const DEFAULT_MUSIC_DRAFTS: MusicDrafts = {
+ song: { instrumental: false, durationS: null, variations: 1 },
+ sfx: { prompt: "", durationS: null, variations: 1 },
+ edit: {
+ source: null,
+ action: null,
+ ranges: [],
+ strength: null,
+ extendS: 15,
+ prompt: "",
+ },
+};
+
+type DraftPatch<M extends MusicMode> = M extends "song"
+ ? Partial<MusicSongDraft>
+ : M extends "sfx"
+ ? Partial<MusicSfxDraft>
+ : Partial<MusicEditDraft>;
+
+interface AudioMusicState extends MusicDrafts {
+ mode: MusicMode;
+ setMode: (mode: MusicMode) => void;
+ patchDraft: <M extends MusicMode>(mode: M, patch: DraftPatch<M>) => void;
+ pushClipToEdit: (
+ clip: AudioSourceSelection,
+ action?: MusicEditAction | null,
+ ) => void;
+ loadedEditActions: readonly MusicEditAction[];
+ setLoadedEditActions: (actions: readonly MusicEditAction[]) => void;
+}
+
+export const useAudioMusicStore = create<AudioMusicState>()(
+ persist(
+ (set) => ({
+ mode: "song",
+ ...DEFAULT_MUSIC_DRAFTS,
+ loadedEditActions: [],
+ setLoadedEditActions: (loadedEditActions) => set({ loadedEditActions }),
+ setMode: (mode) => set({ mode }),
+ patchDraft: (mode, patch) =>
+ set(
+ (state) =>
+ ({
+ [mode]: { ...state[mode], ...patch },
+ }) as Partial<AudioMusicState>,
+ ),
+ pushClipToEdit: (clip, action = null) =>
+ set((state) => ({
+ mode: "edit",
+ edit: {
+ ...state.edit,
+ source: clip,
+ // A new clip's old ranges point at the wrong audio.
+ ranges: state.edit.source?.id === clip.id ? state.edit.ranges : [],
+ action: action ?? state.edit.action,
+ prompt: state.edit.prompt.trim() ? state.edit.prompt : clip.name,
+ },
+ })),
+ }),
+ {
+ name: AUDIO_MUSIC_STORAGE_KEY,
+ version: 1,
+ partialize: (state) => ({
+ mode: state.mode,
+ song: state.song,
+ sfx: state.sfx,
+ edit: state.edit,
+ }),
+ // Drafts saved by an older build may miss fields added since.
+ merge: (persisted, current) => {
+ const saved = (persisted ?? {}) as Partial<
+ MusicDrafts & { mode: MusicMode }
+ >;
+ return {
+ ...current,
+ mode: saved.mode ?? current.mode,
+ song: { ...current.song, ...saved.song },
+ sfx: { ...current.sfx, ...saved.sfx },
+ edit: { ...current.edit, ...saved.edit },
+ };
+ },
+ },
+ ),
+);
diff --git a/studio/frontend/src/features/audio/tools/clone-panels.tsx b/studio/frontend/src/features/audio/tools/clone-panels.tsx
index 1d64d614b55..2e205ecbb74 100644
--- a/studio/frontend/src/features/audio/tools/clone-panels.tsx
+++ b/studio/frontend/src/features/audio/tools/clone-panels.tsx
@@ -34,7 +34,7 @@ import {
} from "./panel-logic";
import type { AudioToolPanel } from "./types";
-function PanelSection({
+export function PanelSection({
title,
hint,
children,
diff --git a/studio/frontend/src/features/audio/tools/music-panel-logic.ts b/studio/frontend/src/features/audio/tools/music-panel-logic.ts
new file mode 100644
index 00000000000..c870472299d
--- /dev/null
+++ b/studio/frontend/src/features/audio/tools/music-panel-logic.ts
@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// No app imports: the node test runner loads this directly.
+
+import type { AudioOptionSpec } from "../audio-options";
+import type { AudioToolPanel } from "./types";
+
+type MusicPanelLogic<V> = Omit<AudioToolPanel<V>, "Component">;
+
+function specDefault(
+ specs: AudioOptionSpec[],
+ name: string,
+): string | number | boolean | null {
+ const value = specs.find((spec) => spec.name === name)?.default;
+ return value === undefined ? null : value;
+}
+
+export const ACE_STEP_NOTES = [
+ "C",
+ "C#",
+ "D",
+ "Eb",
+ "E",
+ "F",
+ "F#",
+ "G",
+ "Ab",
+ "A",
+ "Bb",
+ "B",
+] as const;
+
+export const ACE_STEP_KEYS: readonly string[] = ACE_STEP_NOTES.flatMap(
+ (note) => [`${note} major`, `${note} minor`],
+);
+
+export const ACE_STEP_TIME_SIGNATURES = [
+ { value: "2", label: "2/4" },
+ { value: "3", label: "3/4" },
+ { value: "4", label: "4/4" },
+ { value: "6", label: "6/8" },
+] as const;
+
+export const ACE_STEP_BPM = { min: 30, max: 300, default: 100 } as const;
+
+export interface AceStepMusicalValue {
+ bpm: number | null;
+ keyscale: string;
+ timesignature: string;
+ avoid: string;
+ sampler: string;
+}
+
+export const aceStepMusicalLogic: MusicPanelLogic<AceStepMusicalValue> = {
+ id: "ace-step-musical",
+ families: ["ace_step"],
+ workflows: ["music"],
+ title: "Musical controls",
+ claims: [
+ "bpm",
+ "keyscale",
+ "timesignature",
+ "negative_prompt",
+ "sampler_mode",
+ ],
+ initial: () => ({
+ bpm: null,
+ keyscale: "",
+ timesignature: "",
+ avoid: "",
+ sampler: "",
+ }),
+ toRequest: (value) => {
+ const options: Record<string, string | number> = {};
+ if (value.bpm !== null && Number.isFinite(value.bpm)) {
+ options.bpm = Math.round(
+ Math.min(ACE_STEP_BPM.max, Math.max(ACE_STEP_BPM.min, value.bpm)),
+ );
+ }
+ if (ACE_STEP_KEYS.includes(value.keyscale))
+ options.keyscale = value.keyscale;
+ if (
+ ACE_STEP_TIME_SIGNATURES.some(
+ (item) => item.value === value.timesignature,
+ )
+ )
+ options.timesignature = value.timesignature;
+ const avoid = value.avoid.trim();
+ if (avoid) options.negative_prompt = avoid;
+ if (value.sampler === "euler" || value.sampler === "heun")
+ options.sampler_mode = value.sampler;
+ return Object.keys(options).length > 0 ? { options } : {};
+ },
+};
+
+export type YueCot = "off" | "melody" | "full";
+
+export const YUE_COT_LABELS: Record<YueCot, { label: string; hint: string }> = {
+ off: { label: "Off", hint: "Fastest. Writes the audio directly." },
+ melody: { label: "Melody", hint: "Plans the melody first." },
+ full: {
+ label: "Full",
+ hint: "Plans melody and arrangement first. Slowest, most structured.",
+ },
+};
+
+export interface YueCompositionValue {
+ cot: YueCot;
+}
+
+export const yueCompositionLogic: MusicPanelLogic<YueCompositionValue> = {
+ id: "yue2-composition",
+ families: ["yue2"],
+ workflows: ["music"],
+ title: "Composition",
+ claims: ["cot"],
+ initial: (specs) => {
+ const fallback = specDefault(specs, "cot");
+ return {
+ cot:
+ fallback === "off" || fallback === "melody" || fallback === "full"
+ ? fallback
+ : "full",
+ };
+ },
+ toRequest: (value) => ({ options: { cot: value.cot } }),
+};
+
+export const STABLE_AUDIO_SAMPLERS = [
+ { value: "pingpong", label: "Ping-pong" },
+ { value: "euler", label: "Euler" },
+] as const;
+
+export interface StableAudioSamplerValue {
+ sampler: string;
+ steps: number | null;
+}
+
+export const stableAudioSamplerLogic: MusicPanelLogic<StableAudioSamplerValue> =
+ {
+ id: "stable-audio-sampler",
+ families: ["stable_audio"],
+ workflows: ["music"],
+ title: "Sampler",
+ claims: ["sampler", "num_inference_steps"],
+ initial: () => ({ sampler: "", steps: null }),
+ toRequest: (value) => {
+ const options: Record<string, string | number> = {};
+ if (STABLE_AUDIO_SAMPLERS.some((item) => item.value === value.sampler))
+ options.sampler = value.sampler;
+ if (
+ value.steps !== null &&
+ Number.isFinite(value.steps) &&
+ value.steps >= 1
+ )
+ options.num_inference_steps = Math.round(value.steps);
+ return Object.keys(options).length > 0 ? { options } : {};
+ },
+ };
+
+export function stepsRange(specs: AudioOptionSpec[]): {
+ min: number;
+ max: number;
+ default: number;
+} {
+ const spec = specs.find((item) => item.name === "num_inference_steps");
+ const min = typeof spec?.min === "number" ? Math.max(1, spec.min) : 1;
+ const max = typeof spec?.max === "number" ? Math.max(min, spec.max) : 100;
+ const fallback = typeof spec?.default === "number" ? spec.default : 8;
+ return { min, max, default: Math.min(max, Math.max(min, fallback)) };
+}
diff --git a/studio/frontend/src/features/audio/tools/music-panels.tsx b/studio/frontend/src/features/audio/tools/music-panels.tsx
new file mode 100644
index 00000000000..3a3b03c350d
--- /dev/null
+++ b/studio/frontend/src/features/audio/tools/music-panels.tsx
@@ -0,0 +1,216 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
+import { Textarea } from "@/components/ui/textarea";
+import { ParamSlider } from "@/features/chat";
+import { PillTabs } from "@/features/model-picker/components/model-selector/pill-tabs";
+import { Field } from "../components/field";
+import { PanelSection } from "./clone-panels";
+import {
+ ACE_STEP_BPM,
+ ACE_STEP_KEYS,
+ ACE_STEP_TIME_SIGNATURES,
+ type AceStepMusicalValue,
+ STABLE_AUDIO_SAMPLERS,
+ type StableAudioSamplerValue,
+ YUE_COT_LABELS,
+ type YueCompositionValue,
+ type YueCot,
+ aceStepMusicalLogic,
+ stableAudioSamplerLogic,
+ stepsRange,
+ yueCompositionLogic,
+} from "./music-panel-logic";
+import type { AudioToolPanel } from "./types";
+
+/** Radix forbids an empty item value. */
+const AUTO = "auto";
+
+function AutoSelect({
+ id,
+ value,
+ onChange,
+ options,
+ disabled,
+}: {
+ id: string;
+ value: string;
+ onChange: (next: string) => void;
+ options: readonly { value: string; label: string }[];
+ disabled: boolean;
+}) {
+ return (
+ <Select
+ value={value || AUTO}
+ onValueChange={(next) => onChange(next === AUTO ? "" : next)}
+ disabled={disabled}
+ >
+ <SelectTrigger id={id} size="sm" className="w-full">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ <SelectItem value={AUTO}>Auto</SelectItem>
+ {options.map((option) => (
+ <SelectItem key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ );
+}
+
+export const aceStepMusicalPanel: AudioToolPanel<AceStepMusicalValue> = {
+ ...aceStepMusicalLogic,
+ Component: ({ value, onChange, disabled }) => (
+ <PanelSection
+ title="Musical controls"
+ hint="Optional. Anything left on Auto is chosen by the model."
+ >
+ <div className="grid gap-1.5">
+ <label
+ htmlFor="music-bpm-auto"
+ className="flex items-center justify-between gap-3 text-ui-13 font-medium text-foreground"
+ >
+ Set the tempo
+ <Switch
+ id="music-bpm-auto"
+ checked={value.bpm !== null}
+ disabled={disabled}
+ onCheckedChange={(on) =>
+ onChange({ ...value, bpm: on ? ACE_STEP_BPM.default : null })
+ }
+ />
+ </label>
+ {value.bpm !== null ? (
+ <ParamSlider
+ label="BPM"
+ value={value.bpm}
+ min={ACE_STEP_BPM.min}
+ max={ACE_STEP_BPM.max}
+ step={1}
+ valueSize={4}
+ disabled={disabled}
+ onChange={(bpm) => onChange({ ...value, bpm })}
+ />
+ ) : null}
+ </div>
+ <div className="grid grid-cols-2 gap-3">
+ <Field label="Key" htmlFor="music-key">
+ <AutoSelect
+ id="music-key"
+ value={value.keyscale}
+ onChange={(keyscale) => onChange({ ...value, keyscale })}
+ options={ACE_STEP_KEYS.map((key) => ({ value: key, label: key }))}
+ disabled={disabled}
+ />
+ </Field>
+ <Field label="Time signature" htmlFor="music-time-signature">
+ <AutoSelect
+ id="music-time-signature"
+ value={value.timesignature}
+ onChange={(timesignature) => onChange({ ...value, timesignature })}
+ options={ACE_STEP_TIME_SIGNATURES}
+ disabled={disabled}
+ />
+ </Field>
+ </div>
+ <Field
+ label="Keep out"
+ htmlFor="music-avoid"
+ hint="Sounds or styles to avoid, such as “distorted guitar, shouting”."
+ >
+ <Textarea
+ id="music-avoid"
+ value={value.avoid}
+ disabled={disabled}
+ onChange={(event) =>
+ onChange({ ...value, avoid: event.target.value })
+ }
+ className="min-h-12"
+ />
+ </Field>
+ <Field label="Sampler" htmlFor="music-ace-sampler">
+ <AutoSelect
+ id="music-ace-sampler"
+ value={value.sampler}
+ onChange={(sampler) => onChange({ ...value, sampler })}
+ options={[
+ { value: "euler", label: "Euler (faster)" },
+ { value: "heun", label: "Heun (smoother, slower)" },
+ ]}
+ disabled={disabled}
+ />
+ </Field>
+ </PanelSection>
+ ),
+};
+
+export const yueCompositionPanel: AudioToolPanel<YueCompositionValue> = {
+ ...yueCompositionLogic,
+ Component: ({ value, onChange, disabled }) => (
+ <PanelSection title="Planning" hint={YUE_COT_LABELS[value.cot].hint}>
+ <PillTabs
+ ariaLabel="Planning"
+ value={value.cot}
+ onValueChange={(cot) => onChange({ cot: cot as YueCot })}
+ disabled={disabled}
+ fit={true}
+ compact={true}
+ className="[&>button]:px-3"
+ tabs={(Object.keys(YUE_COT_LABELS) as YueCot[]).map((cot) => ({
+ value: cot,
+ label: YUE_COT_LABELS[cot].label,
+ }))}
+ />
+ </PanelSection>
+ ),
+};
+
+export const stableAudioSamplerPanel: AudioToolPanel<StableAudioSamplerValue> =
+ {
+ ...stableAudioSamplerLogic,
+ Component: ({ value, onChange, disabled, specs }) => {
+ const steps = stepsRange(specs);
+ return (
+ <PanelSection
+ title="Sampler"
+ hint="Optional. More steps can sound cleaner and take longer."
+ >
+ <Field label="Method" htmlFor="music-sa-sampler">
+ <AutoSelect
+ id="music-sa-sampler"
+ value={value.sampler}
+ onChange={(sampler) => onChange({ ...value, sampler })}
+ options={STABLE_AUDIO_SAMPLERS}
+ disabled={disabled}
+ />
+ </Field>
+ <ParamSlider
+ label="Steps"
+ value={value.steps ?? steps.default}
+ min={steps.min}
+ max={steps.max}
+ step={1}
+ valueSize={4}
+ disabled={disabled}
+ onChange={(next) => onChange({ ...value, steps: next })}
+ />
+ </PanelSection>
+ );
+ },
+ };
+
+export const MUSIC_TOOL_PANELS = [
+ aceStepMusicalPanel,
+ yueCompositionPanel,
+ stableAudioSamplerPanel,
+] as const;
diff --git a/studio/frontend/src/features/audio/tools/registry.tsx b/studio/frontend/src/features/audio/tools/registry.tsx
index 1f59e8665ae..7f54f011e2d 100644
--- a/studio/frontend/src/features/audio/tools/registry.tsx
+++ b/studio/frontend/src/features/audio/tools/registry.tsx
@@ -8,7 +8,12 @@ import {
} from "../components/instructions-fields";
import type { AudioWorkflowId } from "../workflows";
import { CLONE_TOOL_PANELS } from "./clone-panels";
-import { instructionsKindFor, panelApplies } from "./select";
+import { MUSIC_TOOL_PANELS } from "./music-panels";
+import {
+ instructionsKindFor,
+ legacyMusicDescription,
+ panelApplies,
+} from "./select";
import { SPEAK_TOOL_PANELS } from "./speak-panels";
import type {
AnyAudioToolPanel,
@@ -44,7 +49,9 @@ function instructionsPanel(
title,
// Request fields, not spec options, so Advanced keeps every option.
claims: [],
- appliesTo: (ctx) => instructionsKindFor(ctx) === kind,
+ appliesTo: (ctx) =>
+ instructionsKindFor(ctx) === kind &&
+ (kind !== "music" || legacyMusicDescription(ctx)),
initial: () => ({ instructions: "", language: "" }),
Component: ({ value, onChange, ctx }) => (
<>
@@ -107,6 +114,7 @@ export const AUDIO_TOOL_PANELS: readonly AnyAudioToolPanel[] = [
...INSTRUCTION_PANELS,
...SPEAK_TOOL_PANELS.slice(1),
...CLONE_TOOL_PANELS,
+ ...MUSIC_TOOL_PANELS,
];
export function audioToolPanelsFor(
diff --git a/studio/frontend/src/features/audio/tools/select.ts b/studio/frontend/src/features/audio/tools/select.ts
index b1be0df12a5..6eb59860c41 100644
--- a/studio/frontend/src/features/audio/tools/select.ts
+++ b/studio/frontend/src/features/audio/tools/select.ts
@@ -8,6 +8,8 @@ import {
type NativeAudioInstructionsKind,
nativeAudioInstructionsKind,
} from "../audio-page-policy";
+import { isMusicGenerationModel } from "../catalog";
+import { parseMusicCapabilities } from "../music/music-types";
import type { AudioWorkflowId } from "../workflows";
import type {
AnyAudioToolPanel,
@@ -26,6 +28,12 @@ export function instructionsKindFor(
: nativeAudioInstructionsKind(ctx.audioType);
}
+/** The Music studio has its own description field, preview included; only a loaded music model
+ * without studio modes (native MiniMax) keeps the old one. */
+export function legacyMusicDescription(ctx: AudioModelContext): boolean {
+ return ctx.audioMusic !== true && isMusicGenerationModel(null, ctx.audioType);
+}
+
export function panelApplies(
panel: Pick<AudioToolPanel<unknown>, "workflows" | "families" | "appliesTo">,
workflow: AudioWorkflowId,
@@ -56,6 +64,7 @@ export function audioModelContextFor(
audio_workflows?: readonly string[] | null;
audio_required_inputs?: readonly string[] | null;
audio_reference_text?: string | null;
+ audio_music?: unknown;
} | null,
page: {
musicGeneration: boolean;
@@ -81,6 +90,7 @@ export function audioModelContextFor(
REFERENCE_TEXT_MODES.has(referenceText)
? (referenceText as AudioReferenceTextMode)
: null,
+ audioMusic: parseMusicCapabilities(status?.audio_music) !== null,
};
}
diff --git a/studio/frontend/src/features/audio/tools/types.ts b/studio/frontend/src/features/audio/tools/types.ts
index e1c8167edd0..4cd43ab9ed7 100644
--- a/studio/frontend/src/features/audio/tools/types.ts
+++ b/studio/frontend/src/features/audio/tools/types.ts
@@ -18,6 +18,7 @@ export interface AudioModelContext {
audioWorkflows?: readonly string[];
requiredInputs?: readonly string[];
referenceTextMode?: AudioReferenceTextMode | null;
+ audioMusic?: boolean;
/** Ids of the saved voices, once the list has loaded. */
savedVoiceIds?: readonly string[] | null;
}
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index 1833086d2d4..7ac978c7df5 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -384,6 +384,8 @@ export interface InferenceStatusResponse {
audio_reference_text?: "required" | "optional" | "unused" | null;
/** e.g. Maya1: "instruct" (its voice description). */
audio_required_inputs?: string[] | null;
+ /** Unknown-shaped on purpose: validated by parseMusicCapabilities. */
+ audio_music?: unknown;
has_audio_input?: boolean;
has_video_input?: boolean;
loading: string[];
diff --git a/studio/frontend/tests/audio-music-edit-inputs.test.ts b/studio/frontend/tests/audio-music-edit-inputs.test.ts
new file mode 100644
index 00000000000..d104ece2cb5
--- /dev/null
+++ b/studio/frontend/tests/audio-music-edit-inputs.test.ts
@@ -0,0 +1,232 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readSrc, registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+
+const {
+ editBeyondEndS,
+ editMaxRanges,
+ editUsesRanges,
+ editUsesStrength,
+ formatEditLimit,
+ musicEditProblem,
+ MUSIC_EDIT_ACTION_LABEL,
+} = await import("../src/features/audio/music/music-edit-rules.ts");
+
+type Rule = Parameters<typeof musicEditProblem>[0];
+type Draft = Parameters<typeof musicEditProblem>[1];
+
+const aceRule: Rule = {
+ id: "edit",
+ actions: ["repaint", "extend", "cover", "continue"],
+ max_source_s: 240,
+};
+const stableRule: Rule = {
+ id: "edit",
+ actions: ["inpaint", "restyle"],
+ max_ranges: 3,
+};
+
+const source = { kind: "clip" as const, id: "c1", name: "Clip", durationS: 20 };
+
+function draft(patch: Partial<Draft> = {}): Draft {
+ return {
+ source,
+ action: "repaint",
+ ranges: [{ start_s: 2, end_s: 4 }],
+ strength: null,
+ extendS: 15,
+ prompt: "brighter chorus",
+ ...patch,
+ };
+}
+
+test("a complete edit has no problem", () => {
+ assert.equal(musicEditProblem(aceRule, draft(), 20), null);
+ assert.equal(
+ musicEditProblem(stableRule, draft({ action: "restyle", ranges: [] }), 20),
+ null,
+ );
+});
+
+test("each missing piece is named, in the order it is fixed", () => {
+ assert.equal(
+ musicEditProblem(aceRule, draft({ source: null }), null),
+ "Pick a clip to edit.",
+ );
+ assert.equal(
+ musicEditProblem(aceRule, draft({ action: null }), 20),
+ "Pick what to do with the clip.",
+ );
+ assert.equal(
+ musicEditProblem(aceRule, draft({ action: "inpaint" }), 20),
+ "Pick what to do with the clip.",
+ );
+ assert.equal(
+ musicEditProblem({ id: "edit", actions: [] }, draft(), 20),
+ "This model cannot edit clips.",
+ );
+ assert.equal(
+ musicEditProblem(aceRule, draft({ ranges: [] }), 20),
+ "Select the part to change on the waveform.",
+ );
+ assert.equal(
+ musicEditProblem(stableRule, draft({ action: "inpaint", ranges: [] }), 20),
+ "Select the parts to change on the waveform.",
+ );
+ assert.equal(
+ musicEditProblem(aceRule, draft({ prompt: " " }), 20),
+ "Describe what the new part should sound like.",
+ );
+ assert.equal(
+ musicEditProblem(
+ aceRule,
+ draft({ action: "cover", ranges: [], prompt: "" }),
+ 20,
+ ),
+ "Describe the new style.",
+ );
+});
+
+test("a clip past the model's limit asks for a trim", () => {
+ assert.equal(
+ musicEditProblem(aceRule, draft(), 300),
+ "Edit clips up to 4 minutes. Trim it first.",
+ );
+ assert.equal(musicEditProblem(aceRule, draft(), 240), null);
+ assert.equal(formatEditLimit(60), "1 minute");
+ assert.equal(formatEditLimit(90), "90 s");
+});
+
+test("invalid ranges are refused", () => {
+ assert.equal(
+ musicEditProblem(
+ aceRule,
+ draft({ ranges: [{ start_s: 2, end_s: 2.1 }] }),
+ 20,
+ ),
+ "Make each selected part at least 0.25 s long.",
+ );
+ assert.equal(
+ musicEditProblem(
+ aceRule,
+ draft({ ranges: [{ start_s: 21, end_s: 22 }] }),
+ 20,
+ ),
+ "A selected part starts after the clip ends. Move it inside the clip.",
+ );
+ assert.equal(
+ musicEditProblem(
+ aceRule,
+ draft({
+ ranges: [
+ { start_s: 1, end_s: 2 },
+ { start_s: 3, end_s: 4 },
+ ],
+ }),
+ 20,
+ ),
+ "Select one part to change.",
+ );
+ assert.equal(
+ musicEditProblem(
+ { ...stableRule, max_ranges: 1 },
+ draft({
+ action: "inpaint",
+ ranges: [
+ { start_s: 1, end_s: 2 },
+ { start_s: 3, end_s: 4 },
+ ],
+ }),
+ 20,
+ ),
+ "Select one part to change.",
+ );
+});
+
+test("only a repaint may run past the end, and only so far", () => {
+ assert.equal(
+ musicEditProblem(
+ aceRule,
+ draft({ ranges: [{ start_s: 18, end_s: 30 }] }),
+ 20,
+ ),
+ null,
+ );
+ assert.equal(
+ musicEditProblem(
+ aceRule,
+ draft({ ranges: [{ start_s: 18, end_s: 60 }] }),
+ 20,
+ ),
+ "A repaint can reach at most 30 s past the end.",
+ );
+ assert.equal(
+ musicEditProblem(
+ stableRule,
+ draft({ action: "inpaint", ranges: [{ start_s: 18, end_s: 22 }] }),
+ 20,
+ ),
+ "A selected part runs past the end of the clip.",
+ );
+ assert.ok(editBeyondEndS("repaint") > 0);
+ assert.equal(editBeyondEndS("inpaint"), 0);
+ assert.equal(editBeyondEndS("extend"), 0);
+});
+
+test("extend asks for 5 to 120 seconds", () => {
+ assert.equal(
+ musicEditProblem(
+ aceRule,
+ draft({ action: "extend", ranges: [], extendS: 2 }),
+ 20,
+ ),
+ "Add between 5 and 120 seconds.",
+ );
+ assert.equal(
+ musicEditProblem(aceRule, draft({ action: "extend", ranges: [] }), 20),
+ null,
+ );
+});
+
+test("which controls each action shows", () => {
+ assert.equal(editUsesRanges("repaint"), true);
+ assert.equal(editUsesRanges("inpaint"), true);
+ assert.equal(editUsesRanges("cover"), false);
+ assert.equal(editUsesStrength("cover"), true);
+ assert.equal(editUsesStrength("restyle"), true);
+ assert.equal(editUsesStrength("repaint"), false);
+ assert.equal(editMaxRanges(stableRule, "inpaint"), 3);
+ assert.equal(editMaxRanges(stableRule, "repaint"), 1);
+ assert.equal(editMaxRanges(stableRule, "restyle"), 0);
+ assert.equal(MUSIC_EDIT_ACTION_LABEL.continue, "Add parts");
+});
+
+test("the inputs reuse the source card and keep lyrics out of edit", () => {
+ const ui = readSrc("features/audio/components/music-edit-inputs.tsx");
+ assert.match(ui, /allowSavedVoice=\{false\}/);
+ assert.match(ui, /label="Clip to edit"/);
+ assert.match(ui, /renderWaveform=/);
+ assert.match(ui, /"How much to change"/);
+ assert.match(ui, /"Add seconds"/);
+ assert.match(ui, /Extends the clip by/);
+ assert.match(ui, /export \{ musicEditProblem \}/);
+ assert.doesNotMatch(ui, /draft\.lyrics/);
+});
+
+test("clip actions follow what the loaded model's Edit mode can do", async () => {
+ const { sendActionsFor } = await import(
+ "../src/features/audio/music/music-edit-rules.ts"
+ );
+ assert.deepEqual(sendActionsFor([]), []);
+ assert.deepEqual(sendActionsFor(["inpaint", "restyle"]), ["edit"]);
+ assert.deepEqual(sendActionsFor(["repaint", "extend", "cover", "continue"]), [
+ "edit",
+ "extend",
+ ]);
+});
diff --git a/studio/frontend/tests/audio-music-panels.test.ts b/studio/frontend/tests/audio-music-panels.test.ts
new file mode 100644
index 00000000000..47b383c9252
--- /dev/null
+++ b/studio/frontend/tests/audio-music-panels.test.ts
@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readSrc, registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+const {
+ aceStepMusicalLogic,
+ stableAudioSamplerLogic,
+ yueCompositionLogic,
+ stepsRange,
+} = await import("../src/features/audio/tools/music-panel-logic.ts");
+const { audioModelContextFor, legacyMusicDescription, panelApplies } =
+ await import("../src/features/audio/tools/select.ts");
+
+const registry = readSrc("features/audio/tools/registry.tsx");
+const panels = readSrc("features/audio/tools/music-panels.tsx");
+
+const MUSIC_STATUS = { modes: [{ id: "song" }] };
+
+function ctx(family: string, audioMusic: unknown = MUSIC_STATUS) {
+ return audioModelContextFor(
+ {
+ audio_type: "audiocpp_music",
+ audio_family: family,
+ audio_music: audioMusic,
+ },
+ {
+ musicGeneration: true,
+ cudaMusicGeneration: false,
+ musicNeedsDescription: false,
+ },
+ );
+}
+
+test("each music panel shows on Music for its own family only", () => {
+ for (const [panel, family] of [
+ [aceStepMusicalLogic, "ace_step"],
+ [yueCompositionLogic, "yue2"],
+ [stableAudioSamplerLogic, "stable_audio"],
+ ] as const) {
+ assert.equal(panelApplies(panel, "music", ctx(family)), true, panel.id);
+ assert.equal(panelApplies(panel, "speak", ctx(family)), false, panel.id);
+ assert.equal(
+ panelApplies(panel, "music", ctx("heartmula")),
+ false,
+ panel.id,
+ );
+ }
+ assert.match(registry, /\.\.\.MUSIC_TOOL_PANELS/);
+ assert.match(
+ panels,
+ /aceStepMusicalPanel,\s*yueCompositionPanel,\s*stableAudioSamplerPanel/,
+ );
+});
+
+test("the status's music block reaches the tool context", () => {
+ assert.equal(ctx("ace_step").audioMusic, true);
+ assert.equal(ctx("ace_step", null).audioMusic, false);
+ assert.equal(ctx("ace_step", { modes: [] }).audioMusic, false);
+});
+
+test("the old Music description shows only for a loaded music model without studio modes", () => {
+ const described = (status: Record<string, unknown> | null) =>
+ legacyMusicDescription(
+ audioModelContextFor(status, {
+ musicGeneration: true,
+ cudaMusicGeneration: false,
+ musicNeedsDescription: false,
+ }),
+ );
+ // Nothing loaded: the studio preview has its own description field.
+ assert.equal(described(null), false);
+ assert.equal(described({ audio_type: "audiocpp_tts" }), false);
+ assert.equal(described({ audio_type: "minimax_music3" }), true);
+ assert.equal(
+ described({ audio_type: "audiocpp_music", audio_music: MUSIC_STATUS }),
+ false,
+ );
+ assert.match(registry, /kind !== "music" \|\| legacyMusicDescription\(ctx\)/);
+});
+
+test("ACE-Step sends only what the user set, in the runtime's spelling", () => {
+ const value = aceStepMusicalLogic.initial([]);
+ assert.deepEqual(aceStepMusicalLogic.toRequest(value), {});
+ assert.deepEqual(
+ aceStepMusicalLogic.toRequest({
+ bpm: 999,
+ keyscale: "A minor",
+ timesignature: "3",
+ avoid: " shouting ",
+ sampler: "heun",
+ }),
+ {
+ options: {
+ bpm: 300,
+ keyscale: "A minor",
+ timesignature: "3",
+ negative_prompt: "shouting",
+ sampler_mode: "heun",
+ },
+ },
+ );
+ assert.deepEqual(
+ aceStepMusicalLogic.toRequest({
+ ...value,
+ keyscale: "H major",
+ timesignature: "4/4",
+ }),
+ {},
+ );
+ assert.deepEqual(aceStepMusicalLogic.claims, [
+ "bpm",
+ "keyscale",
+ "timesignature",
+ "negative_prompt",
+ "sampler_mode",
+ ]);
+});
+
+test("YuE2 planning starts from the spec default and sends cot", () => {
+ assert.deepEqual(yueCompositionLogic.initial([]), { cot: "full" });
+ assert.deepEqual(
+ yueCompositionLogic.initial([
+ { name: "cot", type: "enum", default: "off" },
+ ]),
+ { cot: "off" },
+ );
+ assert.deepEqual(yueCompositionLogic.toRequest({ cot: "melody" }), {
+ options: { cot: "melody" },
+ });
+});
+
+test("Stable Audio's sampler sends pingpong or euler and whole steps", () => {
+ assert.deepEqual(
+ stableAudioSamplerLogic.toRequest({ sampler: "", steps: null }),
+ {},
+ );
+ assert.deepEqual(
+ stableAudioSamplerLogic.toRequest({ sampler: "dpm", steps: 0 }),
+ {},
+ );
+ assert.deepEqual(
+ stableAudioSamplerLogic.toRequest({ sampler: "euler", steps: 12.4 }),
+ {
+ options: { sampler: "euler", num_inference_steps: 12 },
+ },
+ );
+ assert.deepEqual(
+ stepsRange([
+ { name: "num_inference_steps", type: "int", min: 1, max: 50, default: 8 },
+ ]),
+ { min: 1, max: 50, default: 8 },
+ );
+});
+
+test("the Music studio's Advanced hides speech sampling it never sends", () => {
+ const page = readSrc("features/audio/pages/music-page.tsx");
+ assert.match(
+ page,
+ /musicGeneration=\{false\}\s*samplingControls=\{false\}\s*inputs=\{\s*<MusicStudioInputs/,
+ );
+});
+
+test("Music's source card releases the mic when Audio is hidden, as Clone's does", () => {
+ const host = readSrc("features/audio/audio-page.tsx");
+ assert.match(host, /<AudioActiveProvider value=\{active\}>\s*<MusicRail/);
+ assert.match(host, /<AudioActiveProvider value=\{active\}>\s*<CloneRail/);
+});
diff --git a/studio/frontend/tests/audio-music-policy.test.ts b/studio/frontend/tests/audio-music-policy.test.ts
new file mode 100644
index 00000000000..9c9b6fd568b
--- /dev/null
+++ b/studio/frontend/tests/audio-music-policy.test.ts
@@ -0,0 +1,407 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+
+const { parseMusicCapabilities } = await import(
+ "../src/features/audio/music/music-types.ts"
+);
+const {
+ buildMusicRunRequest,
+ durationLabel,
+ effectiveMusicMode,
+ musicModeHint,
+ musicModeLabel,
+ insertSectionTag,
+ instrumentalChoice,
+ lyricsShown,
+ musicBlocker,
+ musicDurationFor,
+ reloadNotice,
+ sectionTags,
+ variationsFor,
+} = await import("../src/features/audio/music/music-policy.ts");
+const { buildAudioRunBody } = await import(
+ "../src/features/audio/audio-run-request.ts"
+);
+const { DEFAULT_MUSIC_DRAFTS } = await import(
+ "../src/features/audio/stores/audio-music-store.ts"
+);
+
+const STABLE = {
+ modes: [
+ {
+ id: "song",
+ lyrics: "unused",
+ description: "required",
+ instrumental: "always",
+ duration: { min: 1, max: 120, default: 30, approximate: false },
+ variations: { max: 4, how: "batch", loaded: 1 },
+ },
+ {
+ id: "edit",
+ actions: ["inpaint", "restyle"],
+ max_ranges: 8,
+ max_source_s: 120,
+ },
+ ],
+};
+
+const MINIMAX = {
+ modes: [
+ {
+ id: "song",
+ lyrics: "required",
+ description: "required",
+ instrumental: "never",
+ section_case: "lower",
+ duration: { min: 5, max: 240, default: 30, approximate: true },
+ variations: null,
+ },
+ ],
+};
+
+const YUE = {
+ modes: [
+ {
+ id: "song",
+ lyrics: "optional",
+ description: "required",
+ instrumental: "toggle",
+ section_case: "title",
+ duration: { min: 5, max: 240, default: 30, approximate: true },
+ },
+ ],
+};
+
+function caps(raw: unknown) {
+ const parsed = parseMusicCapabilities(raw);
+ assert.ok(parsed);
+ return parsed;
+}
+
+const PATHLIKE = /"(path|voice_ref|file|audio_path|trim)"\s*:/;
+
+// biome-ignore lint/suspicious/noExplicitAny: fixtures stand in for any mode rule and draft.
+function inputs(rule: any, overrides: any = {}) {
+ return {
+ rule,
+ description: "",
+ lyrics: "",
+ ...structuredClone(DEFAULT_MUSIC_DRAFTS),
+ ...overrides,
+ };
+}
+
+test("status parsing keeps known modes and drops malformed ones", () => {
+ assert.equal(parseMusicCapabilities(null), null);
+ assert.equal(parseMusicCapabilities({ modes: [] }), null);
+ assert.equal(parseMusicCapabilities({ modes: [{ id: "karaoke" }] }), null);
+ const parsed = caps({
+ modes: [...STABLE.modes, { id: "song" }, { id: "bogus" }],
+ });
+ assert.deepEqual(
+ parsed.modes.map((mode) => mode.id),
+ ["song", "edit"],
+ );
+ assert.equal(parsed.modes[0].variations?.how, "batch");
+ assert.deepEqual(parsed.modes[1].actions, ["inpaint", "restyle"]);
+ const single = caps({
+ modes: [{ id: "sfx", variations: { max: 1, how: "batch" } }],
+ });
+ assert.equal(single.modes[0].variations, null);
+});
+
+test("the picked mode wins only when the model has it", () => {
+ const stable = caps(STABLE);
+ assert.equal(effectiveMusicMode(stable, "edit").id, "edit");
+ assert.equal(effectiveMusicMode(stable, "sfx").id, "song");
+});
+
+test("section tags follow the model's casing", () => {
+ assert.equal(sectionTags("lower")[1].tag, "[verse]");
+ assert.equal(sectionTags("title")[1].tag, "[Verse]");
+ assert.equal(sectionTags("title")[2].tag, "[Pre-Chorus]");
+ assert.equal(sectionTags("lower")[2].tag, "[pre-chorus]");
+});
+
+test("a section tag lands on its own line at the cursor", () => {
+ assert.deepEqual(insertSectionTag("", 0, "[verse]"), {
+ text: "[verse]\n",
+ cursor: 8,
+ });
+ const after = insertSectionTag("line one", 8, "[chorus]");
+ assert.equal(after.text, "line one\n\n[chorus]\n");
+ assert.equal(after.text.slice(0, after.cursor), "line one\n\n[chorus]\n");
+});
+
+test("instrumental: toggle, always and never", () => {
+ const song = (raw: unknown) => caps(raw).modes[0];
+ assert.deepEqual(instrumentalChoice(song(YUE), true).value, true);
+ assert.equal(instrumentalChoice(song(STABLE), false).value, true);
+ assert.equal(instrumentalChoice(song(MINIMAX), true).value, false);
+ assert.equal(instrumentalChoice(song(MINIMAX), true).enabled, false);
+ assert.ok(instrumentalChoice(song(MINIMAX), true).reason);
+ assert.equal(lyricsShown(song(STABLE), true), false);
+ assert.equal(lyricsShown(song(YUE), true), false);
+ assert.equal(lyricsShown(song(YUE), false), true);
+});
+
+test("length stays inside the model's bounds", () => {
+ const rule = caps(MINIMAX).modes[0];
+ assert.equal(musicDurationFor(rule, null), 30);
+ assert.equal(musicDurationFor(rule, 1), 5);
+ assert.equal(musicDurationFor(rule, 999), 240);
+});
+
+test("blocker reasons are plain and per mode", () => {
+ const minimax = caps(MINIMAX).modes[0];
+ assert.match(String(musicBlocker(inputs(minimax))), /Describe the music/);
+ assert.match(
+ String(musicBlocker(inputs(minimax, { description: "pop" }))),
+ /Write the lyrics/,
+ );
+ assert.equal(
+ musicBlocker(inputs(minimax, { description: "pop", lyrics: "la" })),
+ null,
+ );
+ const yue = caps(YUE).modes[0];
+ const instrumental = inputs(yue, {
+ description: "pop",
+ song: { ...DEFAULT_MUSIC_DRAFTS.song, instrumental: true },
+ });
+ assert.equal(musicBlocker(instrumental), null);
+ const sfx = caps({ modes: [{ id: "sfx" }] }).modes[0];
+ assert.match(String(musicBlocker(inputs(sfx))), /Describe the sound/);
+ const edit = caps(STABLE).modes[1];
+ assert.equal(
+ musicBlocker(inputs(edit, { editProblem: "Pick a clip." })),
+ "Pick a clip.",
+ );
+});
+
+test("the reload notice shows only when a batch needs more than the server holds", () => {
+ const rule = caps(STABLE).modes[0];
+ assert.equal(reloadNotice(rule, 1, "Stable Audio"), null);
+ assert.match(
+ String(reloadNotice(rule, 3, "Stable Audio")),
+ /Reloads Stable Audio/,
+ );
+ const loaded = caps({
+ modes: [
+ { ...STABLE.modes[0], variations: { max: 4, how: "batch", loaded: 4 } },
+ ],
+ }).modes[0];
+ assert.equal(reloadNotice(loaded, 3, "Stable Audio"), null);
+ const sequential = caps({
+ modes: [{ id: "sfx", variations: { max: 4, how: "sequential" } }],
+ }).modes[0];
+ assert.equal(reloadNotice(sequential, 4, "ControlFoley"), null);
+ assert.equal(variationsFor(sequential, 9), 4);
+});
+
+test("a song request carries only music keys and no paths", () => {
+ const rule = caps(YUE).modes[0];
+ const request = buildMusicRunRequest({
+ ...inputs(rule, { description: " dream pop ", lyrics: "[Verse]\nla" }),
+ options: { cot: "melody" },
+ seed: 7,
+ });
+ const body = buildAudioRunBody(request);
+ assert.deepEqual(body, {
+ workflow: "music",
+ text: "dream pop",
+ options: { cot: "melody" },
+ seed: 7,
+ mode: "song",
+ lyrics: "[Verse]\nla",
+ duration_s: 30,
+ });
+ assert.doesNotMatch(JSON.stringify(body), PATHLIKE);
+});
+
+test("instrumental songs send the switch and no lyrics", () => {
+ const rule = caps(YUE).modes[0];
+ const body = buildAudioRunBody(
+ buildMusicRunRequest(
+ inputs(rule, {
+ description: "ambient",
+ lyrics: "[Verse]\nkept for later",
+ song: { ...DEFAULT_MUSIC_DRAFTS.song, instrumental: true },
+ }),
+ ),
+ );
+ assert.equal(body.instrumental, true);
+ assert.equal("lyrics" in body, false);
+});
+
+test("variations go only to models that make them", () => {
+ const stable = caps(STABLE).modes[0];
+ const body = buildAudioRunBody(
+ buildMusicRunRequest(
+ inputs(stable, {
+ description: "house",
+ lyrics: "never sent",
+ song: { ...DEFAULT_MUSIC_DRAFTS.song, variations: 3 },
+ }),
+ ),
+ );
+ assert.equal(body.variations, 3);
+ assert.equal("lyrics" in body, false);
+ assert.equal("instrumental" in body, false);
+ const minimax = caps(MINIMAX).modes[0];
+ const single = buildAudioRunBody(
+ buildMusicRunRequest(
+ inputs(minimax, {
+ description: "pop",
+ lyrics: "la",
+ song: { ...DEFAULT_MUSIC_DRAFTS.song, variations: 3 },
+ }),
+ ),
+ );
+ assert.equal("variations" in single, false);
+});
+
+test("an edit sends the source by id, its ranges and the action's own value", () => {
+ const edit = caps(STABLE).modes[1];
+ const draft = {
+ ...DEFAULT_MUSIC_DRAFTS.edit,
+ source: { kind: "clip", id: "c".repeat(32), name: "take", durationS: 20 },
+ action: "inpaint",
+ ranges: [
+ { start_s: 1, end_s: 2 },
+ { start_s: 5, end_s: 6.5 },
+ ],
+ strength: 0.9,
+ prompt: "brighter",
+ };
+ const body = buildAudioRunBody(
+ buildMusicRunRequest(inputs(edit, { edit: draft })),
+ );
+ assert.deepEqual(body, {
+ workflow: "music",
+ text: "brighter",
+ mode: "edit",
+ inputs: { source: { clip_id: "c".repeat(32) } },
+ edit: {
+ action: "inpaint",
+ ranges: [
+ { start_s: 1, end_s: 2 },
+ { start_s: 5, end_s: 6.5 },
+ ],
+ },
+ });
+ const restyle = buildAudioRunBody(
+ buildMusicRunRequest(
+ inputs(edit, { edit: { ...draft, action: "restyle" } }),
+ ),
+ );
+ assert.deepEqual(restyle.edit, { action: "restyle", strength: 0.9 });
+ // An untouched slider sends the value it shows, not the runtime's 1.0.
+ const untouched = (action: "restyle" | "cover") =>
+ buildAudioRunBody(
+ buildMusicRunRequest(
+ inputs(edit, {
+ edit: { ...draft, action, ranges: [], strength: null },
+ }),
+ ),
+ ).edit;
+ assert.deepEqual(untouched("restyle"), { action: "restyle", strength: 0.45 });
+ assert.deepEqual(untouched("cover"), { action: "cover", strength: 0.5 });
+ const voice = buildAudioRunBody(
+ buildMusicRunRequest(
+ inputs(edit, {
+ edit: {
+ ...draft,
+ source: { kind: "voice", id: "v", name: "x", durationS: 3 },
+ },
+ }),
+ ),
+ );
+ assert.equal("inputs" in voice, false);
+ assert.doesNotMatch(JSON.stringify(body), PATHLIKE);
+});
+
+test("extend sends its seconds and continue its length; repaint keeps a range past the end", () => {
+ const ace = caps({
+ modes: [
+ {
+ id: "edit",
+ actions: ["repaint", "extend", "cover", "continue"],
+ max_ranges: 1,
+ duration: { min: 5, max: 240, default: 60 },
+ },
+ ],
+ }).modes[0];
+ const source = {
+ kind: "input",
+ id: "i".repeat(32),
+ name: "a.wav",
+ durationS: 30,
+ };
+ const extend = buildAudioRunBody(
+ buildMusicRunRequest(
+ inputs(ace, {
+ edit: {
+ ...DEFAULT_MUSIC_DRAFTS.edit,
+ source,
+ action: "extend",
+ extendS: 12,
+ },
+ }),
+ ),
+ );
+ assert.deepEqual(extend.edit, { action: "extend", extend_s: 12 });
+ assert.equal("duration_s" in extend, false);
+ const cont = buildAudioRunBody(
+ buildMusicRunRequest(
+ inputs(ace, {
+ edit: { ...DEFAULT_MUSIC_DRAFTS.edit, source, action: "continue" },
+ }),
+ ),
+ );
+ assert.equal(cont.duration_s, 60);
+ const repaint = buildAudioRunBody(
+ buildMusicRunRequest(
+ inputs(ace, {
+ edit: {
+ ...DEFAULT_MUSIC_DRAFTS.edit,
+ source,
+ action: "repaint",
+ ranges: [{ start_s: 25, end_s: 40 }],
+ },
+ }),
+ ),
+ );
+ assert.deepEqual((repaint.edit as { ranges: unknown }).ranges, [
+ { start_s: 25, end_s: 40 },
+ ]);
+});
+
+test("clone and speak bodies never carry music keys", () => {
+ const body = buildAudioRunBody({
+ workflow: "speak",
+ text: "Hi",
+ music: { mode: "song", lyrics: "x", variations: 3 },
+ });
+ for (const key of ["mode", "lyrics", "variations", "edit", "duration_s"]) {
+ assert.equal(key in body, false, key);
+ }
+});
+
+test("instrumental-only models say so in the mode label and length wording", () => {
+ const stable = caps(STABLE).modes[0];
+ assert.equal(musicModeLabel(stable), "Instrumental");
+ assert.match(musicModeHint(stable), /without vocals/);
+ assert.equal(musicModeLabel(caps(YUE).modes[0]), "Song");
+ assert.equal(durationLabel(stable), "Length (seconds)");
+ assert.equal(
+ durationLabel(caps(YUE).modes[0]),
+ "Length (seconds, approximate)",
+ );
+});
diff --git a/studio/frontend/tests/audio-music-store.test.ts b/studio/frontend/tests/audio-music-store.test.ts
new file mode 100644
index 00000000000..0c2c7e9e64a
--- /dev/null
+++ b/studio/frontend/tests/audio-music-store.test.ts
@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ installLocalStorageFake,
+ registerBundlerResolver,
+} from "./helpers/kit.ts";
+
+const { store } = installLocalStorageFake();
+registerBundlerResolver();
+
+store.set(
+ "unsloth_audio_music_v1",
+ JSON.stringify({
+ state: {
+ mode: "sfx",
+ song: { instrumental: true, durationS: 45, variations: 2 },
+ sfx: { prompt: "rain", durationS: 8, variations: 1 },
+ edit: {
+ source: null,
+ action: "inpaint",
+ ranges: [],
+ strength: 0.4,
+ prompt: "",
+ },
+ },
+ version: 1,
+ }),
+);
+
+const { AUDIO_MUSIC_STORAGE_KEY, useAudioMusicStore } = await import(
+ "../src/features/audio/stores/audio-music-store.ts"
+);
+
+test("drafts come back after a reload, with fields added since filled in", () => {
+ assert.equal(AUDIO_MUSIC_STORAGE_KEY, "unsloth_audio_music_v1");
+ const state = useAudioMusicStore.getState();
+ assert.equal(state.mode, "sfx");
+ assert.deepEqual(state.song, {
+ instrumental: true,
+ durationS: 45,
+ variations: 2,
+ });
+ assert.equal(state.sfx.prompt, "rain");
+ assert.equal(state.edit.action, "inpaint");
+ assert.equal(state.edit.extendS, 15);
+});
+
+test("switching mode keeps every other mode's draft", () => {
+ const { setMode, patchDraft } = useAudioMusicStore.getState();
+ patchDraft("song", { variations: 3 });
+ setMode("edit");
+ patchDraft("edit", { prompt: "brighter" });
+ setMode("song");
+ const state = useAudioMusicStore.getState();
+ assert.equal(state.song.variations, 3);
+ assert.equal(state.sfx.prompt, "rain");
+ assert.equal(state.edit.prompt, "brighter");
+ const saved = JSON.parse(store.get("unsloth_audio_music_v1") ?? "{}");
+ assert.equal(saved.state.edit.prompt, "brighter");
+ assert.equal(saved.state.mode, "song");
+});
+
+test("Edit in Music opens Edit on the clip and drops ranges drawn on another clip", () => {
+ const { patchDraft, pushClipToEdit } = useAudioMusicStore.getState();
+ const first = {
+ kind: "clip" as const,
+ id: "a",
+ name: "first",
+ durationS: 20,
+ };
+ pushClipToEdit(first, "repaint");
+ patchDraft("edit", { ranges: [{ start_s: 1, end_s: 2 }] });
+ pushClipToEdit(first);
+ let state = useAudioMusicStore.getState();
+ assert.equal(state.mode, "edit");
+ assert.equal(state.edit.action, "repaint");
+ assert.equal(state.edit.ranges.length, 1);
+ pushClipToEdit(
+ { kind: "clip" as const, id: "b", name: "second", durationS: 9 },
+ "extend",
+ );
+ state = useAudioMusicStore.getState();
+ assert.equal(state.edit.source?.id, "b");
+ assert.equal(state.edit.action, "extend");
+ assert.deepEqual(state.edit.ranges, []);
+ assert.equal(state.sfx.prompt, "rain");
+});
+
+test("an empty change prompt starts from the clip's own description", () => {
+ const { patchDraft, pushClipToEdit } = useAudioMusicStore.getState();
+ patchDraft("edit", { prompt: "" });
+ pushClipToEdit({
+ kind: "clip" as const,
+ id: "c",
+ name: "lofi beat",
+ durationS: 30,
+ });
+ assert.equal(useAudioMusicStore.getState().edit.prompt, "lofi beat");
+ patchDraft("edit", { prompt: "brighter" });
+ pushClipToEdit({
+ kind: "clip" as const,
+ id: "d",
+ name: "other",
+ durationS: 30,
+ });
+ assert.equal(useAudioMusicStore.getState().edit.prompt, "brighter");
+ useAudioMusicStore.getState().setLoadedEditActions(["inpaint"]);
+ const saved = JSON.parse(store.get("unsloth_audio_music_v1") ?? "{}");
+ assert.equal("loadedEditActions" in saved.state, false);
+});
diff --git a/studio/frontend/tests/audio-variation-groups.test.ts b/studio/frontend/tests/audio-variation-groups.test.ts
new file mode 100644
index 00000000000..982844543f2
--- /dev/null
+++ b/studio/frontend/tests/audio-variation-groups.test.ts
@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readSrc } from "./helpers/kit.ts";
+
+const { groupHistory, historyRows, variationLabel, variationSiblings } =
+ await import("../src/features/audio/music/variation-groups.ts");
+
+const clip = (id: string, group_id?: string | null, variation?: number) => ({
+ id,
+ group_id,
+ settings: variation === undefined ? null : { variation },
+});
+
+const clips = [
+ clip("a"),
+ clip("v3", "g1", 3),
+ clip("v1", "g1", 1),
+ clip("b", "solo"),
+ clip("v2", "g1", 2),
+ clip("c", null),
+];
+
+test("a group of variations is one row where its first clip was", () => {
+ const entries = groupHistory(clips);
+ assert.deepEqual(
+ entries.map((entry) =>
+ entry.kind === "clip" ? entry.clip.id : `group:${entry.groupId}`,
+ ),
+ ["a", "group:g1", "b", "c"],
+ );
+ const group = entries[1];
+ assert.equal(group.kind, "group");
+ if (group.kind === "group") {
+ assert.deepEqual(
+ group.clips.map((item) => item.id),
+ ["v1", "v2", "v3"],
+ );
+ }
+});
+
+test("a group of one, or clips without a group, render as before", () => {
+ assert.deepEqual(
+ groupHistory([clip("x", "only"), clip("y")]).map((entry) => entry.kind),
+ ["clip", "clip"],
+ );
+ assert.deepEqual(groupHistory([]), []);
+});
+
+test("without recorded variation numbers the listed order stands", () => {
+ const entries = groupHistory([
+ clip("p", "g"),
+ clip("q", "g"),
+ clip("r", "g"),
+ ]);
+ assert.equal(entries.length, 1);
+ const group = entries[0];
+ if (group.kind === "group") {
+ assert.deepEqual(
+ group.clips.map((item) => item.id),
+ ["p", "q", "r"],
+ );
+ }
+});
+
+test("labels and siblings", () => {
+ assert.equal(variationLabel(3), "3 variations");
+ assert.equal(variationLabel(1), "1 variation");
+ assert.deepEqual(
+ variationSiblings(clips, "v3").map((item) => item.id),
+ ["v1", "v2", "v3"],
+ );
+ assert.deepEqual(variationSiblings(clips, "b"), []);
+ assert.deepEqual(variationSiblings(clips, "a"), []);
+ assert.deepEqual(variationSiblings(clips, null), []);
+ assert.deepEqual(variationSiblings(clips, "missing"), []);
+});
+
+test("an open group lists its clips nested under the header", () => {
+ const closed = historyRows(clips, new Set());
+ assert.equal(closed.length, 4);
+ assert.equal(closed[1].header?.open, false);
+ const open = historyRows(clips, new Set(["g1"]));
+ assert.deepEqual(
+ open.map((row) =>
+ row.header ? "header" : `${row.clip.id}${row.nested ? "*" : ""}`,
+ ),
+ ["a", "header", "v1*", "v2*", "v3*", "b", "c"],
+ );
+});
+
+test("TtsOutput groups history rows and offers Send to for music clips", () => {
+ const source = readSrc("features/audio/pages/tts-workspace.tsx");
+ assert.match(source, /historyRows\(clips, openGroups\)/);
+ assert.match(source, /<VariationChips/);
+ assert.match(source, /<MusicSendToMenuItems clip=\{clip\} \/>/);
+ assert.match(source, /menu=\{clipMenu\(selectedClip, "row"\)\}/);
+ const send = readSrc("features/audio/components/music-send-to.tsx");
+ assert.match(send, /pushClipToEdit\(/);
+ assert.match(send, /edit: "Edit"/);
+ assert.match(send, /extend: "Extend"/);
+ assert.match(send, /sendActionsFor\(editActions\)/);
+ assert.match(send, /clipWorkflow\(clip\) === "music"/);
+ assert.match(send, /requestWorkflow\("music"\)/);
+});
diff --git a/studio/frontend/tests/audio-waveform-range.test.ts b/studio/frontend/tests/audio-waveform-range.test.ts
new file mode 100644
index 00000000000..f5722435954
--- /dev/null
+++ b/studio/frontend/tests/audio-waveform-range.test.ts
@@ -0,0 +1,222 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readSrc } from "./helpers/kit.ts";
+
+const {
+ MIN_RANGE_S,
+ addRange,
+ clampRange,
+ defaultRange,
+ dragToRange,
+ formatRange,
+ formatRangeTime,
+ mergeRanges,
+ moveRange,
+ nextFreeRange,
+ normalizeRanges,
+ nudgeStep,
+ pxToSeconds,
+ rangeLabel,
+ removeRange,
+ secondsBeyondEnd,
+ secondsToFraction,
+ secondsToPx,
+ timelineEnd,
+} = await import("../src/features/audio/components/waveform-range.ts");
+
+const inside = { durationS: 10, maxRanges: 3 };
+const one = { durationS: 10, maxRanges: 1 };
+const tail = { durationS: 10, maxRanges: 1, beyondEndS: 5 };
+
+test("pixels and seconds map across the timeline, tail included", () => {
+ assert.equal(timelineEnd(inside), 10);
+ assert.equal(timelineEnd(tail), 15);
+ assert.equal(pxToSeconds(50, 200, 10), 2.5);
+ assert.equal(pxToSeconds(-20, 200, 10), 0);
+ assert.equal(pxToSeconds(400, 200, 10), 10);
+ assert.equal(pxToSeconds(10, 0, 10), 0);
+ assert.equal(secondsToPx(2.5, 200, 10), 50);
+ assert.equal(secondsToFraction(15, 15), 1);
+ assert.equal(secondsToFraction(20, 15), 1);
+ assert.equal(secondsToFraction(1, 0), 0);
+});
+
+test("a range is ordered, clamped and at least 0.25 s", () => {
+ assert.deepEqual(clampRange({ start_s: 4, end_s: 2 }, inside), {
+ start_s: 2,
+ end_s: 4,
+ });
+ assert.deepEqual(clampRange({ start_s: -1, end_s: 12 }, inside), {
+ start_s: 0,
+ end_s: 10,
+ });
+ assert.deepEqual(clampRange({ start_s: 3, end_s: 3.1 }, inside), {
+ start_s: 3,
+ end_s: 3 + MIN_RANGE_S,
+ });
+ assert.deepEqual(clampRange({ start_s: 9.95, end_s: 10 }, inside), {
+ start_s: 9.75,
+ end_s: 10,
+ });
+ assert.equal(
+ clampRange({ start_s: 0, end_s: 1 }, { durationS: 0.1, maxRanges: 1 }),
+ null,
+ );
+ assert.equal(clampRange({ start_s: Number.NaN, end_s: 1 }, inside), null);
+});
+
+test("overlapping and touching ranges merge, sorted", () => {
+ assert.deepEqual(
+ mergeRanges(
+ [
+ { start_s: 6, end_s: 8 },
+ { start_s: 1, end_s: 3 },
+ { start_s: 2, end_s: 4 },
+ { start_s: 8, end_s: 9 },
+ ],
+ inside,
+ ),
+ [
+ { start_s: 1, end_s: 4 },
+ { start_s: 6, end_s: 9 },
+ ],
+ );
+});
+
+test("max ranges caps the list; one allowed replaces, past the cap is refused", () => {
+ const three = [
+ { start_s: 0, end_s: 1 },
+ { start_s: 2, end_s: 3 },
+ { start_s: 4, end_s: 5 },
+ ];
+ assert.equal(
+ normalizeRanges([...three, { start_s: 7, end_s: 8 }], inside).length,
+ 3,
+ );
+ assert.deepEqual(addRange(three, { start_s: 7, end_s: 8 }, inside), three);
+ assert.deepEqual(addRange(three, { start_s: 4.5, end_s: 6 }, inside).at(-1), {
+ start_s: 4,
+ end_s: 6,
+ });
+ assert.deepEqual(
+ addRange([{ start_s: 0, end_s: 1 }], { start_s: 5, end_s: 6 }, one),
+ [{ start_s: 5, end_s: 6 }],
+ );
+ assert.deepEqual(
+ addRange(three, { start_s: 7, end_s: 8 }, { durationS: 10, maxRanges: 0 }),
+ [],
+ );
+ assert.deepEqual(removeRange(three, 1), [three[0], three[2]]);
+});
+
+test("arrow keys nudge by 0.1 s, Shift+arrow by 1 s", () => {
+ assert.equal(nudgeStep({ key: "ArrowRight" }), 0.1);
+ assert.equal(nudgeStep({ key: "ArrowLeft" }), -0.1);
+ assert.equal(nudgeStep({ key: "ArrowUp", shiftKey: true }), 1);
+ assert.equal(nudgeStep({ key: "ArrowDown", shiftKey: true }), -1);
+ assert.equal(nudgeStep({ key: "Enter" }), null);
+ const ranges = [{ start_s: 2, end_s: 4 }];
+ assert.deepEqual(moveRange(ranges, 0, "both", 0.1, inside), [
+ { start_s: 2.1, end_s: 4.1 },
+ ]);
+ assert.deepEqual(moveRange(ranges, 0, "start", -1, inside), [
+ { start_s: 1, end_s: 4 },
+ ]);
+ assert.deepEqual(moveRange(ranges, 0, "end", 1, inside), [
+ { start_s: 2, end_s: 5 },
+ ]);
+ assert.deepEqual(moveRange(ranges, 0, "start", 5, inside), [
+ { start_s: 3.75, end_s: 4 },
+ ]);
+ assert.deepEqual(moveRange(ranges, 0, "both", -5, inside), [
+ { start_s: 0, end_s: 2 },
+ ]);
+ assert.deepEqual(moveRange(ranges, 0, "both", 50, inside), [
+ { start_s: 8, end_s: 10 },
+ ]);
+ assert.deepEqual(
+ moveRange(
+ [
+ { start_s: 1, end_s: 2 },
+ { start_s: 3, end_s: 4 },
+ ],
+ 0,
+ "end",
+ 1.5,
+ inside,
+ ),
+ [{ start_s: 1, end_s: 4 }],
+ );
+});
+
+test("past the end only when the tail is allowed", () => {
+ assert.deepEqual(moveRange([{ start_s: 8, end_s: 9 }], 0, "end", 3, inside), [
+ { start_s: 8, end_s: 10 },
+ ]);
+ assert.deepEqual(moveRange([{ start_s: 8, end_s: 9 }], 0, "end", 3, tail), [
+ { start_s: 8, end_s: 12 },
+ ]);
+ assert.deepEqual(moveRange([{ start_s: 8, end_s: 9 }], 0, "end", 30, tail), [
+ { start_s: 8, end_s: 15 },
+ ]);
+ assert.equal(secondsBeyondEnd({ start_s: 8, end_s: 12 }, 10), 2);
+ assert.equal(secondsBeyondEnd({ start_s: 1, end_s: 2 }, 10), 0);
+ assert.deepEqual(dragToRange(9, 13, inside), { start_s: 9, end_s: 10 });
+ assert.deepEqual(dragToRange(9, 13, tail), { start_s: 9, end_s: 13 });
+});
+
+test("a tiny drag is a click; a drag either way makes a range", () => {
+ assert.equal(dragToRange(3, 3.05, inside), null);
+ assert.deepEqual(dragToRange(5, 2, inside), { start_s: 2, end_s: 5 });
+});
+
+test("keyboard users get a first range and the next free gap", () => {
+ assert.deepEqual(defaultRange(inside), { start_s: 4, end_s: 6 });
+ const next = nextFreeRange([{ start_s: 4, end_s: 6 }], inside);
+ assert.ok(next);
+ assert.ok(
+ next.end_s < 4 || next.start_s > 6,
+ "lands in a gap, not on the existing part",
+ );
+ assert.equal(
+ normalizeRanges([{ start_s: 4, end_s: 6 }, next], inside).length,
+ 2,
+ );
+ assert.equal(nextFreeRange([{ start_s: 0, end_s: 10 }], inside), null);
+ assert.equal(nextFreeRange([{ start_s: 1, end_s: 2 }], one), null);
+});
+
+test("times read as 0:01.2 and ranges have spoken labels", () => {
+ assert.equal(formatRangeTime(1.24), "0:01.2");
+ assert.equal(formatRangeTime(62.5), "1:02.5");
+ assert.equal(formatRangeTime(-3), "0:00.0");
+ assert.equal(formatRange({ start_s: 1.2, end_s: 2.5 }), "0:01.2–0:02.5");
+ assert.equal(
+ rangeLabel(0, { start_s: 1.2, end_s: 2.5 }),
+ "Range 1, 1.2 to 2.5 seconds",
+ );
+});
+
+test("the range select is neutral, static and keyboard reachable", () => {
+ const source = readSrc("features/audio/components/waveform-range-select.tsx");
+ assert.match(
+ source,
+ /var\(--foreground\)_calc\(10%\*var\(--contrast-wash-gain,1\)\)/,
+ );
+ assert.match(source, /ring-1/);
+ assert.match(source, /font-mono/);
+ assert.match(
+ source,
+ /event\.key === "Delete" \|\| event\.key === "Backspace"/,
+ );
+ assert.match(source, /rangeLabel\(/);
+ assert.match(source, /setPointerCapture/);
+ assert.doesNotMatch(source, /animate-|transition-/);
+ const waveform = readSrc("features/audio/components/waveform.tsx");
+ assert.match(waveform, /border-dashed/);
+ assert.doesNotMatch(waveform, /animate-|transition-/);
+});