本文へ移動
React開発ガイド

Reactでhls.jsを実装する入門ガイド

Reactでhls.jsを使った安定した動画プレーヤーを作るには、コンポーネントのライフサイクル、参照、イベントリスナーを適切に管理する必要があります。HLSストリームをReactアプリに安全かつ効率よく組み込む手順を説明します。

HTTP Live Streaming(HLS)は、インターネット経由の映像配信で広く使われています。ただし、すべてのブラウザーがHLSを標準で再生できるわけではありません。Safariは.m3u8をそのまま扱えますが、Chrome、Firefox、Edgeではhls.jsなどのJavaScriptライブラリでマニフェストを解析し、Media Source Extensions(MSE)経由で映像セグメントを渡します。

Reactコンポーネントはマウント、アンマウント、再描画されますが、hls.jsは継続的なインスタンスとDOMへの直接操作を使います。この違いを踏まえ、メモリリークを防ぎながらM3U8を再生するReactコンポーネントを作ります。

標準のvideo要素だけでなくhls.jsを使う理由

HTML5の<video src="stream.m3u8">にM3U8のURLを指定するだけでは、多くのデスクトップブラウザーで再生できません。hls.jsはHLSマニフェストを読み、`.ts`や`.m4s`のセグメントを取得してvideo要素へ渡します。

手順1:インストール

まずReactプロジェクトにhls.jsパッケージをインストールします。

npm install hls.js
# or
yarn add hls.js

手順2:HlsPlayerコンポーネントを作る

Reactでhls.jsを使うには、フックで次の二つを管理します。

  • useRefで実際の<video> DOMノードへの参照を保持します。
  • useEffectでコンポーネントのライフサイクルに合わせてHlsインスタンスを初期化、接続、破棄します。

以下はHLSプレーヤーコンポーネントの基本的な実装です。

import React, { useEffect, useRef } from 'react';
import Hls from 'hls.js';

const HlsPlayer = ({ src, autoPlay = true, controls = true }) => {
  const videoRef = useRef(null);

  useEffect(() => {
    let hls;
    const video = videoRef.current;

    if (video) {
      // 1. Check if the browser supports hls.js (Media Source Extensions)
      if (Hls.isSupported()) {
        hls = new Hls({
          // You can pass configuration options here
          maxBufferLength: 30,
          maxMaxBufferLength: 600,
        });
        
        // Bind the HLS instance to the video element
        hls.attachMedia(video);
        
        // Listen for the MEDIA_ATTACHED event to load the source
        hls.on(Hls.Events.MEDIA_ATTACHED, () => {
          hls.loadSource(src);
        });

        // Listen for the MANIFEST_PARSED event to optionally auto-play
        hls.on(Hls.Events.MANIFEST_PARSED, () => {
          if (autoPlay) {
            video.play().catch(e => console.warn("Autoplay prevented:", e));
          }
        });
      }
      // 2. Fallback for browsers with native HLS support (like Safari)
      else if (video.canPlayType('application/vnd.apple.mpegurl')) {
        video.src = src;
        video.addEventListener('loadedmetadata', () => {
          if (autoPlay) {
            video.play().catch(e => console.warn("Autoplay prevented:", e));
          }
        });
      }
    }

    // 3. Cleanup: destroy the hls instance on unmount to prevent memory leaks
    return () => {
      if (hls) {
        hls.destroy();
      }
    };
  }, [src, autoPlay]); // Re-run effect if the source URL changes

  return (
    <div className="hls-player-wrapper">
      <video 
        ref={videoRef} 
        controls={controls} 
        style={{ width: '100%', height: 'auto' }} 
      />
    </div>
  );
};

export default HlsPlayer;

クリーンアップ関数の役割

return () => { hls.destroy(); }は重要です。省略すると、コンポーネントが再描画されたり別ページへ移動したりした後もHLSインスタンスが残り、裏でセグメントを取得してメモリを消費し続けます。最終的にブラウザーのタブが停止するおそれがあります。

手順3:エラーに対応する

実際の配信では、通信が切れたりM3U8のトークンが期限切れになって403 Forbiddenが返ったりします。プレーヤーが何も表示せず停止しないよう、hls.jsインスタンスにエラーリスナーを登録します。

// Add this inside the Hls.isSupported() block
hls.on(Hls.Events.ERROR, (event, data) => {
  if (data.fatal) {
    switch (data.type) {
      case Hls.ErrorTypes.NETWORK_ERROR:
        console.error("Fatal network error encountered, trying to recover...");
        hls.startLoad();
        break;
      case Hls.ErrorTypes.MEDIA_ERROR:
        console.error("Fatal media error encountered, trying to recover...");
        hls.recoverMediaError();
        break;
      default:
        // Cannot recover
        console.error("Unrecoverable error, destroying hls instance");
        hls.destroy();
        break;
    }
  }
});
NETWORK_ERRORとMEDIA_ERRORを処理すれば、短いWi-Fiの切断や軽微なマニフェストの問題から、ページの再読み込みなしで復旧できる場合があります。

手順4:再生元を動的に切り替える

ライブテレビアプリなどでストリームを切り替える場合、useEffectの依存配列に[src]があるため、URLの変更時に処理が再実行されます。先にクリーンアップ関数が古いHLSインスタンスを破棄し、新しいインスタンスが新しいURLをvideo要素に接続します。

この宣言的な方法で、アプリの状態とプレーヤーの状態を同期できます。

応用:画質選択を追加する

HLSはアダプティブビットレート(ABR)を使い、hls.jsが回線速度に応じて画質を自動調整します。1080pへの固定など、手動選択が必要な場合はhls.levelsで利用可能な画質を読み、hls.currentLevelで指定します。

hls.on(Hls.Events.MANIFEST_PARSED, (event, data) => {
  const availableQualities = data.levels.map(level => level.height);
  console.log("Available resolutions:", availableQualities);
  
  // To force the highest quality:
  // hls.currentLevel = data.levels.length - 1;
});

画質選択UIを作るには、data.levelsをReactのuseState配列に保存して選択メニューを表示し、解像度が選ばれたらhls.currentLevelを更新します。hlsインスタンスにuseEffectの外のボタンからアクセスするなら、不要な再描画を避けるためuseRef(null)に保持します。

まとめ

Reactでhls.jsを実装する鍵は、コンポーネントのライフサイクルを理解することです。hls.jsの命令的なAPIをuseEffect内で扱い、useRefでvideo要素を参照し、終了時にhls.destroy()で確実に後片付けすれば、安定して動くHLSプレーヤーを作れます。