画中画（Picture-in-Picture, PiP）是一种多窗口模式，允许用户在屏幕一角的小窗口中观看视频，同时在主屏幕上继续与其他应用或内容进行交互。播放器 SDK 支持以下两种画中画实现模式，以适应不同的业务场景：

• 手动模式：​由用户主动触发。通常是在播放器界面提供一个“画中画”或“小窗播放”按钮，用户点击后，视频窗口会缩小并悬浮。开发者需要在用户点击按钮时，调用 SDK 提供的 API 来开启画中画。
• 自动模式：由系统事件触发。当视频正在播放时，如果用户将应用切换到后台（例如按 Home 键返回桌面），视频会自动进入画中画模式继续播放，而不会中断。开发者需要先调用 SDK 提供的 API 开启自动画中画模式，并结合监听应用的生命周期事件来实现。

前提条件 #

在集成画中画功能前，请确保您的项目满足对应平台的前提条件。

Android #

系统权限：画中画功能需要获取“显示在其他应用上层”（即悬浮窗）的系统权限。

• 如果您在应用未获授权时调用 startPictureInPicture 接口，SDK 会自动跳转至系统授权页面。当用户授权并返回应用后，SDK 会再次尝试开启画中画。
• 此外，您也可以调用 requestOverlayPermission 接口，主动引导用户进行授权。

iOS #

• 项目配置：在 Xcode 项目中，您必须开启 Audio, AirPlay, and Picture in Picture 后台模式。参考步骤如下：
  1. 在 Xcode 项目中选择 App 的 Target。
  2. 单击 Signing & Capabilities 页签。
  3. 单击 + Capability 按钮添加 Background Modes 功能，勾选 Audio, AirPlay, and Picture in Picture。
     
• 系统要求：
  • 设备系统版本：iOS 15 及以上版本
  • 系统画中画设置：请确保用户已在设备的设置 > 通用 > 画中画页面中，开启了自动开启画中画开关。
    

权限申请（仅 Android） #

为了提供更好的用户体验，建议您在用户点击画中画按钮前，通过一个引导流程主动申请悬浮窗权限，而不是在用户点击后被动触发。

// 调用后会跳转到系统设置页面引导用户进行手动授权
await VodPlayerFlutter.requestOverlayPermission();

手动开启画中画 #

手动开启画中画，通常与界面上的一个按钮绑定。

// 1. 检查设备是否支持
bool isSupported = await player.isPictureInPictureSupported();
if (!isSupported) {
  // 不支持画中画，可以弹窗提示或禁用按钮
  print("当前设备不支持画中画");
  return;
}

// 2. 开启画中画 (可在按钮点击事件中调用)
// 仅在视频播放时才能成功开启
bool success = await player.startPictureInPicture();
if (!success) {
  print("开启画中画失败");
}

// 3. 停止画中画 (可在返回 App 或其他交互中调用)
await player.stopPictureInPicture();

开启自动画中画 #

自动画中画是指应用从前台运行状态切换到后台运行状态后（例如用户返回桌面或切换到其他应用），系统自动将该视频播放窗口缩小为悬浮的画中画窗口，而无需用户手动开启。

步骤 1：开启 SDK 的自动画中画模式（通用） #

您需要监听播放器的 playbackStateDidChange 事件，在第一次播放开始后调用 enableAutoBackgroundPictureInPicture 方法开启自动画中画模式。

player.playbackStateDidChange = (TTVideoEnginePlaybackState playbackState) {
  switch (playbackState) {
    case TTVideoEnginePlaybackState.playing:
      // 假设 enablePIPBackgroundAuto 是您应用中用于控制此功能的全局开关
      if (enablePIPBackgroundAuto) {
        // 关键：在播放开始后调用，通知 SDK 开启自动画中画模式
        player.enableAutoBackgroundPictureInPicture(true);
      }
      break;
    default:
      break;
  }
};

步骤 2：监听 App 生命周期并手动触发（仅 Android） #

与 iOS 不同，Android 平台需要在 App 进入后台时手动调用 startPictureInPicture。这需要您在播放页面监听 Flutter 的 App 生命周期事件。

@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  super.didChangeAppLifecycleState(state);
  if (!mounted) return;
  if (state == AppLifecycleState.resumed) {
    if (GlobalConfiguration.enablePIPBackgroundAuto) {
      _player.stopPictureInPicture();
    }
  } else if (state == AppLifecycleState.paused) {
    if (GlobalConfiguration.enablePIPBackgroundAuto && Platform.isAndroid) {
      // 当 App 进入后台时，手动调用 startPictureInPicture
      _player.startPictureInPicture();
    }
  }
}