deffcode 0.2.7__tar.gz → 0.2.8__tar.gz

{deffcode-0.2.7 → deffcode-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deffcode
-Version: 0.2.7
+Version: 0.2.8
 Summary: A cross-platform High-performance & Flexible Real-time Video Frames Decoder in Python.
 Author-email: Abhishek Thakur <abhi.una12@gmail.com>
 License: Apache License 2.0
@@ -22,11 +22,11 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Education
 Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cython
@@ -113,7 +113,7 @@ Here are some key features that stand out:
 - Effortless [**Metadata Extraction**][extracting-video-metadata] from all streams available in the source.
 - Maintains the standard easy to learn [**OpenCV-Python**](https://docs.opencv.org/4.x/d6/d00/tutorial_py_root.html) coding syntax.
 - Out-of-the-box support for all prominent Computer Vision libraries.
-- Cross-platform, runs on Python 3.10+, and easy to install.
+- Cross-platform, runs on Python 3.11+, and easy to install.
 
 <!--
 - [x] Lossless Transcoding support with [WriteGear](https://abhitronix.github.io/deffcode/latest/gears/writegear/introduction/). #TODO
@@ -235,6 +235,8 @@ Once you have DeFFcode installed, checkout our Well-Documented **[Recipes 🍱][
 - [CUDA-NVENC-accelerated Video Transcoding with WriteGear API][cuda-nvenc-accelerated-video-transcoding-with-writegear-api]
 - [CUDA-NVENC-accelerated End-to-end Lossless Video Transcoding with WriteGear API][cuda-nvenc-accelerated-end-to-end-lossless-video-transcoding-with-writegear-api]
 - [Multi-Input Source Configurations][multi-input-source-configurations]
+  - [Decoding multiple inputs as 2x2 video grid _(mosaic)_][decoding-multiple-inputs-as-2x2-video-grid-mosaic]
+  - [Decoding crossfade transition between multiple inputs][decoding-crossfade-transition-between-multiple-inputs]
 
 </details>
 
@@ -271,9 +273,8 @@ decoder = FFdecoder("https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1
 
 # grab RGB24(default) 3D frames from decoder
 for frame in decoder.generateFrame():
-
     # lets print its shape
-    print(frame.shape) # (1080, 1920, 3)
+    print(frame.shape)  # (1080, 1920, 3)
 
 # terminate the decoder
 decoder.terminate()
@@ -288,7 +289,9 @@ The primary function of [**Sourcer API**][sourcer-api] is to **gather metadata i
 from deffcode import Sourcer
 
 # initialize and formulate the decoder using suitable source
-sourcer = Sourcer("https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1MB.mp4").probe_stream()
+sourcer = Sourcer(
+    "https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1MB.mp4"
+).probe_stream()
 
 # print metadata as `json.dump`
 print(sourcer.retrieve_metadata(pretty_json=True))
@@ -354,18 +357,24 @@ 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.12689394.svg)](https://doi.org/10.5281/zenodo.12689394)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19658542.svg)](https://doi.org/10.5281/zenodo.19658542)
 
 ```BibTeX
 @software{deffcode,
   author       = {Abhishek Thakur},
-  title        = {abhiTronix/deffcode: v0.2.6},
-  month        = jul,
-  year         = 2024,
+  title        = {abhiTronix/deffcode: v0.2.7},
+  month        = apr,
+  year         = 2026,
   publisher    = {Zenodo},
-  version      = {v0.2.6},
-  doi          = {10.5281/zenodo.12689394},
-  url          = {https://doi.org/10.5281/zenodo.12689394},
+  version      = {v0.2.7},
+  doi          = {10.5281/zenodo.19658542},
+  url          = {https://doi.org/10.5281/zenodo.19658542},
+  swhid        = {swh:1:dir:85e8dfd087aed870deb4043c532faaa9b156d1e1
+                   ;origin=https://doi.org/10.5281/zenodo.6976947;vis
+                   it=swh:1:snp:af1b478890801c02d56b95f563b86761980bf
+                   82c;anchor=swh:1:rel:85f9af4452f8030317ec2012acc10
+                   29e8a945e2d;path=abhiTronix-deffcode-5162649
+                  },
 }
 ```
 
@@ -478,6 +487,8 @@ Advanced Recipes
 [smart-keyframe-only-decoding-for-heavy-ai-inference]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/extract-frame-metadata/#smart-keyframe-only-decoding-for-heavy-ai-inference
 [variable-frame-rate-vfr-synchronization-via-pts_time]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/extract-frame-metadata/#variable-frame-rate-vfr-synchronization-via-pts_time
 [multi-input-source-configurations]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_input/#multi-input-source-configurations
+[decoding-multiple-inputs-as-2x2-video-grid-mosaic]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_input/#decoding-multiple-inputs-as-2x2-video-grid-mosaic
+[decoding-crossfade-transition-between-multiple-inputs]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_input/#decoding-crossfade-transition-between-multiple-inputs
 
 <!--
 CI Apps URLs

{deffcode-0.2.7 → deffcode-0.2.8}/README.md

@@ -73,7 +73,7 @@ Here are some key features that stand out:
 - Effortless [**Metadata Extraction**][extracting-video-metadata] from all streams available in the source.
 - Maintains the standard easy to learn [**OpenCV-Python**](https://docs.opencv.org/4.x/d6/d00/tutorial_py_root.html) coding syntax.
 - Out-of-the-box support for all prominent Computer Vision libraries.
-- Cross-platform, runs on Python 3.10+, and easy to install.
+- Cross-platform, runs on Python 3.11+, and easy to install.
 
 <!--
 - [x] Lossless Transcoding support with [WriteGear](https://abhitronix.github.io/deffcode/latest/gears/writegear/introduction/). #TODO
@@ -195,6 +195,8 @@ Once you have DeFFcode installed, checkout our Well-Documented **[Recipes 🍱][
 - [CUDA-NVENC-accelerated Video Transcoding with WriteGear API][cuda-nvenc-accelerated-video-transcoding-with-writegear-api]
 - [CUDA-NVENC-accelerated End-to-end Lossless Video Transcoding with WriteGear API][cuda-nvenc-accelerated-end-to-end-lossless-video-transcoding-with-writegear-api]
 - [Multi-Input Source Configurations][multi-input-source-configurations]
+  - [Decoding multiple inputs as 2x2 video grid _(mosaic)_][decoding-multiple-inputs-as-2x2-video-grid-mosaic]
+  - [Decoding crossfade transition between multiple inputs][decoding-crossfade-transition-between-multiple-inputs]
 
 </details>
 
@@ -231,9 +233,8 @@ decoder = FFdecoder("https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1
 
 # grab RGB24(default) 3D frames from decoder
 for frame in decoder.generateFrame():
-
     # lets print its shape
-    print(frame.shape) # (1080, 1920, 3)
+    print(frame.shape)  # (1080, 1920, 3)
 
 # terminate the decoder
 decoder.terminate()
@@ -248,7 +249,9 @@ The primary function of [**Sourcer API**][sourcer-api] is to **gather metadata i
 from deffcode import Sourcer
 
 # initialize and formulate the decoder using suitable source
-sourcer = Sourcer("https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1MB.mp4").probe_stream()
+sourcer = Sourcer(
+    "https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1MB.mp4"
+).probe_stream()
 
 # print metadata as `json.dump`
 print(sourcer.retrieve_metadata(pretty_json=True))
@@ -314,18 +317,24 @@ 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.12689394.svg)](https://doi.org/10.5281/zenodo.12689394)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19658542.svg)](https://doi.org/10.5281/zenodo.19658542)
 
 ```BibTeX
 @software{deffcode,
   author       = {Abhishek Thakur},
-  title        = {abhiTronix/deffcode: v0.2.6},
-  month        = jul,
-  year         = 2024,
+  title        = {abhiTronix/deffcode: v0.2.7},
+  month        = apr,
+  year         = 2026,
   publisher    = {Zenodo},
-  version      = {v0.2.6},
-  doi          = {10.5281/zenodo.12689394},
-  url          = {https://doi.org/10.5281/zenodo.12689394},
+  version      = {v0.2.7},
+  doi          = {10.5281/zenodo.19658542},
+  url          = {https://doi.org/10.5281/zenodo.19658542},
+  swhid        = {swh:1:dir:85e8dfd087aed870deb4043c532faaa9b156d1e1
+                   ;origin=https://doi.org/10.5281/zenodo.6976947;vis
+                   it=swh:1:snp:af1b478890801c02d56b95f563b86761980bf
+                   82c;anchor=swh:1:rel:85f9af4452f8030317ec2012acc10
+                   29e8a945e2d;path=abhiTronix-deffcode-5162649
+                  },
 }
 ```
 
@@ -438,6 +447,8 @@ Advanced Recipes
 [smart-keyframe-only-decoding-for-heavy-ai-inference]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/extract-frame-metadata/#smart-keyframe-only-decoding-for-heavy-ai-inference
 [variable-frame-rate-vfr-synchronization-via-pts_time]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/extract-frame-metadata/#variable-frame-rate-vfr-synchronization-via-pts_time
 [multi-input-source-configurations]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_input/#multi-input-source-configurations
+[decoding-multiple-inputs-as-2x2-video-grid-mosaic]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_input/#decoding-multiple-inputs-as-2x2-video-grid-mosaic
+[decoding-crossfade-transition-between-multiple-inputs]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_input/#decoding-crossfade-transition-between-multiple-inputs
 
 <!--
 CI Apps URLs

{deffcode-0.2.7 → deffcode-0.2.8}/deffcode/ffdecoder.py

@@ -30,7 +30,7 @@ import threading
 from collections import OrderedDict
 from collections.abc import Generator
 from types import TracebackType
-from typing import Any
+from typing import Any, Self
 
 import numpy as np
 
@@ -226,6 +226,9 @@ class FFdecoder:
         if {"-vf", "-filter_complex"}.intersection(self.__extra_params.keys()):
             key = "-vf" if "-vf" in self.__extra_params else "-filter_complex"
             sourcer_params[key] = self.__extra_params[key]
+        # multi-input output streams are selected via `-map`, so probe with it too
+        if self.__is_multi and "-map" in self.__extra_params:
+            sourcer_params["-map"] = self.__extra_params["-map"]
 
         # define dict to store user-defined parameters
         self.__user_metadata = {}
@@ -364,7 +367,7 @@ class FFdecoder:
             # reset improper values
             self.__custom_resolution = None
 
-    def formulate(self) -> FFdecoder:
+    def formulate(self) -> Self:
         """
         This method formulates all necessary FFmpeg pipeline arguments and executes it inside the FFmpeg `subprocess` pipe.
 
@@ -662,7 +665,9 @@ class FFdecoder:
             if "-frames:v" in input_params:
                 self.__raw_frame_num = input_params["-frames:v"]
             elif (
-                self.__sourcer_metadata["approx_video_nframes"] is not None
+                # composite output length is unrelated to the primary source's length
+                not self.__is_multi
+                and self.__sourcer_metadata["approx_video_nframes"] is not None
                 and self.__sourcer_metadata["approx_video_nframes"] > 0
             ):
                 self.__raw_frame_num = self.__sourcer_metadata["approx_video_nframes"]
@@ -956,7 +961,7 @@ class FFdecoder:
                 )
                 if _src_meta.get("source_demuxer"):
                     cmd += ["-f", _src_meta["source_demuxer"]]
-                cmd += ["-i", _src]
+                cmd += ["-i", _src_meta.get("source", _src)]
         else:
             cmd += self.__ffmpeg_prefixes
             cmd += input_parameters

{deffcode-0.2.7 → deffcode-0.2.8}/deffcode/ffhelper.py

@@ -42,8 +42,14 @@ logger.propagate = False
 logger.addHandler(logger_handler())
 logger.setLevel(logging.DEBUG)
 
+# set default timeout for subprocesses
+MAX_TIMEOUT_SUBPROCESS: float = float(os.getenv("MAX_TIMEOUT_SUBPROCESS", 10.0))
+# set grace period (seconds) between SIGTERM and SIGKILL when terminating
+# a timed-out subprocess. Allows FFmpeg to flush buffers and release hardware
+# resources before being force-killed.
+TERMINATE_TIMEOUT_SUBPROCESS: float = float(os.getenv("TERMINATE_TIMEOUT_SUBPROCESS", 2.0))
 # set default timer for download requests
-DEFAULT_TIMEOUT = 3
+DEFAULT_TIMEOUT_REQUESTS: float = float(os.getenv("DEFAULT_TIMEOUT_REQUESTS", 3.0))
 
 
 class TimeoutHTTPAdapter(HTTPAdapter):
@@ -52,7 +58,7 @@ class TimeoutHTTPAdapter(HTTPAdapter):
     """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
-        self.timeout: float = DEFAULT_TIMEOUT
+        self.timeout: float = DEFAULT_TIMEOUT_REQUESTS
         if "timeout" in kwargs:
             self.timeout = kwargs["timeout"]
             del kwargs["timeout"]
@@ -210,7 +216,9 @@ def download_ffmpeg_binaries(path: str, os_windows: bool = False, os_bit: str =
                         status_forcelist=[429, 500, 502, 503, 504],
                     )
                     # Mount it for https usage
-                    adapter = TimeoutHTTPAdapter(timeout=2.0, max_retries=retries)
+                    adapter = TimeoutHTTPAdapter(
+                        timeout=MAX_TIMEOUT_SUBPROCESS, max_retries=retries
+                    )
                     http.mount("https://", adapter)
                     response = http.get(file_url, stream=True)
                     response.raise_for_status()
@@ -410,6 +418,7 @@ def extract_device_n_demuxer(
         metadata = check_sp_output(
             [path, *default_ffcommand.split(" ")],
             force_retrieve_stderr=True,
+            timeout=MAX_TIMEOUT_SUBPROCESS,
         )
         # clean and split metadata
         splitted = [x.decode("utf-8").strip() for x in metadata.split(b"\n")]
@@ -469,6 +478,7 @@ def extract_device_n_demuxer(
                         # search in path properties
                         metadata_path = check_sp_output(
                             ["v4l2-ctl", "--device={}".format(path), "--all"],
+                            timeout=MAX_TIMEOUT_SUBPROCESS,
                         )
                         # decode path metadata
                         decoded_path = metadata_path.decode("utf-8").strip()
@@ -488,6 +498,7 @@ def extract_device_n_demuxer(
         metadata = check_sp_output(
             [path, *default_ffcommand.split(" ")],
             force_retrieve_stderr=True,
+            timeout=MAX_TIMEOUT_SUBPROCESS,
         )
         # clean and split metadata
         splitted = [x.decode("utf-8").strip() for x in metadata.split(b"\n")]
@@ -641,44 +652,83 @@ def check_sp_output(*args: Any, **kwargs: Any) -> bytes:
     """
     ## check_sp_output
 
-    Returns FFmpeg `stdout` output from subprocess module.
+    Executes a subprocess command and returns its `stdout` (or `stderr` when
+    requested). On timeout, performs a two-step graceful shutdown — sends
+    `SIGTERM` first to allow FFmpeg to flush buffers and release hardware
+    resources (decoders, capture devices), then escalates to `SIGKILL` if the
+    process fails to exit within a short grace period.
 
     Parameters:
         args (based on input): Non Keyword Arguments
         kwargs (based on input): Keyword Arguments
+            force_retrieve_stderr (bool): If True, returns stderr. Also
+                suppresses `CalledProcessError` on non-zero exit, since some
+                FFmpeg diagnostic commands (e.g. `-list_devices`) emit useful
+                output on stderr while exiting non-zero by design.
+            timeout (float): Seconds to wait before terminating the process.
 
-    **Returns:** A string value.
+    **Returns:** A bytes value.
     """
     # workaround for python bug: https://bugs.python.org/issue37380
     if platform.system() == "Windows":
         # see comment https://bugs.python.org/msg370334
         sp._cleanup = lambda: None
+
     # handle additional params
     retrieve_stderr = kwargs.pop("force_retrieve_stderr", False)
+    timeout = kwargs.pop("timeout", None)
+
     # execute command in subprocess
     process = sp.Popen(
         *args,
         stdout=sp.PIPE,
-        stderr=sp.DEVNULL if not (retrieve_stderr) else sp.PIPE,
+        stderr=sp.PIPE if retrieve_stderr else sp.DEVNULL,
         **kwargs,
     )
-    # communicate and poll process
-    output, stderr = process.communicate()
+
+    # communicate and poll process with two-step timeout handling
+    timeout_occurred = False
+    try:
+        output, stderr = process.communicate(timeout=timeout)
+    except sp.TimeoutExpired:
+        timeout_occurred = True
+        logger.warning(
+            f"[Pipeline-Warning] :: Process exceeded timeout of {timeout}s. "
+            "Attempting graceful termination..."
+        )
+        # Step 1: polite SIGTERM, give process a chance to clean up
+        process.terminate()
+        try:
+            output, stderr = process.communicate(timeout=TERMINATE_TIMEOUT_SUBPROCESS)
+        except sp.TimeoutExpired:
+            # Step 2: process ignored SIGTERM, force kill
+            logger.error("[Pipeline-Error] :: Process unresponsive to SIGTERM. Hard killing...")
+            process.kill()
+            output, stderr = process.communicate()
+
     retcode = process.poll()
+
     # handle return code
-    if retcode and not (retrieve_stderr):
-        logger.error("[Pipeline-Error] :: {}".format(output.decode("utf-8")))
+    # Bypass CalledProcessError if caller wants stderr (some FFmpeg commands
+    # exit non-zero by design) or if we killed the process via our timeout.
+    if retcode and not retrieve_stderr and not timeout_occurred:
+        logger.error(
+            "[Pipeline-Error] :: {}".format(output.decode("utf-8") if output else "No output")
+        )
         cmd = kwargs.get("args")
         if cmd is None:
             cmd = args[0]
         error = sp.CalledProcessError(retcode, cmd)
         error.output = output
         raise error
-    # raise error if no output
-    bool(output) or bool(stderr) or logger.error(
-        "[Pipeline-Error] :: Pipeline failed to exact any data from command: {}!".format(
-            args[0] if args else []
+
+    # warn if process emitted nothing on either stream
+    if not (bool(output) or bool(stderr)):
+        logger.error(
+            "[Pipeline-Error] :: Pipeline failed to extract any data from command: {}!".format(
+                args[0] if args else []
+            )
         )
-    )
-    # return output otherwise
+
+    # return stderr when explicitly requested (and present), else stdout
     return stderr if retrieve_stderr and stderr else output

{deffcode-0.2.7 → deffcode-0.2.8}/deffcode/sourcer.py

@@ -28,11 +28,12 @@ import os
 import platform
 import re
 import shutil
-from typing import Any
+from typing import Any, Self
 
 import numpy as np
 
 from .ffhelper import (
+    MAX_TIMEOUT_SUBPROCESS,
     check_sp_output,
     extract_device_n_demuxer,
     get_supported_demuxers,
@@ -294,7 +295,7 @@ class Sourcer:
         # check whether metadata probed or not?
         self.__metadata_probed = False
 
-    def probe_stream(self, default_stream_indexes: list[int] | tuple[int, int] = (0, 0)) -> Sourcer:
+    def probe_stream(self, default_stream_indexes: list[int] | tuple[int, int] = (0, 0)) -> Self:
         """
         This method Parses/Probes FFmpeg `subprocess` pipe's Standard Output for given input source and Populates the information in private class variables.
 
@@ -308,6 +309,40 @@ class Sourcer:
             and len(default_stream_indexes) == 2
             and all(isinstance(x, int) for x in default_stream_indexes)
         ), "Invalid default_stream_indexes value!"
+        # probe extra inputs first via independent single-source Sourcers, so
+        # their resolved source/demuxer (e.g. camera index -> device) can be
+        # reused by the combined filtergraph probe below.
+        extra_metadata = []
+        if self.__is_multi:
+            for idx in range(1, len(self.__source_list)):
+                _src = self.__source_list[idx]
+                _demux = self.__source_demuxer_list[idx]
+                _prefixes = self.__ffmpeg_prefixes_list[idx]
+                _params = self.__sourcer_params.copy()
+                _params["-ffprefixes"] = _prefixes
+                # output routing references all inputs; meaningless per-source
+                for _key in ("-vf", "-filter_complex", "-map"):
+                    _params.pop(_key, None)
+                # Resolve to an absolute path: on Unix `self.__ffmpeg` may be
+                # the bare command "ffmpeg" found via PATH, which the nested
+                # `get_valid_ffmpeg_path()` would reject as "not a file".
+                _custom_ffmpeg = (
+                    self.__ffmpeg
+                    if self.__ffmpeg and os.path.isfile(self.__ffmpeg)
+                    else (shutil.which(self.__ffmpeg) or "")
+                )
+                _s = Sourcer(
+                    _src,
+                    source_demuxer=_demux,
+                    custom_ffmpeg=_custom_ffmpeg,
+                    verbose=self.__verbose_logs,
+                    **_params,
+                )
+                _s.probe_stream(default_stream_indexes)
+                extra_metadata.append(_s.retrieve_metadata(force_retrieve_missing=True))
+        self.__resolved_extra_inputs = [
+            (m[0]["source"], m[0].get("source_demuxer")) for m in extra_metadata
+        ]
         # validate source and extract metadata
         self.__ffsp_output = self.__validate_source(
             self.__source,
@@ -394,34 +429,7 @@ class Sourcer:
             # the guard inside retrieve_metadata (checks for non-empty
             # __multi_source_metadata) prevents `sources: []` self-pollution.
             self.__multi_source_metadata.append(self.retrieve_metadata(force_retrieve_missing=True))
-            for idx in range(1, len(self.__source_list)):
-                _src = self.__source_list[idx]
-                _demux = self.__source_demuxer_list[idx]
-                _prefixes = self.__ffmpeg_prefixes_list[idx]
-                _params = self.__sourcer_params.copy()
-                _params["-ffprefixes"] = _prefixes
-                # spawn an independent single-source Sourcer per extra input;
-                # this reuses the resolved ffmpeg path and isolates per-source
-                # parsing state (which probe_stream otherwise clobbers).
-                # Resolve to an absolute path: on Unix `self.__ffmpeg` may be
-                # the bare command "ffmpeg" found via PATH, which the nested
-                # `get_valid_ffmpeg_path()` would reject as "not a file".
-                _custom_ffmpeg = (
-                    self.__ffmpeg
-                    if self.__ffmpeg and os.path.isfile(self.__ffmpeg)
-                    else (shutil.which(self.__ffmpeg) or "")
-                )
-                _s = Sourcer(
-                    _src,
-                    source_demuxer=_demux,
-                    custom_ffmpeg=_custom_ffmpeg,
-                    verbose=self.__verbose_logs,
-                    **_params,
-                )
-                _s.probe_stream(default_stream_indexes)
-                self.__multi_source_metadata.append(
-                    _s.retrieve_metadata(force_retrieve_missing=True)
-                )
+            self.__multi_source_metadata.extend(extra_metadata)
 
         # return reference to the instance object.
         return self
@@ -671,6 +679,20 @@ class Sourcer:
                 + self.__ffmpeg_prefixes
                 + (["-f", source_demuxer] if source_demuxer else [])
                 + ["-i", source]
+                # multi-input filtergraphs reference every input (e.g. `[1:v]`),
+                # so the probe must ingest all of them to resolve output metadata.
+                + [
+                    arg
+                    for (src, demux), prefixes in zip(
+                        self.__resolved_extra_inputs,
+                        self.__ffmpeg_prefixes_list[1:],
+                        strict=True,
+                    )
+                    for arg in ["-t", "0.0001"]
+                    + prefixes
+                    + (["-f", demux] if demux else [])
+                    + ["-i", src]
+                ]
                 + dict2Args(self.__sourcer_params)
                 + ["-f", "null", "-"]
             )
@@ -687,13 +709,16 @@ class Sourcer:
             check_sp_output(
                 meta_cmd,
                 force_retrieve_stderr=True,
+                timeout=MAX_TIMEOUT_SUBPROCESS,
             )
             .decode("utf-8")
             .strip()
         )
         # separate input and output metadata (if available)
         if "Output #" in metadata:
-            (metadata, self.__metadata_output) = metadata.split("Output #")
+            metadata, self.__metadata_output = metadata.split("Output #")
+        # primary `source_*` metadata must only describe input 0
+        metadata = re.split(r"^Input #1\b", metadata, maxsplit=1, flags=re.M)[0]
         # return metadata based on params
         return metadata
 

deffcode-0.2.8/deffcode/version.py

@@ -0,0 +1 @@
+__version__: str = "0.2.8"

{deffcode-0.2.7 → deffcode-0.2.8}/deffcode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deffcode
-Version: 0.2.7
+Version: 0.2.8
 Summary: A cross-platform High-performance & Flexible Real-time Video Frames Decoder in Python.
 Author-email: Abhishek Thakur <abhi.una12@gmail.com>
 License: Apache License 2.0
@@ -22,11 +22,11 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Education
 Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cython
@@ -113,7 +113,7 @@ Here are some key features that stand out:
 - Effortless [**Metadata Extraction**][extracting-video-metadata] from all streams available in the source.
 - Maintains the standard easy to learn [**OpenCV-Python**](https://docs.opencv.org/4.x/d6/d00/tutorial_py_root.html) coding syntax.
 - Out-of-the-box support for all prominent Computer Vision libraries.
-- Cross-platform, runs on Python 3.10+, and easy to install.
+- Cross-platform, runs on Python 3.11+, and easy to install.
 
 <!--
 - [x] Lossless Transcoding support with [WriteGear](https://abhitronix.github.io/deffcode/latest/gears/writegear/introduction/). #TODO
@@ -235,6 +235,8 @@ Once you have DeFFcode installed, checkout our Well-Documented **[Recipes 🍱][
 - [CUDA-NVENC-accelerated Video Transcoding with WriteGear API][cuda-nvenc-accelerated-video-transcoding-with-writegear-api]
 - [CUDA-NVENC-accelerated End-to-end Lossless Video Transcoding with WriteGear API][cuda-nvenc-accelerated-end-to-end-lossless-video-transcoding-with-writegear-api]
 - [Multi-Input Source Configurations][multi-input-source-configurations]
+  - [Decoding multiple inputs as 2x2 video grid _(mosaic)_][decoding-multiple-inputs-as-2x2-video-grid-mosaic]
+  - [Decoding crossfade transition between multiple inputs][decoding-crossfade-transition-between-multiple-inputs]
 
 </details>
 
@@ -271,9 +273,8 @@ decoder = FFdecoder("https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1
 
 # grab RGB24(default) 3D frames from decoder
 for frame in decoder.generateFrame():
-
     # lets print its shape
-    print(frame.shape) # (1080, 1920, 3)
+    print(frame.shape)  # (1080, 1920, 3)
 
 # terminate the decoder
 decoder.terminate()
@@ -288,7 +289,9 @@ The primary function of [**Sourcer API**][sourcer-api] is to **gather metadata i
 from deffcode import Sourcer
 
 # initialize and formulate the decoder using suitable source
-sourcer = Sourcer("https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1MB.mp4").probe_stream()
+sourcer = Sourcer(
+    "https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1MB.mp4"
+).probe_stream()
 
 # print metadata as `json.dump`
 print(sourcer.retrieve_metadata(pretty_json=True))
@@ -354,18 +357,24 @@ 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.12689394.svg)](https://doi.org/10.5281/zenodo.12689394)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19658542.svg)](https://doi.org/10.5281/zenodo.19658542)
 
 ```BibTeX
 @software{deffcode,
   author       = {Abhishek Thakur},
-  title        = {abhiTronix/deffcode: v0.2.6},
-  month        = jul,
-  year         = 2024,
+  title        = {abhiTronix/deffcode: v0.2.7},
+  month        = apr,
+  year         = 2026,
   publisher    = {Zenodo},
-  version      = {v0.2.6},
-  doi          = {10.5281/zenodo.12689394},
-  url          = {https://doi.org/10.5281/zenodo.12689394},
+  version      = {v0.2.7},
+  doi          = {10.5281/zenodo.19658542},
+  url          = {https://doi.org/10.5281/zenodo.19658542},
+  swhid        = {swh:1:dir:85e8dfd087aed870deb4043c532faaa9b156d1e1
+                   ;origin=https://doi.org/10.5281/zenodo.6976947;vis
+                   it=swh:1:snp:af1b478890801c02d56b95f563b86761980bf
+                   82c;anchor=swh:1:rel:85f9af4452f8030317ec2012acc10
+                   29e8a945e2d;path=abhiTronix-deffcode-5162649
+                  },
 }
 ```
 
@@ -478,6 +487,8 @@ Advanced Recipes
 [smart-keyframe-only-decoding-for-heavy-ai-inference]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/extract-frame-metadata/#smart-keyframe-only-decoding-for-heavy-ai-inference
 [variable-frame-rate-vfr-synchronization-via-pts_time]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/extract-frame-metadata/#variable-frame-rate-vfr-synchronization-via-pts_time
 [multi-input-source-configurations]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_input/#multi-input-source-configurations
+[decoding-multiple-inputs-as-2x2-video-grid-mosaic]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_input/#decoding-multiple-inputs-as-2x2-video-grid-mosaic
+[decoding-crossfade-transition-between-multiple-inputs]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_input/#decoding-crossfade-transition-between-multiple-inputs
 
 <!--
 CI Apps URLs

{deffcode-0.2.7 → deffcode-0.2.8}/pyproject.toml

@@ -7,7 +7,7 @@ name = "deffcode"
 description = "A cross-platform High-performance & Flexible Real-time Video Frames Decoder in Python."
 authors = [{name = "Abhishek Thakur", email = "abhi.una12@gmail.com"}]
 license = {text = "Apache License 2.0"}
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 keywords = [
     "FFmpeg",
     "Decoder",
@@ -30,10 +30,10 @@ classifiers = [
     "Intended Audience :: Science/Research",
     "Intended Audience :: Education",
     "License :: OSI Approved :: Apache Software License",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
     "cython",
@@ -58,9 +58,14 @@ packages = ["deffcode"]
 [tool.setuptools.dynamic]
 version = {attr = "deffcode.version.__version__"}
 
+[tool.poetry]
+# Poetry can't read setuptools' dynamic version,
+# keep in sync with deffcode/version.py
+version = "0.2.8"
+
 [tool.ruff]
 line-length = 100
-target-version = "py310"
+target-version = "py311"
 extend-exclude = [
     "build",
     "dist",

{deffcode-0.2.7 → deffcode-0.2.8}/tests/test_ffdecoder.py

@@ -667,7 +667,7 @@ def test_FFdecoder_params(source: str | list[str], ffparams: dict[str, Any], res
             # prepare OpenCV parameters
             FOURCC = cv2.VideoWriter_fourcc("M", "J", "P", "G")
             FRAMERATE = metadata_dict["source_video_framerate"]
-            FRAMESIZE = tuple(metadata_dict["source_video_resolution"])
+            FRAMESIZE = tuple(metadata_dict["output_frames_resolution"])
 
             # Define writer with parameters and suitable output filename for e.g. `output_foo.avi`
             writer = cv2.VideoWriter(f_name, FOURCC, FRAMERATE, FRAMESIZE)
@@ -848,3 +848,39 @@ def test_discard_n_filter_params(frame_format: str, ffparams: dict[str, Any], re
     finally:
         # terminate
         decoder is not None and decoder.terminate()
+
+
+_grid = "[0:v][1:v][2:v][3:v]xstack=inputs=4:layout=0_0|w0_0|0_h0|w0_h0[out]"
+test_data = [
+    (["320x240"] * 2, {"-filter_complex": "hstack=inputs=2"}, (240, 640), 50),
+    (
+        ["320x240", "160x120"],
+        {"-filter_complex": "[1:v]scale=80:-1[s];[0:v][s]overlay=W-w-10:H-h-10"},
+        (240, 320),
+        50,
+    ),
+    (["320x240"] * 4, {"-filter_complex": _grid, "-map": "[out]"}, (480, 640), 50),
+    (
+        ["320x240"] * 2,
+        {"-filter_complex": "[0:v][1:v]xfade=duration=1:offset=1[v]", "-map": "[v]"},
+        (240, 320),
+        75,
+    ),
+    (["320x240", "160x120"], {"-map": "1:v"}, (120, 160), 50),
+]
+
+
+@pytest.mark.parametrize("sizes, ffparams, shape, n_frames", test_data)
+def test_multi_input_composites(
+    sizes: list[str], ffparams: dict[str, Any], shape: tuple[int, int], n_frames: int
+) -> None:
+    """
+    Testing multi-input filtergraph recipes yield frames of the composite size and length
+    """
+    source = ["testsrc=size={}:rate=25:duration=2".format(s) for s in sizes]
+    with FFdecoder(
+        source, source_demuxer=["lavfi"] * len(sizes), frame_format="bgr24", **ffparams
+    ) as decoder:
+        frames = [f for f in decoder.generateFrame() if f is not None]
+    assert frames and frames[0].shape == (*shape, 3)
+    assert abs(len(frames) - n_frames) <= 1

{deffcode-0.2.7 → deffcode-0.2.8}/tests/test_ffhelper.py

@@ -145,9 +145,70 @@ def test_get_valid_ffmpeg_path(paths: str, ffmpeg_download_paths: str, results:
 @pytest.mark.xfail(raises=Exception)
 def test_check_sp_output() -> None:
     """
-    Testing check_sp_output method
+    Testing check_sp_output method raises CalledProcessError on invalid flags.
     """
-    check_sp_output(["ffmpeg", "-Vv"])
+    check_sp_output(["ffmpeg", "-Vv"], timeout=2.0)
+
+
+def test_check_sp_output_happy_path() -> None:
+    """
+    Testing check_sp_output returns stdout bytes for a successful command.
+    """
+    output = check_sp_output([return_static_ffmpeg(), "-version"], timeout=5.0)
+    assert isinstance(output, bytes) and len(output) > 0, "Expected non-empty stdout"
+    assert b"ffmpeg version" in output, "Expected ffmpeg version banner in stdout"
+
+
+def test_check_sp_output_force_retrieve_stderr_bypass() -> None:
+    """
+    Testing that `force_retrieve_stderr=True` suppresses CalledProcessError on
+    non-zero exit and returns stderr bytes. Mirrors how `extract_device_n_demuxer`
+    consumes `ffmpeg -list_devices` output (which exits non-zero by design).
+    """
+    # `-list_devices true -i dummy` exits non-zero on every platform
+    cmd = [
+        return_static_ffmpeg(),
+        "-hide_banner",
+        "-list_devices",
+        "-i",
+        "dummy",
+    ]
+    stderr = check_sp_output(cmd, force_retrieve_stderr=True, timeout=5.0)
+    assert isinstance(stderr, bytes), "Expected bytes return on stderr bypass"
+
+
+def test_check_sp_output_graceful_timeout() -> None:
+    """
+    Testing two-step timeout handling: a long-running FFmpeg process must be
+    terminated within roughly `timeout + grace_period` seconds and must NOT
+    raise CalledProcessError (timeout kills are bypassed by design).
+    """
+    import time
+
+    # null source → null sink loop runs forever; ensures we hit the timeout
+    cmd = [
+        return_static_ffmpeg(),
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-f",
+        "lavfi",
+        "-i",
+        "nullsrc",
+        "-t",
+        "60",
+        "-f",
+        "null",
+        "-",
+    ]
+    timeout = 1.0
+    start = time.monotonic()
+    output = check_sp_output(cmd, timeout=timeout)
+    elapsed = time.monotonic() - start
+    # must return bytes (possibly empty), no exception
+    assert isinstance(output, bytes), "Expected bytes return on graceful timeout"
+    # must complete within timeout + 2s grace + reasonable overhead
+    assert elapsed < timeout + 5.0, f"Process took {elapsed:.2f}s — graceful shutdown likely stuck"
 
 
 @pytest.mark.parametrize(

{deffcode-0.2.7 → deffcode-0.2.8}/tests/test_sourcer.py

@@ -196,3 +196,28 @@ def test_probe_stream_n_retrieve_metadata(
             pytest.xfail("Test Still Passed!")
         else:
             pytest.fail(str(e))
+
+
+def test_multi_input_primary_metadata() -> None:
+    """
+    Primary `source_*` metadata must describe input 0 only, even with a
+    nonzero default video stream index and a combined filtergraph probe.
+    """
+    metadata = (
+        Sourcer(
+            [
+                "testsrc=size=320x240:rate=25:duration=2",
+                "testsrc=size=160x120:rate=10:duration=2",
+            ],
+            source_demuxer="lavfi",
+            **{"-filter_complex": "[0:v][1:v]overlay"},
+        )
+        .probe_stream(default_stream_indexes=(1, 0))
+        .retrieve_metadata()
+    )
+    assert metadata["source_video_resolution"] == [320, 240]
+    assert metadata["source_video_framerate"] == 25.0
+    assert [s["source_video_resolution"] for s in metadata["sources"]] == [
+        [320, 240],
+        [160, 120],
+    ]

deffcode-0.2.7/deffcode/version.py

@@ -1 +0,0 @@
-__version__: str = "0.2.7"