Picture in Picture

When a call is connected, @alaznah/calling can keep media on screen while the user leaves the full-screen call UI.

This is not the same as force-killing the app. PiP and the in-app bubble keep a live process. Swiping the app away from recents (true kill) still stops WebRTC media — see Background Calling.

What ships in the SDK

Mount CallingUI or CallingScreen (or ActiveCallScreen from @alaznah/calling/ui). You do not write your own AVPictureInPictureController or Android enterPictureInPictureMode for a standard React Native app.

Remote camera off still shows an avatar in the PiP window (Android TextureView overlay + iOS AVKit fallback), driven by remoteVideoEnabled and optional participants[].avatarUrl.

Android

Two native paths share one overlay (AlaznahPipVideoController):

Host Kotlin is not required when the launcher Activity is ${applicationId}.MainActivity. The library:

• Merges android:supportsPictureInPicture="true" onto that Activity
• Registers AlaznahPipActivity
• Hooks leave/resume through React Native ActivityEventListener (AlaznahCallingHostHooks)
• Starts ActiveCallKeepAliveService so signaling heartbeats survive PiP / background

Custom launcher Activity name

If your main Activity is not MainActivity, add PiP flags yourself:

<activity
  android:name=".YourMainActivity"
  android:supportsPictureInPicture="true"
  android:resizeableActivity="true"
  android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode" />

Do not override onUserLeaveHint to call enterPictureInPictureMode — the SDK already does that.

Android versions

System PiP needs API 26 (Android 8.0+). minSdk for the SDK is 24; older devices keep the in-app bubble only.

iOS

One AVKit controller is attached to the remote RTCView inside the call Modal (iosPIP on react-native-webrtc). Home and Minimize use that same path.

No AppDelegate PiP code. Do not add a second AVPictureInPictureController in the host app.

Required host config (iOS)

1. Background Modes → Audio (audio in UIBackgroundModes) — required for video PiP while backgrounded
2. Background Modes → Voice over IP (voip) — kill/background incoming, not PiP itself
3. NSCameraUsageDescription + NSMicrophoneUsageDescription
4. Apply the react-native-webrtc patch shipped with the SDK (below)
5. Test on a physical iPhone (iOS 15+)

WebRTC patch (required for iOS PiP)

Stock react-native-webrtc PiP is not enough. The SDK ships the patch under node_modules/@alaznah/calling/patches/.

npm i -D patch-package

Host package.json:

{
  "scripts": {
    "postinstall": "patch-package --patch-dir node_modules/@alaznah/calling/patches"
  }
}

Reinstall, then pod install and rebuild iOS. Do not copy patch files into your app — the SDK folder is the source of truth. The basic-call example already sets this postinstall.

Full native checklist: Native Modules.

Simulator

iOS Simulator does not support AVKit Picture-in-Picture. In-app minimize bubble still works. Validate system PiP on a device.

What you do in JavaScript

With CallingUI / CallingScreen, nothing extra. PiP is armed while a video call is connected.

If you build a custom active-call layout and skip ActiveCallScreen, you must either:

• Render ActiveCallScreen from @alaznah/calling/ui, or
• Reproduce remote RTCView mounting + the SDK’s PiP lifecycle (not recommended)

CallingUI hides the JS Modal while Android system PiP is active so the native overlay is not covered by a black Dialog.

Keep-alive vs kill

Incoming calls when the app is already killed use push + CallKit / full-screen UI — Background Calling — not PiP.

Test checklist

Troubleshooting

Related

• Native Modules — autolinked packages vs host plist / manifest / patch
• Permissions — Background Modes and Android merge table
• Video Calls
• Call UI
• Background Calling — ring when killed (different feature)