HLS プレイリストは UTF-8 でエンコードされたテキストドキュメントです。#EXT で始まる行はタグ、URI 行は別のプレイリストやメディアリソースの場所を示し、それ以外の # で始まる行はコメントです。タグ名は、後続の属性がどのスコープおよび対象リソースを修飾しているかを示します。ファイル内を単一のキーワードで検索するよりも、この構造的な関連性を正しく読み取ることがトラブル解決への近道です。
本ガイドでは、RFC 8216（HTTP Live Streaming） で定義されている代表的なディレクティブを整理して解説します。標準仕様としての正式な定義は RFC に基づきます。各プレーヤーの実装や拡張仕様によって追加機能が提供される場合もあるため、特殊なプレイリストを扱う際は、実際にサポート対象とするプレーヤーや配信プラットフォームの要件に照らし合わせて検証してください。
まずプレイリストの種類を特定する
マスタープレイリストは、利用可能なバリアント（画質別ストリーム）や追加レンディションを定義します。通常、#EXT-X-STREAM-INF とそれに続く子プレイリストの URI が記述され、必要に応じて代替音声、字幕、別アングルの映像を指定する #EXT-X-MEDIA が含まれます。一方、メディアプレイリストは実際のメディアセグメントの連続した並びを記述し、通常は #EXTINF、セグメントの URI、時間やシーケンスに関するディレクティブを含みます。
マスタープレイリスト専用のタグと、メディアプレイリスト専用のタグを混同してはいけません。デバッグ時には、開いている URL がマスターなのか選択された子プレイリストなのかを最初に確認してください。プレーヤーがマスターの解析には成功しても、子メディアプレイリスト、セグメント、初期化セクション、字幕、暗号化キーの段階で失敗することが多々あります。
両方のプレイリストで共通して使われる基本タグ
| タグ | 目的 | 診断時の着眼点 |
|---|---|---|
#EXTM3U | 拡張 M3U プレイリストであることを示し、ファイルの先頭行に必須です。 | サーバーエラーやログインリダイレクトにより、プレイリストではなく HTML が返されていませんか？ |
#EXT-X-VERSION | 使用している機能に必要なプレイリストの互換バージョンを示します。 | 宣言されたバージョンは、実際に使われている構文や属性を正しくカバーしていますか？ |
#EXT-X-INDEPENDENT-SEGMENTS | 仕様の範囲内で、各セグメントのサンプルが他のセグメントの情報なしで単独デコード可能であることを示します。 | 実際のメディアパッケージングはこの宣言と矛盾していませんか？ |
#EXT-X-START | タイムオフセットを用いて、推奨される再生開始位置を指定します。 | 指定されたオフセットは、現在のライブウィンドウや VOD の総時間に対して適切ですか？ |
#EXT-X-VERSION は単なるエンコーダーのバージョン表示ではありません。プレイリスト内で使用されている構文機能が求めるクライアント側の対応バージョンを伝達します。古いクライアントを除外してしまう可能性があるため、理由なくバージョンを上げすぎないこと、また構文が要求する値よりも低い値を宣言しないことが重要です。
マスタープレイリストの主要タグ
#EXT-X-STREAM-INF
このタグはバリアントストリーム（特定品質の映像・音声）を記述します。必須属性である BANDWIDTH は、RFC の定義に基づくそのバリアントのピークセグメントビットレートを指定します。よく使われるオプション属性には、AVERAGE-BANDWIDTH、CODECS、RESOLUTION、FRAME-RATE、および AUDIO や SUBTITLES などのグループ参照があります。直後の行の URI が、そのバリアントのメディアプレイリストの場所を示します。
特定の画質のみ再生に失敗する場合は、直後の URI を直接開いて確認してください。宣言されているコーデックが実際のセグメントと一致しているか、相対パスがマスター URL から正しく解決されるか、参照先の音声・字幕グループが存在するかを検証します。BANDWIDTH の値はアダプティブ再生の選択アルゴリズムを正しく機能させるためのものであり、視聴者に推奨される通信速度そのものではありません。
#EXT-X-MEDIA
代替レンディション（多言語音声、字幕、別視点映像など）を宣言するタグです。TYPE で AUDIO、VIDEO、SUBTITLES、CLOSED-CAPTIONS の別を指定し、GROUP-ID でバリアントと関連付け、NAME で人間が読める表示名を定義します。タイプに応じて、LANGUAGE、DEFAULT、AUTOSELECT、FORCED、CHARACTERISTICS、URI などの属性が選択動作を決定します。
グループ参照の整合性は厳密でなければなりません。バリアント行に AUDIO="stereo" とある場合、対応する GROUP-ID を持つメディアグループが必ず存在しなければなりません。同一グループ内での名前の重複、アクセス不能な URI、または RFC の制約を満たさないデフォルト指定などは、トラック選択の不具合の原因となります。
その他のマスターディレクティブ
#EXT-X-I-FRAME-STREAM-INF：Iフレーム専用バリアント（早送り・巻き戻しプレビュー用）を記述し、URI は次の行ではなく属性として記述されます。#EXT-X-SESSION-DATA：マスタープレイリスト全体に適用されるセッションデータを保持します。公開プレイリスト内に秘密情報を記述しないでください。#EXT-X-SESSION-KEY：指定された暗号化方式とフォーマットに従い、バリアントで使用される暗号化キーをクライアントが事前に読み込むことを可能にします。
メディアセグメントとタイミングに関するタグ
#EXTINF
#EXTINF は、直後の URI で示されるメディアセグメントの継続時間（秒単位）を指定します。カンマの後のテキストは任意のタイトルです。メディアプレイリスト内のすべてのセグメントにこのタグが必要です。指定時間が不正確だと、ファイル自体が正常に読み込めても、タイムラインのズレ、シークの失敗、ライブエッジ判定の誤り、バッファ計算の破綻につながります。
#EXT-X-TARGETDURATION
このタグは、RFC の四捨五入ルールに基づく最大のセグメント継続時間を秒単位で定義し、メディアプレイリスト内で1度だけ記述されます。クライアントはこの値を参考に、ライブプレイリストを再取得する周期を決定します。セグメントの実時間がターゲット継続時間を超過している場合はパッケージングエラーとなり、逆に過大に設定されているとライブの更新反映が遅れる原因となります。
#EXT-X-MEDIA-SEQUENCE
現在プレイリスト内に最初にリストされているセグメントのシーケンス番号（連番）を示します。必ずしも 0 から始まる必要はありません。スライド式のライブ配信では、古いセグメントがリストから削除されるにつれてこの値が順次加算されます。CDN が古いキャッシュを誤った順序で返すと、クライアントはすでに削除されたセグメントをリクエストしたり、ライブの最前線を見失って停止します。
#EXT-X-DISCONTINUITY
エンコード設定、タイムスタンプの連続性、その他のメディア特性が変化する境界を示します。代表的な例として、広告の挿入、配信元の切り替え、タイムスタンプのリセットなどがあります。変化が発生する正確な境界位置に配置してください。このタグが欠落しているとデコードやタイミング同期が破綻し、逆に不要な場所に配置すると無駄なバッファリセットが発生します。
#EXT-X-DISCONTINUITY-SEQUENCE は、プレイリストの更新や異なるレンディション間で不連続シーケンス番号を揃えるためのタグです。最初のメディアセグメントの前に配置し、ライブウィンドウのスライドに合わせて整合性を保つ必要があります。
リソースの取得方法を変更するタグ
#EXT-X-BYTERANGE
直後の URI で指定された単一の大きなファイル内から、特定のバイト範囲（オフセットと長さ）をメディアセグメントとして取得するよう指示します。オフセットが省略された場合、仕様で定義された条件に従い直前のサブ範囲からの相対位置として解釈されます。配信元サーバーと CDN は Range リクエストを正常に処理できなければならず、キャッシュが誤ったバイト範囲を返さないようにする必要があります。
#EXT-X-MAP
後続のセグメントをパースするために必要なメディア初期化セクション（主に fragmented MP4 の moov ボックスなど）を指定します。URI 属性のほか、BYTERANGE を伴うこともあります。プレイリストとメディアセグメントの通信が成功していても、この初期化リソースが欠落していたり、ブロックされていたり、古いものがキャッシュされていると、再生は完全に失敗します。
#EXT-X-KEY
後続のメディアセグメントがどのように暗号化されているかを指定します。METHOD 属性のほか、方式に応じてキーの URI、初期化ベクトル（IV）、キーフォーマットなどが指定されます。この設定は、別のキーディレクティブによって変更されるまで後続のセグメントに適用され続けます。METHOD=NONE は暗号化されていない状態を示します。
キー取得のリクエストをデバッグする際は、秘密キー情報を公開しないよう注意してください。HTTP ステータス、認証ヘッダー、トークンの有効期限、ホスト名、およびブラウザでキーを取得する際の CORS 挙動を確認します。DRM ライセンスの処理フローは、単純な AES-128 キー取得とは全く異なる点に注意してください。
プレイリストのライフサイクルタグ
#EXT-X-ENDLIST
これ以上メディアセグメントが追加されないことを示す終了マーカーです。完成したオンデマンド配信（VOD）プレイリストには必須であり、ライブ配信イベントが終了した際にも付与されます。このタグがないライブプレイリストは継続的に更新されます。未終了の配信に誤って付与すると再生が途中で停止し、完了した VOD から省略するとクライアントが無駄にポーリングを継続してしまいます。
#EXT-X-PLAYLIST-TYPE
プレイリストの変更可能性（ミュータビリティ）を制限するタグで、値として EVENT または VOD を取ります。EVENT プレイリストは過去のセグメントを保持したまま末尾に新しいセグメントを追加できます。VOD プレイリストは内容が一切変更されません。古いセグメントが順次消去されるスライディング型のライブ配信では、通常このタグは省略されます。
#EXT-X-PROGRAM-DATE-TIME
直後のメディアセグメントの最初のサンプルを、絶対的な日時（ISO 8601 形式）と紐付けます。複数ストリームの同期、番組表（EPG）との連携、サーバーログの突合、タイムドメタデータの同期に役立ちます。日時の値があいまいだったり単調増加していないと障害発生時の時系列の再現が困難になるため、タイムゾーンを含めて正確なタイムスタンプを出力してください。
注釈付きマスターおよびメディアの記述例
以下のシンプルなマスタープレイリストは、2つの解像度バリアントを1つの代替音声グループに関連付けています：
#EXTM3U
#EXT-X-VERSION:6
#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio",NAME="English",DEFAULT=YES,AUTOSELECT=YES,URI="audio/en.m3u8"
#EXT-X-STREAM-INF:BANDWIDTH=1800000,AVERAGE-BANDWIDTH=1500000,RESOLUTION=1280x720,CODECS="avc1.4d401f,mp4a.40.2",AUDIO="audio"
video/720p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=850000,AVERAGE-BANDWIDTH=700000,RESOLUTION=854x480,CODECS="avc1.4d401e,mp4a.40.2",AUDIO="audio"
video/480p.m3u8次のオンデマンド（VOD）メディアプレイリストは、初期化マップ（fMP4）と3つのセグメントを使用しています。セグメントの継続時間はターゲット期間の規則を満たしており、終了マーカーによってリストの完了を示しています：
#EXTM3U
#EXT-X-VERSION:7
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-MAP:URI="init.mp4"
#EXTINF:6.000,
segment-000.m4s
#EXTINF:6.000,
segment-001.m4s
#EXTINF:4.500,
segment-002.m4s
#EXT-X-ENDLISTこれらの例はタグ同士の関連性を示すものです。必要なバージョン番号、コーデック文字列、セグメント継続時間、パッケージング方式は、生成するメディアと対象クライアントの要件に合致していなければなりません。
不具合のあるプレイリストを診断する順序
- レスポンス本文が HTML のエラー画面ではなく、
#EXTM3Uで始まる UTF-8 テキストであることを確認する。 - マスタープレイリストかメディアプレイリストかを識別し、種別ごとの専用タグが混在していないか確認する。
- 記述されている各相対 URI が、その親プレイリストの URL を基準にして正しく解決されるかを計算する。
- マスターの場合は、各バリアントおよびレンディションのグループ参照、コーデック宣言、子 URI の到達性を検証する。
- メディアの場合は、ターゲット継続時間、セグメント実時間、シーケンス番号の連続性、不連続性、初期化マップ、キー、終了タグを確認する。
- 最初に失敗した子リソースを直接リクエストし、ステータス、本文、MIME タイプ、CORS ヘッダー、キャッシュ有効期間、認証を確認する。
- マニフェストの記述内容と実際のメディアバイナリを比較し、タグの外見だけでなく中身が有効であるかを検証する。
マニフェストでよくある記述ミス
- マスタープレイリスト内の相対パスが、配信者が意図したディレクトリ構造と異なっている。
- バリアントで宣言された CODECS 文字列が、実際の映像や音声のエンコード仕様と合致していない。
- 代替レンディショングループが参照されているのに、定義が存在しない、重複している、または到達できない。
- ライブ配信のターゲット継続時間（TARGETDURATION）よりも長い継続時間のセグメントが含まれている。
- メディアシーケンス番号が進んでいるのに、古いプレイリストのキャッシュが CDN に長く残りすぎている。
- fragmented MP4（fMP4）配信において、初期化マップ（#EXT-X-MAP）の記述が抜けているかアクセスできない。
- 暗号化キー URL の有効期限が、プレイリストやセグメントの URL よりも早く切れてしまう。
- 広告挿入やソース切り替え時に、必要な不連続タグ（#EXT-X-DISCONTINUITY）を置かずにタイムスタンプやコーデックが変わっている。
- VOD プレイリストなのに末尾に #EXT-X-ENDLIST がないため、クライアントが終了と判定できず通信を繰り返す。
当サイトの M3U8 マニフェスト検査ツール を使用すると、プレイリストの種別、バリアント、コーデック、ホスト名、暗号化キー、警告シグナルを自動で解析できます。本リファレンスとあわせて活用し、確認後は 無料 M3U8 オンラインプレーヤー で実際の再生テストを行ってください。