Hi @Ashp116 👋🏻 Another great idea! Video processing is probably the oldest part of supervision, written over two years ago, and I’ve been wanting to update its API for a while. Would you be open to not only adding audio support but also helping me with the update?

Hi @SkalskiP, yea, I would like to help update the API. I was thinking of changing how videos are written in process_video. The original compression is lost when annotations are added and the file is written to a target_path. But yea, I would like to help out with the update.

Hi @Ashp116 I'm really glad you want to help me! Let's goooo! 🔥 🔥 🔥

I want the functionalities currently found in supervision.utils.video to be reorganized around a new Video class. Importantly, all features previously available in the old API must still be supported in the new one. Ideally, the new API should be more consistent and expressive.

• get video info (works for files, RTSP, webcams)

  import supervision as sv
   
  # static video
  sv.Video("source.mp4").info
  
  # video stream
  sv.Video("rtsp://...").info
  
  # webcam
  sv.Video(0).info

• simple frame iteration (object is iterable)

  import supervision as sv
  
  video = sv.Video("source.mp4")
  for frame in video:
      ...

• advanced frame iteration (stride, sub-clip, on-the-fly resize)

  import supervision as sv
  
  for frame in sv.Video("source.mp4").frames(stride=5, start=100, end=500, resolution_wh=(1280, 720)):
      ...

• process the video

  import cv2
  import supervision as sv
  
  def blur(frame, i):
      return cv2.GaussianBlur(frame, (11, 11), 0)
  
  sv.Video("source.mp4").save(
      "blurred.mp4",
      callback=blur,
      show_progress=True
  )

• overwrite target video parameters

  import supervision as sv
  
  sv.Video("source.mp4").save(
      "timelapse.mp4",
      fps=60,
      callback=lambda f, i: f,
      show_progress=True
  )

• complete manual control with explicit VideoInfo

  from supervision import Video, VideoInfo
  
  source = Video("source.mp4")
  target_info = VideoInfo(width=800, height=800, fps=24)
  
  with src.sink("square.mp4", info=target_info) as sink:
      for f in src.frames():
          f = cv2.resize(f, target_info.resolution_wh)
          sink.write(f)

• multi-backend support decode/encode

  import supervision as sv
  
  video = sv.Video("source.mkv", backend="pyav")
  
  video = sv.Video("source.mkv", backend="opencv")

  suggested minimal protocol

  class Backend(Protocol):
      def open(self, path: str) -> Any: ...
      def info(self, handle: Any) -> VideoInfo: ...
  
      def read(self, handle: Any) -> tuple[bool, np.ndarray]: ...
      def grab(self, handle: Any) -> bool: ...
      def seek(self, handle: Any, frame_idx: int) -> None: ...
  
      def writer(self, path: str, info: VideoInfo, codec: str) -> Writer: ...
  
  class Writer(Protocol):
      def write(self, frame: np.ndarray) -> None: ...
      def close(self) -> None: ...

Hi @SkalskiP,

I’ve addressed most of the features you mentioned, but I have some thoughts on a few aspects of the implementation:

• .save Functionality
  How would you handle .save for a video feed coming from a webcam or an RTSP stream? Currently, I have it where only video files can be saved.

• Writer and Backend Classes
  This is just my personal opinion, but should these classes be moved to separate scripts/modules? If we add more writers and backends in the future, keeping everything inside the main video script might become cluttered.

• “Complete manual control with explicit VideoInfo” Functionality

  from supervision import Video, VideoInfo
  
  source = Video("source.mp4")
  target_info = VideoInfo(width=800, height=800, fps=24)
  
  with src.sink("square.mp4", info=target_info) as sink:
      for f in src.frames():
          f = cv2.resize(f, target_info.resolution_wh)
          sink.write(f)

  I’m not fully clear on what this feature is intended to do. In this snippet, the Video instance source is created but never used afterward. Is src supposed to be source? Also, is the goal to create sinks for each backend? Could you please clarify the purpose and expected usage here?