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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Stems from a saved separation answer, base64-decoded in chunks from an mmap; json.loads would
hold ~42 MB of base64 per 180 s stem three times over."""
from __future__ import annotations
import binascii
import json
import mmap
import re
import struct
from pathlib import Path
from typing import Any, Optional
# Keys whose string value can carry base64 audio, matching ``_audio_candidates`` in the backend.
_AUDIO_KEYS = ("audio", "wav", "data", "audio_base64", "b64_json")
_AUDIO_KEY_RE = re.compile(rb'(?<!\\)"(' + "|".join(_AUDIO_KEYS).encode() + rb')"\s*:\s*"')
_PLACEHOLDER = "\u0000span"
_ID_UNSAFE_RE = re.compile(r"[^A-Za-z0-9_-]")
_B64_ALPHABET = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/="
# Everything else is dropped before decoding: JSON's ``\\/`` escape, line breaks, padding spaces.
_B64_DROP = bytes(b for b in range(256) if b not in _B64_ALPHABET)
NO_STEMS = "The audio runtime returned no stems."
class SeparationOutputError(RuntimeError):
"""The answer has no stem Studio can decode."""
def __init__(self, detail: str = NO_STEMS):
super().__init__(detail)
def _string_end(mm: mmap.mmap, start: int) -> int:
"""Index of the unescaped quote that closes the JSON string starting at ``start``."""
pos = start
while True:
end = mm.find(b'"', pos)
if end < 0:
raise SeparationOutputError()
slashes = 0
while end - 1 - slashes >= start and mm[end - 1 - slashes] == 0x5C:
slashes += 1
if slashes % 2 == 0:
return end
pos = end + 1
def _audio_spans(mm: mmap.mmap) -> list[tuple[int, int]]:
spans = []
pos = 0
while True:
match = _AUDIO_KEY_RE.search(mm, pos)
if match is None:
return spans
start = match.end()
end = _string_end(mm, start)
spans.append((start, end))
pos = end + 1
def _redacted(mm: mmap.mmap, spans: list[tuple[int, int]]) -> Any:
"""The document with every audio string replaced by ``"\\u0000span<k>"``, parsed."""
parts = []
prev = 0
for index, (start, end) in enumerate(spans):
parts.append(mm[prev:start])
parts.append(f"\\u0000span{index}".encode("ascii"))
prev = end
parts.append(mm[prev:])
try:
return json.loads(b"".join(parts).decode("utf-8"))
except (UnicodeDecodeError, ValueError) as exc:
raise SeparationOutputError() from exc
def _find_outputs(node: Any) -> Optional[list]:
if isinstance(node, dict):
outputs = node.get("named_audio_outputs")
if isinstance(outputs, list):
return outputs
for value in node.values():
found = _find_outputs(value)
if found is not None:
return found
elif isinstance(node, list):
for item in node:
found = _find_outputs(item)
if found is not None:
return found
return None
def _span_index(item: dict) -> Optional[int]:
for key in _AUDIO_KEYS:
value = item.get(key)
if isinstance(value, str) and value.startswith(_PLACEHOLDER):
try:
return int(value[len(_PLACEHOLDER) :])
except ValueError:
return None
return None
def safe_stem_id(raw: Any, taken: set[str]) -> str:
"""A file-safe id (``[A-Za-z0-9_-]{1,64}``), unique among ``taken`` by a ``_2`` style suffix,
ignoring case (Windows and macOS read ``Vocals.wav`` as ``vocals.wav``)."""
base = _ID_UNSAFE_RE.sub("_", str(raw or "").strip())[:64] or "stem"
seen = {item.casefold() for item in taken}
stem_id = base
n = 2
while stem_id.casefold() in seen:
suffix = f"_{n}"
stem_id = base[: 64 - len(suffix)] + suffix
n += 1
taken.add(stem_id)
return stem_id
def _decode_span(mm: mmap.mmap, start: int, end: int, dest: Path, chunk: int) -> None:
head = mm[start : min(end, start + 128)]
if head.startswith(b"data:"):
comma = head.find(b",")
if comma >= 0:
start += comma + 1
chunk = max(4, chunk - chunk % 4)
carry = b""
with open(dest, "wb") as out:
pos = start
while pos < end:
stop = min(end, pos + chunk)
raw = mm[pos:stop]
text = raw.translate(None, _B64_DROP)
del raw
if carry:
text = carry + text
usable = len(text) - len(text) % 4
if usable:
out.write(binascii.a2b_base64(memoryview(text)[:usable]))
carry = text[usable:]
del text
pos = stop
if carry.strip(b"="):
out.write(binascii.a2b_base64(carry + b"=" * (-len(carry) % 4)))
def riff_info(path: Path) -> dict[str, Any]:
"""``sample_rate``, ``channels``, ``frames`` from a RIFF/WAVE header; ValueError otherwise."""
with open(path, "rb") as f:
header = f.read(12)
if len(header) < 12 or header[:4] != b"RIFF" or header[8:12] != b"WAVE":
raise ValueError("not a RIFF/WAVE file")
size = path.stat().st_size
fmt = None
while True:
chunk_head = f.read(8)
if len(chunk_head) < 8:
raise ValueError("no data chunk")
name, length = chunk_head[:4], struct.unpack("<I", chunk_head[4:])[0]
if name == b"fmt ":
body = f.read(length)
if len(body) < 16:
raise ValueError("short fmt chunk")
audio_format, channels, rate, _byte_rate, block_align, _bits = struct.unpack(
"<HHIIHH", body[:16]
)
if audio_format not in (1, 3, 0xFFFE) or not channels or not rate:
raise ValueError("unsupported WAV encoding")
fmt = (channels, rate, block_align or 1)
if length % 2:
f.seek(1, 1)
elif name == b"data":
if fmt is None:
raise ValueError("data before fmt")
# A streamed writer leaves the size at 0 or 0xFFFFFFFF; the file length is the truth.
available = size - f.tell()
if length == 0 or length > available:
length = available
channels, rate, block_align = fmt
return {"sample_rate": rate, "channels": channels, "frames": length // block_align}
else:
f.seek(length + (length % 2), 1)
def extract_named_outputs(
json_path: Path | str,
out_dir: Path | str,
*,
chunk: int = 4 << 20,
) -> list[dict[str, Any]]:
"""Decode ``named_audio_outputs[*]`` into ``out_dir/<id>.wav``, all or none.
Top-level ``audio`` is ignored: in a batch answer it repeats the first named output."""
json_path = Path(json_path)
out_dir = Path(out_dir)
try:
size = json_path.stat().st_size
except OSError as exc:
raise SeparationOutputError() from exc
if size == 0:
raise SeparationOutputError()
written: list[Path] = []
try:
with open(json_path, "rb") as f, mmap.mmap(f.fileno(), 0, access = mmap.ACCESS_READ) as mm:
spans = _audio_spans(mm)
outputs = _find_outputs(_redacted(mm, spans))
if not outputs:
raise SeparationOutputError()
taken: set[str] = set()
results = []
for item in outputs:
if not isinstance(item, dict) or item.get("id") in (None, ""):
raise SeparationOutputError()
index = _span_index(item)
if index is None or index >= len(spans):
raise SeparationOutputError()
stem_id = safe_stem_id(item["id"], taken)
dest = out_dir / f"{stem_id}.wav"
written.append(dest)
start, end = spans[index]
try:
_decode_span(mm, start, end, dest, chunk)
info = riff_info(dest)
except (binascii.Error, ValueError) as exc:
raise SeparationOutputError() from exc
results.append(
{
"id": stem_id,
"path": str(dest),
"sample_rate": info["sample_rate"],
"channels": info["channels"],
"duration_s": round(info["frames"] / info["sample_rate"], 3),
}
)
return results
except BaseException:
for path in written:
try:
path.unlink(missing_ok = True)
except OSError:
pass
raise