Picture-in-Picture

1. In AndroidManifest.xml, declare that the current Activity supports PiP mode:

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

2. Make MainActivity extend AgoraPIPFlutterActivity or AgoraPIPFlutterFragmentActivity.

   import io.agora.agora_rtc_ng.AgoraPIPFlutterActivity
   
   class MainActivity : AgoraPIPFlutterActivity()

How PiP is triggered differs by Android version:

• Android 12 and later: The system can automatically enter PiP when the user leaves the current screen in appropriate scenarios. You can use this with autoEnterEnabled.
• Earlier than Android 12: Automatic PiP entry via autoEnterEnabled is not supported. You must trigger PiP entry explicitly, for example by calling pipStart() in response to a user action.

In Xcode, add the Background Modes capability to your app:

1. Open your target's Signing & Capabilities tab.
2. Click + Capability.
3. Select Background Modes.
4. Check Audio, AirPlay, and Picture in Picture.

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

final options = AgoraPipOptions(
  autoEnterEnabled: pipAutoEnterSupported,
  aspectRatioX: 16,
  aspectRatioY: 9,
  sourceRectHintLeft: 0,
  sourceRectHintTop: 0,
  sourceRectHintRight: 0,
  sourceRectHintBottom: 0,
  seamlessResizeEnabled: true,
  useExternalStateMonitor: false,
  externalStateMonitorInterval: 100,
);

await _pip.pipSetup(options);

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

final options = AgoraPipOptions(
  preferredContentWidth: 960,
  preferredContentHeight: 540,
  sourceContentView: 0,
  contentView: 0,
  contentViewLayout: const AgoraPipContentViewLayout(
    padding: 0,
    spacing: 2,
    row: 1,
    column: 2,
  ),
  videoStreams: [
    AgoraPipVideoStream(
      connection: RtcConnection(
        channelId: channelId,
        localUid: localUid,
      ),
      canvas: const VideoCanvas(
        uid: 0,
        sourceType: VideoSourceType.videoSourceCamera,
        setupMode: VideoViewSetupMode.videoViewSetupAdd,
        renderMode: RenderModeType.renderModeHidden,
        mirrorMode: VideoMirrorModeType.videoMirrorModeEnabled,
      ),
    ),
    ...remoteUsers.entries.map(
      (entry) => AgoraPipVideoStream(
        connection: entry.value,
        canvas: VideoCanvas(
          uid: entry.key,
          sourceType: VideoSourceType.videoSourceRemote,
          setupMode: VideoViewSetupMode.videoViewSetupAdd,
          renderMode: RenderModeType.renderModeHidden,
        ),
      ),
    ),
  ],
  controlStyle: 2,
);

await _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. If the page is about to be destroyed or you no longer need PiP, call pipDispose() and dispose() to release resources.

// Start PiP
await _pip.pipStart();

// Stop PiP and restore the app interface
await _pip.pipStop();

// Release the current PiP session
await _pip.pipDispose();

// Destroy the controller
await _pip.dispose();

• After entering PiP on Android, you typically need to update the app UI to match the PiP state. Many apps show only the video area while PiP is active.
• 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.
• pipStart() does not guarantee success in all timing scenarios. Calling it when the app moves to the background is generally more reliable.
• 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.
• Call pipDispose() or dispose() promptly when leaving a channel, destroying the page, or when PiP is no longer needed, to avoid resource leaks.

• 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 supports four control styles. Style 2 is recommended for video call scenarios. Style 3 hides all controls, including the close and restore buttons.
• Call pipDispose() or dispose() promptly when leaving a channel, destroying the page, or when PiP is no longer needed, to avoid resource leaks.