IMediaControlClientAsync

​

Interface IMediaControlClientAsync

interface IMediaControlClientAsync

Extends com.amazon.apmf.IStandard Provides methods to send requests to a media control endpoint. Each instance of this interface is associated with a media control endpoint. All control requests take an [IActionResponseListener] instance which is notified when the request completes or when an error occurs. Requests for information or media meta-data are received through the listener interface provided to those methods.

​

Methods

​

play()

void play(IActionResponseListener* listener, MediaSessionId? sessionId)

Requests a media control endpoint to start or resume playback. The media sesssion should update its [MediaSessionState] to reflect the new playback status. The media control endpoint may reset playback speed back to normal.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

pause()

void pause(IActionResponseListener* listener, MediaSessionId? sessionId)

Requests a media control endpoint to pause playback. The media sesssion should update its [MediaSessionState] to reflect the new playback status.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

togglePlayPause()

void togglePlayPause(IActionResponseListener* listener, MediaSessionId? sessionId)

Requests a media control endpoint to start, resume or pause playback depending on the current playback status. When the current playback status is [PlaybackStatus#PLAYING] or [PlaybackStatus#BUFFERING] the request should be interpreted as a pause request. When the current playback status is [PlaybackStatus#PAUSED] or [PlaybackStatus#NOT_PLAYING] the request should be interpreted as a play request. The media sesssion should update its [MediaSessionState] to reflect the new playback status.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

stop()

void stop(IActionResponseListener* listener, MediaSessionId? sessionId)

Requests a media control endpoint to stop playback. The media sesssion should update its [MediaSessionState] to reflect the new playback status.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

startOver()

void startOver(IActionResponseListener* listener, MediaSessionId? sessionId)

Requests a media control endpoint to seek to the start of the currently selected media and resume playback from the start. The media sesssion should update its [MediaSessionState] to reflect any changes due to this request, like the new playback position and/or an updated playback status.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

fastForward()

void fastForward(IActionResponseListener* listener, MediaSessionId? sessionId)

Requests a media control endpoint to fast forward playback. The target media session decides which accelerated playback speed should be used. Sending multiple consecutive fast-foward requests can increase the playback speed at steps decided by the media session (see [Capabilities#speeds] excluding the range from 0.0 to 1.0). A media session can decide to stop increasing playback speed after numerous fast-forward requests but it should accept and acknowledge the request normally. Audio playback may be muted or disabled when playback speed is not 1.0. The media sesssion should update its [MediaSessionState] to reflect changes in playback speed.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

rewind()

void rewind(IActionResponseListener* listener, MediaSessionId? sessionId)

Requests a media control endpoint to rewind playback. The target media session should start playing media backwards at a normal speed from the current playback position. If playback is already going backwards, the media session decides which accelerated reverse playback speed should be used. Sending multiple consecutive rewind requests can increase the playback speed at steps decided by the media session (see [Capabilities#speeds], excluding the range from -1.0 to 0.0). A media session can decide to stop increasing playback speed after numerous rewind requests but it should accept and acknowledge the request normally. Audio playback may be muted or disabled when playback speed is not 1.0. The media sesssion should update its [MediaSessionState] to reflect changes in playback speed.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

setPlaybackSpeed()

void setPlaybackSpeed(IActionResponseListener* listener, float speed, MediaSessionId? sessionId)

Requests a media control endpoint to change the playback speed.

• A value of 1.0 indicates normal playback speed.
• Values greater than 1.0 represent accelerated playback.
• Values between 0.0 and 1.0 (excluding 0.0) indicate slowed playback.
• Values less than 0.0 but greater than -1.0 represent slowed down backwards playback.
• Values less than -1.0 represent accelerated backwards playback.

The media sesssion should update its [MediaSessionState] to reflect the new playback speed.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

speed

float — Required the new playback speed.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

skipForward()

void skipForward(IActionResponseListener* listener, com.amazon.apmf.MonotonicDuration delta, MediaSessionId? sessionId)

Requests a media control endpoint to skip forward from the current playback position. The media sesssion should update its [MediaSessionState] to reflect the new playback position.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

delta

com.amazon.apmf.MonotonicDuration — Required The amount to skip forward relative to the currently playing position.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

skipBackward()

void skipBackward(IActionResponseListener* listener, com.amazon.apmf.MonotonicDuration delta, MediaSessionId? sessionId)

Requests a media control endpoint to skip backward from the current playback position. The media sesssion should update its [MediaSessionState] to reflect the new playback position.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

delta

com.amazon.apmf.MonotonicDuration — Required The amount to skip backward relative to the currently playing position.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

seek()

void seek(IActionResponseListener* listener, com.amazon.apmf.MonotonicDuration position, MediaSessionId? sessionId)

Requests a media control endpoint to seek to a given playback position. The media sesssion should update its [MediaSessionState] to reflect the new playback position.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

position

com.amazon.apmf.MonotonicDuration — Required The playback position to seek to, relative to the start of the media, where 0 represents the start of the media.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

setAudioVolume()

void setAudioVolume(IActionResponseListener* listener, float volume, MediaSessionId? sessionId)

Requests a change in the audio volume of the currently playing audio track.

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

volume

float — Required The target volume level, expressed in a normalized range from 0.0 (complete silence) to 1.0 (maximum volume).

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

setAudioTrack()

void setAudioTrack(IActionResponseListener* listener, Track* audioTrack, MediaSessionId? sessionId)

Requests to change the audio track. The media sesssion should update its [MediaSessionState] to reflect the new active audio track (see [MediaInfo#activeAudioTrack]).

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

audioTrack

Track* — Required One of the available audio tracks from [MediaInfo#availableAudioTracks].

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

enableTextTrack()

void enableTextTrack(IActionResponseListener* listener, Track* textTrack, MediaSessionId? sessionId)

Requests to select and enable a given text track. The media sesssion should update its [MediaSessionState] to reflect the new active text track (see [MediaInfo#activeTextTrack]).

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

textTrack

Track* — Required One of the available text tracks from [MediaInfo#availableTextTracks].

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

disableTextTrack()

void disableTextTrack(IActionResponseListener* listener, MediaSessionId? sessionId)

Requests to disable the active text track. The media sesssion should update its [MediaSessionState] to reflect no active text track (see [MediaInfo#activeTextTrack]).

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

next()

void next(IActionResponseListener* listener, MediaSessionId? sessionId)

Requests to select the next media item in the playlist or queue. The media sesssion should update the media info (see [MediaSessionState#mediaInfo]).

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

previous()

void previous(IActionResponseListener* listener, MediaSessionId? sessionId)

Requests to select the previous media item in the playlist or queue. The media sesssion should update the media info (see [MediaSessionState#mediaInfo]).

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

enableShuffle()

void enableShuffle(IActionResponseListener* listener, bool enable, MediaSessionId? sessionId)

Requests to enable or disable the playlist shuffle mode.

• When shuffle is true, tracks within the playlist are played in a random order.
• When shuffle is false, tracks are played in their original order.

The media sesssion should update the playlist state (see [MediaSessionState#playlistState]).

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

enable

bool — Required true to enable shuffle mode, false to disable it.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

setRepeatMode()

void setRepeatMode(IActionResponseListener* listener, RepeatMode mode, MediaSessionId? sessionId)

Requests to change the playlist repeat mode.

• RepeatMode.OFF indicates that repeat mode is disabled. When playback of the current track or playlist finishes, it will not automatically restart from the beginning.
• RepeatMode.REPEAT_TRACK specifies that the current track should be repeated indefinitely. Once the track ends, it will automatically start over from the beginning.
• RepeatMode.REPEAT_PLAYLIST indicates that the entire playlist (or album, queue, etc.) should be repeated indefinitely. When the last track in the playlist finishes, playback will return to the first track and continue.

The media sesssion should update the playlist state (see [MediaSessionState#playlistState]).

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

mode

RepeatMode — Required The mode to change to.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

setRating()

void setRating(IActionResponseListener* listener, com.amazon.kepler.media.types.MediaId* id, float rating, MediaSessionId? sessionId)

Requests to change the rating of a media item. The rating value is in the normalized range from 0.0 (worst rating) to 1.0 (best rating). The media id of the currently selected media can be obtained by inspecting [MediaSessionState#mediaInfo]. The media sesssion should update its [MediaSessionState] to reflect the current rating (see [MediaInfo#currentRating]).

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

id

com.amazon.kepler.media.types.MediaId* — Required The identifier for the media item to rate

rating

float — Required The rating value to assign, in a normalized range from 0.0 to 1.0.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

getMetadata()

void getMetadata(com.amazon.kepler.media.types.MediaId* id, IGetMetadataResponseListener* listener)

Requests to retrieve media metadata. The media id of the currently selected media can be obtained by inspecting [MediaSessionState#mediaInfo].

​

Parameters

id

com.amazon.kepler.media.types.MediaId* — Required The identifier of the media item for which metadata is requested.

listener

IGetMetadataResponseListener* — Required Invoked when the meta-data has been retrieved or when an error occurred handling the request.

---

​

sendCustomAction()

void sendCustomAction(IActionResponseListener* listener, Action* action, MediaSessionId? sessionId)

Sends a custom action request. The set of custom supported actions accepted by a media session is advertised in [Capabilities#actions] from [MediaSessionState#capabilities]. The media sesssion will update any associated custom control state in [MediaSessionState#controls].

​

Parameters

listener

IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.

action

Action* — Required One of the actions from [Capabilities#actions].

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IActionResponseListener#onError] is invoked. When null, the media control server decides how to route the request. For example, a server may decide to send the request to all its media sessions or it may target a media session it deems the default.

---

​

getSessionState()

void getSessionState(IGetMediaSessionStateResponseListener* listener, MediaSessionId? sessionId)

Requests the current media session state.

​

Parameters

listener

IGetMediaSessionStateResponseListener* — Required Invoked when the media session state has been retrieved or when an error occurred handling the request.

sessionId

MediaSessionId? — Optional When not null, the request is targeted to the specified media session. If the media session does not exists, [IGetMediaSessionStateResponseListener#onError] is invoked. When null, the media control server returns the states of all media sessions.

---

​

addListener()

void addListener(IMediaControlListener* listener)

Requests to register a listener that gets notified when a media control server updates the state of any of its media sessions.

​

Parameters

listener

IMediaControlListener* — Required is invoked when the subscription request succeeds or fails. Once a subscription request succeeds, the listener will be invoked when the media control server updates the state of any of its media sessions.

---

​

getEndpointPackageId()

com.amazon.kepler.pkg.PackageId? getEndpointPackageId()

Retrieves the target endpoint package id, if any.

​

Returns

com.amazon.kepler.pkg.PackageId? The return value is optional and might be absent. the package id associated with the endpoint or null if the endpoint is not associated with any package.

---