RemotePlaybackClient

open class RemotePlaybackClient
kotlin.Any
   ↳ androidx.mediarouter.media.RemotePlaybackClient

A helper class for playing media on remote routes using the remote playback protocol defined by MediaControlIntent.

The client maintains session state and offers a simplified interface for issuing remote playback media control intents to a single route.

Summary

Nested classes
abstract

A callback that will receive media status updates.

abstract

Base callback type for remote playback requests.

abstract

Callback for remote playback requests that operate on items.

abstract

Callback for remote playback requests that operate on sessions.

abstract

A callback that will receive messages from media sessions.

Public constructors
<init>(context: Context!, route: MediaRouter.RouteInfo!)

Creates a remote playback client for a route.

Public methods
open Unit
enqueue(contentUri: Uri!, mimeType: String!, metadata: Bundle!, positionMillis: Long, extras: Bundle!, callback: RemotePlaybackClient.ItemActionCallback!)

Sends a request to enqueue a media item.

open String!

Gets the current session id if there is one.

open Unit
seek(itemId: String!, positionMillis: Long, extras: Bundle!, callback: RemotePlaybackClient.ItemActionCallback!)

Sends a request to seek to a new position in a media item.

open Unit
play(contentUri: Uri!, mimeType: String!, metadata: Bundle!, positionMillis: Long, extras: Bundle!, callback: RemotePlaybackClient.ItemActionCallback!)

Sends a request to play a media item.

open Unit

Sends a request to resume (unpause) media playback.

open Boolean

Returns true if the route supports session management features.

open Unit

Sends a message.

open Unit

Sends a request to get the status of a media item.

open Unit
setSessionId(sessionId: String!)

Sets the current session id.

open Boolean

Returns true if the route supports queuing features.

open Unit

Sends a request to pause media playback.

open Unit
remove(itemId: String!, extras: Bundle!, callback: RemotePlaybackClient.ItemActionCallback!)

Sends a request to remove a media item from the queue.

open Unit

Sends a request to get the status of the media playback session.

open Unit

Sets a callback that should receive status updates when the state of media sessions or media items created by this instance of the remote playback client changes.

open Boolean

Returns true if the route supports messages.

open Boolean

Returns true if the client currently has a session.

open Unit

Sends a request to stop media playback and clear the media playback queue.

open Unit

Sets a callback that should receive messages when a message is sent from media sessions created by this instance of the remote playback client changes.

open Unit

Releases resources owned by the client.

open Unit

Sends a request to end the media playback session.

open Boolean

Returns true if the route supports remote playback.

open Unit

Sends a request to start a new media playback session.

Public constructors

<init>

RemotePlaybackClient(context: Context!, route: MediaRouter.RouteInfo!)

Creates a remote playback client for a route.

Parameters
route Context!: The media route.

Public methods

enqueue

open fun enqueue(contentUri: Uri!, mimeType: String!, metadata: Bundle!, positionMillis: Long, extras: Bundle!, callback: RemotePlaybackClient.ItemActionCallback!): Unit

Sends a request to enqueue a media item.

Enqueues a new item to play. If the queue was previously paused, then will remain paused.

The request is issued in the current session. If no session is available, then one is created implicitly.

Please refer to ACTION_ENQUEUE for more information about the semantics of this request.

Parameters
contentUri Uri!: The content Uri to enqueue.
mimeType Uri!: The mime type of the content, or null if unknown.
positionMillis Uri!: The initial content position for the item in milliseconds, or 0 to start at the beginning.
metadata Uri!: The media item metadata bundle, or null if none.
extras Uri!: A bundle of extra arguments to be added to the MediaControlIntent#ACTION_ENQUEUE intent, or null if none.
callback Uri!: A callback to invoke when the request has been processed, or null if none.
Exceptions
UnsupportedOperationException if the route does not support queuing.

getSessionId

open fun getSessionId(): String!

Gets the current session id if there is one.

Return
String!: The current session id, or null if none.

seek

open fun seek(itemId: String!, positionMillis: Long, extras: Bundle!, callback: RemotePlaybackClient.ItemActionCallback!): Unit

Sends a request to seek to a new position in a media item.

Seeks to a new position. If the queue was previously paused then it remains paused but the item's new position is still remembered.

The request is issued in the current session.

Please refer to ACTION_SEEK for more information about the semantics of this request.

Parameters
itemId String!: The item id.
positionMillis String!: The new content position for the item in milliseconds, or 0 to start at the beginning.
extras String!: A bundle of extra arguments to be added to the MediaControlIntent#ACTION_SEEK intent, or null if none.
callback String!: A callback to invoke when the request has been processed, or null if none.
Exceptions
IllegalStateException if there is no current session.

play

open fun play(contentUri: Uri!, mimeType: String!, metadata: Bundle!, positionMillis: Long, extras: Bundle!, callback: RemotePlaybackClient.ItemActionCallback!): Unit

Sends a request to play a media item.

Clears the queue and starts playing the new item immediately. If the queue was previously paused, then it is resumed as a side-effect of this request.

The request is issued in the current session. If no session is available, then one is created implicitly.

Please refer to ACTION_PLAY for more information about the semantics of this request.

Parameters
contentUri Uri!: The content Uri to play.
mimeType Uri!: The mime type of the content, or null if unknown.
positionMillis Uri!: The initial content position for the item in milliseconds, or 0 to start at the beginning.
metadata Uri!: The media item metadata bundle, or null if none.
extras Uri!: A bundle of extra arguments to be added to the MediaControlIntent#ACTION_PLAY intent, or null if none.
callback Uri!: A callback to invoke when the request has been processed, or null if none.
Exceptions
UnsupportedOperationException if the route does not support remote playback.

resume

open fun resume(extras: Bundle!, callback: RemotePlaybackClient.SessionActionCallback!): Unit

Sends a request to resume (unpause) media playback.

The request is issued in the current session. If playback is not paused then the request has no effect.

Please refer to ACTION_RESUME for more information about the semantics of this request.

Parameters
extras Bundle!: A bundle of extra arguments to be added to the MediaControlIntent#ACTION_RESUME intent, or null if none.
callback Bundle!: A callback to invoke when the request has been processed, or null if none.
Exceptions
IllegalStateException if there is no current session.

isSessionManagementSupported

open fun isSessionManagementSupported(): Boolean

Returns true if the route supports session management features.

If the route does not support session management, then the session will not be created until the first media item is played.

This method returns true if the route supports all of the basic remote playback actions and all of the following actions: start session, get session status, end session.

Return
Boolean: True if session management is supported. Implies isRemotePlaybackSupported is also true.

sendMessage

open fun sendMessage(message: Bundle!, callback: RemotePlaybackClient.SessionActionCallback!): Unit

Sends a message.

The request is issued in the current session.

Please refer to MediaControlIntent#ACTION_SEND_MESSAGE for more information about the semantics of this request.

Parameters
message Bundle!: A bundle message denoting MediaControlIntent#EXTRA_MESSAGE.
callback Bundle!: A callback to invoke when the request has been processed, or null if none.
Exceptions
IllegalStateException if there is no current session.
UnsupportedOperationException if the route does not support messages.

getStatus

open fun getStatus(itemId: String!, extras: Bundle!, callback: RemotePlaybackClient.ItemActionCallback!): Unit

Sends a request to get the status of a media item.

The request is issued in the current session.

Please refer to ACTION_GET_STATUS for more information about the semantics of this request.

Parameters
itemId String!: The item id.
extras String!: A bundle of extra arguments to be added to the MediaControlIntent#ACTION_GET_STATUS intent, or null if none.
callback String!: A callback to invoke when the request has been processed, or null if none.
Exceptions
IllegalStateException if there is no current session.

setSessionId

open fun setSessionId(sessionId: String!): Unit

Sets the current session id.

It is usually not necessary to set the session id explicitly since it is created as a side-effect of other requests such as play, enqueue, and startSession.

Parameters
sessionId String!: The new session id, or null if none.

isQueuingSupported

open fun isQueuingSupported(): Boolean

Returns true if the route supports queuing features.

If the route does not support queuing, then at most one media item can be played at a time and the enqueue method will not be available.

This method returns true if the route supports all of the basic remote playback actions and all of the following actions: enqueue, remove.

Return
Boolean: True if queuing is supported. Implies isRemotePlaybackSupported is also true.

pause

open fun pause(extras: Bundle!, callback: RemotePlaybackClient.SessionActionCallback!): Unit

Sends a request to pause media playback.

The request is issued in the current session. If playback is already paused then the request has no effect.

Please refer to ACTION_PAUSE for more information about the semantics of this request.

Parameters
extras Bundle!: A bundle of extra arguments to be added to the MediaControlIntent#ACTION_PAUSE intent, or null if none.
callback Bundle!: A callback to invoke when the request has been processed, or null if none.
Exceptions
IllegalStateException if there is no current session.

remove

open fun remove(itemId: String!, extras: Bundle!, callback: RemotePlaybackClient.ItemActionCallback!): Unit

Sends a request to remove a media item from the queue.

The request is issued in the current session.

Please refer to ACTION_REMOVE for more information about the semantics of this request.

Parameters
itemId String!: The item id.
extras String!: A bundle of extra arguments to be added to the MediaControlIntent#ACTION_REMOVE intent, or null if none.
callback String!: A callback to invoke when the request has been processed, or null if none.
Exceptions
IllegalStateException if there is no current session.
UnsupportedOperationException if the route does not support queuing.

getSessionStatus

open fun getSessionStatus(extras: Bundle!, callback: RemotePlaybackClient.SessionActionCallback!): Unit

Sends a request to get the status of the media playback session.

The request is issued in the current session.

Please refer to ACTION_GET_SESSION_STATUS for more information about the semantics of this request.

Parameters
extras Bundle!: A bundle of extra arguments to be added to the MediaControlIntent#ACTION_GET_SESSION_STATUS intent, or null if none.
callback Bundle!: A callback to invoke when the request has been processed, or null if none.
Exceptions
IllegalStateException if there is no current session.
UnsupportedOperationException if the route does not support session management.

setStatusCallback

open fun setStatusCallback(callback: RemotePlaybackClient.StatusCallback!): Unit

Sets a callback that should receive status updates when the state of media sessions or media items created by this instance of the remote playback client changes.

The callback should be set before the session is created or any play commands are issued.

Parameters
callback RemotePlaybackClient.StatusCallback!: The callback to set. May be null to remove the previous callback.

isMessagingSupported

open fun isMessagingSupported(): Boolean

Returns true if the route supports messages.

This method returns true if the route supports all of the basic remote playback actions and all of the following actions: start session, send message, end session.

Return
Boolean: True if session management is supported. Implies isRemotePlaybackSupported is also true.

hasSession

open fun hasSession(): Boolean

Returns true if the client currently has a session.

Equivalent to checking whether getSessionId returns a non-null result.

Return
Boolean: True if there is a current session.

stop

open fun stop(extras: Bundle!, callback: RemotePlaybackClient.SessionActionCallback!): Unit

Sends a request to stop media playback and clear the media playback queue.

The request is issued in the current session. If the queue is already empty then the request has no effect.

Please refer to ACTION_STOP for more information about the semantics of this request.

Parameters
extras Bundle!: A bundle of extra arguments to be added to the MediaControlIntent#ACTION_STOP intent, or null if none.
callback Bundle!: A callback to invoke when the request has been processed, or null if none.
Exceptions
IllegalStateException if there is no current session.

setOnMessageReceivedListener

open fun setOnMessageReceivedListener(listener: RemotePlaybackClient.OnMessageReceivedListener!): Unit

Sets a callback that should receive messages when a message is sent from media sessions created by this instance of the remote playback client changes.

The callback should be set before the session is created.

Parameters
listener RemotePlaybackClient.OnMessageReceivedListener!: The callback to set. May be null to remove the previous callback.

release

open fun release(): Unit

Releases resources owned by the client.

endSession

open fun endSession(extras: Bundle!, callback: RemotePlaybackClient.SessionActionCallback!): Unit

Sends a request to end the media playback session.

The request is issued in the current session. If this request is successful, the session id property will be set to null after the callback is invoked.

Please refer to ACTION_END_SESSION for more information about the semantics of this request.

Parameters
extras Bundle!: A bundle of extra arguments to be added to the MediaControlIntent#ACTION_END_SESSION intent, or null if none.
callback Bundle!: A callback to invoke when the request has been processed, or null if none.
Exceptions
IllegalStateException if there is no current session.
UnsupportedOperationException if the route does not support session management.

isRemotePlaybackSupported

open fun isRemotePlaybackSupported(): Boolean

Returns true if the route supports remote playback.

If the route does not support remote playback, then none of the functionality offered by the client will be available.

This method returns true if the route supports all of the following actions: play, seek, get status, pause, resume, stop.

Return
Boolean: True if remote playback is supported.

startSession

open fun startSession(extras: Bundle!, callback: RemotePlaybackClient.SessionActionCallback!): Unit

Sends a request to start a new media playback session.

The application must wait for the callback to indicate that this request is complete before issuing other requests that affect the session. If this request is successful then the previous session will be invalidated.

Please refer to ACTION_START_SESSION for more information about the semantics of this request.

Parameters
extras Bundle!: A bundle of extra arguments to be added to the MediaControlIntent#ACTION_START_SESSION intent, or null if none.
callback Bundle!: A callback to invoke when the request has been processed, or null if none.
Exceptions
UnsupportedOperationException if the route does not support session management.