# ustvgo-tvguide: A GitHub Action that turns USTVGO channel data into EPG XML > ustvgo-tvguide is a small ETL repository that generates EPG XML for USTVGO Free IPTV channels, twice an hour, via GitHub Actions. It is a companion to the ustvgo-iptv project, and it exists to solve a narrow problem: giving IPTV players a program guide without running your own server. **interlark/ustvgo-tvguide** — TV Guide for USTVGO Free IPTV - Repository: https://github.com/interlark/ustvgo-tvguide - Website: https://github.com/interlark/ustvgo-iptv - Stars: 75 · Forks: 11 - Language: Python - License: not declared - Published: 2026-08-22 · Updated: 2026-08-22 · Language: en - Canonical page: https://hysenlabs.com/projects/interlark-ustvgo-tvguide ## What this repository actually is ustvgo-tvguide is not a standalone application. It is the TV guide component of the larger USTVGO Free IPTV project, which lives at interlark/ustvgo-iptv. The README describes this repo as a GitHub Action based ETL that generates EPG XML for upcoming programs of all the channels. The output is a set of XML files, both plain and gzip compressed, that IPTV players can consume. The project targets a specific audience: people who use the ustvgo-iptv playlist and want a program schedule that updates regularly. It does not aim to be a general EPG service. The entire deliverable is four files, two color variants and their compressed versions. That is the whole scope. ## The mechanism: a scheduled GitHub Actions workflow The README states that the ETL runs twice an hour. That cadence is a clue to the architecture. A GitHub Actions workflow, referenced as tvguide.yml in the badges, is the engine. The workflow presumably fetches channel data from the upstream ustvgo-iptv project, extracts program information, and writes EPG XML. The repository layout shows a master branch with the generated XML files committed directly. That means the workflow runs on a schedule, updates the files, and commits them back to the repository. The generated files are then served via raw.githubusercontent.com. This approach avoids any external hosting. The player fetches the XML from the raw URL, just like it would fetch the playlist. The compression is a practical touch: gzipped XML reduces bandwidth for players that support it. The dark and light variants are a user interface consideration, since EPG background colors differ between players. ## Getting it running: what the material shows The README provides no installation instructions. There are no commands to run, no config keys to set. The only concrete artifacts are the four file URLs. To use the guide, you point your IPTV player at one of those raw GitHub URLs. For a dark UI player, use ustvgo.for-dark-bg.xml or the .gz version. For a light UI player, use ustvgo.for-light-bg.xml. If you want to run the ETL yourself, you would need to inspect the tvguide.yml workflow file in the repository, since the README does not document it. The PyPI badge links to the ustvgo-iptv package, not to this repo, so the Python code likely lives in the parent project. This repository is more of a deployment artifact than a codebase you run locally. ## Limitations and failure modes The most obvious limitation is that this repository has no license. The README does not state a license, and the metadata lists it as unknown. That is a legal problem if you plan to fork or redistribute the workflow. Another limitation is the lack of documentation. There is no explanation of the EPG schema, no example of the XML structure, and no troubleshooting guide. If the workflow breaks, you have no guidance. The project also depends entirely on the upstream ustvgo-iptv project. If that project changes its data format or goes offline, this guide stops producing useful output. The twice-an-hour schedule is a trade-off: it is frequent enough for most live TV, but not for last-minute schedule changes. A player that caches the XML might show stale data for up to 30 minutes. That is acceptable for free IPTV, but not for a production service. ## The alternative: running your own EPG service The obvious alternative is to run a dedicated EPG service like XMLTV or a self-hosted tool such as tvheadend's EPG grabber. Those tools give you control over the schedule, the channels, and the output format. They also require a server, a database, and ongoing maintenance. ustvgo-tvguide avoids all of that by offloading the work to GitHub Actions. The difference in approach is fundamental: this repo is a scheduled batch job that writes static files, while a self-hosted EPG service is a daemon that responds to requests. The static file approach is simpler and free, but it cannot offer per-user customization. You cannot ask it for a specific set of channels. You get whatever the workflow produces. For a user who just wants a guide for the ustvgo playlist, that is fine. For someone who wants to merge multiple sources or filter channels, a real EPG service is the better fit. ## Maintenance and upgrade cost Because this repository has no release history and no documented changelog, the maintenance cost is hard to estimate. The last push date is unknown, which is a warning sign. The project could be dormant. The only active component is the GitHub Actions workflow, which runs on GitHub's infrastructure. That means you do not pay for servers, but you do depend on GitHub's free tier limits. If the workflow uses more than the allowed minutes, it will fail. Upgrading the project means editing the workflow file, which is not documented. The license situation adds risk: without a license, you cannot legally reuse the code in a commercial project. The PyPI package, ustvgo-iptv, is the actual Python code. This repo is just the output. So the maintenance burden is split: you maintain the workflow here, and the upstream project maintains the ETL logic. That split can cause version mismatches. ## Conclusion Adopt ustvgo-tvguide if you already use the ustvgo-iptv project and need a program guide that updates frequently without hosting your own EPG service. The repository is thin: no license, no release history, no documented setup steps beyond the workflow file. Do not adopt it if you need a general-purpose EPG generator, or if you expect a maintained, documented project. Verify first that the GitHub Actions workflow still runs, that the generated XML matches your player's expectations, and that the upstream ustvgo-iptv project is active. The project's value is its simplicity: a scheduled workflow that produces two XML files. That is also its ceiling. ## FAQ ### How often is the ustvgo-tvguide EPG XML rebuilt? Twice an hour, by a GitHub Action described as an ETL over the upcoming programs of all the channels. The four XML files sit in the master branch and the README links them through raw.githubusercontent.com. ### Which EPG file should an IPTV player use with ustvgo-tvguide? Match the suffix to the player interface. ustvgo.for-dark-bg.xml and ustvgo.for-light-bg.xml are the plain guides, and ustvgo.for-dark-bg.xml.gz and ustvgo.for-light-bg.xml.gz are the compressed copies of the same two. ### What does ustvgo-tvguide need in order to run? The README documents no local command, so the documented runtime is the tvguide.yml GitHub Action. requirements.txt asks for aiohttp, tqdm, pydantic, py-xmltv, Pillow, diskcache, furl and lxml, with only py-xmltv pinned exactly at 1.0.8. ### What licence applies to the ustvgo-tvguide XML files? None is stated. There is no LICENSE file at the top level of the repository and no licence recorded for it, so the terms for redistribution are not written down anywhere in the project. ### Is ustvgo-tvguide the same project as USTVGO Free IPTV? No. The README calls it the TV Guide part of the USTVGO Free IPTV project, which is a separate repository at github.com/interlark/ustvgo-iptv with its own PyPI page. The two header badges point at that parent project rather than at a package built from this repository. ## Sources - [Official documentation](https://github.com/interlark/ustvgo-iptv) - [Official README](https://github.com/interlark/ustvgo-tvguide#readme) - [Project repository](https://github.com/interlark/ustvgo-tvguide) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/interlark-ustvgo-tvguide