/pps/services/mm-control/control

Control object for mm-control mediaplayer

Publishers
mm-renderer; any app
Subscribers
mm-control; any app
Note: This type of object is known as a server object, a special PPS object designed for point-to-point communication between a server and one or more clients. For details, see "Server objects" in the QNX Persistent Publish/Subscribe Developer's Guide.

Overview

The mm-control manager conveniently ties together media outputs, zones, tracksessions, and renderer control. It provides a simple interface for HMIs that have limited access to native calls.

The following types of commands are supported:

Message/response format

Commands sent to the /pps/services/mm-control/control object are of the form:

msg::command_string\nid::ID_number\ndat:json:{JSON_data}

Responses always reflect the command_string and ID_number that were sent in the message, along with any errors:

res::command_string\nid::ID_number\ndat:json:{JSON_data}\nerr::errno_number\nerrstr::error_description

Output commands

msg:: id:: dat:json:
output_create Number {"name":"output_name", "url":"output url", "type":"output type"}
output_destroy Number {"name":"output_name"}

Examples of output commands

echo 'msg::output_create\nid::1\ndat:json:{"name":"output0", "url":"snd:pcmPreferredp","type":"audio"}' >> /pps/services/mm-control/control

echo 'msg::output_destroy\nid::2\ndat:json:{"name":"output0"}' >> /pps/services/mm-control/control

Output responses

res:: id:: dat:json: err:: errstr::
output_create Number n/a EBUSY "Output name already exists"
output_destroy Number n/a ENOENT "Couldn't find output name"

Zone commands

Zones are containers for collecting outputs into sets that can be atomically added to or removed from players.

Note: Outputs must already exist before you can use the zone_attach_outputs or zone_detach_outputs commands.
msg:: id:: dat:json:
zone_attach_outputs Number {"name":"zone_name", "outputs":["output name",…]}
zone_create Number {"name":"zone_name"}
zone_destroy Number {"name":"zone_name"}
zone_detach_outputs Number {"name":"zone_name", "outputs":["output name",…]}

Examples of zone commands

echo 'msg::zone_create\nid::3\ndat:json:{"name":"zone0"}' >> /pps/services/mm-control/control

echo 'msg::zone_destroy\nid::4\ndat:json:{"name":"zone0"}' >> /pps/services/mm-control/control

echo 'msg::zone_attach_outputs\nid::5\ndat:json:{"name":"zone0", "outputs":["output0"]}' >> /pps/services/mm-control/control

echo 'msg::zone_detach_outputs\nid::6\ndat:json:{"name":"zone0", "outputs":["output0"]}' >> /pps/services/mm-control/control

Zone responses

res:: id:: dat:json: err:: errstr::
zone_attach_outputs Number n/a errno_number as appropriate
zone_create Number n/a errno_number as appropriate
zone_destroy Number n/a errno_number as appropriate
zone_detach_outputs Number n/a errno_number as appropriate

Tracksession commands

Use tracksessions to provide a collection of tracks to a player.

Note: Note the following:
  1. The trksession_randomize_range command lets you randomize any portion of a tracksession. A "start" of 0 and an "end" of -1 will randomize the entire session. You may want to randomize a subrange to allow the user to enable random playback partway through a session. Randomizing the range after the current track permits randomized playback of the remaining unheard songs without mixing in some of the tracks already heard.
  2. The trksession_get_range command lets you view a session in either sequential or playback order, which will differ if randomized playback is requested.
msg:: id:: dat:json:
trksession_create Number {"name":"trksession_name", "media_source":"attribute name in /pps/services/mm-detect/status"}
trksession_delete Number {"name":"trksession_name"}
trksession_get_range Number {"name":"trksession_name","start":start,"end":end, "type":"random|sequential"}
trksession_import Number {"name":"trksession_name","url":"sql"}
trksession_randomize_range Number {"name": "trksession_name","start": start,"end": end}

Examples of trksession commands

echo 'msg::trksession_create\nid::7\ndat:json:{"name":"mtrksession", "media_source":"dbmme"}' >> /pps/services/mm-control/control

echo 'msg::trksession_import\nid::8\ndat:json:{"name":"mtrksession", "url":"SELECT mediastore_metadata.mountpath || folders.basepath || library.filename AS url, fid AS userdata from mediastore_metadata, folders, file WHERE file.folderid == folders.folderid ORDER BY fid;"}' >> /pps/services/mm-control/control

echo 'msg::trksession_randomize_range\nid::10\ndat:json:{"name": "mtrksession","start":0,"end":5}' >> /pps/services/mm-control/control

echo 'msg::trksession_get_range\nid::11\ndat:json:{"name": "mtrksession","start":0,"end":5,"type":"sequential"}' >> /pps/services/mm-control/control

echo 'msg::trksession_delete\nid::9\ndat:json:{"name":"mtrksession"}' >> /pps/services/mm-control/control

Tracksession responses

res:: id:: dat:json: err:: errstr::
trksession_create Number n/a errno_number as appropriate
trksession_get_range Number {"num":num, "entries":[{"fid":fid,"url":"url"},...]} errno_number as appropriate
trksession_import Number {"trksession_size": int session_size} errno_number as appropriate
trksession_randomize_range Number n/a errno_number as appropriate

Player commands

Players are used to play tracks from a tracksession. Players are created and referenced by name so that the HMI can connect to players created or started before the HMI is initialized.

For every player created, mm-control creates a PPS status object called /pps/services/mm-control/playername/status to publish the status associated with that player.

Note: Note the following:
  1. For player_set_position, the exact format of the position depends on the input media type.
  2. For player_set_read_mode, if the requested read mode for an active tracksession differs from the current read mode, the tracksession will be either shuffled or unshuffled and the TABLE trksessionview field inside the media source’s database will be updated accordingly.
  3. For player_set_trksession, the track specified by idx in the tracksession named by trksession is attached as the new input.
  4. For player_set_current, the track specified by index is attached as the new input.
  5. For player_play, if you don't set position, the default playback position is the beginning of the track.
msg:: id:: dat:json:
player_attach_zone Number {"player":"player_name","zone":"zone name"}
player_create Number {"name":"player_name"}
player_current_track Number {"player":"player_name"}
player_detach_zone Number {"player":"player_name","zone":"zone name"}
player_next_track Number {"player":"player_name"}
player_play Number {"player":"player_name","position":position_ms}
player_previous_track Number {"player":"player_name"}
player_set_current Number {"player":"player_name,"index":index}
player_set_params Number {"player":"player_name,"type":"context|input|track","params":[{"key0":"value0"}, {"key1":"value1"},…]}
player_set_position Number {"player":"player_name,"position":"position_ms"}
player_set_read_mode Number {"player":"player_name,"mode":"random|sequential"}
player_set_repeat_mode Number {"player":"player_name, "mode":"all|one|none"}
player_set_speed Number {"player":"player_name","speed":speed}
player_stop Number {"player":"player_name"}
player_set_trksession Number {"player":"player_name","trksession":"trksession_name","idx":current_idx}

Examples of player commands

echo 'msg::player_create\nid::9\ndat:json:{"name":"mptest"}' >> /pps/services/mm-control/control

echo 'msg::player_attach_zone\nid::12\ndat:json:{"player":"mptest", "zone":"zone0"}' >> /pps/services/mm-control/control

echo 'msg::player_detach_zone\nid::12\ndat:json:{"player":"mptest", "zone":"zone0"}' >> /pps/services/mm-control/control

echo 'msg::player_set_trksession\nid::13\ndat:json:{"player":"mptest", "trksession":"mtrksession","idx":0}' >> /pps/services/mm-control/control

echo 'msg::player_set_speed\nid::14\ndat:json:{"player":"mptest", "speed":0}' >> /pps/services/mm-control/control

echo 'msg::player_set_position\nid::14\ndat:json:{"player":"mptest", "position":"100000"}' >> /pps/services/mm-control/control

echo 'msg::player_set_read_mode\nid::17\ndat:json:{"player":"mptest", "mode":"random"}' >> /pps/services/mm-control/control

echo 'msg::player_set_repeat_mode\nid::17\ndat:json:{"player":"mptest", "repeatmode":"all"}' >> /pps/services/mm-control/control

echo 'msg::player_set_current\nid::14\ndat:json:{"player":"mptest", "index":2}' >> /pps/services/mm-control/control

echo 'msg::player_play\nid::13\ndat:json:{"player":"mptest"}' >> /pps/services/mm-control/control

echo 'msg::player_stop\nid::17\ndat:json:{"player":"mptest"}' >> /pps/services/mm-control/control

echo 'msg::player_previous_track\nid::17\ndat:json:{"player":"mptest"}' >> /pps/services/mm-control/control

echo 'msg::player_next_track\nid::16\ndat:json:{"player":"mptest"}' >> /pps/services/mm-control/control

echo 'msg::player_current_track\nid::15\ndat:json:{"player":"mptest"}' >> /pps/services/mm-control/control

echo 'msg::player_set_params\nid::14\ndat:json:{"player":"mptest", "type":"track","params":[{"language":"english"}]}' >> /pps/services/mm-control/control

Player responses

res:: id:: dat:json: err:: errstr::
player_attach_zone Number n/a errno_number as appropriate
player_create Number {"status_path":"path to the status object for this player"} errno_number as appropriate
player_current_track Number {"trk_id":idx,"fid":fid,"url":"url"} errno_number as appropriate
player_detach_zone Number n/a errno_number as appropriate
player_next_track Number {"trk_id":idx,"fid":fid,"url":"url"} errno_number as appropriate
player_play Number {"trk_id":fid} errno_number as appropriate
player_previous_track Number {"trk_id":idx,"fid":fid,"url":"url"} errno_number as appropriate
player_set_current Number n/a errno_number as appropriate
player_set_params Number n/a errno_number as appropriate
player_set_position Number n/a errno_number as appropriate
player_set_read_mode Number n/a errno_number as appropriate
player_set_repeat_mode Number n/a errno_number as appropriate
player_set_speed Number n/a errno_number as appropriate
player_set_trksession Number n/a errno_number as appropriate
player_stop Number n/a errno_number as appropriate

Player states

State: Description:
IDLE No active trksession is set for the player.
INVALID An error has occurred; the player thread is dead. The player cannot accept any new commands from the HMI.
PLAYING The active trksession is playing.
PAUSED The active trksession is playing; the speed is set to zero.
STOPPED All other scenarios.

Attributes published to /pps/services/mm-control/playername/status

When this command is called: These attributes are published to the status object:
player_create
  • state::IDLE
  • speed::1000
player_play
  • trkid:n:index_of_trk
  • fid:n: (fid of the track inside the database; stored inside the trksession as userdata)
  • state::PLAYING
  • position:n: (current position of the track)
  • duration:n: (for iPods only, duration of the track)
player_set_current
  • trkid:n:index_of_trk
  • fid:n: (fid of the track inside the database; stored inside the trksession as userdata)
player_set_trksession
  • trksession::trksession_name
  • media_source::attribute name in /pps/mm/status
  • trkid:n:index_of_trk
  • fid:n: (fid of the track inside the database; stored inside the trksession as userdata)
  • state::STOPPED
player_stop If called when player is PLAYING or PAUSED:
  • state::STOPPED