vidgear

abhiTronixApache-2.0活跃维护

跨平台高性能视频处理 Python 库,封装 FFmpeg、OpenCV 等后端,支持多线程实时推流、HLS 直播、摄像头与屏幕捕获。

A High-performance cross-platform Video Processing Python framework powerpacked with unique trailblazing features :fire:

vidgear-0.3.7发布于 2026-11-07 03:20 UTC3,735star +1 / 7 天286fork同步于 2026-11-10 23:40 UTC

怎么上手

由 README 提炼,执行前请确认
pip install vidgear
硬件要求按 README 说明

README 未说明具体显存或 CPU 要求;FFGear 支持 CUDA、CUVID 等 GPU 硬件加速解码,其余功能依赖 OpenCV、FFmpeg 等后端库。

支持 Apple Silicon需要 CUDA
下载:源码 zip·GitHub Releases(安装包)本站不镜像安装包

项目说明

由 README 自动翻译提炼

跨平台高性能视频处理 Python 框架,用几行代码完成实时读写、处理和网络传输

跨平台高性能视频处理 Python 库,封装 FFmpeg、OpenCV 等后端,支持多线程实时推流、HLS 直播、摄像头与屏幕捕获。

核心能力

  • 基于 OpenCV、FFmpeg、ZeroMQ 等库封装多线程与 Asyncio API
  • CamGear 支持 IP、USB 摄像头、RTSP 等网络流及 YouTube 等直播站点
  • FFGear 通过 FFmpeg 子进程实现 CUDA、CUVID 硬件加速解码与滤镜图
  • WriteGear 无损编码写文件,StreamGear 转码自适应流媒体格式
  • WebGear、NetGear 分别提供 ASGI 视频服务与跨机帧数据传输

容易踩的坑

FFGear 依赖 DeFFcode 与 FFmpeg,需另行安装对应后端;CamGear 拉取 YouTube 等直播站点依赖 yt_dlp 后端;PiGear 仅面向树莓派摄像头模块。

内容由模型根据 README 生成,可能不完整或不准确,以官方文档为准。看原文 README

最近发版

5 个版本vidgear-0.3.7
  1. vidgear-0.3.7VidGear Stable v0.3.7最新正式版2026-11-07 · 2026-11-07 03:20 UTC

    What's Changed (Highlights)

    📓 Release Notes can be found here ↗️

    New Features ✨

    • ⚡️ WebGear Low-Latency H.264 Streaming:
      • Added streaming_mode parameter ("mjpeg" default / "h264") and h264_options attribute, streaming FFmpeg-encoded H.264 Annex-B access units over WebSockets with automatic MJPEG fallback.
      • Delivers up to ~9x to ~38x bandwidth reduction compared to MJPEG at 1080p30 with ~50ms localhost latency.
    • 💄 Modernized Default Theme v0.2.0 (WebGear & WebGear_RTC):
      • Added off-thread WebCodecs VideoDecoder worker, <canvas> renderer, and live telemetry HUD (codec, resolution, FPS, bitrate/bandwidth, decode latency).
      • WebGear_RTC theme features real-time WebRTC getStats() performance overlay, auto-reconnect with backoff, and zero external dependencies.
    • 🌐 WebGear_RTC Enhancements:
      • Added codec attribute ("VP8" / "H264") to force negotiated video codecs and ice_servers attribute for custom STUN/TURN configurations.
      • Added per-peer connection management via unique peer IDs on /offer and /close_connection.
    • 🏗️ Unified FFmpeg Execution (helper.run_ffmpeg):
      • Added a shared execution primitive handling exit codes, bounded stderr_tail capture, timeouts, cancellation, and progress across WriteGear and StreamGear.
    • 🚩 Gear APIs & Stabilizer Updates:
      • WriteGear & StreamGear: Added -capture_stderr, stderr_tail property, return codes, and clean cancellation timeouts on close().
      • FFGear: Added timeout handling to read(), framerate attribute, and upgraded dependency to deffcode>=0.2.9 for multi-output pipelines.
      • Stabilizer: Added flush() (exposed via STABILIZER_FLUSH in VideoGear) to drain buffered ASW frames at end of stream, alongside single-channel grayscale frame support.

    Updates/Improvements ⚡️

    • WebGear & WebGear_RTC Pipeline: Shared raw-frame pipelines between modes, offloaded source frame reads from the asyncio event loop with aiortc MediaRelay, and added automated asset downloads for WebCodecs worker scripts.
    • ScreenGear: Migrated to the modern mss.MSS class interface.
    • Dependencies: Raised minimum version requirements for yt-dlp>=2026.10.26, deffcode>=0.2.9, starlette>=1.10.0, and msgpack>=1.2.4.
    • Testing: Migrated asyncio tests to pytest-asyncio loop_scope fixtures and added Playwright CI integration suites covering WebGear H.264 WebSockets and WebGear_RTC loopback streams.

    Breaking Updates/Changes 💥

    • 💣 Removed Asyncio Terminal CLI: Removed the legacy python -m vidgear.gears.asyncio terminal CLI; WebGear and WebGear_RTC should be run programmatically via Uvicorn.
    • 💣 WebGear_RTC API Contracts:
      • /offer strictly requires POST and returns 400 on invalid offers or 503 after stream shutdown.
      • /close_connection no longer supports blanket boolean payloads; requires JSON payload {"id": "<peer id>"}.
      • Removed RTC_VideoServer.reset().
      • Default theme no longer bundles fallback STUN servers by default; explicit configuration via ice_servers is required.

    Bug-fixes 🐛

    • WebGear_RTC: Fixed frame splitting across multiple peers when broadcast mode was disabled, resolved black screen issues on odd frame dimensions with H.264, and eliminated peer-connection leaks.
    • FFGear: Resolved deadlock during stop() on stalled sources and eliminated 100% CPU thread busy-spin at stream completion in Threaded Queue Mode.
    • StreamGear: Fixed Single-Source Mode progress bar rendering on \r-terminated FFmpeg output, and fixed -extra_window_size configuration mapping.
    • NetGear: Isolated ZMQ contexts per instance to ensure close(kill=True) does not terminate adjacent NetGear instances within the same process.
    • VideoGear: Guarded against crashes during stabilize=True combined with `-extract_me
  2. vidgear-0.3.6VidGear Stable v0.3.62026-10-26 · 2026-10-26 04:28 UTC
    查看更新说明

    What's Changed (Highlights)

    📓 Release Notes can be found here ↗️

    New Features ✨

    • ✨ Zero-Latency Kalman Stabilizer:
      • Added KalmanStabilizer backend, selectable via StabilizerMode.KALMAN, that smooths the camera trajectory online with a vectorized Kalman filter and stabilizes every frame immediately (no frame buffering), ideal for live streams.
      • Added process_noise and measurement_noise tuning parameters, exposed in VideoGear (and gears wrapping it) as PROCESS_NOISE and MEASUREMENT_NOISE options.
      • Noise parameters are validated at initialization, raising ValueError unless a finite positive scalar or a 3-element [x, y, a] sequence is given.
    • ⬆️ Python 3.14 Support:
      • Added official support for Python 3.14 across package classifiers and all CI pipelines (test matrix now covers Python 3.11–3.14).

    Updates/Improvements ⚡️

    • Stabilizer: Moved shared feature tracking and motion estimation into _StabilizerBase for reuse across all backends.
    • Dependencies:
      • Raised minimum versions of core and asyncio dependencies: yt-dlp>=2026.8.19, pyzmq>=27.2.0, Pillow>=13.0.0, deffcode>=0.2.8, dxcam>=0.3.0, starlette>=1.8.0, jinja2>=3.1.6, msgpack>=1.2.3, aiortc>=1.15.0, uvicorn>=0.54.0, and uvloop>=0.23.0.
      • Previously unpinned Pillow and jinja2 now have lower bounds.
    • Packaging:
      • Added poetry.lock to the repository and a static [tool.poetry] version to pyproject.toml, since Poetry can't read setuptools' dynamic version.
      • Enforced LF line endings project-wide via .gitattributes (* text=auto eol=lf) and renormalized existing CRLF files.
    • Typing: Replaced the TypeVar self-bound workaround with typing.Self for fluent start()/launch() return types in CamGear, VideoGear, ScreenGear, PiGear, and NetGear_Async.
    • Tests:
      • Added Kalman stabilizer tests, including a jitter-reduction check on synthetic shaky footage, noise parameter validation, and featureless frames.
      • Switched from httpx to httpx2 for Starlette TestClient (Starlette 1.8+ deprecates the httpx fallback).
      • Replaced asyncio.TimeoutError with builtin TimeoutError.
    • Docs Engine Migration (MkDocs → Zensical):
      • Migrated documentation builds from MkDocs + Material for MkDocs to Zensical, reusing the existing mkdocs.yml configuration.
      • Switched emoji extension namespace from material.extensions.emoji to zensical.extensions.emoji and dropped the unsupported git-revision-date-localized plugin.
      • Moved static assets from docs/overrides/assets to docs/assets, since Zensical only reads templates from custom_dir.
      • Updated docs deployment CI to install zensical, mkdocstrings-python, and the Zensical-compatible mike fork, replacing all MkDocs dependencies.
      • Switched archived Clappr plugin repos (dash-shaka-playback, clappr-level-selector-plugin) to their Clappr monorepo npm packages (dash-shaka-playback, @clappr/level-selector) with shaka-player loaded as a peer, and pinned all CDN script versions in mkdocs.yml instead of @latest.
      • Adapted relative links and images on all non-index pages to Zensical's source-file-based path resolution.

    Breaking Updates/Changes 💥

    • 💣 Dropped Python 3.10 Support:
      • Python 3.10 has reached end-of-life; VidGear now requires Python 3.11 or newer (requires-python = ">=3.11").

    Bug-fixes 🐛

    • Stabilizer:
      • Fixed stabilize() crashing with an uncaught TypeError on an empty keypoint array, and logging a misleading "too dark" warning when no keypoints were found; both cases now short-circuit to zero motion before optical flow.
    • Docs Video Demos:
      • Fixed broken StreamGear HLS and Stabilizer DASH demo players caused by @clappr/hlsjs-playback v3 requiri
  3. vidgear-0.3.5VidGear Stable v0.3.52026-05-17 · 2026-05-17 18:57 UTC
    查看更新说明

    What's Changed (Highlights)

    📓 Release Notes can be found here ↗️

    New Features ✨

    • ✨ FFGear API:
      • Introduced a brand-new high-performance, multi-threaded video decoding Gear built on top of DeFFcode's FFdecoder API.
      • Supports real-time FFmpeg subprocess pipelines, low-overhead hardware-accelerated decoding (e.g., CUDA/NVDEC), flexible pixel format conversions, and asynchronous per-frame metadata extraction.
      • Includes dedicated parameters: source_demuxer, frame_format, custom_ffmpeg, and extract_metadata.
    • ⚡️ Unified Backend Selection (Backend Enum):
      • Introduced a unified api parameter accepting a new Backend enum (Backend.CAMGEAR, Backend.PIGEAR, Backend.FFGEAR) across VideoGear, WebGear, WebGear_RTC, and NetGear_Async.
      • Replaces the legacy enablePiCamera boolean flag with a clean, explicit enumeration-based backend selection.
    • ⚡️ Plugin-Ready Stabilizer Architecture:
      • Refactored the monolithic Stabilizer class into a plugin-style stabilizer/ sub-package with a shared _StabilizerBase, an ASWStabilizer implementation, and a factory Stabilizer() function.
      • Added a new StabilizerMode enum for selecting stabilization backends via VideoGear's STABILIZER_MODE option, with clean provisions for upcoming real-time backends (e.g., Kalman tracking).
    • 🚩 WriteGear: Discard -vcodec via None:
      • Setting -vcodec or -c:v to None in output_params now cleanly omits the video codec parameter, letting FFmpeg auto-select the encoder (useful for GIF output and similar workflows).
    • 📦️ Poetry Package Management:
      • Added an official Poetry installation guide and ecosystem support for Poetry-managed environments.

    Updates/Improvements ⚡️

    • Packaging Infrastructure Modernization:
      • Migrated build and metadata configurations from legacy setup.py/setup.cfg to modern pyproject.toml configuration standards.
      • Switched to automatic package discovery via setuptools, excluding tests and docs from distribution builds.
    • Toolchain Overhaul (Ruff Migration):
      • Completely replaced flake8 and black with ruff for unified, high-speed linting and formatting across the entire codebase.
    • Type Hint Modernization:
      • Systematically updated type hints to leverage native Python 3.10+ structures, including PEP 604 union types (X | Y) and built-in collection generics.
    • PEP 561 Compliance:
      • Added a py.typed marker file so external type checkers (e.g., pyright, mypy) properly recognize VidGear as an inline-typed package.
    • CamGear YouTube Backend Refactor:
      • Extracted YT_backend into a dedicated yt_backend module for cleaner separation of concerns and improved maintainability.
    • Asyncio CLI Updates:
      • Replaced boolean string arguments with proper store_true flags for -S, -yt, -l, and -ep.
      • Added -a/--api flag for backend selection (camgear/pigear/ffgear) and FFGear-specific arguments (-sd, -ff, -cf).
      • Marked --enablePiCamera as a deprecated CLI flag with a runtime warning.

    Breaking Updates/Changes 💥

    • 💣 Deprecated enablePiCamera:

      • The enablePiCamera boolean flag has been officially deprecated across all core capture APIs (VideoGear, WebGear, WebGear_RTC, NetGear_Async) in favor of the explicit api=Backend.PIGEAR enumeration syntax.
      • Using the old flag will emit a DeprecationWarning at runtime. It will be removed in a future release.

    Bug-fixes 🐛

    • Stabilizer Memory Leak:
      • Fixed a severe memory bottleneck where self.__transforms tracking records grew unbounded over the entire runtime duration (O(total_frames) → O(smoothing_radius)), eliminating an out-of-memory hazard for long-running sessions.
    • FFGear Metadata Tuple Handling:
      • Fixed
  4. vidgear-0.3.4VidGear Stable v0.3.42025-11-12 · 2025-11-12 05:14 UTC
    查看更新说明

    This release significantly enhances VidGear’s robustness, developer experience, and future readiness. The primary focus is on adding comprehensive type hints across all public APIs, modernizing dependencies, and deeply restructuring documentation to improve clarity, navigation, and accessibility.

    📓 Complete Release Notes can be found here ↗️


    It is something I am doing with my own free time. But so much more needs to be done, and I need your help to do this. For just the price of a cup of coffee 🍵, you can make a difference 🤝

    What's Changed (Highlights)

    New Features ✨

    • Core:
      • Type Hints: Added comprehensive type hints to function signatures and return types across all API modules for improved code readability and IDE support.
    • Docs:
      • Docker Guide: Added a comprehensive new guide, detailing the challenges of containerizing VidGear, particularly around building OpenCV with correct GStreamer and FFmpeg support.
      • Sponsor Recognition: Added prominent sponsor section in the README.md and a new dedicated "Our Sponsors" page to highlight and thank supporters.

    Updates/Improvements ⚡️

    • Core: * Migrated from deprecated pkg_resources to packaging library for version parsing to ensure compatibility with future Python versions. * Replaced yt_dlp dependency with yt-dlp[default].

    Breaking Updates/Changes 💥

    • Setup.py:
      • 💣 Raised minimum Python version requirement from 3.8+ to 3.10+ to ensure long-term support.
      • 💣 VidGear no longer installs opencv-python automatically as a dependency when installed from source. Users must now manually install their preferred OpenCV binaries (e.g., opencv-python, opencv-contrib-python) as a prerequisite.
    • StreamGear:
      • 💣 The terminate() method is now formally deprecated and will be removed in a future release. The close() method should be used instead for safer process termination.

    Bug-fixes 🐛

    • Core:
      • Various minor bug fixes and improvements across the codebase as part of the type hint additions and dependency updates.
      • .gitignore expanded to standard Python template (covers caches, build, virtualenvs, packaging artifacts, IDE metadata).
      • Increased consistency in logging and error surfacing.
  5. vidgear-0.3.3VidGear Stable v0.3.32024-06-22 · 2024-06-22 18:41 UTC
    查看更新说明

    This update significantly enhances Vidgear's capabilities, ensuring better performance, broader compatibility, and improved user experience. The introduction of the Picamera2 API support, enhanced error handling, and detailed documentation updates are pivotal in making Vidgear more robust and user-friendly.

    📓 Complete Release Notes can be found here ↗️


    It is something I am doing with my own free time. But so much more needs to be done, and I need your help to do this. For just the price of a cup of coffee, you can make a difference 🙂

    What's Changed

    New Features ✨

    • PiGear:
      • Official Support for Picamera2 API backend:
        • This massive update brings official support for the new Picamera2 API, unlocking powerful features for Raspberry Pi Camera Modules and limited USB camera support.
        • Seamless Python wrapper: A robust wrapper around Picamera2 API library simplifies integration with minimal code changes for existing PiGear users.
        • Enhanced camera control: Leverages libcamera API under the hood for Raspberry Pi Camera Modules.
        • Existing compatibility: Maintains compatibility with PiGear's existing super-charged multi-threaded and colorspace manipulation framework.
        • Proper Resource management: Ensures proper resource release during PiGear termination.
        • USB camera support (limited): Provides basic functionality for USB webcams. PiGear could accurately differentiates between USB and Raspberry Pi cameras using metadata.
        • Backward compatibility: Seamlessly switches to the legacy Picamera library backend if Picamera2 is unavailable.
        • Standalone functionalities: Standalone functionalities for both legacy picamera and newer picamera2 backends for clarity.
        • Advanced optional parameters handling: Handles camera configurational parameters and user-defined settings for various camera types.
    • StreamGear:
      • Introduced new -enable_force_termination attribute for immediate FFmpeg process termination.
    • Helper:
      • Added support for SRTP/RTSPS in is_valid_url function:
        • SRTP/RTSPS extends RTSP/RTP to encrypt video and audio data using the same ciphers as HTTPS, typically AES with a 128-bit key length.
      • Added a custom deprecated decorator to mark deprecated functions and parameters.

    Updates/Improvements ⚡️

    • Core:
      • Improved exception handling for module imports.
      • Improved colorspace handling in videocapture gears.
    • Asyncio:
      • Replaced deprecated Starlette's on_shutdown parameter with an async context manager lifespan in WebGear and WebGear_RTC APIs.
    • NetGear_Async API:
      • Changed launch method to use self.loop.create_task() instead of asyncio.ensure_future()
      • Moved the event loop initialization code to an earlier point before setting event loop policy to ensure it is set up correctly before selecting WindowsSelectorEventLoop policy.
    • StreamGear:
      • Updated close() methods for handling gracefully signal interruptions based on different operating systems with device audio streams.
      • Enhanced stream copy support in Single Source mode.
    • NetGear:
      • Handled socket session expiration more gracefully in recv_handler.
      • Ensured proper termination of the ZMQ context and socket when closing th

用户点评

登录用户的真实使用记录,可按版本和硬件筛选
共 0 条

    还没有人点评。第一个说出真实体验的人最有价值。

    README 原文

    未翻译

    Getting Started   |   Gears   |   Documentation   |   Installation   |   License

    Build Status Codecov branch Azure DevOps builds (branch)

    Glitter chat Build Status PyPi version

    Recall.ai - API for meeting recordings
    If you’re looking for a meeting recording API,consider checking out Recall.ai, an API that records Zoom,Google Meet, Microsoft Teams, in-person meetings, and more.

    🙏 We are incredibly thankful to all our sponsors for supporting the development of VidGear. If you'd like to support VidGear, please check out our GitHub Sponsors page ➶

     

    Overview

    VidGear provides an easy-to-use, highly extensible, thoroughly optimised Multi-Threaded + Asyncio API Framework on top of many state-of-the-art specialized libraries like OpenCV, FFmpeg, ZeroMQ, picamera2, starlette, yt_dlp, pyscreenshot, dxcam, aiortc and python-mss serving at its backend, and enable us to flexibly exploit their internal parameters and methods, while silently delivering robust error-handling and real-time performance 🔥.

    If you're new to VidGear, head straight to the Getting Started ➶ section to install VidGear.

    The following functional block diagram clearly depicts the generalized functioning of VidGear APIs:

     

    Table of Contents

     

     

    TL;DR

    What is vidgear?

    "VidGear is a cross-platform High-Performance Framework that provides an one-stop Video-Processing solution for building complex real-time media applications in python."

    What does it do?

    "VidGear can read, write, process, send & receive video files/frames/streams from/to various devices in real-time, and faster than underline libraries."

    What is its purpose?

    "Write Less and Accomplish More" — VidGear's Motto

    "Built with simplicity in mind, VidGear lets programmers and software developers to easily integrate and perform Complex Video-Processing Tasks in their existing or newer applications without going through hefty documentation and in just a few lines of code. Beneficial for both, if you're new to programming with Python language or already a pro at it."

     

     

    Getting Started

    If this is your first time using VidGear, head straight to the Installation ➶ to install VidGear.

    Once you have VidGear installed, Checkout its Well-Documented Function-Specific Gears ➶

    Also, if you're already familiar with OpenCV library, then see Switching from OpenCV Library ➶

    Or, if you're just getting started with OpenCV-Python programming, then refer this FAQ ➶

    Finally, if looking for containerizing VidGear with Docker, then refer this guide ➶

     

     

    Gears: What are these?

    VidGear is built with multiple APIs a.k.a Gears, each with some unique functionality.

    Each API is designed exclusively to handle/control/process different data-specific & device-specific video streams, network streams, and media encoders/decoders. These APIs provides the user an easy-to-use, dynamic, extensible, and exposed Multi-Threaded + Asyncio optimized internal layer above state-of-the-art libraries to work with, while silently delivering robust error-handling.

    These Gears can be classified as follows:

    A. Video-Capture Gears:

    • CamGear: Multi-Threaded API targeting various IP-USB-Cameras/Network-Streams/Streaming-Sites-URLs.
    • FFGear: Multi-Threaded API for hardware-accelerated FFmpeg-powered video decoding with full filtergraph support.
    • PiGear: Multi-Threaded API targeting various Camera Modules and (limited) USB cameras on Raspberry Pis 🍇.
    • ScreenGear: High-performance API targeting rapid Screencasting Capabilities.
    • VideoGear: Common Video-Capture API with internal Video Stabilizer wrapper.

    B. Video-Writer Gears:

    • WriteGear: Handles Lossless Video-Writer for file/stream/frames Encoding and Compression.

    C. Streaming Gears:

    • StreamGear: Handles Transcoding of High-Quality, Dynamic & Adaptive Streaming Formats.

    • Asynchronous I/O Streaming Gear:

      • WebGear: ASGI Video-Server that broadcasts Live MJPEG-Frames (or low-latency H.264 video) to any web-browser on the network.
      • WebGear_RTC: Real-time Asyncio WebRTC media server for streaming directly to peer clients over the network.

    D. Network Gears:

    • NetGear: Handles High-Performance Video-Frames & Data Transfer between interconnecting systems over the network.

    • Asynchronous I/O Network Gear:

      • NetGear_Async: Immensely Memory-Efficient Asyncio Video-Frames Network Messaging Framework.

     

     

    CamGear

    CamGear can grab ultra-fast frames from a diverse range of file-formats/devices/streams, which includes almost any IP-USB Cameras, multimedia video file-formats, various network stream protocols such as http(s), rtp, rtsp, rtmp, mms, etc., and GStreamer's pipelines, plus direct support for live video streaming sites like YouTube, Twitch, LiveStream, Dailymotion etc.

    CamGear provides a flexible, high-level, multi-threaded framework around OpenCV's VideoCapture class with access almost all of its available parameters. CamGear internally implements yt_dlp backend class for seamlessly pipelining live video-frames and metadata from various streaming services like YouTube, Twitch, and many more ➶. Furthermore, its framework relies exclusively on Threaded Queue mode for ultra-fast, error-free, and synchronized video-frame handling.

    CamGear API Guide:

    >>> Usage Guide

     

     

    FFGear

    FFGear is a multi-threaded, high-performance wrapper around DeFFcode's FFdecoder API that compiles and executes an FFmpeg pipeline inside a subprocess pipe for generating real-time, low-overhead, lightning-fast decoded video frames in Python.

    FFGear API provides direct, transparent access to the full FFdecoder feature set, including:

    Similar to CamGear, FFGear also supports the yt_dlp backend for seamlessly pipelining live video frames from streaming services like YouTube, Twitch, and many more ➶

    Below is a snapshot of FFGear optimizing Real-time YOLOv10-Nano model inference by processing only Keyframes (I-frames) while skipping all non-keyframes (P/B-frames), reducing unnecessary decoding and inference workloads by up to 98%.

    Code to generate above result:

    # import required libraries
    from vidgear.gears import FFGear
    from ultralytics import YOLO
    
    # Initialize YOLOv10-Nano model
    model = YOLO("yolov10n.pt")
    
    # Configure FFGear with per-frame metadata extraction enable
    options = {"-extract_metadata": True}
    stream = FFGear(
        source="test.mp4", frame_format="bgr24", logging=True, **options
    ).start()
    
    # loop over
    while True:
    
        # read data from stream
        output = stream.read()
    
        # check if end of stream
        if output is None:
            break
    
        # Unpack the frame and its associated metadata
        frame, meta = output
    
        # --- OPTIMIZATION STEP ---
        # We skip all non-keyframes to save processing power.
        # This ensures the model only runs on the most information-dense frames.
        if not meta.get("is_keyframe"):
            continue  # <-- Skips Non-key frames (P, B-frames)
    
        # Log keyframe details
        print(f"Keyframe #{meta['frame_num']} at {meta['pts_time']:.3f}s")
    
        # Perform AI Inference on keyframes (I-frames) only
        # Because we skip non-keyframes, this heavy task runs significantly less often.
        results = model(frame)
    
        # Annotate the frame with detection boxes and labels
        annotated_frame = results[0].plot()
    
        # {Insert your custom logic here, e.g., displaying/saving frames or triggering an alert}
    
    # safely close video stream
    stream.stop()
    

    FFGear API Guide:

    >>> Usage Guide

     

     

    VideoGear

    VideoGear API provides a special internal wrapper around VidGear's exclusive Video Stabilizer class.

    VideoGear also serves as a unified video-capture API, offering seamless access to CamGear, PiGear, and FFGear along with their respective parameters. You can switch between these backends using the api parameter (defaults to Backend.CAMGEAR).

    It is especially useful when you want to toggle between different video-capture backends without significant code changes. Additionally, it simplifies video stabilization for both real-time and non-real-time streams, requiring minimal effort and fewer lines of code. The Stabilizer offers two backends: the default Average Sliding-Window (StabilizerMode.ASW) and a zero-latency Kalman filter (StabilizerMode.KALMAN) for live streams.

    Below is a snapshot of a VideoGear Stabilizer in action (See its detailed usage here):

    Code to generate above result:

    # import required libraries
    from vidgear.gears import VideoGear
    import numpy as np
    import cv2
    
    # open any valid video stream with stabilization enabled(`stabilize = True`)
    stream_stab = VideoGear(source="test.mp4", stabilize=True).start()
    
    # open same stream without stabilization for comparison
    stream_org = VideoGear(source="test.mp4").start()
    
    # loop over
    while True:
    
        # read stabilized frames
        frame_stab = stream_stab.read()
    
        # check for stabilized frame if Nonetype
        if frame_stab is None:
            break
    
        # read un-stabilized frame
        frame_org = stream_org.read()
    
        # concatenate both frames
        output_frame = np.concatenate((frame_org, frame_stab), axis=1)
    
        # put text over concatenated frame
        cv2.putText(
            output_frame,
            "Before",
            (10, output_frame.shape[0] - 10),
            cv2.FONT_HERSHEY_SIMPLEX,
            0.6,
            (0, 255, 0),
            2,
        )
        cv2.putText(
            output_frame,
            "After",
            (output_frame.shape[1] // 2 + 10, output_frame.shape[0] - 10),
            cv2.FONT_HERSHEY_SIMPLEX,
            0.6,
            (0, 255, 0),
            2,
        )
    
        # Show output window
        cv2.imshow("Stabilized Frame", output_frame)
    
        # check for 'q' key if pressed
        key = cv2.waitKey(1) & 0xFF
        if key == ord("q"):
            break
    
    # close output window
    cv2.destroyAllWindows()
    
    # safely close both video streams
    stream_org.stop()
    stream_stab.stop()
    

    VideoGear API Guide:

    >>> Usage Guide

     

     

    PiGear

    PiGear is a specialized API similar to the CamGear API but optimized for Raspberry Pi :grapes: Boards, offering comprehensive support for camera modules (e.g., OmniVision OV5647 Camera Module, Sony IMX219 Camera Module), along with limited compatibility for USB cameras.

    PiGear implements a seamless and robust wrapper around the picamera2 python library, simplifying integration with minimal code changes and ensuring a smooth transition for developers already familiar with the Picamera2 API. PiGear leverages the libcamera API under the hood with multi-threading, providing high-performance :fire:, enhanced control and functionality for Raspberry Pi camera modules.

    PiGear handles common configuration parameters and non-standard settings for various camera types, simplifying the integration process. PiGear currently supports PiCamera2 API parameters such as sensor, controls, transform, and format etc., with internal type and sanity checks for robust performance.

    While primarily focused on Raspberry Pi camera modules, PiGear also provides basic functionality for USB webcams only with Picamera2 API, along with the ability to accurately differentiate between USB and Raspberry Pi cameras using metadata.

    PiGear seamlessly switches to the legacy picamera library if the picamera2 library is unavailable, ensuring seamless backward compatibility. For this, PiGear also provides a flexible multi-threaded framework around complete picamera API, allowing developers to effortlessly exploit a wide range of parameters, such as brightness, saturation, sensor_mode, iso, exposure, and more.

    Furthermore, PiGear supports the use of multiple camera modules, including those found on Raspberry Pi Compute Module IO boards and USB cameras (only with Picamera2 API).

    Best of all, PiGear contains Threaded Internal Timer - that silently keeps active track of any frozen-threads/hardware-failures and exit safely, if any does occur. That means that if you're running PiGear API in your script and someone accidentally pulls the Camera-Module cable out, instead of going into possible kernel panic, API will exit safely to save resources.

    Code to open picamera2 stream with variable parameters in PiGear API:

    # import required libraries
    from vidgear.gears import PiGear
    from libcamera import Transform
    import cv2
    
    # formulate various Picamera2 API 
    # configurational parameters
    options = {
        "controls": {"Brightness": 0.5, "ExposureValue": 2.0},
        "transform": Transform(hflip=1),
        "sensor": {"output_size": (480, 320)},  # will override `resolution`
        "format": "RGB888", # 8-bit BGR
    }
    
    # open pi video stream with defined parameters
    stream = PiGear(resolution=(640, 480), framerate=60, logging=True, **options).start()
    
    # loop over
    while True:
    
        # read frames from stream
        frame = stream.read()
    
        # check for frame if Nonetype
        if frame is None:
            break
    
        # {do something with the frame here}
    
        # Show output window
        cv2.imshow("Output Frame", frame)
    
        # check for 'q' key if pressed
        key = cv2.waitKey(1) & 0xFF
        if key == ord("q"):
            break
    
    # close output window
    cv2.destroyAllWindows()
    
    # safely close video stream
    stream.stop()
    

    PiGear API Guide:

    >>> Usage Guide

     

     

    ScreenGear

    ScreenGear is designed exclusively for targeting rapid Screencasting Capabilities, which means it can grab frames from your monitor in real-time, either by defining an area on the computer screen or full-screen, at the expense of inconsiderable latency. ScreenGear also seamlessly support frame capturing from multiple monitors as well as supports multiple backends.

    ScreenGear implements a Lightning-Fast API wrapper around dxcam, pyscreenshot & python-mss python libraries and also supports an easy and flexible direct internal parameters manipulation.

    Below is a snapshot of a ScreenGear API in action:

    Code to generate the above results:

    # import required libraries
    from vidgear.gears import ScreenGear
    import cv2
    
    # open video stream with default parameters
    stream = ScreenGear().start()
    
    # loop over
    while True:
    
        # read frames from stream
        frame = stream.read()
    
        # check for frame if Nonetype
        if frame is None:
            break
    
        # {do something with the frame here}
    
        # Show output window
        cv2.imshow("Output Frame", frame)
    
        # check for 'q' key if pressed
        key = cv2.waitKey(1) & 0xFF
        if key == ord("q"):
            break
    
    # close output window
    cv2.destroyAllWindows()
    
    # safely close video stream
    stream.stop()
    

    ScreenGear API Guide:

    >>> Usage Guide

     

     

    WriteGear

    WriteGear handles various powerful Video-Writer Tools that provide us the freedom to do almost anything imaginable with multimedia data.

    WriteGear API provides a complete, flexible, and robust wrapper around FFmpeg, a leading multimedia framework. WriteGear can process real-time frames into a lossless compressed video-file with any suitable specifications (such asbitrate, codec, framerate, resolution, subtitles, etc.).

    WriteGear also supports streaming with traditional protocols such as RTSP/RTP, RTMP. It is powerful enough to perform complex tasks such as Live-Streaming (such as for Twitch, YouTube etc.) and Multiplexing Video-Audio with real-time frames in just few lines of code.

    Best of all, WriteGear grants users the complete freedom to play with any FFmpeg parameter with its exclusive Custom Commands function (see this doc) without relying on any third-party API.

    In addition to this, WriteGear also provides flexible access to OpenCV's VideoWriter API tools for video-frames encoding without compression.

    WriteGear primarily operates in the following two modes:

    • Compression Mode: In this mode, WriteGear utilizes powerful FFmpeg inbuilt encoders to encode lossless multimedia files. This mode provides us the ability to exploit almost any parameter available within FFmpeg, effortlessly and flexibly, and while doing that it robustly handles all errors/warnings quietly. You can find more about this mode here ➶

    • Non-Compression Mode: In this mode, WriteGear utilizes basic OpenCV's inbuilt VideoWriter API tools. This mode also supports all parameter transformations available within OpenCV's VideoWriter API, but it lacks the ability to manipulate encoding parameters and other important features like video compression, audio encoding, etc. You can learn about this mode here ➶

    WriteGear API Guide:

    >>> Usage Guide

     

     

    StreamGear

    StreamGear streamlines and simplifies the transcoding workflow to generate Ultra-Low Latency, High-Quality, Dynamic & Adaptive Streaming Formats like MPEG-DASH and Apple HLS with just a few lines of Python code, allowing developers to focus on their application logic rather than dealing with the complexities of transcoding and chunking media files.

    StreamGear API provides a standalone, highly extensible, and flexible wrapper around the FFmpeg multimedia framework for generating chunk-encoded media segments from your multimedia content effortlessly.

    With StreamGear, you can transcode source video/audio files and real-time video frames into a sequence of multiple smaller chunks/segments of suitable lengths. These segments facilitate streaming at different quality levels (bitrates or spatial resolutions) and allow for seamless switching between quality levels during playback based on available bandwidth. You can serve these segments on a web server, making them easily accessible via standard HTTP GET requests.

    SteamGear currently supports both MPEG-DASH (Dynamic Adaptive Streaming over HTTP, ISO/IEC 23009-1) and Apple HLS (HTTP Live Streaming).

    Additionally, StreamGear generates a manifest file (such as MPD for DASH) or a master playlist (such as M3U8 for Apple HLS) alongside the segments. These files contain essential segment information, including timing, URLs, and media characteristics like video resolution and adaptive bitrates. They are provided to the client before the streaming session begins.

    StreamGear primarily works in two Independent Modes for transcoding which serves different purposes:

    • Single-Source Mode 💿 : In this mode, StreamGear transcodes entire video file (as opposed to frame-by-frame) into a sequence of multiple smaller chunks/segments for streaming. This mode works exceptionally well when you're transcoding long-duration lossless videos(with audio) for streaming that required no interruptions. But on the downside, the provided source cannot be flexibly manipulated or transformed before sending onto FFmpeg Pipeline for processing. Learn more about this mode here ➶

    • Real-time Frames Mode 🎞️ : In this mode, StreamGear directly transcodes frame-by-frame (as opposed to a entire video file), into a sequence of multiple smaller chunks/segments for streaming. This mode works exceptionally well when you desire to flexibility manipulate or transform numpy.ndarray frames in real-time before sending them onto FFmpeg Pipeline for processing. But on the downside, audio has to added manually (as separate source) for streams. Learn more about this mode here ➶

    StreamGear API Guide:

    >>> Usage Guide

     

     

    NetGear

    NetGear is exclusively designed to transfer video-frames & data synchronously between interconnecting systems over the network in real-time.

    NetGear implements a high-level wrapper around PyZmQ python library that contains python bindings for ZeroMQ - a high-performance asynchronous distributed messaging library.

    NetGear seamlessly supports additional bidirectional data transmission between receiver(client) and sender(server) while transferring video-frames all in real-time.

    NetGear can also robustly handle Multiple Server-Systems and Multiple Client-Systems and at once, thereby providing access to a seamless exchange of video-frames & data between multiple devices across the network at the same time.

    NetGear allows remote connection over SSH Tunnel that allows us to connect NetGear client and server via secure SSH connection over the untrusted network and access its intranet services across firewalls.

    NetGear also enables real-time JPEG Frame Compression capabilities for boosting performance significantly while sending video-frames over the network in real-time.

    For security, NetGear implements easy access to ZeroMQ's powerful, smart & secure Security Layers that enable Strong encryption on data and unbreakable authentication between the Server and the Client with the help of custom certificates.

    NetGear as of now seamlessly supports three ZeroMQ messaging patterns:

    Whereas supported protocol are: tcp and ipc.

    NetGear API Guide:

    >>> Usage Guide

     

     

    WebGear

    WebGear is a powerful ASGI Video-Broadcaster API ideal for transmitting Motion-JPEG-frames (or low-latency H.264 video) from a single source to multiple recipients via the browser.

    WebGear API works on Starlette's ASGI application and provides a highly extensible and flexible async wrapper around its complete framework. WebGear can flexibly interact with Starlette's ecosystem of shared middleware, mountable applications, Response classes, Routing tables, Static Files, Templating engine(with Jinja2), etc.

    WebGear API operates in two modes: MJPEG Mode (default) uses an intraframe-only compression scheme where each video-frame is encoded as JPEG and streamed over HTTP using Starlette's Multipart Streaming Response, which needs no FFmpeg and imposes lower processing requirements, but uses more bandwidth. Whereas H.264 Mode (streaming_mode="h264") encodes frames with FFmpeg into low-latency H.264 and streams them over WebSockets, where browser decodes them with hardware-accelerated WebCodecs, using ~9-38x less bandwidth than MJPEG, but starting one FFmpeg encoder per connected viewer. Both are served by a Uvicorn ASGI Server.

    In layman's terms, WebGear acts as a powerful Video Broadcaster that transmits live video-frames to any web-browser in the network. Additionally, WebGear API also provides a special internal wrapper around VideoGear, which itself provides internal access to CamGear, PiGear, and FFGear APIs (via the api parameter), thereby granting it exclusive power of broadcasting frames from any incoming stream. It also allows us to define our custom Server as source to transform frames easily before sending them across the network (see this doc example).

    Below is a snapshot of a WebGear Video Server in action on Chrome browser:

    Code to generate the above result:

    # import required libraries
    import uvicorn
    from vidgear.gears.asyncio import WebGear
    
    # low-latency H.264 mode, or use "mjpeg" (default)
    options = {
        "frame_size_reduction": 40,
    }
    
    # initialize WebGear app
    web = WebGear(source="foo.mp4", streaming_mode="h264", logging=True, **options)
    
    # run this app on Uvicorn server at address http://localhost:8000/
    uvicorn.run(web(), host="localhost", port=8000)
    
    # close app safely
    web.shutdown()
    

    WebGear API Guide:

    >>> Usage Guide

     

     

    WebGear_RTC

    WebGear_RTC is similar to WeGear API in many aspects but utilizes WebRTC technology under the hood instead of Motion JPEG, which makes it suitable for building powerful video-streaming solutions for all modern browsers as well as native clients available on all major platforms.

    WebGear_RTC is implemented with the help of aiortc library which is built on top of asynchronous I/O framework for Web Real-Time Communication (WebRTC) and Object Real-Time Communication (ORTC) and supports many features like SDP generation/parsing, Interactive Connectivity Establishment with half-trickle and mDNS support, DTLS key and certificate generation, DTLS handshake, etc.

    WebGear_RTC can handle multiple consumers seamlessly and provides native support for ICE (Interactive Connectivity Establishment) protocol, STUN (Session Traversal Utilities for NAT), and TURN (Traversal Using Relays around NAT) servers that help us to seamlessly establish direct media connection with the remote peers for uninterrupted data flow. It also allows us to define our custom streaming class with suitable source to transform frames easily before sending them across the network(see this doc example).

    WebGear_RTC API works in conjunction with Starlette's ASGI application and provides easy access to its complete framework. WebGear_RTC can also flexibly interact with Starlette's ecosystem of shared middleware, mountable applications, Response classes, Routing tables, Static Files, Templating engine(with Jinja2), etc.

    Additionally, WebGear_RTC API also provides a special internal wrapper around VideoGear, which itself provides internal access to CamGear, PiGear, and FFGear APIs, selectable via the api parameter.

    Below is a snapshot of a WebGear_RTC Media Server in action on Chrome browser:

    Code to generate the above result:

    # import required libraries
    import uvicorn
    from vidgear.gears.asyncio import WebGear_RTC
    
    # various performance tweaks
    options = {
        "frame_size_reduction": 30,
    }
    
    # initialize WebGear_RTC app
    web = WebGear_RTC(source="foo.mp4", logging=True, **options)
    
    # run this app on Uvicorn server at address http://localhost:8000/
    uvicorn.run(web(), host="localhost", port=8000)
    
    # close app safely
    web.shutdown()
    

    WebGear_RTC API Guide:

    >>> Usage Guide

     

     

    NetGear_Async

    NetGear_Async can generate the same performance as NetGear API at about one-third the memory consumption, and also provide complete server-client handling with various options to use variable protocols/patterns similar to NetGear, but lacks in term of flexibility as it supports only a few NetGear's Exclusive Modes.

    NetGear_Async is built on zmq.asyncio, and powered by a high-performance asyncio event loop called uvloop to achieve unmatchable high-speed and lag-free video streaming over the network with minimal resource constraints. NetGear_Async can transfer thousands of frames in just a few seconds without causing any significant load on your system.

    NetGear_Async provides complete server-client handling and options to use variable protocols/patterns similar to NetGear API. Furthermore, NetGear_Async allows us to define our custom Server as source to transform frames easily before sending them across the network(see this doc example).

    NetGear_Async also provides a special internal wrapper around VideoGear, which itself provides internal access to CamGear, PiGear, and FFGear APIs, selectable via the api parameter.

    NetGear_Async now supports additional bidirectional data transmission between receiver(client) and sender(server) while transferring video-frames. Users can easily build complex applications such as like Real-Time Video Chat in just few lines of code.

    NetGear_Async as of now supports all four ZeroMQ messaging patterns:

    Whereas supported protocol are: tcp and ipc.

    NetGear_Async API Guide:

    >>> Usage Guide

     

     

    Contributions

    We welcome your contributions to help us improve and extend this project. If you want to get involved with VidGear development, checkout the Contribution Guidelines ➶

    We're offering support for VidGear on Gitter Community Channel. Come and join the conversation over there!

     

     

    Donations and Sponsorships

    It is something I am doing with my own free time. But so much more needs to be done, and I need your help to do this. For just the price of a cup of coffee 🍵, you can make a difference 🤝

    You can also become a sponsor via GitHub Sponsors by clicking the button below:

    Thanks a million! 💖

     

     

    Citation

    Here is a Bibtex entry you can use to cite this project in a publication:

    DOI

    @software{vidgear,
      author       = {Abhishek Thakur and
                      Zoe Papakipos and
                      Christian Clauss and
                      Shail and
                      Christian Hollinger and
                      Ian Max Andolina and
                      Kyle Ahn and
                      freol35241 and
                      Abhishek Suran and
                      Benjamin Lowe and
                      Mickaël Schoentgen and
                      Renaud Bouckenooghe and
                      Ibtsam Ahmad},
      title        = {abhiTronix/vidgear: VidGear Stable v0.3.6},
      month        = oct,
      year         = 2026,
      publisher    = {Zenodo},
      version      = {vidgear-0.3.6},
      doi          = {10.5281/zenodo.23656015},
      url          = {https://doi.org/10.5281/zenodo.23656015},
    }
    

     

     

    Copyright

    Copyright © abhiTronix 2019

    This library is released under the Apache 2.0 License.