Skip to main content

Agora Conversational AI Engine v2.4 Release

×

March 2026 Agora Monthly Digest Meet our new AI agents

×

React Native iOS Video Pausing When App Minimized – Implementing and Troubleshooting Picture-in-Picture (PiP) with Agora

Updated

Issue Description:

In a React Native app using the Agora SDK on iOS, video streaming stops when the user minimizes the app or switches to another app. Audio continues playing, but the local video feed pauses instead of showing in a floating window, unlike apps such as WhatsApp that continue displaying video using Picture-in-Picture (PiP) mode.

 

Platform/SDK:

React Native Agora SDK on iOS

 

Error Message (optional):

No visible error message appears. The camera feed simply pauses when the app goes into the background.

 

Step by Step Solution:

1. Enable Background Modes in Xcode:

a. Open your iOS project in Xcode.
b. Select your project target.
c. Go to Signing & Capabilities > + Capability > Background Modes.
d. Enable the following options:

  • ✅ Audio, AirPlay, and Picture in Picture
  • (Optional) ✅ Background Processing

 

2. Implement Picture-in-Picture (PiP) Support:

a. Use AVPictureInPictureController to create a PiP experience, allowing the video to continue in a small floating window when the app is minimized.
b. Ensure your video rendering view is compatible with PiP (for example, RTCVideoView or a UIView backed by AVPlayerLayer).
c. Start PiP mode programmatically when the app enters the background using appropriate React Native lifecycle hooks or native module bridging.

 

3. Update Info.plist (if not already):

Add required keys in your Info.plist file to ensure background video functionality:

  • Required background modes → Add App plays audio or streams audio/video using AirPlay

 

4. Rebuild and Test:

a. Rebuild your app using npx react-native run-ios.
b. Start a video call and minimize the app to confirm that the floating PiP window continues showing the video feed.

 

Root Cause:

On iOS, when an app moves to the background, the operating system automatically suspends camera capture for privacy and performance reasons. Enabling Picture-in-Picture (PiP) mode is required to allow video playback or capture to continue while the app is not active.

 

Prevention/Best Practice:

  • Always enable appropriate background modes early in development when building apps that require continuous audio or video streaming.
  • Test PiP behavior on real iOS devices, as simulators may not fully reflect background video behavior.
  • Keep your Agora SDK updated to ensure compatibility with the latest iOS background policies.

 

Corresponding Document/Link (optional):

Related articles