Pure Javascript cross-platform module to manage m3u iptv playlist

Functionalities:

• parser: Assumed to parse an M3U file string into a structured JSON format.
• generator: Playlist and Link classes for generating M3U playlists.
• checker: Assumed to validate URLs in an M3U playlist, returning their status (e.g., online, ofline).
• merger: Assumed to combine multiple M3U playlists into one, handling duplicates or formatting.

Similar Packages

I developed iptv-util to overcome the limitations of existing packages, which suffer from parsing errors, missing features and heavy dependencies.

❌ @iptv/playlist Fails to handle some M3U formats, lacking essential features like merging and validation.
❌ iptv-playlist-parser Some parsing bugs, offering no generation and validation capabilities.
❌ esx-iptv-playlist-parser A buggy, untested mess with no recent updates.
❌ iptv-checker Crippled by FFmpeg dependency, missing parsing and generation.
❌ iptv-playlist-generator Incompatible with its own parser, missing validation.
❌ iptv-checker-module It’s a clunky, single-purpose module.

Performance

Package	Ops/sec	Min (ms)	Max (ms)	Mean (ms)	p75 (ms)	p99 (ms)	RME
iptv-util	3.3648	287.17	318.69	297.19	306.11	318.69	±2.56%
@iptv/playlist	0.8647	1093.79	1210.04	1156.40	1188.41	1210.04	±2.22%
iptv-playlist-parser	2.6438	366.59	396.95	378.24	383.14	396.95	±1.81%
esx-iptv-playlist-parser	1.7687	548.36	587.98	565.39	571.14	587.98	±1.39%

Benchmark Summary

• iptv-util - test/main.bench.js
  • 1.27x faster than iptv-playlist-parser
  • 1.90x faster than esx-iptv-playlist-parser
  • 3.89x faster than @iptv/playlist

Installation

1# npm
2npm install iptv-util
3
4# pnpm
5pnpm add iptv-util
6
7# yarn
8yarn add iptv-util

Usage

The iptv-util library provides tools to parse, generate, check, and merge IPTV M3U playlists. Below are examples demonstrating how to use the main functionalities: parser, Playlist and Link for generating playlists, checker for validating links, and merger for combining multiple playlists.

Parser

Use the parser function to parse an M3U playlist file into a structured format.

1import { parser } from 'iptv-util'
2import fs from 'node:fs'
3
4// Read the M3U playlist file from the filesystem
5const m3uContent = fs.readFileSync('playlist.m3u', 'utf8')
6// Parse the M3U content using the iptv-util parser to create a Playlist object
7const playlist = parser(m3uContent)
8
9// Convert the Playlist object to a JSON representation
10const json = playlist.toJson()
11// Convert the Playlist object back to its M3U text representation
12const text = playlist.toText()
13// Save the converted M3U text to a new file named 'output_playlist.m3u'
14fs.writeFileSync('output_playlist.m3u', text, 'utf8')
15
16// Check the playlist for working streams and return a cleaned Playlist object
17const cleanPlaylist = await playlist.check()
18// Convert the cleaned Playlist object to its M3U text representation
19const onlineOnly = cleanPlaylist.toText()
20// Save the cleaned M3U text to a new file named 'online_playlist.m3u'
21fs.writeFileSync('online_playlist.m3u', onlineOnly, 'utf8')
22// Access offline array
23const offlineArr = cleanPlaylist.offline

Generator

Use the Playlist and Link classes to create a new M3U playlist programmatically.

1import { Playlist, Link } from 'iptv-util'
2import fs from 'node:fs'
3
4// Create a new Playlist instance
5const playlist = new Playlist()
6
7// Set playlist header with TV guide URLs
8playlist.header = {
9  'x-tvg-url': '...',
10  'url-tvg': '...'
11}
12
13// Create a new Link for the first channel
14const link1 = new Link('http://example.com/stream1.m3u8')
15link1.title = 'Channel 1' // Set channel title
16link1.duration = -1 // Set duration (-1 for live stream)
17link1.extinf = {
18  'tvg-id': 'channel1', // Set TV guide ID
19  'group-title': 'Entertainment' // Set group category
20}
21link1.extgrp = 'Sports' // Set external group
22link1.extvlcopt = {
23  'http-referrer': 'http://example.com', // Set HTTP referrer
24  'http-user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)' // Set user agent
25}
26
27// Create a new Link for the second channel
28const link2 = new Link('http://example.com/stream2.m3u8')
29link2.title = 'Channel 2' // Set channel title
30link2.duration = -1 // Set duration (-1 for live stream)
31link2.extinf = {
32  'tvg-id': 'channel2', // Set TV guide ID
33  'group-title': 'Entertainment' // Set group category
34}
35
36// Add links to the playlist
37playlist.addLink(link1)
38playlist.addLink(link2)
39
40// Generate M3U text and JSON representations of the playlist
41const m3uText = playlist.toText()
42const m3uJson = playlist.toJson()
43
44// Log generated M3U and JSON content
45console.log('Generated M3U:', m3uText)
46console.log('Generated JSON:', m3uJson)
47
48// Save the M3U content to a file
49fs.writeFileSync('generated-playlist.m3u', m3uText)

Checker

Use the checker function to validate the URLs in an M3U playlist.

1import { checker, url2text, parser } from 'iptv-util'
2import fs from 'node:fs'
3
4// Check if a single stream URL is online
5const url1 = 'https://demiroren-live.daioncdn.net/kanald/kanald.m3u8'
6const isOnline = await checker(url1) // Returns true if the stream is working
7
8// Read M3U playlist content from a local file
9const m3uContent1 = fs.readFileSync('playlist.m3u', 'utf8')
10// Fetch M3U playlist content from a remote URL
11const url2 = 'https://raw.githubusercontent.com/iptv-org/iptv/refs/heads/master/streams/uk_samsung.m3u'
12const m3uContent2 = await url2text(url2)
13
14// Parse M3U content into a Playlist object
15const playlist = parser(m3uContent1) // Can also use m3uContent2
16
17// Check playlist for valid streams, returning a cleaned Playlist object
18const cleanPlaylist = await playlist.check()
19// Convert cleaned playlist to M3U text (online links only)
20const text = cleanPlaylist.toText()
21// Convert cleaned playlist to JSON (online links only)
22const json = cleanPlaylist.toJson()
23
24// Get arrays of offline and online links from the cleaned playlist
25const offlineArr = cleanPlaylist.offline
26const onlineArr = cleanPlaylist.links

Merger

Use the merger function to combine multiple M3U playlists into a single playlist.

1import { merger } from 'iptv-util'
2import fs from 'node:fs'
3
4// Load M3U playlist files from the filesystem
5const playlist1 = fs.readFileSync('playlist1.m3u', 'utf8')
6const playlist2 = fs.readFileSync('playlist2.m3u', 'utf8')
7
8// Array of M3U content strings
9const textArr = [
10  playlist1,
11  playlist2
12]
13
14// Array of M3U playlist URLs
15const urlArr = [
16  'https://raw.githubusercontent.com/iptv-org/iptv/refs/heads/master/streams/uk.m3u',
17  'https://raw.githubusercontent.com/iptv-org/iptv/refs/heads/master/streams/uk_sportstribal.m3u'
18]
19
20// Merge multiple playlists into a single Playlist object
21const mergedPlaylist1 = await merger(playlist1, playlist2) // Merge two local playlists
22const mergedPlaylist2 = await merger(...textArr) // Merge from text array
23const mergedPlaylist3 = await merger(...urlArr) // Merge from URL array
24
25// Convert merged playlists to M3U text format
26const text1 = mergedPlaylist1.toText()
27const text2 = mergedPlaylist2.toText()
28const text3 = mergedPlaylist3.toText()
29
30// Save merged playlists to separate M3U files
31fs.writeFileSync('mergedPlaylist1.m3u', text1, 'utf8')
32fs.writeFileSync('mergedPlaylist2.m3u', text2, 'utf8')
33fs.writeFileSync('mergedPlaylist3.m3u', text3, 'utf8')
34
35// Check merged playlist for valid streams and create a cleaned Playlist object
36const cleanPlaylist = await mergedPlaylist1.check()
37
38// Convert cleaned playlist to M3U text format (online links only)
39const cleanText = cleanPlaylist.toText()

Test

• npm run test
• Check test folder and quickstart.js for extra usages.

Support

I use this package actively myself, so it has my top priority. You can use GitHub issues for any infos, ideas and suggestions.

Submitting an Issue

If you find a bug or a mistake, you can help by submitting an issue to GitHub Repository

Creating a Pull Request

• A Guide for First-Timers
• How to create a pull request
• Check Contributing Guide

License

Apache-2.0 and all it's dependencies are MIT or BSD licensed.