iptv-org/epgで番組表をXMLにまとめる方法

SITES.mdを起点にした取得処理

iptv-org/epgの役割は、複数の番組情報サイトからElectronic Program Guideを取得することです。READMEの導入手順ではNode.jsとGitを用意し、masterブランチを浅くcloneしてepgディレクトリへ移動し、npm installで依存関係を入れます。取得元は任意のURLを直接渡すのではなく、SITES.mdに登録されたサイト名を指定します。基本コマンドはnpm run grab -- --sites=example.comで、処理が終わると作業ディレクトリにguide.xmlが生成されます。最小Node.js版やOSごとの詳細条件はREADMEに記載されていないため、導入前に実行環境で確認する必要があります。

grabの出力と取得条件を分けて考える

grabにはサイト名、カスタムチャンネルXML、出力先、言語、タイムアウト、遅延、プロキシ、取得日数、接続数、gzip、JSON、curl表示などの指定があります。複数サイトはカンマ区切りで渡せますが、異なるサイトの番組表を一つへ混ぜたくない場合はguides/{site}.xmlのような出力パターンを使います。--channelsを指定する場合、--sitesは不要で、利用したいチャンネルの説明をXMLとして用意します。出力形式と対象範囲を先に決めておくと、配信側で想定外のチャンネルが増える問題を抑えられます。

並列化は速度より相手サイトへの影響を先に見る

既定ではチャンネルを順番に取得します。--maxConnectionsを増やせば並列リクエストが増え、取得時間を短縮できる可能性があります。しかしREADMEは、高負荷時にサイトがエラーを返したりアクセスを遮断したりすることを明記しています。したがって接続数を大きくすることは単純な性能向上策ではありません。少数の対象で応答、失敗率、取得時間を記録し、timeoutとdelayを含めて相手側の制限に合わせます。カスタムチャンネルXMLを使えば不要なチャンネルへのアクセスを減らせるため、負荷管理と出力管理を同時に行えます。

cronとserveを組み合わせた提供例

READMEは、取得を一度実行するだけでなくタスクスケジューラから繰り返す方法も示しています。chronosを使い、npx chronos --execute="npm run grab -- --sites=example.com" --pattern="0 0,12 * * *" --logのようにcron式とコマンドを渡します。生成したguide.xmlをURLで読ませる用途ではnpx serveを使い、localhostの3000番からファイルを提供する例があります。これは簡易的な配信方法であり、認証、TLS、アクセス制御、外部公開時の監視まで設定するものではありません。実運用では配信サーバーの権限と公開範囲を別に設計してください。

Docker版で固定できる運用パラメータ

公式イメージはghcr.io/iptv-org/epg:masterとして案内されています。channels.xmlを/epg/public/channels.xmlへマウントし、ポート3000を公開してコンテナを起動する例がREADMEにあります。既定では毎日00:00 UTCに取得し、/epg/public/guide.xmlへ保存します。CRON_SCHEDULE、MAX_CONNECTIONS、GZIP、JSON、CURL、PROXY、DAYS、TIMEOUT、DELAY、RUN_AT_STARTUPといった環境変数はgrabの設定に対応します。コンテナの内部時刻、ボリュームの永続性、生成物の外部公開は利用者が確認すべき項目です。

周辺リポジトリとの役割分担

番組表を作るコードだけを見ていると、チャンネル定義の管理場所を取り違えます。READMEはチャンネルデータをiptv-org/database、APIドキュメントをiptv-org/api、IPTV関連資源をiptv-org/awesome-iptvへ案内しています。作成したガイドを共有するためのGUIDES.md、GitHub Discussions、貢献ガイドも入口として挙げられています。リポジトリのメタデータにはHTMLが主要言語として表示されますが、実際の取得手順はNode.jsのnpm scriptを中心に説明されています。統計値は取得時点の情報なので、採用判断では現在のREADMEとリリースを再確認してください。

Unlicenseが示す利用上の境界

ライセンスはUnlicenseで、本文はソフトウェアを商用または非商用を問わずコピー、変更、公開、利用、コンパイル、販売、配布できると説明します。一方、ソフトウェアは現状のまま提供され、保証はなく、著作者が請求や損害に責任を負わないという免責も含まれます。これは番組情報サイトの利用条件、著作権、再配信契約、個人情報の扱いを許可する文書ではありません。EPGを公開する場合は、取得元と配信先の規約、更新頻度、障害時の表示を別途点検する必要があります。

XML配信側で守るべき境界

npx serveの例は生成ファイルを簡単に読ませるための入口です。外部利用者へ配信する場合は、公開アドレス、認証方式、TLS証明書、アクセス記録、帯域制限、障害表示を個別に設計します。guide.xmlが置かれたディレクトリへchannels.xmlや設定ファイルまで公開しないよう、マウント先と公開根を分離します。番組情報の再配信に関する権利や取得元の条件は、Unlicenseの対象外です。配信先の利用規約、著作権表示、削除依頼、保存期間を確認し、コードのライセンスとデータの利用権を混同しないようにします。運用記録には取得日、対象局、取得件数、失敗局、生成時刻、公開時刻、修正者、確認者を残します。時刻情報はUTCと地域時刻を併記し、夏時間変更や日跨ぎによる誤表示を検査します。旧ファイルを保持したまま新ファイルを検証し、構文不正や件数急減がある場合は公開を切り替えません。サイト側の利用条件が変わった場合は処理を停止し、条件確認後に再開します。障害時に利用者へ古いデータを示すのか、停止を示すのかも事前に決めます。

編集部の結論

iptv-org/epgは、対応サイトの番組情報を定期的に集め、XMLTV形式のguide.xmlとして配信したい人に向きます。対象サイトの負荷、取得失敗、チャンネル定義の更新は利用者側の運用課題です。まず少数サイトと低い同時接続数で結果を確認し、生成XML、cron設定、Dockerの公開範囲を個別に検証してから定期処理へ移してください。導入判断では、取得対象、取得頻度、保存期間、出力形式、公開経路、利用権限、障害通知、復旧手順、監視項目を文書化します。サイト名、チャンネルID、言語コード、番組時刻、地域設定の対応関係を確認し、同一番組の重複、時刻帯のずれ、欠落チャンネル、空の番組表を検出できる照合処理を用意します。変更前後のguide.xmlを保存し、件数、開始時刻、終了時刻、番組名、説明文、文字コードを比較します。取得失敗は再試行だけで解決するとは限らず、サイト停止、HTML変更、接続拒否、レート制限、証明書異常、プロキシ障害を分けて記録します。接続数を増やす場合は、対象サイト別の応答時間、失敗率、帯域使用量、CPU使用量、メモリ使用量を測定し、許容値を決めます。Docker運用ではイメージ版、環境変数、UTC時刻、ボリューム、公開ポート、ログ保存、コンテナ再起動条件を固定します。channels.xmlの内容と権限を点検し、設定ファイルや秘密情報が配信根へ混入しないことを確認します。外部公開ではTLS、認証、アクセス制限、削除依頼、利用規約、著作権、再配信条件を確認します。Unlicenseはコード利用の条件を示すもので、取得元データの権利や第三者サイトの規約を置き換えません。READMEにない性能保証、保守保証、可用性保証、正確性保証を補ってはいけません。検証結果と未確認項目を分けて保存し、更新時はSITES.md、関連リポジトリ、リリース履歴、Docker定義を再確認します。番組表更新では、取得開始時刻、応答終了時刻、処理成功、部分失敗、再試行回数、生成件数、配信件数を分離して記録します。対象サイトのHTML構造が変更された場合、旧形式の解析結果を正常値として扱わず、検知通知を発行します。言語コードと地域コードの誤りは、取得成功でも利用者表示を壊すため、代表チャンネルを固定した受入確認を行います。日付境界、夏時間、UTC変換、深夜番組、日跨ぎ番組の時刻計算を確認します。複数サイトを同時処理する場合は、サイト別ログ、サイト別出力、全体集約結果を分離し、片側の障害が全体成功に見えないようにします。cron実行では重複起動、前回処理の残存、排他制御、終了コード、ログ容量を管理します。Dockerではイメージ更新前に生成物、channels.xml、環境変数、ボリューム、公開ポートを記録し、更新後に同じ対象を再取得します。取得元の仕様、再配信許可、削除要請、著作権表記、連絡先を確認し、コードの自由利用と番組データの自由利用を分けます。監視ではファイル更新時刻だけでなく、チャンネル数、番組数、未来時刻の有無、過去時刻の過多、XML検証結果を見ます。復旧時は最後に正常だったファイルを保持し、空ファイルや破損ファイルで正常なガイドを上書きしない手順を決めます。SITES.md、database、api、awesome-iptvの役割を確認し、定義変更を単独コードの変更として処理しません。未確認の性能値、保守期間、正確性、可用性、法的許諾を記事から補足せず、版、設定、ログ、生成XML、照合結果を根拠として採用判断を更新します。

公式情報源

1. Official documentation
2. Official README
3. Project repository