deffcode 0.2.8__py3-none-any.whl → 0.2.9__py3-none-any.whl

deffcode/ffdecoder.py

@@ -26,9 +26,11 @@ import platform
 import queue
 import re
 import subprocess as sp
+import sys
 import threading
-from collections import OrderedDict
+from collections import OrderedDict, deque
 from collections.abc import Generator
+from itertools import pairwise
 from types import TracebackType
 from typing import Any, Self
 
@@ -36,6 +38,7 @@ import numpy as np
 
 # import utils packages
 from .ffhelper import (
+    TERMINATE_TIMEOUT_SUBPROCESS,
     get_supported_pixfmts,
     get_supported_vdecoders,
 )
@@ -207,6 +210,15 @@ class FFdecoder:
                 self.__ffmpeg_prefixes = []
             sourcer_params["-ffprefixes"] = self.__ffmpeg_prefixes
 
+        # handles user-defined additional FFmpeg outputs, appended after the rawvideo pipe output (must be a flat list)
+        self.__extra_outputs = self.__extra_params.pop("-extra_outputs", [])
+        if not isinstance(self.__extra_outputs, list) or any(
+            isinstance(x, (list, tuple, dict)) for x in self.__extra_outputs
+        ):
+            logger.warning("Discarding invalid `-extra_outputs` value! It must be a flat list.")
+            self.__extra_outputs = []
+        self.__extra_outputs = [str(x) for x in self.__extra_outputs]
+
         # pass parameter(if specified) to Sourcer API, specifying where to save the downloaded FFmpeg Static
         # assets on Windows(if specified)
         sourcer_params["-ffmpeg_download_path"] = self.__extra_params.pop(
@@ -229,6 +241,17 @@ class FFdecoder:
         # 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"]
+        # filtergraph labels consumed only by `-extra_outputs` must also be consumed while
+        # probing, otherwise FFmpeg aborts with "unconnected output"; map all into the probe sink.
+        if self.__extra_outputs and "-filter_complex" in sourcer_params:
+            if "-map" in self.__extra_params:
+                sourcer_params["-map"] = self.__extra_params["-map"]
+            sourcer_params["-clones"] = [
+                arg
+                for key, val in pairwise(self.__extra_outputs)
+                if key == "-map" and val.startswith("[")
+                for arg in (key, val)
+            ]
 
         # define dict to store user-defined parameters
         self.__user_metadata = {}
@@ -280,6 +303,13 @@ class FFdecoder:
                 "Enabling asynchronous `showinfo` per-frame metadata extraction."
             )
 
+        # handle capturing FFmpeg stderr tail for diagnosing pipeline failures
+        self.__capture_stderr = self.__extra_params.pop("-capture_stderr", False)
+        if not isinstance(self.__capture_stderr, bool):
+            self.__capture_stderr = False
+        self.__stderr_tail: deque[str] = deque(maxlen=50)
+        self.__returncode: int | None = None
+
         # handle disabling window for ffmpeg subprocess on Windows OS
         # this patch prevents ffmpeg creation window from opening when
         # building exe files
@@ -783,16 +813,39 @@ class FFdecoder:
             while not self.__terminate_stream:  # infinite raw frames
                 frame = self.__fetchNextFrame()
                 if frame is None:
-                    self.__terminate_stream = True
+                    self.__handle_stream_end()
                     break
                 yield self.__attach_metadata(frame)
         else:
             for _ in range(self.__raw_frame_num):  # finite raw frames
                 frame = self.__fetchNextFrame()
                 if frame is None:
-                    self.__terminate_stream = True
+                    self.__handle_stream_end()
                     break
                 yield self.__attach_metadata(frame)
+        # generator exhausted, FFmpeg may still be flushing/exiting cleanly
+        self.__terminate_stream = True
+
+    def __handle_stream_end(self) -> None:
+        """
+        Internal: marks stream as ended on a short read and, when `-capture_stderr`
+        is enabled and FFmpeg exited with a non-zero code, logs the `stderr_tail`.
+        """
+        self.__terminate_stream = True
+        if not self.__capture_stderr or self.__process is None:
+            return
+        try:
+            retcode = self.__process.wait(timeout=TERMINATE_TIMEOUT_SUBPROCESS)
+        except sp.TimeoutExpired:
+            return
+        if retcode:
+            # let the reader thread drain remaining stderr lines first
+            self.__stderr_thread and self.__stderr_thread.join(timeout=TERMINATE_TIMEOUT_SUBPROCESS)
+            logger.error(
+                "FFmpeg exited with code {}. Last stderr lines:\n{}".format(
+                    retcode, "\n".join(self.__stderr_tail)
+                )
+            )
 
     def __attach_metadata(self, frame: np.ndarray):
         """
@@ -830,6 +883,25 @@ class FFdecoder:
         """
         self.terminate()
 
+    @property
+    def returncode(self) -> int | None:
+        """
+        A property object that holds FFmpeg process exit code, set by `terminate()`.
+
+        **Returns:** FFmpeg exit code, or `None` if pipeline has not been terminated yet.
+        """
+        return self.__returncode
+
+    @property
+    def stderr_tail(self) -> list[str]:
+        """
+        A property object that holds the last 50 lines of FFmpeg's stderr output.
+        Only populated when `-capture_stderr` (or `-extract_metadata`) is enabled.
+
+        **Returns:** List of stderr lines (oldest first).
+        """
+        return list(self.__stderr_tail)
+
     @property
     def metadata(self) -> str:
         """
@@ -908,8 +980,10 @@ class FFdecoder:
                 else:
                     # otherwise discard and log it
                     logger.warning(
-                        "Manually assigned `{}` metadata property value is of invalid type. Discarding!"
-                    ).format(key)
+                        "Manually assigned `{}` metadata property value is of invalid type. Discarding!".format(
+                            key
+                        )
+                    )
                 # delete invalid key
                 del value[key]
             # There is no concept of a tuple in the JSON format.
@@ -974,11 +1048,12 @@ class FFdecoder:
 
         cmd += output_parameters
         cmd += ["-f", "rawvideo", "-"]
-        # When metadata extraction is enabled we must capture stderr regardless
-        # of verbose mode so the background reader thread can parse showinfo
-        # lines. Without PIPE the reader would have nothing to read (verbose
+        cmd += self.__extra_outputs
+        # When metadata extraction or stderr capture is enabled we must pipe stderr
+        # regardless of verbose mode so the background reader thread can consume
+        # it. Without PIPE the reader would have nothing to read (verbose
         # inherits parent stderr; silent discards it).
-        if self.__extract_metadata:
+        if self.__extract_metadata or self.__capture_stderr:
             stderr_target = sp.PIPE
         elif self.__verbose_logs:
             stderr_target = None
@@ -1001,18 +1076,20 @@ class FFdecoder:
                 ),
             )
 
-        # spin up the stderr reader thread that parses `showinfo` lines and
-        # feeds per-frame metadata dicts into the queue consumed by generateFrame()
-        if self.__extract_metadata:
-            self.__metadata_queue = queue.Queue()
+        # spin up the stderr reader thread that records stderr tail, and parses
+        # `showinfo` lines into the metadata queue consumed by generateFrame()
+        if self.__extract_metadata or self.__capture_stderr:
+            if self.__extract_metadata:
+                self.__metadata_queue = queue.Queue()
             self.__stderr_stop.clear()
             self.__stderr_thread = threading.Thread(target=self.__read_stderr, daemon=True)
             self.__stderr_thread.start()
 
     def __read_stderr(self) -> None:
         """
-        Internal: background daemon that parses FFmpeg `showinfo` lines off
-        stderr and pushes per-frame metadata dicts onto `__metadata_queue`.
+        Internal: background daemon that appends FFmpeg stderr lines to `__stderr_tail`
+        (echoing them when verbose), and parses `showinfo` lines into per-frame metadata
+        dicts on `__metadata_queue` when `-extract_metadata` is enabled.
         Exits when FFmpeg closes stderr or when `__stderr_stop` is signalled.
         """
         assert self.__process is not None and self.__process.stderr is not None
@@ -1022,6 +1099,11 @@ class FFdecoder:
                 if self.__stderr_stop.is_set():
                     break
                 decoded = line.decode("utf-8", errors="ignore")
+                self.__stderr_tail.append(decoded.rstrip())
+                # echo so verbose console output stays unchanged
+                self.__verbose_logs and sys.stderr.write(decoded)
+                if not self.__extract_metadata:
+                    continue
                 match = _SHOWINFO_REGEX.search(decoded)
                 if not match:
                     continue
@@ -1037,35 +1119,51 @@ class FFdecoder:
             pass
         finally:
             # sentinel so consumers unblock on EOF
-            self.__metadata_queue.put(None)
+            self.__metadata_queue is not None and self.__metadata_queue.put(None)
 
-    def terminate(self) -> None:
+    def terminate(self) -> int | None:
         """
         Safely terminates all processes.
+
+        **Returns:** FFmpeg process exit code (also available via `returncode`), or `None` if no process was launched.
         """
 
         # signal we are closing
         self.__verbose_logs and logger.debug("Terminating FFdecoder Pipeline...")
+        stream_exhausted = self.__terminate_stream
         self.__terminate_stream = True
         self.__stderr_stop.set()
         # check if no process was initiated at first place
-        if self.__process is None or self.__process.poll() is not None:
+        if self.__process is None:
             logger.info("Pipeline already terminated.")
-            return
+            return self.__returncode
         # Attempt to close pipeline.
         # close `stdin` output
         self.__process.stdin and self.__process.stdin.close()
         # close `stdout` output
         self.__process.stdout and self.__process.stdout.close()
-        # close `stderr` so the background reader thread's blocking readline() unblocks
-        self.__process.stderr and self.__process.stderr.close()
-        # terminate/kill process if still processing
-        self.__process.poll() is None and self.__process.terminate()
-        # wait if not exiting
-        self.__process.wait()
-        # join the stderr reader thread so it does not outlive the pipeline
+        # let FFmpeg finalize `-extra_outputs` (trailers/moov) on EPIPE, or exit cleanly
+        # after stream end, before forcing termination
+        if self.__extra_outputs or stream_exhausted:
+            try:
+                self.__process.wait(TERMINATE_TIMEOUT_SUBPROCESS)
+            except sp.TimeoutExpired:
+                pass
+        # terminate process if still processing, escalate to kill if unresponsive
+        if self.__process.poll() is None:
+            self.__process.terminate()
+            try:
+                self.__process.wait(TERMINATE_TIMEOUT_SUBPROCESS)
+            except sp.TimeoutExpired:
+                self.__process.kill()
+                self.__process.wait()
+        # join the stderr reader thread (it hits EOF once FFmpeg exits) so it does not outlive
+        # the pipeline, then close `stderr`; closing earlier blocks on the reader's buffer lock
         if self.__stderr_thread is not None and self.__stderr_thread.is_alive():
             self.__stderr_thread.join(timeout=2.0)
         self.__stderr_thread = None
+        self.__process.stderr and self.__process.stderr.close()
+        self.__returncode = self.__process.returncode
         self.__process = None
         logger.info("Pipeline terminated successfully.")
+        return self.__returncode

deffcode/ffhelper.py

@@ -677,6 +677,8 @@ def check_sp_output(*args: Any, **kwargs: Any) -> bytes:
     # handle additional params
     retrieve_stderr = kwargs.pop("force_retrieve_stderr", False)
     timeout = kwargs.pop("timeout", None)
+    # never inherit parent's stdin, avoids blocking on unexpected input reads
+    kwargs.setdefault("stdin", sp.DEVNULL)
 
     # execute command in subprocess
     process = sp.Popen(

deffcode/sourcer.py

@@ -321,7 +321,7 @@ class Sourcer:
                 _params = self.__sourcer_params.copy()
                 _params["-ffprefixes"] = _prefixes
                 # output routing references all inputs; meaningless per-source
-                for _key in ("-vf", "-filter_complex", "-map"):
+                for _key in ("-vf", "-filter_complex", "-map", "-clones"):
                     _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

deffcode/version.py

@@ -1 +1 @@
-__version__: str = "0.2.8"
+__version__: str = "0.2.9"

{deffcode-0.2.8.dist-info → deffcode-0.2.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deffcode
-Version: 0.2.8
+Version: 0.2.9
 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
@@ -108,6 +108,7 @@ Here are some key features that stand out:
 - Hands down the easiest [**Index based Camera Device Capturing**][decoding-camera-devices-using-indexes], similar to OpenCV.
 - Easy to code **Real-time [Simple][transcoding-live-simple-filtergraphs] & [Complex][transcoding-live-complex-filtergraphs] Filtergraphs**. _(Yes, You read it correctly "Real-time"!)_
 - Native **[Multi-Input Source Configurations][multi-input-source-configurations]** support for decoding complex topologies.
+- Native **[Multi-Outputs Configurations][multi-outputs-configurations]** support for recording/streaming while decoding, in a single FFmpeg pipeline.
 - Lightning fast dedicated **GPU-Accelerated Video [Decoding][hardware-accelerated-video-decoding] & [Transcoding][hardware-accelerated-video-transcoding]**.
 - Enables precise FFmpeg [**Key-frame Seeking**][extracting-key-frames-as-png-image] with pinpoint accuracy.
 - Effortless [**Metadata Extraction**][extracting-video-metadata] from all streams available in the source.
@@ -237,6 +238,9 @@ Once you have DeFFcode installed, checkout our Well-Documented **[Recipes 🍱][
 - [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]
+- [Multi-Outputs Configurations][multi-outputs-configurations]
+  - [Recording while decoding][recording-while-decoding]
+  - [Encode once, duplicate to file and stream][encode-once-duplicate-to-file-and-stream]
 
 </details>
 
@@ -357,24 +361,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.19658542.svg)](https://doi.org/10.5281/zenodo.19658542)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23446604.svg)](https://doi.org/10.5281/zenodo.23446604)
 
 ```BibTeX
 @software{deffcode,
   author       = {Abhishek Thakur},
-  title        = {abhiTronix/deffcode: v0.2.7},
-  month        = apr,
+  title        = {abhiTronix/deffcode: v0.2.8},
+  month        = oct,
   year         = 2026,
   publisher    = {Zenodo},
-  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
-                  },
+  version      = {v0.2.8},
+  doi          = {10.5281/zenodo.23446604},
+  url          = {https://doi.org/10.5281/zenodo.23446604},
 }
 ```
 
@@ -489,6 +487,9 @@ Advanced Recipes
 [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
+[multi-outputs-configurations]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_output/#multi-outputs-configurations
+[recording-while-decoding]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_output/#recording-while-decoding
+[encode-once-duplicate-to-file-and-stream]: https://abhitronix.github.io/deffcode/latest/recipes/advanced/multi_output/#encode-once-duplicate-to-file-and-stream
 
 <!--
 CI Apps URLs

deffcode-0.2.9.dist-info/RECORD

@@ -0,0 +1,11 @@
+deffcode/__init__.py,sha256=BQO_1Yv0E9PZCPtJ8-1z3X0VLP6VgBbdV5RahJU_RIk,286
+deffcode/ffdecoder.py,sha256=4ywrmP076ZGdrZdcIrFP336HXEAyWT2NKmRiJOo7-5Q,55259
+deffcode/ffhelper.py,sha256=Kms1CiVsyB3CgQvLdScGSuL5ml0eRqxm6xrTd-0g6fE,29032
+deffcode/sourcer.py,sha256=xys3OH4AO0RgdaIj-bYc76rP0F3ZZJSocxGuM0OG2N0,43628
+deffcode/utils.py,sha256=bIR1Hu_icLs3Xe7njHR9YE09MYUbvUfhOUMSqSHh730,4729
+deffcode/version.py,sha256=cHThOwcEXKpIPW-ZC1HETHv-MyCCWj4sJISXFDdM8u4,27
+deffcode-0.2.9.dist-info/licenses/LICENSE,sha256=pF-0xwtgiRjzW5P97fyEOCIqe7LV5Sd5cjIC4fBDwVQ,12259
+deffcode-0.2.9.dist-info/METADATA,sha256=WMCK5mRr3eEfDt5wuvh7iG4gOfJlfKNeVttRqf73dIM,35196
+deffcode-0.2.9.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+deffcode-0.2.9.dist-info/top_level.txt,sha256=1C-kyZgIKFviemaQMmhP0VKR3wkzEZcrf1o5oUckvHI,9
+deffcode-0.2.9.dist-info/RECORD,,

{deffcode-0.2.8.dist-info → deffcode-0.2.9.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (84.0.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

deffcode-0.2.8.dist-info/RECORD

@@ -1,11 +0,0 @@
-deffcode/__init__.py,sha256=BQO_1Yv0E9PZCPtJ8-1z3X0VLP6VgBbdV5RahJU_RIk,286
-deffcode/ffdecoder.py,sha256=0N1x1GstU7_RpqXe3RF-Uw4ZMGjBsRiDXlcFaycecxA,50640
-deffcode/ffhelper.py,sha256=6DwWsCf22DQH2bXtkBvsh01APc26TFsDfWD5N00snJg,28911
-deffcode/sourcer.py,sha256=k_Sau4vYLc8uGTJ5kX0Jorx0HC006bnA5Eplu_Ney7A,43617
-deffcode/utils.py,sha256=bIR1Hu_icLs3Xe7njHR9YE09MYUbvUfhOUMSqSHh730,4729
-deffcode/version.py,sha256=HUqwShoZiCc_WHZJmLh-SoGXaMatKowDyny2qENFLOU,27
-deffcode-0.2.8.dist-info/licenses/LICENSE,sha256=pF-0xwtgiRjzW5P97fyEOCIqe7LV5Sd5cjIC4fBDwVQ,12259
-deffcode-0.2.8.dist-info/METADATA,sha256=mZcgTQV75a8E4ytkFBgYiD5bpgRTY0jz6BqKd4wjhUw,34772
-deffcode-0.2.8.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-deffcode-0.2.8.dist-info/top_level.txt,sha256=1C-kyZgIKFviemaQMmhP0VKR3wkzEZcrf1o5oUckvHI,9
-deffcode-0.2.8.dist-info/RECORD,,