hmlendea/iptv-playlist-aggregator
hmlendea/iptv-playlist-aggregator has 62 GitHub stars and 15 forks. GitHot measured -1 stars in 24 hours. Last checked 2026-11-18 12:42 UTC. Last push 2026-11-14.
What you can do
- Retrieves M3U playlists from multiple configurable providers.
- Matches provider channels against configured channel definitions and aliases.
Measured star growth
- in 24h
- -1
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
.NET console application that downloads IPTV playlists from multiple providers and merges them into a single curated M3U file.
Self-hostedREADME.md
OriginalIPTV Playlist Aggregator
IPTV Playlist Aggregator is a .NET console application that retrieves playlists from multiple providers and aggregates them into one curated M3U output.
📑 Table of Contents
- Table of Contents
- Capabilities
- Usage
- Known Limitations
- System Requirements
- Installation
- Configuration
- Development
- GitHub Actions
- Project Structure
- Architecture
- Contributing
- Supporting the Project
- Security
- License
✨ Capabilities
- Retrieves M3U playlists from multiple configurable providers.
- Matches provider channels against configured channel definitions and aliases.
🚀 Usage
dotnet run --project IptvPlaylistAggregator
Before running, adjust data files in IptvPlaylistAggregator/Data/ and revise settings in IptvPlaylistAggregator/appsettings.json.
⚠️ Known Limitations
- Playlist retrieval and stream validation require internet access.
- Enabled providers must have unique priorities; a later playlist replaces an earlier playlist with the same priority.
- One process should own a cache directory at a time because cache files have no cross-process coordination.
- Stream-status URLs containing commas are truncated when the CSV cache is serialised.
🖥️ System Requirements
- OS: Linux, macOS, Windows.
- RAM: 256 MB minimum.
- .NET 10.0 runtime.
📦 Installation
CLI Installation
Download the archive for your platform from the latest GitHub release and execute the extracted binary.
⚙️ Configuration
All settings are loaded from the configuration file. The subsequent keys are recognised:
| Section | Key | Description |
|---|---|---|
nuciLoggerSettings |
logFilePath |
Path for the application log file. |
nuciLoggerSettings |
isFileOutputEnabled |
Enables or disables file logging. |
nuciLoggerSettings |
minimumLevel |
Minimum severity level written to logs. |
applicationSettings |
outputPlaylistPath |
Output path for the aggregated M3U playlist. |
applicationSettings |
daysToCheck |
Number of days checked for date-based provider URLs. |
applicationSettings |
areUnmatchedChannelsIncluded |
Includes unmatched channels in the output when enabled. |
applicationSettings |
areTvGuideTagsEnabled |
Enables TV guide tags in output entries. |
applicationSettings |
arePlaylistDetailsTagsEnabled |
Enables source playlist detail tags in output entries. |
cacheSettings |
cacheDirectoryPath |
Directory used for cached data. |
cacheSettings |
streamAliveStatusCacheTimeout |
Cache timeout in seconds for alive stream checks. |
cacheSettings |
streamDeadStatusCacheTimeout |
Cache timeout in seconds for dead stream checks. |
cacheSettings |
streamUnauthorisedStatusCacheTimeout |
Cache timeout in seconds for unauthorised stream checks. |
cacheSettings |
streamNotFoundStatusCacheTimeout |
Cache timeout in seconds for not-found stream checks. |
dataStoreSettings |
channelStorePath |
XML path for channel definitions. |
dataStoreSettings |
groupStorePath |
XML path for group definitions. |
dataStoreSettings |
playlistProviderStorePath |
XML path for playlist provider definitions. |
🛠️ Development
Requirements
Setup
All NuGet dependencies are restored automatically by dotnet restore.
Build
dotnet build IptvPlaylistAggregator
Run
dotnet run --project IptvPlaylistAggregator
Test
dotnet test IptvPlaylistAggregator.slnx
Release
Publish a release on GitHub; .github/workflows/github-release.yml builds the self-contained per-runtime release artefacts and attaches them to the release.
Dependencies
| Package | Purpose |
|---|---|
Microsoft.Extensions.Configuration |
Configuration loading infrastructure. |
Microsoft.Extensions.Configuration.Binder |
Strongly typed configuration binding. |
Microsoft.Extensions.Configuration.Json |
JSON configuration provider. |
Microsoft.Extensions.DependencyInjection |
Dependency injection container. |
NuciDAL |
XML data access primitives. |
NuciExtensions |
General utility extensions. |
NuciLog |
Logging implementation. |
NuciLog.Core |
Core logging abstractions. |
NuciWeb.HTTP |
HTTP client construction and connectivity checks. |
⚙️ GitHub Actions
| Workflow | Purpose | What it does |
|---|---|---|
| .NET | Validates the solution | Restores dependencies, compiles the solution, and executes the tests on Ubuntu for pushes and pull requests to master. |
| GitHub Release | Publishes release assets | Builds the self-contained archives for every supported runtime through the shared release script and attaches them to the published GitHub release. |
| Security | Automated security scanning | Checks dependencies for known vulnerabilities and runs CodeQL static analysis for C# on pushes and pull requests to master, and on a weekly schedule. |
🗂️ Project Structure
The solution contains the subsequent projects:
IptvPlaylistAggregator: Main console application.IptvPlaylistAggregator.UnitTests: Unit test suite.IptvPlaylistAggregator.IntegrationTests: Mock-driven integration-style test suite using temporary cache state.IptvPlaylistAggregator.ArchitectureTests: ArchUnit.NET and Roslyn checks for layer dependencies, source conventions, and project and solution layout.
The key directories inside IptvPlaylistAggregator/ are:
| Directory | Purpose |
|---|---|
Configuration/ |
Application, cache, and datastore settings models. |
Data/ |
XML source files for channels, groups, and providers. |
DataAccess/ |
Data objects used for XML persistence. |
Logging/ |
Logging operation and contextual keys. |
Service/ |
Aggregation, validation, matching, and output generation services. |
🏗️ Architecture
See ARCHITECTURE.md for a structural synopsis and component interactions.
See docs/README.md for detailed runtime, data, selection, playlist, testing, and maintenance documentation.
🤝 Contributing
You are welcome to submit any suggestion, feedback, or modification to this project.
When doing so, please:
- Maintain cross-platform compatibility
- Maintain the pull requests as focused and consistent with the existing code style
- Maintain your branch up-to-date with
master - Revise the documentation when behaviour changes
- Properly test all changes, including edge cases and error conditions
- Add unit tests for any new or changed functionality
💝 Supporting the Project
Discovered a problem or have a suggestion? Open an issue!
If you find this project useful, consider funding it or starring ⭐️ it on GitHub!
🔐 Security
Please review SECURITY.md for details on reporting vulnerabilities, supported versions, and the project's coordinated disclosure policy.
📄 License
This project is being distributed under the GNU General Public License v3.0 or later.
See LICENSE for further information.

