![]() |
![]() |
![]() |
![]() |
Neutrino multimedia playback controller
io-media-generic [options]
ARM, PowerPC, SH, x86
The io-media-generic controller is required by the MME to manage media playback. HMI applications that use the MME don't access io-media-generic directly. All playback and ripping requests are passed via the MME's API.
How to configure io-media and its modules, and the implications of different configurations is described under the following headings:
The io-media-generic controller presents a generic API to clients (such as the MME), but the implementation of its functionality is contained in various modules. At compile time, io-media can be configured to use different modules, depending on target hardware and the media types to be played. The default io-media-generic includes modules that use the Multimedia Framework 2 (MMF2, called simply MMF) for decoding and encoding media files. This decoding and encoding can be performed entirely by the software, by a combination of software and hardware.
At system startup, You can alter the behavior of the modules by changing default settings, either with the -M command-line option at system startup, or by changing the io-media configuration file.
For more information about specific modules and their options, see the relevant sections below.
![]() |
If you require an alternative software framework for media playback, or have a hardware DSP solution on your target, you can use a customized variant of io-media. Contact your QNX sales representative for more information. |
When a module creates a graph to play a media file, the graph spawns various threads to read, process, and play the media data. Global options are applied to all modules.
Global options that set priorities apply to all threads spawned by modules:
The ability to apply MMF resources to a specified filter rather than to the entire graph is implemented in the following io-media modules:
Depending on the graph, the filter= attribute can be set to one of reader, parser, decoder, audio_writer, rawfile_writer, or wavfile_writer.
The resource is applied to the filter after its input is attached, but before its output is examined, except in the case of writer filters, for which the resource is applied before the input is attached.
![]() |
The filter= attribute is optional. If it is not specified, the resource is applied to the graph after it has been built, but before it is finalized. |
The mmf_graphbuilder module builds graphs used by the mmf_trackplayer module. For information about this module, see “mmf_trackplayer options” below.
The mmf_graphbuilder module has these options:
![]() |
You should alter this setting only if you understand how your writer filter is implemented to build graphs, and how your audio driver/hardware handles multiple connections. Attempting to establish two writer filter connections to an audio driver that supports only one connection can produce unexpected results. |
Track buffering is managed by a media graph. The mmf_graphbuilder module creates a new graph for every track it's requested to play. This option determines how the module builds the graph for the next track when the first graph has finished reading track data, but hasn't yet finished writing the buffered track data to the audio output.
The default is none.
The queue options are for two types of buffer queues:
When the MME receives the high water event, it delivers the user event MME_PLAY_ERROR_INPUTUNDERRUN to the client application.
By default, one resource is set: MM_CDDA_READ_MAX_RETRY is set to 0 (zero), which disables automatic retries at the streamer level.
![]() |
See the caution for the pre-buffer option above before altering this setting. |
The trans setting can be one of:
The default is none.
If the trans setting is none or stop, the old graph is destroyed after the new graph has begun playing. These options provide a more rapid transition, but require sufficient memory to build a new graph before the memory allocated for the old graph's buffers has been freed.
The mmf_trackplayer module monitors and controls a graph after it has been built by mmf_graphbuilder. For information about this module, see “mmf_graphbuilder options” above.
The mmf_trackplayer module interprets client requests and sends events to the client. It has these options:
The default value is 2: delay playback until the buffer reaches the low-water mark.
The cdda_trackplayer module contains functionality for playing audio CDs. It has these options:
The default value is 2: delay playback until the buffer reaches the low-water mark.
The trackcopier module contains functionality for media copying and ripping. Its option is a list of filter resources to apply to the mmf graph after the graph is built:
You can repeat the resource option as many times as necessary to list all the required filter resources. By default, one resource is set: MM_RAWFILE_WRITER_BUFFER_SIZE is set to 16384, which specifies the buffer size the graph uses when writing the copied or ripped file.
The mmf module contains MMF-specific functionality, and has these options:
![]() |
If you change the audio_writer, make sure the supporting DLL is available to io-media. |
The default is none.
![]() |
It may not be safe to use the used or all settings with some filter DLLs, depending on how they are designed. It is safer to use the aoi module options to keep specific DLLs loaded. |
This module contains Addon Interface functionality, used by the mmf module. You can force io-media to load a filter DLL and keep it memory using this option:
load { dll = /dll/media/somedll.so keep = "yes" }
There is no corresponding -M command-line setting for this option; you need to use a configuration file to set it. See “Configuration File” below.
The damping_audio_writer filter can fade the PCM stream IN or OUT.
To have this filter drop the volume level during trickplay mode by ramping down the PCM stream use, modify the io-media configuration file so that io-media MMF-based graphs use the damping_audio_writer filter as the audio output filter. For more information, see “Configuring output writer filters” below.
The following resources are supported:
If you use the TrickPlayVolumeFade resource with the mmf_graphbuilder module, make sure that the filter attribute is set to “audio_writer”. Below is a portion of an io-media configuration file showing how to set these resources:
module-options { module = "mmf_graphbuilder" ... resource { filter = "audio_writer" name = "TrickPlayVolumeFade" type = long value = 10 optional = yes } resource { name = "TrickFadeTime" type = long value = 20000 optional = yes } resource { name = "FadeTime" type = long value = 20000 optional = yes } }
![]() |
|
A copy of the relevant default configuration file is shipped with each io-media variant. You can copy and modify this file, then specify a configuration file to override io-media-generic's built-in default settings using the -c command-line option.
The configuration file is a plain-text file with the following format:
io-media-config { # lines starting with a # character are comments # 1 global options section: global-options { # priority settings applied to all modules } # 1 or more module-options sections: module-options { module = module name # followed by module-specific settings } }
This is an sample configuration file, showing the default settings:
io-media-config { global-options { audio-hi-prio=22 audio-mid-prio=15 audio-lo-prio=12 play-status-prio=14 rip-prio = 9 } module-options { module = "cdda_trackplayer" skip-on-error = 200,100,10 queue-time = 15000 # Prefetch options. 0 = disable, 1 = resume on high water mark, 2 = resume on low # water mark, 3 = resume on high water mark, pause on low water mark. prefetch = 2 # dts_writer, if not "", specifies a different writer filter for DTS CDs dts_writer = "" } module-options { module = "trackcopier" # MMF resources here resource { name = "MM_RAWFILE_WRITER_BUFFER_SIZE" type = long value = 16384 optional = yes } } module-options { module = "mmf_graphbuilder" queue1-size = 49 queue1-pre-hw = 80 queue1-pre-lw = 20 queue1-time = 12000 queue2-size = 8 queue2-pre-hw = 90 queue2-pre-lw = 10 queue2-time = 1000 # pre-buffer can be "none", "stream", "parser", "build", or "start" pre-buffer = none # What to do with the old graph before starting the new one: # "none", "stop", or "destroy" transition = none resource { name = "MM_CDDA_READ_MAX_RETRY" type = long value = 0 optional = yes } format { url = "cdda:*" parser = "cdda_parser" } format { url = "*.mp[a123]" parser = "mpega_parser" decoder = "xing_mpega_decoder" } format { url = "*.mp4" parser = "mp4_parser" decoder = "qnx_raac_decoder" } format { url = "*.m4a" parser = "mp4_parser" decoder = "qnx_raac_decoder" } format { url = "*.aac" parser = "aac_parser" decoder = "qnx_raac_decoder" } format { url = "*.wma" parser = "wma9_parser" decoder = "wma9_decoder" } format { url = "*.wav" parser = "wav_parser" } } module-options { module = "mmf_trackplayer" # If skip on error is not "no", it defines the number of milliseconds # to skip on a read error, the percentage to grow it by on each subsequent error, # and the maximum number of skips. skip-on-error = 200,100,10 # Prefetch options. 0 = disable, 1 = resume on high water mark, 2 = resume on low # water mark, 3 = resume on high water mark, pause on low water mark. prefetch = 2 } module-options { module = "mmf" audio_writer { url = "snd:*" filter = "audio_writer" } video_writer { url = "gf:*" filter = "gf_writer" } dlldir = "$MM_INIT" # keepdlls can be: # "none" (unload any DLLs when they aren't in use) # "used" (after a DLL is first used, keep it loaded forever) # "all" (permanently load all DLLs from the specified directory) keepdlls = "none" } module-options { module = "aoi" # For each DLL you want to load, specify a "load" element like this: # load { # dll = "/dll/media/somedll.so" # keep = "yes" # } } }
The mmf module specifies the writer filters used to deliver audio and video streams to output devices. When an MMF-based io-media graph receives the URL of an audio or video output device, the graph selects a writer filter based on the output type (audio or video) and the URL of the device, using a list of audio_writer and video_writer elements in the io-media configuration file. Both types of element contain a pattern to match against the URL, and the name of the writer filter to use for devices that match the pattern.
If no matching element of the appropriate type is found for a device URL, the device is rejected, unless the (deprecated) audio_writer or video_writer attribute is also specified, in which case the value of this attribute names the filter to use.
For example, with the configuration shown below, assuming no other video_writer configuration elements or attributes, if the graph is asked to output to a video device whose URL matches the pattern specified by the url attribute (“gf:*”), it will use gf_writer; if no match is found the graph will reject the URL.
module-options { module = "mmf" ... video_writer { url = "gf:*" filter = "gf_writer" } ... }
To update the io-media configuration file, after installing the latest release of io-media:
To have io-media-generic use dynamic filters at least one of the following must be true:
The default io-media configuration loads some filters and streamers permanently into memory; other filters are loaded and unloaded dynamically when necessary.
Some filters are loaded permanently because they are needed by the majority of graphs; if any of these required filters are missing, there is a high probability that io-media will not be able to play any media. These filters are, therefore, specified as required by the default configuration; if any of these filters are missing, io-media will exit at startup.
Some other filters are loaded permanently because they might be used for potentially high-bandwidth operations that could be significantly slowed down by having to load and unload filters. These filters typically support a particular operation or media type; if they are missing, io-media will not be able to play some media but will have no problems playing other media. Some of these filters are shipped in a separate, optional package, and may not be present on some targets. These filters are flagged as optional in the default configuration; if they are missing, io-media logs a warning to the system log, but does not treat the situation as a fatal error.
You can change the minimum DLL set that io-media maintains in memory in order to make optimal use for your environment of the system resources you have available. Generally, the more DLLs in memory, the better the performance but the greater the memory required.
The io-media configuration file includes multiple keepdll elements under the mmf module's module-options element. Each keepdll element determines if the named filter or streamer is in the set or is optional.
The default setting is required: if it the DLL is missing, log an error and exit. Thus, in the example below:
module-options { ... keepdll { name = "tmpfile_streamer" optional = yes } keepdll { name = "stream_reader" } ... }
You can also use the keepdlls (note the final “s”) element to specify DLLs to keep by an interface name, rather than by the DLL name. This approach allows you to use, for example, one element to load all streamers, while another element loads all parsers. For example:
keepdlls { # Keep all the DLLs that have the specified interface interface = "AOStreamer" } keepdlls { interface = "MediaMetadataParser" }
Since the keepdlls element was implemented, the default io-media configuration no longer has a keepdll entry for the optional streamers and parsers. Note, however, that the configuration maintains keepdll entries for non-optional (mandatory) DLLs, to ensure that io-media fails if any of these DLLs are missing.
To ensure system efficiency, all io-media DLLs should be installed in their own, exclusive directory, such as, for example, /lib/dll/media. No other libraries should be installed at this location, because io-media loads all DLLs from its DLL directory in order to check if it can recognize them as MMF filters or as other Addon Interface (aoi) DLLs. Placing io-media DLLs in a directory with other DLLs, such as for example, /proc/boot, may adversely affect system performance.
To set the directory io-media searches for its DLLs, use the module-options element's dlldir attribute in the io-media configuration file.
![]() |
|
If io-media does not find its DLLs it will fail to process the media files for which the missing DLLs are required. If this situation occurs in your environment, you may encounter symptoms such as the following, reported in the slog:
Jan 10 10:04:36 2 20 1 io-media-generic/trackplayer: Error 1 Jan 10 10:04:36 2 20 1 io-media-generic/trackplayer: Couldn't load the MediaReader filter
The information provided in the example above suggests the following problems:
The MMF filters (files with .so extensions) used by io-media are typically installed at lib/dll/mmedia. When you start io-media, it needs to know the path to this directory. You can specify this path by one of the following methods:
Other shared libraries must be in your library search path. This path is specified by the $LD_LIBRARY_PATH environment variable. Make sure that all shared libraries required by io-media are installed in a path specified.
![]() |
|
You can configure io-media for optimal performance when it selects filters for its graphs, when it encounters damaged (scratched) media, and when it attempts to retrieve metadata:
io-media maintains a list of URL patterns that you can associate with filters, filter resources, and options, such as the strict attribute.
To associate filters, filter resources and options with a URL pattern, use the io-media configuration file's format element. The format element can have the following attributes:
To build a graph for a media file, io-media:
If at a later point in the processing a decoder is required (for example, if a stream is encoded and the writer doesn't have a built-in decoder), a similar process is repeated to find a decoder.
If none of the patterns specified by format element url attributes matches the URL for the file to be processed, io-media uses its rating-based query to search for a parser or decoder, as required. That is, io-media proceeeds as though the last format element in its configuration file were configured thus:
format { url = "*" }
When io-media tests for matches of URL patterns, it performs the test in the order of the format elements in its configuration file.
This order is relevant only in the case where more than one pattern could match a URL. In such cases, the most likely configuration would be to place the pattern least likely to match the URL first, since this pattern would typically describe a special case that should be overridden for URLs that match both patterns.
For example, you would list /fs/cd0/*.mp3 before *.mp3 in order to apply special settings for MP3 files on a slow CD-ROM, but apply other settings for all other MP3 files — files on USB sticks and hard drives. Placing the more general *.mp3 pattern first would match all MP3 files, including those on CD-ROMs, and the special settings for these files would never be applied.
The strict attribute causes io-media to fail immediately and return an error if:
or
To use the strict attribute, modify your io-media configuration file (io-media-*.cfg) to include “strict = yes” for each parser for which you want this attribute applied. For example:
format { url = "*.mp[a123]" parser = "mpega_parser" strict = yes }
To speed up failure by rejecting files based on their extensions (i.e. *.pdf), for a specified format set the strict attribute and do not specify a parser. This configuration ensures failure except when the URL calls for a streamer that knows that the stream it must process is uncompressed audio.
A simple way to reject all files that don't have any of the recognized extensions is to add the following format element to your io-media configuration file:
format { url = "*" strict = yes }
![]() |
|
The StickyReadError resource is implemented with the fildes_streamer AOI streamer. This resource reduces the time a client application has to wait for io-media to return with an error after it has encountered damaged or otherwise unreadable media. When this resource is set, a streamer error returned by any read, sniff or seek operation is sticky: after one of these operations fails, the streamer fails all subsequent attempts to perform these operations without actually attempting to read anything from the filesystem.
io-media should set the StickyReadError resource at graph creation time. If io-media is configured for skip-on-error behavior, it should reset the resource at graph playtime, falling back to the skip-on-error configured behavior. If io-media is not configured for skip-on-error behavior, the StickyReadError resource can be maintained for the life for the graph.
The StickyReadError resource feature uses the io-media ability to apply MMF resources to a specified filter rather than to an entire graph. For more information, see “Applying a resource to a filter” above.
To configure io-media to use the StickyReadError resource, you must configure the io-media configuration file to tell io-media:
module = "mmf_graphbuilder" resource { filter = "reader" name = "StreamerStickyError" type = long value = 1 optional = yes }
resource { name = "StreamerStickyError" type = long value = 0 optional = yes }
The resource element configured for a trackplayer can be used, not only when creating a streamer for playback, but also when creating a streamer to use solely for a metadata scan.
The streamer filter attribute values are:
The default io-media configuration uses these new values to set the StreamerStickyError resource for both playback and metadata extraction. To change this configuration, simply change the io-media configuration file. For example, to set the StreamerStickyError resource for playback only, update the file as follows:
module = "mmf_graphbuilder" resource { filter = "streamer/playback" name = "StreamerStickyError" type = long value = 1 optional = yes }
The QuickMetadataScan resource is supported by the mpega_parser filter. Setting this resource instructs io-media to skip time consuming tasks, such as seeking and scanning, when attempting to extract metadata from a file.
If QuickMetadataScan is set, when io-media is asked to play a file and extract its metadata, io-media does not:
![]() |
All io-media variants that load the mpega_parser filter for playback inherit the behavior described above. |
To configure io-media to use the QuickMetadataScan resource, you must configure the io-media configuration under:
module-options { module = "mmf_graphbuilder" ... }
For example, to set the QuickMetadataScan resource on any MP3 files coming from the device mounted at /fs/cd0:
format { url = "/fs/cd0/*.mp[a123]" parser = "mpega_parser" decoder = "xing_mpega_decoder" # You can set MMF graph-level parameters here: graphparam { name = "QuickMetadataScan" value = "1" } }
Or, to set the QuickMetadataScan resource on all MP3 files, regardless of their location:
format { url = "*.mp[a123]" parser = "mpega_parser" decoder = "xing_mpega_decoder" # You can set MMF graph-level parameters here: graphparam { name = "QuickMetadataScan" value = "1" } }
The MM_TMPFILE_STREAMER_SEEKABLE mmf_graphbuilder resource controls whether seeking and trick play acitivities are permitted during a ripping with playback operation. This resource can be:
or:
For example:
resource { name = "MM_TMPFILE_STREAMER_SEEKABLE" type = long value = 0 optional = yes }
An io-media option allows you to set a maximum time io-media will wait for metadata from device, such as an iPod, that manages its own track sessions.
This option applies to the mediafs_2wire graph. The default waiting period is 200 milliseconds.
To configure this option, change the value of the metadata-timeout attribute in the io-media configuration file:
module-options { module = "mediafs_2wire" metadata-timeout = 200 }
io-media includes a configurable resource that sets the reader timeout interval, in microseconds.
To use this resource, update the graphbuilder configuration in the io-media configuration file, following the example below:
resource { filter = "reader" name = "MM_TMPFILE_STREAMER_READ_TIMEOUT" type = long # This timeout is in microseconds: value = 10000000 optional = yes }
The cdda_streamer MM_CDDA_DMA_CAM_READCD_TIMEOUT resource allows you to configure the DMA read timeout period, in seconds. The timeout configured with this resource corresponds to the devb/ATAPI driver's cdrom timeout settings. MM_CDDA_DMA_CAM_READCD_TIMEOUT requires that DMA be enabled. Thus, it can be used if DMA is enabled on CDDA playback, or when performing a ripping operation (DMA is enabled with the MM_CDDA_DMA_CAM_READCD resource). If DMA is not enabled, cdda_streamer ignores this resource .
The MM_CDDA_DMA_CAM_READCD_TIMEOUT resource is set in the io-media configuration file.
If you do not specify the MM_CDDA_DMA_CAM_READCD_TIMEOUT timeout resource, or if you set the timeout to 0 seconds, DMA reads will time out according to the “group 1” timeout of the devb cdrom timeout settings. A non-zero timeout setting for the MM_CDDA_DMA_CAM_READCD_TIMEOUT resource sets the number of seconds before cdda_streamer times out on DMA reads.
![]() |
|
Below is an example from a configuration file:
# Max retries when reading from CDDA: # default value = 0 since devb driver # typically does its own retries resource { filter = "reader" name = "MM_CDDA_READ_MAX_RETRY" type = long value = 0 optional = yes } # Enable DMA reads from CDDA: # value = 0 DMA disabled, value = 1 DMA enabled resource { filter = "reader" name = "MM_CDDA_DMA_CAM_READCD" type = long value = 0 optional = yes } # Drive specific 'readcd.rsvd3' # value to be used when doing DMA reads from CDDA # Note: only applies if DMA is enabled # (MM_CDDA_DMA_CAM_READCD), consult CD drive # specs for value resource { filter = "reader" name = "MM_CDDA_DMA_CAM_READCD_RSVD3" type = long value = 0 optional = yes } # Timeout value in seconds when doing DMA reads from CDDA # Value corresponds to devb driver # 'cdrom timeout' values, value = 0 defaults # to devb group 1 timeout. Note: only applies if DMA # is enabled (MM_CDDA_DMA_CAM_READCD) resource { filter = "reader" name = "MM_CDDA_DMA_CAM_READCD_TIMEOUT" type = long value = 7 optional = yes }
The io-media section of the chapter Architecture, in Introduction to the MME
![]() |
![]() |
![]() |
![]() |