deffcode 0.2.8__tar.gz → 0.2.9__tar.gz

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

@@ -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.8 → deffcode-0.2.9}/README.md

@@ -68,6 +68,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.
@@ -197,6 +198,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>
 
@@ -317,24 +321,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},
 }
 ```
 
@@ -449,6 +447,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.8 → deffcode-0.2.9}/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-0.2.8 → deffcode-0.2.9}/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-0.2.8 → deffcode-0.2.9}/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-0.2.9/deffcode/version.py

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

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

@@ -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.8 → deffcode-0.2.9}/pyproject.toml

@@ -61,7 +61,7 @@ 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"
+version = "0.2.9"
 
 [tool.ruff]
 line-length = 100

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

@@ -450,6 +450,79 @@ def test_extract_luma_invalid_type() -> None:
         decoder is not None and decoder.terminate()
 
 
+@pytest.mark.parametrize("verbose", [True, False])
+def test_capture_stderr_on_failure(verbose: bool) -> None:
+    """
+    With `-capture_stderr`, an FFmpeg pipeline that dies (invalid filter) must end
+    the generator gracefully, expose its non-zero exit code via `terminate()`/`returncode`,
+    and keep its error output in `stderr_tail`.
+    """
+    decoder = FFdecoder(
+        return_testvideo_path(fmt="vo"),
+        custom_ffmpeg=return_static_ffmpeg(),
+        verbose=verbose,
+        **{"-capture_stderr": True, "-vf": "nonexistentfilter"},
+    ).formulate()
+    assert decoder.returncode is None, "Test failed - returncode set before termination"
+    assert list(decoder.generateFrame()) == [], "Test failed - expected no frames"
+    retcode = decoder.terminate()
+    assert retcode and retcode == decoder.returncode, f"Test failed - got exit code {retcode}"
+    assert any("nonexistentfilter" in line for line in decoder.stderr_tail), (
+        f"Test failed - error missing from stderr_tail: {decoder.stderr_tail}"
+    )
+    # repeated terminate must be idempotent
+    assert decoder.terminate() == retcode, "Test failed - returncode lost on re-terminate"
+
+
+@pytest.mark.parametrize("capture", [True, "yes"])
+def test_capture_stderr_success(capture: Any) -> None:
+    """
+    A cleanly finished pipeline must report exit code 0. Non-bool
+    `-capture_stderr` values are discarded, leaving `stderr_tail` empty.
+    """
+    decoder = FFdecoder(
+        return_testvideo_path(fmt="vo"),
+        custom_ffmpeg=return_static_ffmpeg(),
+        **{"-capture_stderr": capture, "-vframes": 5},
+    ).formulate()
+    assert len(list(decoder.generateFrame())) == 5, "Test failed - expected 5 frames"
+    assert decoder.terminate() == 0, "Test failed - expected exit code 0"
+    assert bool(decoder.stderr_tail) == (capture is True), (
+        f"Test failed - unexpected stderr_tail: {decoder.stderr_tail}"
+    )
+
+
+def test_returncode_on_stream_exhausted() -> None:
+    """
+    Decoding a source to its end and terminating right away must report exit
+    code 0, not a SIGTERM-induced one while FFmpeg is still exiting.
+    """
+    decoder = FFdecoder(
+        return_testvideo_path(fmt="vo"), custom_ffmpeg=return_static_ffmpeg()
+    ).formulate()
+    # discard frames to consume fast, racing FFmpeg exit
+    assert sum(1 for _ in decoder.generateFrame()) > 0, "Test failed - expected frames"
+    assert decoder.terminate() == 0, "Test failed - expected exit code 0"
+
+
+def test_metadata_invalid_type_discarded() -> None:
+    """
+    Assigning an invalid-typed value to a source metadata property must be
+    discarded with a warning, not raise `AttributeError`.
+    """
+    decoder = FFdecoder(
+        return_testvideo_path(fmt="vo"), custom_ffmpeg=return_static_ffmpeg()
+    ).formulate()
+    try:
+        original = json.loads(decoder.metadata)["source_video_pixfmt"]
+        decoder.metadata = {"source_video_pixfmt": 1234}
+        assert json.loads(decoder.metadata)["source_video_pixfmt"] == original, (
+            "Test failed - invalid-typed value was not discarded"
+        )
+    finally:
+        decoder.terminate()
+
+
 @pytest.mark.parametrize(
     "custom_params, checks",
     [
@@ -884,3 +957,140 @@ def test_multi_input_composites(
         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
+
+
+def _side_path(name: str) -> str:
+    return os.path.join(tempfile.gettempdir(), "temp_write", name)
+
+
+test_data = [
+    (
+        {"-extra_outputs": ["-y", "-map", "0", "-c", "copy", _side_path("side_copy.mkv")]},
+        [_side_path("side_copy.mkv")],
+        None,
+    ),
+    (
+        {
+            "-filter_complex": "[0:v]split=2[main][rec];[main]scale=320:-2[main]",
+            "-map": "[main]",
+            "-extra_outputs": [
+                "-y",
+                "-map",
+                "[rec]",
+                "-c:v",
+                "libx264",
+                _side_path("side_split.mp4"),
+            ],
+        },
+        [_side_path("side_split.mp4")],
+        320,
+    ),
+    (
+        {
+            "-extra_outputs": [
+                "-y",
+                "-map",
+                "0:v",
+                "-c:v",
+                "libx264",
+                "-flags",
+                "+global_header",
+                "-f",
+                "tee",
+                # tee treats `\` as escape char, so use forward slashes for Windows paths
+                "{}|[f=mpegts]{}".format(
+                    _side_path("side_tee.mkv"), _side_path("side_tee.ts")
+                ).replace("\\", "/"),
+            ]
+        },
+        [_side_path("side_tee.mkv"), _side_path("side_tee.ts")],
+        None,
+    ),
+]
+
+
+@pytest.mark.parametrize("ffparams, side_files, width", test_data)
+def test_extra_outputs(ffparams: dict[str, Any], side_files: list[str], width: int | None) -> None:
+    """
+    Testing `-extra_outputs` writes side outputs from the same pipeline while frames
+    still reach Python intact (incl. `-filter_complex` labels consumed only by side outputs)
+    """
+    decoder = None
+    source = return_testvideo_path(fmt="av")
+    actual_count, actual_shape = actual_frame_count_n_frame_size(source)
+    os.makedirs(_side_path(""), exist_ok=True)
+    try:
+        decoder = FFdecoder(
+            source, frame_format="bgr24", custom_ffmpeg=return_static_ffmpeg(), **ffparams
+        ).formulate()
+        frames = [f for f in decoder.generateFrame() if f is not None]
+        assert decoder.terminate() == 0, "Test failed - FFmpeg exited with an error"
+        assert len(frames) == actual_count, f"Test failed - got {len(frames)} frames"
+        # width proves output metadata came from the probe, not the source fallback
+        assert frames[0].shape[1] == (width or actual_shape[1]), (
+            f"Test failed - unexpected frame shape {frames[0].shape}"
+        )
+        for side in side_files:
+            # count via FFmpeg, since OpenCV on macOS (AVFoundation) can't read `.mkv`; use
+            # default FFmpeg, as the pinned 2022 static build dies silently probing `.ts` on CI
+            side_decoder = FFdecoder(side).formulate()
+            side_count = sum(f is not None for f in side_decoder.generateFrame())
+            side_decoder.terminate()
+            assert side_count > 0, f"Test failed - empty {side}"
+    except Exception as e:
+        pytest.fail(str(e))
+    finally:
+        decoder is not None and decoder.terminate()
+        for side in side_files:
+            remove_file_safe(side)
+
+
+def test_extra_outputs_early_terminate() -> None:
+    """
+    Terminating mid-stream must still leave a valid (finalized) side `.mp4`
+    """
+    decoder = None
+    side = _side_path("side_early.mp4")
+    os.makedirs(_side_path(""), exist_ok=True)
+    try:
+        decoder = FFdecoder(
+            return_testvideo_path(fmt="av"),
+            frame_format="bgr24",
+            custom_ffmpeg=return_static_ffmpeg(),
+            **{"-extra_outputs": ["-y", "-map", "0:v", "-c:v", "libx264", side]},
+        ).formulate()
+        for num, frame in enumerate(decoder.generateFrame()):
+            if frame is None or num == 9:
+                break
+        decoder.terminate()
+        assert actual_frame_count_n_frame_size(side)[0] >= 10, (
+            "Test failed - side output not finalized"
+        )
+    except Exception as e:
+        pytest.fail(str(e))
+    finally:
+        decoder is not None and decoder.terminate()
+        remove_file_safe(side)
+
+
+@pytest.mark.parametrize("value", ["foo", [["-map", "0"]], {"a": 1}])
+def test_extra_outputs_invalid(value: Any) -> None:
+    """
+    Invalid `-extra_outputs` values must be discarded, leaving normal decoding untouched
+    """
+    decoder = None
+    source = return_testvideo_path(fmt="vo")
+    actual_count, actual_shape = actual_frame_count_n_frame_size(source)
+    try:
+        decoder = FFdecoder(
+            source,
+            frame_format="bgr24",
+            custom_ffmpeg=return_static_ffmpeg(),
+            **{"-extra_outputs": value},
+        ).formulate()
+        frames = [f for f in decoder.generateFrame() if f is not None]
+        assert len(frames) == actual_count and frames[0].shape == actual_shape
+    except Exception as e:
+        pytest.fail(str(e))
+    finally:
+        decoder is not None and decoder.terminate()

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

@@ -159,6 +159,23 @@ def test_check_sp_output_happy_path() -> None:
     assert b"ffmpeg version" in output, "Expected ffmpeg version banner in stdout"
 
 
+def test_check_sp_output_stdin_devnull(monkeypatch: pytest.MonkeyPatch) -> None:
+    """
+    Testing check_sp_output defaults `stdin` to DEVNULL, while honoring caller override.
+    """
+    seen = []
+    real_popen = ffhelper.sp.Popen
+
+    def spy(*args, **kwargs):
+        seen.append(kwargs.get("stdin"))
+        return real_popen(*args, **kwargs)
+
+    monkeypatch.setattr(ffhelper.sp, "Popen", spy)
+    check_sp_output([return_static_ffmpeg(), "-version"], timeout=5.0)
+    check_sp_output([return_static_ffmpeg(), "-version"], stdin=None, timeout=5.0)
+    assert seen == [ffhelper.sp.DEVNULL, None], f"Unexpected stdin values: {seen}"
+
+
 def test_check_sp_output_force_retrieve_stderr_bypass() -> None:
     """
     Testing that `force_retrieve_stderr=True` suppresses CalledProcessError on

deffcode-0.2.8/deffcode/version.py

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