本文へスキップ
開発者向けガイド

Video.jsでHLS再生を設定する完全ガイド

Video.jsはオープンソースのHTML5動画プレーヤーです。さまざまなブラウザーでHLSを再生するには、ネイティブ再生とHTTP Streamingプラグイン(VHS)の設定を理解する必要があります。このガイドでは、安定したM3U8再生の設定を解説します。

HLSのネイティブ対応はブラウザーによって異なります。macOSとiOSのSafariはOSのメディア機能でM3U8を処理しますが、Chrome、Firefox、Edgeでは通常、Media Source Extensions(MSE)とJavaScriptによる解析が必要です。

Video.jsを適切に設定すれば、この違いを吸収できます。以前はvideojs-contrib-hlsが必要でしたが、現在はvideojs-http-streaming(VHS)が標準で組み込まれています。基本設定から高度な設定、デバッグまで説明します。

Video.jsとVHSの基本構成

Video.jsにM3U8 URLを渡したときの処理は次のとおりです。

  • まずブラウザーが`application/x-mpegURL` MIMEタイプに標準対応しているか確認します。
  • Safariなどでネイティブ対応があれば、HTML5の<video>要素に再生を任せます。
  • 対応していなければVHSがXHR/Fetchでマスタープレイリストを取得・解析し、帯域に合う画質を選び、TSまたはfMP4セグメントをMSEバッファーに渡します。

基本設定:初期化と動画ソース

まずVideo.jsのCSSとJavaScriptを読み込みます。CDNを使えば手早く導入できます。VHSが標準で含まれる安定版(例:v8.x)を選んでください。

<!-- Include Video.js stylesheet -->
<link href="https://vjs.zencdn.net/8.3.0/video-js.css" rel="stylesheet" />

<!-- The HTML5 Video Element -->
<video-js id="my-video" class="video-js vjs-default-skin" controls preload="auto" width="854" height="480">
    <source src="https://example.com/live/master.m3u8" type="application/x-mpegURL">
</video-js>

<!-- Include Video.js script -->
<script src="https://vjs.zencdn.net/8.3.0/video.min.js"></script>
<script>
    var player = videojs('my-video', {
        fluid: true,
        playbackRates: [0.5, 1, 1.5, 2]
    });
</script>

VHSの高度な設定

ネイティブ再生の切り替えや認証付きセグメントの処理などでは、VHSのオプションを直接設定します。

ネイティブHLS再生の切り替え

SafariのネイティブHLSは省電力ですが、ID3タグの取得や画質の手動選択などで必要な機能が使えない場合があります。次の設定でSafariにVHSの使用を指定できます。

var player = videojs('my-video', {
    html5: {
        vhs: {
            overrideNative: true
        },
        nativeAudioTracks: false,
        nativeVideoTracks: false
    }
});

overrideNativeの注意点

ネイティブ再生を切り替えるとAPIを統一できますが、iPhoneのiOS SafariではMSEが制限され、overrideNativeが無視される場合があります。一方、iPadOSのiPadではMSEを利用できます。

認証情報とCORSの扱い

HLSでCookieや独自ヘッダーによる認証が必要なら、VHSのXHRリクエストに認証情報を含めます。別オリジンへのリクエストでは、サーバー側でも該当ヘッダーをCORSで許可してください。

var player = videojs('my-video', {
    html5: {
        vhs: {
            withCredentials: true
        }
    }
});

// For custom headers, intercept the XHR request:
videojs.Vhs.xhr.beforeRequest = function(options) {
    options.headers = options.headers || {};
    options.headers['Authorization'] = 'Bearer YOUR_TOKEN';
    return options;
};

画質の手動選択(ABR)

Video.jsは標準で適応ビットレート(ABR)により画質を自動選択します。1080pや720pを利用者が選ぶUIを設けるには、videojs-hls-quality-selectorなどの追加プラグインが必要です。

VHS APIで手動制御する場合は、representations()を使います。

player.on('loadedmetadata', function() {
    var representations = player.tech().vhs.representations();
    
    // Disable automatic ABR and force the highest quality rendition
    representations.forEach(function(rep) {
        rep.enabled(false);
    });
    
    var highestBitrateRep = representations.sort((a,b) => b.bandwidth - a.bandwidth)[0];
    highestBitrateRep.enabled(true);
});
注意:画質を手動で固定するとABRが停止します。回線が遅くなっても自動で低ビットレートへ切り替わらず、再生が止まる場合があります。

Video.jsのHLS再生エラーの対処

Video.jsでM3U8を再生できない場合、CORS、MIMEタイプ、プレイリストの内容を確認します。

  • CORSヘッダー:CDNまたは配信元がAccess-Control-Allow-Origin: *(または対象ドメイン)を返すようにします。ない場合はVHSによるプレイリストとセグメントの取得がブロックされます。
  • MIMEタイプ:.m3u8にはapplication/x-mpegURLまたはapplication/vnd.apple.mpegurl、.tsにはvideo/MP2Tを設定します。
  • 混在コンテンツ(HTTP/HTTPS):ページがHTTPSでもM3U8やセグメントのURLがHTTPだと、ブラウザーがリクエストをブロックします。相対パスを使うか、絶対URLをすべてHTTPSにします。
  • コーデックの不一致:音だけ出て映像が黒い場合は、マスターのCODECSを確認します。hvc1(HEVC)のみだとChromeの環境によって再生できません。avc1(H.264)の代替ストリームを用意します。

イベントによる再生状態の監視

運用時にはイベントリスナーで再生状態を監視できます。Video.jsがHLS再生中に発火するイベントを、監視用バックエンドに記録できます。

player.on('waiting', function() {
    console.warn('Player is buffering...');
});

player.on('error', function() {
    var error = player.error();
    console.error('Video.js Error Code:', error.code, error.message);
});

// VHS specific events
player.tech().on('usage', function(e) {
    if (e.name === 'vhs-rendition-change') {
        console.log('Switched to new rendition:', player.tech().vhs.playlists.media().attributes.RESOLUTION);
    }
});

まとめ

Video.jsのVHSを使い、必要に応じてネイティブ再生を切り替え、CORSとABRを適切に設定すれば、端末をまたいだM3U8再生を実現できます。複数のブラウザーで動作を確認し、Chrome DevToolsの通信速度制限でABRの切り替えもテストしてください。