SEPG框架-播放器组件使用手册

返回目录

SEPG框架-播放器组件使用手册

  • 框架版本: 2.1.0
  • 文档版本: 1.0.0
  • 生成时间: 2026-03-19 10:58:18

1. 概述

SEPG框架播放器组件是基于STB原生播放器封装的通用媒体播放器类，支持：

播放器组件提供了完整的播放控制、音量调节、进度监听、事件回调等功能。

2. 类型定义

2.1 播放器状态枚举 ISTATUS

播放器支持的所有播放状态：

export type ISTATUS = 'INIT' | 'PLAY' | 'FORWARD' | 'REWIND' | 'PAUSE' | 'STOP' | 'ERROR';

2.2 STATUS 常量

/**
 * 播放器状态枚举
 * @readonly
 */
export const STATUS = {
  /** 初始化 */ INIT: 'INIT',
  /** 播放 */ PLAY: 'PLAY',
  /** 快进倍速播放 */ FORWARD: 'FORWARD',
  /** 快退倍速播放 */ REWIND: 'REWIND',
  /** 暂停 */ PAUSE: 'PAUSE',
  /** 停止 */ STOP: 'STOP',
  /** 错误 */ ERROR: 'ERROR'
}

2.3 基础配置接口 BaseConfig

定义播放器位置和尺寸：

interface BaseConfig {
  left: number;    // 播放器left值
  top: number;     // 播放器top值
  width: number;   // 播放器宽度
  height: number;  // 播放器高度
}

2.4 媒体事件类型 MediaEvent

type MediaEvent = { 
  type: string; 
  source: string; 
};

2.5 监听事件类型 MediaType

type MediaType = 'all' | 'start' | 'end' | 'error' | 'resume' | 'change' | 'release';

3. Player 类

通用播放器类，封装了所有播放器核心功能。

3.1 公有属性

属性 类型 说明 默认值
display boolean 当前是否为显示状态(通过show、hide方法切换) true
type number 播放器类型 0 点播 1 直播 0

3.2 构造函数

constructor(config: BaseConfig, type?: 'PIP' | 'MOSAIC' | 'VR')

参数说明：

3.3 显示/隐藏控制

hide() - 隐藏播放器

hide(): Player

将播放器移出可视区域并暂停视频显示，设置 display = false。 返回： 当前播放器实例，支持链式调用

show() - 显示播放器

show(): Player

将播放器移回配置的位置并显示，设置 display = true。 返回： 当前播放器实例，支持链式调用

3.4 事件监听

addEventListener() - 添加事件监听器

addEventListener(type: MediaType, handler: (ev?: MediaEvent) => void): void

参数说明：

player.addEventListener('start', (ev) => {
  console.log('播放开始', ev);
});

3.5 海报相关

setPoster() - 设置海报元素

setPoster(poster: HTMLElement | null): Player

参数： poster - 海报DOM元素，传入null移除海报
返回： 当前播放器实例，支持链式调用

getPoster() - 获取海报元素

getPoster(): any

返回： 包装后的海报元素对象

3.6 加载器

setLoader() - 设置加载器

setLoader(config: LoaderConfig = {}): Player

参数：

3.7 播放控制

togglePlay() - 切换播放/暂停

togglePlay(): ISTATUS

如果当前是播放状态则暂停，如果是暂停/停止状态则恢复播放。
返回： 当前播放器状态 ISTATUS

resume() - 恢复播放

resume(): Player

恢复播放，设置状态为 PLAY，重置快进快退倍率，开始进度更新。
返回： 当前播放器实例，支持链式调用

pause() - 暂停播放

pause(): Player

暂停播放，设置状态为 PAUSE，停止进度更新。
返回： 当前播放器实例，支持链式调用

stop() - 停止播放

stop(): Player

停止播放，设置状态为 STOP，停止进度更新。
返回： 当前播放器实例，支持链式调用

3.8 音量控制

setVolumeBox() - 设置音量UI元素

setVolumeBox(volumeBox: HTMLElement, volumeInterval: number = 3000): Player

参数：

setVolume() - 设置当前音量

setVolume(volume: number): Player

参数：

getVolume() - 获取当前音量

getVolume(): number

返回： 当前音量值 (0-100)

volumeUp() - 增大音量

volumeUp(value?: number): number

参数：

volumeDown() - 减小音量

volumeDown(value?: number): number

参数：

setMuteFlag() - 设置静音标志

setMuteFlag(muteFlag: number): Player

参数：

getMuteFlag() - 获取静音标志

getMuteFlag(): number

返回： 0 非静音，1 静音

toggleMute() - 切换静音状态

toggleMute(): number

切换当前静音状态，如果当前是非静音则变为静音，如果是静音则变为非静音。
返回： 当前静音标志 0 或 1

volumeChange - 音量变化回调

volumeChange?: (percent: number, volume: number, muteFlag: number) => void;

音量变化时的回调函数，开发者可以设置此回调来更新自定义音量UI。
参数：

player.volumeChange = (percent, volume, muteFlag) => {
  console.log(`音量: ${volume}, 进度: ${percent * 100}%, 静音: ${muteFlag}`);
  // 更新你的音量UI
};

3.9 时间信息获取

getMediaDuration() - 获取影片总时长

getMediaDuration(): number

返回： 影片总时长，单位：秒(s)，直播返回当前时间相关值

getCurrentPlayTime() - 获取当前播放时间

getCurrentPlayTime(): number

返回： 当前播放时间，单位：秒(s)

3.10 快进快退

fastForward() - 倍速快进

fastForward(speed?: number): number

参数：

fastRewind() - 倍速快退

fastRewind(speed?: number): number

参数：

resetFastRate() - 重置快进退倍率

resetFastRate(): Player

将快进和快退倍率重置为 1。
返回： 当前播放器实例，支持链式调用

3.11 跳转

gotoStart() - 跳到媒体起始点播放

gotoStart(): Player

跳转到影片开头开始播放，触发进度回调。
返回： 当前播放器实例，支持链式调用

gotoEnd() - 跳到媒体末端播放

gotoEnd(): Player

跳转到影片末尾开始播放，触发进度回调。
返回： 当前播放器实例，支持链式调用

gotoStart() - 跳到媒体起始点播放

gotoStart(): Player

跳转到影片开头开始播放，触发进度回调。
返回： 当前播放器实例，支持链式调用

seek() - 基于当前时间偏移

seek(offset: number): Player

参数：

seekTo() - 跳转到指定时间位置

seekTo(breakpoint: number | string): Player

参数：

3.12 音频PID

getAudioPID() - 获取音频PID

getAudioPID(): number | null

返回音频PID，如果正在播放返回当前播放的PID，否则返回第一个PID。
返回： 音频PID 或 null

setAudioPID() - 指定播放音频ID

setAudioPID(pid: string): Player

参数：

3.13 视频显示控制

setVideoDisplayMode() - 设置视频显示模式

setVideoDisplayMode(mode: 0 | 1 | 2 | 3 | 255): Player

参数：

setVideoDisplayArea() - 设置视频显示区域

setVideoDisplayArea(left: number, top: number, width: number, height: number): Player

参数：

refreshVideoDisplay() - 刷新视频显示

refreshVideoDisplay(): Player

根据 videoDisplayMode 和 videoDisplayArea 属性，调整视频的显示。
返回： 当前播放器实例，支持链式调用

3.14 播放器状态

setStatus() - 设置播放器状态

setStatus(status: ISTATUS): Player

参数：

getStatus() - 获取播放器状态

getStatus(): ISTATUS

返回： 当前播放器状态 ISTATUS

3.15 进度监听

onProgress - 进度回调

onProgress?: (currentTime: number, totalTime: number) => void;

播放进度回调，每秒触发一次。
参数：

player.onProgress = (current, total) => {
  const percent = (current / total * 100).toFixed(1);
  console.log(`播放进度: ${percent}%`);
  // 更新进度条UI
};

updateProgress() - 开始进度更新

updateProgress(): Player

开始定时器，每秒触发一次 onProgress 回调。播放开始或恢复时自动调用。
返回： 当前播放器实例，支持链式调用

stopProgress() - 停止进度更新

stopProgress(): Player

停止进度更新定时器。暂停或停止播放时自动调用。
返回： 当前播放器实例，支持链式调用

3.16 频道相关 (直播)

getChannelNum() - 获取当前频道号

getChannelNum(): number

返回： 当前频道号，如果获取失败返回 -1

joinChannel() - 加入频道

joinChannel(channelNumber: number): Player

参数：

leaveChannel() - 退出频道

leaveChannel(): Player

退出当前频道，设置状态为 STOP。
返回： 当前播放器实例，支持链式调用

3.17 启动播放

preLoad() - 预加载媒体

preLoad(
  mediaCode: string,
  mediaURL: string,
  mediaType: 1 | 2 | 3 | 4 = 2,
  streamType: 1 | 2 | 3 | 4 = 2
): Player

参数：

startPlay() - 启动播放

startPlay(
  mediaCode: string,
  mediaURL: string,
  breakpoint: number = 0,
  mediaType: 1 | 2 | 3 | 4 = 2,
  streamType: 1 | 2 | 3 | 4 = 2
): Player

参数：

setSingleMedia() - 设置媒体参数

setSingleMedia(json: string): Player

参数：

playFromStart() - 从片头开始播放

playFromStart(): Player

从媒体开头开始播放，设置状态为 PLAY，开始进度更新。
返回： 当前播放器实例，支持链式调用

restartPlay() - 重头播放

restartPlay(): Player

跳转回 0 位置重新播放。
返回： 当前播放器实例，支持链式调用

playByTime() - 从时间戳位置开始播放

playByTime(type: number = 1, timestamp: number | string = 0, speed: number = 1): Player

参数：

3.18 释放

releaseMediaPlayer() - 释放播放器

releaseMediaPlayer(instanceId: number): Player

参数：

getNativePlayerInstanceID() - 获取原生实例ID

getNativePlayerInstanceID(): number

返回： 原生播放器实例ID，如果播放器不存在返回 -1

3.19 VR全景播放器特有方法

switchProjectionMode() - 切换渲染模式

switchProjectionMode(projectionMode: number = 0): Player

参数：

switchDirection() - 按方向移动视角

switchDirection(dir: 'left' | 'right' | 'up' | 'down' = 'left'): Player

参数：

setDirectionDelta() - 设置视角移动增量

setDirectionDelta(dirNum: number = 37): Player

参数：

setSingleOrPlaylistMode() - 设置播放列表模式

setSingleOrPlaylistMode(mode: number): Player

参数：

switchDisplayMode() - 切换显示模式

switchDisplayMode(mode: number): Player

参数：

4. 工厂方法

SEPG播放器模块提供了五个工厂函数用于创建不同类型的播放器实例：

4.1 createPlayer() - 创建点播播放器

export function createPlayer(
  config: number | BaseConfig,
  ...args: Array<number>
): Player

参数：

// 使用配置对象
let player = createPlayer({ 
  left: 0, 
  top: 0, 
  width: 1920, 
  height: 1080 
});
// 使用参数列表
let player = createPlayer(0, 0, 1920, 1080);

4.2 createLivePlayer() - 创建直播播放器

export function createLivePlayer(
  config: number | BaseConfig,
  ...args: Array<number>
): Player

用法同 createPlayer()，返回直播播放器实例 (type = 1)。

4.3 createPipPlayer() - 创建PIP画中画播放器

export function createPipPlayer(
  config: number | BaseConfig,
  ...args: Array<number>
): Player

用法同 createPlayer()，返回PIP画中画播放器实例 (type = 1)。

4.4 createMosaicPlayer() - 创建马赛克播放器

export function createMosaicPlayer(
  config: number | BaseConfig,
  ...args: Array<number>
): Player

用法同 createPlayer()，返回马赛克播放器实例 (type = 1)，用于多屏同显场景。

4.5 createVrPlayer() - 创建VR播放器

export function createVrPlayer(
  config: number | BaseConfig,
  ...args: Array<number>
): Player

用法同 createPlayer()，返回VR全景播放器实例 (type = 0)。

5. 使用示例

5.1 基础点播播放器示例

import { createPlayer, STATUS } from 'sepg';
// 1. 创建播放器实例
const player = createPlayer();
// 2. 设置加载器
player.setLoader({
  container: document.getElementById('loader-container')
});
// 3. 添加事件监听
player.addEventListener('start', (ev) => {
  console.log('播放开始');
  // 隐藏海报
  const poster = player.getPoster();
  poster.none();
});
player.addEventListener('end', () => {
  console.log('播放结束');
});
player.addEventListener('error', (ev) => {
  console.error('播放错误', ev);
});
// 4. 监听播放进度，更新进度条
player.onProgress = (currentTime, totalTime) => {
  const percent = currentTime / totalTime * 100;
  // 更新你的进度条UI
  console.log(`进度: ${percent.toFixed(1)}%`);
};
// 5. 监听音量变化，更新音量UI
player.volumeChange = (percent, volume, muteFlag) => {
  console.log(`音量: ${volume}, 静音: ${muteFlag}`);
  // 更新你的音量UI
};
// 6. 设置海报
const posterEl = document.getElementById('poster');
if (posterEl) {
  player.setPoster(posterEl);
}
// 7. 开始播放
player.startPlay(
  'video-123',           // mediaCode
  'http://example.com/video.mp4',  // 播放地址
  0                      // 从0秒开始
);
// 8. 播放控制示例
// 暂停
document.getElementById('btn-pause').addEventListener('click', () => {
  player.pause();
});
// 恢复
document.getElementById('btn-resume').addEventListener('click', () => {
  player.resume();
});
// 切换播放/暂停
document.getElementById('btn-toggle').addEventListener('click', () => {
  const status = player.togglePlay();
  console.log('当前状态:', status);
});
// 音量加
document.getElementById('vol-up').addEventListener('click', () => {
  player.volumeUp();
});
// 音量减
document.getElementById('vol-down').addEventListener('click', () => {
  player.volumeDown();
});
// 切换静音
document.getElementById('mute-toggle').addEventListener('click', () => {
  const mute = player.toggleMute();
  console.log('静音状态:', mute);
});
// 前进10秒
document.getElementById('forward').addEventListener('click', () => {
  player.seek(10);
});
// 后退10秒
document.getElementById('backward').addEventListener('click', () => {
  player.seek(-10);
});
// 跳转到指定位置(单位:秒)
function seekTo(position: number) {
  player.seekTo(position);
}
// 9. 页面卸载时释放资源
window.addEventListener('beforeunload', () => {
  const instanceId = player.getNativePlayerInstanceID();
  player.releaseMediaPlayer(instanceId);
});

5.2 直播播放器示例

import { createLivePlayer } from 'sepg';
// 创建直播播放器
const player = createLivePlayer();
// 加入频道
player.joinChannel(10); // 进入频道10
// 退出频道
// player.leaveChannel();

5.3 VR播放器使用示例

import { createVrPlayer } from 'sepg';
// 创建VR播放器
const player = createVrPlayer();
// 设置全景模式
player.switchProjectionMode(0); // 360全景
// 方向控制
player.switchDirection('left');  // 左转
player.switchDirection('right'); // 右转
player.switchDirection('up');     // 上移
player.switchDirection('down');  // 下移
// 开始播放VR视频
player.startPlay('vr-1', 'vr-video-url');

5.4 画中画示例

import { createPipPlayer } from 'sepg';
// 在右下角创建一个小窗口画中画播放器
const pipPlayer = createPipPlayer({
  left: 1580,
  top: 880,
  width: 320,
  height: 180
});
// 播放内容
pipPlayer.startPlay('pip-1', 'pip-stream-url');

6. 默认配置参数

参数 默认值 说明
left 视口left 播放器X坐标
top 视口top 播放器Y坐标
width 视口width 播放器宽度
height 视口height 播放器高度
nowVolume 50 默认音量
totalVolume 100 最大音量
step 5 音量步长
volumeInterval 3000 音量UI自动隐藏间隔(ms)
forwardSpeed 1 默认快进倍率
rewindSpeed 1 默认快退倍率
display true 初始显示状态
type 0 播放器类型 0点播 1直播

7. 注意事项

  1. 环境依赖: 该播放器基于STB(机顶盒)原生MediaPlayer API，只能在支持该API的环境中运行，在不支持的环境中会打印警告并失败。
  2. 原生UI禁用: 播放器在初始化时禁用了所有原生UI（音量条、进度条等），所有控制都需要通过SEPG API自定义UI实现。
  3. 事件监听器: 调用 releaseMediaPlayer() 会自动清除所有事件监听器，释放内存。
  4. 进度更新: 播放开始和恢复时会自动开始进度更新，暂停/停止时自动停止，一般开发者不需要手动调用 updateProgress() 和 stopProgress()。
  5. VR播放器: VR相关功能只有在创建VR播放器实例后才能使用，普通播放器不支持这些方法。
  6. 链式调用: 绝大多数方法都返回播放器实例本身，支持链式调用：
    player.setVolume(80)
      .setPoster(posterEl)
      .setLoader()
      .startPlay('id', 'url');