西瓜播放器 - 全能开源HTML5视频播放器

文章最后更新时间：2024年05月30日

西瓜播放器简介

西瓜视频播放器(HTML5) 一款带解析器、能节省流量的H5播放器，该web播放器支持大部分视频格式与用户终端设备，还是一款特色的弹幕播放器，功能特色是从底层解析 MP4、HLS、FLV 探索更大的视频播放可控空间易拓展 ...西瓜播放器目前最新版本为V3.x

西瓜播放器官方概述：

西瓜播放器是一个Web视频播放器类库，它本着一切都是组件化的原则设计了独立可拆卸的 UI 组件。更重要的是它不只是在 UI 层有灵活的表现，在功能上也做了大胆的尝试：摆脱视频加载、缓冲、格式支持对 video 的依赖。尤其是在 mp4 点播上做了较大的努力，让本不支持流式播放的 mp4 能做到分段加载，这就意味着可以做到清晰度无缝切换、加载控制、节省视频流量。同时，它也集成了对 flv、HLS、dash 的点播和直播支持。

西瓜播放器实例

实例HTML：

...
//官方CDN引入
<link rel="stylesheet" href="https://unpkg.byted-static.com/XGplayer/3.0.1/dist/index.min.CSS">
<script type="text/JavaScript" src="https://unpkg.byted-static.com/XGplayer/3.0.1/dist/index.min.js"></script>
<script type="text/JavaScript" src="https://unpkg.byted-static.com/xgplayer-flv/3.0.1/dist/index.min.js"></script>
<script type="text/javascript" src="https://unpkg.byted-static.com/xgplayer-dash/3.0.0-alpha.2/dist/index.min.js"></script>
...
<div id="player"></div>

实例JS：

const config = {
	"id": "player",//容器
	"url": "https://xxx.com/2023/index.M3U8",//视频地址
	"playsinline": true,//内联播放
	"poster": "//lf9-cdn-tos.bytecdntp.com/cdn/expire-1-M/byted-player-videos/1.0.0/poster.jpg",//视频封面
	"screenShot": true,//截图
	"height": window.innerHeight,//播放器高度
	"width": window.innerWidth,//播放器宽度
	"pip": true,//画中画
	"volume": 1,//音量
	"loop": true,//循环播放
	"isLive": false,//直播模式
	"autoplay": false,//自动播放
	"playbackRate": [0.5,1,1.5,2],//倍速播放
};
config.plugins.push(HlsPlayer);
let player = new Player(config);

西瓜播放器参数

"id": "player",//容器
"url": vid,//视频地址
"playsinline": true,//内联播放
"poster": "//lf9-cdn-tos.bytecdntp.com/cdn/expire-1-M/byted-player-videos/1.0.0/poster.jpg",//视频封面
"plugins": [],//插件
"screenShot": true,//截图
"height": window.innerHeight,//播放器高度
"width": window.innerWidth,//播放器宽度
"pip": true,//画中画
"volume": 1,//画中画
"loop": true,//画中画
"isLive": false,//直播模式
"autoplay": false,//自动播放
"fluid": true,//流式布局,启用流式布局时根据width、height计算播放器宽高比，若width和height不是Number类型，默认使用16:9比例
"playbackRate": [0.5,1,1.5,2],//倍速播放
"download": true,//下载
"closeVideoDblclick": false,//关闭video双击事件
"closeVideoClick": false,//关闭video点击事件
"danmu": {//弹幕
	"comments": [
		{
			"duration": 15000,
			"id": "2",
			"start": 3000,
			"txt": "长弹幕长弹幕长弹幕",
			"mode": "top"
		},
	],
	"area": {//弹幕显示区域
		"start": 0,
		"end": 1
	},
	"closeDefaultBtn": false,//不使用默认提供弹幕开关
	"defaultOff": false,//关闭弹幕初始化
	"panel": true//弹幕控制面板
},
"rotate": {//视频旋转
	"clockwise": true,//旋转方向：顺时针逆时针
	"innerRotate": true//只旋转内部video
},
"progressDot": [//进度条标记
	{
		"time": 33,
		"text": "进度条标记33"
	},
],
"thumbnail": {//预览图
	"pic_num": 44,
	"width": 160,
	"height": 90,
	"col": 10,
	"row": 10,
	"urls": ["//lf9-cdn-tos.bytecdntp.com/cdn/expire-1-M/byted-player-videos/1.0.0/poster.jpg"]
},
"textTrack": [//外挂字幕
	{
		"src": "//lf3-static.bytednsdoc.com/obj/eden-cn/nupenuvpxnuvo/xgplayer_doc/textTrack-1.vtt",
		"label": "字幕1",
		"default": true
	},
],

西瓜播放器API

API样式：

player.play()
// OR
player.play().then(() => {
    // 播放成功
}).catch(() => {
    // 播放失败，一般发生于未经用户交互时的自动播放
})

API目录：
play//播放
pause//暂停
start//启动播放器，开始加载媒体资源，初始化video元素
replay//播放器返回至片头，重新播放，一般在播放结束时调用（对于直播场景无效）
seek//跳转到某个时间点继续播放，参数是number类型，单位是s(秒)（对于直播场景无效）
reload//重新加载视频
resetState()//重置当前实例状态，暂停视频并且将当前实例状态设置为起播之前的状态， 累计播放时长的计算结果会清空，播放器容器dom上的类名会重置为起播之前的状态
reset()//调用resetState重置实例状态，并且注销所有已经注册的组件，并且将当前实例的配置恢复为默认值
setConfig//更新配置信息，如果新的配置列表中包含内置插件的配置项，则会调用内置插件的setConfig对其进行更新
    player.setConfig({
      url: '另一个url',
    })
    
playNext(newConfig)//切换播放源
    player.playNext({
      url: '另一个url',
      poster: '新的海报图'，
      ...
    })
    
switchURL//切换播放源//该API为切换播放源的一种方式，内部实现了两个功能：1.为播放器设置src， player.src = src 2.根据切换前的播放状态，如果是播放中则在合适时机启动播放
    player.switchURL('url')
    
changeDefinition//切换清晰度
    player.changeDefinition({
      url: '另一个url',
      definition: 1，
      ...
    })
    
destroy//销毁播放器对象，该对象销毁的时候所有内置对象都会销毁，在调用的时候会下发Events.DESTROY事件
resetState//尝试暂停 Mediaelement，并还原播放器UI状态
on//添加事件监听player.on(Events.PlAY, boundFunc)
off//解除事件监听player.off(Events.PlAY, boundFunc)
emit//触发事件player.emit(Events.ERROR, {})
focus//播放器获取焦点
blur//播放器失去焦点
canPlayType//检测当前浏览器是否能播放指定类型的视频player.canPlayType(mimeType);
getBufferedRange//返回currentTime所处的缓冲时间范围，start表示缓冲起始时间，end表示缓存截止时间
checkBuffer//验证某个时间点是否在当前缓冲区间内
getFullscreen//全屏作用的DOM节点，如果不传默认是player.root，必须是player.root的父辈节点，如果该接口调用的时候处于网页全屏状态会自动退出网页全屏，下发事件Events.FULLSCREEN_CHANGE
exitFullscreen//播放器退出全屏状态
getCSSFullscreen//播放器进入网页全屏
exitCssFullscreen//播放器退出网页全屏
addClass//给播放器容器player.root添加CSS类名
removeClass//给播放器容器player.root移除CSS类名
hasClass//判断播放器容器player.root是否存在CSS类名
setAttribute//给播放器容器player.root设置属性player.setAttribute('key', 'value')
resize//调整播放器尺寸，如果初始化的时候有配置fitVideoSize 或者 videoFillMode，或者视频画面做了旋转，该api会触发整体的尺寸计算，根据视频画面和当前播放器容器尺寸做计算
getPlugin//从当前播放器获取插件的实例const pluginInstance = player.getPlugin('pluginName')
registerPlugin//在当前播放器上注册某个插件const pluginInstance = player.registerPlugin(MyPlugin)
unRegisterPlugin//在当前播放器上销毁/注销某个插件const pluginInstance = player.unRegisterPlugin(pluginName)
usePluginHooks//启用某个插件的某个hook
removePluginHooks//移除某个插件的某个hook
useHooks//启用播放器的某个hook
removeHooks//移除播放器的某个hook
attachVideoEvents//给播放器挂载一个媒体对象，并注册相应事件
detachVideoEvents//给播放器解除媒体对象，并移除相应事件，参数不传入则获取现有的player.video
setEventsMiddleware//设置媒体事件中间件，中间件在相关事件emit之前执行，可以阻止某个事件的下发
removeEventsMiddleware//移除媒体事件中间件player.removeEventsMiddleware(middlewares)

西瓜播放器监听

监听方式1:
const Events = window.Player.Events
player.on(Events.PlAY, () => {
  // TODO
})

监听方式2:
player.on("pause", () => {
  // TODO
});


媒体事件:
EVENTS.LOAD_START//loadstart//视频内容开始加载    
EVENTS.LOADED_DATA//loadeddata//视频起播数据加载完成
EVENTS.PLAY//play//播放
EVENTS.PAUSE//pause//暂停
EVENTS.ENDED//ended//结束
EVENTS.ERROR//error//错误
EVENTS.PLAYING//playing//（暂停、卡顿后）恢复播放
EVENTS.SEEKING//seeking//seek播放
EVENTS.SEEKED//seeked//seek完成
EVENTS.TIME_UPDATE//timeupdate//播放时间改变
EVENTS.WAITING//waiting//等待加载数据
EVENTS.CANPLAY//canplay//视频缓冲足够数据，可以播放
EVENTS.CANPLAY_THROUGH//canplaythrough//视频可以流畅播放
EVENTS.DURATION_CHANGE//durationchange//视频时长发生变化
EVENTS.VOLUME_CHANGE//volumechange//音量发生变化
EVENTS.RATE_CHANGE//ratechange//播放速率发生变化


扩展事件:
EVENTS.READY//ready//播放器完成实例化
EVENTS.AUTOPLAY_PREVENTED//autoplay_was_prevented//自动播放失败
EVENTS.AUTOPLAY_STARTED//autoplay_started//成功自动播放
EVENTS.COMPLETE//complete//播放器创建video完成，可以开始播放
EVENTS.URL_CHANGE//urlchange//播放资源发生变化，player.src='xxx'
EVENTS.PLAYER_FOCUS//focus//播放器聚焦
EVENTS.PLAYER_BLUR//blur//播放器失焦
EVENTS.FULLSCREEN_CHANGE//fullscreen_change//全屏状态切换
EVENTS.CSS_FULLSCREEN_CHANGE//cssFullscreen_change//样式全屏状态切换
EVENTS.MINI_STATE_CHANGE//mini_state_change//画中画播放模式切换
EVENTS.DESTROY//destroy//播放器销毁
EVENTS.REPLAY//replay//播放器重新播放
EVENTS.RETRY//retry//重试
EVENTS.DEFINITION_CHANGE//definition_change//清晰度发生变化	
EVENTS.VIDEO_RESIZE//video_resize//播放器容器尺寸发生变化	
EVENTS.PIP_CHANGE//pip_change//画中画状态切换	
EVENTS.ROTATE//rotate//播放器被旋转
EVENTS.SHORTCUT//shortcut//播放器内置快捷键事件触发
EVENTS.SEI_PARSED//SEI_PARSED//SEI信息解析（目前在xgplayer-flv、xgplayer-hls插件安装时生效）
EVENTS.USER_ACTION//user_action//(3.0.0-alpha.92-2之后支持)内置插件用户行为触发，所有内置插件用户行为交互都会下发该事件，可用于用户行为埋点

西瓜播放器错码

1	资源请求被用户终止	media
2	媒体请求网路错误	network
3	媒体解码出错	decoder
4	媒体资源不支持播放	format
600	http请求失败, 存在 404，403、500等标准错误码	network
601	http请求超时	network
602	请求出错. https下请求http资源、不允许跨域请求之类	network
603	其它错误。 fetch流式请求出错 reader.read()出错等	network
700	解封装过程出错	demux
800	重封装过程出错	remux
900	M3U8解析失败	hls
901	m3u8内容有误	hls
1000	mse addSourceBuffer出错