unslothai/unsloth · error · ValueError

That reference audio decoded to no samples.

Error message

That reference audio decoded to no samples.

What it means

After _decode_audio_stream returns, decode_h3_reference_audio raises ValueError when the decoded waveform is None — the audio track existed (streams.audio was non-empty) but decoding produced no samples. _decode_audio_stream returns (None, None) when its chunk list is empty, which happens with headers-only audio streams or fully unparseable payloads.

Source

Thrown at studio/backend/core/inference/video_minimax_h3.py:447

    with av.open(io.BytesIO(blob)) as container:
        if container.streams.audio:
            waveform, sample_rate = _decode_audio_stream(container, np)
    return frames, waveform, sample_rate


def decode_h3_reference_audio(blob: bytes) -> tuple[Any, int]:
    """Decode one uploaded audio file to a float32 ``(samples, channels)`` waveform + its rate."""
    import io

    import av
    import numpy as np

    with av.open(io.BytesIO(blob)) as container:
        if not container.streams.audio:
            raise ValueError("That reference file carries no audio track.")
        waveform, sample_rate = _decode_audio_stream(container, np)
    if waveform is None:
        raise ValueError("That reference audio decoded to no samples.")
    return waveform, sample_rate


def _decode_audio_stream(container: Any, np: Any) -> tuple[Optional[Any], Optional[int]]:
    """The container's first audio stream as float32 ``(samples, channels)`` at its own rate.

    Bounded while decoding, for the reason the video path above is: the encoded size says almost
    nothing about the decoded size. A 32 MiB request-limit MP3 is over half an hour of audio, which
    expands to ~1.9 GB of float32 here and doubles again in ``np.concatenate``, and three
    references are accepted per request. H3's reference window is
    ``H3_REF_VIDEO_MAX_SECONDS`` anyway, so anything past it is unusable rather than merely large:
    refuse it with the same message the video guard uses instead of decoding it first."""
    import av

    stream = container.streams.audio[0]
    sample_rate = int(stream.codec_context.sample_rate or 48_000)
    # One resampler pass gives interleaved float32 whatever the source layout/format was.
    resampler = av.AudioResampler(format = "flt", layout = stream.layout.name, rate = sample_rate)

View on GitHub (pinned to 203007d190)

Solutions

  1. Re-export the audio to a standard format: ffmpeg -i in.m4a -c:a libmp3lame ref.mp3 (fails loudly if truly dead).
  2. Verify decodability first: ffmpeg -v error -i ref.mp3 -f null -.
  3. Re-upload from the original source file rather than a partial transfer.

Example fix

# before: truncated upload -> ValueError('decoded to no samples')

# after: validate before upload
import subprocess
ok = subprocess.run(["ffmpeg", "-v", "error", "-i", "ref.mp3", "-f", "null", "-"]).returncode == 0
if not ok:
    raise ValueError("audio file is not decodable; re-export it")
Defensive patterns

Strategy: validation

Validate before calling

import av, io

def audio_yields_samples(blob: bytes) -> bool:
    with av.open(io.BytesIO(blob)) as c:
        if not c.streams.audio:
            return False
        return next(iter(c.decode(audio=0)), None) is not None

Try / catch

try:
    wf, sr = decode_h3_reference_audio(blob)
except ValueError as e:
    if str(e) == "That reference audio decoded to no samples.":
        return HTTPException(400, "audio track is empty; re-export the file") from e
    raise

Prevention

When it happens

Trigger: An audio stream with zero decodable packets (interrupted write, truncated upload); codec the PyAV build cannot decode so every packet fails; container with an audio track header but no data.

Common situations: Truncated uploads from dropped connections; re-muxed files with dead audio tracks; exotic codecs in user uploads.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/ace1924374bd816b. Report an issue: GitHub.