Player

本文档主要提供播放器模块下的播放器使用方式 Api 文档。

一、创建播放器

通过 setupPlayer 创建观看页的播放器。

lowLatency 参数负责控制播放器是否使用无延迟播放，开启后若当前为无延迟频道并且设备支持无延迟播放则使用无延迟进行播放，开发者可通过 supportLowLatency 方法判断当前环境和频道是否支持无延迟。

通过 PlayerEvents.PlayerInited 监听播放器创建并初始化完成事件，当触发该事件后即可调用播放器模块的其他方法，如：play、pause。

Api 方法： setupPlayer(options: SetupPlayerOptions): Promise<void>

参数说明：

• options：创建参数，SetupPlayerOptions 类型，必传，详细类型说明如下

参数名	说明	类型	必须	默认值
container	创建容器	HTMLDivElement	是	-
lowLatency	是否使用无延迟播放	boolean	否	false
playbackOptions	回放参数	SetupPlayerPlaybackOptions	否	-
autoplay	是否自动播放	boolean	否	根据后台设置
barrageEnabled	弹幕功能开关	boolean	否	根据后台设置
barrageShow	弹幕默认是否显示	boolean	否	根据后台设置
barrageSpeed	弹幕速度	number	否	根据后台设置
barrageSize	弹幕字号	number	否	根据后台设置
barrageDirection	弹幕位置对应的显示方向	IDirection	否	默认顶部, 自上向下
barragePercent	弹幕位置对应的显示百分比, 取值范围0~1	number	否	默认顶部, 1/4
barrageLocationId	弹幕位置对应的ID	number	否	默认顶部, 0
barrageAlpha	弹幕透明度, 取值范围0~100	number	否	默认80
barrageAutoAdd	自动监听消息事件添加弹幕	boolean	否	true
language	语言，0-中文，1-英文	0 | 1	否	0
languageStreamEnabled	双语流功能	boolean	否	根据后台设置
streamTrackKey	languageStreamEnabled	string	否	-
showController	是否显示控制栏	boolean	否	true
skinConfig	皮肤设置	LivePlayerUISkinConfig	否	-
fullScreenMode	全屏模式	FullScreenMode	否	根据后台配置
audioSwitchEnabled	显示音频切换，仅移动端支持	boolean	否	根据后台配置
banHeaderAdvertisement	是否禁用片头广告	boolean	否	false
banPassword	是否禁用播放密码	boolean	否	false
autoChangePlayback	是否自动切换回放(仅支持直播暂存视频)	boolean	否	false

示例：

await watchCore.player.setupPlayer({
  container: 'NodeElement',
  lowLatency: true, // 使用无延迟播放
});

二、获取播放器信息

播放器模块会保存播放器的状态信息，通过 getPlayerInfo 方法获取当前播放的所有状态。

Api 方法： getPlayerInfo(): PlayerStoreInfo

返回值说明： 播放器信息，PlayerStoreInfo 类型，详细类型说明如下

属性名	说明	类型
playerInited	播放器是否初始化完成	boolean
supportRefresh	是否支持刷新	boolean
supportAutoPlay	是否支持自动播放	boolean
supportLanguageStream	是否支持多语流	boolean
supportLowLatency	是否支持无延迟播放	boolean
isLowLatency	当前是否无延迟播放	boolean
playStatus	播放状态	PlayStatus
barrageShow	弹幕显示状态	boolean
supportBarrageSpeed	是否支持弹幕速度切换	boolean
currentBarrageSpeed	弹幕速度	number
barrageSpeedDefaultGrade	弹幕速度默认档位	number
supportBarrageSize	是否支持弹幕字号切换	boolean
currentBarrageSize	弹幕字号	number
barrageSizeDefaultGrade	弹幕字号默认档位	number
supportBarrageLocation	是否支持弹幕字号切换	boolean
barrageLocationDefaultId	默认弹幕位置ID	number
currentBarrageLocationIndex	当前弹幕位置ID	number
supportBarrageAlpha	是否支持弹幕透明度切换	boolean
barrageDefaultAlpha	默认弹幕透明度	number
currentBarrageAlpha	当前弹幕透明度	number
currentVolume	当前音量	number
lineCount	总线路数	number
currentLine	当前线路索引	number
qualityLevels	可选的清晰度列表	QualityLevelItem[]
currentQualityLevel	当前清晰度级别	number
rateList	可选的倍速列表	number[]
currentRate	当前倍速	number
durationTime	播放总时长，单位：秒	number
currentTime	当前播放进度，单位：秒	number
supportTimeAxisMark	是否支持时间轴标记	boolean
supportLiveTimeShift	是否支持直播时移	boolean
stopLivePlayEnabled	直播时是否显示播放按钮， 默认开	boolean
playbackMultiplierEnabled	回放时是否显示倍速按钮，默认开	boolean
playbackProgressBarEnabled	回放时是否显示进度条，默认开	boolean
playbackShowPlayButtonEnabled	回放时是否显示左下角播放/暂停按钮，默认开	boolean
loopPlayEnabled	回放时是否循环播放，列表播放播放完最后一个视频会暂停播放，默认开	boolean
pcPlayerVersion	播放器版本，目前仅支持pc播放器	string
newPlayerPauseStyleEnabled	是否开启播放器新版暂停样式	boolean
recordFileAudioUrl	录制文件音频流地址	string

示例：

const playerInfo = watchCore.player.getPlayerInfo();
console.log('播放状态', playerInfo.playStatus); // playing or pause
console.log('是否支持无延迟', playerInfo.supportLowLatency);
console.log('是否无延迟', playerInfo.isLowLatency);

三、无延迟

3.1 是否支持无延迟观看

通过 supportLowLatency 方法获取当前环境和频道是否支持无延迟观看。

Api 方法： supportLowLatency(): SupportResult

返回值说明： 支持结果，SupportResult 类型

示例：

const supportResult = watchCore.player.supportLowLatency();
if (supportResult.support) {
  console.log('支持无延迟观看');
} else {
  console.log('不支持无延迟观看');
}

四、播放/暂停

4.1 恢复视频播放

通过 play 方法触发播放器播放直播流或视频。

Api 方法： play(): void

示例：

// 恢复播放
watchCore.player.play();

4.2 冻结视频播放

Api 方法： freezePlay(isFreeze: boolean): void

参数说明：

• isFreeze：undefined，boolean 类型，必传

示例：

// 冻结播放
watchCore.player.freezePlay(true);

4.3 暂停视频播放

通过 pause 方法暂停视频播放。

Api 方法： pause(): void

示例：

// 暂停播放
watchCore.player.pause();

4.4 停止拉流

通过 stop 方法停止视频拉流，暂支持无延迟停止拉流 可通过 play 方法恢复播放

Api 方法： stop(): void

示例：

// 停止拉流
watchCore.player.stop();

五、刷新

5.1 是否支持刷新

通过 supportRefresh 方法判断当前是否支持刷新直播流，判断条件：

• 频道正在直播

• 播放器初始化完成

• 非无延迟频道

• 当前用户未连麦

Api 方法： supportRefresh(): SupportResult

返回值说明： 支持结果，SupportResult 类型

示例：

const supportResult = watchCore.player.supportRefresh();
if (supportResult.support) {
  console.log('支持刷新，显示刷新按钮');
} else {
  console.log('不支持刷新，隐藏刷新按钮');
}

5.2 刷新直播流

通过 refresh 刷新当前直播流，注意需要根据 supportRefresh 方法或 getPlayerInfo 方法判断是否当前是否支持刷新直播流。

Api 方法： refresh(): void

示例：

const playerInfo = watchCore.player.getPlayerInfo();
if (playerInfo.supportRefresh) {
  watchCore.player.refresh();
}

六、音量

6.1 设置视频音量

通过 setVolume 方法设置当前播放器视频的音量。

Api 方法： setVolume(volume?: number): void

参数说明：

• volume：音量，范围：0～1，number 类型，选传，默认 1

示例：

// 静音播放器
watchCore.player.setVolume(0);
// 设为 70% 音量
watchCore.player.setVolume(0.7);

6.2 获取视频音量

通过 getCurrentVolume 获取当前播放器的视频音量，除了该 Api 外你也可以通过 playerInfo 获取当前音量。

Api 方法： getCurrentVolume(): number

返回值说明： 音量，范围：0～1

示例：

// 通过 api 获取
const volume = watchCore.player.getCurrentVolume();
console.log('当前音量', volume);
// 通过状态获取
const playerInfo = watchCore.player.getPlayerInfo();
console.log('当前音量', playerInfo.currentVolume);

七、弹幕

7.1 添加弹幕

通过 addBarrage 添加弹幕，在创建播放器传入 barrageAutoAdd 为 true 时，播放器模块会自动监听聊天消息事件，当有观众发言时会自动将消息文本插入到弹幕中。

Api 方法： addBarrage(options: BarrageAddOptions): void

参数说明：

• options：弹幕参数，BarrageAddOptions 类型，必传

示例：

// 添加弹幕消息
watchCore.player.addBarrage({
  msg: '今天天气真好',
});
// 带有表情
watchCore.player.addBarrage({
  msg: '老师讲的真好[大笑][大笑]',
});

7.2 设置弹幕显示状态

创建播放器时传入 barrageEnabled 为 true 时，通过 setBarrageShow 方法切换弹幕都显示和隐藏状态。

Api 方法： setBarrageShow(show: boolean): void

参数说明：

• show：弹幕显示状态，boolean 类型，必传

示例：

// 显示弹幕
watchCore.player.setBarrageShow(true);
// 隐藏弹幕
watchCore.player.setBarrageShow(false);

7.3 是否支持弹幕速度切换

通过 supportBarrageSpeed 获取播放器是否支持弹幕速度切换。

Api 方法： supportBarrageSpeed(): SupportResult

返回值说明： SupportResult 类型

示例：

const supportResult = watchCore.player.supportBarrageSpeed();
if (supportResult.support) {
  console.log('显示弹幕速度切换');
} else {
  console.log('隐藏弹幕速度切换');
}

7.4 切换弹幕速度

当观众想要显示更快或更慢的弹幕速度时，可调用 setBarrageSpeed 设置弹幕滚动速度。 注意播放器模块会记录用户切换的弹幕速度，调用 setupPlayer 没有传入 barrageSpeed 时会优先使用本地缓存的速度。

注意需要通过 supportBarrageSpeed 方法获取当前播放器是否支持弹幕速度切换。

弹幕速度值最大不得超过 400

Api 方法： setBarrageSpeed(speed: number): void

参数说明：

• speed：弹幕速度，number 类型，必传

示例：

// 缓慢速度
watchCore.player.setBarrageSpeed(340);
// 较慢速度
watchCore.player.setBarrageSpeed(270);
// 标准速度
watchCore.player.setBarrageSpeed(200);
// 较快速度
watchCore.player.setBarrageSpeed(130);
// 快速速度
watchCore.player.setBarrageSpeed(60);

7.5 是否支持弹幕字号切换

Api 方法： supportBarrageSize(): SupportResult

返回值说明： SupportResult 类型

示例：

const supportResult = watchCore.player.supportBarrageSize();
if (supportResult.support) {
  console.log('显示弹幕字号切换');
} else {
  console.log('隐藏弹幕字号切换');
}

7.6 切换弹幕字号

Api 方法： setBarrageSize(size: number): void

参数说明：

• size：弹幕字号，number 类型，必传

示例：

// 较小
watchCore.player.setBarrageSize(12);
// 小
watchCore.player.setBarrageSize(16);
// 标准
watchCore.player.setBarrageSize(20);
// 大
watchCore.player.setBarrageSize(24);
// 较大
watchCore.player.setBarrageSize(28);

7.7 是否支持弹幕位置切换

Api 方法： supportBarrageLocation(): SupportResult

返回值说明： SupportResult 类型

示例：

const supportResult = watchCore.player.supportBarrageLocation();
if (supportResult.support) {
  console.log('显示弹幕位置切换');
} else {
  console.log('隐藏弹幕位置切换');
}

7.8 获取弹幕位置信息

Api 方法： getBarrageLocationSetting(): BarrageLocationInfo[]

返回值说明： BarrageLocationInfo[] 类型

示例：

const locationInfo = watchCore.player.getBarrageLocationSetting();
locationInfo.forEach(item => {
  console.info('位置类型:', item.type, '位置ID:', item.index);
});

7.9 切换弹幕位置

Api 方法： setBarrageLocation(index: number): void

参数说明：

• index：切换弹幕位置的ID，number 类型，必传

示例：

watchCore.player.setBarrageLocation(index);

7.10 是否支持弹幕透明度切换

Api 方法： supportBarrageAlpha(): SupportResult

返回值说明： SupportResult 类型

示例：

const supportResult = watchCore.player.supportBarrageAlpha();
if (supportResult.support) {
  console.log('显示弹幕透明度切换');
} else {
  console.log('隐藏弹幕透明度切换');
}

7.11 切换弹幕透明度

当观众想要弹幕文本显示不同的透明度，可调用 setBarrageAlpha 设置弹幕文本的透明度。

注意需要通过 supportBarrageAlpha 方法获取当前播放器是否支持弹幕透明度切换。

Api 方法： setBarrageAlpha(alpha: number): void

参数说明：

• alpha：切换弹幕透明度, 取值范围0~100，number 类型，必传

示例：

watchCore.player.setBarrageAlpha(80);

7.12 更新弹幕显示区域

在点击全屏按钮，实现网页全屏或者css旋转横屏场景下需要更新弹幕区域显示高度

Api 方法： resizeBarrage(): void

八、线路

8.1 获取线路总数

通过 getLineCount 获取当前播放器可切换的总线路数，除了该 Api 外你也可以通过 playerInfo 获取总线路数。

Api 方法： getLineCount(): number

返回值说明： 可切换的线路总数

示例：

const lineCount = watchCore.player.getLineCount();
console.log('可切换的总线路数', lineCount);
// 通过状态获取
const playerInfo = watchCore.player.getPlayerInfo();
console.log('可切换的总线路数', playerInfo.lineCount);

8.2 切换线路

当用户点击切换线路时，通过 changeLine 方法切换数，线路总数可调用 getLineCount 获取。

Api 方法： changeLine(line: number): void

参数说明：

• line：线路索引，number 类型，必传

示例：

// 切换线路1
watchCore.player.changeLine(0);
// 切换线路2
watchCore.player.changeLine(1);

8.3 获取当前线路

通过 getCurrentLine 获取当前播放器的线路，除了该 Api 外你也可以通过 playerInfo 获取总线路数。

Api 方法： getCurrentLine(): number

返回值说明： 当前线路索引（从 0 开始）

示例：

const currentLine = watchCore.player.getCurrentLine();
console.log('当前线路索引', currentLine);
// 通过状态获取
const playerInfo = watchCore.player.getPlayerInfo();
console.log('当前线路索引', playerInfo.currentLine);

九、清晰度

9.1 获取可选的清晰度级别

通过 getQualityLevels 方法获取当前播放器可选的清晰度列表，除了该 Api 外你也可以通过 playerInfo 获取清晰度列表，清晰度类型可见 QualityLevelType。

Api 方法： getQualityLevels(): QualityLevelItem[]

返回值说明： 清晰度级别列表，QualityLevelItem[] 类型

示例：

const levels = watchCore.player.getQualityLevels();
levels.forEach(item => {
  console.log('清晰度类型', item.type); // auto-自动、sd-流程
  console.log('清晰度级别', item.level);
});

9.2 切换清晰度级别

获取清晰度列表(getQualityLevels)后，通过清晰度节点的 level 字段设置清晰度。

Api 方法： changeQualityLevel(level: number): void

参数说明：

• level：清晰度级别，number 类型，必传

示例：

const levels = watchCore.player.getQualityLevels();
// 切换清晰度
watchCore.player.changeQualityLevel(levels[1].level);

9.3 获取播放器清晰度级别

通过 getCurrentQualityLevel 方法获取当前播放器所在的清晰度级别，除了该 Api 外你也可以通过 playerInfo 获取清晰度级别。

Api 方法： getCurrentQualityLevel(): number

返回值说明： 清晰度级别

示例：

const qualityLevel = watchCore.player.getCurrentQualityLevel();
console.log('当前清晰度级别', qualityLevel);
// 通过状态获取
const playerInfo = watchCore.player.getPlayerInfo();
console.log('当前清晰度级别', playerInfo.currentQualityLevel);

十、倍速

10.1 获取可选的倍速列表

通过 getRateList 获取当前播放器可选的倍速列表，除了该 Api 外你也可以通过 playerInfo 获取倍速列表。

Api 方法： getRateList(): number[]

返回值说明： 可选的倍速列表，number[] 类型

示例：

const rateList = watchCore.player.getRateList();
console.log('可选的倍速列表', rateList);

10.2 切换倍速

获取倍速列表后通过 changeRate 切换倍速。

Api 方法： changeRate(rate: number): void

参数说明：

• rate：倍速，number 类型，必传

示例：

const rateList = watchCore.player.getRateList();
// 切换倍速
watchCore.player.changeRate(rateList[4]);

10.3 获取播放器倍速

通过 getCurrentRate 获取播放器的倍速。

Api 方法： getCurrentRate(): number

返回值说明： 播放器倍速

示例：

const currentRate = watchCore.player.getCurrentRate();
console.log('当前倍速', currentRate);

十一、回放

11.1 获取回放播放时间

在回放下，通过 getCurrentTime 获取播放器的回放播放时间，除了该 Api 外你也可以通过 playerInfo 获取播放时间，如果当前播放的是直播流，该方法固定返回 0。

Api 方法： getCurrentTime(): number

返回值说明： 播放时间，单位秒

示例：

const currentTime = watchCore.player.getCurrentTime();
console.log('当前回放播放时间', currentTime);

11.2 获取回放播放总时长

在回放下，通过 getDurationTime 获取播放器的回放总时长，除了该 Api 外你也可以通过 playerInfo 获取回放总时长，如果当前播放的是直播流，该方法固定返回 0。

Api 方法： getDurationTime(): number

返回值说明： 回放总时长，单位秒

示例：

const durationTime = watchCore.player.getDurationTime();
console.log('当前回放播放总时长', durationTime);

11.3 设置播放进度

当观众拖拽回放进度条时，通过 seekVideo 设置回放播放进度。

Api 方法： seekVideo(time: number): void

参数说明：

• time：播放时间，单位秒，number 类型，必传

示例：

// 切到 1 分 20 秒
watchCore.player.seekVideo(120);

11.4 是否支持回放视频

Api 方法： supportPlaybackVideo(): SupportResult

返回值说明： SupportResult 类型

11.5 是否能自动切回放

从 v1.0.0 版本开始通过观看页 SDK 内部流程，会自行在直播结束后自动尝试切回放

Api 方法： getAutoChangePlaybackEnabled(): boolean

11.6 切换回放

通过 changePlayback 切换回放视频。

Api 方法： changePlayback(playbackOptions: SetupPlayerPlaybackOptions): Promise<void>

参数说明：

• playbackOptions：回放参数，SetupPlayerPlaybackOptions 类型，必传

示例：

watchCore.player.changePlayback({
  // 切换参数
});

11.7 更新播放器回放字幕选择组件的文案和显示状态

Api 方法： setPlayerReplaySubtitleSelectConfig(config: SubtitleSelectBtnConfig): void

参数说明：

• config：undefined，SubtitleSelectBtnConfig 类型，必传，详细类型说明如下

参数名	说明	类型	必须	默认值
index	-	number	是	-
show	-	boolean	否	-
text	-	string	否	-

十二、播放器设置

12.1 获取播放器设置

用于获取管理后台设置的播放器信息。

fullScreenMode 需要在 PlayerEvents.PlayerInited 触发后获取才是最终值

Api 方法： getPlayerSetting(): PlayerSetting

返回值说明： 播放器设置，PlayerSetting 类型，详细类型说明如下

属性名	说明	类型
playerFullscreenEnabled	播放器是否支持全屏	boolean
portraitPlayerFullscreenEnabled	竖屏播放器是否支持全屏	boolean
mobileAudioEnabled	移动端音视频切换开关	boolean
fullScreenMode	播放器全屏模式	FullScreenMode

示例：

const setting = watchCore.player.getPlayerSetting();
console.log('移动端音视频切换开关', setting.mobileAudioEnabled);

12.2 获取播放器 logo 设置

用于获取管理后台设置的播放器 logo 信息。

从 v1.2.0 开始可以通过 PlvPlayerModule.generateDefaultPlayerLogoSetting() 来获取默认配置

Api 方法： getPlayerLogoSetting(): PlayerLogoSetting

返回值说明： 播放器 logo 设置，PlayerLogoSetting 类型，详细类型说明如下

属性名	说明	类型
logoImage	logo 图片地址	undefined | string
logoHref	logo 跳转地址	undefined | string
logoOpacity	logo 透明度	number
logoPosition	logo 位置	PlayerLogoPosition

示例：

const logoSetting = watchCore.player.getPlayerLogoSetting();
console.log('logo 图片', logoSetting.logoImage);
console.log('logo 跳转链接', logoSetting.logoHref);

12.3 获取播放器暖场设置信息

用于获取管理后台设置的播放器暖场信息，注意暖场设置有一定延迟，需要通过 PlayerEvents.PlayerWarmUpSettingChange 事件监听信息更新。

Api 方法： getPlayerWarmUpSetting(): PlayerWarmUpSetting

返回值说明： 播放器暖场设置，PlayerWarmUpSetting 类型，详细类型说明如下

属性名	说明	类型
warmUpType	暖场类型	WarmUpType
warmUpImg	暖场图片地址	string
warmUpLargeImg	暖场大图图片地址	string
warmUpVideo	暖场视频地址	string
warmUpHref	暖场图片点击跳转地址	string

示例：

watchCore.player.eventEmitter.on(PlayerEvents.PlayerWarmUpSettingChange, () => {
  const setting = watchCore.player.getPlayerWarmUpSetting();
  console.log('暖场类型', setting.warmUpType);
  console.log('暖场图片地址', setting.warmUpImg);
  console.log('暖场视频地址', setting.warmUpVideo);
});

十三、时移打点

13.1 是否支持直播时移

通过 supportLiveTimeShift 获取播放器否支持直播时移

Api 方法： supportLiveTimeShift(): SupportResult

返回值说明： SupportResult 类型

示例：

const supportResult = watchCore.player.supportLiveTimeShift();
if (supportResult.support) {
  console.log('支持直播时移');
} else {
  console.log('不支持直播时移');
}

13.2 是否支持时间轴标记

通过 supportTimeAxisMark 获取播放器是否支持时间轴标记。注意，直播打点需要直播时移也开启了，才能正常返回 true

Api 方法： supportTimeAxisMark(): SupportResult

返回值说明： SupportResult 类型

示例：

const supportResult = watchCore.player.supportTimeAxisMark();
if (supportResult.support) {
  console.log('支持时间轴标记');
} else {
  console.log('不支持时间轴标记');
}

十四、实时字幕

14.1 改变实时字幕播放器的开关展示

通过 changeSubtitleSkinShow 改变实时字幕播放器的开关展示

Api 方法： changeSubtitleSkinShow(show: boolean): void

参数说明：

• show：undefined，boolean 类型，必传

返回值说明： void

示例：

watchCore.player.changeSubtitleSkinShow(true);

十五、画中画

15.1 获取"是否开启画中画功能"

Api 方法： getPIPEnabled(): boolean

15.2 获取"是否开启IOS系统画中画功能"

Api 方法： getPIPForIOSEnabled(): boolean

十六、销毁

16.1 销毁播放器

页面或组件销毁前调用 destroyPlayer 销毁播放器。

Api 方法： destroyPlayer(): Promise<void>

示例：

watchCore.player.destroyPlayer();