Skip to main content
Version: 11.8.0

Picture-in-Picture on Android

The Picture-in-Picture (PiP) feature allows you to create a floating player. This is commonly used to let the video remain playing on screen even if:

  • The user scrolls to another section of the page (causing the original player to no longer be visible).
  • The user sends the application to the background.
  • The user opens a new page within the same application.

THEOplayer distinguishes two flavors of Picture-in-Picture:

  • With in-app Picture-in-Picture, the visibility of the PiP window is contained to the inside of the app. In other words, it goes to background and foreground together with the application.
  • With out-of-app Picture-in-Picture, the visibility of the PiP window is not contained to the inside of the app. It can remain visible while the user navigates to other views, pages or apps.

Picture-in-Picture is a presentation mode of the player. As such, you can listen for a presentationmodechange event, or read the player's presentation mode, to find out what the presentation mode is at a given moment or to detect a change.

On Android and Fire TV, there is no API to explicitly only allow in-app Picture-in-Picture: the PiP API always activates out-of-app Picture-in-Picture as well. Note that the minimum required Android version for out-of-app PiP is Oreo (API level 26).

Enabling Picture-in-Picture​

Instantiate the player with a PipConfiguration, passed in the THEOplayerConfig.

val playerConfig = THEOplayerConfig.Builder()
    .pipConfiguration(PipConfiguration.Builder().build())
    .build()

val theoPlayerView = THEOplayerView(context, playerConfig)

Once Picture-in-Picture is enabled, you can enter it through the PiP manager of your THEOplayerView.

theoPlayerView.piPManager?.enterPiP(PiPType.ACTIVITY)

THEOplayer supports three PiP types:

  • ACTIVITY: this mode generates a separate Android activity that functions as the PiP window.
  • DIALOG: in this mode, a dialog window is used as the PiP window. The video content is displayed within the dialog.
  • CUSTOM: unlike the predefined PiP types, CUSTOM allows you to design and implement your own PiP window. For details on implementing a custom PiP window, explore this Android documentation.

Observing Picture-in-Picture​

Listen for the PRESENTATIONMODECHANGE event, or read the presentation mode of the player, to find out what the presentation mode is at a given moment or to detect a change.

theoPlayerView.player.addEventListener(PlayerEventTypes.PRESENTATIONMODECHANGE) { event ->
    if (event.presentationMode == PresentationMode.PICTURE_IN_PICTURE) {
        // Currently in PiP
    }
}

// The listener above is triggered by one of:
theoPlayerView.piPManager?.enterPiP(PiPType.ACTIVITY)
theoPlayerView.piPManager?.exitPiP()

Returning from Picture-in-Picture​

ACTIVITY PiP type​

When your app uses the ACTIVITY PiP type and the user closes the PiP window, playback is automatically paused, provided that theoPlayerView.settings.setAllowBackgroundPlayback(false) is set to false (which is the default setting).

To resume playback, check whether your app's activity is in the foreground. If it is, call the play() method on the player instance.

theoPlayerView.player.addEventListener(PlayerEventTypes.PRESENTATIONMODECHANGE) { event ->
    if (event.presentationMode == PresentationMode.INLINE) {
        // Playback pauses after closing the PiP window
        if (lifecycle.currentState == Lifecycle.State.STARTED) {
            theoPlayerView.player.play()
        }
    }
}

DIALOG PiP type​

For the DIALOG PiP type, in order to correctly exit the PiP window, you should override onPictureInPictureModeChanged and call piPManager.exitPiP().

override fun onPictureInPictureModeChanged(
    isInPictureInPictureMode: Boolean,
    newConfig: Configuration
) {
    super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)

    if (!isInPictureInPictureMode) {
        theoPlayerView.piPManager?.exitPiP()
    }
}

This example ensures that playback pauses if the activity that holds THEOplayer is in the background and background playback is not allowed, providing a smoother transition for users returning from PiP mode.

CUSTOM PiP type​

For the CUSTOM PiP type, you are responsible for implementing your own PiP window and handling the necessary tasks for entering and exiting PiP mode. Managing playback after returning from PiP mode is in your hands as a developer. You can use the code snippet for the ACTIVITY type as a starting point, and adapt it to match your app's unique design and logic.

Known limitations​

  • Android TV: when the player is showing a native Google IMA advertisement while being in Picture-in-Picture mode, and the user triggers something which moves the PiP window (such as opening the keyboard), then the view showing the advertisement might be misaligned. This is a limitation of the Android framework.

Resources​