🎉 Release VidGear Stable v0.3.3

.github/workflows/ci_linux.yml

@@ -59,12 +59,12 @@ jobs:
           chmod +x scripts/bash/install_opencv.sh
       - name: install pip_dependencies
         run: |
-          pip install -U pip wheel numpy
-          pip install -U .[asyncio]
+          pip install -U pip wheel
+          pip install "numpy<2.0.0"
+          pip install -U .[asyncio] six httpx yt_dlp paramiko
           pip uninstall opencv-python -y
-          pip install -U flake8 six codecov httpx pytest pytest-asyncio pytest-cov yt_dlp mpegdash paramiko m3u8 async-asgi-testclient
+          pip install -U flake8 codecov pytest pytest-asyncio pytest-cov mpegdash m3u8 async-asgi-testclient
           pip install -U deffcode
-          pip install cryptography==38.0.4
         if: success()
       - name: run prepare_dataset_script
         run: bash scripts/bash/prepare_dataset.sh

.github/workflows/deploy_docs.yml

@@ -47,7 +47,9 @@ jobs:
         if: success()
       - name: install_dependencies
         run: |
-          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy          
+          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin          
+          pip install -U mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy
+          pip install -U mkdocs-git-authors-plugin
           pip install jinja2==3.0.*
         if: success()
       - name: git configure
@@ -65,7 +67,7 @@ jobs:
       - name: mike deploy docs release
         run: |
           echo "${{ env.NAME_RELEASE }}"
-          mike deploy --push --update-aliases --no-redirect ${{ env.NAME_RELEASE }} ${{ env.RELEASE_NAME }} --title=${{ env.RELEASE_NAME }}
+          mike deploy --push --update-aliases --alias-type=copy ${{ env.NAME_RELEASE }} ${{ env.RELEASE_NAME }} --title=${{ env.RELEASE_NAME }}
         env:
           NAME_RELEASE: "v${{ env.RELEASE_NAME }}-release"
         if: success()
@@ -88,7 +90,9 @@ jobs:
         if: success()
       - name: install_dependencies
         run: |
-          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy
+          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin          
+          pip install -U mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy
+          pip install -U mkdocs-git-authors-plugin          
           pip install jinja2==3.0.*
         if: success()
       - name: git configure
@@ -106,7 +110,7 @@ jobs:
       - name: mike deploy docs stable
         run: |
           echo "${{ env.NAME_STABLE }}"
-          mike deploy --push --update-aliases --no-redirect ${{ env.NAME_STABLE }} latest --title=latest
+          mike deploy --push --update-aliases --alias-type=copy ${{ env.NAME_STABLE }} latest --title=latest
           mike set-default --push latest
         env:
           NAME_STABLE: "v${{ env.RELEASE_NAME }}-stable"
@@ -131,7 +135,9 @@ jobs:
         if: success()
       - name: install_dependencies
         run: |
-          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy          
+          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin          
+          pip install -U mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy
+          pip install -U mkdocs-git-authors-plugin          
           pip install jinja2==3.0.*
         if: success()
       - name: git configure
@@ -149,7 +155,7 @@ jobs:
       - name: mike deploy docs dev
         run: |
           echo "Releasing ${{ env.NAME_DEV }}"
-          mike deploy --push --update-aliases --no-redirect ${{ env.NAME_DEV }} dev --title=dev
+          mike deploy --push --update-aliases --alias-type=copy ${{ env.NAME_DEV }} dev --title=dev
         env:
           NAME_DEV: "v${{ env.RELEASE_NAME }}-dev"
         if: success()

.gitignore

@@ -7,6 +7,7 @@ venv
 Pipfile.lock
 env3.*
 env
+.cache
 .coverage
 coverage.xml
 .netlify

README.md

@@ -39,7 +39,7 @@ limitations under the License.
 
  
 
-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], [picamera][picamera], [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 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.
 
@@ -122,7 +122,7 @@ Each API is designed exclusively to handle/control/process different data-specif
 **A. Video-Capture Gears:**
 
 - [**CamGear:**](#camgear) Multi-Threaded API targeting various IP-USB-Cameras/Network-Streams/Streaming-Sites-URLs.
-- [**PiGear:**](#pigear) Multi-Threaded API targeting various Raspberry-Pi Camera Modules.
+- [**PiGear:**](#pigear) Multi-Threaded API targeting various Camera Modules and _(limited)_ USB cameras on Raspberry Pis :grapes:.
 - [**ScreenGear:**](#screengear) High-performance API targeting rapid Screencasting Capabilities.
 - [**VideoGear:**](#videogear) Common Video-Capture API with internal [Video Stabilizer](https://abhitronix.github.io/vidgear/latest/gears/stabilizer/overview/) wrapper.
 
@@ -265,27 +265,35 @@ stream_stab.stop()
   <img src="https://abhitronix.github.io/vidgear/latest/assets/images/picam2.webp" alt="PiGear" width="50%" />
 </p>
 
-> _PiGear is similar to CamGear but made to support various Raspberry Pi Camera Modules _(such as [OmniVision OV5647 Camera Module][ov5647-picam] and [Sony IMX219 Camera Module][imx219-picam])_._
+> _PiGear is a specialized API similar to the [CamGear API](#camgear) 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 provides a flexible multi-threaded framework around complete [picamera](https://picamera.readthedocs.io/en/release-1.13/index.html) python library, and provide us the ability to exploit almost all of its parameters like `brightness, saturation, sensor_mode, iso, exposure, etc.` effortlessly. Furthermore, PiGear also supports multiple camera modules, such as in the case of Raspberry-Pi Compute Module IO boards.
+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 picamera stream with variable parameters in PiGear API:**
+**Code to open picamera2 stream with variable parameters in PiGear API:**
 
 ```python
 # import required libraries
 from vidgear.gears import PiGear
+from libcamera import Transform
 import cv2
 
-# add various Picamera tweak parameters to dictionary
+# formulate various Picamera2 API 
+# configurational parameters
 options = {
-    "hflip": True,
-    "exposure_mode": "auto",
-    "iso": 800,
-    "exposure_compensation": 15,
-    "awb_mode": "horizon",
-    "sensor_mode": 0,
+    "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
@@ -316,7 +324,6 @@ cv2.destroyAllWindows()
 
 # safely close video stream
 stream.stop()
-
 ```
 
 ### PiGear API Guide:
@@ -420,21 +427,21 @@ In addition to this, WriteGear also provides flexible access to [**OpenCV's Vide
   <img src="https://abhitronix.github.io/vidgear/latest/assets/images/streamgear_flow.webp" alt="NetGear API" width=80%/>
 </p>
 
-> _StreamGear automates transcoding workflow for generating Ultra-Low Latency, High-Quality, Dynamic & Adaptive Streaming Formats (such as MPEG-DASH and Apple HLS) in just few lines of python code._
+> _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 provides a standalone, highly extensible, and flexible wrapper around [**FFmpeg**][ffmpeg] multimedia framework for generating chunked-encoded media segments of the content.
+StreamGear API provides a standalone, highly extensible, and flexible wrapper around the [**FFmpeg**](https://ffmpeg.org/) multimedia framework for generating chunk-encoded media segments from your multimedia content effortlessly.
 
-SteamGear is an out-of-the-box solution for transcoding source videos/audio files & real-time video frames and breaking them into a sequence of multiple smaller chunks/segments of suitable lengths. These segments make it possible to stream videos at different quality levels _(different bitrates or spatial resolutions)_ and can be switched in the middle of a video from one quality level to another – if bandwidth permits – on a per-segment basis. A user can serve these segments on a web server that makes it easier to download them through HTTP standard-compliant GET requests.
+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 [**MPEG-DASH**](https://www.encoding.com/mpeg-dash/) _(Dynamic Adaptive Streaming over HTTP, ISO/IEC 23009-1)_ and [**Apple HLS**](https://developer.apple.com/documentation/http_live_streaming) _(HTTP Live Streaming)_. But, Multiple DRM support is yet to be implemented.
+SteamGear currently supports both [**MPEG-DASH**](https://www.encoding.com/mpeg-dash/) _(Dynamic Adaptive Streaming over HTTP, ISO/IEC 23009-1)_  and [**Apple HLS**](https://developer.apple.com/documentation/http_live_streaming) _(HTTP Live Streaming)_. 
 
-SteamGear also creates a Manifest file _(such as MPD in-case of DASH)_ or a Master Playlist _(such as M3U8 in-case of Apple HLS)_ besides segments that describe these segment information _(timing, URL, media characteristics like video resolution and bit rates)_ and is provided to the client before the streaming session.
+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 ➶][ss-mode-doc]_**
+- **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 ➶][ss-mode-doc]_**
 
-- **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`](https://numpy.org/doc/1.18/reference/generated/numpy.ndarray.html#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 ➶][rtf-mode-doc]_**
+- **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`](https://numpy.org/doc/1.18/reference/generated/numpy.ndarray.html#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 ➶][rtf-mode-doc]_**
 
 ### StreamGear API Guide:
 
@@ -508,9 +515,9 @@ from vidgear.gears.asyncio import WebGear
 # various performance tweaks
 options = {
     "frame_size_reduction": 40,
-    "frame_jpeg_quality": 80,
-    "frame_jpeg_optimize": True,
-    "frame_jpeg_progressive": False,
+    "jpeg_compression_quality": 80,
+    "jpeg_compression_fastdct": True,
+    "jpeg_compression_fastupsample": False,
 }
 
 # initialize WebGear app
@@ -650,7 +657,7 @@ It is something I am doing with my own free time. But so much more needs to be d
 
 Here is a Bibtex entry you can use to cite this project in a publication:
 
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8174694.svg)](https://doi.org/10.5281/zenodo.8174694)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8332548.svg)](https://doi.org/10.5281/zenodo.8332548)
 
 ```BibTeX
 @software{vidgear,
@@ -660,18 +667,19 @@ Here is a Bibtex entry you can use to cite this project in a publication:
                   Christian Hollinger and
                   Ian Max Andolina and
                   Vincent Boivin and
-                  enarche-ahn and
+                  Kyle Ahn and
                   freol35241 and
                   Benjamin Lowe and
                   Mickaël Schoentgen and
-                  Renaud Bouckenooghe},
-  title        = {abhiTronix/vidgear: VidGear v0.3.1},
-  month        = jul,
+                  Renaud Bouckenooghe and
+                  Ibtsam Ahmad},
+  title        = {abhiTronix/vidgear: VidGear Stable v0.3.2},
+  month        = sep,
   year         = 2023,
   publisher    = {Zenodo},
-  version      = {vidgear-0.3.1},
-  doi          = {10.5281/zenodo.8174694},
-  url          = {https://doi.org/10.5281/zenodo.8174694}
+  version      = {vidgear-0.3.2},
+  doi          = {10.5281/zenodo.8332548},
+  url          = {https://doi.org/10.5281/zenodo.8332548}
 }
 ```
 
@@ -807,5 +815,6 @@ External URLs
 [zmq-req-rep]: https://learning-0mq-with-pyzmq.readthedocs.io/en/latest/pyzmq/patterns/client_server.html
 [zmq-pub-sub]: https://learning-0mq-with-pyzmq.readthedocs.io/en/latest/pyzmq/patterns/pubsub.html
 [zmq-pull-push]: https://learning-0mq-with-pyzmq.readthedocs.io/en/latest/pyzmq/patterns/pushpull.html#push-pull
+[picamera2]:https://github.com/raspberrypi/picamera2
 [picamera-setting]: https://picamera.readthedocs.io/en/release-1.13/quickstart.html
 [webrtc]: https://webrtc.org/

appveyor.yml

@@ -60,9 +60,10 @@ install:
   - "SET PATH=%PYTHON%;%PYTHON%\\Scripts;%PATH%"
   - "python --version"
   - "python -m pip install --upgrade pip wheel"
-  - "python -m pip install .[asyncio] six codecov httpx pytest-cov pytest-asyncio yt_dlp aiortc paramiko m3u8 async-asgi-testclient"
+  - cmd: python -m pip install "numpy<2.0.0"
+  - "python -m pip install --upgrade .[asyncio] six httpx yt_dlp aiortc"
+  - "python -m pip install --upgrade pytest codecov pytest-cov pytest-asyncio m3u8 async-asgi-testclient paramiko"
   - "python -m pip install --upgrade deffcode"
-  - "python -m pip install cryptography==38.0.4"
   - "python -m pip install https://github.com/abhiTronix/python-mpegdash/releases/download/0.3.0-dev2/mpegdash-0.3.0.dev2-py3-none-any.whl"
   - cmd: chmod +x scripts/bash/prepare_dataset.sh
   - cmd: bash scripts/bash/prepare_dataset.sh

azure-pipelines.yml

@@ -66,11 +66,11 @@ steps:
     displayName: "Prepare dataset"
 
   - script: |
-      python -m pip install --upgrade pip wheel
-      pip install --upgrade .[asyncio] six codecov yt_dlp httpx mpegdash paramiko m3u8 async-asgi-testclient
-      pip install --upgrade deffcode
-      pip install cryptography==38.0.4
-      pip install --upgrade pytest pytest-asyncio pytest-cov pytest-azurepipelines
+      python -m pip install -U pip wheel 
+      python -m pip install "numpy<2.0.0"
+      python -m pip install -U .[asyncio] yt_dlp httpx six paramiko
+      python -m pip install -U codecov pytest pytest-asyncio pytest-cov mpegdash m3u8 async-asgi-testclient
+      python -m pip install -U deffcode
     displayName: "Install pip dependencies"
 
   - script: |