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.

    Picture in picture is one of the new features with iOS 14.

    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

    • 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 19 Nov 2020