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.