feat(video): require PyAV during cv2 transition (roboflow#2438)

- Add the PyAV-backed file-video and audio fallback to the compatibility layer.
- Declare PyAV alongside OpenCV until the final dependency-removal integration.
- _VideoWriter now rejects is_color=False (NotImplementedError) instead of
  silently dropping it, since the PyAV fallback only encodes 3-channel frames.
- _mux_audio cleanup (container closes, temp-file removal) is now best-effort
  so a failing close/remove in finally can no longer mask the primary result
  or the original exception.
- The subprocess used to validate the cv2-free fallback had no timeout;
  a hang (import deadlock, codec probe stall) could block the whole CI
  run. Added a 60s timeout so a hang fails fast with a clear traceback
  instead of an opaque suite-wide stall.
- process_video(preserve_audio=True) docstring still described the old
  ffmpeg-based muxing; audio remuxing was reimplemented with PyAV and no
  longer requires an external ffmpeg executable.
- get_video_frames_generator's documented webcam fallback
  (`_cv2.VideoCapture(0)`) silently fails under the PyAV backend: the
  BackendUnavailableError raised for integer sources was swallowed with no
  logging, so isOpened() just returns False with zero diagnostic signal.
  Doc note now states the limitation explicitly and the capture logs a
  warning instead of failing silently.

---------

Co-authored-by: Codex <codex@openai.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

Author: 4 people

docs/changelog.md

@@ -1,6 +1,6 @@
 ---
 description: "Full version history of the supervision Python library — release notes, breaking changes, new features, and deprecations for every version."
-date_modified: 2026-07-15
+date_modified: 2026-07-16
 ---
 
 # Changelog
@@ -48,6 +48,11 @@ date_modified: 2026-07-15
 - Fixed: dataset IO/export edge cases now avoid mutating caller-owned `Detections` during `DetectionDataset` construction, reject non-integer and out-of-range class ids with a clear `ValueError`, load COCO annotations that omit optional `iscrowd`/`area` fields, expose `DetectionDataset.from_coco(use_iscrowd=...)` without changing the existing positional `show_progress` argument, export mask pixel area to COCO when no stored area is present, ignore folder-structure root clutter and non-image files inside class folders, and accept PIL-readable YOLO images such as RGBA or palette PNGs.
 
 ### Added
+- Added a cv2-free PyAV fallback for file-video capture, writing, frame seeking,
+  metadata, and `process_video(preserve_audio=True)` audio remuxing. OpenCV remains
+  the primary backend when available; `av>=14.2.0` is now required alongside
+  OpenCV during the transition, with the later OpenCV-removal integration removing
+  the OpenCV dependency.
 - Added a cv2-free Hershey text fallback covering all eight OpenCV font faces,
   italic variants, exact text metrics, and packaged glyph provenance. OpenCV
   remains the primary renderer when available; the fallback uses the private

pyproject.toml

@@ -47,6 +47,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
+  "av>=14.2",
   "defusedxml>=0.7.1",
   "matplotlib>=3.6",
   "numpy>=1.21.2",
@@ -191,8 +192,12 @@ mypy_path = "src"
 explicit_package_bases = true
 ignore_missing_imports = false
 python_version = "3.10"
+warn_unused_ignores = true
 strict = true
-overrides = [ { module = [ "examples.*", "tests.*" ], ignore_errors = true } ]
+overrides = [
+  { module = [ "examples.*", "tests.*" ], ignore_errors = true },
+  { module = [ "supervision._cv2" ], warn_unused_ignores = false },
+]
 
 [tool.pytest]
 ini_options.testpaths = [ "src", "tests" ]

src/supervision/_cv2/__init__.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from supervision._cv2._color import _cvt_color, _merge, _split
-from supervision._cv2._common import BackendUnavailableError, _unavailable
+from supervision._cv2._common import BackendUnavailableError
 from supervision._cv2._components import (
     _connected_components,
     _connected_components_with_stats,
@@ -40,6 +40,11 @@
     _get_rotation_matrix_2d,
     _warp_affine,
 )
+from supervision._cv2._video import (
+    _video_writer_fourcc,
+    _VideoCapture,
+    _VideoWriter,
+)
 from supervision._cv2.constants import (
     _BORDER_CONSTANT,
     _CAP_PROP_FPS,
@@ -82,7 +87,7 @@
     _IS_CV2_AVAILABLE = True
 
 if _IS_CV2_AVAILABLE:
-    from cv2 import (
+    from cv2 import (  # type: ignore[attr-defined]
         BORDER_CONSTANT,
         CAP_PROP_FPS,
         CAP_PROP_FRAME_COUNT,
@@ -116,7 +121,7 @@
         RETR_TREE,
         VideoCapture,
         VideoWriter,
-        VideoWriter_fourcc,
+        VideoWriter_fourcc,  # type: ignore[attr-defined]
         addWeighted,
         approxPolyDP,
         blur,
@@ -185,39 +190,41 @@
     LINE_AA = _LINE_AA
     RETR_TREE = _RETR_TREE
 
-    VideoCapture = _unavailable
-    VideoWriter = _unavailable
-    VideoWriter_fourcc = _unavailable
-    addWeighted = _add_weighted
-    approxPolyDP = _approx_poly_dp
-    blur = _blur
-    circle = _circle
-    connectedComponents = _connected_components
-    connectedComponentsWithStats = _connected_components_with_stats
-    contourArea = _contour_area
-    convertScaleAbs = _convert_scale_abs
-    copyMakeBorder = _copy_make_border
-    cvtColor = _cvt_color
-    distanceTransform = _distance_transform
-    drawContours = _draw_contours
-    ellipse = _ellipse
-    fillPoly = _fill_poly
-    findContours = _find_contours
-    flip = _flip
-    getRotationMatrix2D = _get_rotation_matrix_2d
-    getTextSize = _get_text_size
-    imread = _imread
-    imwrite = _imwrite
-    intersectConvexConvex = _intersect_convex_convex
-    line = _line
-    mean = _mean
-    merge = _merge
-    polylines = _polylines
-    putText = _put_text
-    rectangle = _rectangle
-    resize = _resize
-    split = _split
-    warpAffine = _warp_affine
+    # Fallback implementations when cv2 is not available. Suppress type errors because
+    # fallback types differ from cv2 types, but are functionally equivalent.
+    VideoCapture = _VideoCapture  # type: ignore[assignment,misc]
+    VideoWriter = _VideoWriter  # type: ignore[assignment,misc]
+    VideoWriter_fourcc = _video_writer_fourcc  # type: ignore[assignment]
+    addWeighted = _add_weighted  # type: ignore[assignment]
+    approxPolyDP = _approx_poly_dp  # type: ignore[assignment]
+    blur = _blur  # type: ignore[assignment]
+    circle = _circle  # type: ignore[assignment]
+    connectedComponents = _connected_components  # type: ignore[assignment]
+    connectedComponentsWithStats = _connected_components_with_stats  # type: ignore[assignment]
+    contourArea = _contour_area  # type: ignore[assignment]
+    convertScaleAbs = _convert_scale_abs  # type: ignore[assignment]
+    copyMakeBorder = _copy_make_border  # type: ignore[assignment]
+    cvtColor = _cvt_color  # type: ignore[assignment]
+    distanceTransform = _distance_transform  # type: ignore[assignment]
+    drawContours = _draw_contours  # type: ignore[assignment]
+    ellipse = _ellipse  # type: ignore[assignment]
+    fillPoly = _fill_poly  # type: ignore[assignment]
+    findContours = _find_contours  # type: ignore[assignment]
+    flip = _flip  # type: ignore[assignment]
+    getRotationMatrix2D = _get_rotation_matrix_2d  # type: ignore[assignment]
+    getTextSize = _get_text_size  # type: ignore[assignment]
+    imread = _imread  # type: ignore[assignment]
+    imwrite = _imwrite  # type: ignore[assignment]
+    intersectConvexConvex = _intersect_convex_convex  # type: ignore[assignment]
+    line = _line  # type: ignore[assignment]
+    mean = _mean  # type: ignore[assignment]
+    merge = _merge  # type: ignore[assignment]
+    polylines = _polylines  # type: ignore[assignment]
+    putText = _put_text  # type: ignore[assignment]
+    rectangle = _rectangle  # type: ignore[assignment]
+    resize = _resize  # type: ignore[assignment]
+    split = _split  # type: ignore[assignment]
+    warpAffine = _warp_affine  # type: ignore[assignment]
 
 
 __all__ = [