✨ Release DeFFcode Stable v0.2.5 [#37]

FFdecoder: 
- 🩹 Added OpenCV compatibility patch for YUV pixel-formats. (Fixes #30)
  - ⚡ Implemented new patch for handling YUV pixel-formats(such as `YUV420p`, `yuv444p`, `NV12`, `NV21` etc.) for exclusive compatibility with OpenCV APIs.
    - 📝 Note: Only YUV pixel-formats starting with `YUV` and `NV` are currently supported.
  - ✨ Added new `-enforce_cv_patch` boolean attribute for enabling OpenCV compatibility patch.
  - 🐛 Fixed Zero division bug while calculating `raw_bit_per_component`.
- 🔊 Updated log message.

FFhelper:
- 🎨 Replaced depreciating `Retry` API from `requests.packages` with `requests.adapters`.
- 🚑️ Fixed response.headers returning `content-length` as Nonetype since it may not necessarily have the Content-Length header set.
  - 💬 Reason: The response from gitlab.com  contains a Transfer-Encoding field as `'Transfer-Encoding': 'chunked'`, which means data is sent in a series of chunks, so the Content-Length header is emitted. More info: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding#Directives

Sourcer: 
  - ✨ Added Looping Video support. (Fixes #28)
    - 💬 Now raw-frame numbers revert to null(`None`) whenever any looping is defined through filter(such as `-filter_complex "loop=loop=3:size=75:start=25"`) or prefix(`"-ffprefixes":["-stream_loop", "3"]`).

Maintenance:
- ♻️ Replaced `raw.github.com` links with GitLab CDN links.
- 🗑️ Removed unused code.

Setup:
- 🔥 Removed unused imports and patches.

Docs: 
- ♻️ Refactored docs for Decoding and Transcoding recipes.
  - 📝 Updated Decoding Video files doc:
    - ✨ Added YUV frames example code for `Capturing and Previewing BGR frames from a video file` recipe.
    - 🚸 Updated text and admonitions.
    - 🔥 Removed depreciated text.
  - 📝 Updated Transcoding Live frames doc:
    - ✨ Added YUV frames example code for `Transcoding video using OpenCV VideoWriter API` recipe.
    - ✨ Added YUV frames example code for `Transcoding lossless video using WriteGear API` recipe.
    - 🚸 Updated text and admonitions.
    - 🔥 Removed depreciated text.
  - 📝 Updated Hardware-Accelerated Video Decoding doc:
    - Updated abstract text.
    - ✨ Added new python dependency block for recipes.
    - ✨ Added new `CUVID-accelerated Hardware-based Video Decoding and Previewing` recipe.
    - ✨ Added new `CUDA-accelerated Hardware-based Video Decoding and Previewing` recipe.
    - 📝 Reflected new OpenCV compatibility patch for YUV pixel-formats in code.
    - 🚸 Updated recipe assumptions.
    - 🧑‍💻 Updated recipe code.
    - 🔥 Removed old recipe.
  - 📝 Updated Hardware-Accelerated Video Transcoding doc:
    - 📄 Updated abstract text.
    - 📄 Updated `Limitation: Bottleneck in Hardware-Accelerated Video Transcoding performance with Real-time Frame processing` passage.
    - ✨ Added new python dependency block for recipes.
    - ✨ Added new `CUDA-accelerated Video Transcoding with OpenCV's VideoWriter API` recipe.
    - ✨ Added new `CUDA-NVENC-accelerated Video Transcoding with WriteGear API` recipe both for consuming BGR and NV12 frames.
    - ✨ Added new `CUDA-NVENC-accelerated End-to-end Lossless Video Transcoding with WriteGear API` recipe which is still WIP(💬confirmed with a GIF from tenor).
    - 📝 Reflected new OpenCV compatibility patch for YUV pixel-formats in code.
    - 🚸 Updated recipe assumptions.
    - 🧑‍💻 Updated recipe code.
    - 🔥 Removed old recipe and unnecessary text.
  - 📝 Updated FFdecoder `params.md`:
    - ✨ Added docs for `-enforce_cv_patch` boolean attribute in `ffparam` dictionary parameter.
    -🔥 Removed depreciated text.
    - ✏️ Fixed typos.
- 📝 Added docs for Looping Video support.
  - ✨ Added new `Capturing and Previewing frames from a Looping Video` recipe using `-stream_loop` option and `loop` filter".
  - 🚸 Updated text and admonitions.
  - 📝 Updated docs hyperlinks in index.md
  - 📝 Updated and corrected docs hyperlinks in ReadMe.md
- 📝 Fixed badges/shields#8671 badge issue in README.md
- 📝 Replaced `raw.github.com` links with GitLab and GH links.
- 💄 Added new `content.code.copy` and `content.code.link` features.
- 💄 Updated `Readme.md` GIF URLs.
- 💄 Updated `Readme.md` banner image URLs.
- 📄 Update Zenodo Badge and BibTex entry.
- 💄 Updated md-typeset text font size to `.75rem`.
- 📝 Updated docs hyperlinks in index.md
- 📝 Updated and corrected docs hyperlinks in ReadMe.md
- 📝 Updated `changelog.md`.
- ✏️ Fixed several typos and minor tweaks.
- ♻️ Refactored custom.css.

CI: 
- 👷 Updated `test_source` to test looping video support.
- 👷 Updated `test_frame_format` test to include `-enforce_cv_patch` boolean attribute.
- 🚑️ CI: Added fix for codecov upload bug (codecov/codecov-action#598).
  - 👷 Updated `codecov-action` workflow to `v3.
  - 👷 Added new `CODECOV_TOKEN` GitHub secret.

.github/workflows/CIlinux.yml

@@ -69,9 +69,10 @@ jobs:
           flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
         if: success()
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v2
+        uses: codecov/codecov-action@v3
         with:
           name: ${{ matrix.python-version }}
+          token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true
           verbose: true
         if: ${{ env.EXIT_CODE != '124' }}

deffcode/ffdecoder.py

@@ -199,6 +199,15 @@ def __init__(
         # handle valid FFmpeg assets location
         self.__ffmpeg = self.__sourcer_metadata["ffmpeg_binary_path"]
 
+        # handle YUV pixel formats(such as `yuv420p`, `yuv444p`, `nv12`, `nv21` etc.)
+        # patch for compatibility with OpenCV APIs.
+        self.__cv_patch = self.__extra_params.pop("-enforce_cv_patch", False)
+        if not (isinstance(self.__cv_patch, bool)):
+            self.__cv_patch = False
+            self.__verbose_logs and logger.critical(
+                "Enforcing OpenCV compatibility patch for YUV/NV frames."
+            )
+
         # handle pass-through audio mode works in conjunction with WriteGear [TODO]
         self.__passthrough_mode = self.__extra_params.pop("-passthrough_audio", False)
         if not (isinstance(self.__passthrough_mode, bool)):
@@ -428,7 +437,9 @@ def formulate(self):
                 for x in self.__ff_pixfmt_metadata
                 if x[0] == rawframe_pixfmt
             ][0]
-            raw_bit_per_component = rawframesbpp // self.__raw_frame_depth
+            raw_bit_per_component = (
+                rawframesbpp // self.__raw_frame_depth if self.__raw_frame_depth else 0
+            )
             if 4 <= raw_bit_per_component <= 8:
                 self.__raw_frame_dtype = np.dtype("u1")
             elif 8 < raw_bit_per_component <= 16 and rawframe_pixfmt.endswith(
@@ -598,7 +609,7 @@ def formulate(self):
                 self.__raw_frame_num = None
                 # log that number of frames are unknown
                 self.__verbose_logs and logger.info(
-                    "Live/Network Stream detected! Number of frames in given source are not known."
+                    "Number of frames in given source are unknown. Live/Network/Looping stream detected!"
                 )
 
             # log Mode of Operation
@@ -626,11 +637,15 @@ def __fetchNextfromPipeline(self):
             self.__process is None
         ), "Pipeline is not running! You must call `formulate()` method first."
 
-        # formulated raw frame size
+        # formulated raw frame size and apply YUV pixel formats patch(if applicable)
         raw_frame_size = (
-            self.__raw_frame_depth
-            * self.__raw_frame_resolution[0]
-            * self.__raw_frame_resolution[1]
+            (self.__raw_frame_resolution[0] * (self.__raw_frame_resolution[1] * 3 // 2))
+            if self.__raw_frame_pixfmt.startswith(("yuv", "nv")) and self.__cv_patch
+            else (
+                self.__raw_frame_depth
+                * self.__raw_frame_resolution[0]
+                * self.__raw_frame_resolution[1]
+            )
         )
         # next dataframe as numpy ndarray
         nparray = None
@@ -668,6 +683,12 @@ def __fetchNextFrame(self):
                     self.__raw_frame_depth,
                 )
             )[:, :, 0]
+        elif self.__raw_frame_pixfmt.startswith(("yuv", "nv")) and self.__cv_patch:
+            # reconstruct exclusive YUV formats frames for OpenCV APIs
+            frame = frame.reshape(
+                self.__raw_frame_resolution[1] * 3 // 2,
+                self.__raw_frame_resolution[0],
+            )
         else:
             # reconstruct default frames
             frame = frame.reshape(

deffcode/ffhelper.py

@@ -27,8 +27,7 @@
 
 from tqdm import tqdm
 from pathlib import Path
-from requests.adapters import HTTPAdapter
-from requests.packages.urllib3.util.retry import Retry
+from requests.adapters import HTTPAdapter, Retry
 
 # import utils packages
 from .utils import logger_handler, delete_file_safe
@@ -48,7 +47,7 @@ class TimeoutHTTPAdapter(HTTPAdapter):
     A custom Transport Adapter with default timeouts
     """
 
-    def __init__(self, *args, **kwargs): 
+    def __init__(self, *args, **kwargs):
         self.timeout = DEFAULT_TIMEOUT
         if "timeout" in kwargs:
             self.timeout = kwargs["timeout"]
@@ -215,7 +214,11 @@ def download_ffmpeg_binaries(path, os_windows=False, os_bit=""):
                     http.mount("https://", adapter)
                     response = http.get(file_url, stream=True)
                     response.raise_for_status()
-                    total_length = response.headers.get("content-length")
+                    total_length = (
+                        response.headers.get("content-length")
+                        if "content-length" in response.headers
+                        else len(response.content)
+                    )
                     assert not (
                         total_length is None
                     ), "[Helper:ERROR] :: Failed to retrieve files, check your Internet connectivity!"

deffcode/sourcer.py

@@ -362,6 +362,12 @@ def retrieve_metadata(self, pretty_json=False, force_retrieve_missing=False):
                 "approx_video_nframes": (
                     int(self.__approx_video_nframes)
                     if self.__approx_video_nframes
+                    and not any(
+                        "loop" in x for x in self.__ffmpeg_prefixes
+                    )  # check if any loops in prefix
+                    and not any(
+                        "loop" in x for x in dict2Args(self.__sourcer_params)
+                    )  # check if any loops in filters
                     else None
                 ),
                 "source_video_bitrate": self.__default_video_bitrate,

deffcode/version.py

@@ -1 +1 @@
-__version__ = "0.2.4"
+__version__ = "0.2.5"

docs/changelog.md

@@ -20,7 +20,83 @@ limitations under the License.
 
 # Release Notes
 
-## v0.2.4 (2022-10-07) :material-new-box:
+## v0.2.5 (2023-01-11) :material-new-box:
+
+??? new "New Features"
+    - [x] **FFdecoder:**
+        * Added OpenCV compatibility patch for YUV pixel-formats.
+            * Implemented new patch for handling YUV pixel-formats(such as `YUV420p`, `yuv444p`, `NV12`, `NV21` etc.) for exclusive compatibility with OpenCV APIs.
+                * **Note:** Only YUV pixel-formats starting with `YUV` and `NV` are currently supported.
+            * Added new `-enforce_cv_patch` boolean attribute for enabling OpenCV compatibility patch.
+	- [x] **Sourcer:**
+		* Added Looping Video support.
+			* Now raw-frame numbers revert to null(`None`) whenever any looping is defined through filter(such as `-filter_complex "loop=loop=3:size=75:start=25"`) or prefix(`"-ffprefixes":["-stream_loop", "3"]`).
+    - [x] **Docs:** 
+        * Added YUV frames example code for `Capturing and Previewing BGR frames from a video file` recipe.
+		* Added YUV frames example code for `Transcoding video using OpenCV VideoWriter API recipe.
+		* Added YUV frames example code for `Transcoding lossless video using WriteGear API recipe.
+		* Added new CUVID-accelerated Hardware-based Video Decoding and Previewing recipe.
+		* Added new CUDA-accelerated Hardware-based Video Decoding and Previewing recipe.
+		* Added new CUDA-accelerated Video Transcoding with OpenCV`s VideoWriter API recipe.
+		* Added new CUDA-NVENC-accelerated Video Transcoding with WriteGear API recipe both for consuming BGR and NV12 frames.
+		* Added new CUDA-NVENC-accelerated End-to-end Lossless Video Transcoding with WriteGear API recipe which is still WIP(💬confirmed with a GIF from tenor).
+		* Added new Capturing and Previewing frames from a Looping Video recipe using `-stream_loop` option and `loop` filter.
+		* Added docs for `-enforce_cv_patch` boolean attribute in `ffparam` dictionary parameter.
+		* Added new python dependency block for recipes.
+		* Reflected new OpenCV compatibility patch for YUV pixel-formats in code.
+		* Added new `content.code.copy` and `content.code.link` features.
+
+??? success "Updates/Improvements"  
+    - [x] FFhelper:
+		* Replaced depreciating `Retry` API from `requests.packages` with `requests.adapters`.
+	- [x] Maintenance: 
+		* Replaced `raw.github.com` links with GitLab and GH links.
+		* Removed unused code.
+        * Updated log message.
+    - [x] CI:
+        * Updated `test_FFdecoder_params` unittest to include `with` statement access method.
+		* Updated `test_frame_format` test to include `-enforce_cv_patch` boolean attribute.
+		* Updated `test_source` to test looping video support.
+    - [x] Setup:
+        * Removed unused imports and patches.
+        * Bumped version to `0.2.5`.
+    - [x] Docs:
+		* Updated Limitation: Bottleneck in Hardware-Accelerated Video Transcoding performance with Real-time Frame processing passage.
+		* Updated and corrected docs hyperlinks in index.md and ReadMe.md
+		* Update Zenodo Badge and BibTex entry.
+		* Updated `Readme.md` banner image URLs.
+		* Updated md-typeset text font size to `.75rem`.
+		* Updated text and admonitions.
+		* Updated recipe assumptions.
+		* Updated `Readme.md` GIF URLs.
+		* Updated abstract text in recipes.
+        * Updated `changelog.md`.
+		* Updated recipe code.
+		* Removed old recipes.
+
+??? bug "Bug-fixes"
+    - [x] FFdecoder API:
+        * Fixed Zero division bug while calculating `raw_bit_per_component`.
+	- [x] FFhelper:
+		* Fixed response.headers returning `content-length` as Nonetype since it may not necessarily have the Content-Length header set.
+  			* **Reason:** The response from gitlab.com  contains a Transfer-Encoding field as `'Transfer-Encoding': 'chunked'`, which means data is sent in a series of chunks, so the Content-Length header is emitted. More info: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding#Directives
+    - [x] Docs:
+        * Fixed https://github.com/badges/shields/issues/8671 badge issue in README.md
+		* Removed depreciated text.
+        * Fixed several typos in docs.
+    - [x] CI:
+        * Added fix for codecov upload bug (https://github.com/codecov/codecov-action/issues/598).
+            * Updated `codecov-action` workflow to `v3.
+            * Added new `CODECOV_TOKEN` GitHub secret.
+
+??? question "Pull Requests"
+    * PR #37
+
+  
+
+  
+
+## v0.2.4 (2022-10-07)
 
 ??? new "New Features"
     - [x] **FFdecoder API:**

docs/index.md

@@ -197,18 +197,18 @@ 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.6984364.svg)](https://doi.org/10.5281/zenodo.6984364)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7155399.svg)](https://doi.org/10.5281/zenodo.7155399)
 
 ```BibTeX
 @software{deffcode,
-  author       = {Abhishek Thakur},
-  title        = {abhiTronix/deffcode: v0.2.3},
-  month        = aug,
+  author       = {Abhishek Singh Thakur},
+  title        = {abhiTronix/deffcode: v0.2.4},
+  month        = oct,
   year         = 2022,
   publisher    = {Zenodo},
-  version      = {v0.2.3},
-  doi          = {10.5281/zenodo.6984364},
-  url          = {https://doi.org/10.5281/zenodo.6984364}
+  version      = {v0.2.4},
+  doi          = {10.5281/zenodo.7155399},
+  url          = {https://doi.org/10.5281/zenodo.7155399}
 }
 ```