{"record":{"id":"4072081bf2288a91","repo":"roboflow/supervision","slug":"unsupported-video-codec-code","errorCode":null,"errorMessage":"Unsupported video codec: {code}","messagePattern":"Unsupported video codec: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/_cv2/_video.py","lineNumber":56,"sourceCode":"def _video_writer_fourcc(*chars: str) -> int:\n    \"\"\"Encode four single-character strings using OpenCV's integer layout.\"\"\"\n    if len(chars) != 4 or any(len(char) != 1 for char in chars):\n        raise TypeError(\"VideoWriter_fourcc requires exactly four characters\")\n    return sum(ord(char) << (8 * index) for index, char in enumerate(chars))\n\n\ndef _decode_fourcc(fourcc: int) -> str:\n    \"\"\"Decode a fourcc integer into its four-character representation.\"\"\"\n    return \"\".join(chr((fourcc >> (8 * index)) & 0xFF) for index in range(4))\n\n\ndef _codec_details(fourcc: int) -> tuple[str, str]:\n    \"\"\"Return the PyAV codec and pixel format for a supported fourcc.\"\"\"\n    code = _decode_fourcc(fourcc).lower()\n    try:\n        return _CODECS[code]\n    except KeyError as exc:\n        raise ValueError(f\"Unsupported video codec: {code!r}\") from exc\n\n\nclass _VideoCapture:\n    \"\"\"Expose OpenCV-shaped file capture backed by PyAV decoding.\"\"\"\n\n    def __init__(self, source: str | os.PathLike[str] | int) -> None:\n        \"\"\"Open a file source and retain a lazy PyAV frame iterator.\"\"\"\n        self._container: Any = None\n        self._stream: Any = None\n        self._frames: Iterator[Any] | None = None\n        self._source = source\n        self._position = 0\n        self._frame_count_cache: int | None = None\n        self._opened = False\n        self._error: Exception | None = None\n\n        try:\n            if isinstance(source, int):","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/_cv2/_video.py#L38-L74","documentation":"The PyAV-based video writer fallback supports only a fixed codec table: mp4v, xvid, avc1, h264, mjpg, and vp09. _codec_details decodes the fourcc integer back to a string and looks it up; anything else raises ValueError instead of attempting an untested encoder mapping.","triggerScenarios":"Creating a VideoWriter with a fourcc outside the table, e.g. 'WMV1', 'MJPG' variants that decode to unmapped codes, or a corrupted fourcc integer.","commonSituations":"Running in environments without opencv-python where Supervision writes video via PyAV; choosing a codec string from an OpenCV tutorial (e.g. 'DIVX', 'IYUV') that the fallback never mapped.","solutions":["Use one of the supported fourccs: *'mp4v', *'xvid', *'avc1', *'h264', *'mjpg', or *'vp09'.","Install opencv-python so VideoWriter uses real OpenCV backends with broader codec support.","Match the container to the codec (.mp4 for mp4v/avc1/h264, .avi for xvid/mjpg, .webm for vp09)."],"exampleFix":"# before\nfourcc = cv2.VideoWriter_fourcc(*'WMV1')\nwriter = cv2.VideoWriter('out.wmv', fourcc, 30, (w, h))\n\n# after\nfourcc = cv2.VideoWriter_fourcc(*'mp4v')\nwriter = cv2.VideoWriter('out.mp4', fourcc, 30, (w, h))","handlingStrategy":"fallback","validationCode":"SUPPORTED_CODECS = {'mp4v', 'xvid', 'avc1', 'h264', 'mjpg', 'vp09'}\ncodec = codec if codec in SUPPORTED_CODECS else 'mp4v'\nfourcc = cv2.VideoWriter_fourcc(*codec)","typeGuard":null,"tryCatchPattern":"try:\n    writer = cv2.VideoWriter(path, cv2.VideoWriter_fourcc(*codec), fps, size)\n    if not writer.isOpened():\n        writer = cv2.VideoWriter(path, cv2.VideoWriter_fourcc(*'mp4v'), fps, size)\nexcept ValueError:\n    writer = cv2.VideoWriter(path, cv2.VideoWriter_fourcc(*'mp4v'), fps, size)","preventionTips":["Stick to mp4v/xvid/avc1/h264/mjpg/vp09 in cv2-free environments","Match codec to container extension","Install opencv-python for full codec coverage"],"tags":["opencv-fallback","pyav","video-codec","fourcc"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}