Add SplittableOutput

The SplittableOutput allows switching seamlessly from one output to
another without dropping any frames. The switch-overs can be arranged
to happen at video keyframes, so as to ensure that the final pieces
can be played in isolation.

Signed-off-by: David Plowman <david.plowman@raspberrypi.com>

Author: davidplowman

examples/split_output.py

@@ -0,0 +1,30 @@
+#!/usr/bin/python3
+
+import time
+
+from picamera2 import Picamera2
+from picamera2.encoders import H264Encoder
+from picamera2.outputs import PyavOutput, SplittableOutput
+
+picam2 = Picamera2()
+config = picam2.create_video_configuration()
+picam2.configure(config)
+encoder = H264Encoder(bitrate=5000000)
+
+splitter = SplittableOutput(output=PyavOutput("test0.mp4"))
+
+# Start writing initially to one file, and then we'll switch seamlessly to another.
+# You can omit the initial output, and use split_output later to start the first output.
+picam2.start_recording(encoder, splitter)
+
+time.sleep(5)
+
+# This returns only when the split has happened and the first file has been closed.
+# The second file is guaranteed to continue at an I frame with no frame drops.
+print("Waiting for switchover...")
+splitter.split_output(PyavOutput("test1.mp4"))
+print("Switched to new output!")
+
+time.sleep(5)
+
+picam2.stop_recording()

picamera2/outputs/__init__.py

@@ -4,3 +4,4 @@
 from .fileoutput import FileOutput
 from .output import Output
 from .pyavoutput import PyavOutput
+from .splittableoutput import SplittableOutput

picamera2/outputs/splittableoutput.py

@@ -0,0 +1,72 @@
+from threading import Event
+
+from .output import Output
+
+
+class SplittableOutput(Output):
+    """
+    The SplittableOutput passes the encoded bitstream to another output (or drops them if there isn't one).
+
+    It can be told to "split" the current output that it's been writing to, to another one. This means
+    it switches seamlessly from the current output, which is closed, to a new one, without dropping
+    any frames. By default, it performs the switch at a video keyframem though it can be told not to
+    wait for one (by setting wait_for_keyframe to False).
+    """
+
+    def __init__(self, output=None, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._output = output
+        self._new_output = None
+        self._split_done = Event()
+        self._streams = []
+
+    def split_output(self, new_output, wait_for_keyframe=True):
+        """
+        Terminate the current output, switching seamlessly to the new one.
+
+        If wait_for_keyframe is True, the switch only occurs when the next video keyframe is
+        seen. Otherwise the switch happens immediately.
+
+        THe function returns only when the switch has happened, which may entail waiting for a
+        video keyframe, and the old output has been closed.
+        """
+        old_output = self._output
+        # Start the new outoput in this thread, then schedule outputframe to make the switch.
+        new_output.start()
+        for encoder_stream, codec, kwargs in self._streams:
+            new_output._add_stream(encoder_stream, codec, **kwargs)
+        self._wait_for_keyframe = wait_for_keyframe
+        self._new_output = new_output
+        # Wait for the switch-over to happen, and close the old output in this thread too.
+        self._split_done.wait()
+        self._split_done.clear()
+        if old_output:
+            old_output.stop()
+
+    def outputframe(self, frame, keyframe=True, timestamp=None, packet=None, audio=False):
+        # Audio frames probably always say they're keyframes, but we must wait for a video one.
+        if self._new_output and (not self._wait_for_keyframe or (not audio and keyframe)):
+            self._split_done.set()
+            # split_output will close the old output.
+            self._output = self._new_output
+            self._new_output = None
+        if self._output:
+            self._output.outputframe(frame, keyframe, timestamp, packet, audio)
+
+    def start(self):
+        super().start()
+        if self._output:
+            self._output.start()
+
+    def stop(self):
+        super().stop()
+        if self._output:
+            self._output.stop()
+
+    def _add_stream(self, encoder_stream, codec_name, **kwargs):
+        # The underlying output may need to know what streams it's dealing with, so we must
+        # remember them.
+        self._streams.append((encoder_stream, codec_name, kwargs))
+        # Forward immediately to the output if we were given one initially.
+        if self._output:
+            self._output._add_stream(encoder_stream, codec_name, **kwargs)

tests/split_output_test.py

@@ -0,0 +1,51 @@
+#!/usr/bin/python3
+
+# We're going to encode a video stream, splitting it seamlessly into a pair of
+# files using the SplittableOutput. At the same time we'll write a single output
+# file as well, and check that the split files contain as much as the single file.
+
+import io
+import time
+
+from picamera2 import Picamera2
+from picamera2.encoders import H264Encoder
+from picamera2.outputs import FileOutput, SplittableOutput
+
+picam2 = Picamera2()
+config = picam2.create_video_configuration()
+picam2.configure(config)
+
+first_half = io.BytesIO()
+second_half = io.BytesIO()
+whole = io.BytesIO()
+
+encoder = H264Encoder(bitrate=5000000)
+splitter = SplittableOutput(output=FileOutput(first_half))
+output = FileOutput(whole)
+encoder.output = [splitter, output]
+
+picam2.start_encoder(encoder)
+picam2.start()
+
+time.sleep(5)
+
+splitter.split_output(FileOutput(second_half))
+
+time.sleep(5)
+
+picam2.stop_recording()
+
+first_half_len = first_half.getbuffer().nbytes
+second_half_len = second_half.getbuffer().nbytes
+combined_len = first_half_len + second_half_len
+whole_len = whole.getbuffer().nbytes
+
+print("First half:", first_half_len)
+print("Second half:", second_half_len)
+print("Both halves combined:", combined_len)
+print("Whole output:", whole_len)
+
+if combined_len != whole_len:
+    print("Error: split files do not match the whole file")
+else:
+    print("Files match!")

tests/test_list.txt

@@ -94,5 +94,6 @@ tests/stop_slow_framerate.py
 tests/allocator_test.py
 tests/allocator_leak_test.py
 tests/wait_cancel_test.py
+tests/split_output_test.py
 tests/stride_test.py
 tests/yuv_capture.py