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	ライブ配信またはVODモードを設定します。モードによってhls.jsのパラメータが自動的に設定されます。
announce	string	'https://cn.cdnbye.com/v1'	trackerサーバーのアドレス。
trackerZone	string	'eu'	trackerサーバーアドレスの国コード。'cn'、'eu'、'hk'、'us' に分かれます。
memoryCacheLimit	Object	*{"pc": 400 1024 * 1024, "mobile": 100 * 1024 * 1024}**	メモリキャッシュの最大データ量。PCとmobileに分かれます。
p2pEnabled	boolean	true	P2Pを有効にするかどうか。
webRTCConfig	Object	{}	stunとdatachannelを設定するための辞書オブジェクト。
useHttpRange	boolean	true	可能な場合にHttp Rangeリクエストを使用して、p2pダウンロードのタイムアウトによる残りのデータを補完します。
sharePlaylist	boolean	false	m3u8ファイルのP2P伝送を許可するかどうか。
strictSegmentId	boolean	false	デフォルトのシーケンス番号ベースの代わりに、urlベースのSegmentIdを使用します。
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	VODモードでIndexedDBを使ってデータを保存します。
diskCacheLimit	Object	*{"pc": 1500 1024 * 1024, "mobile": 1000 * 1024 * 1024}**	ディスクキャッシュの最大データ量。PCとmobileに分かれます。
prefetchOnly	boolean	false	プリフェッチ方式のみでP2Pダウンロードを行います。
startFromSegmentOffset	number	3	trackerサービスへのリクエストを開始するsegmentオフセット。

P2pEngineHls のプロパティとメソッド

P2pEngineHls.version (static)

SDK のバージョン番号を取得します。

P2pEngineHls.protocolVersion (static)

P2Pプロトコルのバージョン番号を取得します。他のプラットフォームと相互接続するには、P2Pプロトコルのバージョン番号が同じである必要があります。

P2pEngineHls.HlsjsEngine (static)

Hlsjsベースの P2pEngine のコンストラクタを取得します。

P2pEngineHls.ServiceWorkerEngine (static)

ServiceWorkerベースの P2pEngine のコンストラクタを取得します。

P2pEngineHls.tryRegisterServiceWorker(config) (static)

ServiceWorkerを登録するための静的メソッドです。config を指定した場合、対応するデフォルト値は上書きされます。

フィールド	型	デフォルト値	説明
swFile	string	'./sw.js'	ServiceWorkerファイル名とパス。
swScope	string	'./'	ServiceWorkerのデフォルトのスコープは現在のディレクトリとすべてのサブディレクトリです。

P2pEngineHls.getBrowser() (static)

ブラウザの名称を取得します。取りうる値は以下の通りです：

Chrome
Firefox
Mac-Safari
iOS-Safari
X5
Unknown

P2pEngineHls.isSupported() (static method)

現在のブラウザがWebRTC data channelに対応しているか、および MSE または ServiceWorker のいずれかに対応しているかを判定します。

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()

ServiceWorkerを登録し、promiseを返します。

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情報を取得する

javascript

p2pConfig: {
    getStats: function (totalP2PDownloaded, totalP2PUploaded, totalHTTPDownloaded, p2pDownloadSpeed) {
        // p2pダウンロード情報を取得
    },
    getPeerId: function (peerId) {
        // 自ノードのIdを取得
    },
    getPeersInfo: function (peers) {
        // 接続に成功したノードの情報を取得
    },
    onHttpDownloaded: function (traffic) {
        // httpダウンロードトラフィックを監視
    },
    onP2pDownloaded: function (traffic, speed) {
        // p2pダウンロードトラフィックと速度を監視
    },
    onP2pUploaded: function (traffic) {
        // p2pアップロードトラフィックを監視
    },
}

WARNING

ダウンロード・アップロードデータ量の単位はKB、ダウンロード速度の単位はKB/sです。

Hls.jsに追加された新しいAPI

Hls.engineVersion (static method)

本プラグインの現在のバージョン番号

Hls.WEBRTC_SUPPORT (static method)

現在のブラウザがWebRTCに対応しているかを判定します

javascript

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

Hls.P2pEngine (static method)

HlsからP2pEngineを取得します。直接importする 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	false	ライブ配信モードでのみ有効。m3u8ファイルに "#EXT-X-START:TIME-OFFSET=[playlistTimeOffset]" を挿入し、プレイヤーを強制的に特定の位置から読み込ませます
playlistTimeOffset	number	0.01	insertTimeOffsetTag=true の場合のみ有効。負の値の場合、プレイリストの末尾からのオフセットになります（単位：秒）
allowedMediaFiles	Array	['ts', 'mp4', 'm4s', 'fmp4']	サポートが必要なメディアファイルの拡張子。例：['txt', 'png']。拡張子がない場合は ['*'] を設定できます
mediaFileSeparator	String	'.'	メディアファイル拡張子の区切り文字
allowedPlaylistSuffix	Array	['m3u8']	サポートが必要な追加のプレイリストファイル拡張子。例：['txt']

HlsProxy.version (static)

HlsProxyのバージョン番号を取得します。

高度な使い方

動的に変化するm3u8パスの問題を解決する

一部のストリーミング配信事業者のm3u8は動的に生成されており、ノードごとにm3u8のアドレスが異なります。例えばexample.com/clientId1/streamId.m3u8とexample.com/clientId2/streamId.m3u8のようになります。本プラグインはデフォルトでm3u8のアドレス（クエリパラメータを除いたもの）をchannelIdとして使用します。このような場合、実際に同じライブ配信/動画を視聴しているノードを同じチャンネルに配置するために、共通のchannelIdを構築する必要があります。

javascript

// channelId をカスタマイズするには、先に p2pConfig で token を設定する必要があります！他のプラットフォームと相互接続するには、同一の token と channelId が必要です。
p2pConfig: {
    token: YOUR_TOKEN,
    channelId: function (m3u8Url) {
        const videoId = extractVideoIdFromUrl(m3u8Url);   // 差異のある部分を無視し、一貫したchannelIdを構築します。extractVideoIdFromUrlは自身で定義する必要があり、url内の動画IDを抽出して結果として返すことができます
        return videoId;
    }
    // channelId: VIDEO_ID       // for fixed channel id
}

http://example.com/token123456/video1/playlist.m3u8 を例にすると、token123456はユーザーごとに異なるtoken、video1は動画の一意のIDです。

javascript

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

WARNING

他のプラットフォームと相互接続する場合は、両者が同じ token と channelId を持つことを必ず確認してください。

Http Rangeリクエストを許可する

ピア側のアップロード帯域幅が不足している場合、p2p伝送がタイムアウトしてhttpダウンロードに切り替わることがあり、元々p2pでダウンロードしたデータを再利用できなくなります。Http Rangeリクエストは、p2pダウンロードのタイムアウトによって残った部分のデータを補完するために使用されます。Http Rangeを有効にするには、まずオリジンサーバー側の対応が必要です。Http Rangeリクエストを許可するを参照した上で、以下の設定を追加してください：

javascript

p2pConfig: {
    useHttpRange: true,
}

特定のセグメントファイルを除外する

特定のセグメントファイル、例えばSSAI（Server Side Ad Insertion）によって生成されたユーザー固有のセグメントをP2Pに参加させたくない場合があります。このような場合、segmentBypass 関数を利用してフィルタリングできます：

javascript

p2pConfig: {
    segmentBypass: (url, tags) => {
        return isSSAISegment(url)
    },
}

sw.js で再生時間オフセットを設定する

m3u8に特殊なタグを設定することで、プレイヤーを強制的にリストの先頭位置から読み込ませることができ、P2Pの効果を向上させられますが、同時に遅延が増加するため、トレードオフを考慮する必要があります。

javascript

// sw.js
self.importScripts('https://cdn.jsdmirror.com/npm/@swarmcloud/hls/hls-proxy.js')
new HlsProxy({
    insertTimeOffsetTag: true,
    playlistTimeOffset: 0.01,
})

Service Workerモードでより多くの拡張子をサポートするには？

sw.jsがデフォルトでサポートするplaylistの拡張子はm3u8、デフォルトでサポートするメディアファイルの拡張子は 'ts', 'mp4', 'm4s', 'fmp4' です。より多くの拡張子をサポートする必要がある場合は、カスタム設定を行うことができます：

javascript

self.importScripts('https://cdn.jsdmirror.com/npm/@swarmcloud/hls/hls-proxy.js')
new HlsProxy({
    allowedPlaylistSuffix: ['m3u8', 'html'],     // サポートが必要なプレイリストurlが xxx.html の場合
    allowedMediaFiles: ['ts', 'mp4', 'm4s', 'fmp4', 'jpg'], // サポートが必要なメディアファイルurlが xxx.jpg の場合
    // allowedMediaFiles: ['*']   // 拡張子がない場合
})

STUNとTURNサーバーアドレスを自分で設定する

STUNはp2p接続の過程でグローバルIPアドレスを取得するために使用され、TURNはp2p接続が疎通しない場合にデータを中継するために使用できます。本SDKには公開のSTUNサービスが内蔵されており、開発者はP2pConfigを通じてSTUNアドレスを変更できます。TURNサーバーは開発者自身が構築する必要があり、coturnを参考にできます。

javascript

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

セグメントのハッシュ検証

ノードからダウンロードしたセグメントの正当性を検証する必要がある場合があります（bittorrentのハッシュ検証に類似）。 SDKはフック関数を提供しており、ダウンロードしたセグメントをコールバックして開発者が検証できるようにします。検証に使用するハッシュテーブルはサーバーから直接ダウンロードすることを推奨します。開発者はプログラムで各tsファイルのハッシュを計算し、特定のファイルに保存するか、m3u8ファイルに直接埋め込むことができます。検証に失敗した場合は、コールバック関数内で直接falseを返すだけで構いません。

javascript

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

P2pEngineHls API ​

var engine = new P2pEngineHls(p2pConfig); ​

P2pEngineHls のプロパティとメソッド ​

P2pEngineHls.version (static) ​

P2pEngineHls.protocolVersion (static) ​

P2pEngineHls.HlsjsEngine (static) ​

P2pEngineHls.ServiceWorkerEngine (static) ​

P2pEngineHls.tryRegisterServiceWorker(config) (static) ​

P2pEngineHls.getBrowser() (static) ​

P2pEngineHls.isSupported() (static method) ​

P2pEngineHls.isMSESupported() (static) ​

P2pEngineHls.isServiceWorkerSupported() (static) ​

engine.realEngine ​

engine.engineName ​

engine.enableP2P() ​

engine.disableP2P() ​

engine.destroy() ​

engine.registerServiceWorker() ​

engine.unregisterServiceWorker() ​

P2pEngineHls のイベント ​

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

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

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

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

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

p2pConfigを通じてp2p情報を取得する ​

Hls.jsに追加された新しいAPI ​

Hls.engineVersion (static method) ​

Hls.WEBRTC_SUPPORT (static method) ​

Hls.P2pEngine (static method) ​

インスタンス化とパラメータ設定 ​

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

hls.p2pEngine ​

HlsProxy API ​

new HlsProxy(config); ​

HlsProxy.version (static) ​

高度な使い方 ​

動的に変化するm3u8パスの問題を解決する ​

Http Rangeリクエストを許可する ​

特定のセグメントファイルを除外する ​

sw.js で再生時間オフセットを設定する ​

Service Workerモードでより多くの拡張子をサポートするには？ ​

STUNとTURNサーバーアドレスを自分で設定する ​

セグメントのハッシュ検証 ​

P2pEngineHls API

var engine = new P2pEngineHls(p2pConfig);

P2pEngineHls のプロパティとメソッド

P2pEngineHls.version (static)

P2pEngineHls.protocolVersion (static)

P2pEngineHls.HlsjsEngine (static)

P2pEngineHls.ServiceWorkerEngine (static)

P2pEngineHls.tryRegisterServiceWorker(config) (static)

P2pEngineHls.getBrowser() (static)

P2pEngineHls.isSupported() (static method)

P2pEngineHls.isMSESupported() (static)

P2pEngineHls.isServiceWorkerSupported() (static)

engine.realEngine

engine.engineName

engine.enableP2P()

engine.disableP2P()

engine.destroy()

engine.registerServiceWorker()

engine.unregisterServiceWorker()

P2pEngineHls のイベント

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

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

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

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

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

p2pConfigを通じてp2p情報を取得する

Hls.jsに追加された新しいAPI

Hls.engineVersion (static method)

Hls.WEBRTC_SUPPORT (static method)

Hls.P2pEngine (static method)

インスタンス化とパラメータ設定

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

hls.p2pEngine

HlsProxy API

new HlsProxy(config);

HlsProxy.version (static)

高度な使い方

動的に変化するm3u8パスの問題を解決する

Http Rangeリクエストを許可する

特定のセグメントファイルを除外する

sw.js で再生時間オフセットを設定する

Service Workerモードでより多くの拡張子をサポートするには？

STUNとTURNサーバーアドレスを自分で設定する

セグメントのハッシュ検証