/pps/services/multimedia/mediaplayer/control

The Now Playing service listens for commands on this control object

Publishers: Media players
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/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

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) 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.
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.
track\ndat::`command_string`	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

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
Notify Now Playing that we want to be the active media player:
# echo "msg::acquire\nid::1" >&3; cat <&3
We can see the response from the server:
```
@control
res::acquire
id::1
error::ok
```

Button-registration examples

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
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.