/pps/services/multimedia/mediaplayer/phone

The Now Playing service listens for commands on this control object

Publishers: Phone app
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/mediaplayer/phone 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\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) Note: 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`.