HLSプラグインの基本
HLS プラグインを理解し、使用するには、次の点が役立ちます。
- このドキュメントの冒頭文で述べたように、プラグインは W3C のメディアソース拡張 (MSE) に依存しています。MSE は W3C 仕様で、JavaScript が HTML5 ビデオをサポートするウェブブラウザ内のメディアコーデックにバイトストリームを送信できるようにします。他の可能な用途の中でも、これにより、ストリーミングメディアのクライアント側のプリフェッチとバッファリングコードを JavaScript で完全に実装できます。
- プラグインを使用すると、プレーヤーで HLS (m3u8) ビデオコンテンツを使用できます。たとえば、メディアセクションでこの設定を使用してプレーヤーを作成できます。
"media":{ "sources": [{ "src": "http://example.com/video.m3u8", "type": "application/x-mpegURL" }] }
- クロスオリジンリソース共有 (CORS) は、HLS を使用するときに問題になる可能性があります。CORS の使用方法の詳細については、 CORS ガイドを参照してください。
- HLS は IE11 より前のバージョンの IE ではサポートされていません。
概要
HTTP ライブストリーミング (HLS) は、iOS と Android でのネイティブサポートのおかげで、モバイルデバイスでのビデオのストリーミングのデファクトスタンダードとなっています。しかし、フォーマットを推奨するプラットフォームに依存しない理由はいくつかあります。
- (クライアント駆動の)アダプティブビットレート選択をサポート
- 標準 HTTP ポート経由で配信
- シンプルなテキストベースのマニフェスト形式
- 独自のストリーミングサーバは不要
残念ながら、Safariを除くすべての主要なデスクトップブラウザには、HLSのサポートがありません。これにより、ウェブ開発者は同じビデオの代替レンディションを維持し、潜在的に最高のデスクトップ視聴体験を提供するために、HTMLベースのビデオを完全に見守らなければならないという残念な立場にあります。
このプラグインは、Media Source Extensions または Flash をサポートするブラウザーで HLS 用のポリフィルを提供することで、状況に対処します。単一のHLSストリームをデプロイし、通常のHTML5ビデオAPIに対してコードを記述し、すべての大きなWebデバイスカテゴリにわたって高速で高品質のビデオエクスペリエンスを作成できます。
現在、この時点では いいえ 次のサポート:
- 代替オーディオおよびビデオトラック
- セグメントコーデック 以外 H.264 AAC オーディオ付き
- Internet Explorer <11
オプション
HLS プラグインの設定には、いくつかのオプションがあります。
クレデンシャル付き
タイプ: boolean
以下として使用できます。
- ソースオプション
- 初期化オプション
withCredentials
プロパティがに設定されている場合true
、マニフェストとセグメントに対するすべての XHR 要求にはwithCredentials
true
もに設定します。これにより、マニフェストとセグメントが保存されているサーバーから Cookie を保存し、渡すことができます。これは、CORSにいくつかの影響があります。なぜなら、Access-Control-Allow-Origin
設定するとヘッダーをに設定できないからです。また*
、レスポンスヘッダーにはAccess-Control-Allow-Credentials
ヘッダーにセットされますtrue
。を参照してくださいHTML5Rocksの記事詳細については。
プラグインは、プレーヤー管理API HTTPを使用するPATCH
ここに示すように、メソッド:
curl \
--header "Content-Type: application/json" \
--user YOUR_EMAIL \
--request PATCH \
--data '{ "hls": { "withCredentials": true } }' \
https://players.api.brightcove.com/v2/accounts/YOUR_ACCOUNT_ID/players/YOUR_PLAYER_ID/configuration
表示されているように、プレイヤーベースではなく、withCredentials
ソースごとにオプションを設定することもできます。たとえば、ソースを設定するときに、次に示すようにwithCredentials
、含めることができます。
curl \
--header "Content-Type: application/json" \
--user $EMAIL \
--request POST \
--data '{
"name": "MySamplePlayer",
"configuration": {
"media": {
"sources": [{
"src":"http://solutions.brightcove.com/bcls/assets/videos/Tiger.mp4",
"type":"video/mp4",
"withCredentials": true
}]
}
}
}' \
https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players
ランタイム設定
withCredentials
実行時にを設定できます。あなたは2つの実装の下に表示されます:
- 使用して
player.hls.xhr.beforeRequest
- 使用して
player.src()
次のコードでは、player.hls.xhr.beforeRequest
を使用して関数を割り当てて、オプションを含むオブジェクトとともに呼び出されます。この関数は、xhr
リクエスト。この例では、withCredentials
が構成されているだけが表示されます。
if (videojs.Hls) {
videojs.Hls.xhr.beforeRequest = function (options) {
options.withCredentials = true;
}
}
withCredentials
ビデオソースを設定するときにオプションを設定することもできます。あなたはplayer.src()
ここに示すように、メソッド:
player.src({
src: 'https://adomain.com/bipbop_16x9_variant.m3u8',
type: 'application/x-mpegURL',
withCredentials: true
});
EnableLoWinitialPlaylist
タイプ: boolean
デフォルト:undefined
(ブラウザがAndroidデバイスで表示されている場合を除く)。その後、に設定されますtrue
。Android デバイスの場合、以下のように、プレーヤーにパッチを適用することで、この動作を変更できますfalse
。
次のように使用できます。
- 初期化オプション
が true enableLowInitialPlaylist
に設定されている場合、最初に最も低いビットレートのプレイリストを選択するために使用されます。これは、再生開始時間を短縮するのに役立ちます。
以下に示すように、HTTP PATCH
メソッドを使用してプレーヤー管理 API を使用してプラグインを設定できます。
curl \
--header "Content-Type: application/json" \
--user YOUR_EMAIL \
--request PATCH \
--data '{ "hls": { "enableLowInitialPlaylist": true } }' \
https://players.api.brightcove.com/v2/accounts/YOUR_ACCOUNT_ID/players/YOUR_PLAYER_ID/configuration
ランタイム・プロパティ
一般に、HLS オブジェクトには次のようにアクセスできます。
- Brightcove Player v5:
player.hls
- ブライトコーブプレイヤー v6:
player.tech().hls
player.hls.playlists.master
タイプ: object
解析されたマスタープレイリストを表すオブジェクト。メディアプレイリストを直接ロードすると、エントリが 1 つだけのマスタープレイリストが作成されます。
player.hls.playlists.media
タイプ: function
現在アクティブなメディアプレイリストを取得または変更するために使用できる機能。アクティブなメディアプレイリストは、追加のビデオデータをダウンロードする必要があるときに参照されます。引数なしでこの関数を呼び出すと、アクティブなメディアプレイリストの解析済みプレイリストオブジェクトが返されます。マスタープレイリストまたはマスタープレイリストで指定された URI 文字列からプレイリストオブジェクトを使用してこの関数を呼び出すと、指定されたメディアプレイリストの非同期ロードがキックオフされます。取り出されると、アクティブなメディアプレイリストになります。
player.hls帯域幅を
タイプ: number
最後のセグメントのダウンロードで 1 秒あたりにダウンロードされたビット数。この値は、の既定の実装で、selectPlaylist
再生する適切なビットレートを選択するために使用されます。最初のビデオセグメントがダウンロードされる前に、帯域幅を正確に推定することは困難です。HLS 技術では、プレイリストのダウンロード時間に基づくヒューリスティックを使用して、デフォルトでこの推定を行います。より正確な帯域幅情報のソースがある場合は、HLS 技術がロードされるとすぐにこの値を上書きして、初期帯域幅の見積もりを提供できます。
Player.hls.Stats.bytesReceived
タイプ: number
HLS 技術によってダウンロードされたコンテンツバイトの総数。
Player.hls.SelectPlaylist
タイプ: function
次のセグメントのダウンロードに使用するメディアプレイリストオブジェクトを返す関数。これは、新しいセグメントがダウンロードされる直前にプラグインによって呼び出されます。この関数をオーバーライドして、アダプティブストリーミングロジックを提供できます。ただし、に存在する有効なメディアプレイリストオブジェクトを必ず返す必要がありますplayer.hls.playlists.master
。
イベント
ロードされたメタデータ
ストリーム用に最初のメディアプレイリストがダウンロードされた後に発生します。
loadedPlaylist
新しいマスタープレイリストまたはメディアプレイリストがダウンロードされた直後に発生します。デフォルトでは、プラグインは必要に応じてプレイリストをダウンロードするだけです。
メディアチャンジ
新しいプレイリストがアクティブなメディアプレイリストになったときに発生します。実際のレンダリング品質の変更は、このイベントと同時に発生しません。新しいセグメントを要求し、既存のバッファを最初に枯渇させる必要があります。
エラー時にソースを再ロード
HLS プラグインを使用する場合、プレーヤーによってエラーが発生したときにソースを現在の時刻にリロードするメソッドを呼び出すことができます。この機能をオンにするには、reloadSourceOnError()
メソッドを呼び出す必要があります。次の短いビデオは、アクション中のメソッドを示しています。ビデオに示されているすべてのコードについては、このセクションの後半で説明します。
の構文reloadSourceOnError()
方法は次のとおりです。
reloadSourceOnError(optionsObject)
optionsObject
オプションには、次のプロパティがあります。
プロパティ | データタイプ | デフォルト値 | 説明 |
---|---|---|---|
errorInterval |
[番号] | 30 | リロードがトリガーされるために、2 つのエラーの間に経過する最小時間(秒単位)。たとえば、時刻を 10 に設定した場合、エラーが発生するたびに、関数は 10 秒未満前にリロードが発生したかどうかをチェックします。時間間隔よりも短い場合は、ソースをリロードしません。(これは、エラーのあるコンテンツが絶えずリロードされないようにするためです)。指定した間隔よりも長い時間が経過すると、エラーが発生した時点でビデオが再ロードされます。 |
getSource() |
関数 | 現在のソースを取得します | ロードまたはリロードするソースオブジェクトを取得するために呼び出される関数。デフォルトでは、プレーヤーの現在のソースを取得します。 |
上記のビデオデモで使用されたコードの詳細を次に示します。
- 1 ~ 9 行目:
id
プレーヤーが追加された標準のページ内埋め込みコード。 - 11行目:エラーを手動で作成するボタン。
- 22~24行目は次のとおりです。ボタンをクリックしたときに呼び出され、エラーをディスパッチします。
- 19行目:設定オプションを配置するオブジェクトを作成します。
- 20行目です:設定オブジェクトで、
errorInterval
プロパティを作成し、値を割り当てます。 - 21行目です:
reloadSourceOnError()
メソッドを呼び出し、設定オブジェクトを引数として渡します。
<video-js id="myPlayerID"
data-video-id="4607746980001"
data-account="1507807800001"
data-player="HJLp3Hvmg"
data-embed="default"
data-application-id
class="video-js"
controls
></video-js>
<p><button onclick="createError()">createError</button></p>
<script src="https://players.brightcove.net/1507807800001/HJLp3Hvmg_default/index.min.js"></script>
<script type="text/javascript">
var createError;
videojs.getPlayer('myPlayerID').ready(function() {
var myPlayer = this,
reloadOptions = {};
reloadOptions.errorInterval = 10;
myPlayer.reloadSourceOnError(reloadOptions);
createError = function(){
myPlayer.error({code:'2'});
}
});
</script>
マニフェストの WebVTT
HLS プラグインは、マニフェストの WebVTT をサポートします。プラグインでは標準であるため、この機能を有効にするために必要なことは何もありません。ビデオは、マニフェスト内のWebVTTを考慮して取り込む必要があります。たとえば、ブライトコーブの動的取り込み APIでは、動画の取り込み、キャプションをマニフェストとして設定できます。概要を参照してください。詳細については、ダイナミックデリバリーの動的取り込み API ドキュメントを参照してください。
以下のプレーヤーは、マニフェスト内のWebVTTキャプション付きのビデオを再生しています。次に示すように、キャプションアイコンからキャプションを選択できます。
ビデオを開始すると、見たいキャプションを選択できるようになります。
簡単に見ると、これはあなたが自分で構築しないものであるため、上記のプレーヤーに示されたビデオのマニフェストがここにあります:
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="Woofer",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="en",URI="subtitles/en/index.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="Woofer (Forced)",DEFAULT=NO,AUTOSELECT=NO,FORCED=YES,LANGUAGE="en",URI="subtitles/en_forced/index.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="Spanish",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="es",URI="subtitles/es/index.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="Spanish (Forced)",DEFAULT=NO,AUTOSELECT=NO,FORCED=YES,LANGUAGE="es",URI="subtitles/es_forced/index.m3u8"
#EXT-X-STREAM-INF:BANDWIDTH=865000,CODECS="mp4a.40.2, avc1.42001e",RESOLUTION=640x360,SUBTITLES="subs"
865/prog_index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=12140000,CODECS="mp4a.40.2, avc1.42001e",RESOLUTION=1280x720,SUBTITLES="subs"
12140/prog_index.m3u8
その中には、キャプションファイルへの参照があります。
アダプティブスイッチング
HLS レンディションの選択
再生中、プレーヤーはアルゴリズムに基づいてより高いレンディションまたは低いレンディションに切り替わります。このアルゴリズムへの入力は次のとおりです。
- 使用可能な帯域幅
- プレーヤーの寸法
レンディションの選択の詳細については、「どのレンディションを再生するかを決定する」ドキュメントを参照してください。
MP4 レンディションの選択
何らかの理由で Brightcove Player が HLS ソースを再生できない場合、MP4 の再生にフォールバックします。この場合、モバイルデバイス上でビデオを表示し、MP4を再生する場合、プレーヤーは.5 MB/秒に最も近いビットレートを持つMP4を選択します。デスクトップまたはラップトップデバイスでは、3 MB/秒に最も近いMP4レンディションが選択されます。
インバンドメタデータ
Brightcove Player は、HLS 動画ストリームに埋め込まれた特定の種類の ID3 タグ情報を認識します。ID3 規格は、もともと MP3 オーディオトラックに関するメタデータを提供するために使用されました。(頭字語は、 ID エンフィー MP 3 から。)埋め込みメタデータでストリームが検出されると、ストリーム内で検出されたキューがインバンドメタデータテキストトラックに自動的に作成され、キューが入力されます。一般的なユースケースは、広告をライブストリームに表示する必要があるときに ID3 データが指示される場合です。
ID3 標準では、多くのフレームタイプが定義されていますが、次の 2 つの UTF-8 エンコードフレームのみがキューポイントにマップされ、キューテキストとして値が設定されます。
- WXXX-ユーザー定義URLリンクフレーム
- TXXX-ユーザー定義テキスト情報フレーム
キューは、他のすべてのフレームタイプに対して作成され、生成されたキューにデータがアタッチされます。
cue.frame.data
テキストトラック全般の詳細については、「トラックエレメントの使用を開始する」を参照してください。Brightcove Player とキューポイントの詳細については、「広告キューポイントを使用した広告の表示」を参照してください。
デバッグ
このセクションの情報は、情報を収集するために提供され、HLS の問題の解決に役立つ Brightcove サポートに渡すことができます。つまり、報告されたデータのいくつかはあなたにとって興味深いものかもしれません。
HLS デバッグを支援する 2 つのメソッドと 1 つのプロパティについて詳しく説明します。
方法:videojs.log.level ()
videojs.log.level()
このメソッドは、現在のログレベルを取得または設定します。デバッグを有効にするには、次のようにします。
videojs.log.level('debug');
メソッド:videojs.log.history ()
history()
このメソッドは、履歴に記録されたすべてのものを含む配列を返します。
videojs.log
API を介してログに記録されたメッセージは、history
配列に追加されます。その配列に配置される情報は、API を使用するプラグインとプレーヤーの状態によって異なります。つまり、HLS 以外の情報を履歴に簡単に含めることができます。のコンソールからの表示例history
配列は次のとおりです。
送信する必要がある場合history
サポートするアレイの場合、コンソールで次のように入力するのが最善の方法です。
JSON.stringify(videojs.log.history())
ここに表示されているものと同様の情報が表示されます。
生成され、サポートに送信できるJSONをコピーします。
プロパティ:player.tech () .hls.stats
このオブジェクトには、HLS とプレイヤー関連の統計の概要が含まれています。次の表に、使用可能なプロパティを示します。
プロパティ名 | タイプ | 説明 |
---|---|---|
帯域幅 | 番号 | 最後のセグメントのダウンロード速度 (ビット/秒) |
緩衝 | アレイ | SourceBuffer にあるコンテンツの時間範囲のリスト |
CurrentSource | 対象 | ソースオブジェクト。構造を持つ{src: 'url', type: 'mimetype'} |
CurrentTech | ひも | 使用中の技術の名前 |
CurrentTime | 番号 | プレーヤーの現在の位置 |
継続時間 | 番号 | 動画の再生時間(秒) |
主人 | 対象 | マスタープレイリストオブジェクト |
MediaBytestRansFerred | 番号 | ダウンロードされたコンテンツの総バイト数 |
MediaReQuests | 番号 | メディアセグメント要求の総数 |
MediaRequestsAborted | 番号 | 中止されたメディアセグメント要求の総数 |
MediaRequestSerroRed | 番号 | エラーメディアセグメント要求の総数 |
MediaRequestStimeOut | 番号 | Timedout メディアセグメント要求の総数 |
MediaseCondsLoaded | 番号 | ダウンロードされたコンテンツの合計秒数 |
MediaTransFerDuration | 番号 | メディアセグメントのダウンロードにかかった合計時間(ミリ秒) |
PlayerDimensions | 対象 | プレーヤーの幅と高さが含まれています |
探せない | アレイ | プレイヤーがシークできる時間範囲のリスト |
タイムスタンプ | 番号 | hls.stats アクセスされた時刻のタイムスタンプ |
VideoPlaybackQuality | 対象 | によって指定されたメディア再生品質メトリックW3Cのメディア再生品質API |
のコンソールからの表示例stats
オブジェクトは次のとおりです。
コード例
これらのデバッグ機能を試したい場合は、以下のコードを出発点としてサーバーを使用できます。
<video-js id="myPlayerID" data-video-id="5622718636001"
data-account="1507807800001"
data-player="SkxERgnQM"
data-embed="default"
data-application-id
class="video-js"
controls
width="640"
height="360"></video-js>
<script src="https://players.brightcove.net/1507807800001/SkxERgnQM_default/index.min.js"></script>
<script type="text/javascript">
videojs.getPlayer('myPlayerID').ready(function() {
var myPlayer = this;
videojs.log.level('debug');
myPlayer.on('ended', function(){
console.log('videojs.log.history(): ', videojs.log.history());
console.log('videojs.log.level(): ', videojs.log.level());
console.log('videojs.hls.stats: ', player.tech().hls.stats);
});
});
</script>
608 キャプション
ブライトコーブの HLS プラグインは 608 キャプションをサポートしています。CEA-608キャプション、EIA-608キャプション、およびLine 21キャプションとも呼ばれる608キャプションは、米国およびカナダでのNTSCTVアナログ放送のクローズドキャプションの標準です。608 キャプションをライブストリームに挿入し、HLS ' TS (トランスポートストリーム) ファイルにミックスします。
ホスティングの問題
ネイティブの HLS 実装とは異なり、HLS プラグインはブラウザーのセキュリティポリシーに準拠する必要があります。つまり、ストリームを構成するすべてのファイルは、ビデオプレーヤーをホストしているページと同じドメインから、または適切な CORS ヘッダーが設定されているサーバーから提供する必要があります。一般的なウェブサーバーでは簡単な手順が利用可能で、ほとんどの CDN はアカウントで CORS を有効にするのに問題はありません。
エラー
HLS 再生中のエラーは、 APPEND_BUFFER_ERR 型を使用して報告されます。メッセージは、ブラウザのネイティブエラーから取得されるものになります。たとえば、クォータが超過したとします。