Google is committed to advancing racial equity for Black communities. See how.

MediaControlView

open class MediaControlView : MediaViewGroup
androidx.media2.widget.MediaControlView

A View that contains the controls for MediaController or SessionPlayer. It provides a wide range of buttons that serve the following functions: play/pause, rewind/fast-forward, skip to next/previous, select subtitle track, enter/exit full screen mode, select audio track, and adjust playback speed.

For simple use cases not requiring communication with MediaSession, apps need to create a SessionPlayer (e.g. androidx.media2.player.MediaPlayer) and set it to this view by calling setPlayer. For more advanced use cases that require MediaSession (e.g. handling media key events, integrating with other MediaSession apps as Assistant), apps need to create a MediaController attached to the MediaSession and set it to this view by calling setMediaController.

The easiest way to use a MediaControlView is by creating a VideoView, which internally creates a MediaControlView instance and handles all the commands from buttons inside MediaControlView. It is also possible to create a MediaControlView programmatically and add it to a custom video view. For more information, refer to VideoView.

By default, each button in the MediaControlView is visible only when its corresponding SessionCommand is included in the active SessionCommandGroup. For more details, refer to MediaSession#setAllowedCommands.

UI transitions

The UI of an app can be in one of three modes:
  • In full mode all the views, such as progress bar, title, transport controls, and other icons are visible.
  • In progress-bar only mode the progress bar is the only visible element. The title, transport controls, and other icons are hidden.
  • In None mode all the views are hidden.
When the UI mode changes, MediaControlView animates the transition. The animation does not start immediately, there is a default delay interval of 2000ms before the animation begins. You can change this interval by calling VideoView#setMediaControlView(MediaControlView, long).

User actions can change the scheduled transition during the delay interval according to the following logic:

  1. In Full mode
    • If a touch/trackball event is received during the interval, the UI changes to None mode.
    • If no touch/trackball event is received during the interval, the UI changes to progress-bar only mode.
  2. In Progress-bar only mode
    • If a touch/trackball event is received, the UI changes to Full mode.
    • If no touch/trackball event is received, the UI changes to None mode.
  3. In None mode, if a touch/trackball event is received, the UI changes to Full mode.
All touch/trackballs events are ignored while the system is animating the change between modes.

Customization

The following customizations are supported:

Displaying metadata

MediaControlView supports displaying metadata by calling MediaItem#setMetadata(MediaMetadata). Metadata display is different for two different media types: video (with or without sound) and audio(sound only, no video)

The following table shows the metadata displayed on VideoView and the default values assigned if the keys are not set:

Key Default
MediaMetadata#METADATA_KEY_TITLE androidx.media2.widget.R.string#mcv2_music_title_unknown_text
MediaMetadata#METADATA_KEY_ARTIST androidx.media2.widget.R.string#mcv2_music_artist_unknown_text
MediaMetadata#METADATA_KEY_ALBUM_ART androidx.media2.widget.R.drawable#media2_widget_ic_default_album_image

For video media, MediaMetadata#METADATA_KEY_TITLE metadata is supported. If the value is not set, the following default value will be shown: androidx.media2.widget.R.string#mcv2_non_music_title_unknown_text

Summary

Nested classes
abstract

Interface definition of a callback to be invoked to inform the fullscreen mode is changed.
Public constructors
<init>(@NonNull context: Context)
<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?)
<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?, defStyleAttr: Int)
Public methods
open CharSequence!

open Boolean

open Boolean

open Unit

Requests focus for the play/pause button.
open Unit
setMediaController(@NonNull controller: MediaController)

Sets MediaController to control playback with this view.
open Unit

Sets a listener to be called when the fullscreen mode should be changed.
open Unit
setPlayer(@NonNull player: SessionPlayer)

Sets SessionPlayer to control playback with this view.
Protected methods
open Unit

open Unit

open Unit
onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int)
open Unit
onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int)

Public constructors

<init>

MediaControlView(@NonNull context: Context)

<init>

MediaControlView(
    @NonNull context: Context, 
    @Nullable attrs: AttributeSet?)

<init>

MediaControlView(
    @NonNull context: Context, 
    @Nullable attrs: AttributeSet?, 
    defStyleAttr: Int)

Public methods

getAccessibilityClassName

open fun getAccessibilityClassName(): CharSequence!

onTouchEvent

open fun onTouchEvent(ev: MotionEvent!): Boolean

onTrackballEvent

open fun onTrackballEvent(ev: MotionEvent!): Boolean

requestPlayButtonFocus

open fun requestPlayButtonFocus(): Unit

Requests focus for the play/pause button.

setMediaController

open fun setMediaController(@NonNull controller: MediaController): Unit

Sets MediaController to control playback with this view. Setting a MediaController will unset any MediaController or SessionPlayer that was previously set.

It will throw IllegalStateException if this MediaControlView belongs to a VideoView by androidx.media2.widget.R.attr#enableControlView or by VideoView#setMediaControlView. Use VideoView#setMediaController instead.

Note that MediaControlView allows controlling playback through its UI components, but calling the corresponding methods (e.g. MediaController#play(), MediaController#pause()) will work as well.

Parameters
controller MediaController: the controller

See Also

setOnFullScreenListener

open fun setOnFullScreenListener(@Nullable listener: MediaControlView.OnFullScreenListener?): Unit

Sets a listener to be called when the fullscreen mode should be changed. A non-null listener needs to be set in order to display the fullscreen button.

Parameters
listener MediaControlView.OnFullScreenListener?: The listener to be called. A value of null removes any existing listener and hides the fullscreen button.

setPlayer

open fun setPlayer(@NonNull player: SessionPlayer): Unit

Sets SessionPlayer to control playback with this view. Setting a SessionPlayer will unset any MediaController or SessionPlayer that was previously set.

It will throw IllegalStateException if this MediaControlView belongs to a VideoView by androidx.media2.widget.R.attr#enableControlView or by VideoView#setMediaControlView. Use VideoView#setPlayer instead.

Note that MediaControlView allows controlling playback through its UI components, but calling the corresponding methods (e.g. SessionPlayer#play(), SessionPlayer#pause()) will work as well.

Parameters
player SessionPlayer: the player

Protected methods

onAttachedToWindow

protected open fun onAttachedToWindow(): Unit

onDetachedFromWindow

protected open fun onDetachedFromWindow(): Unit

onLayout

protected open fun onLayout(
    changed: Boolean, 
    left: Int, 
    top: Int, 
    right: Int, 
    bottom: Int
): Unit

onMeasure

protected open fun onMeasure(
    widthMeasureSpec: Int, 
    heightMeasureSpec: Int
): Unit