to top
Android APIs
public final class

RemoteController

extends Object
java.lang.Object
   ↳ android.media.RemoteController

Class Overview

The RemoteController class is used to control media playback, display and update media metadata and playback status, published by applications using the RemoteControlClient class.

A RemoteController shall be registered through registerRemoteController(RemoteController) in order for the system to send media event updates to the RemoteController.OnClientUpdateListener listener set in the class constructor. Implement the methods of the interface to receive the information published by the active RemoteControlClient instances.
By default an RemoteController.OnClientUpdateListener implementation will not receive bitmaps for album art. Use setArtworkConfiguration(int, int) to receive images as well.

Registration requires the RemoteController.OnClientUpdateListener listener to be one of the enabled notification listeners (see NotificationListenerService).

Summary

Nested Classes
class RemoteController.MetadataEditor A class to read the metadata published by a RemoteControlClient, or send a RemoteControlClient new values for keys that can be edited. 
interface RemoteController.OnClientUpdateListener Interface definition for the callbacks to be invoked whenever media events, metadata and playback status are available. 
Constants
int POSITION_SYNCHRONIZATION_CHECK The playback position synchronization mode where the RemoteControlClient instances which expose their playback position to the framework, will be regularly polled to check whether any drift has been noticed between their estimated position and the one they report.
int POSITION_SYNCHRONIZATION_NONE Default playback position synchronization mode where the RemoteControlClient is not asked regularly for its playback position to see if it has drifted from the estimated position.
Public Constructors
RemoteController(Context context, RemoteController.OnClientUpdateListener updateListener)
Class constructor.
RemoteController(Context context, RemoteController.OnClientUpdateListener updateListener, Looper looper)
Class constructor.
Public Methods
boolean clearArtworkConfiguration()
Prevents this RemoteController from receiving artwork images.
RemoteController.MetadataEditor editMetadata()
Creates a RemoteController.MetadataEditor for updating metadata values of the editable keys of the current RemoteControlClient.
long getEstimatedMediaPosition()
Return the estimated playback position of the current media track or a negative value if not available.
boolean seekTo(long timeMs)
Sets the new playback position.
boolean sendMediaKeyEvent(KeyEvent keyEvent)
Send a simulated key event for a media button to be received by the current client.
boolean setArtworkConfiguration(int width, int height)
Set the maximum artwork image dimensions to be received in the metadata.
boolean setSynchronizationMode(int sync)
Set the playback position synchronization mode.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int POSITION_SYNCHRONIZATION_CHECK

Added in API level 19

The playback position synchronization mode where the RemoteControlClient instances which expose their playback position to the framework, will be regularly polled to check whether any drift has been noticed between their estimated position and the one they report. Note that this mode should only ever be used when needing to display very accurate playback position, as regularly polling a RemoteControlClient for its position may have an impact on battery life (if applicable) when this query will trigger network transactions in the case of remote playback.

Constant Value: 1 (0x00000001)

public static final int POSITION_SYNCHRONIZATION_NONE

Added in API level 19

Default playback position synchronization mode where the RemoteControlClient is not asked regularly for its playback position to see if it has drifted from the estimated position.

Constant Value: 0 (0x00000000)

Public Constructors

public RemoteController (Context context, RemoteController.OnClientUpdateListener updateListener)

Added in API level 19

Class constructor.

Parameters
context the Context, must be non-null.
updateListener the listener to be called whenever new client information is available, must be non-null.
Throws
IllegalArgumentException

public RemoteController (Context context, RemoteController.OnClientUpdateListener updateListener, Looper looper)

Added in API level 19

Class constructor.

Parameters
context the Context, must be non-null.
updateListener the listener to be called whenever new client information is available, must be non-null.
looper the Looper on which to run the event loop, or null to use the current thread's looper.
Throws
IllegalArgumentException

Public Methods

public boolean clearArtworkConfiguration ()

Added in API level 19

Prevents this RemoteController from receiving artwork images.

Returns
  • true if receiving artwork images was successfully disabled.

public RemoteController.MetadataEditor editMetadata ()

Added in API level 19

Creates a RemoteController.MetadataEditor for updating metadata values of the editable keys of the current RemoteControlClient. This method can only be called on a registered RemoteController.

Returns
  • a new MetadataEditor instance.

public long getEstimatedMediaPosition ()

Added in API level 19

Return the estimated playback position of the current media track or a negative value if not available.

The value returned is estimated by the current process and may not be perfect. The time returned by this method is calculated from the last state change time based on the current play position at that time and the last known playback speed. An application may call setSynchronizationMode(int) to apply a synchronization policy that will periodically re-sync the estimated position with the RemoteControlClient.

Returns
  • the current estimated playback position in milliseconds or a negative value if not available
See Also

public boolean seekTo (long timeMs)

Added in API level 19

Sets the new playback position. This method can only be called on a registered RemoteController.

Parameters
timeMs a 0 or positive value for the new playback position, expressed in ms.
Returns
  • true if the command to set the playback position was successfully sent.
Throws
IllegalArgumentException

public boolean sendMediaKeyEvent (KeyEvent keyEvent)

Added in API level 19

Send a simulated key event for a media button to be received by the current client. To simulate a key press, you must first send a KeyEvent built with a ACTION_DOWN action, then another event with the ACTION_UP action.

The key event will be sent to the registered receiver (see registerMediaButtonEventReceiver(PendingIntent)) whose associated RemoteControlClient's metadata and playback state is published (there may be none under some circumstances).

Parameters
keyEvent a KeyEvent instance whose key code is one of KEYCODE_MUTE, KEYCODE_HEADSETHOOK, KEYCODE_MEDIA_PLAY, KEYCODE_MEDIA_PAUSE, KEYCODE_MEDIA_PLAY_PAUSE, KEYCODE_MEDIA_STOP, KEYCODE_MEDIA_NEXT, KEYCODE_MEDIA_PREVIOUS, KEYCODE_MEDIA_REWIND, KEYCODE_MEDIA_RECORD, KEYCODE_MEDIA_FAST_FORWARD, KEYCODE_MEDIA_CLOSE, KEYCODE_MEDIA_EJECT, or KEYCODE_MEDIA_AUDIO_TRACK.
Returns
  • true if the event was successfully sent, false otherwise.
Throws
IllegalArgumentException

public boolean setArtworkConfiguration (int width, int height)

Added in API level 19

Set the maximum artwork image dimensions to be received in the metadata. No bitmaps will be received unless this has been specified.

Parameters
width the maximum width in pixels
height the maximum height in pixels
Returns
  • true if the artwork dimension was successfully set.
Throws
IllegalArgumentException

public boolean setSynchronizationMode (int sync)

Added in API level 19

Set the playback position synchronization mode. Must be called on a registered RemoteController.

Parameters
sync POSITION_SYNCHRONIZATION_NONE or POSITION_SYNCHRONIZATION_CHECK
Returns
  • true if the synchronization mode was successfully set.
Throws
IllegalArgumentException