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

• Table of Contents
• Capabilities
• Usage
• Known Limitations
• System Requirements
• Installation
  • CLI Installation
• Configuration
• Development
  • Requirements
  • Setup
  • Build
  • Run
  • Test
  • Release
  • Dependencies
• 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

• .NET 10.0 SDK

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

The repository includes release.sh, which delegates to the upstream deployment script used by the project maintainer.

bash ./release.sh 2.13.2

This script downloads and executes an external release helper from https://raw.githubusercontent.com/hmlendea/deployment-scripts/master/release/dotnet/10.0.sh.

Note: Piping into bash is an intensely controversial topic. Please review any external scripts before running them in your environment!

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.

🗂️ Project Structure

The solution contains the subsequent projects:

• IptvPlaylistAggregator: Main console application.
• IptvPlaylistAggregator.UnitTests: Unit test suite.
• IptvPlaylistAggregator.IntegrationTests: Mock-driven integration-style test sources; the project currently builds but is not marked as a test project.

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.