From c2cfe405228f42c8cbbfce8733421cbad46ff420 Mon Sep 17 00:00:00 2001
From: aviadlevy <aviadlevy1@gmail.com>
Date: Tue, 19 May 2026 22:24:01 +0300
Subject: [PATCH] feat(pip): add Picture-in-Picture support for Android and iOS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the long-requested PiP feature for the Flutter-side video players
(libMPV/libMDK). Native ExoPlayer activity is out of scope.

Behavior:
- The PiP icon button in the player controls is always visible on
  Android/iOS and lets users manually enter PiP at any time.
- A new 'Auto Picture-in-Picture' setting (Settings → Player) controls
  only whether the OS should also auto-enter PiP when the app is
  backgrounded from the player. Defaults to on.
- While in PiP, the controls overlay hides so only the video surface
  is captured for the PiP window.
- Lifecycle: on player dispose, auto-enter is turned off so the user
  is not auto-PiP'd when backgrounding from unrelated screens.

Architecture:
- New PipManager wrapper (lib/wrappers/pip_manager.dart) hides
  package:pip behind a narrow PipClient interface so it can be
  unit-tested without the native plugin. Exposes enable/enter/disable/
  dispose and a Stream<bool> for the current PiP state. 9 unit tests.
- Riverpod providers (lib/providers/pip_provider.dart): pipManagerProvider
  and pipStateProvider.
- VideoPlayer integration listens to the auto-enter preference and
  re-applies it live if the user toggles the setting mid-playback.

Platform plumbing:
- pubspec: add pip ^0.0.3.
- Android manifest: supportsPictureInPicture=true on MainActivity.
  configChanges already covers screenSize|smallestScreenSize|screenLayout.
- iOS Info.plist: add 'audio' to UIBackgroundModes (required for iOS
  PiP per package:pip docs).

Caveats:
- PiP aspect ratio is hardcoded 16:9. PlayerState does not currently
  expose video width/height; plumbing real ratios through every
  backend is deferred.
- The native player (separate VideoPlayerActivity) already has
  supportsPictureInPicture in its manifest but no logic — out of scope.

Closes #494.
---
 android/app/src/main/AndroidManifest.xml      |   1 +
 ios/Runner/Info.plist                         |   1 +
 lib/l10n/app_en.arb                           |  16 ++
 .../settings/video_player_settings.dart       |   1 +
 .../video_player_settings.freezed.dart        |  53 ++++--
 .../settings/video_player_settings.g.dart     |   2 +
 lib/providers/pip_provider.dart               |  14 ++
 .../video_player_settings_provider.dart       |   2 +
 .../settings/player_settings_page.dart        |  12 ++
 lib/screens/video_player/video_player.dart    |  28 ++-
 .../video_player/video_player_controls.dart   |  29 ++-
 lib/wrappers/pip_manager.dart                 | 148 +++++++++++++++
 pubspec.lock                                  |   8 +
 pubspec.yaml                                  |   1 +
 test/pip_manager_test.dart                    | 170 ++++++++++++++++++
 15 files changed, 471 insertions(+), 15 deletions(-)
 create mode 100644 lib/providers/pip_provider.dart
 create mode 100644 lib/wrappers/pip_manager.dart
 create mode 100644 test/pip_manager_test.dart

diff --git a/android/app/src/main/AndroidManifest.xml b/android/app/src/main/AndroidManifest.xml
index 284196fc6..c2083ad9e 100644
--- a/android/app/src/main/AndroidManifest.xml
+++ b/android/app/src/main/AndroidManifest.xml
@@ -38,6 +38,7 @@
             android:theme="@style/LaunchTheme"
             android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
             android:hardwareAccelerated="true"
+            android:supportsPictureInPicture="true"
             android:windowSoftInputMode="adjustResize">
             <!-- Specifies an Android theme to apply to this Activity as soon as
                  the Android process has started. This theme is visible to the user
diff --git a/ios/Runner/Info.plist b/ios/Runner/Info.plist
index 361acb2ee..2eaaed126 100644
--- a/ios/Runner/Info.plist
+++ b/ios/Runner/Info.plist
@@ -50,6 +50,7 @@
 
 		<key>UIBackgroundModes</key>
 		<array>
+			<string>audio</string>
 			<string>fetch</string>
 		</array>
 
diff --git a/lib/l10n/app_en.arb b/lib/l10n/app_en.arb
index 45cfba3c0..1d6e3d46c 100644
--- a/lib/l10n/app_en.arb
+++ b/lib/l10n/app_en.arb
@@ -1120,6 +1120,22 @@
   "@videoScalingFillScreenNotif": {},
   "videoScalingFillScreenTitle": "Fill screen",
   "@videoScalingFillScreenTitle": {},
+  "pictureInPictureTitle": "Picture-in-Picture",
+  "@pictureInPictureTitle": {
+    "description": "Tooltip on the in-player PiP button"
+  },
+  "pictureInPictureAutoTitle": "Auto Picture-in-Picture",
+  "@pictureInPictureAutoTitle": {
+    "description": "Title of the auto-enter Picture-in-Picture setting toggle"
+  },
+  "pictureInPictureSubtitle": "Automatically enter Picture-in-Picture when you leave the player. The PiP button in the controls always works regardless of this setting.",
+  "@pictureInPictureSubtitle": {
+    "description": "Subtitle of the auto-enter Picture-in-Picture setting toggle"
+  },
+  "pictureInPictureNotSupported": "Picture-in-Picture is not available on this device",
+  "@pictureInPictureNotSupported": {
+    "description": "Snackbar shown when the user taps the PiP button and the OS reports it unsupported"
+  },
   "videoScalingFitHeight": "Fit Height",
   "@videoScalingFitHeight": {},
   "videoScalingFitWidth": "Fit Width",
diff --git a/lib/models/settings/video_player_settings.dart b/lib/models/settings/video_player_settings.dart
index 0c9a28c28..a7ce1acc6 100644
--- a/lib/models/settings/video_player_settings.dart
+++ b/lib/models/settings/video_player_settings.dart
@@ -94,6 +94,7 @@ abstract class VideoPlayerSettingsModel with _$VideoPlayerSettingsModel {
     @Default(false) bool enableAdvancedVideoOptions,
     @Default(true) bool enableEdgeGestures,
     @Default(false) bool reverseEdgeGestures,
+    @Default(true) bool enablePictureInPicture,
   }) = _VideoPlayerSettingsModel;
 
   double get volume => internalVolume;
diff --git a/lib/models/settings/video_player_settings.freezed.dart b/lib/models/settings/video_player_settings.freezed.dart
index 4506f254b..000f9d7a4 100644
--- a/lib/models/settings/video_player_settings.freezed.dart
+++ b/lib/models/settings/video_player_settings.freezed.dart
@@ -37,6 +37,7 @@ mixin _$VideoPlayerSettingsModel implements DiagnosticableTreeMixin {
   bool get enableAdvancedVideoOptions;
   bool get enableEdgeGestures;
   bool get reverseEdgeGestures;
+  bool get enablePictureInPicture;
 
   /// Create a copy of VideoPlayerSettingsModel
   /// with the given fields replaced by the non-null parameter values.
@@ -76,12 +77,14 @@ mixin _$VideoPlayerSettingsModel implements DiagnosticableTreeMixin {
       ..add(DiagnosticsProperty(
           'enableAdvancedVideoOptions', enableAdvancedVideoOptions))
       ..add(DiagnosticsProperty('enableEdgeGestures', enableEdgeGestures))
-      ..add(DiagnosticsProperty('reverseEdgeGestures', reverseEdgeGestures));
+      ..add(DiagnosticsProperty('reverseEdgeGestures', reverseEdgeGestures))
+      ..add(DiagnosticsProperty(
+          'enablePictureInPicture', enablePictureInPicture));
   }
 
   @override
   String toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) {
-    return 'VideoPlayerSettingsModel(screenBrightness: $screenBrightness, videoFit: $videoFit, fillScreen: $fillScreen, hardwareAccel: $hardwareAccel, useLibass: $useLibass, enableTunneling: $enableTunneling, bufferSize: $bufferSize, playerOptions: $playerOptions, internalVolume: $internalVolume, allowedOrientations: $allowedOrientations, nextVideoType: $nextVideoType, maxHomeBitrate: $maxHomeBitrate, maxInternetBitrate: $maxInternetBitrate, audioDevice: $audioDevice, segmentSkipSettings: $segmentSkipSettings, hotKeys: $hotKeys, screensaver: $screensaver, enableSpeedBoost: $enableSpeedBoost, speedBoostRate: $speedBoostRate, enableDoubleTapSeek: $enableDoubleTapSeek, enableAdvancedVideoOptions: $enableAdvancedVideoOptions, enableEdgeGestures: $enableEdgeGestures, reverseEdgeGestures: $reverseEdgeGestures)';
+    return 'VideoPlayerSettingsModel(screenBrightness: $screenBrightness, videoFit: $videoFit, fillScreen: $fillScreen, hardwareAccel: $hardwareAccel, useLibass: $useLibass, enableTunneling: $enableTunneling, bufferSize: $bufferSize, playerOptions: $playerOptions, internalVolume: $internalVolume, allowedOrientations: $allowedOrientations, nextVideoType: $nextVideoType, maxHomeBitrate: $maxHomeBitrate, maxInternetBitrate: $maxInternetBitrate, audioDevice: $audioDevice, segmentSkipSettings: $segmentSkipSettings, hotKeys: $hotKeys, screensaver: $screensaver, enableSpeedBoost: $enableSpeedBoost, speedBoostRate: $speedBoostRate, enableDoubleTapSeek: $enableDoubleTapSeek, enableAdvancedVideoOptions: $enableAdvancedVideoOptions, enableEdgeGestures: $enableEdgeGestures, reverseEdgeGestures: $reverseEdgeGestures, enablePictureInPicture: $enablePictureInPicture)';
   }
 }
 
@@ -114,7 +117,8 @@ abstract mixin class $VideoPlayerSettingsModelCopyWith<$Res> {
       bool enableDoubleTapSeek,
       bool enableAdvancedVideoOptions,
       bool enableEdgeGestures,
-      bool reverseEdgeGestures});
+      bool reverseEdgeGestures,
+      bool enablePictureInPicture});
 }
 
 /// @nodoc
@@ -153,6 +157,7 @@ class _$VideoPlayerSettingsModelCopyWithImpl<$Res>
     Object? enableAdvancedVideoOptions = null,
     Object? enableEdgeGestures = null,
     Object? reverseEdgeGestures = null,
+    Object? enablePictureInPicture = null,
   }) {
     return _then(_self.copyWith(
       screenBrightness: freezed == screenBrightness
@@ -247,6 +252,10 @@ class _$VideoPlayerSettingsModelCopyWithImpl<$Res>
           ? _self.reverseEdgeGestures
           : reverseEdgeGestures // ignore: cast_nullable_to_non_nullable
               as bool,
+      enablePictureInPicture: null == enablePictureInPicture
+          ? _self.enablePictureInPicture
+          : enablePictureInPicture // ignore: cast_nullable_to_non_nullable
+              as bool,
     ));
   }
 }
@@ -367,7 +376,8 @@ extension VideoPlayerSettingsModelPatterns on VideoPlayerSettingsModel {
             bool enableDoubleTapSeek,
             bool enableAdvancedVideoOptions,
             bool enableEdgeGestures,
-            bool reverseEdgeGestures)?
+            bool reverseEdgeGestures,
+            bool enablePictureInPicture)?
         $default, {
     required TResult orElse(),
   }) {
@@ -397,7 +407,8 @@ extension VideoPlayerSettingsModelPatterns on VideoPlayerSettingsModel {
             _that.enableDoubleTapSeek,
             _that.enableAdvancedVideoOptions,
             _that.enableEdgeGestures,
-            _that.reverseEdgeGestures);
+            _that.reverseEdgeGestures,
+            _that.enablePictureInPicture);
       case _:
         return orElse();
     }
@@ -441,7 +452,8 @@ extension VideoPlayerSettingsModelPatterns on VideoPlayerSettingsModel {
             bool enableDoubleTapSeek,
             bool enableAdvancedVideoOptions,
             bool enableEdgeGestures,
-            bool reverseEdgeGestures)
+            bool reverseEdgeGestures,
+            bool enablePictureInPicture)
         $default,
   ) {
     final _that = this;
@@ -470,7 +482,8 @@ extension VideoPlayerSettingsModelPatterns on VideoPlayerSettingsModel {
             _that.enableDoubleTapSeek,
             _that.enableAdvancedVideoOptions,
             _that.enableEdgeGestures,
-            _that.reverseEdgeGestures);
+            _that.reverseEdgeGestures,
+            _that.enablePictureInPicture);
       case _:
         throw StateError('Unexpected subclass');
     }
@@ -513,7 +526,8 @@ extension VideoPlayerSettingsModelPatterns on VideoPlayerSettingsModel {
             bool enableDoubleTapSeek,
             bool enableAdvancedVideoOptions,
             bool enableEdgeGestures,
-            bool reverseEdgeGestures)?
+            bool reverseEdgeGestures,
+            bool enablePictureInPicture)?
         $default,
   ) {
     final _that = this;
@@ -542,7 +556,8 @@ extension VideoPlayerSettingsModelPatterns on VideoPlayerSettingsModel {
             _that.enableDoubleTapSeek,
             _that.enableAdvancedVideoOptions,
             _that.enableEdgeGestures,
-            _that.reverseEdgeGestures);
+            _that.reverseEdgeGestures,
+            _that.enablePictureInPicture);
       case _:
         return null;
     }
@@ -577,7 +592,8 @@ class _VideoPlayerSettingsModel extends VideoPlayerSettingsModel
       this.enableDoubleTapSeek = true,
       this.enableAdvancedVideoOptions = false,
       this.enableEdgeGestures = true,
-      this.reverseEdgeGestures = false})
+      this.reverseEdgeGestures = false,
+      this.enablePictureInPicture = true})
       : _allowedOrientations = allowedOrientations,
         _segmentSkipSettings = segmentSkipSettings,
         _hotKeys = hotKeys,
@@ -672,6 +688,9 @@ class _VideoPlayerSettingsModel extends VideoPlayerSettingsModel
   @override
   @JsonKey()
   final bool reverseEdgeGestures;
+  @override
+  @JsonKey()
+  final bool enablePictureInPicture;
 
   /// Create a copy of VideoPlayerSettingsModel
   /// with the given fields replaced by the non-null parameter values.
@@ -716,12 +735,14 @@ class _VideoPlayerSettingsModel extends VideoPlayerSettingsModel
       ..add(DiagnosticsProperty(
           'enableAdvancedVideoOptions', enableAdvancedVideoOptions))
       ..add(DiagnosticsProperty('enableEdgeGestures', enableEdgeGestures))
-      ..add(DiagnosticsProperty('reverseEdgeGestures', reverseEdgeGestures));
+      ..add(DiagnosticsProperty('reverseEdgeGestures', reverseEdgeGestures))
+      ..add(DiagnosticsProperty(
+          'enablePictureInPicture', enablePictureInPicture));
   }
 
   @override
   String toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) {
-    return 'VideoPlayerSettingsModel(screenBrightness: $screenBrightness, videoFit: $videoFit, fillScreen: $fillScreen, hardwareAccel: $hardwareAccel, useLibass: $useLibass, enableTunneling: $enableTunneling, bufferSize: $bufferSize, playerOptions: $playerOptions, internalVolume: $internalVolume, allowedOrientations: $allowedOrientations, nextVideoType: $nextVideoType, maxHomeBitrate: $maxHomeBitrate, maxInternetBitrate: $maxInternetBitrate, audioDevice: $audioDevice, segmentSkipSettings: $segmentSkipSettings, hotKeys: $hotKeys, screensaver: $screensaver, enableSpeedBoost: $enableSpeedBoost, speedBoostRate: $speedBoostRate, enableDoubleTapSeek: $enableDoubleTapSeek, enableAdvancedVideoOptions: $enableAdvancedVideoOptions, enableEdgeGestures: $enableEdgeGestures, reverseEdgeGestures: $reverseEdgeGestures)';
+    return 'VideoPlayerSettingsModel(screenBrightness: $screenBrightness, videoFit: $videoFit, fillScreen: $fillScreen, hardwareAccel: $hardwareAccel, useLibass: $useLibass, enableTunneling: $enableTunneling, bufferSize: $bufferSize, playerOptions: $playerOptions, internalVolume: $internalVolume, allowedOrientations: $allowedOrientations, nextVideoType: $nextVideoType, maxHomeBitrate: $maxHomeBitrate, maxInternetBitrate: $maxInternetBitrate, audioDevice: $audioDevice, segmentSkipSettings: $segmentSkipSettings, hotKeys: $hotKeys, screensaver: $screensaver, enableSpeedBoost: $enableSpeedBoost, speedBoostRate: $speedBoostRate, enableDoubleTapSeek: $enableDoubleTapSeek, enableAdvancedVideoOptions: $enableAdvancedVideoOptions, enableEdgeGestures: $enableEdgeGestures, reverseEdgeGestures: $reverseEdgeGestures, enablePictureInPicture: $enablePictureInPicture)';
   }
 }
 
@@ -756,7 +777,8 @@ abstract mixin class _$VideoPlayerSettingsModelCopyWith<$Res>
       bool enableDoubleTapSeek,
       bool enableAdvancedVideoOptions,
       bool enableEdgeGestures,
-      bool reverseEdgeGestures});
+      bool reverseEdgeGestures,
+      bool enablePictureInPicture});
 }
 
 /// @nodoc
@@ -795,6 +817,7 @@ class __$VideoPlayerSettingsModelCopyWithImpl<$Res>
     Object? enableAdvancedVideoOptions = null,
     Object? enableEdgeGestures = null,
     Object? reverseEdgeGestures = null,
+    Object? enablePictureInPicture = null,
   }) {
     return _then(_VideoPlayerSettingsModel(
       screenBrightness: freezed == screenBrightness
@@ -889,6 +912,10 @@ class __$VideoPlayerSettingsModelCopyWithImpl<$Res>
           ? _self.reverseEdgeGestures
           : reverseEdgeGestures // ignore: cast_nullable_to_non_nullable
               as bool,
+      enablePictureInPicture: null == enablePictureInPicture
+          ? _self.enablePictureInPicture
+          : enablePictureInPicture // ignore: cast_nullable_to_non_nullable
+              as bool,
     ));
   }
 }
diff --git a/lib/models/settings/video_player_settings.g.dart b/lib/models/settings/video_player_settings.g.dart
index c1b169951..5e349a54c 100644
--- a/lib/models/settings/video_player_settings.g.dart
+++ b/lib/models/settings/video_player_settings.g.dart
@@ -54,6 +54,7 @@ _VideoPlayerSettingsModel _$VideoPlayerSettingsModelFromJson(
           json['enableAdvancedVideoOptions'] as bool? ?? false,
       enableEdgeGestures: json['enableEdgeGestures'] as bool? ?? true,
       reverseEdgeGestures: json['reverseEdgeGestures'] as bool? ?? false,
+      enablePictureInPicture: json['enablePictureInPicture'] as bool? ?? true,
     );
 
 Map<String, dynamic> _$VideoPlayerSettingsModelToJson(
@@ -86,6 +87,7 @@ Map<String, dynamic> _$VideoPlayerSettingsModelToJson(
       'enableAdvancedVideoOptions': instance.enableAdvancedVideoOptions,
       'enableEdgeGestures': instance.enableEdgeGestures,
       'reverseEdgeGestures': instance.reverseEdgeGestures,
+      'enablePictureInPicture': instance.enablePictureInPicture,
     };
 
 const _$BoxFitEnumMap = {
diff --git a/lib/providers/pip_provider.dart b/lib/providers/pip_provider.dart
new file mode 100644
index 000000000..0c9c7b855
--- /dev/null
+++ b/lib/providers/pip_provider.dart
@@ -0,0 +1,14 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import 'package:fladder/wrappers/pip_manager.dart';
+
+final pipManagerProvider = Provider<PipManager>((ref) {
+  final manager = PipManager();
+  ref.onDispose(manager.dispose);
+  return manager;
+});
+
+final pipStateProvider = StreamProvider<bool>((ref) {
+  final manager = ref.watch(pipManagerProvider);
+  return manager.isInPip;
+});
diff --git a/lib/providers/settings/video_player_settings_provider.dart b/lib/providers/settings/video_player_settings_provider.dart
index 531d9fc8c..b77f2b0d9 100644
--- a/lib/providers/settings/video_player_settings_provider.dart
+++ b/lib/providers/settings/video_player_settings_provider.dart
@@ -178,4 +178,6 @@ class VideoPlayerSettingsProviderNotifier extends StateNotifier<VideoPlayerSetti
   void setEnableEdgeGestures(bool value) => state = state.copyWith(enableEdgeGestures: value);
 
   void setReverseEdgeGestures(bool value) => state = state.copyWith(reverseEdgeGestures: value);
+
+  void setEnablePictureInPicture(bool value) => state = state.copyWith(enablePictureInPicture: value);
 }
diff --git a/lib/screens/settings/player_settings_page.dart b/lib/screens/settings/player_settings_page.dart
index bbbb627e2..d37089f05 100644
--- a/lib/screens/settings/player_settings_page.dart
+++ b/lib/screens/settings/player_settings_page.dart
@@ -1,3 +1,5 @@
+import 'dart:io';
+
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 
@@ -78,6 +80,16 @@ class _PlayerSettingsPageState extends ConsumerState<PlayerSettingsPage> {
                   ),
                 ],
               ),
+            if (!kIsWeb && (Platform.isAndroid || Platform.isIOS))
+              SettingsListTile(
+                label: Text(context.localized.pictureInPictureAutoTitle),
+                subLabel: Text(context.localized.pictureInPictureSubtitle),
+                onTap: () => provider.setEnablePictureInPicture(!videoSettings.enablePictureInPicture),
+                trailing: Switch(
+                  value: videoSettings.enablePictureInPicture,
+                  onChanged: (value) => provider.setEnablePictureInPicture(value),
+                ),
+              ),
             SettingsListTileEnum(
               label: Text(context.localized.videoScaling),
               current: videoSettings.videoFit.label(context),
diff --git a/lib/screens/video_player/video_player.dart b/lib/screens/video_player/video_player.dart
index 198126900..3f7c419b9 100644
--- a/lib/screens/video_player/video_player.dart
+++ b/lib/screens/video_player/video_player.dart
@@ -1,4 +1,5 @@
 import 'dart:async';
+import 'dart:io';
 
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
@@ -9,6 +10,7 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:fladder/models/media_playback_model.dart';
 import 'package:fladder/models/playback/playback_model.dart';
 import 'package:fladder/models/playback/tv_playback_model.dart';
+import 'package:fladder/providers/pip_provider.dart';
 import 'package:fladder/providers/settings/video_player_settings_provider.dart';
 import 'package:fladder/providers/video_player_provider.dart';
 import 'package:fladder/screens/video_player/components/video_player_guide_wrapper.dart';
@@ -17,6 +19,7 @@ import 'package:fladder/screens/video_player/video_player_controls.dart';
 import 'package:fladder/util/adaptive_layout/adaptive_layout.dart';
 import 'package:fladder/util/themes_data.dart';
 import 'package:fladder/widgets/shared/back_intent_dpad.dart';
+import 'package:fladder/wrappers/pip_manager.dart';
 
 class VideoPlayer extends ConsumerStatefulWidget {
   const VideoPlayer({super.key});
@@ -33,10 +36,14 @@ class _VideoPlayerState extends ConsumerState<VideoPlayer> with WidgetsBindingOb
 
   late PlaybackModel? currentPlaybackModel = ref.read(playBackModel);
 
+  PipManager? _pipManager;
+
   @override
   void didChangeAppLifecycleState(AppLifecycleState state) {
     //Don't pause on desktop focus loss
     if (!(AdaptiveLayout.of(context).isDesktop || kIsWeb)) {
+      // Don't pause when entering PiP — playback must continue.
+      final inPip = ref.read(pipStateProvider).asData?.value ?? false;
       switch (state) {
         case AppLifecycleState.resumed:
           if (playing) ref.read(videoPlayerProvider).play();
@@ -44,7 +51,7 @@ class _VideoPlayerState extends ConsumerState<VideoPlayer> with WidgetsBindingOb
         case AppLifecycleState.hidden:
         case AppLifecycleState.paused:
         case AppLifecycleState.detached:
-          if (playing) ref.read(videoPlayerProvider).pause();
+          if (playing && !inPip) ref.read(videoPlayerProvider).pause();
           break;
         default:
           break;
@@ -56,6 +63,7 @@ class _VideoPlayerState extends ConsumerState<VideoPlayer> with WidgetsBindingOb
   void dispose() {
     WidgetsBinding.instance.removeObserver(this);
     SystemChrome.setPreferredOrientations(DeviceOrientation.values);
+    _pipManager?.disable();
     super.dispose();
   }
 
@@ -70,6 +78,16 @@ class _VideoPlayerState extends ConsumerState<VideoPlayer> with WidgetsBindingOb
           orientations?.isNotEmpty == true ? orientations!.toList() : DeviceOrientation.values);
       return ref.read(videoPlayerSettingsProvider.notifier).setSavedBrightness();
     });
+    Future.microtask(_maybeConfigurePip);
+  }
+
+  void _maybeConfigurePip() {
+    if (kIsWeb) return;
+    if (!(Platform.isAndroid || Platform.isIOS)) return;
+    _pipManager = ref.read(pipManagerProvider);
+    final autoEnter = ref.read(videoPlayerSettingsProvider).enablePictureInPicture;
+    // 16:9 default — PlayerState does not expose real video dimensions.
+    _pipManager?.enable(aspectWidth: 16.0, aspectHeight: 9.0, autoEnter: autoEnter);
   }
 
   @override
@@ -103,6 +121,14 @@ class _VideoPlayerState extends ConsumerState<VideoPlayer> with WidgetsBindingOb
       },
     );
 
+    ref.listen(
+      videoPlayerSettingsProvider.select((value) => value.enablePictureInPicture),
+      (previous, next) {
+        if (previous == next) return;
+        _pipManager?.enable(aspectWidth: 16.0, aspectHeight: 9.0, autoEnter: next);
+      },
+    );
+
     final player = Padding(
       padding: fillScreen ? EdgeInsets.zero : EdgeInsets.only(left: padding.left, right: padding.right),
       child: playerController.videoWidget(
diff --git a/lib/screens/video_player/video_player_controls.dart b/lib/screens/video_player/video_player_controls.dart
index eb194fea5..df39db415 100644
--- a/lib/screens/video_player/video_player_controls.dart
+++ b/lib/screens/video_player/video_player_controls.dart
@@ -1,4 +1,5 @@
 import 'dart:async';
+import 'dart:io';
 
 import 'package:flutter/foundation.dart';
 import 'package:flutter/gestures.dart';
@@ -15,6 +16,7 @@ import 'package:fladder/models/items/media_segments_model.dart';
 import 'package:fladder/models/media_playback_model.dart';
 import 'package:fladder/models/playback/playback_model.dart';
 import 'package:fladder/models/settings/video_player_settings.dart';
+import 'package:fladder/providers/pip_provider.dart';
 import 'package:fladder/providers/settings/client_settings_provider.dart';
 import 'package:fladder/providers/settings/video_player_settings_provider.dart';
 import 'package:fladder/providers/user_provider.dart';
@@ -92,8 +94,18 @@ class _DesktopControlsState extends ConsumerState<DesktopControls> {
 
   @override
   Widget build(BuildContext context) {
-    final mediaSegments = ref.watch(playBackModel.select((value) => value?.mediaSegments));
+    final isInPip = ref.watch(pipStateProvider).asData?.value ?? false;
     final player = ref.watch(videoPlayerProvider);
+    if (isInPip) {
+      // Keep only the subtitle widget so it's captured in the PiP frame.
+      final pipSubtitleWidget = player.subtitleWidget(false, controlsKey: _bottomControlsKey);
+      return Stack(
+        children: [
+          if (pipSubtitleWidget != null) Positioned.fill(child: pipSubtitleWidget),
+        ],
+      );
+    }
+    final mediaSegments = ref.watch(playBackModel.select((value) => value?.mediaSegments));
     final subtitleWidget = player.subtitleWidget(showOverlay, controlsKey: _bottomControlsKey);
     final isDesktop = AdaptiveLayout.of(context).isDesktop || kIsWeb;
     final speedBoostEnabled = ref.watch(videoPlayerSettingsProvider.select((value) => value.enableSpeedBoost));
@@ -345,6 +357,21 @@ class _DesktopControlsState extends ConsumerState<DesktopControls> {
                         IconButton(
                             onPressed: () => showVideoPlayerOptions(context, () => minimizePlayer(context)),
                             icon: const Icon(IconsaxPlusLinear.more)),
+                        if (!kIsWeb &&
+                            (Platform.isAndroid || Platform.isIOS) &&
+                            MediaQuery.orientationOf(context) == Orientation.landscape)
+                          IconButton(
+                            tooltip: context.localized.pictureInPictureTitle,
+                            onPressed: () async {
+                              final ok = await ref.read(pipManagerProvider).enter();
+                              if (!ok && context.mounted) {
+                                ScaffoldMessenger.of(context).showSnackBar(
+                                  SnackBar(content: Text(context.localized.pictureInPictureNotSupported)),
+                                );
+                              }
+                            },
+                            icon: const Icon(Icons.picture_in_picture_alt_outlined),
+                          ),
                         if (AdaptiveLayout.layoutOf(context) == ViewSize.tablet) ...[
                           IconButton(
                             onPressed: () => showSubSelection(context),
diff --git a/lib/wrappers/pip_manager.dart b/lib/wrappers/pip_manager.dart
new file mode 100644
index 000000000..3982cb266
--- /dev/null
+++ b/lib/wrappers/pip_manager.dart
@@ -0,0 +1,148 @@
+import 'dart:async';
+import 'dart:io';
+
+import 'package:flutter/foundation.dart';
+import 'package:pip/pip.dart';
+
+bool _platformSupportsPip() {
+  if (kIsWeb) return false;
+  return Platform.isAndroid || Platform.isIOS;
+}
+
+abstract class PipClient {
+  Future<bool> isSupported();
+  Future<bool> isAutoEnterSupported();
+  Future<void> setup({
+    required double aspectWidth,
+    required double aspectHeight,
+    required bool autoEnterEnabled,
+  });
+
+  // stop() only exits an active session; this re-runs setup with auto-enter off.
+  Future<void> disableAutoEnter();
+  Future<bool> start();
+  Future<void> stop();
+  void registerStateChangedObserver(void Function(bool isInPip) observer);
+  Future<void> dispose();
+}
+
+class _RealPipClient implements PipClient {
+  _RealPipClient() : _pip = Pip();
+
+  final Pip _pip;
+  bool _observerRegistered = false;
+
+  @override
+  Future<bool> isSupported() async {
+    if (!_platformSupportsPip()) return false;
+    return _pip.isSupported();
+  }
+
+  @override
+  Future<bool> isAutoEnterSupported() => _pip.isAutoEnterSupported();
+
+  @override
+  Future<void> setup({
+    required double aspectWidth,
+    required double aspectHeight,
+    required bool autoEnterEnabled,
+  }) async {
+    await _pip.setup(PipOptions(
+      autoEnterEnabled: autoEnterEnabled,
+      aspectRatioX: aspectWidth.toInt(),
+      aspectRatioY: aspectHeight.toInt(),
+    ));
+  }
+
+  @override
+  Future<void> disableAutoEnter() async {
+    await _pip.setup(const PipOptions(autoEnterEnabled: false));
+  }
+
+  @override
+  Future<bool> start() => _pip.start();
+
+  @override
+  Future<void> stop() => _pip.stop();
+
+  @override
+  void registerStateChangedObserver(void Function(bool isInPip) observer) {
+    final wrapped = PipStateChangedObserver(
+      onPipStateChanged: (state, error) {
+        observer(state == PipState.pipStateStarted);
+      },
+    );
+    _pip.registerStateChangedObserver(wrapped);
+    _observerRegistered = true;
+  }
+
+  @override
+  Future<void> dispose() async {
+    if (_observerRegistered) {
+      await _pip.unregisterStateChangedObserver();
+      _observerRegistered = false;
+    }
+    await _pip.dispose();
+  }
+}
+
+// Only file that imports `package:pip` — everything else depends on PipManager.
+class PipManager {
+  PipManager({PipClient? client}) : _client = client ?? _RealPipClient() {
+    _client.registerStateChangedObserver(_onStateChanged);
+  }
+
+  final PipClient _client;
+  final StreamController<bool> _stateController = StreamController<bool>.broadcast();
+
+  bool _supportCached = false;
+  bool _supportChecked = false;
+
+  Stream<bool> get isInPip => _stateController.stream;
+
+  // Always sets up aspect so manual enter() works; autoEnter gates the
+  // OS auto-enter-on-background behavior independently.
+  Future<bool> enable({
+    required double aspectWidth,
+    required double aspectHeight,
+    required bool autoEnter,
+  }) async {
+    if (!await _ensureSupported()) return false;
+    final autoEnterAllowed = autoEnter && await _client.isAutoEnterSupported();
+    await _client.setup(
+      aspectWidth: aspectWidth,
+      aspectHeight: aspectHeight,
+      autoEnterEnabled: autoEnterAllowed,
+    );
+    return true;
+  }
+
+  Future<void> disable() async {
+    if (!await _ensureSupported()) return;
+    await _client.disableAutoEnter();
+    await _client.stop();
+  }
+
+  Future<bool> enter() async {
+    if (!await _ensureSupported()) return false;
+    return _client.start();
+  }
+
+  Future<void> dispose() async {
+    await _client.dispose();
+    await _stateController.close();
+  }
+
+  Future<bool> _ensureSupported() async {
+    if (_supportChecked) return _supportCached;
+    _supportCached = await _client.isSupported();
+    _supportChecked = true;
+    return _supportCached;
+  }
+
+  void _onStateChanged(bool isInPip) {
+    if (!_stateController.isClosed) {
+      _stateController.add(isInPip);
+    }
+  }
+}
diff --git a/pubspec.lock b/pubspec.lock
index 13b25db37..a9134c1f8 100644
--- a/pubspec.lock
+++ b/pubspec.lock
@@ -1557,6 +1557,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "26.1.0"
+  pip:
+    dependency: "direct main"
+    description:
+      name: pip
+      sha256: f3c0890458a1e7ea3597fd2432841fb82565d66e4aa5b4931326a2ec052b3505
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.0.3"
   platform:
     dependency: transitive
     description:
diff --git a/pubspec.yaml b/pubspec.yaml
index 4b964a8f9..14bf8ecab 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -72,6 +72,7 @@ dependencies:
   audio_service: ^0.18.18
   audio_service_mpris: ^0.2.0
   fvp: ^0.35.0
+  pip: ^0.0.3
   video_player: ^2.10.0
 
   image: ^4.5.4 # For saving screenshots.
diff --git a/test/pip_manager_test.dart b/test/pip_manager_test.dart
new file mode 100644
index 000000000..24c735d83
--- /dev/null
+++ b/test/pip_manager_test.dart
@@ -0,0 +1,170 @@
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:fladder/wrappers/pip_manager.dart';
+
+class _FakePipClient implements PipClient {
+  bool supported = true;
+  bool autoEnterSupported = true;
+  bool startResult = true;
+
+  final List<PipOptionsSnapshot> setupCalls = [];
+  int startCount = 0;
+  int stopCount = 0;
+  int disableAutoEnterCount = 0;
+  int disposeCount = 0;
+  void Function(bool isInPip)? _observer;
+
+  void emitState(bool isInPip) => _observer?.call(isInPip);
+
+  @override
+  Future<bool> isSupported() async => supported;
+
+  @override
+  Future<bool> isAutoEnterSupported() async => autoEnterSupported;
+
+  @override
+  Future<void> setup({
+    required double aspectWidth,
+    required double aspectHeight,
+    required bool autoEnterEnabled,
+  }) async {
+    setupCalls.add(PipOptionsSnapshot(aspectWidth, aspectHeight, autoEnterEnabled));
+  }
+
+  @override
+  Future<bool> start() async {
+    startCount++;
+    return startResult;
+  }
+
+  @override
+  Future<void> stop() async {
+    stopCount++;
+  }
+
+  @override
+  Future<void> disableAutoEnter() async {
+    disableAutoEnterCount++;
+  }
+
+  @override
+  void registerStateChangedObserver(void Function(bool isInPip) observer) {
+    _observer = observer;
+  }
+
+  @override
+  Future<void> dispose() async {
+    disposeCount++;
+  }
+}
+
+class PipOptionsSnapshot {
+  PipOptionsSnapshot(this.width, this.height, this.autoEnter);
+  final double width;
+  final double height;
+  final bool autoEnter;
+}
+
+void main() {
+  group('PipManager', () {
+    test('enable calls setup with aspect ratio and propagates autoEnter=true', () async {
+      final fake = _FakePipClient();
+      final manager = PipManager(client: fake);
+
+      await manager.enable(aspectWidth: 1920, aspectHeight: 1080, autoEnter: true);
+
+      expect(fake.setupCalls, hasLength(1));
+      expect(fake.setupCalls.single.width, 1920);
+      expect(fake.setupCalls.single.height, 1080);
+      expect(fake.setupCalls.single.autoEnter, isTrue);
+    });
+
+    test('enable with autoEnter=false still sets up aspect but disables auto-enter', () async {
+      final fake = _FakePipClient();
+      final manager = PipManager(client: fake);
+
+      await manager.enable(aspectWidth: 16, aspectHeight: 9, autoEnter: false);
+
+      expect(fake.setupCalls, hasLength(1));
+      expect(fake.setupCalls.single.autoEnter, isFalse);
+    });
+
+    test('enable forces autoEnter=false when client reports auto-enter unsupported', () async {
+      final fake = _FakePipClient()..autoEnterSupported = false;
+      final manager = PipManager(client: fake);
+
+      await manager.enable(aspectWidth: 16, aspectHeight: 9, autoEnter: true);
+
+      expect(fake.setupCalls.single.autoEnter, isFalse);
+    });
+
+    test('enable returns false when isSupported is false and skips setup', () async {
+      final fake = _FakePipClient()..supported = false;
+      final manager = PipManager(client: fake);
+
+      final result = await manager.enable(aspectWidth: 16, aspectHeight: 9, autoEnter: true);
+
+      expect(result, isFalse);
+      expect(fake.setupCalls, isEmpty);
+    });
+
+    test('enter calls start and returns its result', () async {
+      final fake = _FakePipClient();
+      final manager = PipManager(client: fake);
+
+      final ok = await manager.enter();
+
+      expect(ok, isTrue);
+      expect(fake.startCount, 1);
+    });
+
+    test('enter returns false when isSupported is false', () async {
+      final fake = _FakePipClient()..supported = false;
+      final manager = PipManager(client: fake);
+
+      final ok = await manager.enter();
+
+      expect(ok, isFalse);
+      expect(fake.startCount, 0);
+    });
+
+    test('disable turns off auto-enter and stops any active PiP', () async {
+      final fake = _FakePipClient();
+      final manager = PipManager(client: fake);
+
+      await manager.disable();
+
+      expect(fake.disableAutoEnterCount, 1);
+      expect(fake.stopCount, 1);
+    });
+
+    test('isInPip stream emits values from the observer', () async {
+      final fake = _FakePipClient();
+      final manager = PipManager(client: fake);
+      final emitted = <bool>[];
+      final sub = manager.isInPip.listen(emitted.add);
+
+      fake.emitState(true);
+      fake.emitState(false);
+      await Future<void>.delayed(Duration.zero);
+
+      expect(emitted, [true, false]);
+      await sub.cancel();
+      await manager.dispose();
+    });
+
+    test('dispose closes the stream and calls client.dispose', () async {
+      final fake = _FakePipClient();
+      final manager = PipManager(client: fake);
+
+      await manager.dispose();
+
+      expect(fake.disposeCount, 1);
+      final emitted = <bool>[];
+      final sub = manager.isInPip.listen(emitted.add);
+      await Future<void>.delayed(Duration.zero);
+      expect(emitted, isEmpty);
+      await sub.cancel();
+    });
+  });
+}