Picture-in-Picture with the Native SDKs

Product(s)
Video Cloud
Brightcove Player
Role(s)
Device SDK Developer
Topic(s)
Playback
SDK
Android
iOS
In this topic, you will learn how to implement Picture-in-Picture mode in your apps using the Brightcove Native Player SDKs.

Overview

Picture-in-picture (PIP) mode allows users to multitask on their devices. With this feature, you can create apps where a small video playback window is pinned to a corner of the screen while the user performs other tasks.

Picture-in-picture mode
Picture-in-picture mode

Features

The picture-in-picture functionality provided by the Brightcove Native SDKs, supports the following features:

  • Where a user enters picture-in-picture mode by clicking on the PIP icon in the control bar, a developer can enter PIP mode programmatically.
  • The user can drag the PIP window around the corners of the screen to place it in the most convenient location.
  • The user can pause and play the video in the PIP window, or remove it completely. The user can also maximize the video back to the in-app experience.
  • PIP mode works on top of the app, the device background and other applications.

Supported versions

Picture-in-picture mode is supported with the following versions:

Device OS version

Android: Android OS Oreo 8.0+ (API level 26+)

Native SDK version

Android: Brightcove Native SDK for Android version 6.1.0+

Android implementation

The following topics will help you get started with the picture-in-picture feature:

For more details, see Android's Picture-in-picture support guide.

Using BrightcovePlayer

The easiest way to start using picture-in-picture is to have your activity extend the BrightcovePlayer. To do this, follow these steps:

  1. In your styles.xml file, enable the picture-in-picture button by adding the following code:
    <style name="BrightcoveControlBar" parent="BrightcoveControlBarDefault">
           <item name="brightcove_picture_in_picture">true</item>
        </style>
  2. In your AndroidManifest.xml file, declare picture-in-picture support for the activity by adding the following:
    <activity android:name="VideoActivity"
          android:resizeableActivity="true"
          android:supportsPictureInPicture="true"
          android:configChanges=
              "screenSize|smallestScreenSize|screenLayout|orientation"
          ...
        

    This is an important step. If you do not declare it, when a user presses the picture-in-picture button in the Brightcove Media Controller, an IllegalStateException will be thrown:

    java.lang.IllegalStateException: enterPictureInPictureMode: Current activity does not support picture-in-picture

When going into picture-in-picture mode, the activity itself is resized, retaining all of the activity components in the picture-In-picture window. To avoid this and to provide an easier implementation, the Brightcove video view will go into Full Screen automatically to match the parent layout width and height showing only the video in the picture-in-picture window. Once you leave this mode, Brightcove video view will return to its original state.

If you do not want picture-in-picture in your app, you can disable the picture-in-picture button by adding the following code in your styles.xml file:

<style name="BrightcoveControlBar" parent="BrightcoveControlBarDefault">
   <item name="brightcove_picture_in_picture">false</item>
</style>

Using a regular Activity

If you are using an activity which does not extend BrightcovePlayer, in addition to declaring support for picture-in-picture as mentioned in the previous section, you need to follow a few extra steps:

  1. Open the MainActivity.java file.
  2. In the onCreate method of the activity, register the Activity with the Brightcove PictureInPictureManager:
    PictureInPictureManager.getInstance().registerActivity(Activity, BrightcoveVideoView)
  3. In the onDestroy method, unregister the Activity:
    PictureInPictureManager.getInstance().unregisterActivity(Activity)
  4. Override the onPictureInPictureModeChanged Activity method, and call onPictureInPictureModeChanged() method as shown below:
    @Override
    public void onPictureInPictureModeChanged (boolean isInPictureInPictureMode, Configuration newConfig) {
       super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig);
       PictureInPictureManager.getInstance().onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig);
    }
  5. Finally, override the onUserLeaveHint() Activity method, and call onUserLeaveHint() as shown below:
    @Override
    public void onUserLeaveHint () {
       super.onUserLeaveHint();
       PictureInPictureManager.getInstance().onUserLeaveHint();
    }

After following these steps, the picture-in-picture button will appear in the Brightcove Media Controller automatically. You can also trigger picture-in-picture programmatically as follows:

PictureInPictureManager.getInstance().enterPictureInPictureMode()

Customizing picture-in-picture

You can customize the behavior and appearance of the picture-in-picture window through the PictureInPictureManager. For example, you can change the aspect ratio of the window or enable/disable captions for your videos.

Android Oreo natively provides three parameters that can be customized:

User actions

Brightcove adds a RemoteAction by default, which handles the Play/Pause video events and sets their respective icons. This means that the default RemoteAction will be added to the list of remote actions you set with the following:

setUserActions

Keep in mind that you can only set a limited number of actions. To get the maximum number of actions, call the following:

Activity.getMaxNumPictureInPictureActions()

Closed captions

You can enable/disable Closed Captions when playing a video in Picture-in-Picture mode by calling the following in the inPictureInPictureManager.

setClosedCaptionsEnabled(boolean)

Closed Captions are disabled by default in phones but enabled in tablets. To reduce the size of the Closed Captions while playing in Picture-in-Picture mode, call the following to set a value between 0 and 1.0f.

setClosedCaptionsReductionScaleFactor(float)

By default, the Closed Captions size in picture-in-picture mode is 0.5f or 50% the original size. Lastly, to enter picture-in-picture mode when the Activity onUserLeaveHint() is called, set the following to true:

setOnUserLeaveEnable(boolean)

Parameters

In order to retrieve the current picture-in-picture parameters, you can call the following:

PictureInPicture.getBrightcovePictureInPictureParams()

This call returns the BrightcovePictureInPictureParams object, which has the getters for all the parameters previously discussed.

Limitations

Android

  • Picture-in-picture will only work on devices with Android Oreo or higher.
  • It is currently not supported for Android TV.
  • Videos with ads are not supported.
  • 360 videos are not supported.

Known issues

Android

  • We found that Widevine-protected videos playing in picture-in-picture mode will turn transparent or black in the Pixel C with Android 8.0. The issue is not reproducible in the same device with Android 8.1.