unslothai/unsloth · error · SttUnavailableError

Speech-to-text needs the PyAV package to decode audio. Run `

Error message

Speech-to-text needs the PyAV package to decode audio. Run `unsloth studio update` to install it.

What it means

Raised by the audio decode path when the PyAV package (import av) or its numpy/av.error dependencies fail to import. The STT sidecar uses PyAV's FFmpeg bindings to decode wav/mp3/opus/ogg/m4a into 16 kHz mono PCM for Whisper; without PyAV no audio can be processed.

Source

Thrown at studio/backend/core/inference/stt_sidecar.py:1076


def _decode_audio_bounded(audio: bytes, cancel_event = None):
    """Decode to 16 kHz mono PCM without buffering unbounded audio.

    A small, highly-compressed upload can expand far past the encoded request
    limit once decoded, so decode frame-by-frame and enforce the sample cap as
    frames arrive, then hand the array straight to Whisper.

    ``cancel_event`` is polled inside the frame loop: checking only after the decode
    returned let an abandoned upload run to EOF or the sample cap, and several of them
    could do that at once.
    """
    try:
        import av
        import numpy as np
        from av.error import FFmpegError, InvalidDataError
    except ImportError as exc:
        raise SttUnavailableError(
            "Speech-to-text needs the PyAV package to decode audio. "
            "Run `unsloth studio update` to install it."
        ) from exc

    max_samples = _MAX_AUDIO_SECONDS * _TARGET_SAMPLE_RATE
    sample_count = 0
    raw_buffer = io.BytesIO()
    resampler = av.audio.resampler.AudioResampler(
        format = "s16",
        layout = "mono",
        rate = _TARGET_SAMPLE_RATE,
    )
    # Group frames before resampling so short clips need one resampler call
    # rather than one per codec frame.
    fifo = av.audio.fifo.AudioFifo()

    def write_frame(frame) -> None:
        nonlocal sample_count

View on GitHub (pinned to 203007d190)

Solutions

Run `unsloth studio update` as the message says, which installs PyAV and its FFmpeg runtime.
Or install manually: pip install av numpy in the backend's virtualenv.
On Linux, if av import still fails after install, check that FFmpeg shared libraries are present (ldconfig -p | grep ffmpeg) and install the distro ffmpeg package.

Example fix

# before: transcribe() raises SttUnavailableError on bare env
# after
try:
    result = stt.transcribe(audio)
except SttUnavailableError:
    subprocess.run([sys.executable, "-m", "pip", "install", "av", "numpy"])
    result = stt.transcribe(audio)

Defensive patterns

Strategy: validation

Validate before calling

def stt_runtime_ok() -> bool:
    try:
        import av, numpy  # noqa
        from av.error import FFmpegError  # noqa
        return True
    except ImportError:
        return False

if not stt_runtime_ok():
    run_install("unsloth studio update")

Try / catch

try:
    stt.transcribe(audio)
except SttUnavailableError:
    prompt_user_to_run_update()  # or auto-run installer once, then retry once

Prevention

Check `python -c "import av"` as part of deployment smoke tests
Pin av in requirements so env rebuilds never ship without it
Gate STT features in the UI on a runtime availability probe

When it happens

Trigger: Calling transcribe()/the decode helper on an environment where PyAV is not installed, is a broken install (missing FFmpeg shared libs), or where numpy is missing. The try/except around 'import av, numpy, av.error' converts ImportError into SttUnavailableError.

Common situations: Fresh install without running the studio update step; a venv recreated without av; PyAV wheels failing to install on older glibc or unsupported Python versions; CI images that trim optional deps.

Related errors

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