PIP Mode (beta)

100ms Flutter SDK provides support for creating Picture in Picture mode experience for video calls.

PIP Mode lets the user watch the room video in a small window pinned to a corner of the screen while navigating between apps or browsing content on the main screen.

Minimum Requirements

• Minimum version required to support PiP is Android 8.0 (API level 26) and iOS 15
• Minimum hmssdk_flutter SDK version required is 1.3.0
• To know more about PIP features, minimum version requirements for android please check here.

Android

How to add PiP support

<activity
    ....
    android:supportsPictureInPicture="true"
    android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation"
    ... />

bool isPipAvailable = await HMSAndroidPIPController.isAvailable();

// enterPipMode is a Future<bool> function where true indicates that the application has entered pip mode successfully.
///[autoEnterPip] if true start pip mode will start automatically when app is minimized.For android 12 and above
///[aspectRatio]: List of int indicating ratio for PIP window as [width,height]
bool isPipEnteredSuccesfully = await HMSAndroidPIPController.start(autoEnterPip: true/false, aspectRatio: [16, 9]);

How to check whether PIP is active

To check whether PIP mode is currently active use isActive method as:

bool isPipActive = await HMSAndroidPIPController.isActive();

Checkout PIP in Action

How PIP mode is implemented in our example app. Checkout here:

iOS

Minimum Requirements

• Minimum iOS version required to support PiP is iOS 15
• Minimum hmssdk_flutter SDK version required is 1.3.0
• Your app should have com.apple.developer.avfoundation.multitasking-camera-access Entitlement to use PiP Mode.

Your app needs to run on iOS 13.5 or later to use the entitlement. Without the entitlement, the system disables the camera access for your app. When your app enters PIP mode, it needs this entitlement to continue using the camera.

After you receive permission from Apple, add the Entitlement to your app by opening the Entitlements file in Xcode. Add the key and set the corresponding value to YES.

Check PIP availablility

If you want to check whether the current device supports PIP mode or not, you can use the isAvailable method from the HMSIOSPIPController. However, it's important to note that PIP mode is only available on iOS devices running iOS 15 or later.

To check whether PIP mode is available, you can use the following code:

bool isPipAvailable = await HMSIOSPIPController.isAvailable();

The isAvailable method returns a boolean value that indicates whether PIP mode is supported on the current device. If it returns true, you can use PIP mode in your app. Otherwise, PIP mode is not supported and you should handle this scenario accordingly.

Setup PIP

To enable Picture-in-Picture (PIP) mode in iOS devices, you need to first set it up using the HMSIOSPIPController. This should be done by calling the setup method with the following parameters:

• autoEnterPip: A boolean parameter that determines whether to automatically enter PIP mode when the app is minimized. The default value is true.

• aspectRatio: A list of two integers that specifies the aspect ratio of the PIP window. The first integer represents the width, and the second integer represents the height. Valid aspect ratios include [16, 9], [9, 16], [4, 3], [3, 4] and [1, 1]. The default value is [16, 9].

• scaleType: A string parameter that specifies how the video should be scaled within the PIP window. Valid values are SCALE_ASPECT_FIT, SCALE_ASPECT_FILL, and SCALE_ASPECT_BALANCED. The default value is SCALE_ASPECT_FILL. More information about each scaling type can be found here.

• backgroundColor: A parameter that specifies the background color of the PIP window when the video is off. The default value is Colors.black.

By using these parameters, you can customize the behavior and appearance of the PIP mode in your iOS Flutter app.

HMSIOSPIPController.setup(autoEnterPip: true, aspectRatio: [9, 16]);

You can call the PIP setup function in various scenarios such as:

• When a user joins a call
• When a screenshare session starts
• When a user clicks a button inside Room

By calling the PIP setup function in these scenarios, you can enable PIP mode and provide a more convenient and flexible user experience for your app's users.

Change Video Track

The HMSIOSPIPController.changeVideoTrack method is called when you want to change the HMSVideoTrack in PIP window. following are the parameters need to be passed at time of calling this method:

track - HMSVideoTrack object of the track which you wish to display needs to be passed for changing PIP window track.

aspectRatio - Ratio for PIP window.List of int indicating ratio for PIP window as [width,height].For example: [16, 9], [9, 16] ,[1, 1]. Default value is [16, 9].

alternativeText - Alternative text is a textual substitute if HMSVideoTrack is muted.This is the text which you wish to display when video for peer is OFF while in PIP

scaleType - To set the video scaling. scaleType can be one of the following:

• SCALE_ASPECT_FIT
• SCALE_ASPECT_FILL
• SCALE_ASPECT_BALANCED

Default value is ScaleType.SCALE_ASPECT_FILL. More info about each of this can be found here

backgroundColor - To set the background colour when video is off that colour will be visible in background of PIP window. Default value is Colors.black.

HMSIOSPIPController.changeVideoTrack(
  track: videoTrack,
  aspectRatio: [9, 16],
  alternativeText: "peer Name",
  scaleType: ScaleType.SCALE_ASPECT_FILL,
  backgroundColor: Colors.blue
);

Change Text

The HMSIOSPIPController.changeText method is called when you want to remove or show only text in PIP window. following are the parameters need to be passed at time of calling this method:

text - Text you want to show in PIP window. It will replace HMSVideoTrack if it playing in PIP window.

aspectRatio - Ratio for PIP window.List of int indicating ratio for PIP window as [width,height].For example: [16, 9], [9, 16] ,[1, 1]. Default value is [16, 9].

scaleType - To set the video scaling. scaleType can be one of the following: [SCALE_ASPECT_FIT, SCALE_ASPECT_FILL, SCALE_ASPECT_BALANCED]. Default value is ScaleType.SCALE_ASPECT_FILL.More info about each of this can be found here

backgroundColor - To set the background colour when video is off that colour will be visible in background of PIP window. Default value is Colors.black.

HMSIOSPIPController.changeText(
  text: "Peer Name",
  aspectRatio: [9, 16],
  scaleType: ScaleType.SCALE_ASPECT_FILL,
  backgroundColor: Colors.blue
);

How to check whether PIP is active

To check whether PIP mode is currently active use isActive method as:

bool isPipActive = await HMSIOSPIPController.isActive();

Start PIP Manually

To start PIP manually call the following method:

HMSIOSPIPController.start();

Stop PIP Manually

To stop PIP manually call the following method:

HMSIOSPIPController.stop();

Destroy PIP

This method is called to destroy PIP window:

HMSIOSPIPController.destroy();

Checkout PIP in Action

How PIP mode is implemented in our example app. Checkout here:

You can checkout the 100ms Flutter SDK Github repository which also contains the PIP implementation. Example app implementation here.