本文へスキップ
高度なHLS

M3U8ストリームに多言語WebVTT字幕を追加する方法

HTTP Live Streaming(HLS)に多言語WebVTT字幕を組み込むための技術ガイドです。#EXT-X-MEDIAの設定、セグメント分割、各種プレーヤーで字幕を正しく表示するための調査方法を説明します。

高品質で同期の取れた字幕は、動画配信に欠かせません。HLSでは字幕とクローズドキャプションの標準形式としてWebVTT(Web Video Text Tracks)を使用します。単一の字幕ファイルとは異なり、HLSでは通常、字幕を分割してマスタープレイリストから参照します。

このガイドでは、M3U8による多言語WebVTT配信の構成、マスタープレイリストの設定、VTTの分割、同期や表示の問題への対処を説明します。

HLSにおけるWebVTTの仕組み

HLSストリームに字幕を追加するときは、動画タグへ単一の`.vtt`ファイルを指定するだけではありません。HLSは字幕を独立したメディアトラックとして扱います。必要な字幕だけを取得できるため、帯域を節約しながら言語を滑らかに切り替えられます。

一般的な多言語配信は、次の要素で構成されます。

  • マスタープレイリスト(`master.m3u8`): #EXT-X-MEDIAタグで字幕トラックを宣言し、SUBTITLES属性を#EXT-X-STREAM-INFに指定して動画の各バリアントに関連付けます。
  • 字幕プレイリスト(例:`subs_en.m3u8`): 分割されたWebVTTファイルをタイムスタンプと`#EXTINF`の長さ指定とともに列挙するメディアプレイリストです。
  • 分割されたWebVTTファイル(`.vtt`): 字幕の本文を含むファイルで、通常は動画セグメントの長さに合わせて分割します。

マスタープレイリストの設定

多言語字幕配信の中心となるのはマスタープレイリストです。#EXT-X-MEDIAタグは音声や字幕などの代替メディアを定義します。英語とスペイン語の字幕を指定する例を見てみましょう。

#EXTM3U
#EXT-X-VERSION:4

# Subtitle Definitions
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",DEFAULT=YES,AUTOSELECT=YES,FORCED=NO,LANGUAGE="en",URI="subs/en/prog_index.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="Spanish",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="es",URI="subs/es/prog_index.m3u8"

# Video Variants
#EXT-X-STREAM-INF:BANDWIDTH=1500000,RESOLUTION=854x480,SUBTITLES="subs"
video/480p/prog_index.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=3000000,RESOLUTION=1280x720,SUBTITLES="subs"
video/720p/prog_index.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=6000000,RESOLUTION=1920x1080,SUBTITLES="subs"
video/1080p/prog_index.m3u8

#EXT-X-MEDIAの属性を読み解く

  • TYPE=SUBTITLES: このメディアが字幕トラックであることを示します。
  • GROUP-ID="subs": 字幕と動画バリアントを結ぶ一意の識別子です。SUBTITLES="subs"属性を指定する#EXT-X-STREAM-INFタグと完全に一致する必要があります。
  • DEFAULT=YES/NO: ユーザーが選択していない場合に既定で表示するかを示します。グループ内でDEFAULT=YESにできるのは1トラックだけです。
  • AUTOSELECT=YES: システムの言語設定に基づいてプレーヤーが自動選択できるようにします。
  • LANGUAGE="en": RFC 5646の言語タグを使用します。ネイティブプレーヤーの言語メニューに重要です。

強制表示字幕

FORCED=YESは、主音声に含まれる外国語のせりふなど、理解に必要な翻訳を示します(例:英語中心の映画に登場するエルフ語)。通常の字幕をオフにしていても自動的に表示されます。

字幕プレイリストの作成

字幕プレイリストは動画のメディアプレイリストによく似ており、WebVTTセグメントを順番に列挙します。

#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-VERSION:4
#EXT-X-MEDIA-SEQUENCE:1
#EXT-X-PLAYLIST-TYPE:VOD

#EXTINF:6.000,
seq_1.vtt
#EXTINF:6.000,
seq_2.vtt
#EXTINF:6.000,
seq_3.vtt
#EXT-X-ENDLIST

字幕セグメントの境界は動画と合わせることを強く勧めます(動画が6秒なら字幕も6秒)。HLS仕様上は必須ではありませんが、ずれるとSafariのネイティブ再生や古いhls.jsなどで停止や解析エラーが起きることがあります。

WebVTTの分割ルール

WebVTTセグメントはテキストファイルを単純に切り分けたものではありません。各セグメントが単独で有効なWebVTTファイルである必要があります。

WEBVTT
X-TIMESTAMP-MAP=MPEGTS:900000,LOCAL:00:00:00.000

00:00:01.500 --> 00:00:03.200
Hello, and welcome to our stream.

00:00:04.000 --> 00:00:05.500
This is an example of WebVTT.

重要なX-TIMESTAMP-MAP

X-TIMESTAMP-MAPヘッダーはVTTファイルを動画と同期させるために不可欠です。WebVTT内の時刻をMPEG-TSの表示タイムスタンプ(PTS)に対応付けます。

字幕がずれる、時間とともにずれが大きくなる、または表示されない場合は、まずX-TIMESTAMP-MAPを確認してください。MPEGTSの値が動画セグメントの最初のフレームのPTSと正確に対応している必要があります。

字幕配信のトラブルシューティング

HLS字幕配信では特殊なケースにも対応が必要です。よくある問題と解決方法を紹介します。

  • プレーヤーのメニューに字幕が表示されない: GROUP-IDが#EXT-X-MEDIAタグに正しく指定され、SUBTITLES属性が#EXT-X-STREAM-INFタグで一致するか確認します。誤記があると字幕と動画が関連付けられません。
  • 字幕は表示されるが同期しない: X-TIMESTAMP-MAPを確認します。TSではなく断片化MP4(fMP4)を使う場合、同期にISO Base Media File FormatのbaseMediaDecodeTimeが使われることもあります。
  • 字幕読み込み時のCORSエラー: JavaScriptプレーヤーはXHR/FetchでWebVTTファイルを読み込むため、CORSの対象になります。CDNまたはオリジンサーバーが`.vtt`ファイルにAccess-Control-Allow-Origin: *ヘッダーを返すことを確認してください。詳しくはCORSガイドを参照してください。
  • 字幕キューの重複: キューがあるセグメントで始まり次のセグメントで終わる場合、表示エラーを避けるため分割ツールが適切に複製または切り分ける必要があります。Shaka Packager、FFmpeg、Bento4などを使用してください。

FFmpegで字幕を生成する

自動処理では、単一の字幕ファイルから分割WebVTTを生成する標準的なツールとしてFFmpegが使われます。

ffmpeg -i input.mp4 -i input.vtt \
  -c:v copy -c:a copy -c:s webvtt \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_segment_filename "output_%03d.vtt" \
  master.m3u8

このコマンドは動画と字幕の入力を6秒のセグメントに分割し、プレイリストと必要なタイムスタンプ対応を自動生成します。