100ms Logo

100ms

Docs

Search docs
/

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

Update the manifest file

You need to update the activity tag in the AndroidManifest.xml

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

Check PIP availablility

PIP mode only works above Android API Level 26(Android 8.0) but to check whether the current device supports PIP mode or not HMSAndroidPIPController.isAvailable method can be used:

bool _isPipAvailable = await HMSAndroidPIPController.isAvailable();

Enter PIP mode

To show PIP mode in the application:

// 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();

To display UI according to PIP use the isActive to set the state for PIP mode and render the UI accordingly.

Checkout PIP in Action

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

iOS

Check PIP availablility

PIP mode only works above iOS 15 but to check whether the current device supports PIP mode or not HMSIOSPIPController.isAvailable method can be used:

bool _isPipAvailable = await HMSIOSPIPController.isAvailable();

Setup PIP

In iOS devices PIP is needed to be setup first for that call HMSIOSPIPController.setup with the following parameters:

autoEnterPip - Enable [autoEnterPip] will start pip mode automatically when app minimized. Default value is true

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.setup(autoEnterPip: true, aspectRatio: [9, 16]);

Note: Setup PIP function can be called like - onJoin, or on click of a button, or when a Screenshare starts etc

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 );

Note: changeVideoTrack method can be callled like - minimizing of app, onUpdateSpeakers or onTrackUpdate etc.

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 );

Note: changeText method can be callled like - when HMSVideoTrack changes its mute status or want to show text when local peer is speaking.

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();

Note: This method can be call at time of changing role to hls-viewer role.

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.


Have a suggestion? Recommend changes ->

Was this helpful?

1234