{"record":{"id":"59e666dd0b6e592e","repo":"roboflow/supervision","slug":"pyav-fallback-supports-file-paths-not-webcam-devi","errorCode":null,"errorMessage":"PyAV fallback supports file paths, not webcam device indexes.","messagePattern":"PyAV fallback supports file paths, not webcam device indexes\\.","errorType":"exception","errorClass":"BackendUnavailableError","httpStatus":null,"severity":"error","filePath":"src/supervision/_cv2/_video.py","lineNumber":75,"sourceCode":"\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):\n                raise BackendUnavailableError(\n                    \"PyAV fallback supports file paths, not webcam device indexes.\"\n                )\n            self._container = av.open(str(source), mode=\"r\")\n            if not self._container.streams.video:\n                raise ValueError(f\"Video source has no video stream: {source}\")\n            self._stream = self._container.streams.video[0]\n            self._frames = iter(self._container.decode(video=self._stream.index))\n            self._opened = True\n        except Exception as exc:\n            self._error = exc\n            logger.warning(\"Failed to open video source %r: %s\", source, exc)\n            self.release()\n\n    def isOpened(self) -> bool:\n        \"\"\"Return whether the underlying video file is open for reading.\"\"\"\n        return self._opened\n\n    def _frame_count(self) -> int:","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/_cv2/_video.py#L57-L93","documentation":"BackendUnavailableError raised by the PyAV VideoCapture fallback when the source is an integer device index. PyAV can only demux files/URLs; it has no V4L2/DSHOW camera access, so webcam indices are rejected explicitly instead of hanging or failing obscurely.","triggerScenarios":"cv2.VideoCapture(0) or any integer device index in an environment where opencv-python is missing and Supervision substitutes its PyAV capture.","commonSituations":"Running webcam demos in slim Docker containers or CI where opencv-python was removed to shrink the image; PyAV is present (or installed as Supervision's media fallback) but no camera backend exists.","solutions":["Install opencv-python (headless is insufficient for webcams on some platforms; use opencv-python plus v4l2 on Linux) to get real capture backends.","If you only need file/HTTP video, pass a path or URL string instead of an index.","Gate webcam features: detect the fallback via try-import cv2 and disable camera input in that environment."],"exampleFix":"# before\ncap = cv2.VideoCapture(0)  # webcam — fails on PyAV fallback\n\n# after\n# environment fix\npip install opencv-python\ncap = cv2.VideoCapture(0)","handlingStrategy":"validation","validationCode":"def open_source(source):\n    if isinstance(source, int):\n        try:\n            import cv2  # noqa: F401\n        except ImportError:\n            raise RuntimeError('webcam requires opencv-python; PyAV fallback supports files only')\n    return cv2.VideoCapture(source)","typeGuard":null,"tryCatchPattern":"try:\n    cap = cv2.VideoCapture(source)\nexcept Exception as e:\n    if 'webcam device indexes' in str(e):\n        raise RuntimeError('install opencv-python for webcam support') from e\n    raise","preventionTips":["Install opencv-python in any environment that needs cameras","Pass file paths/URLs, not device indexes, in cv2-free environments","Feature-detect webcam support before exposing camera UI"],"tags":["opencv-fallback","pyav","webcam","backend-unavailable","environment"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}