Picture-in-Picture

Declare that the current Activity supports PiP mode in your Android project:

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

Then, make MainActivity extend AgoraPIPActivity:

import io.agora.rtc.ng.react.AgoraPIPActivity

class MainActivity : AgoraPIPActivity() {
}

If you need audio or video capture and playback to continue after the app moves to the background or enters PiP, also complete the foreground service configuration. For the required permissions, manifest declarations, and integration steps, see Android background restrictions.

Add the background playback capability to your app in Xcode:

1. Open your target's Signing & Capabilities tab.

2. Click + Capability.

3. Add Background Modes.

4. Select Audio, AirPlay, and Picture in Picture.

   If your use case requires capturing local camera video in multi-tasking mode, contact support@agora.io for guidance on enabling iOS multi-tasking capture. The React Native SDK does not directly expose the multitaskingCameraAccessEnabled configuration. If your use case requires local camera capture during PiP, additional native-side adaptation is needed.

Pass the measured bounds of the video view to sourceRectHint to improve the transition animation when entering PiP.

On Android, you typically need to configure the aspect ratio, the initial source region, and seamless resize:

const videoViewBounds = {
 left: measuredLeft,
 top: measuredTop,
 right: measuredRight,
 bottom: measuredBottom,
};

const options: AgoraPipOptions = {
 autoEnterEnabled: pip.pipIsAutoEnterSupported(),
 aspectRatioX: 960,
 aspectRatioY: 540,
 sourceRectHintLeft: videoViewBounds.left,
 sourceRectHintTop: videoViewBounds.top,
 sourceRectHintRight: videoViewBounds.right,
 sourceRectHintBottom: videoViewBounds.bottom,
 seamlessResizeEnabled: true,
 useExternalStateMonitor: true,
 externalStateMonitorInterval: 100,
};

pip.pipSetup(options);

On iOS, you can configure the PiP window size, video stream layout, and system control style:

const options: AgoraPipOptions = {
 autoEnterEnabled: pip.pipIsAutoEnterSupported(),
 preferredContentWidth: 960,
 preferredContentHeight: 540,
 contentView: 0,
 sourceContentView: 0,
 contentViewLayout: {
  padding: 0,
  spacing: 2,
  row: 1,
  column: 2,
 },
 videoStreams: [
  {
   connection: {
    channelId,
    localUid: uid,
   },
   canvas: {
    sourceType: VideoSourceType.VideoSourceCamera,
    setupMode: VideoViewSetupMode.VideoViewSetupAdd,
    renderMode: RenderModeType.RenderModeHidden,
    mirrorMode: VideoMirrorModeType.VideoMirrorModeEnabled,
   },
  },
  ...remoteUsers.map((userUid) => ({
   connection: {
    channelId,
    localUid: userUid,
   },
   canvas: {
    uid: userUid,
    sourceType: VideoSourceType.VideoSourceRemote,
    setupMode: VideoViewSetupMode.VideoViewSetupAdd,
    renderMode: RenderModeType.RenderModeHidden,
   },
  })),
 ],
 controlStyle: 2,
};

pip.pipSetup(options);

In this example:

• When contentView is set to 0, the SDK manages the native views inside the PiP window. If you pass a non-zero value, you are responsible for managing the native view layout.
• videoStreams defines the local and remote streams to display.
• contentViewLayout configures the grid layout for video streams inside the PiP window. Streams are arranged from left to right, then top to bottom.
• controlStyle: 2 hides the play/pause button and progress bar, keeping only the essential window control buttons. This is recommended for real-time interactive scenarios.

Call pipStop to stop PiP and restore the app interface, then call pipDispose to release the session resources. Call release only when destroying the page or when the controller is no longer needed.

// Session level: start PiP
pip.pipStart();

// Session level: stop PiP and restore the app interface
pip.pipStop();

// Session level: release the current PiP session resources
pip.pipDispose();

// Controller/page destroy level: final release
pip.release();

• After entering PiP on Android, you typically need to update the app UI to match the PiP state.
• Android 12 and later support automatic PiP entry when the app moves to the background. On earlier versions, you must trigger PiP entry explicitly, for example by calling pipStart in response to a user action. Extending AgoraPIPActivity simplifies this adaptation.
• PiP does not bypass Android background restrictions. If you need to continue capturing or playing audio and video in the background, combine PiP with a foreground service. For details, see Android background restrictions.
• On Android, pipStop moves the task to the background rather than exiting PiP and restoring the foreground page. Full-screen restoration is typically handled by the user through the system PiP window controls.
• Distinguish between session-level and controller-level release: call pipDispose to end the current PiP session, and call release only when the page is destroyed or the controller is no longer needed.

• PiP must be triggered by explicit user action only, such as tapping a button or swiping up to the home screen. Triggering PiP programmatically without a user action may result in App Store review rejection.
• The PiP window is managed by the system and the SDK. Your app does not need to render a custom floating window.
• To display multiple video streams in PiP mode, configure the layout explicitly using videoStreams and contentViewLayout. When remote users join or leave, call pipSetup again with the updated videoStreams. You do not need to call pipDispose first.
• AgoraPipOptions.controlStyle accepts values 0 to 3. Use 2 for video call scenarios, which hides the play/pause button and progress bar. Style 3 hides all controls, including the close and restore buttons.
• Distinguish between session-level and controller-level release: call pipStop and pipDispose to end the current PiP session, and call release only when the page is destroyed or the controller is no longer needed.