com.apple.android.music.playback.controller

Interface MediaPlayerController

public interface MediaPlayerController

An interface for controlling Apple Music media playback.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	MediaPlayerController.Listener An interface defining callbacks that a media player controller calls on registered listeners.

Field Summary

Fields

Modifier and Type	Field and Description
static long	DURATION_UNKNOWN The duration of the media item is unknown.
static int	INDEX_UNSET The index of the current media item is unknown.
static long	POSITION_UNKNOWN The position of the current media item in the queue is unknown.

Method Summary

Modifier and Type	Method and Description
void	addListener(MediaPlayerController.Listener listener) Registers the media player controller to listen to events, which is maintained with a strong reference.
void	addQueueItems(com.apple.android.music.playback.queue.PlaybackQueueItemProvider queueProvider, int insertionType) Adds the items from the specified playback queue item provider to the current playback queue insertion type, which controls where the items are loaded in the playback queue.
boolean	canAppendToPlaybackQueue() A Boolean value that indicates whether it's possible to append items to the playback queue.
boolean	canEditPlaybackQueue() A Boolean value that indicates whether it's possible to move or remove items from the playback queue.
boolean	canPrependToPlaybackQueue() A Boolean value that indicates whether it's possible to prepend items to the playback queue.
boolean	canSeek() A Boolean that indicates whether it's possible to seek to a position in the current playback item.
boolean	canSetRadioLikeState() Gets whether it is currently possible to set the radio like state for the currently playing item.
boolean	canSetRepeatMode() A Boolean value that indicates whether it's possible to change the active repeat mode.
boolean	canSetShuffleMode() A Boolean value that indicates whether it's possible to change the active shuffle mode.
boolean	canSkipToNextItem() A Boolean value that indicates whether it's possible to skip to the next item in the playback queue.
boolean	canSkipToPreviousItem() A Boolean value that indicates whether it's possible to skip to the previous item in the playback queue.
boolean	canSkipToQueueItem() A Boolean value that indicates whether it's possible to the skip to an item in the queue item list.
Set<com.apple.android.music.playback.model.MediaPlayerTrackInfo>	getAvailableTracks() Gets the set of currently available tracks in the player.
long	getBufferedPosition() Gets the player's buffered position, in milliseconds.
String	getCurrentContainerHashId()
int	getCurrentContainerIndex() Gets the index of the currently playing item in the current media container.
long	getCurrentContainerPersistentId() Gets the persistent id of the currently playing media container, or null if there are no items loaded, or the player is not playing from a container with a persistent id.
String	getCurrentContainerStoreId()
int	getCurrentContainerType() Gets the type of the currently playing media container.
PlayerQueueItem	getCurrentItem() Gets the current player queue item loaded into the player, which is null if no items have been loaded yet.
long	getCurrentPosition() Gets the current playback position, in milliseconds.
long	getDuration() Gets the duration, in milliseconds.
int	getPlaybackQueueIndex() Gets the index in the playback queue of the currently playing item.
int	getPlaybackQueueItemCount() Gets the total number of items in the playback queue.
float	getPlaybackRate() Gets the current playback rate, as a multiple of 1.0 to denote the normal playback rate, 0 if playback is paused or stopped, or a negative value means that playback is playing in reverse.
int	getPlaybackState() Gets the playback state.
List<PlayerQueueItem>	getQueueItems() Gets a bounded list of the queued items following the currently playing item in the playback queue, which will update as playback progresses, or new items are added to/removed from the queue.
int	getRepeatMode() Gets the repeat mode.
int	getShuffleMode() Gets the shuffle mode.
int	getVideoHeight() Gets the height, in pixels, of the currently playing video, or 0 if no video is currently playing.
float	getVideoPixelAspectRatio() Gets the pixel aspect ratio of the currently playing video, or 0 if no video is currently playing.
int	getVideoWidth() Gets the width, in pixels, of the currently playing video, or 0 if no video is currently playing.
boolean	isBuffering() A Boolean value that indicates if the player is buffering.
boolean	isLiveStream() A Boolean value that indicates if the current media is a live stream.
void	moveQueueItemWithId(long sourcePlaybackQueueId, long targetPlaybackQueueId, int moveTargetType) Moves the item with the specified playback queue ID to a position in the playback queue, either before or after the item with the specified target ID.
void	pause() Pauses playback.
void	play() Starts or resumes playback.
void	prepare(com.apple.android.music.playback.queue.PlaybackQueueItemProvider queueProvider) Stops playback, and prepares the queue to add items.
void	prepare(com.apple.android.music.playback.queue.PlaybackQueueItemProvider queueProvider, boolean playWhenReady) Stops playback, and prepares the queue to add items and starts playing if specified.
void	prepare(com.apple.android.music.playback.queue.PlaybackQueueItemProvider queueProvider, int playbackQueueInsertionType, boolean playWhenReady) Stops playback, and prepares the queue to add items with the given insertion type and starts playing if specified.
void	release() Releases this media player controller when it's no longer needed.
void	removeListener(MediaPlayerController.Listener listener) Unregisters the specified listener from receiving events.
void	removeQueueItemWithId(long playbackQueueId) Removes the item with the specified playback queue ID from the playback queue, if present.
void	restoreState(boolean block) Restores any previously saved player state.
void	seekToPosition(long position) Seeks to the specified position, in milliseconds.
void	setItemPositionProvider(com.apple.android.music.playback.player.PlayerMediaItemPositionProvider itemPositionProvider) Sets the item position provider, which allows for overriding of the default start position of each media item in the playback queue.
void	setRadioLikeState(int radioLikeState) Sets the radio like state for the currently playing item, if that operation is currently supported.
void	setRepeatMode(int repeatMode) Sets the current repeat mode.
void	setShuffleMode(int shuffleMode) Sets the current shuffle mode.
void	setTimedTextOutputHandler(com.apple.android.music.playback.player.TimedTextOutput timedTextOutput, Handler handler) Sets an output handler for timed text data (subtitles and closed captions).
void	setTimedTextTrackSelection(com.apple.android.music.playback.model.MediaPlayerTrackInfo trackSelection) Sets the track selection for timed text output.
void	setVideoOutputSurface(Surface videoOutputSurface) Sets the surface to which video output should be rendered to.
void	skipToNextItem() Skips to the next item in the playback queue if valid.
void	skipToPreviousItem() Skips to the previous item in the playback queue if valid.
void	skipToQueueItemWithId(long playbackQueueId) Skips to the item specified by the given playback queue ID if valid.
void	stop() Stops playback.

Field Detail

DURATION_UNKNOWN

static final long DURATION_UNKNOWN

The duration of the media item is unknown.

See Also:

Constant Field Values

INDEX_UNSET

static final int INDEX_UNSET

The index of the current media item is unknown.

See Also:

Constant Field Values

POSITION_UNKNOWN

static final long POSITION_UNKNOWN

The position of the current media item in the queue is unknown.

See Also:

Constant Field Values

Method Detail

addListener

void addListener(@NonNull
                 MediaPlayerController.Listener listener)

Registers the media player controller to listen to events, which is maintained with a strong reference.

Parameters:

listener - The listener to register.

addQueueItems

void addQueueItems(@NonNull
                   com.apple.android.music.playback.queue.PlaybackQueueItemProvider queueProvider,
                   int insertionType)

Adds the items from the specified playback queue item provider to the current playback queue insertion type, which controls where the items are loaded in the playback queue.

Parameters:

queueProvider - A PlaybackQueueItemProvider which will provide the new playback items.

insertionType - The type of insertion to perform.

canAppendToPlaybackQueue

boolean canAppendToPlaybackQueue()

A Boolean value that indicates whether it's possible to append items to the playback queue.

Returns:

True if it is possible to append items to the queue, false otherwise.

canEditPlaybackQueue

boolean canEditPlaybackQueue()

A Boolean value that indicates whether it's possible to move or remove items from the playback queue.

Returns:

True if it is possible to edit the queue, false otherwise.

canPrependToPlaybackQueue

boolean canPrependToPlaybackQueue()

A Boolean value that indicates whether it's possible to prepend items to the playback queue.

Returns:

True if it is possible to prepend items to the queue, false otherwise.

canSeek

boolean canSeek()

A Boolean that indicates whether it's possible to seek to a position in the current playback item.

Returns:

True if its possible to seek, false otherwise.

canSetRadioLikeState

boolean canSetRadioLikeState()

Gets whether it is currently possible to set the radio like state for the currently playing item.

Returns:

True if it is possible to set the radio like state, false otherwise.

canSetRepeatMode

boolean canSetRepeatMode()

A Boolean value that indicates whether it's possible to change the active repeat mode.

Returns:

True if it is possible to change the repeat mode, false otherwise.

canSetShuffleMode

boolean canSetShuffleMode()

A Boolean value that indicates whether it's possible to change the active shuffle mode.

Returns:

True if it is possible to change the shuffle mode, false otherwise.

canSkipToNextItem

boolean canSkipToNextItem()

A Boolean value that indicates whether it's possible to skip to the next item in the playback queue.

Returns:

True if its possible to skip to the next item, false otherwise.

canSkipToPreviousItem

boolean canSkipToPreviousItem()

A Boolean value that indicates whether it's possible to skip to the previous item in the playback queue.

Returns:

True if its possible to skip to the previous item, false otherwise.

canSkipToQueueItem

boolean canSkipToQueueItem()

A Boolean value that indicates whether it's possible to the skip to an item in the queue item list.

Returns:

True if its possible to skip to a queued item, false otherwise.

getAvailableTracks

@NonNull
Set<com.apple.android.music.playback.model.MediaPlayerTrackInfo> getAvailableTracks()

Gets the set of currently available tracks in the player. May be empty.

Returns:

The currently available tracks.

getBufferedPosition

long getBufferedPosition()

Gets the player's buffered position, in milliseconds.

Returns:

The current buffered position, or POSITION_UNKNOWN.

getCurrentContainerHashId

@Nullable
String getCurrentContainerHashId()

getCurrentContainerIndex

int getCurrentContainerIndex()

Gets the index of the currently playing item in the current media container.

Returns:

The current container index, or INDEX_UNSET.

getCurrentContainerPersistentId

long getCurrentContainerPersistentId()

Gets the persistent id of the currently playing media container, or null if there are no items loaded, or the player is not playing from a container with a persistent id.

Returns:

The current container persistent id, or 0.

getCurrentContainerStoreId

@Nullable
String getCurrentContainerStoreId()

getCurrentContainerType

int getCurrentContainerType()

Gets the type of the currently playing media container.

Returns:

The type of the container.

getCurrentItem

@Nullable
PlayerQueueItem getCurrentItem()

Gets the current player queue item loaded into the player, which is null if no items have been loaded yet.

Returns:

The current media item, or null.

getCurrentPosition

long getCurrentPosition()

Gets the current playback position, in milliseconds.

Returns:

The current playback position, or POSITION_UNKNOWN.

getDuration

long getDuration()

Gets the duration, in milliseconds.

Returns:

The current playback duration, or DURATION_UNKNOWN.

getPlaybackQueueIndex

int getPlaybackQueueIndex()

Gets the index in the playback queue of the currently playing item.

Returns:

The index of the current item.

getPlaybackQueueItemCount

int getPlaybackQueueItemCount()

Gets the total number of items in the playback queue.

Returns:

The total number of items in the playback queue.

getPlaybackRate

float getPlaybackRate()

Gets the current playback rate, as a multiple of 1.0 to denote the normal playback rate, 0 if playback is paused or stopped, or a negative value means that playback is playing in reverse.

Returns:

The current playback rate.

getPlaybackState

int getPlaybackState()

Gets the playback state.

Returns:

The current playback state.

getQueueItems

@NonNull
List<PlayerQueueItem> getQueueItems()

Gets a bounded list of the queued items following the currently playing item in the playback queue, which will update as playback progresses, or new items are added to/removed from the queue.

Returns:

The list of currently queued playback items.

getRepeatMode

int getRepeatMode()

Gets the repeat mode.

Returns:

The current repeat mode.

getShuffleMode

int getShuffleMode()

Gets the shuffle mode.

Returns:

The current shuffle mode.

getVideoHeight

int getVideoHeight()

Gets the height, in pixels, of the currently playing video, or 0 if no video is currently playing.

Returns:

The video height in pixels.

getVideoPixelAspectRatio

float getVideoPixelAspectRatio()

Gets the pixel aspect ratio of the currently playing video, or 0 if no video is currently playing.

Returns:

The video pixel aspect ratio.

getVideoWidth

int getVideoWidth()

Gets the width, in pixels, of the currently playing video, or 0 if no video is currently playing.

Returns:

The video width in pixels.

isBuffering

boolean isBuffering()

A Boolean value that indicates if the player is buffering.

Returns:

true if this player is currently buffering, false otherwise.

isLiveStream

boolean isLiveStream()

A Boolean value that indicates if the current media is a live stream.

Returns:

True if it is a live stream, false otherwise.

moveQueueItemWithId

void moveQueueItemWithId(long sourcePlaybackQueueId,
                         long targetPlaybackQueueId,
                         int moveTargetType)

Moves the item with the specified playback queue ID to a position in the playback queue, either before or after the item with the specified target ID.

Parameters:

sourcePlaybackQueueId - The source item id to move.

targetPlaybackQueueId - The target item id to move to.

moveTargetType - The type of target move, either before or after the target id.

pause

void pause()

Pauses playback.

play

void play()

Starts or resumes playback.

prepare

void prepare(@NonNull
             com.apple.android.music.playback.queue.PlaybackQueueItemProvider queueProvider)

Stops playback, and prepares the queue to add items. Equivalent to prepare(queueProvider, false).

Parameters:

queueProvider - A PlaybackQueueItemProvider instance responsible for providing items to the new playback queue.

prepare

void prepare(@NonNull
             com.apple.android.music.playback.queue.PlaybackQueueItemProvider queueProvider,
             boolean playWhenReady)

Stops playback, and prepares the queue to add items and starts playing if specified.

Parameters:

queueProvider - A PlaybackQueueItemProvider instance responsible for providing items to the new playback queue.

playWhenReady - Whether playback should start once the media has been loaded.

prepare

void prepare(@NonNull
             com.apple.android.music.playback.queue.PlaybackQueueItemProvider queueProvider,
             int playbackQueueInsertionType,
             boolean playWhenReady)

Stops playback, and prepares the queue to add items with the given insertion type and starts playing if specified.

Parameters:

queueProvider - A queue provider responsible for providing the new playback queue.

playbackQueueInsertionType - The playback queue insertion type to use for the specified provider.

playWhenReady - Whether playback should start once the media has been loaded.

release

void release()

Releases this media player controller when it's no longer needed.

removeListener

void removeListener(@NonNull
                    MediaPlayerController.Listener listener)

Unregisters the specified listener from receiving events.

Parameters:

listener - The listener to unregister.

removeQueueItemWithId

void removeQueueItemWithId(long playbackQueueId)

Removes the item with the specified playback queue ID from the playback queue, if present.

Parameters:

playbackQueueId - The playback queue id of the item to remove.

restoreState

void restoreState(boolean block)

Restores any previously saved player state.

Parameters:

block - Whether the operation should block the calling thread until it is complete

seekToPosition

void seekToPosition(long position)

Seeks to the specified position, in milliseconds.

Parameters:

position - The position to seek to.

setItemPositionProvider

void setItemPositionProvider(@Nullable
                             com.apple.android.music.playback.player.PlayerMediaItemPositionProvider itemPositionProvider)

Sets the item position provider, which allows for overriding of the default start position of each media item in the playback queue.

Parameters:

itemPositionProvider - A PlayerMediaItemPositionProvider instance, or null.

setRadioLikeState

void setRadioLikeState(int radioLikeState)

Sets the radio like state for the currently playing item, if that operation is currently supported.

Parameters:

radioLikeState - The like state to set for the current item.

setRepeatMode

void setRepeatMode(int repeatMode)

Sets the current repeat mode.

Parameters:

repeatMode - The new repeat mode.

setShuffleMode

void setShuffleMode(int shuffleMode)

Sets the current shuffle mode.

Parameters:

shuffleMode - The new shuffle mode.

setTimedTextOutputHandler

void setTimedTextOutputHandler(@Nullable
                               com.apple.android.music.playback.player.TimedTextOutput timedTextOutput,
                               @Nullable
                               Handler handler)

Sets an output handler for timed text data (subtitles and closed captions). If this data is present in the currently playing media item, the specified output handler will be called in order to render this data on the device.

Parameters:

timedTextOutput - An instance of TimedTextOutput, or null to remove timed text output rendering.

handler - A Handler to specify which thread to call the output, or null to use the current thread (if a Handler is associated to it) or the player background thread.

setTimedTextTrackSelection

void setTimedTextTrackSelection(@Nullable
                                com.apple.android.music.playback.model.MediaPlayerTrackInfo trackSelection)

Sets the track selection for timed text output.

Parameters:

trackSelection - The new track selection, or null to deselect the timed text track.

setVideoOutputSurface

void setVideoOutputSurface(@Nullable
                           Surface videoOutputSurface)

Sets the surface to which video output should be rendered to. The caller is responsible for tracking the lifecycle of the specified surface, and calling this method with a null argument when the specified surface is destroyed.

Parameters:

videoOutputSurface - A surface to render video output, or null.

skipToNextItem

void skipToNextItem()

Skips to the next item in the playback queue if valid.

skipToPreviousItem

void skipToPreviousItem()

Skips to the previous item in the playback queue if valid.

skipToQueueItemWithId

void skipToQueueItemWithId(long playbackQueueId)

Skips to the item specified by the given playback queue ID if valid.

Parameters:

playbackQueueId - The playback queue id of the item to skip to.

stop

void stop()

Stops playback.