基础功能--视频直播-火山引擎

文档中心

立即注册

导航

基础功能

最近更新时间：2025.08.29 11:19:49首次发布时间：2025.08.22 17:24:27

本文介绍如何使用 Flutter 拉流 SDK 的基础功能。

前提条件

已完成 SDK 的集成和初始化。详见集成 Flutter 拉流 SDK 和初始化 Flutter 拉流 SDK。

创建播放器并配置渲染 View

使用 Flutter 拉流 SDK，需要先创建直播播放器。为了展示播放器的视频画面，您需要配置一个渲染 View。

// 创建播放器。此处以创建一个宽度为屏幕宽度，高度为屏幕高度 9/16 的播放器为例。
VeLivePlayer manager = await VeLivePlayer.createManager();

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: Container(
      height: MediaQuery.of(context).size.height * 9 / 16,
      width: MediaQuery.of(context).size.width,
      // 配置渲染 View。
      child: VeliveFlutterPlayerView(manager: manager),
    ),
  );
}

初始化配置

在创建播放器后，您可以通过 VeLivePlayerConfiguration 对播放器进行初始化配置。详细参数说明如下表所示。

参数	类型	说明
enableSei	boolean	是否开启 SEI（Supplemental Enhancement Information，补充增强信息）消息的解析。默认值为 `false`。取值如下： `true`：开启。 `false`：关闭。说明 SEI 消息是一种与视频帧同步的数据通道，常用于在特定时间点同步显示互动内容，如题目、弹幕、虚拟道具等，为观众带来更丰富的互动体验。
enableHardwareDecode	boolean	是否开启硬件解码功能。默认值为 `true`。取值如下： `true`：开启。如果硬件解码失败，播放器会自动切换为软解码。 `false`：关闭。
enableLiveDNS	boolean	是否开启本地 DNS 预解析。默认值为 `false`。取值如下： `true`：开启。开启本地 DNS 预解析可以优化播放器的起播时间。 `false`：关闭。说明如果预解析出现异常，可能会影响播放器的正常使用。
enableStatisticsCallback	boolean	是否开启播放信息周期性回调。默认值为 `false`。取值如下： `true`：开启。 `false`：关闭。
statisticsCallbackInterval	int	播放信息周期性回调的时间间隔。单位为秒，默认值为 `5`。
networkTimeoutMs	int	网络超时时间。单位为毫秒，默认值为 `5000`。如果网络请求在超时时间内未收到服务器响应，播放器会认为请求失败。
retryIntervalTimeMs	int	重试时间间隔。单位为毫秒，默认值为 `5000`。在播放直播时，如果出现了网络异常等问题导致播放中断，播放器会立即进行一次重试。重试失败之后，每达到重试间隔时间，播放器会再次重试。说明仅在无备流时生效。如存在备流，则在出现网络异常等问题时，会直接切换至备流继续播放。
retryMaxCount	int	在网络连接错误的情况下，播放器的最大重试次数。默认值为 `5`。取值为 `0` 表示关闭播放器内部的重试机制。

// 初始化配置。以下示例中，开启了 SEI 消息的解析以及硬件解码功能。
VeLivePlayerConfiguration configuration = VeLivePlayerConfiguration(
      enableSei: true
      enableHardwareDecode: true
    );

配置播放地址

配置单一播放地址，支持 RTM、FLV、HLS 直播协议地址。

// 通过 URL 进行播放。
String playUrl = "http://pull.example.com/live/stream.flv"
// 配置播放地址。
manager.setPlayUrl(playUrl)

说明

如需为播放器配置不同的播放地址，以便在播放过程中进行切换，可使用 setPlayStreamData 方法。该方法支持主备流和自适应码率（ABR）功能。详见进阶功能。

开始播放

Future<void> play();

获取播放器是否正在播放

Future<bool?> isPlaying();

暂停播放

Future<void> pause();

说明

在直播中，暂停和停止的行为相同。暂停后再调用 play 方法，播放器将重新拉流。

停止播放

Future<void> stop();

销毁播放器

销毁播放器并释放内存。如需在停止播放后销毁播放器，可调用该方法。

Future<void> destroy();

设置播放画面填充模式

通过播放器的 setRenderFillMode 方法可以配置播放画面的填充模式。播放器支持以下 3 种填充模式。

填充模式	说明
aspectfill	保持视频的原始宽高比例，填满播放器。如果视频的宽高比与播放器的宽高比不同，超出播放器边界的部分会被裁剪，因此画面可能不完整。
aspectfit	保持视频的原始宽高比例，直到视频完全显示在播放器内。如果视频的宽高比与播放器的宽高比不同，未被视频填充的区域将显示为黑色。
fullfill	视频完全填充播放器，但视频的宽高比可能会发生变化。

参考以下代码示例设置播放画面的填充模式。

Future<void> setRenderFillMode(VeLivePlayerFillMode fillMode);

设置是否静音播放

设置是否静音播放。默认非静音播放。

Future<void> setMute(bool mute);

获取是否为静音状态

Future<bool?> isMute();

设置视频画面旋转角度

enum VeLivePlayerRotation {
  // 关闭旋转。
  rotation0,
  // 顺时针旋转 90 度。
  rotation90,
  // 顺时针旋转 180 度。
  rotation180,
  // 顺时针旋转 270 度。
  rotation270,
}

Future<void> setRenderRotation(VeLivePlayerRotation rotation);

配置事件监听

您可以通过配置事件回调监听来获取播放器的内部状态信息，包括播放状态、错误信息、音视频首帧回调以及周期性统计数据等。代码示例如下所示。

配置播放器回调。

Future<void> setObserver(VeLivePlayerObserver observer);

播放器回调处理。

// 当播放器出现错误时，触发该回调。
void Function(VeLivePlayerError error)? onError;

// 视频首帧渲染事件回调。视频首帧渲染成功，或播放过程中发生重试，重试后的第一个视频帧渲染成功，均会触发此回调。
void Function(bool isFirstFrame)? onFirstVideoFrameRender;

// 音频首帧渲染事件回调。音频首帧渲染成功，或播放过程中发生重试，重试后的第一个音频帧渲染成功，均会触发此回调。
void Function(bool isFirstFrame)? onFirstAudioFrameRender;

// 清晰度档位变化回调。
void Function(VeLivePlayerResolution resolution, VeLivePlayerError? error, VeLivePlayerResolutionSwitchReason reason)? onResolutionSwitch;

//  播放卡顿开始回调。
void Function()? onStallStart;

// 播放卡顿结束回调。当音频缓冲区达到起播条件且开始播放时，触发该回调。
void Function()? onStallEnd;

// 当视频宽高发生变化时，触发该回调。
void Function(int width, int height)? onVideoSizeChanged;

// 视频渲染卡顿回调。
void Function(int stallTime)? onVideoRenderStall;

// 音频渲染卡顿回调。
void Function(int stallTime)? onAudioRenderStall;

// 播放状态变化回调。
void Function(VeLivePlayerStatus status)? onPlayerStatusUpdate;

// 播放信息周期性回调。SDK 会周期性触发该回调。您可以通过该回调，获取当前播放器的播放地址、码率和帧率等信息。
void Function(VeLivePlayerStatistics statistics)? onStatistics;

// 当 SDK 接收到 SEI 消息时，触发该回调。
void Function(String message)? onReceiveSeiMessage;

// 主备流切换回调。
void Function(VeLivePlayerStreamType streamType, VeLivePlayerError? error)? onMainBackupSwitch;

获取 SDK 版本号

static Future<String?> getVersion();

设置日志打印级别

设置打印到控制台的日志级别。

enum VeLivePlayerLogLevel {
  // 输出 VERBOSE、DEBUG、INFO、WARNING 和 ERROR 级别的日志。
  verbose,
  // 输出 DEBUG、INFO、WARNING 和 ERROR 级别的日志。
  debug,
  // 输出 INFO、WARNING 和 ERROR 级别的日志。
  info,
  // 输出 WARNING 和 ERROR 级别的日志。
  warn,
  // 输出 ERROR 级别的日志。
  error,
  // 关闭日志打印。
  none,
}

static Future<void> setLogLevel(VeLivePlayerLogLevel level);