Circular Buffer Recording

Relevant source files

The following files were used as context for generating this wiki page:

• picamera2/outputs/circularoutput.py
• picamera2/outputs/circularoutput2.py
• picamera2/picamera2.py
• CHANGELOG.md
• tests/test_list.txt
• apps/app_full.py

Circular buffer recording is a powerful feature in picamera2 that enables "pre-event" recording. It continuously stores the most recent video frames in an in-memory buffer of a fixed size or duration. When a trigger event occurs, the contents of this buffer can be saved to a file, effectively capturing video from before the event happened. This is particularly useful for applications like security cameras or dashcams, where you want to save footage leading up to a detected motion or impact.

The picamera2 library provides two main classes for this purpose: CircularOutput and CircularOutput2. While CircularOutput is a simpler, legacy implementation for direct file output, CircularOutput2 is a more modern and flexible class that can work with various output types, including those that handle audio and video muxing, such as PyavOutput.

Core Components

The circular buffer functionality is primarily implemented through two Output subclasses.

CircularOutput

The CircularOutput class is a straightforward implementation that inherits from FileOutput. It maintains a circular buffer of a specified number of frames and is designed to write directly to a file.

Sources: picamera2/outputs/circularoutput.py

Class Diagram

This diagram shows that CircularOutput is a specialized type of FileOutput.

Key Characteristics

• Buffer Sizing: The buffer size is defined by the buffersize parameter, which specifies the number of frames to keep in memory. The default is 150 frames (30fps * 5s).
• Internal Mechanism: It uses a collections.deque with a maxlen to automatically discard old frames as new ones arrive.
• Output: When stop() is called, it flushes the entire buffer to the specified file, starting from the first available keyframe to ensure a valid video file.
• Limitation: It explicitly does not support audio streams, raising a RuntimeError if an audio frame is passed to outputframe.

Sources: picamera2/outputs/circularoutput.py:10-75

Configuration

Parameter	Type	Description	Default
file	str or BufferedIOBase	The file to write frames to.	None
buffersize	int	The number of frames to store in the circular buffer.	150
outputtofile	bool	If True, frames are written to the file as they are received and popped.	True

Sources: picamera2/outputs/circularoutput.py:13-25

CircularOutput2

Introduced in version 0.3.23, CircularOutput2 is a more advanced and flexible circular buffer. It inherits directly from the base Output class and is designed to wrap other Output objects, such as PyavOutput or FfmpegOutput, allowing for time-shifted recordings into complex container formats like MP4 with both video and audio.

Sources: picamera2/outputs/circularoutput2.py, CHANGELOG.md:81

Class Diagram

This diagram shows that CircularOutput2 is a type of Output and can contain another Output object.

Key Characteristics

• Buffer Sizing: The buffer size is defined by buffer_duration_ms, specifying the duration of video to keep in milliseconds.
• General Purpose: It can be used with any other Output object, making it highly versatile. This is its main advantage over CircularOutput.
• Dynamic Output: Recording to a final destination is controlled by open_output(output) and close_output(). This allows an application to start saving the buffered content to a file on demand.
• Audio Support: It can handle audio frames, which are passed to the underlying output object, enabling synchronized audio-video recording.
• Flushing: When stop() is called, if an output is still open, the remainder of the buffer is flushed to it. Frames are also flushed from the buffer as they expire based on buffer_duration_ms.

Sources: picamera2/outputs/circularoutput2.py:9-116

Configuration

Property/Method	Description
buffer_duration_ms	A property to get or set the duration of the buffer in milliseconds. Can be changed dynamically.
open_output(output)	Takes an Output object (e.g., FfmpegOutput) and starts writing the buffered frames to it.
close_output()	Stops writing to the current underlying output object.

Sources: picamera2/outputs/circularoutput2.py:28-67

Workflow and Usage

The typical workflow for circular recording involves starting the camera with a circular output and then, upon some trigger, saving the buffered content.

The following diagram illustrates a common sequence using CircularOutput2 to save a pre-event recording to an MP4 file.

This sequence diagram shows an application setting up a 4-second circular buffer. After a trigger, it opens an FfmpegOutput to save the buffered 4 seconds plus an additional 5 seconds of post-event footage to video.mp4.

Sources: picamera2/outputs/circularoutput2.py:9-17, picamera2/picamera2.py:1396-1418, apps/app_full.py:165-182, tests/test_list.txt

Comparison: CircularOutput vs. CircularOutput2

Feature	CircularOutput	CircularOutput2
Inheritance	FileOutput	Output
Buffer Unit	Number of frames (buffersize)	Milliseconds (buffer_duration_ms)
Audio Support	No	Yes
Output Target	Direct to a single file stream	Wraps any other Output object (e.g., FfmpegOutput, PyavOutput, FileOutput)
Control	start()/stop() writes entire buffer to file	open_output()/close_output() for on-demand saving
Use Case	Simple, video-only pre-event capture to a raw stream file.	Flexible, time-shifted recording to container formats (e.g., MP4) with audio.

Sources: picamera2/outputs/circularoutput.py, picamera2/outputs/circularoutput2.py

Summary

Circular buffer recording is an essential feature for surveillance and monitoring applications. picamera2 offers two implementations: the basic CircularOutput for simple video-only scenarios and the powerful CircularOutput2 for more complex use cases involving different output containers and audio streams. For most modern applications, CircularOutput2 is the recommended choice due to its flexibility and ability to integrate with other Output types, enabling the creation of standard video files like MP4s complete with audio.

Sources: picamera2/outputs/circularoutput.py, picamera2/outputs/circularoutput2.py