Implementing Picture-in-Picture Mode for iOS Apps
PiP on iOS doesn't work automatically: app must explicitly support via AVKit API, properly configure AVAudioSession, and handle PiP window lifecycle. Seems simple—until you deal with custom content, not AVPlayer.
Basic Implementation with AVPlayerViewController
Simplest path—AVPlayerViewController. PiP out of the box: set allowsPictureInPicturePlayback = true, configure AVAudioSession, PiP button appears automatically.
import AVKit
class VideoViewController: UIViewController {
private var player: AVPlayer!
private var playerViewController: AVPlayerViewController!
override func viewDidLoad() {
super.viewDidLoad()
// Mandatory: playback category for background playback
try? AVAudioSession.sharedInstance().setCategory(.playback, mode: .moviePlayback)
try? AVAudioSession.sharedInstance().setActive(true)
player = AVPlayer(url: videoURL)
playerViewController = AVPlayerViewController()
playerViewController.player = player
playerViewController.allowsPictureInPicturePlayback = true
addChild(playerViewController)
view.addSubview(playerViewController.view)
playerViewController.view.frame = view.bounds
playerViewController.didMove(toParent: self)
}
}
Add to Info.plist: UIBackgroundModes → audio. Without it, PiP shows video but sound disappears on background transition.
Custom PiP: AVPictureInPictureController
Custom video player (not AVPlayerViewController)—need AVPictureInPictureController directly. Initialized via AVPictureInPictureController(playerLayer:) for AVPlayerLayer or AVPictureInPictureControllerContentSource with AVPictureInPictureSampleBufferPlaybackDelegate for custom rendering.
class CustomVideoPlayer: UIView {
private var playerLayer: AVPlayerLayer!
private var pipController: AVPictureInPictureController?
func setupPiP() {
guard AVPictureInPictureController.isPictureInPictureSupported() else { return }
pipController = AVPictureInPictureController(playerLayer: playerLayer)
pipController?.delegate = self
pipController?.canStartPictureInPictureAutomaticallyFromInline = true // auto-start on background
}
}
extension CustomVideoPlayer: AVPictureInPictureControllerDelegate {
func pictureInPictureControllerWillStartPictureInPicture(_ controller: AVPictureInPictureController) {
// hide custom controls over video
}
func pictureInPicture(_ controller: AVPictureInPictureController,
restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void) {
// restore UI when closing PiP
completionHandler(true)
}
}
PiP with Arbitrary Content (iOS 15+)
AVPictureInPictureVideoCallViewController (iOS 15+)—non-video content: live camera, WebRTC, animations. Content renders in UIView, placed in PiP container via AVPictureInPictureControllerContentSource(activeVideoCallSourceView:contentViewController:).
Messengers use this (FaceTime, Zoom) for video calls over other apps. Key restriction: content must be truly "active call"—Apple may reject if abused in review.
Common Problems
PiP doesn't start on background. 90% of cases: missing canStartPictureInPictureAutomaticallyFromInline = true, or UIBackgroundModes: audio not in Info.plist, or AVAudioSession inactive.
Video freezes after PiP exit. In restoreUserInterfaceForPictureInPictureStopWithCompletionHandler, return completionHandler(true) only after UI fully restored. Calling immediately—system thinks restoration complete and does transition animation, but your UI not ready.
Custom buttons in PiP window. iOS 16+—AVPictureInPictureController.requiresLinearPlayback = false and custom playbackControlsIncludeTransportBar, playbackControlsIncludeInfoViews. Before iOS 16—standard controls only.
Timelines
2–3 working days for basic PiP with AVPlayerViewController. Custom player with AVPictureInPictureController and non-standard content—up to 5 days. Cost calculated individually.