You need to enable JavaScript to run this app.
导航
视频直播
  • 文档首页
    • /视频直播/客户端 SDK/拉流 SDK/React Native/基础功能
基础功能
最近更新时间：2024.08.02 17:33:59首次发布时间：2024.08.02 17:33:59
我的收藏

本章节为您介绍拉流基础功能的接入方法，根据文档提供的操作步骤进行配置，您可接入直播拉流播放控制能力。

前提条件

注意事项

真机调试：由于 SDK 使用了大量的音视频接口，这些接口在仿真模拟器下可能会出现异常，推荐您使用真机进行代码调试。

功能接入

本节为您详细介绍如何通过拉流 SDK 实现直播拉流播放控制的能力，包括但不限于创建播放器、初始化配置、事件监听、设置渲染 View、设置播放地址。

创建播放器

使用拉流 SDK，需要先创建直播播放器。您可以参考以下代码创建播放器。

import {initPlayer} from '@volcengine/react-native-velive-pull';

const mLivePlayer = await initPlayer({
  viewId: 'pull-view',
  enableSei: true, // 初始化配置参数
  networkTimeoutMs: 10000,
});

初始化配置

播放器进行初始化相关配置。详细参数说明如下表所示。

参数类型说明
enableSeiboolean是否开启 SEI 消息的解析。默认值为 false。
enableHardwareDecodeboolean是否开启硬件解码功能。默认值为 true。开启后，如果硬件解码失败，播放器会自动切换为软解码。
networkTimeoutMsint网络超时时间，单位为 ms。默认值为 5000。如果网络请求在超时时间内未收到服务器响应，播放器会认为请求失败。
retryIntervalTimeMsint重试时间间隔，单位为 ms。默认值为 5000。在播放直播时，如果出现网络异常等导致播放中断，播放器会尝试进行重试。
retryMaxCountint播放器在网络连接错误的情况下的最大重试次数。默认值为 5。如果配置为 0，表示关闭播放器内部的重试机制。

enableLiveDNS

boolean

是否开启本地 DNS 预解析。默认值为 false。开启本地 DNS 预解析可以优化播放器的起播时间。

注意

如果预解析出现异常，可能会影响播放器的正常使用。

enableStatisticsCallbackboolean是否开启播放信息周期性回调。默认值为 false。
statisticsCallbackIntervalint播放信息周期性回调的时间间隔，单位为 s。默认值为 5。

配置事件监听

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

mLivePlayer.setObserver({
  onFirstVideoFrameRender() {
    addLog('视频首帧渲染');
  },
  onFirstAudioFrameRender() {
    addLog('音频首帧渲染');
  },
  onVideoRenderStall() {
    addLog('视频渲染卡顿');
  },
  onAudioRenderStall() {
    addLog('音频渲染卡顿');
  },
  onResolutionSwitch(_player, resolution) {
    if (resolution !== playerConfig.resolution) {
      playerConfig.resolution = resolution;
    }
    addLog(`清晰度切换: ${VeLivePlayerResolution[resolution]}`);
  },
  onVideoSizeChanged(_player, width, height) {
    addLog(`分辨率切换: ${width} * ${height}`);
  },
  onReceiveSeiMessage(_player, message) {
    if (message.includes('[RTS]')) {
      return;
    }
    addLog(`收到sei消息: ${message}`);
  },
  onMainBackupSwitch(_player, _streamType, _error) {
    addLog('主备切换');
  },
  onPlayerStatusUpdate(_player, status) {
    addLog('播放器状态更新' + VeLivePlayerStatus[status]);
  },
  onSnapshotComplete(_player, _bitmap) {
    addLog('截图完成');
  },
  onStreamFailedOpenSuperResolution(_player, err) {
    addLog(`开启超分失败 (${err.errorCode || ''}) ${err.errorMsg || ''}`);
  },
  onStatistics(_player, info) {
    playerConfig.info = `url: ${info.url}
当前播放延迟: ${info.delayMs}
下载码率: ${info.bitrate}
当前播放格式: ${VeLivePlayerFormat[info.format]}
当前帧率: ${info.fps}
分辨率: ${info.width} * ${info.height}
解码方式: ${info.isHardwareDecode ? '硬解' : '软解'}
传输协议: ${VeLivePlayerProtocol[info.protocol]}
累计卡顿时长: ${info.stallTimeMs}
音频缓冲区大小: ${info.audioBufferMs}
视频缓冲区大小: ${info.videoBufferMs}
视频编码类型: ${info.videoCodec}`;
  },
  onError(_player, error) {
    addLog(`播放错误: (${error.errorCode}) ${error.errorMsg}`);
  },
});

配置渲染 View

为了展示播放器的视频画面，您需要配置一个渲染 View。播放器提供了 NativeViewComponent 来进行配置。

import {NativeViewComponent} from '@volcengine/react-native-velive-pull';

const PullView = () => {
  return (
    <NativeViewComponent
      id="pull-view"
      kind={
        Platform.select({
          android: 'SurfaceView',
          ios: 'UIView',
        })!
      }
      onViewLoad={initPlayer}
      style={{width: '100%', height: '100%'}}
    />
  );
};

配置播放地址

通过 setPlayUrl 接口配置单一播放地址，支持 RTMP、FLV、HLS 等直播协议地址。代码示例如下所示。

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

说明

如果您需要配置多路组合播放地址，可使用 setPlayStreamData 接口，该接口支持 RTM、QUIC、主备流、多档位、ABR 等功能，详细的代码示例和接入方法请参考进阶功能接入。

调整播放画面

您可以通过以下接口调整播放画面的填充模式、镜像和旋转角度，以获得更好的观看体验。

配置填充模式

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

填充模式说明
VeLivePlayerFillModeAspectFit显示完整的视频帧。视频帧等比缩放，直至视频帧恰好在画布上全部显示。如果视频帧长宽比例与画布不同，视窗上未被视频帧填满区域将填充为黑色。
VeLivePlayerFillModeFullFill视频帧自适应画布。视频帧非等比缩放，直至填满画布。在此过程中，视频帧的长宽比例可能会发生变化。
VeLivePlayerFillModeAspectFill视频填满画布。视频帧等比缩放，直至填满画布，超出屏幕的部分将被裁剪，画面可能不完整。

您可以参考以下代码示例配置填充模式。

// 配置填充模式
mLivePlayer.setRenderFillMode(
  VeLivePlayerFillMode.VeLivePlayerFillModeAspectFill,
);

配置镜像

通过播放器的 setRenderMirror 接口可以配置播放画面的镜像模式，播放器支持以下 3 种镜像模式。

镜像说明
VeLivePlayerMirrorNone关闭镜像
VeLivePlayerMirrorHorizontal水平镜像
VeLivePlayerMirrorVertical垂直镜像

您可以参考以下代码示例配置镜像。

// 配置水平镜像
mLivePlayer.setRenderMirror(VeLivePlayerMirror.VeLivePlayerMirrorHorizontal);

配置旋转

通过播放器的 setRenderRotation 接口可以配置播放画面的旋转角度，播放器支持以下 4 种旋转角度。

旋转说明
VeLivePlayerRotation0关闭旋转
VeLivePlayerRotation90顺时针旋转 90 度
VeLivePlayerRotation180顺时针旋转 180 度
VeLivePlayerRotation270顺时针旋转 270 度

您可以参考以下代码示例配置旋转角度。

// 配置画面旋转 90 度
mLivePlayer.setRenderRotation(VeLivePlayerRotation.VeLivePlayerRotation90);

开始播放

调用播放器的 play 接口开始播放。代码示例如下所示。

mLivePlayer.play(); //开始播放。

调用播放器的 isPlaying 接口可以获取当前的播放状态。代码示例如下所示。

const isPlaying = mLivePlayer.isPlaying(); //获取播放状态

暂停播放

调用播放器的 pause 接口暂停播放，代码示例如下所示。

mLivePlayer.pause(); //暂停播放

说明

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

停止播放

调用播放器的 stop 接口停止播放。代码示例如下所示。

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

销毁播放器

调用播放器的 destroy 接口销毁播放器并释放内存。当您停止播放后需要销毁播放器时，请调用该接口。代码示例如下所示。

mLivePlayer.destroy(); // 销毁拉流引擎，退出前释放播放器和内存

前后台切换

在应用程序从前台切换到后台时，播放器默认会继续播放音频。如果您希望在后台状态停止播放，可参考以下示例代码。

AppState.addEventListener('change', state => {
  state === 'active' && mLivePlayer.play();
  state === 'background' && mLivePlayer.pause();
});

静音配置

调用播放器的 setMute 接口可以控制是否静音播放。代码示例如下所示。

mLivePlayer.setMute(true); // 配置静音播放

调用播放器的 isMute 接口可以获取当前是否为静音状态。代码示例如下所示。

boolean isMute = mLivePlayer.isMute(); // 获取静音状态

配置播放音量

调用播放器的 setPlayerVolume 接口可以控制播放音量，参数表示音量大小，默认值为 1.0，取值范围为 [0.0,1.0]。代码示例如下所示。

mLivePlayer.setPlayerVolume(0.5); // 配置播放音量