mmr_track_parameters()

Updated: October 26, 2022

Set parameters for a track in the input

Synopsis:

#include <mm/renderer.h>
int mmr_track_parameters(mmr_context_t *ctxt,
                         unsigned index,
                         strm_dict_t *parms)

Arguments:

ctxt
A handle to the context for which a track in the input is being configured
index
For playlist inputs, use zero to set the default parameters, and nonzero to set the parameters for the track at the specified index in the playlist window. For autolist inputs, this must be 1, because default parameters aren't used.
parms

A handle to a dictionary containing the track parameters to set. Any previous parameters are overridden. Use NULL to reset the parameters of the specified track to the default values.

The strm_dict_t object becomes API property after this call, even if it fails. You should not use or destroy the dictionary after passing it to this function.

Library:

mmrndclient

Description:

Set parameters for a track in the input. This function can be used when the input type is playlist or autolist or when it's undefined because an input hasn't been attached. When the input type is track, the function fails.

For playlist inputs, you should call this function with index set to 0 before attaching any input. This way, any new default parameters (and not old ones) are applied to tracks when mm-renderer begins populating the playlist window, which might happen as soon as you attach the input. Afterwards, you can override the default parameters for individual tracks. To do so, you must monitor events to detect when a track is added to the playlist window and then immediately call this function with index set to a nonzero value representing the track's index in the window. You can still set track parameters for index 0 to affect the playback of any track that subsequently enters the window.

For autolist inputs, any input parameters that you set before attaching the input are taken as the initial track parameters (because the single track is the input). Afterwards, you can change the repeat parameter by calling this function with index set to 1; changes to other track parameters are ignored. Using an index of 0 has no effect with autolist inputs, because no new track ever enters the playlist window.

Some mm-renderer plugins don't return errors when you provide unacceptable parameter values. Instead, these plugins revert bad parameters to their previous values or to their default values (for parameters that you set for the first time). To see which values were accepted or changed, you can examine the parameters reported in the data dictionary field of the mmr_event_t structure returned for MMR_EVENT_TRKPAR events.

For HTTP-based inputs, you can set track parameters that map to libcurl options. These are the same libcurl options that you can define through context or input parameters. For any options defined in either of these other sets but also in the track parameters, the track parameter settings take precedence.

Returns:

Zero on success, -1 on failure (use mmr_error_info())