メインコンテンツへスキップ
M3U8 Technical Guides

M3U8ストリームをダウンロードするPythonスクリプトの書き方

HLSのM3U8ストリームを取得するPythonスクリプトを自作すると、ダウンロード処理を細かく制御できます。このガイドでは、複雑な認証ヘッダー、レート制限への対応、セグメントの並列取得、AES-128の復号を含む構成を説明します。

通常のHLS取得にはFFmpegやyoutube-dlが便利ですが、独自仕様の認証や暗号化があるストリームでは不足することがあります。Pythonでダウンローダーを作れば、セグメントごとのヘッダー指定、プロキシの切り替え、並列取得、マスタープレイリストからの配信版の選択を制御できます。

ここではM3U8を解析し、セグメントを並列に取得し、必要に応じて復号して一つの動画へ結合するPythonスクリプトを組み立てます。

準備するライブラリ

安定したダウンローダーを作るには、M3U8を正規表現だけで解析する方法を避けます。HLS仕様(RFC 8216)には多くの例外があるため、解析には m3u8 のPythonライブラリ、通信には requests を使います。

pip install m3u8 requests pycryptodome
  • m3u8: プレイリストの文字列を扱いやすいPythonオブジェクトに変換します。
  • requests: 独自ヘッダー、Cookie、セッションを指定してHTTP通信を行います。
  • pycryptodome: 暗号化されたストリームのAES復号に使います。

マスター・メディアプレイリストを解析

M3U8のURLは、複数の画質を含むマスタープレイリストを指すことがあります。スクリプトでそれを判定し、メディアプレイリストを選んでセグメントを解析します。

import m3u8
import requests

def get_best_playlist(url, headers):
    playlist = m3u8.load(url, headers=headers)
    
    if playlist.is_variant:
        # Sort by bandwidth, highest first
        variants = sorted(playlist.playlists, key=lambda p: p.stream_info.bandwidth, reverse=True)
        best_uri = variants[0].absolute_uri
        print(f"Selected highest quality variant: {best_uri}")
        return m3u8.load(best_uri, headers=headers)
    
    return playlist

url = "https://example.com/master.m3u8"
headers = {"User-Agent": "Mozilla/5.0"}
media_playlist = get_best_playlist(url, headers)

この m3u8.load() 関数は相対パスを内部で処理し、後続のリクエストに使う absolute_uri を設定します。自作ダウンローダーで起こりがちなURLの不具合を防げます。

AES-128暗号化への対応

ストリームが暗号化されている場合、メディアプレイリストには #EXT-X-KEY タグがあります。 METHOD=AES-128ではセグメント全体がAESのCBCモードで暗号化されます。鍵を取得し、初期化ベクトル(IV)を取り出してバイナリデータを復号します。

暗黙的なIVと明示的なIV

鍵タグに IV 属性がなければ、HLS仕様ではセグメントのシーケンス番号をゼロ埋めしてIVとして使います。スクリプトでもこれに対応します。

from Crypto.Cipher import AES

def decrypt_segment(encrypted_data, key_uri, iv_hex, seq_num, headers):
    # Fetch the 16-byte key
    key = requests.get(key_uri, headers=headers).content
    
    # Determine the IV
    if iv_hex:
        iv = bytes.fromhex(iv_hex.replace("0x", ""))
    else:
        # Fallback to segment sequence number
        iv = seq_num.to_bytes(16, byteorder='big')
        
    cipher = AES.new(key, AES.MODE_CBC, iv)
    return cipher.decrypt(encrypted_data)

セグメントを並列に取得

セグメントを一つずつ取得すると時間がかかります。帯域を有効に使うため、Pythonの concurrent.futures.ThreadPoolExecutorを使います。取得後は元の順序で結合する必要があります。

import concurrent.futures
import os

def download_segment(segment, index, headers):
    response = requests.get(segment.absolute_uri, headers=headers)
    data = response.content
    
    # Check for encryption
    if segment.key and segment.key.method == "AES-128":
        data = decrypt_segment(data, segment.key.absolute_uri, segment.key.iv, segment.media_sequence, headers)
        
    file_path = f"seg_{index:04d}.ts"
    with open(file_path, "wb") as f:
        f.write(data)
    
    print(f"Downloaded {file_path}")
    return file_path

# Execute downloads concurrently
downloaded_files = []
with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
    futures = {executor.submit(download_segment, seg, i, headers): i for i, seg in enumerate(media_playlist.segments)}
    
    # Collect files in order
    results = [None] * len(media_playlist.segments)
    for future in concurrent.futures.as_completed(futures):
        idx = futures[future]
        results[idx] = future.result()
        
downloaded_files = results
重要: パラメーター max_workers の値を上げすぎると、オリジンサーバーのDDoS対策やレート制限により429または403エラーが返ることがあります。

セグメントを一つの動画に結合

M3U8のセグメントは通常MPEG-TS(.ts)です。Linuxの cat やPythonのバイナリ書き込みで単純連結もできますが、タイムスタンプの不連続を修正するには、結合後のファイルをFFmpegに通す方が安全です。

import subprocess

def merge_segments(file_list, output_file="output.mp4"):
    # Create a concatenation text file for FFmpeg
    with open("concat_list.txt", "w") as f:
        for file in file_list:
            f.write(f"file '{file}'\n")
            
    # Run FFmpeg to merge without re-encoding
    command = [
        "ffmpeg", "-f", "concat", "-safe", "0", 
        "-i", "concat_list.txt", "-c", "copy", output_file
    ]
    subprocess.run(command, check=True)
    
    # Cleanup temporary files
    os.remove("concat_list.txt")
    for file in file_list:
        os.remove(file)
        
    print(f"Merge complete: {output_file}")

merge_segments(downloaded_files)

高度な問題調査のヒント

  • 期限切れのトークン: 多くのCDNは有効期限付きトークンをマスターM3U8のURLに付けます。プレイリストを解析した後、 m3u8 ライブラリが自動で引き継がない場合は、セグメントのリクエストにも必要なトークンを付けてください。
  • EXT-X-MAPの扱い: fMP4ストリームでは #EXT-X-MAPで初期化セグメントを指定します。このファイルも取得して結合ファイルの先頭に置かないと、動画は再生できません。
  • 再試行処理: ネットワークが切断された場合に備え、 requests.get() の呼び出しを while ループで囲み、指数バックオフと try-except ブロックで requests.exceptions.RequestExceptionを捕捉します。

まとめ

PythonでM3U8ダウンローダーを作れば、一般的なツールで対応しにくい制約も扱えます。 m3u8 パーサー、Pythonの並列処理、AES-128復号を組み合わせることで、安定した自動メディア処理を構築できます。