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.

27.0 KB
Raw Blame
# 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 page inputs kept a day under <gallery_dir>/inputs; requests name an input, clip or voice by
id, resolved in the current account, never a file path."""

from __future__ import annotations

import hashlib
import json
import os
import shutil
import threading
import time
import uuid
import wave
from dataclasses import dataclass
from pathlib import Path
from typing import Any, AsyncIterable, Optional

from core.inference import audio_gallery
from loggers import get_logger
from utils.account_context import OWNER, AccountContext, is_owner_context, run_as
from utils.paths.storage_roots import account_path
from utils.upload_limits import audio_input_max_bytes

logger = get_logger(__name__)

MAX_SECONDS = 30 * 60
# Uploads (and Transcribe on audio.cpp) take up to this; minutes in the env var override it.
TRANSCRIBE_MAX_MINUTES_ENV = "UNSLOTH_STUDIO_TRANSCRIBE_MAX_MINUTES"
DEFAULT_TRANSCRIBE_MAX_SECONDS = 4 * 60 * 60
TTL_SECONDS = 24 * 60 * 60
BYTE_CAP = 2 * 1024 * 1024 * 1024
REFERENCE_MAX_SECONDS = 30.0
REFERENCE_RATE = 24000
_MAX_CHANNELS = 2
# Caps the stored rate so a 30 minute upload stays under ~350 MB however it was encoded;
# longer uploads are refused once their WAV copy would pass BYTE_CAP.
MAX_RATE = 48000
_NAME_MAX = 255
_STALE_TMP_SECONDS = 60 * 60


def transcribe_max_seconds() -> int:
    """The longest upload, read per call; never under MAX_SECONDS."""
    try:
        minutes = int(os.environ.get(TRANSCRIBE_MAX_MINUTES_ENV, "").strip())
    except ValueError:
        minutes = 0
    seconds = minutes * 60 if minutes > 0 else DEFAULT_TRANSCRIBE_MAX_SECONDS
    return max(MAX_SECONDS, seconds)


def length_words(seconds: float) -> str:
    """``4 hours``, ``1 hour`` or ``90 minutes``."""
    if seconds >= 3600 and seconds % 3600 == 0:
        hours = int(seconds // 3600)
        return "1 hour" if hours == 1 else f"{hours} hours"
    return f"{int(seconds // 60)} minutes"


def _size_words(nbytes: int) -> str:
    gib = 1024 * 1024 * 1024
    if nbytes >= gib and nbytes % gib == 0:
        return f"{nbytes // gib} GB"
    return f"{nbytes // (1024 * 1024)} MB"


class AudioInputError(ValueError):
    """A refusal with the HTTP status and plain reason the route sends."""

    def __init__(self, status: int, detail: str):
        super().__init__(detail)
        self.status = status
        self.detail = detail


def inputs_dir() -> Path:
    """``<gallery_dir>/inputs``, which ``gallery_dir`` scopes to the account for a non-owner."""
    directory = audio_gallery.gallery_dir() / "inputs"
    directory.mkdir(parents = True, exist_ok = True)
    return directory


def _valid_id(input_id: Optional[str]) -> bool:
    return bool(input_id) and bool(audio_gallery._ID_RE.match(str(input_id)))


def _now() -> float:
    return time.time()


def _iso(epoch: float) -> str:
    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(epoch))


def _clean_name(name: Optional[str]) -> str:
    """The file's own name: no folders, no control characters, bounded."""
    text = str(name or "").replace("\\", "/").rsplit("/", 1)[-1]
    text = "".join(ch for ch in text if ch.isprintable()).strip()
    return text[:_NAME_MAX] or "audio"


def _sidecar(directory: Path, input_id: str) -> Path:
    return directory / f"{input_id}.json"


def _read_sidecar(path: Path) -> Optional[dict[str, Any]]:
    try:
        meta = json.loads(path.read_text(encoding = "utf-8"))
    except (OSError, ValueError, UnicodeError):
        return None
    required = ("name", "duration_s", "sample_rate", "channels", "sha256", "created_at")
    if not isinstance(meta, dict) or any(k not in meta for k in required):
        return None
    return meta


def _touched(meta: dict[str, Any]) -> float:
    try:
        return float(meta.get("touched_at") or meta.get("created_at_epoch") or 0.0)
    except (TypeError, ValueError):
        return 0.0


def _expired(meta: dict[str, Any], now: Optional[float] = None) -> bool:
    return _touched(meta) + TTL_SECONDS <= (now if now is not None else _now())


def _record(input_id: str, meta: dict[str, Any]) -> dict[str, Any]:
    return {
        "id": input_id,
        "name": meta["name"],
        "duration_s": meta["duration_s"],
        "sample_rate": meta["sample_rate"],
        "channels": meta["channels"],
        "url": f"/api/inference/audio/inputs/{input_id}/file",
        "expires_at": _iso(_touched(meta) + TTL_SECONDS),
    }


def _write_json(path: Path, meta: dict[str, Any]) -> None:
    tmp = path.with_name(f".{path.name}.{uuid.uuid4().hex[:8]}.tmp")
    try:
        tmp.write_text(json.dumps(meta), encoding = "utf-8")
        os.replace(tmp, path)
    except BaseException:
        tmp.unlink(missing_ok = True)
        raise


def _protocol_options(source) -> dict:
    # Playlists open what they name: a path may read files only, a buffer nothing.
    local = isinstance(source, (str, os.PathLike))
    return {"protocol_whitelist": "file" if local else "none"}


def _av_open(av, source):
    from utils.media_playlist import refuse_playlist

    # `file` stays allowed for a path, so a playlist that names local files is refused here.
    refuse_playlist(source)
    options = _protocol_options(source)
    try:
        return av.open(source, mode = "r", metadata_errors = "ignore", options = options)
    except TypeError as exc:
        if "metadata_errors" not in str(exc):
            raise
        return av.open(source, mode = "r", format = None, options = options)


def _decoded_frames(av, container):
    for packet in container.demux(container.streams.audio[0]):
        try:
            frames = packet.decode()
        except av.error.InvalidDataError:
            continue
        yield from frames


def transcode(
    src: Path,
    dst: Path,
    *,
    rate: Optional[int] = None,
    mono: bool = False,
    stereo: bool = False,
    max_seconds: Optional[float] = None,
    cut: bool = False,
    max_bytes: Optional[int] = None,
) -> dict[str, Any]:
    """Streams through the FFmpeg resampler so a voice reference does not alias; past max_seconds it is cut if cut is set, else refused with 413.
    A WAV that would pass max_bytes is refused with 413."""
    import av

    max_seconds = MAX_SECONDS if max_seconds is None else max_seconds
    tmp = dst.with_name(f".{dst.name}.{uuid.uuid4().hex[:8]}.tmp")
    frames = channels = ceiling = 0
    out = resampler = None

    def write(blocks) -> bool:
        nonlocal frames
        for block in blocks:
            take = min(block.samples, ceiling - frames)
            if take < block.samples and not cut:
                raise AudioInputError(413, f"Audio is longer than {length_words(max_seconds)}.")
            if max_bytes is not None and (frames + take) * channels * 2 > max_bytes:
                raise AudioInputError(
                    413,
                    "This audio is too long to keep: its WAV copy would pass the "
                    f"{_size_words(max_bytes)} an account can hold. Trim it, or upload it as "
                    "mono or at a lower sample rate.",
                )
            out.writeframesraw(block.to_ndarray().reshape(-1)[: take * channels].tobytes())
            frames += take
            if cut and frames >= ceiling:
                return True
        return False

    try:
        try:
            container = _av_open(av, str(src))
        except Exception as exc:  # noqa: BLE001 - not a container PyAV knows
            raise AudioInputError(400, "This file is not audio Unsloth can read.") from exc
        with container:
            if not container.streams.audio:
                raise AudioInputError(400, "This file has no audio stream.")
            try:
                for frame in _decoded_frames(av, container):
                    if resampler is None:
                        rate = rate or min(int(frame.sample_rate or 0), MAX_RATE)
                        if rate <= 0:
                            raise AudioInputError(400, "This audio has no sample rate.")
                        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)
                        ceiling = int(max_seconds * rate)
                        out = wave.open(str(tmp), "wb")
                        out.setnchannels(channels)
                        out.setsampwidth(2)
                        out.setframerate(rate)
                    if write(resampler.resample(frame)):
                        break
                else:
                    if resampler is not None:
                        write(resampler.resample(None))
            except AudioInputError:
                raise
            except Exception as exc:  # noqa: BLE001 - a corrupt stream mid-file keeps what decoded
                if not frames:
                    raise AudioInputError(400, "This file is not audio Unsloth can read.") from exc
                logger.info("audio_inputs: decode stopped early after %d frames: %s", frames, exc)
        if out is not None:
            out.close()
            out = None
        if not frames:
            raise AudioInputError(400, "This file has no audio in it.")
        os.replace(tmp, dst)
    finally:
        if out is not None:
            out.close()
        tmp.unlink(missing_ok = True)
    return {"duration_s": round(frames / rate, 3), "sample_rate": rate, "channels": channels}


# /v1/audio/speech formats besides WAV: (container, encoder, media type, sample rate it needs).
_SPEECH_ENCODINGS = {
    "mp3": ("mp3", "mp3", "audio/mpeg", None),
    "opus": ("ogg", "libopus", "audio/ogg", 48000),
    "aac": ("adts", "aac", "audio/aac", None),
    "flac": ("flac", "flac", "audio/flac", None),
    # OpenAI's pcm is 24 kHz 16-bit mono; its clients assume that rate.
    "pcm": ("s16le", "pcm_s16le", "audio/pcm", 24000),
}


def speech_formats() -> list[str]:
    """``wav`` plus each speech format whose encoder this FFmpeg build has."""
    import av

    formats = ["wav"]
    for fmt, (_container, codec, _media_type, _rate) in _SPEECH_ENCODINGS.items():
        try:
            av.codec.Codec(codec, "w")
        except Exception:  # noqa: BLE001 - not in this build
            continue
        formats.append(fmt)
    return formats


def encode_wav(wav_bytes: bytes, fmt: str) -> tuple[bytes, str]:
    """A WAV re-encoded as ``fmt`` (a ``speech_formats`` name but wav); ``(bytes, media type)``.
    ``pcm`` is 24 kHz 16-bit little-endian mono samples, with no header."""
    import io

    import av

    container_format, codec, media_type, fixed_rate = _SPEECH_ENCODINGS[fmt]
    out = io.BytesIO()
    with _av_open(av, io.BytesIO(wav_bytes)) as src:
        audio = src.streams.audio[0]
        rate = fixed_rate or audio.rate
        # A WAV with no channel mask reads as "1 channels", which no encoder takes.
        layout = "stereo" if audio.channels == 2 and fmt != "pcm" else "mono"
        with av.open(out, "w", format = container_format) as dst:
            stream = dst.add_stream(codec, rate = rate, layout = layout)
            stream.codec_context.open(strict = True)  # sets frame_size, which mp3, aac and opus need
            resampler = av.AudioResampler(
                format = stream.format.name,
                layout = layout,
                rate = rate,
                frame_size = stream.frame_size or None,
            )

            def mux(frames) -> None:
                for frame in frames:
                    for packet in stream.encode(frame):
                        dst.mux(packet)

            for frame in src.decode(audio):
                frame.pts = None
                mux(resampler.resample(frame))
            mux(resampler.resample(None))
            mux([None])
    return out.getvalue(), media_type


async def save_stream(
    chunks: AsyncIterable[bytes],
    name: Optional[str],
    *,
    max_bytes: Optional[int] = None,
) -> tuple[dict[str, Any], bool]:
    """The byte cap is checked per chunk, so an oversize upload is refused before it is read whole."""
    import asyncio

    cap = audio_input_max_bytes() if max_bytes is None else max_bytes
    directory = inputs_dir()
    tmp = directory / f".{uuid.uuid4().hex}.upload.tmp"
    digest = hashlib.sha256()
    size = 0
    try:
        with open(tmp, "wb") as f:
            async for chunk in chunks:
                if not chunk:
                    continue
                size += len(chunk)
                if cap is not None and size > cap:
                    raise AudioInputError(413, "Audio is too large.")
                digest.update(chunk)
                f.write(chunk)
        if not size:
            raise AudioInputError(400, "Audio is empty.")
        return await asyncio.to_thread(
            _finish_upload,
            directory,
            tmp,
            digest.hexdigest(),
            _clean_name(name),
            size,
            max_seconds = transcribe_max_seconds(),
            max_wav_bytes = BYTE_CAP,
        )
    finally:
        tmp.unlink(missing_ok = True)


def save_from_media(
    src: Path,
    name: Optional[str],
    start_s: float = 0.0,
    end_s: Optional[float] = None,
) -> tuple[dict[str, Any], bool]:
    """Register the audio track of a media file (a gallery video), cut to ``[start_s, end_s)``,
    as an input; ``(record, created)``. The same cut again returns the existing record."""
    directory = inputs_dir()
    full = directory / f".{uuid.uuid4().hex}.upload.tmp"
    cut = directory / f".{uuid.uuid4().hex}.upload.tmp"
    try:
        try:
            info = transcode(src, full)
        except AudioInputError as exc:
            if exc.status == 400 and "no audio" in exc.detail:
                raise AudioInputError(400, "This video has no audio track.") from None
            raise
        rate = info["sample_rate"]
        with wave.open(str(full), "rb") as reader:
            total = reader.getnframes()
            channels = reader.getnchannels()
            first = int(start_s * rate)
            if first >= total:
                raise AudioInputError(
                    400,
                    f"start_s is past the end of the audio ({total / rate:.2f} s); "
                    "Unsloth Studio can only cut inside the track.",
                )
            last = total if end_s is None else min(total, max(first + 1, int(end_s * rate)))
            whole = not first and last == total
            if not whole:
                reader.setpos(first)
                with wave.open(str(cut), "wb") as writer:
                    writer.setparams(reader.getparams())
                    writer.writeframes(reader.readframes(last - first))
        if whole:
            os.replace(full, cut)
        digest = hashlib.sha256()
        with open(cut, "rb") as f:
            for chunk in iter(lambda: f.read(1 << 20), b""):
                digest.update(chunk)
        # transcode() wrote this WAV, so transcoding it again would only rewrite the same bytes.
        prepared = {
            "duration_s": round((last - first) / rate, 3),
            "sample_rate": rate,
            "channels": channels,
        }
        return _finish_upload(
            directory,
            cut,
            digest.hexdigest(),
            _clean_name(name),
            os.stat(cut).st_size,
            prepared = prepared,
        )
    finally:
        full.unlink(missing_ok = True)
        cut.unlink(missing_ok = True)


def _find_by_sha(directory: Path, sha: str) -> Optional[tuple[str, dict[str, Any]]]:
    now = _now()
    for sidecar in directory.glob("*.json"):
        meta = _read_sidecar(sidecar)
        if meta is None or meta.get("sha256") != sha or _expired(meta, now):
            continue
        if (directory / f"{sidecar.stem}.wav").is_file():
            return sidecar.stem, meta
    return None


def _finish_upload(
    directory: Path,
    tmp: Path,
    sha: str,
    name: str,
    size: int,
    *,
    prepared: Optional[dict[str, Any]] = None,
    max_seconds: Optional[float] = None,
    max_wav_bytes: Optional[int] = None,
) -> tuple[dict[str, Any], bool]:
    """``prepared``: ``tmp`` is already a ``transcode`` output with this info, so it is moved in
    as is; otherwise it is transcoded under ``max_seconds`` and ``max_wav_bytes``."""
    existing = _find_by_sha(directory, sha)
    if existing is not None:
        input_id, meta = existing
        meta["touched_at"] = _now()
        _write_json(_sidecar(directory, input_id), meta)
        return _record(input_id, meta), False
    input_id = uuid.uuid4().hex
    wav = directory / f"{input_id}.wav"
    try:
        if prepared is None:
            info = transcode(tmp, wav, max_seconds = max_seconds, max_bytes = max_wav_bytes)
        else:
            os.replace(tmp, wav)
            info = prepared
        now = _now()
        meta = {
            "name": name,
            **info,
            "sha256": sha,
            "bytes": size,
            "created_at": _iso(now),
            "created_at_epoch": now,
            "touched_at": now,
        }
        # The sidecar is the record's commit marker, so it lands last.
        _write_json(_sidecar(directory, input_id), meta)
    except BaseException:
        wav.unlink(missing_ok = True)
        raise
    sweep(keep = input_id)
    return _record(input_id, meta), True


def _has_inputs() -> bool:
    """Whether the acting account has an inputs folder, checked without creating one."""
    if is_owner_context():
        return (audio_gallery.gallery_dir() / "inputs").is_dir()
    return (account_path("audio") / "inputs").is_dir()


def sweep_all_accounts() -> int:
    """Sweeps owner and every account with inputs, else expired inputs wait until next upload."""
    from auth.storage import list_accounts

    accounts = [OWNER] + [
        AccountContext(row["account_id"], row["username"], row["role"])
        for row in list_accounts()
        if row["account_id"] != OWNER.account_id and row["role"] != OWNER.role
    ]
    removed = 0
    for account in accounts:
        try:
            removed += run_as(account, lambda: sweep() if _has_inputs() else 0)
        except Exception as exc:  # noqa: BLE001 - housekeeping never fails the server
            logger.debug("audio input sweep skipped for an account: %s", exc)
    return removed


def start_sweeper(interval_seconds: float = 3600.0) -> None:
    """Sweep every account at startup and then hourly, on a daemon thread."""

    def loop() -> None:
        while True:
            try:
                sweep_all_accounts()
            except Exception as exc:  # noqa: BLE001 - e.g. the auth database is not ready yet
                logger.debug("audio input sweep failed: %s", exc)
            time.sleep(interval_seconds)

    threading.Thread(target = loop, daemon = True, name = "audio-inputs-sweep").start()


def _derived(directory: Path, stem: str) -> list[Path]:
    """Prepared copies made from one input (``{id}.24000.mono....wav``)."""
    try:
        return [p for p in directory.glob(f"{stem}.*.wav") if p.name != f"{stem}.wav"]
    except OSError:
        return []


def _derived_index(directory: Path) -> Optional[dict[str, list[Path]]]:
    """``_derived`` for every id from one listing (an id has no dot); None where pathlib's case folding cannot be matched exactly."""
    fold = os.path.normcase
    insensitive = fold("A") != "A"
    try:
        names = os.listdir(directory)
    except OSError:
        return None
    index: dict[str, list[Path]] = {}
    for name in names:
        if insensitive and not name.isascii():
            return None
        folded = fold(name)
        key, dot, _rest = folded.partition(".")
        if dot and folded.endswith(".wav") and len(folded) >= len(key) + 5:
            index.setdefault(key, []).append(directory / name)
    return index


def _derived_from(index: Optional[dict[str, list[Path]]], directory: Path, stem: str) -> list[Path]:
    if index is None or not _valid_id(stem):
        return _derived(directory, stem)
    return index.get(os.path.normcase(stem), [])


def _remove(directory: Path, input_id: str) -> bool:
    wav = directory / f"{input_id}.wav"
    existed = wav.is_file()
    for path in (wav, *_derived(directory, input_id)):
        try:
            path.unlink(missing_ok = True)
        except OSError as exc:
            logger.warning("audio_inputs.delete_failed: %s", exc)
    try:
        _sidecar(directory, input_id).unlink(missing_ok = True)
    except OSError:
        pass
    return existed


def _size(path: Path) -> int:
    try:
        return path.stat().st_size
    except OSError:
        return 0


def _mtime(path: Path) -> float:
    try:
        return path.stat().st_mtime
    except OSError:
        return 0.0


def sweep(
    *,
    keep: Optional[str] = None,
    ttl: Optional[float] = None,
    byte_cap: Optional[int] = None,
) -> int:
    """Best-effort: removes expired inputs and the oldest over the byte cap, never the one just saved."""
    ttl = TTL_SECONDS if ttl is None else ttl
    byte_cap = BYTE_CAP if byte_cap is None else byte_cap
    try:
        directory = inputs_dir()
        now = _now()
        removed = 0
        live: list[tuple[float, str, int]] = []
        derived = _derived_index(directory)
        for sidecar in directory.glob("*.json"):
            input_id = sidecar.stem
            meta = _read_sidecar(sidecar)
            if meta is None:
                continue
            if input_id != keep and _touched(meta) + ttl <= now:
                removed += _remove(directory, input_id)
                continue
            size = _size(directory / f"{input_id}.wav") + sum(
                _size(p) for p in _derived_from(derived, directory, input_id)
            )
            live.append((_touched(meta), input_id, size))
        live.sort(reverse = True)
        running = 0
        for index, (_touched_at, input_id, size) in enumerate(live):
            # Only kept inputs count toward the cap, so one eviction does not doom every older one.
            if running + size > byte_cap and index > 0 and input_id != keep:
                removed += _remove(directory, input_id)
                continue
            running += size
        for path in directory.iterdir():
            name = path.name
            age = now - _mtime(path)
            if name.startswith(".") and name.endswith(".tmp") and age > _STALE_TMP_SECONDS:
                path.unlink(missing_ok = True)
            # "." = a crashed timed transcription's upload; full TTL (aligner downloads take an hour).
            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)
        return 0


def input_path(input_id: str) -> Optional[Path]:
    """The canonical WAV of a live input in this account, else None."""
    if not _valid_id(input_id):
        return None
    directory = inputs_dir()
    meta = _read_sidecar(_sidecar(directory, input_id))
    if meta is None or _expired(meta):
        return None
    path = directory / f"{input_id}.wav"
    try:
        path.resolve().relative_to(directory.resolve())
    except (OSError, ValueError):
        return None
    return path if path.is_file() else None


def delete(input_id: str) -> bool:
    if not _valid_id(input_id):
        return False
    directory = inputs_dir()
    if _read_sidecar(_sidecar(directory, input_id)) is None:
        return False
    return _remove(directory, input_id)


@dataclass(frozen = True)
class Source:
    kind: str  # "input" | "clip" | "voice"
    id: str
    path: Path
    name: str


def resolve_source(ref: dict[str, Any]) -> Source:
    """The canonical file behind ``{"input_id"|"clip_id"|"voice_id": id}`` in this account.

    404 for an id that is unknown, expired, unsafe or another account's."""
    kinds = [k for k in ("input_id", "clip_id", "voice_id") if ref.get(k)]
    if len(kinds) != 1:
        raise AudioInputError(400, "Name exactly one of input_id, clip_id or voice_id.")
    key = kinds[0]
    source_id = str(ref[key])
    if key == "input_id":
        path = input_path(source_id)
        if path is None:
            raise AudioInputError(404, "This reference expired. Add it again.")
        meta = _read_sidecar(_sidecar(path.parent, source_id)) or {}
        return Source("input", source_id, path, meta.get("name") or "audio")
    if key == "clip_id":
        path = audio_gallery.owned_audio_path(source_id) if _valid_id(source_id) else None
        if path is None:
            raise AudioInputError(404, "That clip is no longer in your history.")
        meta = audio_gallery._read_meta(audio_gallery._sidecar_path(source_id, path.parent)) or {}
        prompt = " ".join(str(meta.get("prompt") or "").split())
        return Source("clip", source_id, path, (prompt[:60] or "Clip"))
    from core.inference import audio_voices

    path = audio_voices.voice_path(source_id)
    if path is None:
        raise AudioInputError(404, "That saved voice no longer exists.")
    voice = audio_voices.get(source_id) or {}
    return Source("voice", source_id, path, str(voice.get("name") or "Saved voice"))


def prepared_path(
    source: Source,
    rate: int,
    max_seconds: Optional[float] = None,
    stereo: bool = False,
) -> Path:
    """Input copies go with their input; clip and voice copies (c-/v- files) are swept after the TTL."""
    prefix = {"input": "", "clip": "c-", "voice": "v-"}[source.kind]
    cap = f".m{max_seconds:g}" if max_seconds is not None else ""
    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 = 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)
    return source, prepared_path(source, REFERENCE_RATE, REFERENCE_MAX_SECONDS)