API文档

SwarmCloud

# P2pEngineHls API

# var engine = new P2pEngineHls(p2pConfig);

实例化 P2pEngineHls。

如果指定了 p2pConfig ，那么对应的默认值将会被覆盖。

字段	类型	默认值	描述
hlsjsInstance	Hlsjs	null	Hlsjs的實例化對象，如果沒有傳入則不會啟用基於 Hlsjs 的引擎。
proxyOnly	boolean	false	是否強制啟用基於 ServiceWorker 的引擎。
logLevel	string\|boolean	'error'	log的等级，分为'warn'、'error'、'none'，设为true等于'warn'，设为false等于'none'。
token	string	undefined	token用于控制台多域名数据汇总展示，另外如果自定义channelId也需要设置token。
live	boolean	true	设置直播或者点播模式，不同模式会自动设置不同的hls.js参数。
announce	string	'https://cn.cdnbye.com/v1'	tracker服务器地址。
trackerZone	string	'cn'	tracker服务器地址的国家代号，分为'cn'、'hk'、'us'。
memoryCacheLimit	Object	{"pc": 600 * 1024 * 1024, "mobile": 300 * 1024 * 1024}	内存缓存的最大数据量，分为PC和mobile。
p2pEnabled	boolean	true	是否开启P2P。
webRTCConfig	Object	{}	用于配置stun和datachannel的字典 (opens new window)。
useHttpRange	boolean	true	在可能的情况下使用Http Range请求来补足p2p下载超时的剩余部分数据。
httpLoadTime	number	3.0	P2P下载超时后留给HTTP下载的时间。
sharePlaylist	boolean	false	是否允许m3u8文件的P2P传输。
geoIpPreflight	boolean	true	向在线IP数据库请求ASN等信息，从而获得更准确的调度，会延迟P2P启动时间。
swAutoRegister	boolean	true	是否在初始化基於 ServiceWorker 的引擎後自動註冊 ServiceWorker 。
swFile	string	'./sw.js'	ServiceWorker文件名和路径。
swScope	string	'./'	ServiceWorker默认作用域是当前目录以及所有子目录，因此如果将 sw.js 放在网站根目录，那么所有网站请求都在 ServiceWorker 控制范围内。
mediaElem	HTMLMediaElement\|string	undefined	指定media标签的id或者Element对象，默认是document中的第一个video或audio元素。
useDiskCache	boolean	true	点播模式用 IndexedDB 存储数据。
diskCacheLimit	Object	{"pc": 2500 * 1024 * 1024, "mobile": 1500 * 1024 * 1024}	磁盘缓存的最大数据量，分为PC和mobile。

# P2pEngineHls 屬性和方法

# P2pEngineHls.version (static)

获取 SDK 的版本号。

# P2pEngineHls.protocolVersion (static)

获取 P2P 协议的版本号，与其他平台互通的前提是 P2P 协议版本号相同。

# P2pEngineHls.HlsjsEngine (static)

获取基於 Hlsjs 的 P2pEngine 的构造函数。

# P2pEngineHls.ServiceWorkerEngine (static)

获取基於 ServiceWorker 的 P2pEngine 的构造函数。

# P2pEngineHls.getBrowser() (static)

獲取瀏覽器的名稱，可能取值如下：

Chrome
Firefox
Mac-Safari
iOS-Safari
X5
Unknown

# P2pEngineHls.isSupported() (static method)

判断当前浏览器是否支持WebRTC data channel ，以及 MSE 或者 SeviceWorker 其中之一。

# P2pEngineHls.isMSESupported() (static)

判断当前浏览器是否支持 MEDIA SOURCE EXTENSIONS 。

# P2pEngineHls.isServiceWorkerSupported() (static)

判断当前浏览器是否支持 ServiceWorker 。

# engine.realEngine

獲取目前啟用的內部引擎實例。

# engine.engineName

獲取目前啟用的內部引擎的名稱，可能取值如下：

HlsjsP2pEngine
HlsSwP2pEngine

# engine.enableP2P()

在p2p暂停或未启动情况下启动p2p。

# engine.disableP2P()

停止p2p并释放内存。

# engine.destroy()

停止p2p、销毁engine并释放内存。在Hls.js销毁时会自动调用。

# engine.registerServiceWorker()

# engine.unregisterServiceWorker()

销毁 ServiceWorker 并返回一个 promise 。

# P2pEngineHls事件

# engine.on('peerId', function (peerId) {})

当从服务端获取到peerId时回调该事件。

# engine.on('peers', function (peers) {})

当与新的节点成功建立p2p连接时回调该事件。

# engine.on('stats', function (stats) {})

该回调函数可以获取p2p信息，包括：
stats.totalHTTPDownloaded: 从HTTP(CDN)下载的数据量（单位KB）
stats.totalP2PDownloaded: 从P2P下载的数据量（单位KB）
stats.totalP2PUploaded: P2P上传的数据量（单位KB）
stats.p2pDownloadSpeed: P2P下载速度（单位KB/s）

# engine.on('serverConnected', function (connected) {})

当连接/断开websocket时回调该事件。

# engine.on('exception', function (e) {})

该回调函数可以获取SDK的异常信息，包括：
e.code: 异常标识（TRACKER_EXPT SIGNAL_EXPT HLSJS_EXPT）
e.message: 异常信息
e.stack: 异常堆栈信息

# 通过p2pConfig获取p2p信息

p2pConfig: {
    getStats: function (totalP2PDownloaded, totalP2PUploaded, totalHTTPDownloaded, p2pDownloadSpeed) {
        // 获取p2p下载信息
    },
    getPeerId: function (peerId) {
        // 获取本节点的Id
    },
    getPeersInfo: function (peers) {
        // 获取成功连接的节点的信息
    }
}

# 在Hls.js增加的新API

# Hls.engineVersion (static method)

当前插件的版本号

# Hls.WEBRTC_SUPPORT (static method)

判断当前浏览器是否支持WebRTC

if (Hls.WEBRTC_SUPPORT) {
  // WebRTC is supported
} else {
  // Use a fallback
}

# Hls.P2pEngine (static method)

從Hls獲取 P2pEngine ，等價於直接引入的 P2pEngineHls

# 实例化与参数配置

# var hls = new Hls({p2pConfig: [opts]});

创建一个新的Hls实例。其中 p2pConfig 等价于传入 P2pEngineHls 的 p2pConfig ，此时无需再指定 hlsjsInstance

# hls.p2pEngine

从 Hls 实例中获取 P2pEngineHls 实例。

# HlsProxy API

# new HlsProxy(config);

创建一个 HlsProxy 实例。

如果指定了 config ，那么对应的默认值将会被覆盖。

字段	类型	默认值	描述
httpHeadersForPlaylist	function(url, headers)	null	设置m3u8请求的自定义http头，如：httpHeadersForPlaylist: (url, headers) => { headers.set('token', 'xxx') }
httpHeadersForMediaFile	function(url, headers)	null	设置ts请求的自定义http头，如：httpHeadersForMediaFile: (url, headers) => { headers.set('token', 'xxx') }
insertTimeOffsetTag	boolean	true	仅在直播模式生效，在m3u8文件中插入 #EXT-X-START:TIME-OFFSET=0.01 ，强制播放器从m3u8的第一个ts开始加载
allowedMediaFiles	Array	undefined	需要支持的额外的媒体文件后缀，如 ['txt', 'png']

# HlsProxy.version (static)

获取 HlsProxy 的版本号。

# 高级用法

# 解决动态m3u8路径问题

某些流媒体提供商的m3u8是动态生成的，不同节点的m3u8地址不一样，例如example.com/clientId1/streamId.m3u8和example.com/clientId2/streamId.m3u8，而本插件默认使用m3u8地址(去掉查询参数)作为channelId。这时候就要构造一个共同的chanelId，使实际观看同一直播/视频的节点处在相同频道中。

// 必须先在 p2pConfig 设置 token ，才能自定义 channelId ! 与其他平台互通需要相同的 token 和 channelId 。
p2pConfig: {
    token: YOUR_TOKEN,
    channelId: function (m3u8Url) {
        const videoId = extractVideoIdFromUrl(m3u8Url);   // 忽略差异部分，构造一个一致的channelId，其中 extractVideoIdFromUrl 需要自己定义，可以抽取url中的视频ID作为结果返回
        return videoId;
    }
}

用 http://example.com/token123456/video1/playlist.m3u8 来举例, 其中 token123456 是根据不同用户产生的token，video1 是视频的唯一ID。

p2pConfig: {
    token: YOUR_TOKEN,
    channelId: function (m3u8Url) {
        var parts = m3u8Url.split('/');
        var videoId = parts[parts.length-2]+'/'+parts[parts.length-1];
        return videoId;
    }
}

按如上配置后，结果如下，token被去掉，只保留video ID：

<!-- URL to be replaced -->
http://example.com/token123456/video1/playlist.m3u8
<!-- Resulting channelId -->
video1/playlist.m3u8

如果要与其他平台互通，则必须确保两者拥有相同的 token 和 channelId 。

# P2P优先策略

由于建立P2P连接需要时间，默认情况下前几片用HTTP下载。可以通过配置参数，等待P2P建立连接后优先用P2P下载，从而提升P2P效果，但可能会带来延时，建议在热度比较大的频道开启。

p2pConfig: {
    waitForPeer: true,
    waitForPeerTimeout: 4.0,     // 可以根据具体场景设置超时时间
    sourceUrl: M3U8_URL,         // m3u8地址， 如：'http://xxx.m3u8'
}

# 允许Http Range请求

当对等端上行带宽不够时，可能导致p2p传输超时而转向http下载，原本p2p下载的数据无法复用。Http Range请求用于补足p2p下载超时的剩余部分数据，要开启Http Range，首先需要源服务器支持，请参考允许Http Range请求，然后增加以下配置：

p2pConfig: {
    useHttpRange: true,
}

# 自行配置 STUN 和 TURN 服务器地址

STUN用于p2p连接过程中获取公网IP地址，TURN则可以在p2p连接不通时用于中转数据。本SDK已内置公开的STUN服务，开发者可以通过P2pConfig来更换STUN地址。TURN服务器则需要开发者自行搭建，可以参考coturn (opens new window)。

p2pConfig: {
    webRTCConfig: {
       iceServers: [
           { urls: YOUR_STUN_OR_TURN_SERVER }
       ]
    }
}

# 切片Hash校验

有时候我们需要校验从节点下载的切片的合法性（类似bittorrent的哈希校验）。 SDK提供了一个钩子函数，可以回调下载的切片供开发者进行校验。用于校验的哈希表建议直接从服务器下载，开发者可以通过程序计算每个ts文件的哈希并存储于特定的文件中或者直接嵌入到m3u8文件中。如果校验失败，直接在回调函数中返回false即可。

p2pConfig: {
   validateSegment: function (segId, buffer) {
       var hash = hashFile.getHash(segId);
       return hash === md5(buffer);
   }
}