⚡️ CamGear: Added a new YT_backend Internal Class with YT-DLP backend […

…#274] - ✨ Implemented `YT_backend` a new CamGear's Internal YT-DLP backend class for extracting metadata from Streaming URLs. - ✨ Added support for pipeling (live) video-frames from all yt-dlp supported streaming sites: https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md#supported-sites - ⚡️ Implemented algorithm from scratch for auto-extracting resolution specific streamable URLs for pipelineing. - ⚡️ Implemented logic for auto-calculating `best` and `worst` resolutions. - ✨ Added `is_livestream` global YT_backend parameters. - ✨ Added default options for yt-dlp for extracting info_dict(metadata) of the video as a single JSON line. - ✨ Added new `ytv_metadata` global parameter to CamGear for accessing video's metadata(such as duration, title, description) on-the-go. - 💥 Removed automatic enforcing of GStreamer backend for YouTube-livestreams and made it optional. - ⚰️ Completely removed old logic for extracting streams using pafy. - ⚠️ Playlists are still unsupported. - **CamGear:** - 💥 Removed `streamlink` backend support from `stream_mode` in favor of more reliable CamGear's Internal YT-DLP backend class for extracting metadata from Streaming URLs. - ⚰️ Removed all dead code related to streamlink backend. - 🐛 Fixed KeyError Bug for missing attributed in meta_data json in some streaming sites. - 💥 CamGear will raise `ValueError` if streaming site URL is unsupported by yt-dlp backend. - 💥 CamGear will raise ImportError if `yt-dlp` isn't installed and `stream_mode` is enabled. - **Docs:** - 📝 Added complete usage docs with new CamGear's Internal Class with YT-DLP backend. - 🚩 Updated CamGear parameters. - 📝 Added instructions to extract video's metadata. - 📝 Updated Admonitions with related information. - 🔥 Removed any `pafy` and `streamlink` references. - 💄 Updated Functional Block Diagram(`gears_fbd.png`) image. - ♿️ Updated installation instructions. - ⚰️ Removed dead code. - 💡 Updated code comments. - **Helper:** - 💥 Removed `restore_levelnames` method. - 💥 Removed `youtube_url_validator` helper method. - **Setup.py:** - ➖ Removed `streamlink` dependency. - ➖ Removed `pafy` dependency. - 🎨 Removed `pyzmq` from latest_version group. - 🏷️ Updated SEO Keywords. - **Maintenance:** - 🔥 Removed unused imports. - 🔊 Updated logging messages. - 💡 Updated code comments. - **CI:** - 💚 Restored `test_stream_mode` CamGear test. - 👷 Updated Streaming Sites test links. - 👷 Added more tests cases.
abhiTronix · Dec 4, 2021 · dc26c00 · dc26c00
2 parents cd481c1 + 522aa02
commit dc26c00
Show file tree

Hide file tree

Showing 19 changed files with 526 additions and 482 deletions.
diff --git a/README.md b/README.md
@@ -38,7 +38,7 @@ limitations under the License.
 
 &nbsp;
 
-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], [streamlink][streamlink], [pafy][pafy], [pyscreenshot][pyscreenshot], [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], [picamera][picamera], [starlette][starlette], [yt_dlp][yt_dlp], [pyscreenshot][pyscreenshot], [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.
 
@@ -166,7 +166,7 @@ Each API is designed exclusively to handle/control/process different data-specif
 
 > *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, rstp, rtmp, mms, etc.`, and GStreamer's pipelines, plus direct support for live video streaming sites like YouTube, Twitch, LiveStream, Dailymotion etc.*
 
-CamGear implements a flexible, high-level, multi-threaded framework around OpenCV's [VideoCapture class][opencv-vc] with access almost all of its available parameters. CamGear also employs [streamlink][streamlink] for [piping live videos][piping-live-videos] from various streaming services and also utilizies [pafy][pafy] with [yt_dlp][yt_dlp] at its backend for [YouTube pipelining][youtube-doc]. Furthermore, its framework relies exclusively on [**Threaded Queue mode**][TQM-doc] for ultra-fast, error-free, and synchronized video-frame handling.
+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 ➶](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md#supported-sites). Furthermore, its framework relies exclusively on [**Threaded Queue mode**][TQM-doc] for ultra-fast, error-free, and synchronized video-frame handling.
 
 ### CamGear API Guide:
 

diff --git a/docs/bonus/reference/helper.md b/docs/bonus/reference/helper.md
@@ -126,10 +126,6 @@ limitations under the License.
 
 &nbsp;
 
-::: vidgear.gears.helper.youtube_url_validator
-
-&nbsp;
-
 
 ::: vidgear.gears.helper.validate_auth_keys
 

diff --git a/docs/gears/camgear/advanced/source_params.md b/docs/gears/camgear/advanced/source_params.md
@@ -51,10 +51,9 @@ These tweak parameters can be used to transform input Camera-Source properties _
 
 		!!! example "Its complete usage example is given [here ➶](../../../../help/camgear_faqs/#how-to-change-quality-and-parameters-of-youtube-streams-with-camgear)"
 
-	- [X] `STREAM_PARAMS` _(dict)_: This dictionary attribute can be used in CamGear's Stream Mode (`stream_mode=True`) for specifying underlying API's(i.e. `streamlink` & `yt_dlp`) internal parameters. Its usage is as follows:
+	- [X] `STREAM_PARAMS` _(dict)_: This dictionary attribute can be used in CamGear's Stream Mode (`stream_mode=True`) for specifying parameters for its internal `yt_dlp` backend class. Its usage is as follows:
 
-		!!! tip "All `STREAM_PARAMS` Supported Parameters"
-			- All Streamlink parameter can be found [here ➶](https://streamlink.github.io/api.html#streamlink.Streamlink.set_option)
+		!!! info "All `STREAM_PARAMS` Supported Parameters"
 			- All yt_dlp parameter can be found [here ➶](https://github.com/yt-dlp/yt-dlp/blob/bd1c7923274962e3027acf63111ccb0d766b9725/yt_dlp/__init__.py#L594-L749)
 
 		```python

diff --git a/docs/gears/camgear/overview.md b/docs/gears/camgear/overview.md
@@ -31,7 +31,7 @@ limitations under the License.
 
 CamGear API provides a flexible, high-level multi-threaded wrapper around OpenCV's *[VideoCapture API](https://docs.opencv.org/master/d8/dfe/classcv_1_1VideoCapture.html#a57c0e81e83e60f36c83027dc2a188e80)* with direct access to almost all of its available [*parameters*](../advanced/source_params/). It relies on [**Threaded Queue mode**](../../../bonus/TQM/) for threaded, error-free and synchronized frame handling.
 
-CamGear internally employs [`streamlink`][streamlink] for [*piping live videos*](../usage/#using-camgear-with-streaming-websites) from various streaming services like [Twitch](https://www.twitch.tv/), [Livestream](https://livestream.com/), [Dailymotion](https://www.dailymotion.com/live) etc., and also utilizies [`pafy`][pafy] with [`yt_dlp`][yt_dlp] at its backend for seamless [*YouTube pipelining*](../usage/#using-camgear-with-youtube-videos).
+CamGear internally implements [`yt_dlp`][yt_dlp] backend class for seamlessly pipelining live video-frames and metadata from various streaming services like [YouTube](../usage/#using-camgear-with-youtube-videos), [Twitch](../usage/#using-camgear-with-streaming-websites), and [many more ➶](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md#supported-sites)
 
 &thinsp; 
 

diff --git a/docs/gears/camgear/params.md b/docs/gears/camgear/params.md
@@ -51,34 +51,17 @@ Its valid input can be one of the following:
     CamGear(source='/home/foo.mp4')
     ```
 
-- [x] **Streaming Services URL Address (*string*):** _Valid Video URL as input when Stream Mode is enabled(*i.e. `stream_mode=True`*)_ 
+- [x] **Streaming Services URL Address (*string*):** _Valid Video URL as input when Stream Mode is enabled(i.e. [`stream_mode=True`](#stream_mode)):_ 
 
-    !!! quote "CamGear automatically detects whether `source` belong to YouTube or elsewhere, and handles it with appropriate API."
+    CamGear internally implements `yt_dlp` backend class for pipelining live video-frames and metadata from various streaming services. For example Twitch URL can be used as follows:
 
-    * **Youtube URLs:** CamGear utilizes `pafy` with `yt_dlp` backend. For example `"https://youtu.be/bvetuLwJIkA"` as follows:
+    !!! info "Supported Streaming Websites"
 
-        ??? info "Valid YouTube URL formats"
+        The complete list of all supported Streaming Websites URLs can be found [here ➶](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md#supported-sites)
 
-            All YouTube URLS with following format are supported:
-
-            * `https://youtu.be/{video-id}`
-            * `http://www.youtube.com/watch?v={video-id}`
-            * `http://www.youtube.com/v/{video-id}`
-            * `{video-id}`
-
-        ```python
-        CamGear(source='https://youtu.be/bvetuLwJIkA', stream_mode=True)
-        ```
-
-    * **Streaming Websites URLs:** CamGear utilizes `streamlink` backend. For example `"https://www.dailymotion.com/video/x7xsoud"` as follows:
-
-        ??? info "Supported Streaming Websites"
-
-            The list of all supported Streaming Websites URLs can be found [here ➶](https://streamlink.github.io/plugin_matrix.html#plugins)
-
-        ```python
-        CamGear(source='https://www.dailymotion.com/video/x7xsoud', stream_mode=True)
-        ```
+    ```python
+    CamGear(source='https://www.twitch.tv/shroud', stream_mode=True)
+    ```
 
 - [x] **Network Address (*string*):** _Valid (`http(s)`, `rtp`, `rstp`, `rtmp`, `mms`, etc.) incoming network stream address such as `'rtsp://192.168.31.163:554/'` as input:_
 
@@ -115,18 +98,18 @@ Its valid input can be one of the following:
 
 This parameter controls the Stream Mode, .i.e if enabled(`stream_mode=True`), the CamGear API will interpret the given `source` input as YouTube URL address. 
 
-!!! bug "Due to a [**FFmpeg bug**](https://github.com/abhiTronix/vidgear/issues/133#issuecomment-638263225) that causes video to freeze frequently in OpenCV, It is advised to always use [GStreamer backend](#backend) for any livestreams _(such as Twitch)_."
-
-!!! warning "CamGear automatically enforce [GStreamer backend](#backend) for YouTube-livestreams!"
-
-!!! error "CamGear will exit with `RuntimeError` for YouTube livestreams, if OpenCV is not compiled with GStreamer(`>=v1.0.0`) support. Checkout [this FAQ](../../../help/camgear_faqs/#how-to-compile-opencv-with-gstreamer-support) for compiling OpenCV with GStreamer support."
+!!! bug "Due to a [**FFmpeg bug**](https://github.com/abhiTronix/vidgear/issues/133#issuecomment-638263225) that causes video to freeze frequently in OpenCV, It is advised to always use [GStreamer backend](#backend) for any livestream videos. Checkout [this FAQ](../../../help/camgear_faqs/#how-to-compile-opencv-with-gstreamer-support) for compiling OpenCV with GStreamer support."
 
 **Data-Type:** Boolean
 
 **Default Value:** Its default value is `False`. 
 
 **Usage:**
 
+!!! info "Supported Streaming Websites"
+
+    The complete list of all supported Streaming Websites URLs can be found [here ➶](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md#supported-sites)
+
 ```python
 CamGear(source='https://youtu.be/bvetuLwJIkA', stream_mode=True)
 ```

diff --git a/docs/gears/camgear/usage.md b/docs/gears/camgear/usage.md
@@ -66,96 +66,221 @@ stream.stop()
 
 ## Using Camgear with Streaming Websites
 
-CamGear API provides direct support for piping video streams from various popular streaming services like [Twitch](https://www.twitch.tv/), [Vimeo](https://vimeo.com/), [Dailymotion](https://www.dailymotion.com), and [many more ➶](https://streamlink.github.io/plugin_matrix.html#plugins). All you have to do is to provide the desired Video's URL to its `source` parameter, and enable the [`stream_mode`](../params/#stream_mode) parameter. The complete usage example is as follows:
+CamGear internally implements [`yt_dlp`]() backend class for seamlessly pipelining live video-frames and metadata from various streaming services like [Twitch](https://www.twitch.tv/), [Vimeo](https://vimeo.com/), [Dailymotion](https://www.dailymotion.com), and [many more ➶](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md#supported-sites). All you have to do is to provide the desired Video's URL to its `source` parameter, and enable its [`stream_mode`](../params/#stream_mode) parameter. 
 
-!!! bug "Bug in OpenCV's FFmpeg"
-    To workaround a [**FFmpeg bug**](https://github.com/abhiTronix/vidgear/issues/133#issuecomment-638263225) that causes video to freeze frequently, You must always use [GStreamer backend](../params/#backend) for  Livestreams _(such as Twitch URLs)_. 
+The complete usage example for Dailymotion and Twitch URLs are as follows:
+
+
+??? bug "Bug in OpenCV's FFmpeg"
+
+    To workaround a [**FFmpeg bug**](https://github.com/abhiTronix/vidgear/issues/133#issuecomment-638263225) that causes video to freeze frequently in OpenCV, It is advised to always use [GStreamer backend](../params/#backend) for Livestream videos.
 
     **Checkout [this FAQ ➶](../../../help/camgear_faqs/#how-to-compile-opencv-with-gstreamer-support) for compiling OpenCV with GStreamer support.**
 
-??? info "Exclusive CamGear Attributes"
+    !!! fail "Not all resolutions are supported with GStreamer Backend. See issue #244"
+
+???+ info "Exclusive CamGear Attributes for `yt_dlp` backend"
+
     CamGear also provides exclusive attributes: 
 
     - `STREAM_RESOLUTION` _(for specifying stream resolution)_
-    - `STREAM_PARAMS` _(for specifying underlying API(i.e. [streamlink](https://streamlink.github.io/)) parameters)_ 
+    - `STREAM_PARAMS` _(for specifying  `yt_dlp` parameters)_ 
 
     with its [`options`](../params/#options) dictionary parameter. **More information can be found [here ➶](../advanced/source_params/#exclusive-camgear-parameters)**
 
-```python  hl_lines="12-13"
-# import required libraries
-from vidgear.gears import CamGear
-import cv2
 
-# set desired quality as 720p
-options = {"STREAM_RESOLUTION": "720p"}
+??? note "Supported Streaming Websites"
 
-# Add any desire Video URL as input source
-# for e.g https://vimeo.com/151666798
-# and enable Stream Mode (`stream_mode = True`)
-stream = CamGear(
-    source="https://vimeo.com/151666798",
-    stream_mode=True,
-    logging=True,
-    **options
-).start()
+    The list of all supported Streaming Websites URLs can be found [here ➶](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md#supported-sites)
 
-# loop over
-while True:
 
-    # read frames from stream
-    frame = stream.read()
+??? tip "Accessing Stream's Metadata"
 
-    # check for frame if Nonetype
-    if frame is None:
-        break
+    CamGear now provides `ytv_metadata` global parameter for accessing given Video's metadata as JSON Object. It can used as follows:
 
-    # {do something with the frame here}
+    ??? new "New in v0.2.4" 
+        `ytv_metadata` global parameter was added in `v0.2.4`.
 
-    # Show output window
-    cv2.imshow("Output", frame)
+    ```python
+    # import required libraries
+    from vidgear.gears import CamGear
 
-    # check for 'q' key if pressed
-    key = cv2.waitKey(1) & 0xFF
-    if key == ord("q"):
-        break
+    # Add YouTube Video URL as input source (for e.g https://www.dailymotion.com/video/x2yrnum)
+    # and enable Stream Mode (`stream_mode = True`)
+    stream = CamGear(
+        source="https://www.dailymotion.com/video/x2yrnum", stream_mode=True, logging=True, **options
+    ).start()
 
-# close output window
-cv2.destroyAllWindows()
+    # get Video's metadata as JSON object
+    video_metadata =  stream.ytv_metadata
+
+    # print all available keys
+    print(video_metadata.keys())
+
+    # get data like `title`
+    print(video_metadata["title"])
+    ```
+
+=== "Dailymotion"
+    ```python  hl_lines="12-13"
+    # import required libraries
+    from vidgear.gears import CamGear
+    import cv2
+
+    # set desired quality as 720p
+    options = {"STREAM_RESOLUTION": "720p"}
+
+    # Add any desire Video URL as input source
+    # for e.g https://vimeo.com/151666798
+    # and enable Stream Mode (`stream_mode = True`)
+    stream = CamGear(
+        source="https://www.dailymotion.com/video/x2yrnum",
+        stream_mode=True,
+        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)
+
+        # 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()
+    ```
+=== "Twitch"
+
+    !!! warning "If Twitch user is offline, CamGear will throw ValueError."
+
+    ```python  hl_lines="12-13"
+    # import required libraries
+    from vidgear.gears import CamGear
+    import cv2
+
+    # set desired quality as 720p
+    options = {"STREAM_RESOLUTION": "720p"}
+
+    # Add any desire Video URL as input source
+    # for e.g hhttps://www.twitch.tv/shroud
+    # and enable Stream Mode (`stream_mode = True`)
+    stream = CamGear(
+        source="https://www.twitch.tv/shroud",
+        stream_mode=True,
+        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)
+
+        # 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()
+    ```
 
-# safely close video stream
-stream.stop()
-```
 
 &nbsp; 
 
 ## Using Camgear with Youtube Videos
 
-CamGear API provides direct support for **YouTube Livestream _(with GStreamer)_ + Normal Video frames pipelining**. All you have to do is to provide the desired YouTube Video's URL to its `source` parameter and enable the [`stream_mode`](../params/#stream_mode) parameter. 
+CamGear API also provides out-of-the-box support for pipelining live video-frames and metadata from **YouTube (Livestream + Normal) Videos**. 
+
+!!! fail "YouTube Playlists are not supported yet."
 
 The complete usage example is as follows:
 
-!!! warning "To workaround a [**FFmpeg bug**](https://github.com/abhiTronix/vidgear/issues/133#issuecomment-638263225), CamGear automatically enforces [GStreamer backend](../params/#backend) for YouTube-livestreams! Checkout [this FAQ](../../../help/camgear_faqs/#how-to-compile-opencv-with-gstreamer-support) for compiling OpenCV with GStreamer support."
+??? bug "Bug in OpenCV's FFmpeg"
 
-!!! bug "Not all resolutions are supported with YouTube Livestreams. See issue #244"
+    To workaround a [**FFmpeg bug**](https://github.com/abhiTronix/vidgear/issues/133#issuecomment-638263225) that causes video to freeze frequently in OpenCV, It is advised to always use [GStreamer backend](../params/#backend) for Livestream videos.
 
-??? info "Exclusive CamGear Attributes"
-    CamGear also provides exclusive attributes:
+    **Checkout [this FAQ ➶](../../../help/camgear_faqs/#how-to-compile-opencv-with-gstreamer-support) for compiling OpenCV with GStreamer support.**
 
-    - `STREAM_RESOLUTION`: _(for specifying stream resolution)_
-    - `STREAM_PARAMS`: _(for specifying underlying API(i.e. [yt_dlp](https://github.com/yt-dlp/yt-dlp)) parameters)_ 
+    !!! fail "Not all resolutions are supported with GStreamer Backend. See issue #244"
+
 
+??? info "Exclusive CamGear Attributes for `yt_dlp` backend"
+
+    CamGear also provides exclusive attributes: 
+
+    - `STREAM_RESOLUTION` _(for specifying stream resolution)_
+    - `STREAM_PARAMS` _(for specifying  `yt_dlp` parameters)_ 
+
     with its [`options`](../params/#options) dictionary parameter. **More information can be found [here ➶](../advanced/source_params/#exclusive-camgear-parameters)**
 
 
+??? tip "Accessing Stream's Metadata"
+
+    CamGear now provides `ytv_metadata` global parameter for accessing given Video's metadata as JSON Object. It can used as follows:
+
+    ??? new "New in v0.2.4" 
+        `ytv_metadata` global parameter was added in `v0.2.4`.
+
+    ```python
+    # import required libraries
+    from vidgear.gears import CamGear
+
+    # Add YouTube Video URL as input source (for e.g https://youtu.be/uCy5OuSQnyA)
+    # and enable Stream Mode (`stream_mode = True`)
+    stream = CamGear(
+        source="https://youtu.be/uCy5OuSQnyA", stream_mode=True, logging=True, **options
+    ).start()
+
+    # get Video's metadata as JSON object
+    video_metadata =  stream.ytv_metadata
+
+    # print all available keys
+    print(video_metadata.keys())
+
+    # get data like `title`
+    print(video_metadata["title"])
+    ```
+
 ```python hl_lines="8-9"
 # import required libraries
 from vidgear.gears import CamGear
 import cv2
 
-# Add YouTube Video URL as input source (for e.g https://youtu.be/bvetuLwJIkA)
+# Add YouTube Video URL as input source (for e.g https://youtu.be/uCy5OuSQnyA)
 # and enable Stream Mode (`stream_mode = True`)
 stream = CamGear(
-    source="https://youtu.be/bvetuLwJIkA", 
+    source="https://youtu.be/uCy5OuSQnyA", 
     stream_mode=True,
     logging=True
 ).start()
-Original file line number
+Diff line change
@@ Expand Up / @@ -126,10 +126,6 @@ limitations under the License. @@
     &nbsp;
-    ::: vidgear.gears.helper.youtube_url_validator
-    &nbsp;
     ::: vidgear.gears.helper.validate_auth_keys
@@ Expand Down @@