Flutter音视频播放插件byteark_player_flutter的使用

Flutter音视频播放插件byteark_player_flutter的使用

ByteArk Player插件是一个为无缝集成到Flutter应用而设计的强大且灵活的视频播放包。该插件提供了流畅的视频播放体验，支持各种媒体格式，并且高度可定制以满足您的应用需求。无论您正在开发媒体应用、教育平台还是任何需要视频播放功能的项目，ByteArk Player都能让这一切变得简单。

免责声明

这是ByteArk Player的非商业版本。商业用途和/或商业支持需要许可证。如有需要，请联系 sales@byteark.com 获取更多关于我们解决方案的信息。

安装

使用此包将ByteArk Player插件集成到您的项目中。请遵循以下针对Flutter、Android和iOS平台的说明。

Flutter集成

添加依赖

1. 在终端运行以下命令以添加ByteArk Player插件到您的项目：

   $ flutter pub add byteark_player_flutter
   

   这条命令会自动更新您的pubspec.yaml文件以包含ByteArk Player包，并运行flutter pub get命令。

   或者，您也可以手动在pubspec.yaml文件的dependencies下添加以下行：

   dependencies:
     byteark_player: ^1.0.6 // 请替换为最新版本的插件。
   

   如果您手动编辑了pubspec.yaml文件，可以运行以下命令来获取新的依赖项：

   $ flutter pub get
   

导入并使用ByteArk Player小部件

1. 现在，您可以在Dart代码中导入并开始使用ByteArk Player插件：

   import 'package:byteark_player_flutter/presentation/byteark_player.dart';
   .
   .
   ByteArkPlayer(playerConfig: playerConfig)
   

iOS配置

要使用CocoaPods将ByteArk Player集成到您的Flutter iOS项目中，请按以下步骤操作：

1. 如果您尚未为GitHub帐户设置SSH密钥，请先按照Github网站上的文档添加一个新的SSH密钥（文档链接已去掉）。

2. 打开Podfile

   1. 导航到您的iOS项目目录并打开Podfile，然后在文件中添加以下代码：

      // 设置平台为iOS 14
      platform :ios, '14.0'
      .
      .
      .
      // 指定CocoaPods应从中获取所需依赖项的源：
      source 'https://github.com/CocoaPods/Specs.git'
      source 'https://github.com/byteark/byteark-player-sdk-ios-specs.git'
      source 'https://github.com/byteark/lighthouse-sdk-native-ios-specs.git'
      

3. 安装Pods

   1. 打开终端窗口并导航到您的Flutter项目的ios目录，运行以下命令以安装CocoaPods依赖项并更新仓库：

      pod install --repo-update
      

4. 打开工作区

   1. 运行pod install --repo-update后，CocoaPods将创建一个Xcode工作区文件（.xcworkspace），请在Xcode中打开此工作区。

5. 构建并运行

   1. 在进行上述更改后，请构建并运行您的项目到iOS模拟器或物理设备上以验证集成。

Android配置

要将ByteArk Player集成到您的Flutter Android项目中，请按以下步骤操作：

1. 修改AndroidManifest.xml

   1. 导航到android/app/src/main/AndroidManifest.xml并进行以下更改：
      1. 添加所需的权限以允许网络访问、前台服务和启动接收。在<manifest>内添加以下行：

         <uses-permission android:name="android.permission.INTERNET"/>
         <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
         <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
         <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
         

      2. 使用@style/Theme.AppCompat属性设置android:resource以使用<activity>内的主题。这允许您应用与FlutterFragmentActivity兼容的主题，例如@style/Theme.AppCompat或其他基于AppCompat或MaterialComponents的主题。

         <meta-data
                android:name="io.flutter.embedding.android.NormalTheme"
                android:resource="@style/Theme.AppCompat"/>
         

      3. 在<application>内添加ByteArk Player服务以启用媒体浏览和服务功能：

         <!-- ByteArk -->
         <service android:name="com.byteark.bytearkplayercore.handler.exoplayer.service.ByteArkPlayerService"
               android:enabled="true"
               android:exported="true">
               <intent-filter>
                    <action android:name="androidx.media3.session.MediaLibraryService"/>
                    <action android:name="android.media.browse.MediaBrowserService" />
               </intent-filter>
         </service>
         

      4. 在<application>内添加Nielsen以启用Nielsen服务功能：

         <!--Nielsen-->
         <meta-data
               android:name="com.google.android.gms.ads.APPLICATION_ID"
               android:value="ca-app-pub-3940256099942544~3347511713"/>
         

2. 更新主活动

   1. 导航到android/app/src/main/kotlin/com/example/your_project_name/MainActivity.kt并更新主活动：
      1. 继承FlutterFragmentActivity()以确保正确的集成：

         import io.flutter.embedding.android.FlutterFragmentActivity
         
         class MainActivity: FlutterFragmentActivity()
         

3. 配置本地属性

   1. 在android/local.properties文件中，设置ByteArk Player和ByteArk LightHouse的GitLab私有令牌。
   2. 添加以下行，用您从ByteArk团队获得的令牌替换[YOUR_PRIVATE_TOKEN]：

      gitLabByteArkPlayerPrivateToken=[YOUR_PRIVATE_TOKEN]
      gitLabByteArkLighthousePrivateToken=[YOUR_PRIVATE_TOKEN]
      

4. 构建并运行

   1. 在进行上述更改后，请构建并运行您的项目到Android模拟器或物理设备上以验证集成。

使用

以下是使用ByteArk Player小部件在Flutter应用中播放视频的基本示例：

import 'package:byteark_player_flutter/data/byteark_player_license_key.dart';
import 'package:byteark_player_flutter/domain/method_channel/byteark_player_controller.dart';
import 'package:flutter/material.dart';
import 'package:byteark_player_flutter/data/byteark_player_config.dart';
import 'package:byteark_player_flutter/data/byteark_player_item.dart';
import 'package:byteark_player_flutter/presentation/byteark_player.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  late ByteArkPlayerController _controller;

  @override
  void initState() {
    // 初始化ByteArkPlayerController。
    _controller = ByteArkPlayerController();
    super.initState();
  }

  @override
  void dispose() {
    // 释放ByteArkPlayerController资源。
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    // 步骤1: 设置ByteArkPlayerItem。
    var playerItem = ByteArkPlayerItem(
        url:
            "https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8");

    // 步骤2: 设置ByteArkPlayerConfig。
    var playerConfig = ByteArkPlayerConfig(
        licenseKey: ByteArkPlayerLicenseKey(
            android: "ANDROID_LICENSE_KEY", iOS: "IOS_LICENSE_KEY"),
        playerItem: playerItem);

    return MaterialApp(
      title: 'ByteArk Player Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: Scaffold(
        appBar: AppBar(
          title: const Text('ByteArk Player Demo'),
          centerTitle: true,
        ),
        body: Column(
          children: [
            // 步骤3: 嵌入ByteArk Player小部件。
            AspectRatio(
              aspectRatio: 16 / 9,
              child: ByteArkPlayer(
                playerConfig: playerConfig,
                height: 300,
              ),
            ),
          ],
        ),
      ),
    );
  }
}

播放器配置

ByteArkPlayerItem

ByteArkPlayerItem 类表示要在ByteArk Player中播放的媒体项。它包含必要的元数据和属性，用于配置和显示媒体内容。

class ByteArkPlayerItem {
  final String? mediaId; // 媒体项的唯一标识符。
  final String? posterImage; // 与媒体项关联的海报图像URL。
  final String? title; // 媒体项的标题。
  final String? subtitle; // 媒体项的副标题或描述。
  final String? url; // 媒体内容的URL（例如视频或音频）。
  final String? shareUrl; // 媒体项的分享URL。
  final ByteArkNielsenMetaData? nielsenMetaData; // 与媒体项关联的尼尔森元数据。
  final ByteArkDrm? drm; // 媒体项的数字版权管理设置。
}

ByteArkPlayerConfig

ByteArkPlayerConfig 类用于配置ByteArk Player的各种设置和功能。每个属性都可以设置以自定义播放器的行为和外观。

class ByteArkPlayerConfig {
  final ByteArkPlayerLicenseKey licenseKey; // 播放器的许可证密钥，包含Android和iOS密钥。
  final bool? autoPlay; // 当播放器准备就绪时自动开始播放。
  final bool? backButton; // 显示返回按钮以导航返回。
  final VoidCallback? backButtonAction; // 返回按钮被按下时执行的操作。
  final bool? control; // 显示播放控制（播放、暂停等）在UI上。
  final bool? muted; // 开始播放时将播放器静音。
  final bool? pictureInPicture; // 启用画中画模式。
  final bool? seekButtons; // 显示用于导航媒体的搜索按钮。
  final int? seekTime; // 搜索前进或后退的时间间隔（秒）。
  final ByteArkPlayerItem? playerItem; // 要播放的媒体项。
  final ByteArkPlayerPlaylist? playlist; // 播放列表中的媒体项。
  final bool? shareButton; // 显示一个按钮以分享媒体。
  final bool? fullScreenButton; // 显示一个按钮以切换全屏模式。
  final bool? settingButton; // 控制是否显示设置按钮以调整播放器选项。
  final bool? secureSurface; // 启用安全表面以进行播放（例如，用于DRM）。
  final bool? allowBackgroundPlaying; // 允许后台播放。
  final ByteArkPlaybackSetting? playbackSetting; // 自定义播放设置（例如速度）。
  final ByteArkNielsenSetting? nielsenSetting; // 尼尔森跟踪设置与媒体消费有关。
  final ByteArkLighthouseSetting? lighthouseSetting; // Lighthouse跟踪设置与媒体消费有关。
  final ByteArkChromeCastSetting? chromeCastSetting; // Chromecast设置与流媒体有关。
  final ByteArkAdsInsertionSetting? adsInsertionSetting; // 设置在播放期间插入广告。
  final ByteArkAdsSettings? adsSettings; // 播放器的一般广告设置。
}

播放器API

SDK 提供的方法和变量可以通过 ByteArkPlayer 实例访问，以控制播放行为或获取媒体内容信息。

ByteArkPlayerController

ByteArkPlayerController 类提供了控制ByteArk Player中媒体播放的接口。此类与底层平台特定实现交互以执行媒体控制操作。

示例用法

late ByteArkPlayerController _byteArkPlayerController;

@override
void initState() {
  super.initState();
  // 步骤1: 创建 ByteArkPlayerController 实例
  _byteArkPlayerController = ByteArkPlayerController();
}

// 步骤2: 通过调用 byteArkPlayerController.methodName 使用每个方法
ElevatedButton(
     onPressed: () {
         _byteArkPlayerController.play();
     }
)

@override
void dispose() {
  // 步骤3: 仅在确定不再需要控制器时才释放它
  _byteArkPlayerController.dispose();
  super.dispose();
}

ByteArkPlayerEventChannel

本节设置了事件监听器以处理由ByteArk Player发出的各种事件。监听器订阅流（ByteArkPlayerEventChannel.stream）并根据不同的事件作出反应，这些事件对应于播放器状态的变化，如播放动作、全屏变化或错误。每个事件由ByteArkPlayerEventTypes中的枚举值标识。

示例用法

// 步骤1: 创建 StreamSubscription 实例
StreamSubscription<dynamic>? _subscription;

// 步骤2: 从原生侧开始监听事件，BytearkPlayerEventTypes.eventName
_subscription = BytearkPlayerEventChannel.stream.listen((event) {
  switch (event) {
    case BytearkPlayerEventTypes.playerReady:
      print('Received event: playerReady');
      break;
    default:
      print('Received unknown event: $event');
  }
}, onError: (error) {
  print('Error: $error');
});