io-media-generic

Neutrino multimedia playback controller

Syntax:

io-media-generic [options]

Runs on:

ARM, PowerPC, SH, x86

Options:

-B
Don't detach to the background.
-c file
Use the options specified in the configuration file file rather than the built-in defaults.
-C
Print the built-in configuration to the standard output, and then exit.
-D
Log more debugging information.
-G graph,options
Pass options to graph (none are currently defined). This overrides the corresponding built-in default, as well as the corresponding setting in the configuration file, if specified with the -c option.
-M module,options
Pass options to module. This overrides the built-in default, as well as the corresponding setting in the configuration file, if specified with the -c option.
-o options
Apply the options to the global options. This overrides the built-in default, as well as the corresponding setting in the configuration file, if specified with the -c option.
-q
Log less debugging information.
-S
Log to stderr instead of slogger.

Description:

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:

io-media modules

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.


Note: 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.

io-media global options

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:

audio-hi-prio=priority
Set the highest priority level for audio graph threads; the default is 22. These threads are typically the writer threads, which pass PCM data to audio hardware, or encoded data to a DSP. To ensure smooth audio playback, other processes that may use the CPU for more than a few milliseconds at a time should not have their priorities set higher than the audio-hi-prio priority.
audio-mid-prio = priority
Set the mid priority level for audio threads; the default is 15. These are typically CPU-intensive threads, such as software decode.
audio-lo-prio = priority
Set the lowest priority level for audio threads; the default is 12. These are typically reader threads, where data is being buffered.
play-status-prio = priority
Set the priority level for time update events; the default is 14.
rip-prio = priority
Set the ripping process priority level; the default is 9.

Applying a resource to a filter

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.


Note: 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.

mmf_graphbuilder options

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:

pre-buffer = setting
Determines how “next” tracks are buffered to reduce the time between tracks (that is, to implement “gapless playback”). For any setting other than none, io-media-generic notifies the client (mme) when it's finished reading a track into a buffer (but it's still playing), so that the client can request a new track to be played.

Caution: 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:

queue1-size = size
queue2-size = size
The number of media buffers to queue. The default for queue1 is 49, and for queue2 the default is 8. You can reduce this number on a memory-constrained device, or increase it to increase the amount of data buffered to counteract network latency for streamed data. The size of each buffer allocated depends on the media type.
queue1-pre-hw = percent
queue1-pre-lw = percent
queue2-pre-hw = percent
queue2-pre-lw = percent
The queue “high water” and “low water” marks, expressed as a percentage between 0 and 100. The queue1 default is 80 for the high water, and 20 for the low water. The queue2 default is 90 for the high water, and 10 for the low water. When the percentage of buffers filled exceeds the high water mark, io-media-generic delivers an event to the MME, and continues to send this event until the percentage of buffers filled falls below the low water mark.

When the MME receives the high water event, it delivers the user event MME_PLAY_ERROR_INPUTUNDERRUN to the client application.

queue1-time = time
queue2-time = time
The maximum time to queue, in milliseconds. The default for queue1 is 12000, and for queue2 it's 1000. If you have more buffers than required by this time, the remaining buffers are allocated but not used. If this time exceeds the amount of buffer space allocated, only the allocated buffers are used, and this value is ignored.
resource
This option sets a specific resource for a graph or, if specified, a filter. The resource settings can be:

By default, one resource is set: MM_CDDA_READ_MAX_RETRY is set to 0 (zero), which disables automatic retries at the streamer level.

transition = trans
This option determines what the module does with the graph for a previous track before starting the graph for the next track.

Caution: 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.

mmf_trackplayer options

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:

prefetch
Prefetch pauses playback to allow media buffers to fill with sufficient data so that there are no interruptions to playback once it has started. This option specifies the prefetch behavior for the filter. If this option is set to 1 or 2, the behavior is applied only when an explicit “play”, “change speed” or “seek-to-time” command is received from a client application, or when a track is started “gapless” when playback of another track is finished. Values can be:

The default value is 2: delay playback until the buffer reaches the low-water mark.

skip-on-error = no | milliseconds[,percent[,max_skips]]
This option sets how the module handles read errors, as follows:

cdda_trackplayer options

The cdda_trackplayer module contains functionality for playing audio CDs. It has these options:

dts_writer = "" | ["module name"]
This option specifies the writer filter to use when playing a DTS CD. When this option is empty (""), the trackplayer will use the default writer filter, as specified by the mmf audio_writer option.
prefetch
Prefetch pauses playback to allow media buffers to fill with sufficient data so that there are no interruptions to playback once it has started. This option specifies the prefetch behavior for the filter. If this option is set to 1 or 2, the behavior is applied only when an explicit “play”, “change speed” or “seek-to-time” command is received from a client application, or when a track is started “gapless” when playback of another track is finished. Values can be:

The default value is 2: delay playback until the buffer reaches the low-water mark.

queue-time
The maximum time to queue, in milliseconds. The default for queue-time is 15000 milliseconds. If you have more buffers than required by this time, the remaining buffers are allocated but not used. If this time exceeds the amount of buffer space allocated, only the allocated buffers are used, and this value is ignored.
skip-on-error = no | milliseconds[,percent[,max_skips]]
This option sets how the module handles read errors. For more information, see the skip-on-error option for mmf_trackplayer above.

trackcopier options

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:

resource
This option sets a specific filter resource. The filter resource properties are:

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.

mmf options

The mmf module contains MMF-specific functionality, and has these options:

audio_writer = audio_filter
This option sets the filter/DLL used by MMF graphs, such as mmf_trackplayer and cdda_trackplayer to write out audio information. The default audio_writer corresponds to the MMF audio_writer.so filter for standard audio output to a PCM device. You can change this setting to a different audio writer filter to support a DSP output, for example.

Note: If you change the audio_writer, make sure the supporting DLL is available to io-media.

dlldir = directory
Set the location of the MMF filters. If this option is not specified, io-media uses the directory specified by the $MM_INIT environment variable. If this option is not specified in the command-line startup, and not specified in the io-media configuration file, io-media reports an error and exits.
keepdlls = setting
This option determines how io-media handles DLLs after they've been loaded. The setting can be one of:

The default is none.


Caution: 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.

utf8hook=conversion_dll.so
This option specifies a DLL to perform custom character conversions.

aoi options

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.

damping_audio_writer filter

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:

TrickPlayVolumeFade
Trickplay volume percent to fade from total volume. Default is 0. Range is from 0 to 100 percent. Thus a value of 20 fades volume down to 80 percent.
TrickFadeTime
Fade IN/OUT time, in microseconds, applied during trickplay mode. Default is 20000 (20 milliseconds. Range is 2000-250000 microseconds (2 milliseconds to 250 milliseconds).
FadeTime
Fade IN/OUT time, in microseconds, applied during play mode. Default 2000 (20 milliseconds). Range is 2000-250000 microseconds (2 milliseconds to 250 milliseconds).

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
    }
}

Note:
  • You only need the settings in the io-media configuration file: io-media-*.cfg, if you want to override the default settings for the resources.
  • The damping_audio_writer filter has no effect on iPods because these devices control their own trick play behavior.

io-media configuration file

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"
        # }
    }
}

Configuring output writer filters

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"
    }
    ...
}

Updating the io-media configuration file

To update the io-media configuration file, after installing the latest release of io-media:

  1. Save a copy of your io-media configuration file for later comparison.
  2. Start io-media with the -C to print the default configuration file.
  3. Save a copy of this file for future reference.
  4. Refer to your old io-media configuration file, and edit the new configuration file to incorporate your project-specific settings.
  5. After saving the new configuration file, restart io-media with the -c option and the path to the new configuration file.

Configuring io-media to use DLLs

To have io-media-generic use dynamic filters at least one of the following must be true:

About permanently loaded filters and streamers

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.

Configuring the set of required filters and streamers

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.

Where to install io-media DLLs

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.


Note:
  • If you set this element to "", io-media will not search any directory for DLLs.
  • If you configure io-media to not search any directory for DLLs, you can still use the load attribute in the io-media configuration file to have io-media load specific DLLs.

Troubleshooting io-media DLL paths

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.


Note:
  • Depending on whether your io-media variant has streamers linked in statically or relies on DLLs, an incorrectly set $MM_INIT environment variable may produce a generic “Unable to open %s” error message instead of the MediaReader message in the example above.
  • A filter (other than stream_reader) missing from the DLL directory may produce messages such as “Couldn't create a linking filter for filter name stream”, or variations of the “Couldn't load the filter name stream filter” error message.
  • The MMF, which builds graphs for io-media, doesn't tell io-media whether it failed to build a graph because a filter couldn't be loaded or because it didn't like the file it is attempting to process. If you suspect a configuration problem, you should test it by trying to process media files that you know are supported and not corrupt or damaged.

Configuring io-media optimizations

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:

Using the io-media format element and its strict attribute

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:

url required
This element defines a pattern to compare to the URL of the file being processed. If no format element's url attribute matches the given URL, none of the parser, decoder, or strict attributes are considered to be specified for the file.
parser optional
This element specifies name of the parser filter to use to process the file.
decoder optional
This element specifies the name of the decoder filter to use to process the file.
strict optional, but if it is specified this attribute must be set to yes
This element instructs io-media to use only the specified parser or decoder, if a parser or decoder is specified.
resource optional: none, one or many may be specified
This element specifies a resource to apply to the filter; see Applying resources to afilter above.

To build a graph for a media file, io-media:

  1. Selects the first format element whose url attribute matches the URL for the file to be processed.
  2. Attempts to open the file and build an MMF graph using the information provided in the format element.
  3. If a parser is needed to build the graph (which is usually the case), and a parser is specified for the selected pattern, io-media tries that parser.
  4. If the parser rejects the file, or if no parser was specified for the URL pattern:
  5. If the parser accepts the file, processing continues.

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 = "*"
    }

URL — pattern test order

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.

Using the strict attribute

The strict attribute causes io-media to fail immediately and return an error if:

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
}

Note:
  • The strict attribute is optional; it does not have to be included in your io-media configuration file. However, if you include it, it must be set to yes.
  • To maintain consistent behavior across your system, use the same strict attribute for all your parsers.
  • You may prefer inconsistent behaviour for your projects. For instance, you might prefer files on a CD-ROM to use a strict policy to speed up failures, but files on a hard drive or a USB stick to be probed more thoroughly because these devices are faster and don't get scratched as easily as CDs. To configure your system for this sort of behavior, you can split the format descriptions information in two, for example, by adding an entry for /fs/cd?/*.mp[a123] before the entry for *.mp[a123].

Using the StickyReadError resource

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:

filter attribute values

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
}

Using the QuickMetadataScan resource

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:


Note: 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"
    }
}

MM_TMPFILE_STREAMER_SEEKABLE resource

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:

For example:

resource {
    name = "MM_TMPFILE_STREAMER_SEEKABLE"
    type = long
    value = 0
    optional = yes
}

Configuring the time io-media waits for metadata

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
}

Configuring the reader timeout

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
}

Configurable read timeouts for cdda_streamer

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 .

Configuring the 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.


Note:
  • For the cdda_trackcopier graph, you must specify optional = yes in order to permit copying of files, such as MPEG3 files, from block devices such as USB sticks, data CDs, and HDDs.

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
}

See also:

mme

The io-media section of the chapter Architecture, in Introduction to the MME