帮你快速理解、总结文档立即下载

点播场景

最近更新时间:2026-07-31 15:28:30

我的收藏

阅读对象

本文档部分内容为腾讯云专属能力,使用前请开通 腾讯云 相关服务,未注册用户可注册账号使用。

通过本文您可以学会

如何集成腾讯云视立方 React Native 播放器 SDK。
如何使用播放器 SDK 进行点播播放。
如何使用播放器 SDK 底层能力实现更多功能。

特别说明

视频云 SDK 不会对播放地址的来源做限制,即您可以用它来播放腾讯云或非腾讯云的播放地址。但播放器 SDK RN 端只支持 MP4、HLS(m3u8)和 FLV 三种格式的点播地址。

SDK 集成

步骤1:集成 SDK 开发包

下载和集成 SDK 开发包,请参考 集成指引

步骤2:添加播放器视图

使用 SuperPlayerViewComponent 组件作为视频渲染容器:
import { SuperPlayerViewComponent } from 'react-native-superplayer';
import { View, StyleSheet, Dimensions } from 'react-native';

const { width: SCREEN_WIDTH } = Dimensions.get('window');
const VIDEO_HEIGHT = (SCREEN_WIDTH * 9) / 16; // 16:9 比例

function PlayerScreen() {
const handleViewReady = (viewId: string) => {
console.log('播放器视图已就绪:', viewId);
// 在这里创建播放器实例并绑定视图
};

return (
<View style={styles.container}>
<SuperPlayerViewComponent
viewId="my_player_view"
style={styles.player}
onReady={handleViewReady}
/>
</View>
);
}

const styles = StyleSheet.create({
container: {
flex: 1,
},
player: {
width: SCREEN_WIDTH,
height: VIDEO_HEIGHT,
backgroundColor: '#000',
},
});

步骤3:创建播放器实例

onReady 回调中创建 TXVodPlayer 实例并绑定视图:
import { TXVodPlayer, TXVodConstants } from 'react-native-superplayer';
import { useRef, useCallback } from 'react';

function PlayerScreen() {
const playerRef = useRef<TXVodPlayer | null>(null);

const handleViewReady = useCallback((viewId: string) => {
// 创建播放器实例
const player = new TXVodPlayer();

// 绑定视图
player.setPlayerView(viewId);

// 设置事件监听
player.setListener({
onPlayEvent: (event, param) => {
switch (event) {
case TXVodConstants.VOD_PLAY_EVT_PLAY_BEGIN:
console.log('播放开始');
break;
case TXVodConstants.VOD_PLAY_EVT_PLAY_END:
console.log('播放结束');
break;
// 更多事件处理...
}
},
});

playerRef.current = player;
}, []);

// ... 其他代码
}

步骤4:启动播放

播放器支持两种播放方式:URL 播放FileId 播放
通过 URL 方式
通过 FileId 方式
TXVodPlayer 内部会自动识别播放协议,您只需要将您的播放 URL 传给 startPlay 函数即可。
// 播放视频 URL
player.startPlay('https://example.com/video.mp4');
FileId 播放适用于腾讯云点播资源,支持更丰富的功能(如防盗链、清晰度列表等)。
// psign 即播放器签名
player.startPlayWithFileId(
1500005830, // appId
'387702307091793695', // fileId
'your_psign' // 播放签名(可选)
);
媒资管理 找到对应的视频文件,在文件名下方可以看到 FileId。签名介绍和生成方式可参见 文档介绍
通过 FileId 方式播放,播放器会向后台请求真实的播放地址。如果此时网络异常或 FileId 不存在,则会收到 VOD_PLAY_ERR_GET_PLAYINFO_FAIL 事件,反之收到 VOD_PLAY_EVT_VOD_PLAY_PREPARED 表示请求成功。

步骤5:结束播放

在组件卸载时,务必销毁播放器释放资源:
import { useEffect } from 'react';

function PlayerScreen() {
const playerRef = useRef<TXVodPlayer | null>(null);

useEffect(() => {
return () => {
// 组件卸载时销毁播放器
if (playerRef.current) {
playerRef.current.destroy();
playerRef.current = null;
}
};
}, []);

// ... 其他代码
}
结束播放时记得调用播放器的销毁方法,尤其是在下次 startPlay 之前,否则可能会产生内存泄露以及闪屏问题。
停止播放:
// 停止播放
player.stop(true);

基础功能使用

1、播放控制

暂停播放
// 暂停播放
player.pause();
恢复播放
// 恢复播放
player.resume();
停止播放
// 停止播放
player.stop(true);

调整进度(Seek)
当用户拖拽进度条时,可调用 seek 从指定位置开始播放,播放器 SDK 支持精准 seek。
// 跳转到指定时间点(秒)
// 第二个参数 accurateSeek:true=精准 Seek(较耗时),false=快速 Seek
player.seek(30, true); // 精准跳转到 30 秒
player.seek(60, false); // 快速跳转到 60 秒
从指定时间开始播放
首次调用 startPlay 之前,支持从指定时间开始播放。
// 设置起播时间(需在 startPlay 前调用)
player.setStartTime(10); // 从第 10 秒开始播放
player.startPlay(url);

2、变速播放

点播播放器支持变速播放,通过接口 setRate 设置点播播放速率来完成,支持快速与慢速播放,如 0.5X、1.0X、1.2X、2X 等。
// 设置 1.2 倍速播放
player.setRate(1.2);

3、循环播放

// 设置循环播放
player.setLoop(true);
// 获取当前循环播放状态
const isLooping = player.isLoop();

4、静音与音量控制

// 设置静音,true 表示开启静音,false 表示关闭静音
player.setMute(true);

// 设置音量(0-100)
player.setVolume(50);

5、硬件加速

对于蓝光级别(1080p)的画质,简单采用软件解码的方式很难获得较为流畅的播放体验,所以如果您的场景是以游戏直播为主,一般都推荐开启硬件加速。
软解和硬解的切换需要在切换之前先 stop,切换之后再 startPlay,否则会产生比较严重的花屏问题。
player.stop(true);
player.enableHardwareDecode(true);
player.startPlay(url);

6、清晰度设置

SDK 支持 HLS 的多码率格式,方便用户切换不同码率的播放流,从而达到播放不同清晰度的目标。可以通过下面方法进行清晰度设置。
// 在收到播放器 VOD_PLAY_EVT_VOD_PLAY_PREPARED 事件调用 getSupportedBitrates 才会有值返回
const bitrateList = player.getSupportedBitrates();
// 返回 BitrateItem[]
// [{ index: 0, width: 1920, height: 1080, bitrate: 2000000 }, ...]

const index = bitrateList[0].index; // 指定要播的码率下标
player.setBitrateIndex(index); // 切换码率到想要的清晰度

// 获取当前清晰度索引
const currentIndex = player.getBitrateIndex();
在播放过程中,可以随时通过 setBitrateIndex(index) 切换码率。切换过程中,会重新拉取另一条流的数据,SDK 针对腾讯云的多码率文件做过优化,可以做到切换无卡顿。
如果您提前知道视频流的分辨率信息,可以在启播前优先指定播放的视频分辨率,从而避免播放后切换码流。

设置自适应最高码率

// 限制自适应播放的最高码率(单位 Kbps)
player.setAutoMaxBitrate(2000);

7、码流自适应

SDK 支持 HLS 的多码流自适应,开启相关能力后播放器能够根据当前带宽,动态选择最合适的码率播放。可以通过下面方法开启码流自适应。
player.setBitrateIndex(-1); // index 参数传入 -1
在播放过程中,可以随时通过 setBitrateIndex(index) 切换其它码率,切换后码流自适应也随之关闭。

8、开启平滑切换码率

在启动播放前,通过开启平滑切换码率,在播放过程中切换码率,可以达到无缝平滑切换不同清晰度。对比关闭平滑切换码率,切换过程更流畅、体验更好,可以根据需求进行设置。
const config: TXVodPlayConfig = {
smoothSwitchBitrate: true, // 设为 true,可平滑切换码率
};
player.setConfig(config);

9、播放进度监听

点播播放中的进度信息分为:加载进度播放进度,SDK 目前是以事件通知的方式将这两个进度实时通知出来的。
通过 setListener 接口监听播放器事件,进度通知会通过 VOD_PLAY_EVT_PLAY_PROGRESS 事件回调到您的应用程序。
player.setListener({
onPlayEvent: (event, param) => {
if (event === TXVodConstants.VOD_PLAY_EVT_PLAY_PROGRESS) {
// 当前播放进度(毫秒)
const currentMs = param[TXVodConstants.EVT_PLAY_PROGRESS_MS] ?? 0;
// 视频总时长(毫秒)
const durationMs = param[TXVodConstants.EVT_PLAY_DURATION_MS] ?? 0;
// 可播放时长(毫秒),即加载进度
const playableMs = param[TXVodConstants.EVT_PLAYABLE_DURATION_MS] ?? 0;

console.log(`播放进度: ${currentMs / 1000}s / ${durationMs / 1000}s`);
}
},
});

10、播放网速监听

通过 setListener 接口的 onNetStatus 回调监听播放器的网络状态。
player.setListener({
onNetStatus: (param) => {
const speed = param.NET_SPEED; // 网速(kbps)
const vBitrate = param.VIDEO_BITRATE; // 视频码率
const aBitrate = param.AUDIO_BITRATE; // 音频码率
const fps = param.VIDEO_FPS; // 帧率
},
// ...
});

11、获取视频分辨率

播放器 SDK 通过 URL 字符串播放视频,URL 中本身不包含视频信息。为获取相关信息,需要通过访问云端服务器加载到相关视频信息,因此 SDK 只能以事件通知的方式将视频信息发送到您的应用程序中。
可以通过下面两种方法获取分辨率信息:
方法1:通过 onNetStatusVIDEO_WIDTHVIDEO_HEIGHT 获取视频的宽和高。
方法2:在收到播放器的 VOD_PLAY_EVT_VOD_PLAY_PREPARED 事件回调后,直接调用 getWidth()getHeight() 获取当前宽高。
player.setListener({
onNetStatus: (param) => {
const w = param.VIDEO_WIDTH;
const h = param.VIDEO_HEIGHT;
},
// ...
});

// 获取视频宽高,需要在收到播放器的 VOD_PLAY_EVT_VOD_PLAY_PREPARED 事件回调后才返回值
const width = player.getWidth();
const height = player.getHeight();

12、获取视频信息

// 当前播放时间(秒)
const currentTime = player.getCurrentPlaybackTime();

// 视频总时长(秒)
const duration = player.getDuration();

// 可播放时长(秒,已缓冲部分)
const playableDuration = player.getPlayableDuration();

// 缓冲时长(秒)
const bufferDuration = player.getBufferDuration();

// 视频宽度
const width = player.getWidth();

// 视频高度
const height = player.getHeight();

// 是否正在播放
const isPlaying = player.isPlaying();

13、播放缓冲大小

在视频正常播放时,控制提前从网络缓冲的最大数据大小。如果不配置,则走播放器默认缓冲策略,保证流畅播放。
const config: TXVodPlayConfig = {
maxBufferSize: 10, // 播放时最大缓冲大小。单位:MB
};
player.setConfig(config);

14、视频本地缓存

在短视频播放场景中,视频文件的本地缓存是很刚需的一个特性,对于普通用户而言,一个已经看过的视频再次观看时,不应该再消耗一次流量。
格式支持: SDK 支持 HLS(m3u8) 和 MP4 两种常见点播格式的缓存功能。
开启时机: SDK 并不默认开启缓存功能,对于用户回看率不高的场景,也并不推荐您开启此功能。
开启方式: 全局生效,在使用播放器前开启。开启此功能需要配置两个参数:本地缓存目录及缓存大小。
import { RNTXPlayerGlobalSetting } from 'react-native-superplayer';

// 设置播放引擎的全局缓存目录
RNTXPlayerGlobalSetting.setCacheFolderPath('txcache');
// 设置最大缓存大小(MB)
RNTXPlayerGlobalSetting.setMaxCacheSize(200);

15、屏幕截图

// 截取当前帧,返回图片本地路径
const imagePath = await player.snapshot();
console.log('截图保存至:', imagePath);

// 也可通过回调获取
player.setListener({
onSnapshot: (path) => {
console.log('截图路径:', path);
},
// ...
});

16、画面调整

渲染模式:
import { TXVodConstants } from 'react-native-superplayer';

// 铺满模式(裁剪画面,无黑边)
player.setRenderMode(TXVodConstants.RENDER_MODE_FULL_FILL_SCREEN);

// 适应模式(等比缩放,可能有黑边)
player.setRenderMode(TXVodConstants.RENDER_MODE_ADJUST_RESOLUTION);
画面旋转:
// 设置画面旋转角度(0、90、180、270)
player.setRenderRotation(90);
镜像播放:
// 开启/关闭镜像
player.setMirror(true);

17、外挂字幕

注意:
此功能需要播放器高级版 License 支持。
播放器 SDK 支持添加和切换外挂字幕,现已支持 SRT 和 VTT 这两种格式的字幕。
实践:建议在 startPlay 之前添加字幕,在收到 VOD_PLAY_EVT_VOD_PLAY_PREPARED 事件后,调用 selectTrack 选择字幕。字幕文本内容会通过 onSubtitleData 事件回调,字幕的显示需要业务方自行处理。

步骤 1:添加外挂字幕

import { SubtitleMimeType } from 'react-native-superplayer';

// 【重要】必须在 startPlay 之前调用
player.addSubtitleSource(
'https://example.com/subtitle_cn.srt', // 字幕 URL
'Chinese', // 字幕名称(多条字幕 name 必须唯一)
SubtitleMimeType.SRT // 字幕格式:0=SRT, 1=VTT
);

player.addSubtitleSource(
'https://example.com/subtitle_en.vtt',
'English',
SubtitleMimeType.VTT
);

// 然后开始播放
player.startPlay(videoUrl);

步骤 2:开启字幕文本回调

// 【重要】必须设置 extInfoMap['450'] = 0 才能收到 onSubtitleData 回调
player.setConfig({
extInfoMap: {
'450': 0, // 开启字幕文本回调
},
});

player.setListener({
onSubtitleData: (data) => {
// data.subtitleData: 字幕文本(空串表示清屏)
// data.trackIndex: 当前字幕轨道索引
console.log('字幕:', data.subtitleData);
},
// ...
});

步骤 3:播放后切换字幕

// 获取字幕轨道列表
const subtitleTracks = player.getSubtitleTrackInfo();

// 选中指定字幕轨道
player.selectTrack(subtitleTracks[0].trackIndex);

// 取消选中(关闭字幕)
player.deselectTrack(subtitleTracks[0].trackIndex);

18、多音轨切换

注意:
此功能需要播放器高级版 License 支持。
播放器 SDK 支持切换视频内置的多音轨。用法参见如下代码:
// 获取音频轨道列表
const audioTracks = player.getAudioTrackInfo();

// 切换音轨
player.selectTrack(audioTracks[1].trackIndex);

// TXTrackInfo 结构
interface TXTrackInfo {
trackIndex: number; // 轨道索引
trackType: number; // 轨道类型:1=视频, 2=音频, 3=字幕
name: string; // 轨道名称
isSelected: boolean; // 是否选中
isExclusive: boolean; // 是否互斥
isInternal: boolean; // 是否内嵌(false=外挂)
}

19、画中画

注意:
此功能需要播放器高级版 License 支持。
目前双端均支持画中画能力:
Android:基于系统悬浮窗(SYSTEM_ALERT_WINDOW)实现,UI 完全由 SDK 渲染,支持拖动、播放/暂停、快进快退、关闭、恢复 App 等控件。需要用户授予悬浮窗权限。
iOS:直接走系统 PiP(基于 AVPictureInPictureController),UI 由系统接管,支持应用内 PiP 与应用外 PiP。

iOS 接入步骤

说明:
Android 端引入 SDK 后无需额外配置;以下几步仅 iOS 接入画中画时需要。
步骤一:引入 PiP Bundle 资源
SDK 内 PiP 模块依赖 TXVodPlayer.bundle 里的内置资源,必须在编译前手动将其加入 Xcode 工程,不要修改 bundle 名称或其内部任何资源名,否则会导致无缝切换画中画失败。
资源下载地址:TXVodPlayer.bundle.zip
操作示意:

步骤二:开通后台模式
iOS 端无论应用内还是应用外 PiP,都需要 App 声明音频/PiP 后台能力:
Xcode 选择对应的 Target → Signing & CapabilitiesBackground Modes,勾选“Audio, AirPlay, and Picture in Picture”。

步骤三:系统设置开启自动画中画(仅自动画中画功能需要)
只有使用 setAutoPictureInPictureEnabled(true) 自动画中画时,用户需在系统设置中提前打开:
iPhone / iPad → 设置通用画中画自动开启画中画


前置条件

Android
在播放器所在 App 的 AndroidManifest.xml 中已声明 SYSTEM_ALERT_WINDOW 权限(SDK 自身已声明,引用 SDK 后无需额外配置)。
首次使用前需用户授权悬浮窗权限。
iOS
系统版本:iPhone iOS 14+,iPad iOS 9+。
已完成上方 iOS 接入步骤 的步骤一、二(bundle 资源 + Background Modes)。
如需自动画中画,需用户在系统设置中开启"自动开启画中画"。

检测设备支持

import { TXVodPlayer } from 'react-native-superplayer';

const code = TXVodPlayer.isDeviceSupportPip();
// 返回值:
// 0 = 支持(Android 含已授权)
// -101 = Android 无悬浮窗权限
// -201 = iOS 设备或系统版本不支持
// 其它 = 平台相关错误码,详见错误码表

申请悬浮窗权限(仅 Android)

// 跳转到系统授权页,让用户手动开启悬浮窗权限
TXVodPlayer.requestOverlayPermission();

进入 / 退出画中画

// 进入画中画
player.enterPictureInPictureMode();

// 退出画中画
player.exitPictureInPictureMode();
典型按钮接入:
import { Platform } from 'react-native';
import { TXVodPlayer } from 'react-native-superplayer';

const handleEnterPip = () => {
const player = playerRef.current;
if (!player) return;
if (Platform.OS === 'android') {
const code = TXVodPlayer.isDeviceSupportPip();
if (code !== 0) {
TXVodPlayer.requestOverlayPermission();
return;
}
}
player.enterPictureInPictureMode();
};

自动画中画(切后台自动进入)

// 开启后:
// - iOS:调用即可,系统在 App 切后台时自动进入画中画
// - Android:SDK 不监听 App 生命周期,业务侧需用 AppState 自行监听
player.setAutoPictureInPictureEnabled(true);
Android 业务侧通过 AppState 实现自动画中画:
import { useEffect } from 'react';
import { AppState, Platform } from 'react-native';

useEffect(() => {
if (Platform.OS !== 'android' || !autoPipEnabled) return;
const sub = AppState.addEventListener('change', (next) => {
const player = playerRef.current;
if (!player) return;
if (next === 'background' && player.isPlaying()) {
player.enterPictureInPictureMode();
} else if (next === 'active') {
player.exitPictureInPictureMode();
}
});
return () => sub.remove();
}, [autoPipEnabled]);

监听画中画事件

import type { TXPipListener } from 'react-native-superplayer';

player.setPipListener({
onPipStart: () => {
console.log('画中画已开启');
},
onPipStop: () => {
console.log('画中画已关闭');
},
onPipRestore: () => {
// 用户点击悬浮窗内恢复按钮
console.log('用户点击恢复按钮');
},
onPipError: (code, message) => {
console.warn(`画中画错误 code=${code} msg=${message ?? ''}`);
},
});

// 移除监听
player.setPipListener(null);

画中画错误码

错误码按平台分段:
段位
平台
0
通用 — 无错误。
-1xx
Android 专属(悬浮窗实现)。
-2xx
iOS 专属(系统 PiP 实现)。
Android(-1xx):
错误码
含义
SDK 行为
业务建议
-101
缺少悬浮窗权限。
自动跳转系统授权页。
引导用户开权限,返回后重新调用 enterPictureInPictureMode()
-102
找不到 playerId 对应的播放器实例。
直接返回。
检查是否过早 destroy 了 player。
-103
WindowManager.addView 失败。
自动 cleanup 资源。
上报日志 + 提示用户重试。
iOS(-2xx):
错误码
含义
触发场景
-201
设备或系统版本不支持 PiP。
isDeviceSupportPip() 同步预检使用。
-206
找不到 playerId 对应的播放器实例。
RN 层校验,业务过早 destroy player 时触发。
-200
来自 SDK 的 PiP 错误(统一码)。
所有 AVPictureInPictureController 抛出的错误,具体错误类型通过 message 透传。

生命周期注意事项

重要:当播放器实例正处于画中画时,不要主动调用其 destroy(),否则悬浮窗会同步关闭。

进阶功能使用

1、视频预下载

不需要创建播放器实例,预先下载视频部分内容,使用播放器时,可以加快视频启播速度,提供更好的播放体验。
注意:
视频预下载会占用下载带宽和线程资源,建议进行队列控制,并发个数控制在 3 个以内。
使用示例:
通过媒资 URL 预下载
通过媒资 FileId 预下载
import {
RNTXPlayerGlobalSetting,
TXVodPreloadManager,
type TXPlayInfoParams,
} from 'react-native-superplayer';

// 【重要】必须先设置缓存目录和大小,全局设置一次即可
RNTXPlayerGlobalSetting.setCacheFolderPath('txcache');
RNTXPlayerGlobalSetting.setMaxCacheSize(500); // 500MB

// 添加回调监听
const removeComplete = TXVodPreloadManager.addCompleteListener((event) => {
console.log('预下载完成:', event.taskId, event.url);
});

const removeError = TXVodPreloadManager.addErrorListener((event) => {
console.error('预下载失败:', event.code, event.message);
});

// 启动预下载
const params: TXPlayInfoParams = {
url: 'https://example.com/video.mp4',
};

const taskId = await TXVodPreloadManager.startPreload(
params, // 预下载参数
10, // 预下载大小(MB)
921600 // 期望分辨率(1280×720 = 921600),不指定传 -1
);

// 停止预下载
TXVodPreloadManager.stopPreload(taskId);

// 不需要时移除监听
removeComplete();
removeError();
const removeStart = TXVodPreloadManager.addStartListener((event) => {
console.log('预下载开始:', event.taskId);
console.log('实际播放 URL:', event.url); // FileId 换链后的 URL
});

const params: TXPlayInfoParams = {
appId: 1500005830,
fileId: '387702307091793695',
pSign: 'your_psign',
};

const taskId = await TXVodPreloadManager.startPreload(params, 10, 921600);

2、视频下载

视频下载支持用户在有网络的条件下下载视频,随后在无网络的环境下观看。同时播放器 SDK 提供本地加密能力,下载后的本地视频仍为加密状态,仅可通过指定播放器对视频进行解密播放,可有效防止下载后视频的非法传播,保护视频安全。
由于 HLS 流媒体无法直接保存到本地,因此也无法通过播放本地文件的方式实现 HLS 下载到本地后播放,对于该问题,您可以通过基于 TXVodDownloadManager 的视频下载方案实现 HLS 的离线播放。
说明:
视频下载支持下载 MP4 和 HLS 视频。

步骤1:准备工作

import {
RNTXPlayerGlobalSetting,
TXVodDownloadManager,
} from 'react-native-superplayer';

// 设置下载目录,全局设置一次即可
RNTXPlayerGlobalSetting.setCacheFolderPath('txcache');

步骤2:开始下载

开始下载有 FileId 和 URL 两种方式,具体操作如下:
FileId 方式
URL 方式
FileId 下载至少需要传入 appId、fileId 和 quality。带签名视频需传入 pSign,userName 不传入具体值时,默认为 "default"。
注意:
加密视频只能通过 FileId 下载,psign 参数必须填写。
const TXVodQuality = {
'240P': 240,
'360P': 360,
'480P': 480,
'540P': 540,
'720P': 720,
'1080P': 1080,
};

const mediaInfo = await TXVodDownloadManager.startDownload({
appId: 1500005830,
fileId: '387702307091793695',
quality: TXVodQuality['720P'], // 下载清晰度
pSign: 'your_psign',
userName: 'default',
});
至少需要传入下载地址 URL,不支持嵌套 HLS 格式,仅支持单码流的 HLS 下载。userName 不传入具体值时,默认为 "default"。
const mediaInfo = await TXVodDownloadManager.startDownloadUrl(
'https://example.com/video.mp4',
921600, // 期望分辨率
'default' // 用户标识
);

步骤3:任务信息与监听

// 添加进度监听
const removeProgress = TXVodDownloadManager.addProgressListener((event) => {
const { progress, speed } = event.mediaInfo;
console.log(`下载进度: ${(progress * 100).toFixed(1)}%, 速度: ${speed}KB/s`);
});

// 添加完成监听
const removeFinish = TXVodDownloadManager.addFinishListener((event) => {
console.log('下载完成:', event.mediaInfo.playPath);
// 使用 playPath 播放离线视频
player.startPlay(event.mediaInfo.playPath);
});

// 添加错误监听
const removeError = TXVodDownloadManager.addErrorListener((event) => {
console.error('下载错误:', event.errorCode, event.errorMsg);
});
可能收到的任务事件有:
事件
说明
DownloadState.START
任务开始,表示 SDK 已经开始下载。
DownloadState.FINISH
下载完成,收到此回调表示已全部下载。此时下载文件可以给 TXVodPlayer 播放。
DownloadState.STOP
任务停止,当您调用 stopDownload 停止下载,收到此消息表示停止成功。
DownloadState.ERROR
下载错误,下载过程中遇到网络断开会回调此接口,同时下载任务停止。

步骤4:中断下载

停止下载请调用 stopDownload() 方法,参数为开始下载时返回的 mediaInfo 对象。SDK 支持断点续传,当下载目录没有发生改变时,下次下载同一个文件时会从上次停止的地方重新开始。
TXVodDownloadManager.stopDownload(mediaInfo);

步骤5:管理下载

// 获取所有下载任务
const list = await TXVodDownloadManager.getDownloadMediaInfoList();

// 根据 URL 获取下载信息
const info = await TXVodDownloadManager.getDownloadMediaInfo(url);

// 删除下载(包括本地文件)
const success = TXVodDownloadManager.deleteDownloadMediaInfo(mediaInfo);

步骤6:播放离线视频

通过以上步骤获取到的 mediaInfo 的 downloadState 为 DownloadState.FINISH,并且 mediaInfo 的 playPath 有值,则代表视频缓存完成,可以直接传给播放器进行播放:
const cacheVideoUrl = cacheMediaInfo.playPath;
player.startPlay(cacheVideoUrl);

3、加密播放

视频加密方案主要用于在线教育等需要对视频版权进行保护的场景。如果要对您的视频资源进行加密保护,就不仅需要在播放器上做改造,还需要对视频源本身进行加密转码,亦需要您的后台和终端研发工程师都参与其中。在 视频加密解决方案 中您会了解到全部细节内容。
在腾讯云控制台提取到 appId,加密视频的 fileId 和 psign(可参见 签名介绍和生成方式)后,可以通过下面的方式进行播放:
// psign 即播放器签名
player.startPlayWithFileId(
1500005830, // appId
'387702307091793695', // fileId
'your_psign' // 播放签名
);

4、HEVC 自适应降级播放

播放器支持同时传入 HEVC 和其它视频编码格式。例如:H.264 的播放链接,当播放机型不支持 HEVC 格式时,将自动降级为配置的其它编码格式(如:H.264)的视频播放。
注意:
此功能需要播放器高级版 License 支持。
import { TXVodConstants } from 'react-native-superplayer';

// 设置 HEVC 降级配置
player.setExtendedOption({
// 指定原始视频编码类型为 HEVC
[TXVodConstants.VOD_KEY_VIDEO_CODEC_TYPE]: TXVodConstants.VIDEO_CODEC_HEVC,
// 设置 H.264 格式的备选播放链接
[TXVodConstants.VOD_KEY_BACKUP_URL]: 'https://example.com/video_h264.mp4',
// 可选:设置备选资源的媒体类型
[TXVodConstants.VOD_KEY_BACKUP_URL_MEDIA_TYPE]: TXVodConstants.MEDIA_TYPE_AUTO,
});

// 播放 HEVC 视频,不支持时 SDK 会自动降级到备选 URL
player.startPlay('https://example.com/video_hevc.mp4');

5、播放器配置

在调用 startPlay 之前可以通过 setConfig 对播放器进行参数配置,例如:设置播放器连接超时时间、设置进度回调间隔、设置缓存文件个数等配置。
import type { TXVodPlayConfig } from 'react-native-superplayer';

const config: TXVodPlayConfig = {
// 网络配置
connectRetryCount: 3, // 断连重试次数
connectRetryInterval: 3, // 重连间隔(秒)
timeout: 10, // 连接超时(秒)

// Seek 配置
enableAccurateSeek: true, // 开启精准 Seek

// 进度回调
progressInterval: 500, // 进度回调间隔(毫秒)

// 缓冲配置
maxBufferSize: 50, // 最大播放缓冲(MB)
maxPreloadSize: 10, // 预加载缓冲(MB)

// 清晰度配置
preferredResolution: 921600, // HLS 起播优选分辨率(1280×720)

// 字幕回调
extInfoMap: {
'450': 0, // 开启字幕文本回调
},

// 自定义 HTTP Header
headers: {
'User-Agent': 'MyApp/1.0',
},
};

player.setConfig(config);
完整配置项说明:
参数
类型
默认值
说明
connectRetryCount
number
3
断连重试次数。
connectRetryInterval
number
3
重连间隔(秒,范围 3-30)。
timeout
number
10
连接超时时间(秒)。
enableAccurateSeek
boolean
true
是否开启精准 Seek。
autoRotate
boolean
true
MP4 是否自动旋转。
smoothSwitchBitrate
boolean
false
是否平滑切换码率。
progressInterval
number
500
进度回调间隔(毫秒)。
maxBufferSize
number
-
最大播放缓冲(MB)。
maxPreloadSize
number
-
预加载缓冲(MB)。
preferredResolution
number
-
HLS 起播优选分辨率。
headers
object
-
自定义 HTTP Header。
preferredAudioTrack
string
-
启播优先音轨名称。
playerType
number
1
播放器类型(0:系统播放器;1:自研播放器)。
mediaType
number
0
媒资类型(0:自动)。
extInfoMap
object
-
扩展配置。

启播前指定分辨率

播放 HLS 的多码率视频源,如果您提前知道视频流的分辨率信息,可以在启播前优先指定播放的视频分辨率。播放器会查找小于或等于偏好分辨率的流进行启播,启播后没有必要再通过 setBitrateIndex 切换到需要的码流。
const config: TXVodPlayConfig = {
// 传入参数为视频宽和高的乘积(宽 × 高),可以自定义值传入
preferredResolution: 720 * 1280,
};
player.setConfig(config);

启播前指定媒资类型

当提前知道播放的媒资类型时,可以通过配置 mediaType 减少播放器 SDK 内部播放类型探测,提升启播速度。
const config: TXVodPlayConfig = {
mediaType: TXVodConstants.MEDIA_TYPE_FILE_VOD, // 用于提升 MP4 启播速度
// 或
mediaType: TXVodConstants.MEDIA_TYPE_HLS_VOD, // 用于提升 HLS 启播速度
};
player.setConfig(config);

6、全局缓存配置

全局缓存配置影响所有播放器实例,建议在 App 启动时设置一次:
import { RNTXPlayerGlobalSetting } from 'react-native-superplayer';

// 设置缓存目录(使用相对路径)
// Android: sdcard/Android/data/{包名}/files/txcache
// iOS: Documents/txcache
RNTXPlayerGlobalSetting.setCacheFolderPath('txcache');

// 设置最大缓存大小(MB)
RNTXPlayerGlobalSetting.setMaxCacheSize(500);

// 获取当前缓存目录
const cachePath = RNTXPlayerGlobalSetting.getCacheFolderPath();

// 获取当前最大缓存大小
const maxSize = RNTXPlayerGlobalSetting.getMaxCacheSize();

// 开启 License 柔性校验(首次启动来不及校验时使用)
RNTXPlayerGlobalSetting.setLicenseFlexibleValid(true);

播放器事件监听

您可以通过 TXVodPlayersetListener 来监听播放器的播放事件,向您的应用程序同步信息。

播放事件通知(onPlayEvent)

事件 ID
数值
含义说明
VOD_PLAY_EVT_PLAY_BEGIN
2004
视频播放开始。
VOD_PLAY_EVT_PLAY_PROGRESS
2005
视频播放进度,会通知当前播放进度、加载进度和总体时长。
VOD_PLAY_EVT_PLAY_LOADING
2007
视频播放 loading,如果能够恢复,之后会有 VOD_PLAY_EVT_VOD_LOADING_END 事件。
VOD_PLAY_EVT_VOD_LOADING_END
2014
视频播放 loading 结束,视频继续播放。
VOD_PLAY_EVT_SEEK_COMPLETE
2019
Seek 完成。

结束事件

事件 ID
数值
含义说明
VOD_PLAY_EVT_PLAY_END
2006
视频播放结束。
VOD_PLAY_ERR_NET_DISCONNECT
-2301
网络断连,且经多次重连亦不能恢复,更多重试请自行重启播放。
VOD_PLAY_ERR_FILE_NOT_FOUND
-2303
文件不存在。
VOD_PLAY_ERR_HLS_KEY
-2305
HLS 解密 key 获取失败。

警告事件

如下的这些事件您可以不用关心,它只是用来告知您 SDK 内部的一些事件。
事件 ID
数值
含义说明
VOD_PLAY_ERR_HEVC_DECODE_FAIL
-2304
H.265 解码失败。
VOD_PLAY_ERR_GET_PLAYINFO_FAIL
-2306
获取点播信息失败。
VOD_PLAY_ERR_INVALID_LICENCE
-5
License 不合法。

连接事件

连接服务器的事件,主要用于测定和统计服务器连接时间:
事件 ID
数值
含义说明
VOD_PLAY_EVT_VOD_PLAY_PREPARED
2013
播放器已准备完成,可以播放。设置了 autoPlay 为 false 之后,需要在收到此事件后,调用 resume 才会开始播放。
VOD_PLAY_EVT_RCV_FIRST_I_FRAME
2003
网络接收到首个可渲染的视频数据包(IDR)。
VOD_PLAY_EVT_HIT_CACHE
2002
命中本地缓存。

画面事件

以下事件用于获取画面变化信息:
事件 ID
数值
含义说明
VOD_PLAY_EVT_CHANGE_RESOLUTION
2009
视频分辨率改变。

轨道事件

事件 ID
数值
含义说明
VOD_PLAY_EVT_SELECT_TRACK_COMPLETE
2020
切换轨道完成。
VOD_PLAY_EVT_LOOP_ONCE_COMPLETE
6001
循环一轮播放结束。
通过 setListener 获取视频播放过程信息示例:
player.setListener({
onPlayEvent: (event, param) => {
switch (event) {
case TXVodConstants.VOD_PLAY_EVT_VOD_PLAY_PREPARED:
console.log('准备完成');
break;

case TXVodConstants.VOD_PLAY_EVT_PLAY_BEGIN:
console.log('播放开始');
break;

case TXVodConstants.VOD_PLAY_EVT_PLAY_PROGRESS:
const current = param[TXVodConstants.EVT_PLAY_PROGRESS_MS] / 1000;
const duration = param[TXVodConstants.EVT_PLAY_DURATION_MS] / 1000;
console.log(`进度: ${current}s / ${duration}s`);
break;

case TXVodConstants.VOD_PLAY_EVT_PLAY_END:
console.log('播放结束');
break;

case TXVodConstants.VOD_PLAY_EVT_CHANGE_RESOLUTION:
const width = param[TXVodConstants.EVT_PARAM1];
const height = param[TXVodConstants.EVT_PARAM2];
console.log(`分辨率变化: ${width}x${height}`);
break;

default:
if (event < 0) {
const msg = param[TXVodConstants.EVT_DESCRIPTION];
console.error(`播放错误 [${event}]: ${msg}`);
}
}
},
});

播放状态反馈(onNetStatus)

状态反馈每 0.5 秒都会被触发一次,目的是实时反馈当前的播放器状态,它就像汽车的仪表盘,可以告知您目前 SDK 内部的一些具体情况,以便您能对当前视频播放状态等有所了解。
评估参数
含义说明
NET_SPEED
当前的网络数据接收速度,单位 Kbps。
VIDEO_FPS
当前流媒体的视频帧率。
VIDEO_BITRATE
当前流媒体的视频码率,单位 Kbps。
AUDIO_BITRATE
当前流媒体的音频码率,单位 Kbps。
VIDEO_CACHE
缓冲区(jitterbuffer)大小,缓冲区当前长度为 0,说明离卡顿不远了。
VIDEO_WIDTH
视频分辨率 - 宽。
VIDEO_HEIGHT
视频分辨率 - 高。
通过 onNetStatus 获取视频播放过程信息示例:
player.setListener({
onNetStatus: (param) => {
const speed = param.NET_SPEED;
const videoWidth = param.VIDEO_WIDTH;
const videoHeight = param.VIDEO_HEIGHT;
},
// ...
});

字幕数据回调(onSubtitleData)

player.setListener({
onSubtitleData: (data) => {
// data.subtitleData: 字幕文本(空串表示清屏)
// data.trackIndex: 字幕轨道索引

if (data.subtitleData) {
setSubtitleText(data.subtitleData);
} else {
setSubtitleText(''); // 清屏
}
},
// ...
});