七牛 Web 播放器 SDK 是七牛官方推出的用于开发网页播放器的软件开发工具包，为 Web 开发者提供简单、快捷的接口，帮助开发者在 Web 平台上快速开发播放器应用。

该文档面向考虑使用七牛 Web 播放器 SDK 进行开发并具备 JavaScript 语言基础的开发人员。

示例

引入

创建一个播放器

只要指定资源的播放地址和页面上的一个元素，SDK 就会自动在这个元素下面创建相应的播放器组件，目前支持的资源格式是 mp4、webm 和 m3u8。

const player = new QPlayer({

url: "http://xxx.xxxx.xxx.m3u8",

container: document.getElementById("xxx"),

});

其中构造参数的配置见下

QPlayerConfig {

url: string; // 视频源，目前支持 mp4、webm 和 m3u8

container: HTMLElement | HTMLVideoElement; // 一个 HTML 元素作为播放器的容器，播放器默认使用容器的宽高，也支持直接传入 video 元素

autoplay?: boolean; // 是否自动播放

muted?: boolean; // 是否静音

poster?: string; // 封面图片

hls?: {

DRMKey?: Uint8Array; // 七牛 HLS DRM 加密密钥

isG711?: boolean; // 是否是 G.711 编码的音频

};

mp4?: {

DRMCompanyKey?: Uint8Array; // 七牛 MP4 DRM 的 CompanyKey

};

isLive?: boolean; // 是否是直播流, 这个开启后播放器将不会渲染进度条和时间

loggerLevel?: number; // log 等级，0 info，1 debug， 2 只看错误，3 关闭 log，默认为 1

}

自动播放的注意事项

目前主流浏览器(Firefox/Chrome/Safari)都有各种规则禁止页面在没有用户交互前提下自动播放有声的媒体资源，所以即使这里设置了自动播放，也不能保证 100% 自动播放成功。

关于自动播放的细节可以参考这篇 Chrome 的对外声明 https://developers.google.com/web/updates/2017/09/autoplay-policy-changes

这里我们简单讨论一下如果您的页面非常依赖自动播放该如何应对这个策略。首先我们从刚刚的那句话中提炼出几个关键词，即 “没有用户交互”、“自动播放“ 和 ”有声媒体“，这里的逻辑关系是这样的 —— ”如果没有用户交互” 并且 “媒体是有声的” 那么 “无法自动播放“，这个是板上钉钉的规则写进浏览器层改不了的。既然规则改不了，我们只能利用规则来实现我们需求。

很简单，从规则来看自动播放失败需要 2 个条件，只要其中一个条件不满足，自动播放就可以完成。

首先第一个 ”没有用户交互“，显然我们只要在用户有交互动作之后再创建播放器或者再调用播放器的 play 方法就可以绕过这个限制了。那么什么是用户交互呢？就是我们通常所说的 “点击”/“触摸” 等操作，所以我们可以设计一个按钮/提示框，待用户有点击操作了之后再播放我们的媒体源就可以了。

那么第二个 “有声媒体”，也就是说，只要我们以 静音模式 创建播放器，就不会被自动播放策略所限制。如果您想综合这两者，那我们就当用户第一次进入页面时先静音自动播放，然后提供一个取消静音的按钮或者提示框之类的方案，待用户点击了什么东西之后再取消静音即可，这也是推特/脸书等大厂们采用的方案。

当用户在一个页面上手动播放次数超过一定次数后，Chrome 就会为这个页面接触自动播放限制。不过注意，这个自动播放限制的解除是本地白名单维护的。

播放器对象成员

player.currentTime

当前播放的时间，单位是秒

player.totalTime

视频总时长，在 ready 事件触发前这个值都是 0，单位是秒

player.isPlay

当前是否在播放状态

player.isPause

当前是否在暂停状态

player.isEnded

当前是否在结束状态

player.isMuted

当前是静音状态

player.volume

当前的音量，范围 0-1

player.isLoop

当前是否开启了循环播放

播放器对象方法

player.play()

播放视频源

player.pause()

暂停视频源

player.seek(time)

跳转到指定的时间点 time，time 的单位是秒

player.toggleFullscreen()

切换到全屏/非全屏模式

player.toggleMute()

切换静音状态

player.toggleLoop()

切换循环播放状态

player.setVolume(value)

设置音量， value 需要在 0 - 1 之间

player.setPlaybackRate(rate)

倍速播放，rate 为指定的倍率，需要 > 0

player.destroy()

释放当前播放器

播放器事件

SDK 基于 events 库实现了事件模型，通过以下方法注册绑定事件

// 注册 ready 的监听函数

player.on("ready", handleReady);

// 注册 ready 的监听函数，但是只会触发一次

player.once("ready", handleReady);

// 移除 ready 特定的监听函数

player.off("ready", handleReady);

// 移除 ready 的所有监听函数

myRoom.removeAllListeners("ready");

事件名称

事件介绍

事件参数

参数说明

ready

播放器准备完毕，可以播放

()

无

fullscreenchange

全屏状态改变

(isFullScreen: boolean)

是否全屏

error

播放过程中出现错误

(e)

错误对象，包含了错误代码

play

播放器开始播放

()

无

pause

播放器暂停

()

无

ended

播放结束

()

无

timeupdate

播放时间更新

(currentTime: number, totalTime: number)

分别为当前播放时间和总时间

durationchange

总播放时间更新

(totalTime: number)

总时间

loading

正在加载

()

无

seeked

播放器跳转完成

()

无

volumechange

播放器音量改或者 mute 状态改变

(volume: number, isMuted: boolean)

分别是当前音量和是否静音

错误代码

ErrorCode

描述

10000

浏览器不支持此视频源

10001

无法解析视频源的类型

10002

无法加载视频源

10003

浏览器不支持全屏功能

10006

视频播放失败

10007

配置参数格式非法

10008

unexpected error

10009

HLS engine错误

多码率媒体资源

多码率 HLS

SDK 支持多码率的 m3u8 文件，同时会根据 m3u8 文件上的分辨率、码率字段来生成对应码率媒体源在 UI 上的名称。您也可以手动传入每个码率的名称给到 SDK

const player = new QPlayer({

url: "http://7xlv47.com1.z0.glb.clouddn.com/xxx004.m3u8",

autoplay: true,

hls: {

qualityName: ["低清", "标清", "高清", "超清"],

},

});

多码率 MP4

SDK 允许用户同时传入不同码率的资源文件地址，然后在视图上手动切换码率。

const player = new QPlayer({

qualityList: [{

url: "http://pkeamo5ex.bkt.clouddn.com/snow_miku_qualities/starnight_snow_240p.mp4",

name: "低清240P",

}, {

url: "http://pkeamo5ex.bkt.clouddn.com/snow_miku_qualities/starnight_snow_480p.mp4",

name: "标清480P",

}, {

url: "http://pkeamo5ex.bkS.clouddn.com/snow_miku_qualities/starnight_snow_720p.mp4",

name: "高清720P",

}, {

url: "http://pkeamo5ex.bkt.clouddn.com/snow_miku_qualities/starnight_snow_1080p.mp4",

name: "超清1080P",

}],

});

自定义视图

SDK 的默认视图提供了一些配置选项用于给用户自定义视图，通过在创建播放器的参数中指定，例如下面的代码自定义了播放器的开始播放按钮

const player = new QPlayer({

url: "xxxx",

container: xxxx,

defaultViewConfig: {

playIcon: "https://xxx.xxx.xxx/play.png",

},

})

完整的 defaultViewConfig 见下：

DefaultViewConfig {

playIcon: string, // 播放按钮

pauseIcon: string, // 暂停按钮

fullscreenIcon: string, // 全屏按钮

fullscreenExitIcon: string, // 退出全屏按钮

volumeIcon: string, // 音量按钮

volumeOffIcon: string, // 静音按钮

settingsIcon: string, // 设置按钮

backIcon: string, // 返回按钮

closeIcon: string, // 关闭按钮

inactiveTimeout: number, // 控件隐藏的延迟

noControls: boolean, // 是否不渲染控件

showControls: boolean, // 是否一直显示控件

playerBarBackground: string, // 进度条背景 CSS

playerBarPlayedBackground: string, // 已播放进度条背景 CSS

playerBarBufferedBackground: string,// 已缓存进度条背景 CSS

}

播放 G.711 音频格式的 HLS

为了使浏览器可以播放 G.711 音频格式的 HLS 资源，SDK 需要额外加载一个外部依赖库。开发者在使用这个功能时，必须先将这个外部依赖库的地址传入到 SDK 之中。

请不要直接使用这个地址传入 SDK，我们不保证这个地址长期有效，推荐您将这个依赖库下载后存放在自己网站的存储空间中。

const player = new QPlayer({

url: "xxxxx",

hls: {

// 指明该资源为 G711 HLS

isG711: true,

},

// G711 外部依赖库的地址

g711Wasm: "http://sdk-release.qnsdk.com/aac_wasm.wasm",

});