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

前提条件

您已完成集成 SDK。

引入头文件

import 'package:ve_vod/ve_vod.dart';

初始化 SDK

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

Future<void> initTTSDK() async {
     // 开启日志
    if (kDebugMode) {
      FlutterTTSDKManager.openAllLog();
    }
    // 注册插件日志
    TTFLogger.onLog = (logLevel, msg) {
      print(msg);
    };

    // 传入有效的 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，默认 100M，可根据自身业务场景调整，超过缓存大小按照 LRU 规则清理
    vodConfig.cacheMaxSize = 300 * 1024 * 1024;
    
    // 传入在火山引擎点播控制台应用管理页面获取的 AppID
    TTSDKConfiguration sdkConfig =
        TTSDKConfiguration.defaultConfigurationWithAppIDAndLicPath(
            appID: 'your AppID', licenseFilePath: licPath, channel: channel);
    sdkConfig.vodConfiguration = vodConfig;
    FlutterTTSDKManager.startWithConfiguration(sdkConfig);
    
    // 如需支持多 Region，请提交工单联系技术支持
  }

设置自定义 ID

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

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

创建播放器

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

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

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

设置播放源

点播 SDK 支持设置 Vid 和 DirectUrl 播放源。

• 设置 Vid 播放源：使用 Vid 播放源时，您需要设置 Vid 和 PlayAuthToken 参数。这两个参数是由应用服务端下发给客户端。详情请见通过临时播放 Token 播放。

  TTVideoEngineVidSource source = TTVideoEngineVidSource.init(
          vid: <vid>,
          playAuthToken: <playAuthToken>,
          resolution: <TTVideoEngineResolutionType>);
  
  player.setMediaSource(source);
  

• 设置 DirectUrl 播放源：如使用 DirectUrl 播放源，您需要将播放地址设置给播放器。播放地址可以是第三方点播地址或火山引擎视频点播服务生成的播放地址。

  TTVideoEngineUrlSource source = TTVideoEngineUrlSource.initWithURL(<url>, <cacheKey>);
  
  player.setMediaSource(source);
  

播放控制

// 播放
player.play();

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

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

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

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

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

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

设置填充模式

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

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

设置旋转角度

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

设置镜像模式

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

循环播放

player.setLooping(<bool>);

倍速播放

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

设置自定义 Header

// 设置播放请求中的自定义 HTTP Header
player.setCustomHeader(<String key, String value>);

静音

// 静音
player.setMuted(<bool>);

调节音量

// 调节音量
// @Note: iOS 中左右声道音量一致，左右不一致时 iOS 取左声道的值
// - left: 左声道音量
// - right: 右声道音量
player.setVolume({required TTVolume volume})

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

设置业务类型

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

player.setTag(<String>);

设置自定义标签

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

player.setSubTag(<String>);

设置清晰度

播放 Vid 视频源时，视频点播服务端会下发多个清晰度的播放地址。

获取当前清晰度

// 获取视频清晰度信息，需要在 onPrepared 之后获取
TTVideoEngineResolutionType resolution = await player.currentResolution

获取清晰度列表

当 TTVideoEngine 接收到 fetchedVideoModel 回调时，您可调用 supportedResolutionTypes 方法获取到所有清晰度的数组。您可用该数组做清晰度列表的展示和清晰度逻辑选择。示例代码如下：

player.fetchedVideoModel = () async {
    List<TTVideoEngineResolutionType>? resTypes = await player.supportedResolutionTypes;
};

切换清晰度

// 设置起播清晰度
player.configResolutionBeforeStart(<TTVideoEngineResolutionType>);

// 起播后切换清晰度
player.configResolutionAfterStart(targetResolution:<TTVideoEngineResolutionType>);

清晰度枚举

播放私有加密视频

点播 SDK 通过 Vid 和 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");
  }