Skip to content
Projects

hmlendea/iptv-playlist-aggregator

View on GitHub

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.

How these counts are measured

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-hosted

README.md

Original

Donate Latest Release Build Status Security Scan License: GPL v3

IPTV 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

✨ 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

Obtain it from GitHub

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!

Donate

🔐 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.