support Contact Support | system status System Status
Page Contents

    Picture-in-Picture with the Native SDKs

    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: Oreo 8.0+ (API level 26+)
    • iOS: 10.0+

    Native SDK version

    • Android: Brightcove Native SDK for Android version 6.1.0+
    • iOS: Brightcove Native SDK for iOS version 6.4.4+

    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.

    iOS implementation

    To get started with picture-in-picture, add showPictureInPictureButton to BCOVPUIPlayerViewOptions. When set to true, a picture-in-picture button will be added to the player controls on supported devices.

    For more details, see the following:

    For a code example, see the Basic Video Playback App.

    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

    iOS

    • Currently, Apple only supports iPad devices
    • 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.

    Page last updated on 12 Jun 2020