The Now Playing service listens for commands on this control object

Media players
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/mediaplayer/control object are of the form:


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


Messages sent by the client

Command Parameters Data type Description
acquire n/a n/a

The acquire command asks the system to establish the calling player as the active media player in the system. If a currently active media player is at the same or lower priority as the calling player, the active player will have its active state revoked.

Media players must send the acquire command before they begin media playback so as to allow other players to stop playback. Players should do this only on an explicit action by the user (e.g., the user has pressed the play button or has just launched the player). If the active status is revoked by a higher-priority player (such as VAD or phone), the current player will be paused (not revoked) and will be resumed (if it wasn't paused) and given active status again when the higher-priority player releases. A player is released from being active if it sends the release message, gets preempted by another acquiring player, or disconnects from the PPS object.

button key:button_name JSON

The button_name parameter is of the form:

bn_button_button_length, where button is one of:
  • forward
  • hookswitch
  • minus
  • next
  • pause
  • play
  • playpause
  • plus
  • prev
  • rewind
  • stop
  • vdown
  • vup
and length is one of:
  • med (600ms)
  • short (<600ms)

A time value is required. Registering both short and med will request the button event as soon as the button goes down. Adding the threshold option (nothresh) to a short button registration will prevent the immediate action and provide short or med events based on how long the button is held.

The button_name parameter is designed to be flexible enough to allow any hard button to be combined with a time value and optionally with another button (for simultaneous presses). If the med length is also registered, the action is taken as soon as the button goes down.

nothresh:true|false (optional) JSON Setting for threshold support.
action:forward JSON Forward button notifications to the registered app.
metadata property:value JSON Updates the metadata for the currently played track. 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.

register name:name JSON The value for name is a descriptive string.
prio:priority JSON One of low or high.
audio JSON One of voice or general.
overlay (optional) JSON One of fancy (i.e., enable controls) or plain (i.e., disable controls).
audioman_handle:handle (optional) JSON Handle used for the audio channel. This handle is required for correct functionality of auto-resume when the media player is interrupted by a higher-priority player. The correct functionality that requires this handle is detecting a private-to-public switch. For example, if the headset is unplugged during the interrupting player, the backgrounded player won't resume automatically. The audioman_handle:handle parameter is required to determine this switch.
Note: Generally, only the VAD, phone, or VoIP applications should use voice or any priority but low. Media players should register with low priority and general audio. When the voice-activated dialing or phone applications need to send an acquire command, Now Playing will pause the current media player and resume it (if it wasn't already paused) after the dialing operation or phone call.
recorder (optional flag) JSON One of true or false. Setting the recorder flag to true indicates that this player is a capture device. This is currently intended to be used only for video recording that shouldn't be stopped by screening of incoming calls.
pid:apppid (optional) JSON You may use apppid instead of the connection PID when maximizing the active player with msg::app_maximize (see the entry for /pps/services/multimedia/mediacontroller/control).
release n/a n/a

Notifies Now Playing that the media player is relinquishing control. If this is a higher-priority player (such as VAD or phone), any previously active media player that was paused when this one sent an acquire command will be resumed (if it wasn't paused) and will be given active status.

state dat::state String Updates the player's play state to the given state string, one of:
  • stopped
  • paused
  • playing
  • trackchange—a special string for players that support multiple tracks. Players can send trackchange as a way to delimit tracks when playback moves from one track to another.
unbutton key:button_name JSON

Deregister a single button at the given length.

See the button command for the values for button_name.

Messages sent by Now Playing

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

Message Parameters Description
revoke n/a Indicates that the player's state as the active media player in the system is being revoked. The player should immediately stop playback and free up multimedia resources. This message will be sent to a player to deny its request to acquire active status if a higher-priority player is currently active. The message is also sent to the active player whenever another player preempts it.
One of:
  • forward—enter fast-forward mode
  • holdData—stop sending metadata updates
  • next—jump to the beginning of the next track
  • pause—pause playback of the current track
  • play—play the current track
  • prev—jump to the beginning of the current or previous track
  • rewind—enter rewind mode
  • sendData—start or resume sending metadata updates
  • stop—stop playback of the current track
Asks the media player to handle the given command string.
key\ndat::button_name See the button command for the values for button_name. Notifies the player of the given button press.

Command-line 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/mediaplayer/control

  2. Notify Now Playing that we want to be the active media player:

    # echo "msg::acquire\nid::1" >&3; cat <&3

  3. We can see the response from the server:

Button-registration examples

  1. Register for both short and medium button lengths, which will cause Now Playing to send one button event at button down:

    msg::button\nid::1\ndat:json:{"key":"bn_vup_short","action":"forward"} >> /pps/services/multimedia/mediaplayer/control

    msg::button\nid::1\ndat:json:{"key":"bn_vup_med","action":"forward"} >> /pps/services/multimedia/mediaplayer/control

  2. Now we'll set the nothresh option for the short button registration. Now Playing won't send the event at button down, but rather when the button goes up, as if you registered for just one length:

    msg::button\nid::1\ndat:json:{"key":"bn_vup_short","action":"forward", "nothresh":true} >> /pps/services/multimedia/mediaplayer/control

    msg::button\nid::1\ndat:json:{"key":"bn_vup_med","action":"forward"} >> /pps/services/multimedia/mediaplayer/control

    Note that if nothresh is set and the button is held for less than 600ms, the event will be sent at button up. If the button is held longer than 600ms, the event will be sent at 600ms.