Vidgear
A High-performance cross-platform Video Processing Python framework powerpacked with unique trailblazing features :fire:
Install / Use
/learn @abhiTronix/VidgearREADME
Getting Started | [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-badge]][gitter] [![Build Status][appveyor]][app] [![PyPi version][pypi-badge]][pypi]
</div> <!-- SPONSORS START --> <h1 align="left"> Our Sponsors 🤝 </h1> <div align="left">| <h3>Recall.ai - API for meeting recordings</h3> | | :-------------: | | <a href="https://www.recall.ai/product/meeting-recording-api?utm_source=github&utm_medium=sponsorship&utm_campaign=abhiTronix-vidgear"><img src="https://abhitronix.github.io/vidgear/latest/assets/images/sponsors/sponsor-recallai.png" alt="Recall.ai - Meeting Recording API" /></a> | | If you’re looking for a meeting recording API,</br>consider checking out Recall.ai, an API that records Zoom,</br>Google Meet, Microsoft Teams, in-person meetings, and more. |
</div> <h5></h5><!-- SPONSORS END -->🙏 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][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 🔥.
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:
<p align="center"> <img src="https://abhitronix.github.io/vidgear/latest/assets/images/gears_fbd.png" alt="@Vidgear Functional Block Diagram" /> </p>
Table of Contents
- TL;DR
- Getting Started
- Gears: What are these?
- Contributions
- Donations and Sponsorships
- 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 ➶
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][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
<p align="center"> <img src="https://abhitronix.github.io/vidgear/latest/assets/images/camgear.png" alt="CamGear Functional Block Diagram" width="45%"/> </p>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-
