Defining parameters

Updated: April 19, 2023

Parameters allow you to set properties that influence how media files are accessed and delivered to the output. The parameters applicable to the context, its input, or one of its outputs depend on the media content being played or recorded.

Your application must use the Dictionary Object API to create, populate, modify, and delete the dictionary objects that store parameters. For instance, it must call strm_dict_new() to create a dictionary and strm_dict_set() to define the key-value pairs that hold the parameters.

When calling any of the mmr_*_parameters() functions, the application must pass in a handle to a dictionary object populated with the appropriate key-value pairs. All of these functions always replace the previous settings with the latest ones, so your application must remember which parameters have been defined. These functions consume the dictionary object handle, so if an application wants to keep a dictionary, it must call strm_dict_clone() to duplicate the handle before calling one of them.

By default, no parameters are defined, and mm-renderer behaves as though the client had passed empty dictionaries to the parameter-setting functions. Some parameters control settings that exist regardless of whether you define parameter values for them. For example, the audio volume is always set, and is set to a default level if you don't pass in a dictionary with volume defined. But this default volume level is not the default value of the parameter—it's the level used by mm-renderer when the parameter is left undefined.

Parameters that affect how the input is accessed

The mm-renderer service supports many parameters that affect how input media files are accessed. The exact parameters that apply to playback or recording depend on the type of media file being read (and hence, the URL and input type given to mmr_input_attach()).

These parameters can be defined at different scopes, using separate API functions:

Any parameter supported for input files when the attached input is of type track also works as a playlist track parameter when the input type is playlist. For this second input type, the settings defined with mmr_input_parameters() determine how the playlist file named in the URL is accessed, but don't affect playback of individual playlist tracks; the settings defined with mmr_track_parameters() do. When the input type is autolist, the parameters for the single track are initially identical to the input file parameters, but mmr_track_parameters() can be used to change them. After the input is attached, new settings made through mmr_input_parameters() are ignored.

The table that follows describes all parameters that control how mm-renderer accesses the input. For each parameter, the applicable scopes and input types are listed. For those that apply to more than one scope, any playlist track parameter settings override any input file parameter settings, while any settings at this middle scope override any context parameter settings.

Name(s) Description Scopes
audio_index Specifies the audio track (or stream) within the input file to read. Setting this parameter lets you switch tracks during playback. The parameter's value must be a non-negative decimal number. You can learn the audio track indexes by reading the properties in the data for METADATA events.
  • input file for track type and URL naming an audio or video file
  • playlist tracks
maxlatency Sets the maximum latency, in milliseconds, allowed for audio content during playback. context
minlatency Sets the minimum latency, in milliseconds, allowed for audio content during playback. context
  • OPT_VERBOSE
  • OPT_CONNECTTIMEOUT_MS
  • OPT_LOW_SPEED_LIMIT
  • OPT_LOW_SPEED_TIME
  • OPT_USERAGENT
  • OPT_USERNAME
  • OPT_PASSWORD
  • OPT_PROXYUSERNAME
  • OPT_PROXYPASSWORD
  • OPT_COOKIE
  • OPT_COOKIEFILE
  • OPT_COOKIEJAR
  • OPT_COOKIESESSION
  • OPT_CAINFO
  • OPT_CAPATH
  • OPT_SSL_VERIFYPEER
  • OPT_SSL_VERIFYHOST
  • OPT_PROXY
  • OPT_NOPROXY
  • OPT_HTTPPROXYTUNNEL
  • OPT_PROXYPORT
  • OPT_PROXYTYPE
  • OPT_PROXYAUTH
  • OPT_HTTPAUTH
  • OPT_HTTPHEADER
  • OPT_DNSCACHETIMEOUT
These parameters map to libcurl options, and let client applications configure cookies, SSL, and authentication for secure playback of HTTP streams. For information about these options, see the libcurl page at https://curl.haxx.se/libcurl/.
Note: You can define any other parameter that has a name starting with OPT_COOKIELIST or OPT_HTTPHEADER followed by any suffix starting with a non-alphanumeric character. For each of these additional parameters, mm-renderer will set the corresponding libcurl option.
  • context
  • input file with track type and URL beginning with http: or https:
  • playlist tracks with input URL beginning with http: or https:
  • OPT_SO_RCVBUF
  • OPT_SO_SNDBUF
These parameters map to socket options, and let client applications configure the size of the input and output buffers. For information about socket options, see the getsockopt() entry in the C Library Reference. context
repeat

Determines whether the entire playlist or the current track is replayed. When the end of a track is reached during playback, mm-renderer decides which track to play next (if any) based on this parameter's value.

The acceptable values are:
  • none—stop playback if the end of the playlist has been reached, otherwise jump to the next track in the playlist (this is the default behavior)
  • track—repeat playback of the current track, meaning the play position jumps back to the beginning of the track that just finished playing
  • all—repeat playback of the entire playlist, meaning the play position jumps to the next track if the end of the playlist has not been reached, otherwise, the play position jumps to the beginning of the first track

With either of the last two settings, mm-renderer repeats playback indefinitely. In this case, an application must explicitly set the parameter to none to make playback stop when the current track ends.

  • input file for playlist and autolist types
  • playlist tracks
subpicture_disable Controls visibility of subtitles. When this parameter is left undefined, the default behavior is to display subtitles. You can set this parameter to 1 or yes to temporarily hide subtitles, then set it to 0 or no to display them again.
  • input file for track type and URL naming a video file
  • playlist tracks
subpicture_index

Specifies the subtitle track (or stream) within the input file to read. Setting this parameter lets you switch tracks during playback. The parameter's value must be a non-negative decimal number. You can learn the subtitle track indexes by reading the properties in the data for METADATA events.

This parameter isn't supported for subtitles read from a separate file, because the associated subtitle formats allow for only a single subtitle stream in the file.

  • input file for track type and URL naming a video file
  • playlist tracks
subpicture_url

Names a file separate from the input file from which to read subtitles. The parameter's value must be a URL in a format suitable for track inputs. For the list of supported subtitle formats, see the product release notes.

If you don't define this parameter before attaching the input, mm-renderer attempts to read subtitles embedded in the input file. If do define this parameter, you can't remove it later but you can change it to select a new file of the same type from which to read subtitles.

  • input file for track type and URL naming a video file
  • playlist tracks
transition_speed Applies a new playback speed at the beginning of each playlist track. The mm-renderer service checks this parameter right after it jumps to the next track, and adjusts the speed (if necessary) based on the parameter's value. The two supported values are: 0 (to pause playback), and 1000 (to resume it at normal speed). input file for playlist and autolist types
updateinterval

Requests a particular status update frequency, in milliseconds, from mm-renderer. How accurately the update delivery reflects this parameter setting depends on the plugin handling the media flow. This parameter is supported by both the MMF audio/video player and MMF audio recorder routing plugins.

The default interval is 1000 ms but your code should update this parameter based on the application's state, such as fullscreen versus minimized versus no screen. You can override this parameter in the configuration file.

context

Parameters that affect how the output is delivered

To configure each output, you must first attach it using mmr_output_attach() and then pass the ID returned by this function into the subsequent mmr_output_parameters() call, to specify which output you're configuring.

The parameters for controlling output delivery depend on the output type defined when attaching the output. For video and subpicture outputs, you must use the Screen API instead of setting output parameters through mm-renderer. This other API is documented in the Screen Graphics Subsystem Developer's Guide. The table below shows the supported parameters for audio and file outputs.

Name Description Output type
audio_bitrate

Sets the audio encoding rate, in bits per second. For instance, typical values for MP3 files are between 128 and 192 kbps, so the parameter's value would be between 131,072 and 196,608. Lower values produce smaller files of lower sound quality.

If you want the audio to be uncompressed, don't set this parameter.

file
audio_fourcc Specifies the audio encoding. The parameter value is a string naming the audio format (e.g., AAC, MP3), which is different than the file container type. When you play the file, you should get this value in the md_audio_track0 property of METADATA events. file
audio_type

Classifies the audio track by its content (voice, ring tones, video chat, etc.), which determines how the system performs audio ducking (i.e., the lowering of one stream in volume when a higher priority stream is being concurrently played).

Unlike in previous mm-renderer releases, there are no predefined audio types. The names and behaviors of the audio types are configurable. For an explanation of how to configure them, see the Audio Management chapter in the Audio Developer's Guide.

audio
mimetype Helps mm-renderer select the format of the output file. This feature isn't fully supported at the moment, so we recommend not to use this parameter. file
volume Sets the volume for this audio stream. The parameter value must be between 0 and 100. If you don't set this parameter, mm-renderer uses a default volume of 50. audio