IPTVチャンネルリストを自動管理！M3U8プレイリスト＋EPG一括取得ツール

このソフトで何ができる？

doms9/iptv は、テレビチャンネルとスポーツイベントの M3U8 プレイリストを自動で取得・管理する Python 製のツールセットです。2 本のスクリプトを実行するだけで、チャンネルリストと電子番組表（EPG）を最新の状態に保てます。VLC・Kodi・Jellyfin など多くのメディアプレイヤーと組み合わせて使えるため、自宅でフル機能の IPTV 環境を整えたい方に向いています。手作業でリストを更新する手間がなくなり、定期的に自動実行する仕組みへ発展させることも可能です。

こんな人におすすめ

自宅のメディアサーバーを整えたい人 — Kodi・Jellyfin・Emby に M3U8 プレイリストを取り込んで、パソコンやテレビで一元管理したいホームシアターユーザーに向いています。番組表（EPG）も同時に取得できるため、「今何をやっているか」がアプリ上で見やすくなります。
スポーツ中継をまとめて管理したい人 — events.m3u8 というスポーツイベント専用のプレイリストが用意されており、試合の視聴リストをメインのチャンネルリストと分けて整理できます。特定のイベントだけをすばやく一覧したいときに重宝します。
チャンネルリストの手動更新をなくしたい開発者・上級ユーザー — スクリプトを定期実行する仕組みを組み込むことで、常に最新のリストを維持できます。Docker や cron（定期実行の仕組み）と組み合わせると、ほぼ手を動かさずに運用できる自動化パイプラインが作れます。

インストール・使い方

このツールは Python 3.12 で動作が確認されています。依存パッケージの管理には uv（ユーブイ）という超高速なパッケージマネージャーを使います。uv.lock というファイルで必要なライブラリのバージョンが固定されているため、環境の違いによるトラブルが起きにくい構成です。

ターミナルとは？ 文字を入力してパソコンに命令を送る画面のことです。Mac なら「ターミナル」、Windows なら「PowerShell」や「コマンドプロンプト」が該当します。以下のコマンドはすべてコピー＆ペーストで使えます。

Step 1: リポジトリをダウンロードして移動する

git clone https://github.com/doms9/iptv.git
cd iptv

git clone（ギットクローン）は、GitHub（ソースコードの置き場）からファイル一式をまるごとダウンロードするコマンドです。cd iptv でそのフォルダに移動します。

Step 2: uv をインストールして依存ライブラリをそろえる

# uv がまだ入っていない場合のみ実行
curl -LsSf https://astral.sh/uv/install.sh | sh

# 必要なライブラリを一括インストール
uv sync

uv sync を実行すると、uv.lock に記録されたバージョンどおりにライブラリが揃います。初回は少し時間がかかりますが、2 回目以降はキャッシュが使われて高速です。

Step 3: チャンネルリストと番組表を取得する

# M3U8 プレイリスト（チャンネルリスト）の更新
uv run python M3U8/fetch.py

# EPG（電子番組表）の取得
uv run python M3U8/epg-fetch.py

fetch.py が最新のチャンネルリストを取得し、epg-fetch.py が番組表データ（TV.xml）を生成します。どちらも数秒〜数十秒で完了します。

Step 4: 生成されたファイルを確認する

ls -lh M3U8/

M3U8/ フォルダの中に TV.m3u8・events.m3u8・TV.xml などのファイルが揃っていれば成功です。ファイルの先頭部分を確認したい場合は head -30 M3U8/TV.m3u8 と入力すると最初の 30 行が表示されます。

Step 5: メディアプレイヤーに取り込む

VLC の場合: 「メディア → ネットワークストリームを開く」から M3U8/TV.m3u8 のパス（ファイルの場所）または URL を指定します。
Kodi の場合: 「PVR IPTV Simple Client」アドオンの設定画面で、M3U8 のパスと TV.xml の EPG パスをそれぞれ入力します。
Jellyfin の場合: ライブ TV の設定から M3U チューナーを追加し、同様にパスを登録します。

動かしてみた

Docker 環境でリポジトリを展開したところ、Python 3.12.13 が正常に稼働し、パッケージのインストールも問題なく完了しました。M3U8/ フォルダには以下のファイルが揃っていることを確認しています。

./M3U8/base.m3u8      # ベースとなるプレイリスト
./M3U8/TV.m3u8        # メインの TV チャンネルリスト
./M3U8/events.m3u8   # スポーツイベント専用リスト
./M3U8/TV.xml         # XMLTV 形式の電子番組表
./M3U8/fetch.py       # チャンネルリスト取得スクリプト
./M3U8/epg-fetch.py  # EPG データ取得スクリプト
./health.sh           # ヘルスチェックスクリプト
./pyproject.toml      # Python パッケージ設定ファイル
./uv.lock             # 依存ライブラリのバージョン固定ファイル

health.sh というヘルスチェックスクリプトが同梱されており、Docker コンテナや自動化パイプラインで継続稼働させることを前提とした設計になっています。uv.lock によって依存ライブラリのバージョンが固定されているため、別の PC や別の環境でも同じように動作することが期待できる点も好印象でした。既存の M3U8 ファイルがリポジトリに同梱されているため、スクリプトを実行しなくても VLC でそのまま開いて内容を確認できるのも手軽です。

ブラウザで試す

ブラウザ上で M3U8 プレイリストの構造を視覚的に確認できるインタラクティブなデモが用意されています。サンプルの M3U8 テキストを貼り付けると、チャンネル名・グループ・ストリーム URL の一覧をその場で解析・表示してくれます。ツールをインストールする前に「M3U8 がどんなデータなのか」を体験で確かめたい方にも便利です。

はじめの一歩 — すぐ試すための実践ポイント

まず VLC で開いてみる: スクリプトを実行しなくても、リポジトリに同梱の M3U8/TV.m3u8 を VLC にドラッグ＆ドロップするだけで動作感をつかめます。
最初は fetch.py だけ試す: EPG の設定は後回しにして、まずチャンネルリストの取得だけを確認するとハードルが下がります。
uv sync は必ず先に: スクリプトを実行する前に依存ライブラリをインストールしておかないとエラーになります。手順を飛ばさず順番どおりに進めましょう。
health.sh を cron に登録する: cron（クーロン）とは Linux・Mac でコマンドを定期実行するスケジューラーです。health.sh を登録すると、スクリプトが正常に動いているかを自動で監視できます。
ファイルパスは絶対パスで指定: Kodi や Jellyfin に登録する際、~/iptv/M3U8/TV.m3u8 のように ~ を使うと認識されないことがあります。/home/ユーザー名/iptv/M3U8/TV.m3u8 のようにフルパスで指定するのが確実です。
ライセンス確認は必須: 実際のストリーム URL を利用する際は、配信元のライセンス条件を自分で確認してください。ツール自体の仕組みは標準的な IPTV 管理の手法に沿っていますが、コンテンツの権利はユーザー側の責任になります。

用語とポイント解説

M3U8（エムスリーユーエイト） インターネット経由でライブ映像や動画の配信先 URL をまとめたプレイリスト形式です。かんたんに言うと「どのアドレスにアクセスすればどのチャンネルを見られるか」を並べたリストファイルです。VLC・Kodi・Jellyfin など多くのプレイヤーが対応しています。

EPG（Electronic Program Guide / 電子番組表） テレビの「今日の番組表」をデジタルデータ化したものです。かんたんに言うと「何時に何の番組が放送されるか」の情報を XML 形式で表したファイルです。epg-fetch.py が取得し TV.xml として保存します。

XMLTV（エックスエムエルティービー） EPG データを記述するための標準フォーマットです。かんたんに言うと「Kodi や Jellyfin が読み込める番組表の書き方のルール」です。このリポジトリが出力する TV.xml もこの形式に従っています。

IPTV（アイピーティービー） インターネット回線を使ってテレビ映像を配信・視聴する仕組みの総称です。かんたんに言うと「ネットを通じて見るテレビ」です。地上波や衛星放送とは異なり、専用のアプリやプレイヤーで視聴します。

uv（ユーブイ） Rust（ラスト）という言語で作られた超高速な Python パッケージマネージャーです。かんたんに言うと「Python のライブラリを素早く整えてくれる道具」です。従来の pip より大幅に速く、uv.lock でバージョンを固定できるためチーム開発や自動化との相性が良いです。

pyproject.toml（パイプロジェクトトムル） Python プロジェクトの設定や依存ライブラリを記述する設定ファイルです。かんたんに言うと「このプロジェクトに何が必要か」を書いたメモ書きです。uv sync はこのファイルを読んで必要なライブラリを揃えます。

cron（クーロン） Linux・Mac でコマンドやスクリプトを決まった時間に自動実行するスケジューラーです。かんたんに言うと「毎朝 6 時に自動でリストを更新する」といった設定ができる仕組みです。health.sh を cron に登録すると定期的な稼働確認が自動化されます。

PVR IPTV Simple Client（ピーブイアール） Kodi の拡張機能（アドオン）で、M3U8 プレイリストと XMLTV 形式の EPG を読み込んで Kodi をテレビチューナーのように使えるようにするプラグインです。かんたんに言うと「Kodi を IPTV 対応テレビに変えるための追加部品」です。設定画面に M3U8 のパスと TV.xml のパスを登録するだけで利用できます。

base.m3u8（ベースエムスリーユーエイト） カスタマイズのもとになるプレイリストファイルです。かんたんに言うと「チャンネルリストの原本」で、fetch.py がこのファイルを参照しながら最終的な TV.m3u8 を生成します。独自のチャンネルを追加したい場合はここを編集するのが基本です。

health.sh（ヘルスチェック） スクリプトや Docker コンテナが正常に動いているかを確認するためのシェルスクリプトです。かんたんに言うと「ちゃんと動いてるか確かめる見回り係」です。CI/CD（継続的インテグレーション／デリバリー）パイプラインや Docker Compose の healthcheck 設定と組み合わせて使います。

活用アイデア

Raspberry Pi ホームサーバー: 低消費電力の Raspberry Pi に Kodi をインストールし、このツールで定期更新された TV.m3u8 と TV.xml を読み込ませることで、フル機能の家庭内 IPTV サーバーが構築できます。リビングのテレビに繋いでそのまま運用できます。
Docker Compose での自動更新運用: health.sh を活用して Docker コンテナ内でスクリプトを定期実行し、常に最新のチャンネルリストを配信するマイクロサービスとして運用できます。コンテナが落ちても自動で再起動する設定と組み合わせれば、ほぼ無人で動き続けます。
スポーツ観戦専用リストの整備: events.m3u8 を活用して、スポーツ中継だけを集めた専用プレイリストを Kodi や VLC に登録しておけます。試合のたびにリストを探し回る手間がなくなります。
カスタムチャンネルフィルタリング: base.m3u8 をもとに独自スクリプトを組み合わせることで、「特定の地域のチャンネルだけ」「ニュース系のみ」のような絞り込みプレイリストを自動生成するパイプラインを構築できます。
チーム・家族での共有サーバー: 自宅 LAN（家庭内ネットワーク）内でサーバーを立て、生成した M3U8 ファイルを URL で共有すれば、家族の複数のデバイスから同じチャンネルリストを参照できます。全員が同じ最新リストを使えるため管理の一元化になります。
学習目的の Python スクリプト読解: fetch.py と epg-fetch.py のコードは比較的コンパクトで、HTTP リクエスト・ファイル操作・XML 生成という実用的な処理が詰まっています。Python の実践的なサンプルとしてコードを読み解くことで、スクレイピングや自動化スクリプトの書き方を学ぶ教材にもなります。

まとめ

doms9/iptv は、M3U8 形式の IPTV プレイリスト管理に特化した軽量 Python ツールです。fetch.py によるチャンネルリスト自動更新、epg-fetch.py による電子番組表取得、health.sh による死活監視という 3 点セットが揃っており、ホームメディアサーバーとの連携を前提とした設計になっています。uv による高速な依存関係管理も採用されており、モダンな Python 開発スタイルに沿った構成です。ストリーム URL の利用にあたっては配信元のライセンス条件をご自身で確認いただく必要がありますが、ツール自体の仕組みは IPTV プレイリスト管理の標準的なアプローチを踏んでいます。ぜひ Kodi や Jellyfin を使ったホームシアター構築や、Raspberry Pi を活用した家庭内メディアサーバーの自動化などに活用してみてはいかがでしょうか。