Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases

Console

as

Get Started
Design and Develop
Publish
Reference
Support
Native
Skip to main content

​
Interface IMediaControlHandlerAsync

interface IMediaControlHandlerAsync
Extends com.amazon.apmf.IStandard Interface for receiving media control requests. A media control server application implements this interface and registers it through IMediaControlServerAsync::setHandlerForComponent. See IMediaControlHandlerAsync2 for additional context on the pause command initiator.

​
Methods

​
handlePlay()

void handlePlay(IActionResponseListener* listener, MediaSessionId? sessionId)
Handles a request to resume or start playback. If the application is already playing and the playback speed is not normal (not 1.0) this may return playback to normal speed. Receiving multiple play requests while already in playing state is not an error and should signal success on the given [IActionResponseListener] instance. The media server should update the corresponding [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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handlePause()

void handlePause(IActionResponseListener* listener, MediaSessionId? sessionId)
Handles a request to pause playback. Receiving multiple pause requests while already in pause state is not an error and should signal success on the given [IActionResponseListener] instance. The media server should update the corresponding [MediaSessionState] to reflect the new playback status. Pause could be invoked by an user (e.g., through remote or Alexa) or by the system (e.g., when the display is off). Refer to IMediaControlHandlerAsync2::handlePauseWithContext below if you need more context about why Pause is invoked.

​
Parameters

listener
IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.
sessionId
MediaSessionId? — Optional An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleTogglePlayPause()

void handleTogglePlayPause(IActionResponseListener* listener, MediaSessionId? sessionId)
Handles a request 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 server should update the corresponding [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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleStop()

void handleStop(IActionResponseListener* listener, MediaSessionId? sessionId)
Handles a request to stop playback. Receiving multiple stop requests while already in not_playing state is not an error and should signal success on the given [IActionResponseListener] instance. The media server should update the corresponding [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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleStartOver()

void handleStartOver(IActionResponseListener* listener, MediaSessionId? sessionId)
Handles a request to start playback over at the start of the media. The media server should update the corresponding [MediaSessionState] to reflect the new playback status and position.

​
Parameters

listener
IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.
sessionId
MediaSessionId? — Optional An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleFastForward()

void handleFastForward(IActionResponseListener* listener, MediaSessionId? sessionId)
Handles a request to fast forward playback. This server decides which accelerated playback speed should be used. Receiving multiple consecutive fast-foward requests should increase the playback speed at steps decided by this server. This server can decide to stop increasing playback speed after numerous fast-forward requests but it should accept and acknowledge the request normally. Audio playback can be muted or disabled when playback speed is not 1.0. The media server should update the corresponding [MediaSessionState] to reflect the new playback speed.

​
Parameters

listener
IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.
sessionId
MediaSessionId? — Optional An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleRewind()

void handleRewind(IActionResponseListener* listener, MediaSessionId? sessionId)
Handles a request to rewind playback. Media should start playing backwards at a normal speed from the current playback position, upon receiving the first rewind request. If playback is already going backwards, this server decides which accelerated reverse playback speed should be used. Receiving multiple consecutive rewind requests can increase the playback speed at steps decided by this server. This server can decide to stop increasing playback speed after numerous rewind requests but it should accept and acknowledge the request normally. Audio playback can be muted or disabled when playback speed is not 1.0. The media server should update the corresponding [MediaSessionState] to reflect the new playback speed.

​
Parameters

listener
IActionResponseListener* — Required Invoked when the request is accepted or an error occurred handling the request.
sessionId
MediaSessionId? — Optional An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleSetPlaybackSpeed()

void handleSetPlaybackSpeed(IActionResponseListener* listener, float speed, MediaSessionId? sessionId)
Handles a request 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.
If the requested speed is outside the supported range, use [SpeedOutOfRangeError] in [IActionResponseListener#onError]. The media server should update the corresponding [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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleSkipForward()

void handleSkipForward(IActionResponseListener* listener, com.amazon.apmf.MonotonicDuration delta, MediaSessionId? sessionId)
Handles a request to skip forward. The media server should update the corresponding [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 current playback position.
sessionId
MediaSessionId? — Optional An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleSkipBackward()

void handleSkipBackward(IActionResponseListener* listener, com.amazon.apmf.MonotonicDuration delta, MediaSessionId? sessionId)
Handles a request to skip backward. The media server should update the corresponding [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 current playback position.
sessionId
MediaSessionId? — Optional An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleSeek()

void handleSeek(IActionResponseListener* listener, com.amazon.apmf.MonotonicDuration position, MediaSessionId? sessionId)
Handles a request to seek to seek to a given playback position. The media server should update the corresponding [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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleSetAudioVolume()

void handleSetAudioVolume(IActionResponseListener* listener, float volume, MediaSessionId? sessionId)
Handles a request change the audio volume of the currently playing audio track. The volume value is normalized, from 0.0 (silent) to 1.0 (full volume). The application is expected to notify the given IActionResponseListener either within the invoking thread or asynchronously later on a different thread.

​
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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleSetAudioTrack()

void handleSetAudioTrack(IActionResponseListener* listener, Track* audioTrack, MediaSessionId? sessionId)
Handles a request 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 The audio track to change to.
sessionId
MediaSessionId? — Optional An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleEnableTextTrack()

void handleEnableTextTrack(IActionResponseListener* listener, Track* textTrack, MediaSessionId? sessionId)
Handles a request 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 The text track to select or disables text track if the value is null.
sessionId
MediaSessionId? — Optional An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleDisableTextTrack()

void handleDisableTextTrack(IActionResponseListener* listener, MediaSessionId? sessionId)
Handles a request 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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleNext()

void handleNext(IActionResponseListener* listener, MediaSessionId? sessionId)
Handles a request 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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handlePrevious()

void handlePrevious(IActionResponseListener* listener, MediaSessionId? sessionId)
Handles a request 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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleEnableShuffle()

void handleEnableShuffle(IActionResponseListener* listener, bool enable, MediaSessionId? sessionId)
Handles a request 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 enables shuffle mode, false disables it.
sessionId
MediaSessionId? — Optional An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleSetRepeatMode()

void handleSetRepeatMode(IActionResponseListener* listener, RepeatMode mode, MediaSessionId? sessionId)
Handles a request 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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleSetRating()

void handleSetRating(IActionResponseListener* listener, com.amazon.kepler.media.types.MediaId* id, float rating, MediaSessionId? sessionId)
Handles a request 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 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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleGetMetadataInfo()

void handleGetMetadataInfo(IGetMetadataResponseListener* listener, com.amazon.kepler.media.types.MediaId* id)
Handles requests to retrieve media metadata. The application is expected to notify the given IGetMetadataResponseListener either within the invoking thread or asynchronously later on a different thread.

​
Parameters

listener
IGetMetadataResponseListener* — Required Invoked when the meta-data has been retrieved or when an error occurred handling the request.
id
com.amazon.kepler.media.types.MediaId* — Required The identifier of the media item for which metadata is requested.

​
handleCustomAction()

void handleCustomAction(IActionResponseListener* listener, Action* action, MediaSessionId? sessionId)
Handles a custom action request. The requested action should be one of the items 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 An optional id that identifies which session this request is intended for. If not specified, the request is not intended for any particular session and its up to this server to interpret how it should be handled.

​
handleGetSessionState()

void handleGetSessionState(IGetMediaSessionStateResponseListener* listener, MediaSessionId? sessionId)
Handles a request to get one or all media session states. This method is also invoked as part of endpoint discovery so should invoke the listener promptly to ensure an available endpoint is discoverable.

​
Parameters

listener
IGetMediaSessionStateResponseListener* — Required Invoked when the media session state has been retrieved or when an error occurred handling the request.
sessionId
MediaSessionId? — Optional An optional id that identifies which session this request is intended for. If not specified, the request is to retrieve all known media session states.
Last modified on October 29, 2026