Skip to main content
Version: Android 1.2.0

UI Controls

Regardless of the Player implementation that you're using, you will likely want to show UI elements to control playback and the player behavior. Similar to what happens in the recorder module, we offer a default UI implementation called

With fragments#

If you are using PlayerFragment or PagerFragment, a PlayerControls view will be automatically added to the hierarchy and it is managed by the fragment itself, so there's nothing you should do.

When creating the fragment, you also have the option to pass a more generic layout resource that contains your overlays. If the view contains a PlayerControls instance anywhere in the hierarchy, the player will find it and set it up.

val options = {
overlay(R.layout.player_options_overlay) // customize overlays
overlay(null) // disable default controls

By default, the overlay() layout contains a single PlayerControls view. Your overlays can contain a richer hierarchy or you can leverage a layout file to customize controls with the XML attributes listed below. You can also pass null to disable the default controls.

With other Player implementations#

When using other Player implementations, the controls can be added to your view hierarchy as an overlay to the player. For example, in case of PlayerView, you can simply using a frame layout:

<!-- Part of your UI... -->
<!-- Add PlayerView here: -->
<!-- Then add controls: -->

At runtime, the controls should be bound to the player using PlayerControls.setPlayer(). Once this is done, the controls class will start listening to player events and update the interface accordingly.

val playerView: PlayerView = findViewById(
val playerControls: PlayerControls = findViewById(

Customizing controls#

The PlayerControls class offers many APIs to control the controls appearance, both through XML attributes and programmatically.

APIXML AttributeDescriptionDefault
showErrorsapp:playerControlsShowErrorsIf true, a toast is shown whenever we detect a playback error.true
showSpinnerapp:playerControlsShowSpinnerIf true, a loading spinner is shown when the video is being loaded or buffered.true
showNavigationapp:playerControlsShowNavigationIf true, the "next video" and "previous video" buttons are shown. See navigation.true
showPlayapp:playerControlsShowPlayIf true, the play / pause button will be shown.true
showMuteapp:playerControlsShowMuteIf true, the mute / unmute button will be shown.true
showProgressapp:playerControlsShowProgressIf true, the horizontal progress bar will be shown, including a text view with the current time.true
showDurationapp:playerControlsShowDurationIf true, a text view with the video duration will be shown.true
playDrawableapp:playerControlsPlayDrawableControls the drawable for the play state. Set to @empty to avoid showing a drawable at all.-
pauseDrawableapp:playerControlsPauseDrawableControls the drawable for the pause state. Set to @empty to avoid showing a drawable at all.-
muteDrawableapp:playerControlsMuteDrawableControls the drawable for the mute control. Set to @empty to avoid showing a drawable at all.-
unmuteDrawableapp:playerControlsUnmuteDrawableControls the drawable for the unmute control. Set to @empty to avoid showing a drawable at all.-

You can also have full control over the UI by passing your own layout resource to app:playerControlsLayout.

Touch controls#

The controls view is able to react to simple touch events and perform player actions accordingly. You can configure the touch behavior with the singleTapAction and doubleTapAction APIs, both in XML and programmatically.

val controls: PlayerControls = findViewById(
controls.singleTapAction = SingleTapAction.NONE // do nothing
controls.singleTapAction = SingleTapAction.TOGGLE_PLAYBACK // pause if playing, plays if paused
controls.singleTapAction = SingleTapAction.TOGGLE_VISIBILITY // shows or hides the controls
controls.doubleTapAction = DoubleTapAction.NONE // do nothing
controls.doubleTapAction = DoubleTapAction.SEEK // seek forward / backward depending on the touch position
controls.doubleTapAction = DoubleTapAction.NAVIGATE // navigate to next / previous video, see navigation docs
Last updated on