The Now Playing service listens for commands on this control object

Phone app
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/phone object are of the form:


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\nparameter_data\n error::error_description

Commands sent by the phone app

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

The acquire command asks the system to establish the phone app as the active media player in the system. Any currently active player will be paused (not revoked) and then resumed (if it wasn't paused). When the phone releases, the paused player will be given active status again.

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.

phonereg name:name String The value for name is a descriptive string.
Note: The priority is set at phone (which is higher than low or high for players). Generally, only the phone or VoIP applications should use this interface.
preacquire n/a n/a

Asks the system to establish the phone as the active media player. If a recorder (a type of player flagged at registration time) is active, the phone becomes preacquired alongside the recorder. The recorder continues with no state changes. This state is intended to be used by the phone for screening incoming calls. If the call is rejected, the phone should release and any recorder should continue. If the call is accepted, the phone should send the acquire message, which will cause the recorder to be backgrounded. Any current player (not flagged as a recorder) will be paused (not revoked) and will be resumed (if it wasn't paused) and given active status again when the phone releases. A subsequent acquire before release won't affect the state.

release n/a n/a

Notifies Now Playing that the phone app is relinquishing control. Any previously active media player that was paused when the phone sent an acquire command will be resumed (if it wasn't paused) and will be given active status.

unbutton key:button_name JSON

Deregister a single button at the given length.

See the button command for the values for button_name.