11. API - picamera.encoders Module

The encoders module defines encoder classes for use by the camera. Most users will have no direct need to use these classes directly, but advanced users may find them useful as base classes for Custom encoders.

Note

All classes in this module are available from the picamera namespace without having to import picamera.encoders directly.

The following classes are defined in the module:

11.1. PiVideoFrameType

class picamera.encoders.PiVideoFrameType[source]

This class simply defines constants used to represent the type of a frame in PiVideoFrame.frame_type. Effectively it is a namespace for an enum.

frame

Indicates a predicted frame (P-frame). This is the most common frame type.

key_frame

Indicates an intra-frame (I-frame) also known as a key frame.

sps_header

Indicates an inline SPS/PPS header (rather than picture data) which is typically used as a split point.

motion_data

Indicates the frame is inline motion vector data, rather than picture data.

New in version 1.5.

11.2. PiVideoFrame

class picamera.encoders.PiVideoFrame(index, frame_type, frame_size, video_size, split_size, timestamp)[source]

This class is a namedtuple derivative used to store information about a video frame. It is recommended that you access the information stored by this class by attribute name rather than position (for example: frame.index rather than frame[0]).

index

Returns the zero-based number of the frame. This is a monotonic counter that is simply incremented every time the camera starts outputting a new frame. As a consequence, this attribute cannot be used to detect dropped frames. Nor does it necessarily represent actual frames; it will be incremented for SPS headers and motion data buffers too.

frame_type

Returns a constant indicating the kind of data that the frame contains (see PiVideoFrameType). Please note that certain frame types contain no image data at all.

frame_size

Returns the size in bytes of the current frame. If a frame is written in multiple chunks, this value will increment while index remains static. Query complete to determine whether the frame has been completely output yet.

video_size

Returns the size in bytes of the entire video up to the current frame. Note that this is unlikely to match the size of the actual file/stream written so far. This is because a stream may utilize buffering which will cause the actual amount written (e.g. to disk) to lag behind the value reported by this attribute.

split_size

Returns the size in bytes of the video recorded since the last call to either start_recording() or split_recording(). For the reasons explained above, this may differ from the size of the actual file/stream written so far.

timestamp

Returns the presentation timestamp (PTS) of the current frame as reported by the encoder. This is represented by the number of microseconds (millionths of a second) since video recording started. As the frame attribute is only updated when the encoder outputs the end of a frame, this value may lag behind the actual time since start_recording() was called.

Warning

Currently, the video encoder occasionally returns “time unknown” values in this field which picamera represents as None. If you are querying this property you will need to check the value is not None before using it.

complete

Returns a bool indicating whether the current frame is complete or not. If the frame is complete then frame_size will not increment any further, and will reset for the next frame.

Changed in version 1.5: Deprecated header and keyframe attributes and added the new frame_type attribute instead.

Changed in version 1.9: Added the complete attribute.

header

Contains a bool indicating whether the current frame is actually an SPS/PPS header. Typically it is best to split an H.264 stream so that it starts with an SPS/PPS header.

Deprecated since version 1.5: Please compare frame_type to PiVideoFrameType.sps_header instead.

keyframe

Returns a bool indicating whether the current frame is a keyframe (an intra-frame, or I-frame in MPEG parlance).

Deprecated since version 1.5: Please compare frame_type to PiVideoFrameType.key_frame instead.

position

Returns the zero-based position of the frame in the stream containing it.

11.3. PiEncoder

class picamera.encoders.PiEncoder(parent, camera_port, input_port, format, resize, **options)[source]

Base implementation of an MMAL encoder for use by PiCamera.

The parent parameter specifies the PiCamera instance that has constructed the encoder. The camera_port parameter provides the MMAL camera port that the encoder should enable for capture (this will be the still or video port of the camera component). The input_port parameter specifies the MMAL port that the encoder should connect to its input. Sometimes this will be the same as the camera port, but if other components are present in the pipeline (e.g. a splitter), it may be different.

The format parameter specifies the format that the encoder should produce in its output. This is specified as a string and will be one of the following for image encoders:

  • 'jpeg'
  • 'png'
  • 'gif'
  • 'bmp'
  • 'yuv'
  • 'rgb'
  • 'rgba'
  • 'bgr'
  • 'bgra'

And one of the following for video encoders:

  • 'h264'
  • 'mjpeg'

The resize parameter is either None (indicating no resizing should take place), or a (width, height) tuple specifying the resolution that the output of the encoder should be resized to.

Finally, the options parameter specifies additional keyword arguments that can be used to configure the encoder (e.g. bitrate for videos, or quality for images).

The class has a number of attributes:

camera_port

A pointer to the camera output port that needs to be activated and deactivated in order to start/stop capture. This is not necessarily the port that the encoder component’s input port is connected to (for example, in the case of video-port based captures, this will be the camera video port behind the splitter).

encoder

A pointer to the MMAL encoder component, or None if no encoder component has been created (some encoder classes don’t use an actual encoder component, for example PiRawImageMixin).

encoder_connection

A pointer to the MMAL connection linking the encoder’s input port to the camera, splitter, or resizer output port (depending on configuration), if any.

event

A threading.Event instance used to synchronize operations (like start, stop, and split) between the control thread and the callback thread.

exception

If an exception occurs during the encoder callback, this attribute is used to store the exception until it can be re-raised in the control thread.

format

The image or video format that the encoder is expected to produce. This is equal to the value of the format parameter.

input_port

A pointer to the MMAL port that the encoder component’s input port should be connected to.

output_port

A pointer to the MMAL port of the encoder’s output. In the case no encoder component is created, this should be the camera/component output port responsible for producing data. In other words, this attribute must be set on initialization.

outputs

A mapping of key to (output, opened) tuples where output is a file-like object, and opened is a bool indicating whether or not we opened the output object (and thus whether we are responsible for eventually closing it).

outputs_lock

A threading.Lock() instance used to protect access to outputs.

parent

The PiCamera instance that created this PiEncoder instance.

pool

A pointer to a pool of MMAL buffers.

resizer

A pointer to the MMAL resizer component, or None if no resizer component has been created.

resizer_connection

A pointer to the MMAL connection linking the resizer’s input port to the camera or splitter’s output port, if any.

_callback(port, buf)[source]

The encoder’s main callback function.

When the encoder is active, this method is periodically called in a background thread. The port parameter specifies the MMAL port providing the output (typically this is the encoder’s output port, but in the case of unencoded captures may simply be a camera port), while the buf parameter is an MMAL buffer header pointer which can be used to obtain the data to write, along with meta-data about the current frame.

This method must release the MMAL buffer header before returning (failure to do so will cause a lockup), and should recycle buffers if expecting further data (the _callback_recycle() method can be called to perform the latter duty). Finally, this method must set event when the encoder has finished (and should set exception if an exception occurred during encoding).

Developers wishing to write a custom encoder class may find it simpler to override the _callback_write() method, rather than deal with these complexities.

_callback_recycle(port, buf)[source]

Recycles the buffer on behalf of the encoder callback function.

This method is called by _callback() when there is a buffer to recycle (because further output is expected). It is unlikely descendent classes will have a need to override this method, but if they override the _callback() method they may wish to call it.

_callback_write(buf, key=0)[source]

Writes output on behalf of the encoder callback function.

This method is called by _callback() to handle writing to an object in outputs identified by key. The buf parameter is an MMAL buffer header pointer which can be used to obtain the length of data available (buf[0].length), a pointer to the data (buf[0].data) which should typically be used with ctypes.string_at(), and meta-data about the contents of the buffer (buf[0].flags). The method is expected to return a boolean to indicate whether output is complete (True) or whether more data is expected (False).

The default implementation simply writes the contents of the buffer to the output identified by key, and returns True if the buffer flags indicate end of stream. Image encoders will typically override the return value to indicate True on end of frame (as they only wish to output a single image). Video encoders will typically override this method to determine where key-frames and SPS headers occur.

_close_output(key=0)[source]

Closes the output associated with key in outputs.

Closes the output object associated with the specified key, and removes it from the outputs dictionary (if we didn’t open the object then we attempt to flush it instead).

_create_connections()[source]

Creates all connections between MMAL components.

This method is called to connect the encoder and the optional resizer to the input port provided by the camera. It sets the encoder_connection and resizer_connection attributes as required.

_create_encoder()[source]

Creates and configures the MMAL encoder component.

This method only constructs the encoder; it does not connect it to the input port. The method sets the encoder attribute to the constructed encoder component, and the output_port attribute to the encoder’s output port (or the previously constructed resizer’s output port if one has been requested). Descendent classes extend this method to finalize encoder configuration.

Note

It should be noted that this method is called with the initializer’s option keyword arguments. This base implementation expects no additional arguments, but descendent classes extend the parameter list to include options relevant to them.

_create_pool()[source]

Allocates a pool of MMAL buffers for the encoder.

This method is expected to construct an MMAL pool of buffers for the output_port, and store the result in the pool attribute.

_create_resizer(width, height)[source]

Creates and configures an MMAL resizer component.

This is called when the initializer’s resize parameter is something other than None. The width and height parameters are passed to the constructed resizer. Note that this method only constructs the resizer - it does not connect it to the encoder. The method sets the resizer attribute to the constructed resizer component.

_open_output(output, key=0)[source]

Opens output and associates it with key in outputs.

If output is a string, this method opens it as a filename and keeps track of the fact that the encoder was the one to open it (which implies that _close_output() should eventually close it). Otherwise, output is assumed to be a file-like object and is used verbatim. The opened output is added to the outputs dictionary with the specified key.

close()[source]

Finalizes the encoder and deallocates all structures.

This method is called by the camera prior to destroying the encoder (or more precisely, letting it go out of scope to permit the garbage collector to destroy it at some future time). The method destroys all components that the various create methods constructed and resets their attributes.

start(output)[source]

Starts the encoder object writing to the specified output.

This method is called by the camera to start the encoder capturing data from the camera to the specified output. The output parameter is either a filename, or a file-like object (for image and video encoders), or an iterable of filenames or file-like objects (for multi-image encoders).

stop()[source]

Stops the encoder, regardless of whether it’s finished.

This method is called by the camera to terminate the execution of the encoder. Typically, this is used with video to stop the recording, but can potentially be called in the middle of image capture to terminate the capture.

wait(timeout=None)[source]

Waits for the encoder to finish (successfully or otherwise).

This method is called by the owning camera object to block execution until the encoder has completed its task. If the timeout parameter is None, the method will block indefinitely. Otherwise, the timeout parameter specifies the (potentially fractional) number of seconds to block for. If the encoder finishes successfully within the timeout, the method returns True. Otherwise, it returns False.

active

Returns True if the MMAL encoder exists and is enabled.

11.4. PiVideoEncoder

class picamera.encoders.PiVideoEncoder(parent, camera_port, input_port, format, resize, **options)[source]

Encoder for video recording.

This derivative of PiEncoder configures itself for H.264 or MJPEG encoding. It also introduces a split() method which is used by split_recording() and record_sequence() to redirect future output to a new filename or object. Finally, it also extends PiEncoder.start() and PiEncoder._callback_write() to track video frame meta-data, and to permit recording motion data to a separate output object.

_callback_write(buf, key=0)[source]

Extended to implement video frame meta-data tracking, and to handle splitting video recording to the next output when split() is called.

_create_encoder(bitrate=17000000, intra_period=None, profile='high', quantization=0, quality=0, inline_headers=True, sei=False, motion_output=None, intra_refresh=None)[source]

Extends the base _create_encoder() implementation to configure the video encoder for H.264 or MJPEG output.

split(output, motion_output=None)[source]

Called to switch the encoder’s output.

This method is called by split_recording() and record_sequence() to switch the encoder’s output object to the output parameter (which can be a filename or a file-like object, as with start()).

start(output, motion_output=None)[source]

Extended to initialize video frame meta-data tracking.

11.5. PiImageEncoder

class picamera.encoders.PiImageEncoder(parent, camera_port, input_port, format, resize, **options)[source]

Encoder for image capture.

This derivative of PiEncoder extends the _create_encoder() method to configure the encoder for a variety of encoded image outputs (JPEG, PNG, etc.).

_create_encoder(quality=85, thumbnail=(64, 48, 35), bayer=False)[source]

Extends the base _create_encoder() implementation to configure the image encoder for JPEG, PNG, etc.

11.6. PiRawMixin

class picamera.encoders.PiRawMixin(parent, camera_port, input_port, format, resize, **options)[source]

Mixin class for “raw” (unencoded) output.

This mixin class overrides the initializer of PiEncoder, along with _create_resizer() and _create_encoder() to configure the pipeline for unencoded output. Specifically, it disables the construction of an encoder, and sets the output port to the input port passed to the initializer, unless resizing is required (either for actual resizing, or for format conversion) in which case the resizer’s output is used.

_callback_write(buf, key=0)[source]

Overridden to strip alpha bytes when required.

_create_connections()[source]

Overridden to skip creating an encoder connection; only a resizer connection is required (if one has been configured).

_create_encoder()[source]

Overridden to skip creating an encoder. Instead, this class simply uses the resizer’s port as the output port (if a resizer has been configured) or the specified input port otherwise.

_create_resizer(width, height)[source]

Overridden to configure the resizer’s output with the required encoding.

11.7. PiCookedVideoEncoder

class picamera.encoders.PiCookedVideoEncoder(parent, camera_port, input_port, format, resize, **options)[source]

Video encoder for encoded recordings.

This class is a derivative of PiVideoEncoder and only exists to provide naming symmetry with the image encoder classes.

11.8. PiRawVideoEncoder

class picamera.encoders.PiRawVideoEncoder(parent, camera_port, input_port, format, resize, **options)[source]

Video encoder for unencoded recordings.

This class is a derivative of PiVideoEncoder and the PiRawMixin class intended for use with start_recording() when it is called with an unencoded format.

Warning

This class creates an inheritance diamond. Take care to determine the MRO of super-class calls.

11.9. PiOneImageEncoder

class picamera.encoders.PiOneImageEncoder(parent, camera_port, input_port, format, resize, **options)[source]

Encoder for single image capture.

This class simply extends _callback_write() to terminate capture at frame end (i.e. after a single frame has been received).

11.10. PiMultiImageEncoder

class picamera.encoders.PiMultiImageEncoder(parent, camera_port, input_port, format, resize, **options)[source]

Encoder for multiple image capture.

This class extends PiImageEncoder to handle an iterable of outputs instead of a single output. The _callback_write() method is extended to terminate capture when the iterable is exhausted, while PiEncoder._open_output() is overridden to begin iteration and rely on the new _next_output() method to advance output to the next item in the iterable.

_next_output(key=0)[source]

This method moves output to the next item from the iterable passed to start().

11.11. PiRawImageMixin

class picamera.encoders.PiRawImageMixin(parent, camera_port, input_port, format, resize, **options)[source]

Mixin class for “raw” (unencoded) image capture.

The _callback_write() method is overridden to manually calculate when to terminate output.

_callback_write(buf, key=0)[source]

Overridden to manually calculate when to terminate capture (see comments in __init__()).

11.12. PiCookedOneImageEncoder

class picamera.encoders.PiCookedOneImageEncoder(parent, camera_port, input_port, format, resize, **options)[source]

Encoder for “cooked” (encoded) single image output.

This encoder extends PiOneImageEncoder to include Exif tags in the output.

11.13. PiRawOneImageEncoder

class picamera.encoders.PiRawOneImageEncoder(parent, camera_port, input_port, format, resize, **options)[source]

Single image encoder for unencoded capture.

This class is a derivative of PiOneImageEncoder and the PiRawImageMixin class intended for use with capture() (et al) when it is called with an unencoded image format.

Warning

This class creates an inheritance diamond. Take care to determine the MRO of super-class calls.

11.14. PiCookedMultiImageEncoder

class picamera.encoders.PiCookedMultiImageEncoder(parent, camera_port, input_port, format, resize, **options)[source]

Encoder for “cooked” (encoded) multiple image output.

This encoder descends from PiMultiImageEncoder but includes no new functionality as video-port based encodes (which is all this class is used for) don’t support Exif tag output.

11.15. PiRawMultiImageEncoder

class picamera.encoders.PiRawMultiImageEncoder(parent, camera_port, input_port, format, resize, **options)[source]

Multiple image encoder for unencoded capture.

This class is a derivative of PiMultiImageEncoder and the PiRawImageMixin class intended for use with capture_sequence() when it is called with an unencoded image format.

Warning

This class creates an inheritance diamond. Take care to determine the MRO of super-class calls.