12. API - Encoders¶
Encoders are typically used by the camera to compress captured images or video frames for output to disk. However, picamera also has classes representing “unencoded” output (raw RGB, etc). 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
It is strongly recommended that you familiarize yourself with the
mmalobj
layer before attempting to understand the encoder
classes as they deal with several concepts native to that layer.
The inheritance diagram for the following classes is displayed below:
12.1. PiEncoder¶
-
class
picamera.
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).
-
camera_port
¶ The
MMALVideoPort
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
¶ The
MMALComponent
representing the encoder, orNone
if no encoder component has been created (some encoder classes don’t use an actual encoder component, for examplePiRawImageMixin
).
-
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
¶ The
MMALVideoPort
that the encoder should be connected to.
-
output_port
¶ The
MMALVideoPort
that produces 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 whereoutput
is a file-like object, andopened
is a bool indicating whether or not we opened the output object (and thus whether we are responsible for eventually closing it).
-
pool
¶ A pointer to a pool of MMAL buffers.
-
resizer
¶ The
MMALResizer
component, orNone
if no resizer component has been created.
-
_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
MMALPort
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 anMMALBuffer
which can be used to obtain the data to write, along with meta-data about the current frame.This method must set
event
when the encoder has finished (and should setexception
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_write
(buf, key=PiVideoFrameType.frame)[source]¶ Writes output on behalf of the encoder callback function.
This method is called by
_callback()
to handle writing to an object inoutputs
identified by key. The buf parameter is anMMALBuffer
which can be used to obtain the data. 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 indicateTrue
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=PiVideoFrameType.frame)[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_encoder
(format)[source]¶ Creates and configures the
MMALEncoder
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 theoutput_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_resizer
(width, height)[source]¶ Creates and configures an
MMALResizer
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 theresizer
attribute to the constructed resizer component.
-
_open_output
(output, key=PiVideoFrameType.frame)[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, if output has awrite
method it is assumed to be a file-like object and it is used verbatim. If output is neither a string, nor an object with awrite
method it is assumed to be a writeable object supporting the buffer protocol (this is wrapped in aBufferIO
stream to simplify writing).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 returnsFalse
.
-
active
¶ Returns
True
if the MMAL encoder exists and is enabled.
12.2. PiVideoEncoder¶
-
class
picamera.
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 asplit()
method which is used bysplit_recording()
andrecord_sequence()
to redirect future output to a new filename or object. Finally, it also extendsPiEncoder.start()
andPiEncoder._callback_write()
to track video frame meta-data, and to permit recording motion data to a separate output object.-
encoder_type
¶ alias of
picamera.mmalobj.MMALVideoEncoder
-
_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
(format, bitrate=17000000, intra_period=None, profile='high', level='4', quantization=0, quality=0, inline_headers=True, sei=False, sps_timing=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.
-
request_key_frame
()[source]¶ Called to request an I-frame from the encoder.
This method is called by
request_key_frame()
andsplit()
to force the encoder to output an I-frame as soon as possible.
-
split
(output, motion_output=None)[source]¶ Called to switch the encoder’s output.
This method is called by
split_recording()
andrecord_sequence()
to switch the encoder’soutput
object to the output parameter (which can be a filename or a file-like object, as withstart()
).
-
12.3. PiImageEncoder¶
-
class
picamera.
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.).-
encoder_type
¶ alias of
picamera.mmalobj.MMALImageEncoder
-
_create_encoder
(format, quality=85, thumbnail=(64, 48, 35), restart=0)[source]¶ Extends the base
_create_encoder()
implementation to configure the image encoder for JPEG, PNG, etc.
-
12.4. PiRawMixin¶
-
class
picamera.
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.
12.5. PiCookedVideoEncoder¶
-
class
picamera.
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.
12.6. PiRawVideoEncoder¶
-
class
picamera.
PiRawVideoEncoder
(parent, camera_port, input_port, format, resize, **options)[source]¶ Video encoder for unencoded recordings.
This class is a derivative of
PiVideoEncoder
and thePiRawMixin
class intended for use withstart_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.
12.7. PiOneImageEncoder¶
-
class
picamera.
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).-
_callback_write
(buf, key=PiVideoFrameType.frame)[source]¶ Writes output on behalf of the encoder callback function.
This method is called by
_callback()
to handle writing to an object inoutputs
identified by key. The buf parameter is anMMALBuffer
which can be used to obtain the data. 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 indicateTrue
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.
-
12.8. PiMultiImageEncoder¶
-
class
picamera.
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, whilePiEncoder._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.-
_callback_write
(buf, key=PiVideoFrameType.frame)[source]¶ Writes output on behalf of the encoder callback function.
This method is called by
_callback()
to handle writing to an object inoutputs
identified by key. The buf parameter is anMMALBuffer
which can be used to obtain the data. 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 indicateTrue
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.
-
_next_output
(key=0)[source]¶ This method moves output to the next item from the iterable passed to
start()
.
-
_open_output
(output, key=PiVideoFrameType.frame)[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, if output has awrite
method it is assumed to be a file-like object and it is used verbatim. If output is neither a string, nor an object with awrite
method it is assumed to be a writeable object supporting the buffer protocol (this is wrapped in aBufferIO
stream to simplify writing).The opened output is added to the
outputs
dictionary with the specified key.
-
12.9. PiRawImageMixin¶
-
class
picamera.
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__()
).
-
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).
-
12.10. PiCookedOneImageEncoder¶
-
class
picamera.
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.-
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).
-
12.11. PiRawOneImageEncoder¶
-
class
picamera.
PiRawOneImageEncoder
(parent, camera_port, input_port, format, resize, **options)[source]¶ Single image encoder for unencoded capture.
This class is a derivative of
PiOneImageEncoder
and thePiRawImageMixin
class intended for use withcapture()
(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.
12.12. PiCookedMultiImageEncoder¶
-
class
picamera.
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.
12.13. PiRawMultiImageEncoder¶
-
class
picamera.
PiRawMultiImageEncoder
(parent, camera_port, input_port, format, resize, **options)[source]¶ Multiple image encoder for unencoded capture.
This class is a derivative of
PiMultiImageEncoder
and thePiRawImageMixin
class intended for use withcapture_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.