{"record":{"id":"cd9106f21c9cccf1","repo":"unslothai/unsloth","slug":"webm-export-needs-the-av-package-pyav","errorCode":null,"errorMessage":"WebM export needs the 'av' package (PyAV).","messagePattern":"WebM export needs the 'av' package \\(PyAV\\)\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":501,"severity":"error","filePath":"studio/backend/core/inference/video_gallery.py","lineNumber":139,"sourceCode":"\ndef transcode(video_id: str, fmt: str) -> Optional[bytes]:\n    \"\"\"``transcode_to_file`` read back into memory. Kept for callers that want the bytes; the route\n    uses the file form so a large export is never fully resident.\"\"\"\n    dest = transcode_to_file(video_id, fmt)\n    if dest is None:\n        return None\n    try:\n        return dest.read_bytes()\n    finally:\n        dest.unlink(missing_ok = True)\n\n\ndef _transcode_webm(path: Path, dest: Path) -> None:\n    \"\"\"Transcode ``path`` to VP9 (+ Opus when the clip has audio) at ``dest``.\"\"\"\n    try:\n        import av\n    except Exception as exc:  # noqa: BLE001 -- no PyAV -> no transcode\n        raise RuntimeError(\"WebM export needs the 'av' package (PyAV).\") from exc\n    try:\n        with av.open(str(path)) as src, av.open(str(dest), \"w\", format = \"webm\") as dst:\n            if not src.streams.video:\n                raise RuntimeError(\"WebM export failed: the clip has no video stream.\")\n            in_v = src.streams.video[0]\n            rate = in_v.average_rate or 24\n            out_v = dst.add_stream(\"libvpx-vp9\", rate = rate)\n            out_v.width = in_v.codec_context.width\n            out_v.height = in_v.codec_context.height\n            out_v.pix_fmt = \"yuv420p\"\n            # Realtime settings: VP9's default \"good\" profile is slow; cpu-used 8 + row-mt is much faster at a small quality cost.\n            out_v.options = {\"deadline\": \"realtime\", \"cpu-used\": \"8\", \"row-mt\": \"1\"}\n            # An LTX-2 clip carries a synchronized audio track and WebM is the web-embed format, so dropping it would hand back half the\n            # result. Opus is WebM's audio codec: resample to its 48 kHz grid and feed whole frames through a FIFO (960 samples per frame).\n            in_a = src.streams.audio[0] if src.streams.audio else None\n            out_a = fifo = resampler = None\n            if in_a is not None:\n                try:","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video_gallery.py#L121-L157","documentation":"_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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["pip install av (PyAV ships manylinux/macOS wheels bundling ffmpeg).","If the import still fails after install, reinstall to repair the native extension: pip install --force-reinstall av.","Export as MP4 instead, which does not require PyAV."],"exampleFix":"# before: WebM export on a box without PyAV -> RuntimeError\npip install av\n\n# after: WebM export succeeds","handlingStrategy":"fallback","validationCode":"def webm_available() -> bool:\n    try:\n        import av  # noqa: F401\n        return True\n    except Exception:\n        return False\n\nif not webm_available():\n    export_format = \"mp4\"  # does not need PyAV","typeGuard":null,"tryCatchPattern":"try:\n    data = export_clip(clip, fmt=\"webm\")\nexcept RuntimeError as e:\n    if str(e) == \"WebM export needs the 'av' package (PyAV).\":\n        data = export_clip(clip, fmt=\"mp4\")  # MP4 path needs no PyAV\n    else:\n        raise","preventionTips":["Add 'av' to deployment requirements if any WebM export is reachable.","Smoke-test `import av` at startup and disable the WebM option when absent.","Keep an MP4 fallback for environments you don't control."],"tags":["video","webm","dependency","pyav"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}