/pps/services/multimedia/mediacontroller/control

The Now Playing service listens for commands on this control object

Publishers
Media controllers
Subscribers
Now Playing
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 Persistent Publish/Subscribe Developer's Guide.

Message/response format

Commands sent to the /pps/services/multimedia/mediacontroller/control object are of the form:

msg::command_string\nid::ID_number\nparameter_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\nerror::error_description

Note: The id field can be omitted if there's no need to get a response back for the message.

Commands sent by the client

Command Parameters Data type Description
app_maximize n/a n/a Request that the active player be maximized.
b_down button_id:bid_value JSON Notifies Now Playing of a button make event, intended only for the hardware button driver. The bid_value parameter can be one of:
  • bid_forward
  • bid_hookswitch
  • bid_minus
  • bid_next
  • bid_pause
  • bid_play
  • bid_playpause
  • bid_plus
  • bid_prev
  • bid_rewind
  • bid_stop
  • bid_volume_down
  • bid_volume_up
b_up button_id:bid_value JSON Notifies Now Playing of a button break event, intended only for the hardware button driver. For the bid_value parameter, see the description above for b_down.
v_set vlevel String Set the volume level to the given vlevel (a number from 0 to 100).
v_up n/a n/a Increase the volume level by one step. Media volume typically has 16 steps, voice has 10. Increasing the volume by one step has the effect of a 6.25% increase.
v_down n/a n/a Decrease the volume level by one step.
v_mute mute Boolean Set the mute state to true or false.
v_update n/a n/a Indicates that a volume or mute update was done to the audioman service; the Now Playing service should reread it and display a toast notification.
m_play n/a n/a Direct the connected media player to play its content.
m_pause n/a String Direct the connected media player to pause its content.
m_playpause n/a String Toggle the pause state and direct the connected media player to play or pause its content accordingly.
m_stop n/a String Direct the connected media player to stop its content.
m_previous n/a String Direct the connected media player to jump to the start of the current track or to the previous track.
m_next n/a String Direct the connected media player to jump to the start of the next track.
m_fforward n/a String Direct the connected media player to enter fast-forward mode.
m_rewind n/a String Direct the connected media player to enter rewind mode.
md_subscribe n/a n/a Request that the caller subscribe to updates in metadata, track change, and state for the currently playing content.
md_unsubscribe n/a n/a Request that the caller no longer subscribe to changes for the currently playing content.

Messages sent by Now Playing

Besides returning the client's message and ID, the Now Playing service can also send these responses:

Response Parameters Data type Description
m_active_pid pid Number Provides the active music player's process ID. A value of 0 indicates no active player.
m_background_player_pid pid Number (for the number of pids); JSON (for each pid)

Provides the process IDs of the backgrounded (interrupted) players. A value of 0 indicates no backgrounded players. The format for this message is as follows:

msg::m_background_player_pid\nnumber:n:number_of_pids\ndat:json:pid1, pid2, ...

m_bg_pid pid Number Provides the backgrounded (interrupted) music player's process ID. A value of 0 indicates no backgrounded player.
m_preactive_pid pid Number Provides the process ID of the preactive phone player. This is intended to be used by the phone when screening an incoming call. A value of 0 indicates no preactive player.
m_state state String This message is sent only to subscribing controllers. Reflects the active player's state in the system. The state parameter can be one of:
  • stopped
  • paused
  • playing
  • trackchange

Note that trackchange only delimits tracks—it doesn't indicate a state change (from stopped, paused, or playing). The player is expected to send msg::state\ndat::trackchange at every change of track to generate the trackchange message to the controller.

md_update md_attribute:value JSON This message is sent only to subscribing controllers. Reflects the initial (or change in) metadata for the currently played track to each client controller listening for metadata changes. Strictly speaking, the metadata attributes are arbitrary because these PPS interfaces will proxy any metadata information from the active media player in the system to all subscribed controllers. Known metadata attributes include:
  • artist:name—string representing the name of the artist being played
  • album:name—string representing the name of the album being played
  • track:name—string representing the name of the track being played
  • position:track_pos—number representing the track's current playback position (in milliseconds)
  • duration:track_duration—number representing the track's current duration (in milliseconds)
  • albumArtwork:file_path—absolute path to an image file representing the album's artwork
  • nextEnabled:true|false—control from the player to enable (true) or disable (false) the next button on the volume toast (default is true)
  • prevEnabled:true|false—control from the player to enable (true) or disable (false) the prev button on the volume toast (default is true)

The nextEnabled and prevEnabled attributes are intended to be sent by media players that support and enable the fancy overlay in the volume toast.

Examples

  1. If we want to observe responses from the Now Playing service, we need to force the shell to keep the file descriptor open (because this is a server object):

    # exec 3<> /pps/services/multimedia/mediacontroller/control

  2. Now let's set the volume to 50%:

    # echo "msg::v_set\nid::1\ndat::50" >&3; cat <&3

  3. We can see the response from the server:
    @control
    res::v_set
    id::1
    error::ok