直播云

  • Web 播放端 SDK

    最近更新时间:2018-10-17 23:31:42

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

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

    快速上手

    简单几步就可以创建显示七牛 Web 视频播放器的简单网页:

    1. 创建一个 HTML 页面

    第一步是创建一个包含 video 标签的标准 HTML 页面,将此文件保存为 QiniuPlayerDemo.html,如以下示例所示:

    <!DOCTYPE html>
    <html>
      <head><title>Qiniu Web Player in HTML5</title></head>
      <body>
        <h1>Qiniu Web Player</h1>
        <video id="demo-video" class="video-js vjs-big-play-centered"></video>
      </body>
    </html>
    

    2. 引用 SDK

    可以通过 CDN 的方式直接引用 Web 播放器的 SDK,这种做法的优势是在于可以第一时间获得 SDK 的更新。如果希望锁定到指定版本,则可以把 SDK 下载到本地进行开发。

    七牛 Web 播放器 SDK 一共包含两个文件:
    qiniuplayer-0.3.9.min.js

    qiniuplayer-0.3.9.min.css

    在 QiniuPlayerDemo.html 页面添加如下代码,来添加七牛 Web 播放器:

    <link href="http://sdk-release.qnsdk.com/qiniuplayer-0.3.9.min.css" rel="stylesheet">
    <script src="http://sdk-release.qnsdk.com/qiniuplayer-0.3.9.min.js"></script>
    

    接下来,添加如下 JavaScript 代码来初始化播放器:

    var options = {
        controls: true,
        url: 'http://og9dz2jqu.cvoda.com/Zmlyc3R2b2RiOm9jZWFucy0xLm1wNA==_q00000001.m3u8',
        type: 'hls',
        preload: true,
        autoplay: false // 如为 true,则视频将会自动播放
    };
    
    var player = new QiniuPlayer('demo-video', options);
    

    3. 播放视频

    若要播放视频,打开浏览器并访问 QiniuPlayerDemo.html,可以见到已经初始化完毕的播放器,单击播放按钮则可以播放视频。

    注意

    1. 播放页面需要通过本地或远程启动的 Web 服务器来访问,如若直接打开本地静态页面将无法播放;

    2. 所有播放器方法都必须在播放器初始化完成后再调用;

    4. 开发示例 Demo

    API 文档

    1. 播放器初始化

    可以通过如下代码来初始化 Web 播放器:

    var player = new QiniuPlayer('element-id', options, callback);
    

    QiniuPlayer 构造函数接受三个参数:

    1. element-id 为播放器页面 video 标签的 id;
    2. options 为传递给播放器实例的选项;
    3. callback 是一个函数,该函数将会在播放器为可播放状态(ready)以后被调用。

    options 参数列表

    参数名称 说明 默认值
    engineOrder 取值为数组,可以是 html5 和 flash 的任意单项或组合,如果指定了多个模式,放在前面的将被优先考虑。用于指定播放器使用 HTML5 或 Flash 模式。注意:在 Flash 模式下播放器需要安装 Flash 插件。 ['html5', 'flash']
    swf Flash 模式下使用的 swf 文件,默认为 http://sdk-release.qnsdk.com/QplayerWeb-0.3.8.swf 可以自定义地址
    autoplay 取值:truefalse,用于设置视频是否会自动播放。 true
    preload 取值:auto, metadatanone,用于设置视频是否会自动加载。
    这三个选项的意义分别解释如下:
    auto: 表示视频会参考具体设备来确定是否自动加载。在桌面平台下,视频将会自动加载,但在一些移动平台上,比如 iPhone,为了帮助用户节约流量,会禁止自动加载。
    metadata: 表示将会自动加载视频的元数据,元数据包括视频总长度,宽高等信息。
    none: 表示视频将不会被自动加载。
    auto
    controls 取值:truefalse,用于设置是否显示播放器底部的控制栏。 true
    poster 取值:指向将要用作视频封面的网络链接,比如:http://urlc.cn/i558j2 ''
    width 取值:数字,用于设置播放器的宽度,单位为 px。 300
    height 取值:数字,用于设置播放器的高度,单位为 px。 150
    url 取值:指向将要播放的视频链接,比如:http://urlc.cn/mI9JY3 ''
    type 取值:hlsmp4。指定要播放视频的类型。 ''
    loop 取值:truefalse。指定视频是否循环播放。 false
    stretching 取值:letterbox, panscan, fitwindownone
    这四个选项的意义分别解释如下:
    letterbox:表示视频将会适配窗口,保持视频比例,可能产生黑边;
    panscan: 表示视频将会保持纵横比例,填满窗口,多余视频被切掉;
    fitwindow: 表示不保持视频比例,仅填满窗口,可能会变形;
    none: 表示使用视频真实大小。
    letterbox

    2. 播放器 API 接口

    播放器的 API 可分为两类:查询接口和控制接口。分别用来查询播放器的状态或者设置播放器成指定状态。

    注意:

    1. 请在播放器初始化完成后再调用api接口,推荐在 ready 的回调函数体内调用;
    2. [] 表示当前函数参数为可选。
    • 播放器 ready

    player.ready(callback);

    参数名称 说明
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:ready 事件回调,将在播放器变为 ready 以后调用该函数。

    • 播放

    player.play([callback]);

    参数名称 说明
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 暂停

    player.pause([callback]);

    参数名称 说明
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 查询是否暂停

    player.isPaused();

    返回值 说明
    Boolean true 表示暂停中,false 表示不在暂停状态。
    • 结束播放

    player.end([callback]);

    参数名称 说明
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 播放是否结束

    player.isEnded()

    返回值 说明
    Boolean true 表示播放已结束;false 表示播放尚未结束。
    • 获取/设置视频比例

    player.aspectRatio([ratio], [callback]);

    参数名称 说明
    ratio 取值:"4:3", "16:9", 等视频比例。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选, 不带参数则用于获取当前视频比例。

    • 获取/设置当前视频时间

    player.currentTime([time], [callback]);

    参数名称 说明
    time 取值: 以秒为单位的数字,将会设置视频当前播放时间为指定值。如果时间超过视频的长度,则正在播放的视频会停止播放。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选,不带参数是获取当前视频播放时间。

    • 释放当前播放器实例

    player.dispose([callback]);

    参数名称 说明
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 释放指定播放器实例

    QiniuPlayer.dispose("elementID", callback);

    参数名称 说明
    elementID 取值: 需要释放的播放器实例 ID,一般是初始化播放器的时候所指定的 video 标签 ID。
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 释放所有播放器实例

    QiniuPlayer.disposeAll(callback);

    参数名称 说明
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 获取所有播放器实例

    QiniuPlayer.players();

    返回值格式:

    {
        id: 播放器实例对象,
        ...
    }
    
    • 获取播放器状态

    player.state();

    返回值 说明
    Number 0: 视频尚未开始加载,当前没有可用媒体信息;
    1: 视频元数据已经可用;
    2: 视频可以播放;
    3: 视频可以播放,并且可以被快进;
    4: 视频可以无终止的播放。
    • 获取/设置所播放媒体文件时长

    player.duration([duration], [callback])

    参数名称 说明
    duration 取值: 以秒为单位的数字,将会设置视频播放的总时长。例如:设置为300 秒,表示视频会播放前 300 秒。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选,如果该函数不带参数则返回当前视频总时长。

    • 获取播放器是否静音

    player.isMuted()

    返回值 说明
    Boolean true 表示播放器在静音状态;反之则为 false
    • 设置播放器静音

    player.mute([isMute], [callback]);

    参数名称 说明
    isMute 取值为布尔值,true 表示使播放器静音,false 表示终止播放器的静音状态。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选,如果不提供参数,则使播放器静音。

    • 获取或设置播放器音量

    player.volume([vol], [callback]);

    参数名称 说明
    vol 音量,0~1 之间的浮点数。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选,如果不提供参数,则获取播放器当前音量,返回值范围是 0~1 之间的浮点数。

    • 获取或设置视频宽度

    player.width([width], [callback]);

    参数名称 说明
    width 视频宽度,数字类型,单位为 px。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选,如果不提供参数,则为获取播放器当前宽度。

    • 获取或设置视频高度

    player.height([height], [callback]);

    参数名称 说明
    height 视频高度,数字类型,单位为 px。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选,如果不提供参数,则为获取播放器当前高度。

    • 设置视频宽高

    player.resize(width, height, callback);

    参数名称 说明
    width 视频宽度,数字类型,单位为 px。
    height 视频高度,数字类型,单位为 px。
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 视频是否全屏

    player.isFullscreen();

    返回值 说明
    Boolean true 表示播放器在全屏状态;反之则为 false
    • 设置视频全屏

    player.fullscreen([isFullscreen], [callback]);

    参数名称 说明
    isFullscreen 布尔类型,true 全屏,false 退出全屏。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:1. 参数可选,如果不提供参数,则设置当前视频为全屏状态; 2. IE8/9/10 不支持 HTML5 全屏 API,所以此 API 在以上浏览器上将会用视频在保持比例的情况下填满当前浏览器视窗(viewport),在所有支持 HTML5 全屏 API 的浏览器上视频则可以在当前屏幕上全屏。

    • 是否显示控制条

    player.hasControls();

    返回值 说明
    Boolean true 表示播放器的控制栏可视;反之则为 false
    • 显示/隐藏控制条

    player.controls(show, callback);

    参数名称 说明
    show 布尔类型。true 显示控制栏,false 隐藏控制栏。
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 获取播放引擎

    player.engine();

    返回值 说明
    String html5 表示使用 HTML5 引擎播放;flash 表示使用 Flash 引擎播放;目前支持这两个选项。
    • 监听事件

    player.on(event, callback);

    player.one(event, callback); // 只会被触发一次

    参数名称 说明
    event 字符串类型,监听的事件名。
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 停止监听事件

    player.off(event, callback);

    参数名称 说明
    event 字符串类型,监听的事件名。
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 手动触发事件

    player.trigger(event, callback);

    参数名称 说明
    event 字符串类型,监听的事件名。
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 是否自动播放

    player.isAutoplay();

    返回值 说明
    Boolean true 表示播放器将会自动播放;反之则为 false。注意在移动设备上,因为来自系统的限制,auto 选项将不会生效。
    • 设置为自动播放

    player.autoplay([auto], [callback]);

    参数名称 说明
    auto 布尔类型。true 自动播放,false 不自动播放。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选,如果不传入参数则将播放器设置为自动播放模式。

    • 获取视频缓冲时长

    player.buffered()

    返回值 说明
    TimeRange TimeRange 类型表示一个音频或者视频文件有多少内容已经被缓存。一个 TimeRange 类型的对象包含了一组时间区间,每个区间有开始和结束时间,分别表示被缓存的内容的开始和结束时间。可以参考:https://developer.mozilla.org/en-US/docs/Web/API/TimeRanges
    • 获取缓冲百分比
      返回值为0~1的浮点数,表示当前已经缓冲的百分比。

    player.bufferedPercent();

    返回值 说明
    Number 0 ~ 1 之间的浮点数,表示当前已经缓冲的百分比。
    • 可以播放的视频类型

    player.canPlayType(type);

    参数名称 说明
    string 可选值'mp4', 'm3u8', 'hls',其他值均返回 false。
    • 当前视频源

    player.currentSrc();

    返回值 说明
    String 当前视频源的 URL,例如:'http://example.com/example.mp4'
    • 切换视频源

    player.src(obj, callback);

    参数名称 说明
    obj 将要切换的视频源和类型,样例数据: {type: 'video/mp4', src: 'example.mp4'}。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    如果需要切换 hls,type 值为 application/x-mpegURL

    • 当前播放视频类型

    player.currentType()

    返回值 说明
    String "application/x-mpegURL" 表示当前是 HLS 格式视频,"video/mp4" 标识当前播放 MP4
    • 加载媒体文件

    player.load([callback]);

    参数名称 说明
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 获取当前是否循环播放

    player.isLoop()

    返回值 说明
    Boolean true 表示视频将会循环播放;反之为 false
    • 设置循环播放

    player.loop([t], [callback])

    参数名称 说明
    t 布尔类型。true 表示循环播放, false 表示不循环播放。默认值为 true
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选,如果不传入任何参数,将会使当前视频循环播放。

    • 获取网络状况

    player.networkState()

    返回值 说明
    Number 0: NETWORK_EMPTY 播放器尚未被初始化;
    1: NETWORK_IDLE 播放器已经加载资源并且已经初始化,但目前没有使用网络资源;
    2: NETWORK_LOADING 正在下载数据;
    3: NETWORK_NO_SOURCE 播放器没有可选视频源来播放。
    • 获取或设置播放速率

    player.playRate([rate], [callback]);

    参数名称 说明
    rate 播放速率, 为 大于 0 的浮点数。 0.5: 半速,1: 正常速度,2: 两倍速度,3: 三倍速度等。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选。如果不传入任何参数,则为获取播放速率。返回值是大于 0 的浮点数。

    • 获取或者设置视频封面

    player.poster([url], [callback])

    参数名称 说明
    url 视频封面的链接。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选。如果不传入任何参数则为获取视频封面。

    • 获取或设置媒体文件预加载状态

    player.preload([type], [callback]);

    参数名称 说明
    type 取值为:'auto', 'metadata' 或 'none'。
    auto: 表示视频会参考具体设备来确定是否自动加载。在桌面平台下,视频将会自动加载,但在一些移动平台上,比如 iPhone,为了帮助用户节约流量,会禁止自动加载。
    metadata: 表示将会自动加载视频的元数据,元数据包括视频总长度,宽高等信息。
    none: 表示视频将不会被自动加载。
    callback 回调函数,其入参为已初始化完成的播放器实例。

    注释:参数可选,如果没有参数,则返回当前预加载类型。

    • 获取剩余时间

    player.remainingTime()

    返回值 说明
    Number 返回视频剩余时长,以秒为单位。
    • 判断用户是否在拖动视频

    player.isScrubbing()

    返回值 说明
    Boolean true 表示用户正在拖动视频,反之为 false
    • 设置视频为拖动状态

    player.scrubbing([b], [callback]);

    参数名称 说明
    b 布尔类型。true 把当前播放器置为拖动状态。
    callback 回调函数,其入参为已初始化完成的播放器实例。
    • 查询播放器是否在等待视频流

    player.isWaiting()

    返回值 说明
    Boolean true 表示播放器正在等待视频流,反之为 false

    3. 事件

    播放器可以订阅如下标准事件,并在事件被触发的时候调用相应的回调函数。以 play 事件为例,示例代码如下:

    var player = new QiniuPlayer('id', options);
    player.ready(function() {
        player.on('play', function() {
            // 业务逻辑
            console.log('I am playing.');
        });
    });
    
    
    • ended // 播放结束
    • error // 遇到播放错误
    • loadeddata // 视频数据已经加载
    • loadedmetadata // 元数据加载完毕
    • timeupdate // 视频当前时间被更新,一般意味着视频正在被播放,大约250毫秒更新一次
    • useractive // 用户有操作,比如光标滑过视频区域change
    • userinactive // 用户停止操作,比如光标滑出视频区域
    • ratechange // 视频播放速度变化
    • play // 播放开始
    • pause // 暂停
    • ready // 播放器是可以播放的状态
    • volumechange // 播放器声音调整
    • fullscreenchange // 全屏状态变化
    • waiting // 播放器是等待状态(加载数据,下载数据等)
    • seeking // 正在快进/后退
    • seeked // 快进/后退完成
    • progress // 播放正在进行
    • stalled // 浏览器尝试下载数据失败
    • suspend // 浏览器停止缓冲更多数据(可能是正在等待更多数据,随后可能会继续播放)

    除了标准事件之外,播放器也可以触发和订阅自定义事件,如下代码展示了这一用法:

    player.on('MY_CUSTOM_EVENT', function() {
        console.log('CUSTOME event triggered.');
    });
    
    player.trigger('MY_CUSTOM_EVENT');
    
    以上内容是否对您有帮助?
  • Icon free helper
    Close