12. API -
The streams module defines stream classes suited to generating certain types of
camera output (beyond those provided by Python by default). Currently, this
consists primarily of
The following classes are defined in the module:
PiCameraCircularIO(camera, size=None, seconds=None, bitrate=17000000, splitter_port=1)¶
A derivative of
CircularIOwhich tracks camera frames.
PiCameraCircularIO provides an in-memory stream based on a ring buffer. It is a specialization of
CircularIOwhich associates video frame meta-data with the recorded stream, accessible from the
The class makes a couple of assumptions which will cause the frame meta-data tracking to break if they are not adhered to:
- the stream is only ever appended to - no writes ever start from the middle of the stream
- the stream is never truncated (from the right; being ring buffer based, left truncation will occur automatically)
The camera parameter specifies the
PiCamerainstance that will be recording video to the stream. If specified, the size parameter determines the maximum size of the stream in bytes. If size is not specified (or
None), then seconds must be specified instead. This provides the maximum length of the stream in seconds, assuming a data rate in bits-per-second given by the bitrate parameter (which defaults to
17000000, or 17Mbps, which is also the default bitrate used for video recording by
PiCamera). You cannot specify both size and seconds.
The splitter_port parameter specifies the port of the built-in splitter that the video encoder will be attached to. This defaults to
1and most users will have no need to specify anything different. If you do specify something else, ensure it is equal to the splitter_port parameter of the corresponding call to
start_recording(). For example:
import picamera with picamera.PiCamera() as camera: with picamera.PiCameraCircularIO(camera, splitter_port=2) as stream: camera.start_recording(stream, format='h264', splitter_port=2) camera.wait_recording(10, splitter_port=2) camera.stop_recording(splitter_port=2)
Returns an iterator over the frame meta-data.
As the camera records video to the stream, the class captures the meta-data associated with each frame (in the form of a
PiVideoFrametuple), discarding meta-data for frames which are no longer fully stored within the underlying ring buffer. You can use the frame meta-data to locate, for example, the first keyframe present in the stream in order to determine an appropriate range to extract.
A thread-safe stream which uses a ring buffer for storage.
CircularIO provides an in-memory stream similar to the
io.BytesIOclass. However, unlike BytesIO its underlying storage is a ring buffer with a fixed maximum size. Once the maximum size is reached, writing effectively loops round to the beginning to the ring and starts overwriting the oldest content.
The size parameter specifies the maximum size of the stream in bytes. The
seek()methods all operate equivalently to those in
write()only differs in the wrapping behaviour described above. A
read1()method is also provided for efficient reading of the underlying ring buffer in write-sized chunks (or less).
A re-entrant threading lock guards all operations, and is accessible for external use via the
The performance of the class is geared toward faster writing than reading on the assumption that writing will be the common operation and reading the rare operation (a reasonable assumption for the camera use-case, but not necessarily for more general usage).
bytescontaining the entire contents of the buffer.
Read up to n bytes from the stream and return them. As a convenience, if n is unspecified or -1,
readall()is called. Fewer than n bytes may be returned if there are fewer than n bytes from the current stream position to the end of the stream.
If 0 bytes are returned, and n was not 0, this indicates end of the stream.
Read up to n bytes from the stream using only a single call to the underlying object.
In the case of
CircularIOthis roughly corresponds to returning the content from the current position up to the end of the write that added that content to the stream (assuming no subsequent writes overwrote the content).
read1()is particularly useful for efficient copying of the stream’s content.
Read and return all bytes from the stream until EOF, using multiple calls to the stream if necessary.
Change the stream position to the given byte offset. offset is interpreted relative to the position indicated by whence. Values for whence are:
0– start of the stream (the default); offset should be zero or positive
1– current stream position; offset may be negative
2– end of the stream; offset is usually negative
Return the new absolute position.
Return the current stream position.
Resize the stream to the given size in bytes (or the current position if size is not specified). This resizing can extend or reduce the current stream size. In case of extension, the contents of the new file area will be NUL (
\x00) bytes. The new stream size is returned.
The current stream position isn’t changed unless the resizing is expanding the stream, in which case it may be set to the maximum stream size if the expansion causes the ring buffer to loop around.
Write the given bytes or bytearray object, b, to the underlying stream and return the number of bytes written.
A re-entrant threading lock which is used to guard all operations.
Return the maximum size of the buffer in bytes.