tcadapter

TcAdapter 使用文档说明

本文档是介绍腾讯云 Web TcAdapter，它可以帮助腾讯云客户通过灵活的接口，快速实现第三方播放器与云点播能力的结合，实现视频播放功能。TcAdapter 支持获取视频基本信息、视频流信息、关键帧与缩略图信息等，支持私有加密，本文档适合有一定 Javascript 语言基础的开发人员阅读。

1. 集成SDK

// npm install
npm install --save tcadapter

// import TcAdapter
import TcAdapter from 'tcadapter';

2. 放置播放器容器

在需要展示播放器的页面加入容器，TcAdapter 仅需要承载播放视频的容器，播放样式和自定义功能可由第三方播放器或使用者自行实现

<video id="player-container-id">
</video>

3. 使用sdk

检测当前环境是否支持TcAdapter

TcAdapter.isSupported();

初始化Adapter, 创建Adapter实例

说明

初始化Adapter，初始化过程会请求腾讯云点播服务器，获取视频文件信息

接口

const adapter = new TcAdapter('player-container-id', {
  fileID: string,
  appID: string,
  psign: string,
  hlsConfig: {}
}, callback);

参数说明

参数名	类型	描述
appID	String	点播账号的 appID
fileID	String	要播放的视频fileId
psign	String	超级播放器签名
hlsConfig	HlsConfig	hls相关设置，可使用hls.js支持的任意参数
callback	TcAdapterCallBack	初始化完成回调，可以在此方法之后获取视频基本信息

注：TcAdapter 底层基于 hls.js 实现，可以通过 HlsConfig 接收 hls.js 支持的任意参数，用于对播放行为的精细调整。

获取视频的基本信息

说明

获取视频信息， 必须是在初始化之后才生效。

接口

VideoBasicInfo adapter.getVideoBasicInfo();

参数说明

VideoBasicInfo：参数如下

参数名	类型	描述
name	String	视频名称。
duration	Float	视频时长，单位：秒。
description	String	视频描述。
coverUrl	String	视频封面。

获取视频流信息

说明

接口

List<StreamingOutput> adapter.getStreamimgOutputList();

参数说明

StreamingOutput

参数名	类型	描述
drmType	String	自适应码流保护类型，目前取值有 plain 和 simpleAES。plain 表示不加密，simpleAES 表示 HLS 普通加密。
playUrl	String	播放 URL。
subStreams	List	自适应码流子流信息，类型为 SubStreamInfo。

SubStreamInfo

参数名	类型	描述
type	String	子流的类型，目前可能的取值仅有 video。
width	Int	子流视频的宽，单位：px。
height	Int	子流视频的高，单位：px。
resolutionName	String	子流视频在播放器中展示的规格名。

获取关键帧打点信息

说明

接口

List<KeyFrameDescInfo> adapter.getKeyFrameDescInfo();

参数说明

KeyFrameDescInfo

参数名	类型	描述
timeOffset	Float	1.1
content	String	"片头开始..."

获取缩略图信息

说明

接口

ImageSpriteInfo adapter.getImageSpriteInfo();

参数说明

ImageSpriteInfo

参数名	类型	描述
imageUrls	List	缩略图下载 URL 数组，类型为 String 。
webVttUrl	String	缩略图 VTT 文件下载 URL 。

监听事件

说明：播放器可以通过初始化返回的对象进行事件监听，示例：

const adapter = TcAdapter('player-container-id', options);
adapter.on(TcAdapter.TcAdapterEvents.Error, function(error) {
  // 本例中，错误事件的回调参数格式如下
  // {
  //   type: TcAdapter.TcAdapterEvents.Error,
  //   data: {
  //     type : error specific type,
  //     details : error details,
  //     fatal : is error fatal or not, 
  //     ...other error specific data
  //   }
  // }
  // do something
});

其中 type 为事件类型，支持的事件包括 hls 原生的事件以及以下事件，可从 TcAdapter.TcAdapterEvents 中访问到事件名称：

名称	介绍
LOADEDMETADATA	通过 playcgi 获取到了相应的视频信息，在此事件回调中可以获取视频相关信息
HLSREADY	hls实例创建完成，可以在此时机调用 hls 实例对象上的各种属性和方法
ERROR	出现错误时触发，可从回调参数中查看失败具体原因

Hls 事件参考链接：https://github.com/video-dev/hls.js/blob/master/docs/API.md#runtime-events

错误处理参考链接：https://github.com/video-dev/hls.js/blob/master/docs/API.md#fifth-step-error-handling

获取 Hls 实例

说明：adapter底层基于 hls.js 实现，可以通过 adapter 实例访问到 hls 实例以及实例上的属性和方法，用于实现对播放流程的精细控制

adapter.on('hlsready', () => {
  const hls = adapter.hls;
  // ...
})

参考链接：https://github.com/video-dev/hls.js/

例1：在 React 中使用 TcAdapter

查看示例：https://github.com/tcplayer/tcadapter-combine-video

import { useEffect, useRef } from 'react';
import TcAdapter from 'tcadapter';

function App() {
  if (!TcAdapter.isSupported()) {
    throw new Error('current environment can not support TcAdapter');
  }

  const videoRef = useRef(null);
  useEffect(() => {
    const adapter = new TcAdapter(videoRef.current, {
      appID: '1500002611',
      fileID: '5285890813738446783',
      psign: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MTUwMDAwMjYxMSwiZmlsZUlkIjoiNTI4NTg5MDgxMzczODQ0Njc4MyIsImN1cnJlbnRUaW1lU3RhbXAiOjE2MTU5NTEyMzksImV4cGlyZVRpbWVTdGFtcCI6MjIxNTY1MzYyMywicGNmZyI6ImJhc2ljRHJtUHJlc2V0IiwidXJsQWNjZXNzSW5mbyI6eyJ0IjoiMjIxNTY1MzYyMyJ9fQ.hRrQYvC0UYtcO-ozB35k7LZI6E3ruvow7DC0XzzdYKE',
      hlsConfig: {},
    }, () => {
      console.log('basicInfo', adapter.getVideoBasicInfo());
    });

    adapter.on(TcAdapter.TcAdapterEvents.HLSREADY, () => {
      const hls = adapter.hls;
			// ...
    })
  }, []);
  

  const play = () => {
    videoRef.current.play();
  }

  return (
    <div>	
      <div>
        <video id="player" ref={ videoRef }></video>
      </div>
      <button onClick={play}>play</button>
    </div>
  );
}

export default App;

例2: tcadapter 与 videojs 结合

查看示例：https://github.com/tcplayer/tcadapter-combine-videojs

// 1. videojs 播放 hls 会使用 @videojs/http-streaming，所以我们开发一套使用 tcadapter 播放的策略覆盖原有逻辑（也可以直接修改 @videojs/http-streaming 内部逻辑）

// src/js/index.js
import videojs from './video';
import '@videojs/http-streaming';
import './tech/tcadapter'; // 新增逻辑
export default videojs;


// src/js/tech/tcadapter.js
import videojs from '../video.js';
import TcAdapter from 'tcadapter';

class Adapter {
  constructor(source, tech, options) {
    const el = tech.el();
    // 获取参数并初始化实例
    const adapter = new TcAdapter(el, {
      appID: '1500002611',
      fileID: '5285890813738446783',
      psign: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MTUwMDAwMjYxMSwiZmlsZUlkIjoiNTI4NTg5MDgxMzczODQ0Njc4MyIsImN1cnJlbnRUaW1lU3RhbXAiOjE2MTU5NTEyMzksImV4cGlyZVRpbWVTdGFtcCI6MjIxNTY1MzYyMywicGNmZyI6ImJhc2ljRHJtUHJlc2V0IiwidXJsQWNjZXNzSW5mbyI6eyJ0IjoiMjIxNTY1MzYyMyJ9fQ.hRrQYvC0UYtcO-ozB35k7LZI6E3ruvow7DC0XzzdYKE',
      hlsConfig: {},
    });
    adapter.on(TcAdapter.TcAdapterEvents.LEVEL_LOADED, this.onLevelLoaded.bind(this));
  }

  dispose() {
    this.hls.destroy();
  }

  onLevelLoaded(event) {
    this._duration = event.data.details.live ? Infinity : event.data.details.totalduration;
  }

}

let hlsTypeRE = /^application\/(x-mpegURL|vnd\.apple\.mpegURL)$/i;
let hlsExtRE = /\.m3u8/i;

let HlsSourceHandler = {
  name: 'hlsSourceHandler',
  canHandleSource: function (source) {
    // skip hls fairplay, need to use Safari resolve it.
    if (source.skipHlsJs || (source.keySystems && source.keySystems['com.apple.fps.1_0'])) {
      return '';
    } else if (hlsTypeRE.test(source.type)) {
      return 'probably';
    } else if (hlsExtRE.test(source.src)) {
      return 'maybe';
    } else {
      return '';
    }
  },

  handleSource: function (source, tech, options) {
    if (tech.hlsProvider) {
      tech.hlsProvider.dispose();
      tech.hlsProvider = null;
    } else {
      // hls关闭自动加载后，需要手动加载资源
      if (options.hlsConfig && options.hlsConfig.autoStartLoad === false) {
        tech.on('play', function () {
          if (!this.player().hasStarted()) {
            this.hlsProvider.hls.startLoad();
          }
        });
      }
    }
    tech.hlsProvider = new Adapter(source, tech, options);
    return tech.hlsProvider;
  },
  canPlayType: function (type) {
    if (hlsTypeRE.test(type)) {
      return 'probably';
    }
    return '';
  }
};

function mountHlsProvider(enforce) {
  if (TcAdapter && TcAdapter.isSupported() || !!enforce) {
    try {
      let html5Tech = videojs.getTech && videojs.getTech('Html5');
      if (html5Tech) {
        html5Tech.registerSourceHandler(HlsSourceHandler, 0);
      }
    } catch (e) {
      console.error('hls.js init failed');
    }
  } else {
    //没有引入tcadapter 或者 MSE 不可用或者x5内核禁用
  }
}
mountHlsProvider();
export default Adapter;