文档中心 播放器 SDK Web 端集成 点播播放器使用文档

点播播放器使用文档

最近更新时间:2019-08-21 16:14:40

本文档是介绍腾讯云 Web 视频点播服务的超级播放器,它可以帮助腾讯云客户通过灵活的接口,快速与自有 Web 应用集成,实现视频播放功能,本文档适合有一定 Javascript 语言基础的开发人员阅读。

能力介绍

点播超级播放器是通过 HTML5 <video> 标签以及 Flash 实现视频播放。在浏览器不支持视频播放的情况下,实现了视频播放效果的多平台统一体验,并结合腾讯云点播视频服务,提供防盗链和 DRM 加密播放等功能。

视频格式与平台支持

浏览器/格式 MP4 HLS DASH
Chrome
Firefox
Edge
QQ 浏览器
Mac Safari
iOS Safari
iOS 微信 QQ
Android Chrome
Android 微信、QQ
手机 QQ 浏览器
IE8,9,10,11
说明:

  • 视频编码格式仅支持 H.264 编码。
  • Chrome,Firefox 包括 Windows、macOS 平台。
  • Chrome,Firefox,Edge,QQ 浏览器播放 HLS 需要加载 hls.js。
  • Chrome,Firefox,Edge,Android Chrome,Mac Safari 播放 DASH 需要加载 dash.js。
  • Android 微信、QQ 为 TBS 内核,原生支持播放 MP4、HLS。
  • IE8 采用 Flash 播放,IE9/10/11 播放 HLS 时采用 Flash 播放,需要确保浏览器支持 Flash 插件。
  • IE8 仅支持 Windows 7 系统的 IE8。

播放器兼容常见的浏览器,播放器内部会自动区分平台,并使用最优的播放方案。例如:在 IE11/10/9/8 浏览器中会使用 Flash 播放器以实现其不支持 HTML5 播放 HLS 的能力,在 Chrome 等现代浏览器中优先使用 HTML5 技术实现视频播放,而手机浏览器上会使用 HTML5 技术或者浏览器内核能力实现视频播放。

点播平台的转码服务

由于 MP4 和 HLS(m3u8)是目前在桌面浏览器和手机浏览器上支持程度最广泛的格式,所以腾讯云的视频点播平台最终会把上传的视频发布为 MP4 和 HLS(m3u8) 格式。

准备工作

Step1:开通服务

腾讯云官网 注册腾讯云账号,然后开通点播服务。

Step2:上传视频并转码

点播服务开通之后,需要 上传视频,并进行 转码处理

Step3:获取 ID(fileID) 与 APPID

  1. 获取 ID(fileID):视频上传后,通过媒资管理可以 查看视频 ID

  2. 获取 APPID:在【腾讯云控制台】>【账号信息】中查看。

初始化 Web 播放器

在准备工作完成后,通过以下3个步骤,您就可以在网页上添加一个视频播放器。

Step1:在页面中引入文件

在合适的地方引入播放器样式文件与脚本文件:

 <link href="//imgcache.qq.com/open/qcloud/video/tcplayer/tcplayer.css" rel="stylesheet">
 <!--如果需要在 Chrome 和 Firefox 等现代浏览器中通过 H5 播放 HLS 和 Dash 格式的视频,需要在 tcplayer.min.js 之前引入 hls.js 和 dash.js。-->
 <script src="//imgcache.qq.com/open/qcloud/video/tcplayer/libs/hls.min.0.12.4.js"></script>
 <script src="//imgcache.qq.com/open/qcloud/video/tcplayer/libs/dash.all.min.2.9.3.js"></script>
 <!--播放器脚本文件-->
 <script src="//imgcache.qq.com/open/qcloud/video/tcplayer/tcplayer.min.js"></script>
说明:

暂不支持 VUE React 等框架的模块加载方式,可以通过 script 全局引入相关脚本的方式进行使用。

Step2:放置播放器容器

在需要展示播放器的页面位置加入播放器容器。例如,在 index.html 中加入如下代码(容器 ID 以及宽高都可以自定义)。

<video id="player-container-id" width="414" height="270" preload="auto" playsinline webkit-playsinline>
</video>
说明:

  • 播放器容器必须为 <video> 标签。
  • 示例中的 player-container-id 为播放器容器的 ID,可自行设置。
  • 播放器容器区域的尺寸,建议通过 CSS 进行设置,通过 CSS 设置比属性设置更灵活,可以实现例如铺满全屏、容器自适应等效果。
  • 示例中的 preload 属性规定是否在页面加载后载入视频,通常为了更快的播放视频,会设置为 auto,其他可选值:meta(当页面加载后只载入元数据),none(当页面加载后不载入视频),移动端由于系统限制不会自动加载视频。
  • playsinlinewebkit-playsinline 这几个属性是为了在标准移动端浏览器不劫持视频播放的情况下实现行内播放,此处仅作示例,请按需使用。
  • 设置 x5-playsinline 属性在 TBS 内核会使用 X5 UI 的播放器。

Step3:初始化代码

在页面初始化的代码中加入以下初始化脚本,传入在准备工作中获取到的 fileID 与 appID。

var player = TCPlayer('player-container-id', { // player-container-id 为播放器容器ID,必须与html中一致
    fileID: '4564972818956091133', // 请传入需要播放的视频filID 必须
    appID: '1253668508' // 请传入点播账号的appID 必须
  });
注意:

要播放的视频需经过腾讯云转码,原始视频无法保证在浏览器中正常播放。

完整示例页面

示例代码

功能使用说明

下面将对播放器的部分功能进行详细说明,包括最佳实践与注意事项。

播放器尺寸设置

这里介绍几种给播放器设置尺寸的方法:

  • 可以给 <video> 标签设置 width 和 height 属性,width 和 height 的属性值是以像素计量的(例如 width = "100px" 或 width= 100),不能设置百分比。
  • 可以通过 CSS 设置尺寸,支持像素和百分比等类型的值(例如:width:"100px" 或 width:"100%" )。
说明:

  • 如果不设置宽高,播放器在获取到视频的分辨率后,将会以视频的分辨率设置播放器的显示尺寸,如果浏览器的可视区域尺寸小于视频分辨率,会造成播放器区域超出浏览器的可视区域,所以通常不建议这样做。最佳实践为通过 CSS 设置播放器的尺寸。
  • 熟练运用 CSS 可以实现铺满全屏、容器自适应等效果。

示例:

播放多种清晰度

  1. 播放多种清晰度功能,视频需要 转码处理 成多种清晰度,查看处理后的 视频信息,会有多个规格的资源。
  2. 按照初始化 Web 播放器的步骤在腾讯云点播播放器中播放即可。清晰度选择效果如下图:
注意:

  • 在浏览器劫持视频播放的情况下,该功能无法使用。通常在移动浏览器中,浏览器会劫持视频播放,用浏览器自带的播放器替代。
  • 通过自定义 视频转码模版 转码的视频目前仅支持指定清晰度播放,可以通过转 自适应码流 实现播放多种清晰度的功能。

示例:
多种清晰度

指定播放清晰度

这里分为两种情况:指定播放某个清晰度和让播放器默认播放某个清晰度。

指定播放某个清晰度

通过播放器的 definition 参数指定播放某个清晰度。

可选值 说明
10 MP4 手机
20 MP4 标清
30 MP4 高清
40 MP4 超清
210 HLS 手机
220 HLS 标清
230 HLS 高清
240 HLS 超清

在下面的示例中,将指定播放 MP4 手机清晰度视频:
指定播放清晰度

注意:

  • 通过该方式指定播放某个清晰度,播放器将不会出现清晰度切换菜单,如需要指定播放某个清晰度的同时使用清晰度切换菜单,请采用下面“指定播放器默认播放某个清晰度”的方法。
  • 在播放自适应码率视频的情况下,该功能无法使用。

指定播放器默认播放某个清晰度

  1. Web 播放器管理设置相应播放器的默认画质。
  2. 管理视频 将视频与播放器配置进行关联,如下图所示。
  3. 在使用腾讯云播放器播放该视频时,将会使用关联的播放器配置。
说明:

  • 如果默认清晰度的视频不存在,则获取该视频的清晰度列表中第一个文件进行播放。例如,播放器配置默认播放超高清,但是视频只有标清和高清,这时会播放标清视频。
  • 控制台播放器配置在设置后,大概需要等待10分钟,让所有 CDN 节点生效该配置。
  • 在播放自适应码率视频的情况下,该功能无法使用。
  • 在浏览器劫持视频播放的情况下,该功能无法使用。

续播功能

开启续播功能的前提,必须通过 fileID 播放。有了唯一的 fileID,播放器才能记录该视频的播放时长,当播放未结束时关闭页面,在同一个浏览器中再次打开播放页面,可从上次观看的时间点继续播放。通过以下参数开启续播功能:

var player = TCPlayer('player-container-id', {
    fileID: '', // 请传入需要播放的视频 filID 必须
    appID: '', // 请传入点播账号的 appID 必须
    plugins:{
        ContinuePlay: { // 开启续播功能
          // auto: true, //[可选] 是否在视频播放后自动续播
          // text:'上次播放至 ', //[可选] 提示文案
          // btnText: '恢复播放' //[可选] 按钮文案
        },
      }
  });

开启成功后将会看到的效果如下图:

示例:
续播

注意:

  • 必须通过 fileID 和 appID 播放经过腾讯云转码后的视频,才能使用该功能。
  • 该功能通过 localStorage 存储播放时间点,浏览器需支持该特性。
  • 在浏览器劫持视频播放的情况下,该功能无法使用。
  • 该功能不是多端多浏览器互通的,例如在 PC 浏览器上没看完,不能在移动端浏览器上续播或者在 PC 上另一个浏览器续播,需额外的接口,可以自行开发。

倍速播放

在浏览器支持的情况下播放器默认开启倍速播放功能。

var player = TCPlayer('player-container-id', {
    fileID: '', // 请传入需要播放的视频 filID 必须
    appID: '', // 请传入点播账号的 appID 必须
    playbackRates: [0.511.251.52] // 设置变速播放倍率选项,仅 HTML5 播放模式有效
  });
注意:

  • 如果浏览器不支持倍速播放,播放器将不会显示倍速切换按钮。
  • 如需关闭该功能请看 开发文档

点播超级播放器支持配置播放器 logo,可以在【控制台】>【Web播放器管理】选定某个播放器配置,单击外观栏目进行设置 logo 信息。设置 logo 信息后,使用该播放器配置播放视频时,将会在指定位置显示 logo。

示例:
显示 Logo

注意:

  • 控制台播放器配置在设置后,大概需要等待10分钟,让所有 CDN 节点生效该配置。
  • 在浏览器劫持视频播放的情况下,设置的 logo 将无法显示。

图片贴片功能

点播超级播放器支持配置片头、片中暂停以及片尾显示图片贴片,并且可以添加超链接。可以在【控制台】>【Web播放器管理】选定某个播放器配置,单击贴片栏目进行设置贴片信息。

  • 默认的贴片显示样式为水平垂直居中显示,如果图片的尺寸大于播放器显示区域,将按播放器的宽度等比缩放图片,水平居中显示图片,图片超出播放器区域部分将无法显示。
  • 可以通过 CSS 自定义贴片的显示样式。
    .tcp-image-patch-start{} /* 片头贴片样式Class */
    .tcp-image-patch-pause{} /* 片中贴片样式Class */
    .tcp-image-patch-ended{} /* 片尾贴片样式Class */

示例:
图片贴片

注意:

  • 贴片建议使用体积不超过50KB且尺寸不超过播放器显示区域的图片,避免因图片过大影响视频初始化速度。
  • 控制台播放器配置在设置后,大概需要等待10分钟,让所有 CDN 节点生效该配置。
  • 在浏览器劫持视频播放的情况下,设置的贴片将无法显示。

缩略图预览

点播超级播放器支持缩略图预览,开启该功能有两种方式:

  1. 通过服务端 API 生成视频的缩略图与 VTT 文件,相关文档可参阅 截图 - 雪碧图
  2. 自行生成缩略图文件与 VTT 文件,并将两个文件的 URL 传递给播放器,参考示例“缩略图预览-传入缩略图与 VTT 文件”

开启成功的效果如下图:

示例:

切换 fileID 播放

通过实例化对象的 loadVideoByID(args) 方法,可以更换视频进行播放。该方法支持的参数如下:

player.loadVideoByID({
  fileID: '', // 请传入需要播放的视频 filID 必须
  appID: '', // 请传入点播账号的 appID 必须
  t: '', // 参考 Key 防盗链说明
  us: '', // 参考 Key 防盗链说明
  sign:'', // 参考 Key 防盗链说明
  exper:'' // 参考 试看功能说明
});

示例:
切换 fileID 播放

镜像功能

激活镜像功能,可以让视频画面镜像翻转,如下图所示:

开启右键菜单镜像选项:

var player = TCPlayer('player-container-id', {
  fileID: '', // 请传入需要播放的视频 filID 必须
  appID: '', // 请传入点播账号的 appID 必须
  plugins: {
    ContextMenu: {
      mirror: true
    }
  }
});

示例:
镜像功能

注意:

在浏览器劫持视频播放的情况下,该功能无法使用。

进度条标记

通过服务端 API 对视频 增加打点信息,可以在播放器中开启显示进度条标记,如下图所示:

播放器开启方式:

var player = TCPlayer('player-container-id', {
  fileID: '', // 请传入需要播放的视频 filID 必须
  appID: '', // 请传入点播账号的 appID 必须
  plugins: {
    ProgressMarker: true
  }
});

示例:
进度条标记

注意:

  • 该功能仅支持桌面端浏览器。
  • 在浏览器劫持视频播放的情况下,该功能无法使用。

HLS 自适应码率播放

  • HLS 规范的 Master Playlist 可以根据网络速度自适应码率播放,在视频下载过程中,如果网络速度满足下载高码率的 ts 分片时,播放器将切换播放高码率的 ts 分片,反之播放低码率的 ts 分片。移动端和桌面端大部分浏览器都支持该特性。
  • 使用 HLS Master Playlist 需要通过服务端 API 对视频进行转码,视频转码生成 HLS Master Playlist 才可以开启该特性,请查看相关文档 视频转码
  • 播放 HLS Master Playlist 时,播放器的清晰度选择功能将会变成选择特定的码率或者根据网络速度自动选择。如下图所示:
注意:

  • 自适应码率播放全端都默认采用自动切换逻辑。
  • 由于部分浏览器没有提供相应的接口和不支持 MSE,这些浏览器无法手动选择特定的清晰度,也不会显示切换清晰度的选项。
  • Flash 播放模式下不支持手动选择特定的码率。
  • 如果视频转码时输出了 HLS Master Playlist,播放器将会优先使用 HLS Master Playlist 进行播放。

示例:
HLS Master Playlist

Referer 防盗链

开启流程请看 Referer 防盗链说明文档

播放器初始化需增加参数如下:

var player = TCPlayer('player-container-id', {
     fileID: '', // 请传入需要播放的视频filID 必须
     appID: '', // 请传入点播账号的appID 必须
     flash:{
         swf: '//[腾讯云隔离域名]/vod-player/[appID]/[fileID]/tcplayer/player.swf' //swf 文件地址 必须
     }
   });

需传入 swf URL,如果浏览器使用 Flash 播放,将会从这个地址获取 Flash 播放器。Flash 播放器发起视频请求时,请求的 Referer 会带上该 URL 或者带上页面的 URL。

说明:

  • 播放器在 Flash 模式下发起视频请求的 Referer,在 IE、Firefox 浏览器中会带上 swf URL,与 Chrome 浏览器会带上页面的 URL 的情况不同。
  • 您也可以将 player.swf 文件下载后,存放到您的 CDN 服务器中,swf 参数传入指向您的 CDN 服务器路径。
  • 腾讯云提供的隔离域名是每个用户独有的域名,一个 appID 对应一个域名,通常格式为 [appID].vod2.myqcloud.com。
  • 需要将播放器 swf URL 的域名添加到白名单内,开启了 Referer 防盗链的视频才能在 Flash 模式下播放。
  • 播放器的 Flash swf 文件默认存放在 imgcache.qq.com 域名下,如需部署到自己的服务器上,可自行下载并部署,swf 文件地址
  • iframe 嵌入播放器页面,视频请求的 Referer 会带上 iframe src。

Key 防盗链

开启流程请看 Key 防盗链说明文档

播放器初始化需增加参数如下:

var player = TCPlayer('player-container-id', {
     fileID: '', // 请传入需要播放的视频 filID 必须
     appID: '', // 请传入点播账号的 appID 必须
     t: '',
     us: '',
     sign:''
   });

参数 t、us、sign 的具体含义请查看 Key 防盗链 文档。

注意:

  • sign 的计算方法为:sign = md5(KEY+appId+fileId+t+us),与 Key 防盗链 文档中的计算方式不同,其余参数一致。
  • 如果同时开启了 Referer 防盗链,在 Referer 防盗链配置的示例代码基础上增加参数即可。
  • 如果开启了播放 DRM 内容的功能,sign 的计算方法为:sign = md5(KEY+appId+fileId+playDefinition+t+us) DRM 防盗链参数说明

试看功能

使用试看功能需要先开启 Key 防盗链,开启流程请看 Key 防盗链 文档。播放器初始化需增加参数如下:

var player = TCPlayer('player-container-id', {
     fileID: '', // 请传入需要播放的视频 filID 必须
     appID: '', // 请传入点播账号的 appID 必须
     t: '',
     us: '',
     sign:'',
     exper:''
   });

参数 t、us、sign 和 exper 的具体含义请查看 Key 防盗链 文档。

注意:

  • 该功能暂不支持商业级 DRM 播放方案。
  • 带试看的 sign 计算方法为:sign = md5(KEY+appId+fileId+t+exper+us),与 Key 防盗链说明文档 中的计算方式不同,其余参数一致。
  • 播放器播放的视频时长是 exper 参数指定的长度,与已往在播放端控制播放时长的试看功能不同,播放器不会获取完整的视频。
  • 试看时长是根据视频关键帧进行裁剪,实际截取的试看时长可能会比设定值少。
  • 开启试看后播放器仍会显示视频原始时长(在 Chrome 和 Firefox 播放 hls 格式的试看视频会显示试看时长)。

HLS 加密播放

开启流程请参见 HLS 普通加密 文档。
播放页面必须加载 hls.js ,播放示例代码如下:

var player = TCPlayer('player-container-id', {
     fileID: '', // 请传入需要播放的视频 filID 必须
     appID: '' // 请传入点播账号的 appID 必须
   });
注意:

  • 如果播放页面或者 Flash swf URL 与解密密钥服务器域名不一致,Key 服务器需要部署 corssdomain.xml 和 CORS("跨域资源共享" Cross-origin resource sharing),允许 Flash 和 JavaScript 跨域获取解密密钥。
  • crossdomain.xml 中配置的是 swf URL 的域名,并且 xml 文件必须放置在 Key 服务器的根目录。
  • 播放器的 Flash swf 文件默认存放在 imgcache.qq.com 域名下,如需部署到自己的服务器上,可自行下载并部署,swf 文件地址
  • 视频只能进行一次加密,不可多次加密,严格按照视频加密文档操作。
  • 解密密钥正确长度为16字节,起始和末尾位置不能有空白字符。
  • 目前该功能可用商业级 DRM 方案进行替代。

播放 DRM 内容

点播超级播放器集成了播放 DRM 内容的功能,支持以下几种 DRM 方案:

  • 基于 Widevine 商业级加密的 DASH 方案
  • 基于 FairPlay 商业级加密的 HLS 方案
  • 基于 SimpleAES 基础级加密的 HLS 方案

关于 DRM 的更多详情,您可以参考 如何对内容做版权保护 方案文档。

浏览器的支持情况

各浏览器对 DRM 的支持情况如下。

浏览器 Widevine FairPlay SimpleAES
Chrome(PC Mac)
Firefox(PC Mac)
Edge
Mac Safari
iOS Safari
iOS Chrome
iOS 微信 QQ
Android Chrome
Android 微信 QQ
IE8,9,10,11
注意:

IE 浏览器采用 Flash 播放。

使用方法

首先,App 需要从您的业务后台获取 Token,Token 的生成方式请参见 这里

如果需要播放 FairPlay 加密的内容,按照 ASK 和 FPS 证书指引 生成 FPS 证书,并将证书部署在您的服务器中,证书的下载地址 URI 记为certificateUri

然后,通过 FileId + Token 方式进行播放,播放代码如下:

var player = TCPlayer('player-container-id', {
  appID:  '', // 请传入点播账号的 appID 必须
  fileID: '', // 请传入需要播放的视频 fileID 必须
  playDefinition: '' // 请传入播放模版,播放 DRM 内容必须
  plugins: {
    DRM: {
      token: '', // 传入您的后台服务签发的 token,播放 DRM 内容必须
      certificateUri: '', // 传入 FairPlay 证书的下载地址,播放 FairPlay 加密内容必须
    }
  }``
});

播放器会根据传入的 播放模版 ID 和当前浏览器的支持情况,按优先级选择合适的播放方案,DRM 方案选择优先级为 Widevine > FairPlay > SimpleAES,例如:

  • 传入playDefinition为20 ,播放器依次选择 Widevine 或 FairPlay ,SimpleAES 的加密输出播放。
  • 传入playDefinition为12 ,播放器依次选择 Widevine 或 FairPlay 的加密输出播放。
  • 传入playDefinition为10 ,播放器将会选择未加密的 HLS 或 DASH 输出播放。

示例:
DRM 自动识别播放

注意: