15. API - mmalobj

This module provides an object-oriented interface to libmmal which is the library underlying picamera, raspistill, and raspivid. It is provided to ease the usage of libmmal to Python coders unfamiliar with C and also works around some of the idiosyncracies in libmmal.

15.1. Components

class picamera.mmalobj.MMALComponent

Represents a generic MMAL component. Class attributes are read to determine the component type, and the OPAQUE sub-formats of each connectable port.

close()

Close the component and release all its resources. After this is called, most methods will raise exceptions if called.

control

The MMALControlPort control port of the component which can be used to configure most aspects of the component’s behaviour.

enabled

Retrieves or sets whether the component is currently enabled. When a component is disabled it does not produce or consume data. Components may be implicitly enabled by downstream components.

inputs

A sequence of MMALPort objects representing the inputs of the component.

outputs

A sequence of MMALPort objects representing the outputs of the component.

class picamera.mmalobj.MMALCamera

Bases: picamera.mmalobj.MMALComponent

Represents the MMAL camera component.

The intended use of the output ports (which in turn determines the behaviour of those ports) is as follows:

• Port 0 is intended for preview renderers
• Port 1 is intended for video recording
• Port 2 is intended for still image capture

annotate_rev

The annotation capabilities of the firmware have evolved over time and several structures are available for querying and setting video annotations. By default the MMALCamera class will pick the latest annotation structure supported by the current firmware but you can select older revisions with annotate_rev for other purposes (e.g. testing).

class picamera.mmalobj.MMALCameraInfo

Bases: picamera.mmalobj.MMALComponent

Represents the MMAL camera-info component.

info_rev

The camera information capabilities of the firmware have evolved over time and several structures are available for querying camera information. When initialized, MMALCameraInfo will attempt to discover which structure is in use by the extant firmware. This property can be used to discover the structure version and to modify the version in use for other purposes (e.g. testing).

class picamera.mmalobj.MMALDownstreamComponent

Bases: picamera.mmalobj.MMALComponent

Represents an MMAL component that acts as a filter of some sort, with a single input that connects to an upstream source port. This is an asbtract base class.

class picamera.mmalobj.MMALSplitter

Bases: picamera.mmalobj.MMALDownstreamComponent

Represents the MMAL splitter component.

class picamera.mmalobj.MMALResizer

Bases: picamera.mmalobj.MMALDownstreamComponent

Represents the MMAL resizer component.

class picamera.mmalobj.MMALEncoder

Bases: picamera.mmalobj.MMALDownstreamComponent

Represents a generic MMAL encoder. This is an abstract base class.

class picamera.mmalobj.MMALVideoEncoder

Bases: picamera.mmalobj.MMALEncoder

Represents the MMAL video encoder component.

class picamera.mmalobj.MMALImageEncoder

Bases: picamera.mmalobj.MMALEncoder

Represents the MMAL image encoder component.

class picamera.mmalobj.MMALRenderer

Bases: picamera.mmalobj.MMALDownstreamComponent

Represents the MMAL preview renderer component.

class picamera.mmalobj.MMALNullSink

Bases: picamera.mmalobj.MMALDownstreamComponent

Represents the MMAL null-sink component.

15.2. Ports

class picamera.mmalobj.MMALControlPort(port)

Represents an MMAL port with properties to configure the port’s parameters.

disable()

Disable the port.

enable(callback=None)

Enable the port with the specified callback function (this must be None for connected ports, and a callable for disconnected ports).

The callback function must accept two parameters which will be this MMALControlPort (or descendent) and an MMALBuffer instance. Any return value will be ignored.

flush()

Flush the port.

send_buffer(buf)

Send MMALBuffer buf to the port.

enabled

Returns a bool indicating whether the port is currently enabled. Unlike other classes, this is a read-only property. Use enable() and disable() to modify the value.

index

Returns an integer indicating the port’s position within its owning list (inputs, outputs, etc.)

params

The configurable parameters for the port. This is presented as a mutable mapping of parameter numbers to values, implemented by the MMALPortParams class.

class picamera.mmalobj.MMALPort(port, opaque_subformat='OPQV')

Bases: picamera.mmalobj.MMALControlPort

Represents an MMAL port with properties to configure and update the port’s format. This is the base class of MMALVideoPort, MMALAudioPort, and MMALSubPicturePort.

commit()

Commits the port’s configuration and automatically updates the number and size of associated buffers. This is typically called after adjusting the port’s format and/or associated settings (like width and height for video ports).

copy_from(source)

Copies the port’s format from the source MMALControlPort.

disable()

Disable the port.

enable(callback=None)

Enable the port with the specified callback function (this must be None for connected ports, and a callable for disconnected ports).

The callback function must accept two parameters which will be this MMALControlPort (or descendent) and an MMALBuffer instance. The callback should return True when processing is complete and no further calls are expected (e.g. at frame-end for an image encoder), and False otherwise.

bitrate

Retrieves or sets the bitrate limit for the port’s format.

format

Retrieves or sets the encoding format of the port. Setting this attribute implicitly sets the encoding variant to a sensible value (I420 in the case of OPAQUE).

After setting this attribute, call commit() to make the changes effective.

opaque_subformat

Retrieves or sets the opaque sub-format that the port speaks. While most formats (I420, RGBA, etc.) mean one thing, the opaque format is special; different ports produce different sorts of data when configured for OPQV format. This property stores a string which uniquely identifies what the associated port means for OPQV format.

If the port does not support opaque format at all, set this property to None.

MMALConnection uses this information when negotiating formats for a connection between two ports.

pool

Returns the MMALPool associated with the buffer, if any.

supported_formats

Retrieves a sequence of supported encodings on this port.

Warning

This property does not work on the camera’s still port (MMALCamera.outputs[2]) due to an underlying firmware bug.

class picamera.mmalobj.MMALVideoPort(port, opaque_subformat='OPQV')

Bases: picamera.mmalobj.MMALPort

Represents an MMAL port used to pass video data.

framerate

Retrieves or sets the framerate of the port’s video frames in fps.

After setting this attribute, call commit() to make the changes effective.

framesize

Retrieves or sets the size of the port’s video frames as a (width, height) tuple. This attribute implicitly handles scaling the given size up to the block size of the camera (32x16).

After setting this attribute, call commit() to make the changes effective.

class picamera.mmalobj.MMALSubPicturePort(port, opaque_subformat='OPQV')

Bases: picamera.mmalobj.MMALPort

Represents an MMAL port used to pass sub-picture (caption) data.

class picamera.mmalobj.MMALAudioPort(port, opaque_subformat='OPQV')

Bases: picamera.mmalobj.MMALPort

Represents an MMAL port used to pass audio data.

class picamera.mmalobj.MMALPortParams(port)

Represents the parameters of an MMAL port. This class implements the MMALControlPort.params attribute.

Internally, the class understands how to convert certain structures to more common Python data-types. For example, parameters that expect an MMAL_RATIONAL_T type will return and accept Python’s Fraction class (or any other numeric types), while parameters that expect an MMAL_BOOL_T type will treat anything as a truthy value. Parameters that expect the MMAL_PARAMETER_STRING_T structure will be treated as plain strings, and likewise MMAL_PARAMETER_INT32_T and similar structures will be treated as plain ints.

Parameters that expect more complex structures will return and expect those structures verbatim.

15.3. Connections

class picamera.mmalobj.MMALConnection(source, target)

Represents an MMAL internal connection between two components. The constructor accepts arguments providing the source MMALPort and target MMALPort.

The connection will automatically negotiate the most efficient format supported by both ports (implicitly handling the incompatibility of some OPAQUE sub-formats). See Under the Hood for more information.

15.4. Buffers

class picamera.mmalobj.MMALBuffer(buf)

Represents an MMAL buffer header. This is usually constructed from the buffer header pointer and is largely supplied simply to make working with the buffer’s data a bit simpler; accessing the data attribute implicitly locks the buffer’s memory and returns the data as a bytes string.

copy(data=None)

Return a copy of this buffer header, optionally replacing the data attribute with data which must be an object supporting the buffer protocol.

update(data)

Overwrites the data in the buffer. The data parameter is an object supporting the buffer protocol which contains up to size bytes.

Warning

Some buffer objects cannot be modified without consequence (for example, buffers returned by an encoder’s output port).

command

Returns the command set in the buffer’s meta-data. This is usually 0 for buffers returned by an encoder; typically this is only used by buffers sent to the callback of a control port.

data

Returns the data held in the buffer as a bytes string.

dts

Returns the decoding timestamp (DTS) of the buffer.

flags

Returns the flags set in the buffer’s meta-data.

length

Returns the length of data held in the buffer. This is equal to calling len() on data but faster (as retrieving the buffer’s data requires memory locks in certain cases).

pts

Returns the presentation timestamp (PTS) of the buffer.

size

Returns the length of the buffer’s data area in bytes. This will be greater than or equal to length and is fixed in value.

class picamera.mmalobj.MMALPool(pool)

Construct an MMAL pool containing num buffer headers of size bytes.

get_buffer()

Get the next buffer from the pool.

send_all_buffers(port)

Send all buffers from the pool to port.

send_buffer(port)

Get a buffer from the pool and send it to port.

class picamera.mmalobj.MMALPortPool(port)

Bases: picamera.mmalobj.MMALPool

Construct an MMAL pool for the number and size of buffers required by the MMALPort port.

send_all_buffers(port)

Send all buffers from the pool to the port the pool is associated with.

send_buffer()

Get a buffer from the pool and send it to the port the pool is associated with.

15.5. Debugging

The following functions are useful for quickly dumping the state of a given MMAL pipeline:

picamera.mmalobj.debug_pipeline(port)

Given an MMALVideoPort port, this traces all objects in the pipeline feeding it (including components and connections) and yields each object in turn. Hence the generator typically yields something like:

• MMALVideoPort (the specified output port)
• MMALEncoder (the encoder which owns the output port)
• MMALVideoPort (the encoder’s input port)
• MMALConnection (the connection between the splitter and encoder)
• MMALVideoPort (the splitter’s output port)
• MMALSplitter (the splitter on the camera’s video port)
• MMALVideoPort (the splitter’s input port)
• MMALConnection (the connection between the splitter and camera)
• MMALVideoPort (the camera’s video port)
• MMALCamera (the camera component)

picamera.mmalobj.print_pipeline(port)

Prints a human readable representation of the pipeline feeding the specified MMALVideoPort port.

Note

It is also worth noting that most classes, in particular MMALVideoPort and MMALBuffer have useful repr() outputs which can be extremely useful with simple print() calls for debugging.