WebサイトにHLS動画を埋め込む方法（iframeとhls.js）

HLS（HTTP Live Streaming）は、現在ほとんどのWebサイトがオンデマンド動画に使っている形式です。巨大なMP4ファイル1つの代わりに、同じ動画の複数のバージョンを指す小さなテキストのプレイリストで動画を記述し、各バージョンは短いセグメントに分割されています。プレーヤーは数セグメント先まで読み込み、到着速度を計測しながら、その場でバージョンを切り替えます。スマートフォン回線の視聴者には軽いバージョンが、光回線の視聴者には鮮明なバージョンが届き、最初のフレームが表示される前にファイル全体のダウンロードを待つ人はいません。

このガイドでは、UFOLOADのHLS動画を自分のWebページに載せる2つの方法を紹介します。1つは約1分で済むiframeの既製プレーヤー、もう1つはhls.jsで動かす独自の <video> 要素で、ページを完全に制御できます。どちらも同じストリームを使うため、まずiframeで始めて、後から何も再アップロードせずにhls.jsに移行できます。

UFOLOADのHLSストリームの構成

ファイルをアップロードすると、コンバーターがH.264映像とAACステレオ音声で、レンディションと呼ばれる1〜4つのバージョンにエンコードします：360p、720p、1080p、2160p（4K）です。レンディションが元動画より大きくなることはないため、720pのアップロードからは720pと360pが生成され、アップスケールされた1080pが作られることはありません。実際に得られる最高のレンディションはプランにも左右されます。現在の上限は料金ページに掲載しています。段階の選び方の詳しい背景は、アダプティブビットレートのラダー解説をお読みください。

各レンディションは、インデックスをファイル先頭に置いた通常のMP4として保存されます。視聴者が再生を始めると、ストレージ層がそのMP4ファイルをその場でHLSにパッケージングします。マスタープレイリスト（master.m3u8）には各レンディションがピーク帯域、解像度、コーデックとともに記載され、各レンディションには4秒セグメントの独自のプレイリストがあります。キーフレームはセグメントの境界に揃うよう配置されており、これによってプレーヤーは動画の途中でもきれいに画質を切り替えられます。

プレイリストとセグメントは Access-Control-Allow-Origin: * ヘッダー付きでキャッシュノードから配信されるため、あなたのドメインで動くプレーヤーから直接リクエストできます。すべてのURLは署名付きで有効期限があり、これは後でhls.jsの方法を説明する際に重要になります。

ステップ1：動画をアップロードし、準備完了を待つ

ダッシュボードでファイルをドロップするか直接リンクを貼り付けてアップロードするか、FTP、WebDAV、APIを使います（curl、Python、Node.jsのサンプルはAPIでの動画アップロードを参照）。ファイルのステータスは uploading、queued、processing、ready と進みます。failed は理由とともに報告され、ダッシュボードから再試行できます。短いクリップは数分で準備が整い、長い映画はそれ以上かかります。有料プランには優先エンコードキューがあります。

ページの完成を待つ必要はありません。ファイルの処理中に誰かがプレーヤーを開くと、進行状況付きの処理中メッセージが表示され、処理が終わると自動的に動画に切り替わります。それでも、最初の訪問者がプログレスバーを見るページを公開しないよう、ページを公開する前にステータスが ready であることを確認してください。

動画の識別子が必要です。ダッシュボードでは共有パネルに表示され、APIでは11文字の短いコード public_id として返されます。このコードを埋め込みアドレスに入れます。

ステップ2：iframeでプレーヤーを埋め込む

ダッシュボードでは、アップロード直後と各動画の共有パネルでiframeのコードが提供されます。下の最初のブロックのような形です。VIDEO_ID を動画の識別子に置き換えてください。プレーヤーページ自体は検索エンジンにインデックスされません。埋め込みにとってはこれが望ましい状態で、検索順位がつくのはプレーヤーのフレームではなくあなたのページです。

<iframe width="640" height="360"
  src="https://iframe.andromedans.live/e/VIDEO_ID"
  title="My video"
  frameborder="0"
  allow="autoplay; fullscreen; picture-in-picture"
  allowfullscreen></iframe>

固定のピクセルサイズはスマートフォンで崩れます。レスポンシブなページでは、iframeを16:9の比率を保つボックスで囲み、フレームをその中いっぱいに広げます。プレーヤーはフレーム全体を埋めるため、動画はきれいに拡大縮小されます。

<div style="position:relative;aspect-ratio:16/9;max-width:960px">
  <iframe src="https://iframe.andromedans.live/e/VIDEO_ID"
    title="My video"
    style="position:absolute;inset:0;width:100%;height:100%;border:0"
    loading="lazy"
    allow="autoplay; fullscreen; picture-in-picture"
    allowfullscreen></iframe>
</div>

アドレスに追加できるパラメーター

• autoplay=1 はプレーヤーの読み込み時に再生を開始します。ほとんどの場合ブラウザーは音声付きの自動再生をブロックするため、mute=1 と組み合わせてください。
• mute=1 は動画をミュート状態で開始します。視聴者はいつでもミュートを解除できます。
• loop=1 は動画が終わると最初から再生し直します。
• t=30 は30秒の位置から再生を開始します。長い動画の特定の場面へのディープリンクに便利です。

アドレスのパラメーターは、プレーヤースタジオの同じ設定より常に優先されます。スキン、アクセントカラー、ロゴ、ボタン配置など、どこでも共通のデフォルトにはプレーヤースタジオを使い、特定のページだけ動作を変えたい場合にパラメーターを使います。埋め込み先のドメインごとに別のプレーヤープロファイルを用意することもできます。

ステップ3（任意）：hls.jsでストリームを再生する

iframeが最短の方法ですが、独自のマークアップが欲しい場合もあります。カスタムのコントロールバー、カルーセル内の動画、自分のコードからの分析イベントなどです。その場合は、プレイリストのアドレスとプレーヤーライブラリが必要です。Safari以外のブラウザーはHLSをネイティブ再生できないため、一般的な選択肢は、HLSセグメントを標準の <video> 要素に流し込むJavaScriptライブラリhls.jsです。SafariとiOSはHLSをネイティブ再生できるため不要です。

プレイリストのアドレスは、動画オブジェクトの links.playback フィールドです。APIキーはブラウザーのコードに決して含めてはならないため、サーバーからAPIキーを使って取得します。同じ呼び出しで links.expires_at も返されます。リンクは署名付きで有効期限があるため、データベースに保存するのではなく、ページを描画するたびに新しいリンクを要求してください。

const BASE = 'https://ufoload.com/api/v1'

export async function playbackUrl(fileId) {
  const res = await fetch(`${BASE}/files/${fileId}`, {
    headers: { Authorization: `Bearer ${process.env.UFOLOAD_API_KEY}` },
  })
  if (!res.ok) throw new Error(`UFOLOAD API: ${res.status}`)
  const { file, links } = await res.json()
  if (file.status !== 'ready') return null // still processing
  return links.playback // signed master.m3u8 URL
}

デフォルト以外の有効期間が必要な場合、POST /files/{id}/links は60秒〜30日の ttl を受け付け、リンクをIPアドレスやcookieに紐付けることもできます。詳しくはAPIドキュメントで解説しています。キー不要の公開エンドポイント GET /api/v1/public/files/{id} もあります。視聴ページと埋め込みページはこれを使っており、そのリンクの有効期間は6時間です。

ページ上でプレーヤーを作成します。下のブロックは、対応環境ではhls.jsを使い、Safariではネイティブ再生にフォールバックし、それ以外では簡単なメッセージを表示します。ライブラリのファイルは自分でホストするか、最新版を読み込むのではなくバージョンを固定してください。

<video id="player" controls playsinline preload="metadata"
       poster="POSTER_URL" style="width:100%;aspect-ratio:16/9;background:#000"></video>
<script src="/vendor/hls.min.js"></script>
<script>
  const video = document.getElementById('player')
  const src = 'PLAYLIST_URL_FROM_YOUR_SERVER'

  if (window.Hls && Hls.isSupported()) {
    const hls = new Hls()
    hls.loadSource(src)
    hls.attachMedia(video)
    hls.on(Hls.Events.ERROR, (_, data) => {
      if (!data.fatal) return
      if (data.type === Hls.ErrorTypes.NETWORK_ERROR) hls.startLoad()
      else if (data.type === Hls.ErrorTypes.MEDIA_ERROR) hls.recoverMediaError()
      else hls.destroy()
    })
  } else if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = src // Safari, iOS
  } else {
    video.outerHTML = '<p>This browser cannot play HLS video.</p>'
  }
</script>

動画オブジェクトには、カバー画像用の links.poster と、ホバープレビューのサムネイル用の links.sprite も含まれており、独自のシークバーを作る際に使えます。hls.jsを使うと、UFOLOADプレーヤーが代わりに提供している機能は失われます：画質メニュー、チャプター、字幕選択、ロゴのオーバーレイ、そして広告が利用可能な場合は広告です。これが実際のトレードオフで、下の表にまとめています。

iframeとhls.js：どちらを使うべきか

トラブルシューティング・チェックリスト

• 黒い画面や終わらないローディング表示。 ブラウザーのネットワークパネルを開き、master.m3u8 を探します。403はリンクの期限切れか、視聴者が国やIPのルールでブロックされていることを意味します。新しいリンクを要求してください。
• HTTPSページでブラウザーにブロックされる。 すべてHTTPSである必要があります。iframeやhls.jsに http:// のアドレスを貼り付けないでください。
• 自動再生されない。 音声付きの自動再生はブラウザーにブロックされます。mute=1 を追加するか、hls.jsでは play() を呼ぶ前に video.muted = true を設定します。
• 動画の代わりに処理中メッセージが出る。 ファイルの準備がまだ整っていません。status が ready になるまで GET /files/{id} をポーリングします。
• 低画質しか再生されない。 プレーヤーは控えめに再生を始め、スループットを計測するとすぐに画質を上げます。プランと元動画によっても最高レンディションが制限されます。料金と機能ページで確認してください。

ページが動作したら、直リンクから保護したり、広告が利用可能なら収益を得たりしたくなるかもしれません。どちらも次のガイドで解説しています：動画を埋め込める場所を制限するとプレーヤー内広告で動画サイトを収益化するです。ホスティング先をまだ検討中なら、動画ホスティングのチェックリストに比較すべき点をまとめています。