Parameters for mm-renderer

Parameters allow you to set properties that influence how media files are accessed and rendered during playback. Properties such as the audio volume or video display size can be controlled by defining parameters for a context or its inputs or outputs.

Parameters are represented as dictionary objects, which are collections of key-value pairs where both the key and the value are strings. The parameters that apply to the context and its input and outputs depend on the media content being played or recorded.

There are four kinds of parameters that you can set:
Context parameters These parameters are used for media-independent settings. Context parameters include updateinterval and parameters that map to libcurl options. There is one dictionary per context. Call mmr_context_parameters() to set context parameters.
Input parameters These parameters are used for items that affect the input file. Input parameters include volume, repeat, audio_type, audioman_handle, and parameters that map to libcurl options. There is one dictionary per context. Call mmr_input_parameters() to set input parameters.
Output parameters These parameters are used for items that affect the output file. Output parameters include volume, audio_type, and audioman_handle. There is one dictionary per attached output. Call mmr_output_parameters() to set output parameters.
Track parameters These parameters are used for media files or streams. Track parameters include audio_type, audioman_handle, audio_index, subpicture_index, and parameters that map to libcurl options. There is one dictionary for each media file or stream being played. For playlists, the distinction between the input file (the playlist) and the media files listed by the playlist is significant. This distinction doesn't exist when you play a media file without a playlist. Call mmr_track_parameters() to set track parameters.

The input and track parameters can be adjusted by mm-renderer by removing invalid or unsupported entries, changing a parameter value to the nearest supported value, and so on. Context and output parameters can't be modified by mm-renderer.

To create a dictionary object if one doesn't exist, call strm_dict_new() . Use strm_dict_set() to set the key-value pairs for the parameters you want to define.

To set parameters for a context, call mmr_context_parameters() , passing the handle to the dictionary object that holds the context parameters. Similarly, call mmr_input_parameters() to set the input parameters, and call mmr_output_parameters() to set the output parameters. In each case, you must pass a handle to a separate dictionary object that's populated with the appropriate parameter key-value pairs.

You can set input parameters when you don't have any input; these parameters apply to the next input you attach. The main difference is that the input parameters are reset to an empty dictionary when you detach the input, but the dictionary containing the context parameters is not affected.

To modify parameters, call the appropriate function again, passing a handle to a dictionary object populated with the new parameters. The mmr_*_parameters() functions consume the dictionary object handle. If you want to keep the object, call the function strm_dict_clone() to duplicate the handle before calling one of the parameter functions.

Configuring track and playlist inputs

The behavior of track parameters depends on the input type.

For track inputs, the input parameters and track parameters are the same dictionary. You change the parameters by calling mmr_input_parameters() , not mmr_track_parameters() .

For playlist inputs, input parameters affect the reading of the playlist file and track parameters affect the reading and playback of tracks. Set the input and track parameters by calling mmr_input_parameters() and mmr_track_parameters() . Track parameters can be set only for tracks in the playlist window. Set the default parameters for tracks that enter the window by calling mmr_track_parameters() with an index of 0.

For autolist inputs, there's a simulated playlist file, but the input URL specifies a track. The initial track parameters for the track are the same as the input parameters (for more consistency with track inputs). After the input is attached, the behavior is more consistent with the playlist input type, where mmr_track_parameters() controls the track parameters and mmr_input_parameters() controls the input parameters. Because there’s no real playlist file, all input parameters, except for repeat, are ignored.

Parameter precedence

Some parameter names are recognized as context parameters and also as track or input parameters. An input or track parameter takes precedence over any context parameter with the same name. This precedence allows an app to set default settings in context parameters and use input or track parameters to override the default values for specific items. updateinterval and the HTTP OPT_... parameters belong in this category and are often used in this manner.

Last modified: 2015-03-31

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

comments powered by Disqus