Picture-in-Picture

Enable Picture-in-Picture (PiP) mode to allow users to continue their call in a floating window while using other apps. PiP provides a seamless multitasking experience during calls.

Picture-in-Picture implementation is handled at the app level using Android’s PiP APIs. The Calls SDK only adjusts the call UI layout to fit the PiP window - it does not manage the PiP window itself.

How It Works

1. Your app enters PiP mode using Android’s enterPictureInPictureMode() API
2. You notify the Calls SDK by calling enablePictureInPictureLayout()
3. The SDK adjusts the call UI to fit the smaller PiP window (hides controls, optimizes layout)
4. When exiting PiP, call disablePictureInPictureLayout() to restore the full UI

Enable Picture-in-Picture

Enter PiP mode programmatically using the enablePictureInPictureLayout() action:

Kotlin

val callSession = CallSession.getInstance()
callSession.enablePictureInPictureLayout()

Java

CallSession callSession = CallSession.getInstance();
callSession.enablePictureInPictureLayout();

Disable Picture-in-Picture

Exit PiP mode and return to the full-screen call interface:

Kotlin

val callSession = CallSession.getInstance()
callSession.disablePictureInPictureLayout()

Java

CallSession callSession = CallSession.getInstance();
callSession.disablePictureInPictureLayout();

Listen for PiP Events

Monitor PiP mode transitions using LayoutListener to update your UI accordingly:

Kotlin

val callSession = CallSession.getInstance()

callSession.addLayoutListener(this, object : LayoutListener() {
    override fun onPictureInPictureLayoutEnabled() {
        Log.d(TAG, "Entered PiP mode")
        // Hide custom overlays or controls
        hideCustomControls()
    }

    override fun onPictureInPictureLayoutDisabled() {
        Log.d(TAG, "Exited PiP mode")
        // Show custom overlays or controls
        showCustomControls()
    }

    override fun onCallLayoutChanged(layoutType: LayoutType) {}
    override fun onParticipantListVisible() {}
    override fun onParticipantListHidden() {}
})

Java

CallSession callSession = CallSession.getInstance();

callSession.addLayoutListener(this, new LayoutListener() {
    @Override
    public void onPictureInPictureLayoutEnabled() {
        Log.d(TAG, "Entered PiP mode");
        // Hide custom overlays or controls
        hideCustomControls();
    }

    @Override
    public void onPictureInPictureLayoutDisabled() {
        Log.d(TAG, "Exited PiP mode");
        // Show custom overlays or controls
        showCustomControls();
    }

    @Override public void onCallLayoutChanged(LayoutType layoutType) {}
    @Override public void onParticipantListVisible() {}
    @Override public void onParticipantListHidden() {}
});

Auto-Enter PiP on Home Press

To automatically enter PiP mode when the user presses the home button or navigates away, override onUserLeaveHint() in your Activity:

Kotlin

class CallActivity : AppCompatActivity() {
    
    override fun onUserLeaveHint() {
        super.onUserLeaveHint()
        if (CallSession.getInstance().isSessionActive()) {
            // Enter Android PiP mode
            enterPictureInPictureMode(
                PictureInPictureParams.Builder()
                    .setAspectRatio(Rational(16, 9))
                    .build()
            )
            // Notify SDK to adjust layout
            CallSession.getInstance().enablePictureInPictureLayout()
        }
    }
    
    override fun onPictureInPictureModeChanged(isInPiPMode: Boolean, config: Configuration) {
        super.onPictureInPictureModeChanged(isInPiPMode, config)
        if (isInPiPMode) {
            CallSession.getInstance().enablePictureInPictureLayout()
        } else {
            CallSession.getInstance().disablePictureInPictureLayout()
        }
    }
}

Java

public class CallActivity extends AppCompatActivity {
    
    @Override
    protected void onUserLeaveHint() {
        super.onUserLeaveHint();
        if (CallSession.getInstance().isSessionActive()) {
            // Enter Android PiP mode
            enterPictureInPictureMode(
                new PictureInPictureParams.Builder()
                    .setAspectRatio(new Rational(16, 9))
                    .build()
            );
            // Notify SDK to adjust layout
            CallSession.getInstance().enablePictureInPictureLayout();
        }
    }
    
    @Override
    public void onPictureInPictureModeChanged(boolean isInPiPMode, Configuration config) {
        super.onPictureInPictureModeChanged(isInPiPMode, config);
        if (isInPiPMode) {
            CallSession.getInstance().enablePictureInPictureLayout();
        } else {
            CallSession.getInstance().disablePictureInPictureLayout();
        }
    }
}

Android Manifest Configuration

Add PiP support to your Activity in AndroidManifest.xml:

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

Attribute	Description
supportsPictureInPicture	Enables PiP support for the activity
configChanges	Prevents activity restart during PiP transitions

PiP mode is only available on Android 8.0 (API level 26) and higher. On older devices, the PiP actions will have no effect.