本文为您介绍如何使用 Flutter 播放器 SDK 的基础功能。

开始播放 #

步骤 1：引入头文件 #

import 'package:ve_vod/ve_vod.dart';

步骤 2：初始化 SDK #

建议在项目的 main.dart 文件 runApp 方法初始化 SDK，保障初始化顺序。

Future<void> initTTSDK() async {
     // 打开日志开关
    FlutterTTSDKManager.openAllLog();
    
    // 注册插件日志, 可选择输出到控制台或本地文件，以便问题排查
    TTFLogger.onLog = (logLevel, msg) {
      print(msg);
    };

    // 参考集成 SDK 添加 License, 传入有效的 license 文件路径，如 'assets/VEVod.lic'
    String licPath = 'your license file path'; 
    // Android 平台请传入有效的渠道号，用于统计；iOS选填，默认为 App Store
    String channel = Platform.isAndroid ? 'your channel' : 'App Store';
    // 初始化配置
    TTSDKVodConfiguration vodConfig = TTSDKVodConfiguration();
    // 设置最大缓存 Size，默认 100 MB，可根据自身业务场景调整，超过缓存大小按照 LRU 规则清理
    vodConfig.cacheMaxSize = 300 * 1024 * 1024;
    
    // 传入在火山引擎点播控制台应用管理页面获取的 AppID
    TTSDKConfiguration sdkConfig =
        TTSDKConfiguration.defaultConfigurationWithAppIDAndLicPath(
            appID: 'your AppID', licenseFilePath: licPath, channel: channel);
    sdkConfig.vodConfiguration = vodConfig;
    FlutterTTSDKManager.startWithConfiguration(sdkConfig);
  }

步骤 3：创建播放器 #

// 创建 player 实例
VodPlayerFlutter player = VodPlayerFlutter();

// 若采用预渲染策略，需在调用 createPlayer 时设置 vid 和 preCreated 参数；若未采用预渲染策略，则无需传参。
// 调用 createPlayer 时需要使用 await，待其完成后，才可调用 player 的其他方法。 
await player.createPlayer();

// (Android) 设置 NativeView 类型，默认使用 TextureView，您可以改为 SurfaceView
NativeViewType nativeViewType = NativeViewType.TextureView;
// NativeViewType nativeViewType = NativeViewType.SurfaceView;

// 创建 TTVideoPlayerView 用于渲染视频，TTVideoPlayerView 内部使用 NativeView 构造
TTVideoPlayerView playerView = TTVideoPlayerView(
  nativeViewType: nativeViewType,
  onPlatformViewCreated: (int viewId) {
    // 在 NativeView 创建完成后，需要将 player 和 viewId 进行绑定
    player.setPlayerContainerView(viewId);
  },
);

// 在 Build 方法中引用前面创建的 TTVideoPlayerView
@override
Widget build(BuildContext context) {
    return Scaffold(
        body: playerView,
    );
}

步骤 4：设置播放源 #

播放器 SDK 支持多种播放源，您可以根据视频的来源和业务场景选择最合适的方式。

TTVideoEngineVidSource source = TTVideoEngineVidSource.init(
        vid: <vid>, // 由您的业务服务端提供
        playAuthToken: <playAuthToken>, // 由您的业务服务端提供
        resolution: <TTVideoEngineResolutionType>); // 指定起播清晰度

player.setMediaSource(source);

import 'dart:convert';
import 'package:crypto/crypto.dart';

String generateVideoCacheKey(String videoUrl) {
  final path = Uri.parse(videoUrl).path;
  return md5.convert(utf8.encode(path)).toString();
}

final cacheKey = generateVideoCacheKey(videoUrl);
TTVideoEngineUrlSource source = TTVideoEngineUrlSource.initWithURL(videoUrl, cacheKey);

player.setMediaSource(source);

步骤 5：播放控制 #

// 播放
player.play();

// 暂停，再次调用 play 可由暂停恢复到播放
player.pause();

// 从指定位置起播，单位：毫秒。在调用 play 前设置，可实现从指定时间点开始播放或跳过片头等功能
player.setStartTimeMs(<double>);

// 调用 play 后，Seek 到指定位置进行播放，单位: 毫秒，可以实现拖拽进度条到指定时间开始播放的功能
player.seekToTimeMs(time:<double>);

// Seek，同时监听 seek 状态回调 
player.seekToTimeMs(
    time: <double>,
    seekCompleted: (bool success) {
        // Seek 完成的回调
    },
    seekRenderCompleted: () {
        // Seek 后首帧渲染完成的回调
    });
    
// 刷新当前视频帧到 Surface 上。当播放器处于暂停状态时，将视频数据显示在 Surface 上，解决黑屏问题。
// 仅对 Android 生效。
player.forceDraw(); 

// 停止播放
player.stop();

步骤 6：释放播放器实例 #

// 异步释放播放器实例，当播放器释放后，不应该调用实例的任何方法
player.closeAsync();

设置自定义 ID #

通过配置自定义 ID，您可在视频点播控制台质量平台的单点追查页面查看单设备的播放数据。详细说明请见单点追查。

Future<void> initTTSDK() async {
    // ... 
    FlutterTTSDKManager.startWithConfiguration(sdkConfig);
    
    // TTSDK 初始化后设置 uniqueID，用于单点追踪、问题排查，一般为用户 ID 或设备 ID
    FlutterTTSDKManager.setCurrentUserUniqueID('your uniqueID');
  }

设置填充模式 #

// 设置视频的填充模式，支持以下填充模式：
// TTVideoEngineScalingModeNone: 无拉伸，不会有变形，可能有黑边
// TTVideoEngineScalingModeAspectFit: 等比例适配，不会有变形，按照视频宽高等比适配画面，可能有黑边
// TTVideoEngineScalingModeAspectFill: 等比例填充，不会有变形，按照视频宽高等比充满画面，可能有画面裁切
// TTVideoEngineScalingModeFill: 拉伸填充，视频宽高比例与画面比例不一致，会导致画面变形
player.setScalingMode(<TTVideoEngineScalingMode>);

// （仅 iOS）当 scaleMode = AspectFill 时，在部分较老机型（例如 iPhone8 及以下）可能出现渲染区域超过布局大小的情况。您可调用 setClipToBounds 方法设置是否裁剪渲染区域。默认 false
player.setClipToBounds(<bool>);

设置旋转角度 #

// 设置旋转角度，可设为 0、90、180、270
player.setRotation(<int>)

设置镜像模式 #

// 开启水平镜像
player.setMirrorHorizontal(<bool>);
// 开启垂直镜像
player.setMirrorVertical(<bool>);

截图 #

// 传入完整的截图存储路径。SDK 将根据传入的截图路径保存截图，并返回截图结果：
// - iOS：建议使用沙盒 documents 目录，结合时间戳和格式保存截图，例如：/var/mobile/Containers/Data/Application/<xxxx>/Documents/timestamp.png。
// - Android：建议使用 SurfaceView，结合目录、时间戳和格式保存截图，例如：/storage/emulated/0/Android/data/com.xxxx/files//timestamp.png。如果需要保存至系统目录的子目录，则需要您先行创建子目录。
player?.snapshot(path: <String>, completion: (bool success, String filePath) {},);

循环播放 #

player.setLooping(true);

倍速播放 #

// 设置倍速播放，取值范围 0.1 ～ 3.0
player.setPlaybackSpeed(<double>);

设置自定义 Header #

// 设置播放请求中的自定义 HTTP Header
player.setCustomHeader('X-Custom-Header', 'value');

静音 #

// 静音
player.setMuted(true);

调节音量 #

调节的音量范围大小为 0 ～ 1。

Future<void> setNormalizedVolume(double volume)

默认调节的是系统音量，如果需要单独调节视频的音量，则需要在播放前调用setTrackVolumeEnabled(true)。

// true: 调整播放音量。如设为 true，必须在 play() 之前调用
// false: （默认）调整系统音量
player.setTrackVolumeEnabled(true);

获取音量 #

获取的音量范围大小为 0 ～ 1。

Future<double?> getNormalizedVolume()

设置业务类型 #

业务类型 tag 用于区分同一应用（appid）内不同类型的音视频。可以根据业务需要按视频场景、视频时长等划分，比如沉浸式 feed 流、短视频、长视频等。示例代码如下：

player.setTag(<String>);

设置子业务类型 #

子业务类型 subtag 用于区分同一业务类型下的不同细分，比如加密视频、非加密视频、音频等。示例代码如下：

player.setSubTag(<String>);

生成 UnionInfo #

UnionInfo 是播放端从设备中提取的用于标识访问或设备唯一性的信息。播放器 SDK 通过 UnionInfo 向应用服务端发起播放请求，应用服务端通过服务端 SDK 本地签发包含 UnionInfo 的 PlayAuthToken 并下发给播放器 SDK，即可播放火山引擎私有加密视频。更多信息，请见火山引擎私有加密方案。您可通过以下代码生成 UnionInfo：

String? unionInfo = await FlutterTTSDKManager.getEngineUniqueId();

纯音频播放 #

播放器 SDK 支持在播放视频时，只解码音频而不解码视频，适用于纯音频播放场景。相比您根据自身业务逻辑实现的纯音频播放，SDK 只解码音频会更省电。

示例代码如下：

// true:开启纯音频播放，视频停止渲染
// false:恢复音视频播放，视频恢复渲染
player.setRadioMode(<bool>);

获取播放信息 #

// 获取播放进度, 单位: 毫秒
Duration position = await player.position;

// 获取音视频总时长, 单位: 毫秒
Duration duration = await player.duration;

// 获取已缓冲的播放时长, 单位: 毫秒
Duration playableDuration = await player.playableDuration;

// 获取视频宽高，单位：pixel
int videoWidth  = await player.videoWidth;
int videoHeight = await player.videoHeight;

// 获取当前播放是否是硬解
bool isHardwareDecode = await player.isHardwareDecode;

// 获取播放状态
enum TTVideoEnginePlaybackState {
  stopped(0),
  playing(1),
  paused(2),
  error(3);
}
TTVideoEnginePlaybackState state = await player.getPlaybackState();

播放状态回调 #

// player 实例提供如下事件回调

// 播放器 onPrepared
void Function()? onPrepared;

// 播放状态变化
void Function(TTVideoEnginePlaybackState playbackState)? playbackStateDidChanged;

// 视频加载状态变化
void Function(TTVideoEngineLoadState loadState, Map<Object?, Object?>? extraInfo)?
      loadStateDidChanged;

// 视频首帧渲染完成的回调
void Function()? readyToDisplay;

// 播放结束的回调
void Function(TTError? error)? didFinish;

展示当前视频下载进度 #

播放器 SDK 支持回调当前视频一段时间内获取的视频数据大小，可用来在视频的起播、Seek、卡顿等情况下展示当前视频下载速度。

示例代码如下：

// 1. 设置 delegate
TTVideoEnginePreload.setMediaDataLoaderDelegate(<widget>);

// 收到网络模块回调
  @override
  void ttvideoEngineTestSpeedInfo(Duration durationMs, int sizeByte) {
    double time = durationMs.inMilliseconds / 1000;

    // 间隔时间，单位为秒
    double dataSize = sizeByte / 1024;

    // 间隔时间内下载数据大小，单位 KB
    double downloadSpeed = dataSize / time;

    // 当前视频下载速度
    print(
        "TTF --  TestSpeedInfo callback, timeInternalMs: $time, size: $sizeByte, speed: $downloadSpeed KB/s");
  }

使用 arm64 模拟器（iOS） #

SDK 默认采用 Metal 渲染，而模拟器不支持 Metal 渲染。若您需要使用 arm64 模拟器进行测试，请参考以下代码将渲染方式指定为 OpenGL 渲染：

// play() 前设置，默认 false
 player.setSimulatorEnable(true)