Polyv Flutter Media Player - 專案文件

基於 保利威 iOS 點播播放器 SDK 封裝的 Flutter 影片播放器插件，支援 iOS 和 Android 雙平台。

目錄

• 專案概述
• 架構設計
• 功能特性
• 專案結構
• 快速整合
• API 參考
• UI 元件
• 平台原生層
• 業務服務模組
• Demo 應用
• 開發指南
• 常見問題

專案概述

polyv-flutter-media-player-demo 是一個 Flutter Plugin 專案，將保利威原生播放器 SDK（iOS PolyvMediaPlayerSDK、Android media-player-full）封裝為統一的 Dart API，供 Flutter 應用跨平台呼叫。

專案分為兩層：

技術棧

底層 SDK 參考

本插件封裝的保利威原生 SDK 文件：

• iOS 點播 SDK 文件: https://help.polyv.net/index.html#/vod/ios_player_sdk/
• iOS SDK Demo: https://github.com/polyv/polyv-ios-vod-sdk
• Android SDK: 透過阿里雲私有 Maven 倉庫分發
• 開發者中心: https://www.polyv.net/dev/

架構設計

┌─────────────────────────────────────────────────────────┐
│                    Demo App (example/)                    │
│  ┌──────────┐ ┌──────────────┐ ┌────────────────────┐   │
│  │ HomePage │ │ LongVideoPage│ │ DownloadCenterPage │   │
│  └──────────┘ └──────────────┘ └────────────────────┘   │
└────────────────────────┬────────────────────────────────┘
                         │ 依赖
┌────────────────────────▼────────────────────────────────┐
│                Plugin (polyv_media_player/)               │
│                                                          │
│  ┌─────────────────────────────────────────────────┐     │
│  │  Widgets Layer                                   │     │
│  │  PolyvVideoPlayer · PolyvVideoView               │     │
│  └───────────────────┬─────────────────────────────┘     │
│                      │                                    │
│  ┌───────────────────▼─────────────────────────────┐     │
│  │  UI Components                                   │     │
│  │  ControlBar · ProgressSlider · QualitySelector   │     │
│  │  SpeedSelector · Danmaku · Gestures · Settings   │     │
│  └───────────────────┬─────────────────────────────┘     │
│                      │                                    │
│  ┌───────────────────▼─────────────────────────────┐     │
│  │  Core Layer                                      │     │
│  │  PlayerController · PlayerState · PlayerEvents   │     │
│  └───────────────────┬─────────────────────────────┘     │
│                      │                                    │
│  ┌───────────────────▼─────────────────────────────┐     │
│  │  Platform Channel                                │     │
│  │  MethodChannel · EventChannel · PlayerAPI        │     │
│  └───────────────────┬─────────────────────────────┘     │
│                      │                                    │
│  ┌───────────────────▼─────────────────────────────┐     │
│  │  Infrastructure (共享业务服务)                     │     │
│  │  DanmakuService · VideoListService · Download     │     │
│  └─────────────────────────────────────────────────┘     │
└──────────────────────────────────────────────────────────┘
                         │ Platform Channel
            ┌────────────┴────────────┐
            ▼                         ▼
   ┌────────────────┐      ┌────────────────┐
   │  iOS Native    │      │ Android Native  │
   │  (Objective-C) │      │   (Kotlin)      │
   │                │      │                 │
   │ PolyvMedia     │      │ PolyvMedia      │
   │ PlayerSDK      │      │ PlayerSDK       │
   └────────────────┘      └────────────────┘

核心設計原則

1. Plugin 只提供核心能力：播放控制、狀態管理、Platform Channel 封裝
2. 業務邏輯在 Dart 層統一實作：不在原生層呼叫 Polyv 業務 HTTP 介面
3. 原生層只封裝播放器 SDK：暴露底層能力（播放、下載、字幕等），不包含業務決策
4. 清晰度切換進度恢復：由原生層負責（Dart 層僅觸發切換、消費事件）

功能特性

播放核心

影片下載

彈幕系統

互動體驗

專案結構

polyv-flutter-media-player-demo/          # Git 仓库根目录
├── polyv_media_player/                   # Flutter Plugin 插件
│   ├── lib/
│   │   ├── polyv_media_player.dart       # 主入口（导出所有公共 API）
│   │   ├── core/                         # 核心层
│   │   │   ├── player_controller.dart    # 播放器控制器（ChangeNotifier）
│   │   │   ├── player_state.dart         # 播放器状态模型
│   │   │   ├── player_events.dart        # 事件类型定义
│   │   │   ├── player_event_parser.dart  # 原生事件解析器
│   │   │   ├── player_exception.dart     # 异常类
│   │   │   ├── player_config.dart        # 配置类
│   │   │   ├── subtitle_selection_policy.dart  # 字幕自动选择策略
│   │   │   ├── offline_playback_decider.dart   # 离线播放决策
│   │   │   └── system_locale_provider.dart     # 系统语言检测
│   │   ├── platform_channel/             # Platform Channel 封装
│   │   │   ├── player_api.dart           # Channel 名称 + 方法常量
│   │   │   ├── method_channel_handler.dart  # MethodChannel 处理
│   │   │   └── event_channel_handler.dart   # EventChannel 处理
│   │   ├── services/                     # 服务层
│   │   │   ├── polyv_config_service.dart # 账号配置管理
│   │   │   ├── player_initializer.dart   # 播放器初始化
│   │   │   ├── video_progress_service.dart  # 播放进度记忆
│   │   │   └── subtitle_preference_service.dart  # 字幕偏好
│   │   ├── infrastructure/               # 基础设施（共享业务服务）
│   │   │   ├── danmaku/                  # 弹幕系统
│   │   │   │   ├── danmaku_model.dart    # 弹幕数据模型
│   │   │   │   └── danmaku_service.dart  # 弹幕服务接口 + 实现
│   │   │   ├── download/                 # 下载管理
│   │   │   │   ├── download_task.dart    # 下载任务模型
│   │   │   │   ├── download_task_status.dart  # 下载状态枚举
│   │   │   │   ├── download_state_manager.dart  # 下载状态管理
│   │   │   │   ├── download_event_handler.dart  # 下载事件处理
│   │   │   │   └── download_native_repository.dart  # 原生下载能力封装
│   │   │   ├── video_list/               # 视频列表
│   │   │   │   ├── video_list_models.dart  # 视频列表数据模型
│   │   │   │   ├── video_list_service.dart  # 视频列表服务
│   │   │   │   └── video_list_api_client.dart  # API 客户端
│   │   │   └── polyv_api_client.dart     # Polyv API 通用客户端
│   │   ├── widgets/                      # Widget 层
│   │   │   ├── polyv_video_player.dart   # 全功能播放器 Widget
│   │   │   └── polyv_video_view.dart     # 原生视频视图（PlatformView）
│   │   ├── ui/                           # 内置 UI 组件
│   │   │   ├── control_bar.dart          # 控制栏
│   │   │   ├── control_bar_state_machine.dart  # 控制栏状态机
│   │   │   ├── player_colors.dart        # 播放器颜色常量
│   │   │   ├── double_tap_detector.dart  # 双击检测
│   │   │   ├── progress_slider/          # 进度条组件
│   │   │   ├── quality_selector/         # 清晰度选择器
│   │   │   ├── speed_selector/           # 倍速选择器
│   │   │   ├── subtitle_toggle.dart      # 字幕开关
│   │   │   ├── danmaku/                  # 弹幕 UI 组件
│   │   │   │   ├── danmaku_layer.dart    # 弹幕渲染层
│   │   │   │   ├── danmaku_toggle.dart   # 弹幕开关
│   │   │   │   ├── danmaku_input_overlay.dart  # 弹幕输入浮层
│   │   │   │   └── danmaku_settings.dart # 弹幕设置面板
│   │   │   ├── gestures/                 # 手势系统
│   │   │   │   ├── player_gesture_controller.dart
│   │   │   │   ├── player_gesture_detector.dart
│   │   │   │   └── seek_preview_overlay.dart
│   │   │   └── settings_menu/            # 设置菜单
│   │   └── utils/                        # 工具类
│   │       └── plv_logger.dart           # 日志工具
│   ├── ios/                              # iOS 原生代码
│   │   ├── Classes/
│   │   │   ├── PolyvMediaPlayerPlugin.m  # 插件入口
│   │   │   ├── PLVFlutterMethodRouter.m  # Method 路由分发
│   │   │   ├── PLVFlutterPlayerSession.m # 播放器会话管理
│   │   │   ├── PLVFlutterEventEmitter.m  # 事件发射器
│   │   │   ├── PLVFlutterDownloadMonitor.m # 下载监控
│   │   │   ├── PLVFlutterSubtitleCoordinator.m  # 字幕协调
│   │   │   ├── PLVVideoViewFactory.m     # PlatformView 工厂
│   │   │   └── ...字幕解析相关文件
│   │   └── polyv_media_player.podspec    # CocoaPods 配置
│   ├── android/                          # Android 原生代码
│   │   └── src/main/kotlin/
│   │       ├── PolyvMediaPlayerPlugin.kt # 插件入口
│   │       ├── MethodRouter.kt           # Method 路由
│   │       ├── PlayerCoordinator.kt      # 播放协调
│   │       ├── DownloadCoordinator.kt    # 下载协调
│   │       ├── SubtitleCoordinator.kt    # 字幕协调
│   │       ├── PlaybackEventEmitter.kt   # 播放事件发射
│   │       ├── DownloadEventEmitter.kt   # 下载事件发射
│   │       └── PolyvVideoViewFactory.kt  # PlatformView 工厂
│   └── test/                             # 单元测试
├── example/                              # Demo App
│   ├── lib/
│   │   ├── main.dart                     # 应用入口
│   │   ├── config/
│   │   │   └── app_config.dart           # 账号配置（环境变量注入）
│   │   ├── pages/
│   │   │   ├── home_page.dart            # 首页（长视频/下载中心入口）
│   │   │   ├── long_video_page.dart      # 长视频播放页
│   │   │   └── download_center/          # 下载中心
│   │   │       ├── download_center_page.dart
│   │   │       └── downloading_task_item.dart
│   │   └── player_skin/
│   │       └── video_list/               # 视频列表组件
│   └── pubspec.yaml
└── docs/                                 # 项目文档

快速整合

環境要求

步驟 1: 新增依賴

將 polyv_media_player 目錄複製到專案中（與 lib/ 平級），然後在 pubspec.yaml 中新增：

dependencies:
  polyv_media_player:
    path: polyv_media_player

執行：

flutter pub get

步驟 2: iOS 設定

在 iOS 專案的 Podfile 中確保平台版本 >= 13.0：

platform :ios, '13.0'

然後執行：

cd ios && pod install

插件會自動透過 CocoaPods 引入以下依賴：

PolyvMediaPlayerSDK (~> 2.7.2)
PLVFoundationSDK/AbstractBase (~> 1.30.2)
PLVFDB (~> 1.0.5)
PLVLOpenSSL (~> 1.1.12101)
SSZipArchive (~> 2.0)

步驟 3: 初始化 SDK

在 main.dart 中初始化保利威帳號設定：

import 'package:flutter/material.dart';
import 'package:polyv_media_player/polyv_media_player.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await PolyvMediaPlayer.initialize(
    userId: 'your_user_id',
    secretKey: 'your_secret_key',
    readToken: 'your_read_token',   // 可选
    writeToken: 'your_write_token', // 可选
  );

  runApp(const MyApp());
}

帳號設定資訊可在 保利威後台 註冊後取得。

步驟 4: 使用播放器

最簡用法，一行程式碼即可播放影片：

PolyvVideoPlayer(
  vid: 'your_video_id',
  autoPlay: true,
)

API 參考

SDK 初始化

await PolyvMediaPlayer.initialize(
  userId: String,     // 必填：保利威用户 ID
  secretKey: String,  // 必填：密钥
  readToken: String?, // 可选：读取 Token
  writeToken: String?,// 可选：写入 Token
);

// 检查是否已初始化
bool initialized = PolyvMediaPlayer.isInitialized;

// 获取用户 ID
String userId = await PolyvMediaPlayer.userId;

PlayerController

PlayerController 是播放器的核心控制類別，繼承自 ChangeNotifier，透過 Provider 模式驅動 UI 更新。

播放控制

設定

狀態

生命週期

PlayerState

class PlayerState {
  PlayerLoadingState loadingState;  // idle/loading/prepared/playing/paused/buffering/completed/error
  int position;           // 当前位置（毫秒）
  int duration;           // 总时长（毫秒）
  int bufferedPosition;   // 缓冲位置（毫秒）
  double playbackSpeed;   // 播放速度
  String? errorMessage;   // 错误信息
  String? vid;            // 当前视频 VID
  bool subtitleEnabled;   // 字幕是否开启
  String? currentSubtitleId;  // 当前字幕 ID
  List<SubtitleItem> availableSubtitles;  // 可用字幕列表
}

事件類型

Platform Channel 常數

MethodChannel: com.polyv.media_player/player
EventChannel:  com.polyv.media_player/events
DownloadEvent: com.polyv.media_player/download_events

PolyvVideoPlayer Widget

UI 元件

插件內建了完整的播放器 UI 元件庫，可獨立使用或組合使用。

可用元件

自訂 UI 範例

使用底層元件組裝自訂播放器：

class CustomVideoPage extends StatefulWidget {
  @override
  State<CustomVideoPage> createState() => _CustomVideoPageState();
}

class _CustomVideoPageState extends State<CustomVideoPage> {
  late final PlayerController _controller;

  @override
  void initState() {
    super.initState();
    _controller = PlayerController();
    _controller.loadVideo('your_video_id');
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.black,
      body: Stack(
        children: [
          // 原生视频视图
          const PolyvVideoView(),
          // 自定义控制栏
          Align(
            alignment: Alignment.bottomCenter,
            child: ControlBar(controller: _controller),
          ),
        ],
      ),
    );
  }
}

平台原生層

iOS 原生架構

iOS 原生程式碼採用模組化拆分，每個元件職責單一：

iOS 依賴（透過 CocoaPods）

s.dependency 'PolyvMediaPlayerSDK', '~> 2.7.2'
s.dependency 'PLVFoundationSDK/AbstractBase', '~> 1.30.2'
s.dependency 'PLVFDB', '~> 1.0.5'
s.dependency 'PLVLOpenSSL', '~> 1.1.12101'
s.dependency 'SSZipArchive', '~> 2.0'
s.platform = :ios, '13.0'

Android 原生架構

Android 依賴

implementation("net.polyv.android:media-player-full:2.7.2")
implementation("net.polyv.android:media-player-sdk-addon-business:2.7.2")
implementation("net.polyv.android:media-player-sdk-addon-download:2.7.2")

業務服務模組

插件在 __PLV_K