vidgear

<h1 align="center"> <img src="https://abhitronix.github.io/vidgear/latest/assets/images/vidgear.png" alt="VidGear" title="Logo designed by Abhishek Thakur(@abhiTronix), under CC-BY-NC-SA 4.0 License" width="80%"/> </h1> <h2 align="center"> <img src="https://abhitronix.github.io/vidgear/latest/assets/images/tagline.svg" alt="VidGear tagline" width="40%"/> </h2> <div align="center">

[Releases][release] | [Gears][gears] | [Documentation][docs] | [Installation][installation] | License

[![Build Status][github-cli]][github-flow] [![Codecov branch][codecov]][code] [![Azure DevOps builds (branch)][azure-badge]][azure-pipeline]

[![Glitter chat][gitter-bagde]][gitter] [![Build Status][appveyor]][app] [![PyPi version][pypi-badge]][pypi]

[![Code Style][black-badge]][black]

</div>

VidGear is a High-Performance Video Processing Python Library that 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][opencv], [FFmpeg][ffmpeg], [ZeroMQ][zmq], [picamera2][picamera2], [starlette][starlette], [yt_dlp][yt_dlp], [pyscreenshot][pyscreenshot], [dxcam][dxcam], [aiortc][aiortc] and [python-mss][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 🔥

VidGear primarily focuses on simplicity, and thereby lets programmers and software developers to easily integrate and perform Complex Video Processing Tasks, in just a few lines of code.

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

TL;DR
Getting Started
Gears: What are these?
Contributions
Donations
Citation
Copyright

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][tqm-doc] 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][switch_from_cv]. 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 ➶][installation] to install VidGear.

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

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

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

Gears: What are these?

VidGear is built with multiple APIs a.k.a [Gears][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.
PiGear: Multi-Threaded API targeting various Camera Modules and (limited) USB cameras on Raspberry Pis :grapes:.
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 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 ([upto 4k tested][test-4k]), 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][opencv-vc] with access almost all of its available parameters. CamGear internally implements [yt_dlp][yt_dlp] backend class for seamlessly pipelining live video-frames and metadata from various streaming services like [YouTube][youtube-doc], [Twitch][piping-live-videos], and many more ➶. Furthermore, its framework relies exclusively on [Threaded Queue mode][tqm-doc] for ultra-fast, error-free, and synchronized video-frame handling.

CamGear API Guide:

[>>> Usage Guide][camgear-doc]

VideoGear

VideoGear API provides a special internal wrapper around VidGear's exclusive [Video Stabilizer][stabilizer-doc] class.

VideoGear also acts as a Common Video-Capture API that provides internal access for both CamGear and PiGear APIs and their parameters with an exclusive enablePiCamera boolean flag.

VideoGear is ideal when you need to switch to different video sources without changing your code much. Also, it enables easy stabilization for various video-streams (real-time or not) with minimum effort and writing way fewer lines of code.

Below is a snapshot of a VideoGear Stabilizer in action (See its detailed usage [here][stabilizer-doc-ex]):

<p align="center"> <img src="https://user-images.githubusercontent.com/34266896/211500670-b3aaf4db-a52a-4836-a03c-c2c17b971feb.gif" alt="VideoGear Stabilizer in action!"/> <br> <sub><i>Original Video Courtesy <a href="http://liushuaicheng.org/SIGGRAPH2013/database.html" title="opensourced video samples database">@SIGGRAPH2013</a></i></sub> </p>

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][videogear-doc]

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][ov5647-picam], [Sony IMX219 Camera Module][imx219-picam]), along with limited compatibility for USB cameras.

PiGear implements a seamless and robust wrapper around the [picamera2][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][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][pigear-doc]

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][dxcam], [pyscreenshot][pyscreenshot] & [python-mss][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()