{"record":{"id":"c95922f6cf51846b","repo":"unslothai/unsloth","slug":"speech-to-text-needs-the-pyav-package-to-decode-au","errorCode":null,"errorMessage":"Speech-to-text needs the PyAV package to decode audio. Run `unsloth studio update` to install it.","messagePattern":"Speech-to-text needs the PyAV package to decode audio\\. Run `unsloth studio update` to install it\\.","errorType":"http","errorClass":"SttUnavailableError","httpStatus":501,"severity":"error","filePath":"studio/backend/core/inference/stt_sidecar.py","lineNumber":1076,"sourceCode":"\n\ndef _decode_audio_bounded(audio: bytes, cancel_event = None):\n    \"\"\"Decode to 16 kHz mono PCM without buffering unbounded audio.\n\n    A small, highly-compressed upload can expand far past the encoded request\n    limit once decoded, so decode frame-by-frame and enforce the sample cap as\n    frames arrive, then hand the array straight to Whisper.\n\n    ``cancel_event`` is polled inside the frame loop: checking only after the decode\n    returned let an abandoned upload run to EOF or the sample cap, and several of them\n    could do that at once.\n    \"\"\"\n    try:\n        import av\n        import numpy as np\n        from av.error import FFmpegError, InvalidDataError\n    except ImportError as exc:\n        raise SttUnavailableError(\n            \"Speech-to-text needs the PyAV package to decode audio. \"\n            \"Run `unsloth studio update` to install it.\"\n        ) from exc\n\n    max_samples = _MAX_AUDIO_SECONDS * _TARGET_SAMPLE_RATE\n    sample_count = 0\n    raw_buffer = io.BytesIO()\n    resampler = av.audio.resampler.AudioResampler(\n        format = \"s16\",\n        layout = \"mono\",\n        rate = _TARGET_SAMPLE_RATE,\n    )\n    # Group frames before resampling so short clips need one resampler call\n    # rather than one per codec frame.\n    fifo = av.audio.fifo.AudioFifo()\n\n    def write_frame(frame) -> None:\n        nonlocal sample_count","sourceCodeStart":1058,"sourceCodeEnd":1094,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/stt_sidecar.py#L1058-L1094","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before: transcribe() raises SttUnavailableError on bare env\n# after\ntry:\n    result = stt.transcribe(audio)\nexcept SttUnavailableError:\n    subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"av\", \"numpy\"])\n    result = stt.transcribe(audio)","handlingStrategy":"validation","validationCode":"def stt_runtime_ok() -> bool:\n    try:\n        import av, numpy  # noqa\n        from av.error import FFmpegError  # noqa\n        return True\n    except ImportError:\n        return False\n\nif not stt_runtime_ok():\n    run_install(\"unsloth studio update\")","typeGuard":null,"tryCatchPattern":"try:\n    stt.transcribe(audio)\nexcept SttUnavailableError:\n    prompt_user_to_run_update()  # or auto-run installer once, then retry once","preventionTips":["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"],"tags":["stt","dependency","pyav","ffmpeg","import"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}