unslothai/unsloth · error · RuntimeError

WebM export needs the 'av' package (PyAV).

Error message

WebM export needs the 'av' package (PyAV).

What it means

_transcode_webm imports PyAV lazily and raises this RuntimeError when 'import av' fails, because WebM (VP9/Opus) transcoding is implemented on top of PyAV. The MP4 export path does not need it, so this only fires when the WebM format is requested. The except is broad (noqa BLE001) because any import failure (missing package, broken install, missing native libs) maps to the same user-facing condition.

Source

Thrown at studio/backend/core/inference/video_gallery.py:139

def transcode(video_id: str, fmt: str) -> Optional[bytes]:
    """``transcode_to_file`` read back into memory. Kept for callers that want the bytes; the route
    uses the file form so a large export is never fully resident."""
    dest = transcode_to_file(video_id, fmt)
    if dest is None:
        return None
    try:
        return dest.read_bytes()
    finally:
        dest.unlink(missing_ok = True)


def _transcode_webm(path: Path, dest: Path) -> None:
    """Transcode ``path`` to VP9 (+ Opus when the clip has audio) at ``dest``."""
    try:
        import av
    except Exception as exc:  # noqa: BLE001 -- no PyAV -> no transcode
        raise RuntimeError("WebM export needs the 'av' package (PyAV).") from exc
    try:
        with av.open(str(path)) as src, av.open(str(dest), "w", format = "webm") as dst:
            if not src.streams.video:
                raise RuntimeError("WebM export failed: the clip has no video stream.")
            in_v = src.streams.video[0]
            rate = in_v.average_rate or 24
            out_v = dst.add_stream("libvpx-vp9", rate = rate)
            out_v.width = in_v.codec_context.width
            out_v.height = in_v.codec_context.height
            out_v.pix_fmt = "yuv420p"
            # Realtime settings: VP9's default "good" profile is slow; cpu-used 8 + row-mt is much faster at a small quality cost.
            out_v.options = {"deadline": "realtime", "cpu-used": "8", "row-mt": "1"}
            # An LTX-2 clip carries a synchronized audio track and WebM is the web-embed format, so dropping it would hand back half the
            # result. Opus is WebM's audio codec: resample to its 48 kHz grid and feed whole frames through a FIFO (960 samples per frame).
            in_a = src.streams.audio[0] if src.streams.audio else None
            out_a = fifo = resampler = None
            if in_a is not None:
                try:

View on GitHub (pinned to 203007d190)

Solutions

  1. pip install av (PyAV ships manylinux/macOS wheels bundling ffmpeg).
  2. If the import still fails after install, reinstall to repair the native extension: pip install --force-reinstall av.
  3. Export as MP4 instead, which does not require PyAV.

Example fix

# before: WebM export on a box without PyAV -> RuntimeError
pip install av

# after: WebM export succeeds
Defensive patterns

Strategy: fallback

Validate before calling

def webm_available() -> bool:
    try:
        import av  # noqa: F401
        return True
    except Exception:
        return False

if not webm_available():
    export_format = "mp4"  # does not need PyAV

Try / catch

try:
    data = export_clip(clip, fmt="webm")
except RuntimeError as e:
    if str(e) == "WebM export needs the 'av' package (PyAV).":
        data = export_clip(clip, fmt="mp4")  # MP4 path needs no PyAV
    else:
        raise

Prevention

When it happens

Trigger: Requesting a WebM-format export on an environment where 'av' is not installed or its native ffmpeg shared libraries fail to load; running the backend in a slim container built without the av dependency.

Common situations: Optional-dependency installs (av is not in the core requirements); Docker images that prune pip caches and optional extras; upgrading Python and forgetting to reinstall av wheels.

Related errors

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