メインコンテンツへスキップ
HLS技術

PythonでM3U8プレイリストをプログラムから解析・編集する方法

独自のVOD処理パイプラインの構築、大規模な動画ライブラリの新しいCDNへの移行、HTTP Live Streaming(HLS)のエラー調査の自動化には、M3U8ファイルをプログラムから扱う技術が欠かせません。このガイドでは、Pythonを使ってHLSマニフェストを確実に解析・検証し、動的に編集する方法を説明します。

M3U8ファイルは、IETF RFC 8216で定義されたテキスト形式のマニフェストです。正規表現や文字列操作でも解析はできますが、不連続シーケンス、fMP4の初期化データ、複雑なDRMタグ、入れ子のメディアグループなどには対応しきれません。本番環境で安定して動くコードには専用の解析ライブラリが適しています。Pythonでは m3u8 パッケージが広く使われています。

Pythonのm3u8ライブラリの導入と使い方

この m3u8 パッケージはHLSマニフェスト専用の、保守の行き届いたライブラリです。複数の配信品質を示すマスタープレイリストと、実際のセグメントを含むメディアプレイリストを区別して扱えます。

まずpipでインストールします。

pip install m3u8

URIまたは文字列からマニフェストを読み込めます。URIから読む場合、HTTPリクエストは自動で処理されます。ただし本番環境では、タイムアウトやセッションを細かく管理できる requests や httpx で取得する方法もあります。

マスタープレイリストとバリアントストリームの解析

マスタープレイリストはアダプティブビットレート配信(ABR)を制御し、帯域幅や画面サイズに応じた各画質のバリアントをプレーヤーに示します。解析して動画の各配信版を取り出してみましょう。

import m3u8

# Load a master playlist from a URL
playlist_url = 'https://example.com/master.m3u8'
manifest = m3u8.load(playlist_url)

if manifest.is_variant:
    print(f"Loaded Master Playlist with {len(manifest.playlists)} variants.")
    for variant in manifest.playlists:
        print(f"Bandwidth: {variant.stream_info.bandwidth} bps")
        print(f"Resolution: {variant.stream_info.resolution}")
        print(f"Codec: {variant.stream_info.codecs}")
        print(f"Media URI: {variant.uri}")
        print("---")
else:
    print("This is a media playlist, not a master playlist.")

ヒント:絶対URIと相対URI

マニフェスト内のメディアURIは相対パスの場合があります。 m3u8 ライブラリでURLから読み込むと、 absolute_uri プロパティが自動で設定されるため、 urllib.parse.urljoinを使って手動でパスを結合する必要はありません。

メディアプレイリストとセグメント時間の分析

実際の動画セグメントの分析、総再生時間の計算、セグメント長のばらつきによる再生問題の検出には、メディアプレイリストを扱います。

次のスクリプトはVOD(オンデマンド動画)の総再生時間を計算し、セグメント長の大きなばらつきを調べます。ばらつきは古いスマートテレビや仕様に厳格なWebプレーヤーで深刻なバッファリングを招くことがあります。

import m3u8
import statistics

media_manifest = m3u8.load('https://example.com/720p_media.m3u8')

if not media_manifest.is_variant:
    durations = [segment.duration for segment in media_manifest.segments]
    total_duration = sum(durations)
    
    print(f"Total Segments: {len(media_manifest.segments)}")
    print(f"Total Duration: {total_duration} seconds")
    
    if durations:
        avg_duration = statistics.mean(durations)
        max_duration = max(durations)
        min_duration = min(durations)
        
        print(f"Target Duration (Declared): {media_manifest.target_duration}")
        print(f"Average Segment: {avg_duration:.2f}s")
        print(f"Max Segment: {max_duration}s | Min Segment: {min_duration}s")
        
        if max_duration > media_manifest.target_duration:
            print("WARNING: Found segment exceeding EXT-X-TARGETDURATION!")

プレイリストをプログラムから編集する

動画配信ではマニフェストの動的な編集がよく必要になります。CDNドメインの差し替え、セグメント要求へのDRM認証トークンの付与、モバイル向けに帯域を節約するための高ビットレート4Kバリアントの除外などが例です。

この m3u8 ライブラリはプレイリストをPythonオブジェクトとして扱うため、プロパティを変更してから dumps() メソッドでマニフェストを文字列に戻せます。

例1:モバイル向けバリアントの絞り込み

端末に応じたマニフェストを返すAPIゲートウェイでは、指定の解像度やビットレートを超えるバリアントを除外できます。

import m3u8

manifest = m3u8.load('https://example.com/master.m3u8')
max_bandwidth = 2000000 # 2 Mbps

# Filter the playlists
filtered_playlists = []
for p in manifest.playlists:
    if p.stream_info.bandwidth <= max_bandwidth:
        filtered_playlists.append(p)

manifest.playlists = filtered_playlists

# Generate the new M3U8 string
new_manifest_str = manifest.dumps()
print(new_manifest_str)

例2:CDNホスト名の移行

古いストレージから新しいCDNへ移行する場合は、メディアプレイリスト内のセグメントURIをまとめて書き換えられます。通常はAWS LambdaやCloudflare Workersなどのサーバーレス関数をリバースプロキシとして使います。

import m3u8

media_playlist = m3u8.load('https://old-cdn.com/video.m3u8')
new_base_url = "https://new-fast-cdn.net/"

for segment in media_playlist.segments:
    # If the URI is relative, you might need to prepend the full path.
    # If it's absolute, you can replace the domain.
    if segment.uri.startswith("http"):
        segment.uri = segment.uri.replace("https://old-cdn.com/", new_base_url)
    else:
        # Handling relative paths
        segment.uri = new_base_url + segment.uri

# Dump and save to disk
with open("migrated_video.m3u8", "w") as f:
    f.write(media_playlist.dumps())

暗号化タグとDRMタグの扱い

最近のHLSマニフェストには、AES-128やWidevine/FairPlayなどのDRMに関する暗号化タグ(#EXT-X-KEY)がよく含まれます。CORSの問題でプレーヤーが鍵を取得できないと、再生はすぐに失敗します。Pythonで鍵の情報を確認・変更できます。

for key in media_playlist.keys:
    if key is not None:
        print(f"Encryption Method: {key.method}")
        print(f"Key URI: {key.uri}")
        print(f"IV: {key.iv}")
        
        # Example: Append an authorization token to the key URI
        if key.uri and "?" not in key.uri:
            key.uri += "?auth_token=super_secret_token"

サーバー側広告挿入(SSAI)と不連続点の管理

HLSストリームに冒頭や途中の広告を挿入するSSAIでは、本編と広告の間でコーデック設定、解像度、タイムスタンプが変わることがあります。プレーヤーにデコーダーの再初期化を知らせるには #EXT-X-DISCONTINUITY タグを挿入します。

この m3u8 ライブラリでは不連続点を自然に扱えます。新しいプレイリストを作る場合や二つを結合する場合は、該当セグメントに不連続フラグを付けます。

  • タイムスタンプのリセット: 不連続点は、次のセグメントでPTS/DTSタイムスタンプが飛ぶことをプレーヤーに知らせます。
  • コーデックの変更: Apple端末のハードウェアデコーダーを停止させずに、1080pストリームへ720pの広告を挿入できます。
  • シーケンス番号: ライブ配信を生成するときは #EXT-X-DISCONTINUITY-SEQUENCE タグを適切に管理してください。再生ウィンドウが移動しても、クライアントが位置を見失わずに済みます。
Pythonで segment.discontinuity 真偽値プロパティを設定してから manifest.dumps()を呼び出せば、異なるメディアストリームを正確につなぎ、途切れのない視聴体験を提供できます。

本番環境でのHLS編集のベストプラクティス

Python製のHLSパーサーを本番環境に導入するときは、次の点を押さえてください。

  • RFC 8216に照らして検証する: 正規表現より標準的なライブラリを使います。独自パーサーは #EXT-X-DATERANGE やベンダー独自タグなど、想定外のタグで動かなくなりがちです。
  • HTTPエラーを適切に処理する: ライブ配信ではエンコーダーの処理が遅れると404や502が返ることがあります。 urllib3 や tenacityを使って手動でパスを結合する必要はありません。
  • キャッシュ制御ヘッダーに従う: ライブのメディアプレイリストを取得するときはHTTPの Cache-Control ヘッダーを確認します。取得間隔は #EXT-X-TARGETDURATION の値またはその半分を目安にします。
  • 終わらないライブ配信のメモリ管理: プレイリストに #EXT-X-ENDLIST タグが付かないライブ配信を監視する場合、セグメントをメモリ上の配列へ追加し続けず、直近の一定数だけを保持します。

まとめ

PythonはHLS M3U8ファイルの解析・検査・編集に柔軟に対応できます。 m3u8 ライブラリを使えば、品質確認の自動化、動的なCDN振り分け、SSAIによる結合、利用者別マニフェスト生成を少ないコードで実現できます。バッファリングの調査から大規模ライブ配信の運用まで、マニフェストをプログラムから制御する力は重要です。