Multimedia renderer architecture

The multimedia rendering component, mm-renderer, allows multimedia applications to request and control the playback of audio and video media from files and devices.

The mm-renderer service provides mechanisms for:

  • specifying the set of media to play
  • issuing playback control commands
  • retrieving the current playback status
  • requesting notifications when the status changes
  • providing dynamic metadata (such as position in a track or playlist) for some media content

The BlackBerry 10 Simulator doesn't include any codecs other than those that support .wav files. To play media files of other formats (for example, .mp3 and .aac), you must use real hardware.

The multimedia renderer API allows you to control media playback and recording, and to receive events to monitor your media operations.

When performing permission-sensitive operations such as opening files, the multimedia renderer uses the client's user ID and group IDs.

Supported media categories

The mm-renderer service supports playback of tracks and playlists. It can play content read either from the local filesystem or through HTTP streams.

A track is an audio or video file such as an MP3 or MP4 file.

A playlist is a list of track URLs. The following types of playlists are supported:

  • M3U files—the input URL must be a full path (with or without a file: or http: prefix) of a file with an M3U extension. In its simplest form, an M3U file is a plain-text file containing the pathnames or URLs of the tracks to play (one per line). Playlists for HTTP Live Streaming (HLS) are supported; these may have M3U and M3U8 file extensions.
  • SQL queries—the input URL must be of the form sql:database?query=querystring , where database is a full path to a database file, and querystring is an SQL query that returns a column of track names. If the query contains any reserved characters, they must be URL-encoded (for example, %26 instead of &).

For the current list of supported media formats, see the online list of supported media for BlackBerry devices on the public BlackBerry website.

Media sources

You can play audio and video tracks that come from the following sources:

To play media content from files, specify the path (in POSIX format) of a local file in the input URL (see mmr_input_attach() for information on setting the input URL).
HTTP streams
To play media content from HTTP sources, specify an HLS source or another type of HTTP stream in the input URL. The mm-renderer service supports cookies, SSL, and authentication, which enables secure playback of HTTP streams.

Abstraction layers

The multimedia renderer uses a layered architecture to process playback commands and manage the flow of media content from input to output.

The mm-renderer architecture consists of three abstraction layers:

  • The messaging layer decodes client messages and delivers them to contexts. A context is an object capable of playing one piece of input media at a time on a set of output devices. The input can contain both audio and video signals (for example, a movie), and the set of outputs can consist of both audio and video devices (for example, speakers and a screen).
  • The context management layer:
    • keeps track of the outputs attached to each context
    • maps each output to the engine plugins that can support that output type
    • selects the appropriate engine plugins and attaches them to the context
    • preserves the context state between detaching and reattaching inputs
    • delivers client requests (such as play) to engine plugins
  • The plugin management layer keeps track of all available plugins.


The mm-renderer service provides contexts, each of which can play a stream of media content concurrently with and independently of other contexts. Each context can direct output to a different set of hardware devices or files, creating independent zones of operation.

The operations that are available for a context at a particular time depend on the input and outputs attached to it. For example, changing playlists won't work unless your input type is a playlist, and seeking to a new track position doesn't apply for some input streams (such as radio stations) or devices (such as microphones). You can use a context for operations other than playing, by setting its output appropriately. For instance, you can record rather than play an audio stream by setting a context's output to a file and its input to an audio capture device (such as a microphone).

Your application must connect to the mm-renderer service before it can create a context. When your application creates a context, the context has a unique name but no other properties are set. For subsequent operations, your application accesses the context through the context handle provided by mm-renderer when it creates the context.

You can control properties of the context's operation (for example, audio volume) by attaching parameters to the context, to the input, or to each of the outputs (for details, see Defining parameters).


Each context has to have one or more outputs attached before it can play anything, so that it can determine where to send the content.

The output can be:

  • a file
  • an audio device
  • a video device

Outputs need to be attached before the input. That's because some engine plugins may determine whether to play an input based on what kind of outputs are attached, and may not support detaching and reattaching outputs after the input is connected.


Each context has to have one input attached, so it knows what to play.

When an input is attached, the context management layer selects the appropriate engine plugin and attaches it to the context. Your application has to identify the input type for mm-renderer because the service doesn't automatically detect the type of the attached input.

The input type determines how mm-renderer responds to certain playback requests, such as seeking to a track position or changing playlists.

Although an input may be attached to more than one context, mm-renderer doesn't detect or manage conflicting playback operations. Your application has to manage potential playback conflicts.


Engine plugins are the components used by mm-renderer to process the flow of media data from an input to one or many outputs.

The implementation of the engine plugins is invisible to mm-renderer (and its clients). The context management layer selects the appropriate engine plugin based on the types of inputs and outputs attached to the context, and on the rating each engine gives itself for the specified inputs and outputs.

Last modified: 2014-09-30

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus