✨ Features
- Extremely fast M3U parser and generator
- Lightweight (1.34 kB gzipped)
- No dependencies
- ESM and CommonJS support
- Supports Node and the browser
- Supports any M3U
#EXTINF
& #EXTM3U
attribute - Did I mention it's fast?
📥 Installation
To install this library, use the following command:
pnpm add @iptv/playlist
npm install @iptv/playlist
yarn add @iptv/playlist
🔧 Usage
To use this library in your project, first import the functions you need:
import { parseM3U, writeM3U } from "@iptv/playlist";
Then, you can parse an M3U file and receive back an M3uPlaylist
object:
Example M3U File
Examples will be based on this M3U file, it can be found in the tests/fixtures directory.
#EXTM3U
#EXTINF:-1 tvg-id="Channel1" tvg-name="Channel 1" tvg-language="English" group-title="News",Channel 1
http://server:port/channel1
const m3u = `...`;
const playlist: M3uPlaylist = parseM3U(m3u);
const channels: M3uChannel[] = playlist.channels;
Example output of `parseM3U()`
{
channels: [
{
tvgId: 'Channel1',
tvgName: 'Channel 1',
tvgLanguage: 'English',
groupTitle: 'News',
duration: -1,
name: 'Channel 1',
url: 'http://server:port/channel1',
extras: {
'your-custom-attribute': 'your-custom-value'
}
},
],
headers: {}
}
You can also generate an M3U file from a M3uPlaylist
object:
const playlistObject: M3uPlaylist = {
channels: [
{
tvgId: "Channel1",
tvgName: "Channel 1",
tvgLanguage: "English",
groupTitle: "News",
duration: -1,
name: "Channel 1",
url: "http://server:port/channel1",
extras: {
"your-custom-attribute": "your-custom-value",
},
},
],
headers: {},
};
const m3u = writeM3U(playlistObject);
console.log(m3u);
Standard Attributes
This library supports all standard attributes for the #EXTINF
and #EXTM3U
tags. They will be parsed, camelCased and added as properties on the M3uChannel
object.
Custom Attributes
This library supports any custom attributes you may have in your M3U file. They will be parsed and generated as an object under the extras
property of the M3uChannel
object.
#EXTM3U
#EXTINF:-1 tvg-id="Channel1" tvg-name="Channel 1" tvg-language="English" group-title="News" custom-attribute="hello",Channel 1
http://server:port/channel1
const m3u = `...`;
const playlist: M3uPlaylist = parseM3U(m3u);
const channel: M3uChannel = playlist.channels[0];
console.log(channel.extras);
⚡ Performance
This library has been optimized for parsing and generating M3U files quickly and efficiently. In my benchmarks, it performs better than iptv-playlist-parser, iptv-playlist-generator and m3u-parser-generator.
Benchmarks
Parsing M3U file (small.m3u8)
| Library | Ops/sec |
---|
🟢 | @iptv/playlist | 1,363,859 |
---|
| m3u-parser-generator | 607,573 |
---|
🔴 | iptv-playlist-parser | 244,150 |
---|
Writing M3U file (small.m3u8)
| Library | Ops/sec |
---|
🟢 | @iptv/playlist | 10,514,760 |
---|
| iptv-playlist-generator | 3,119,304 |
---|
🔴 | m3u-parser-generator | 1,816,358 |
---|
Time spent parsing different M3U files
| Channels | 1 | 100 | 500 | 1,000 | 10,000 | 100,000 | 1,000,000 |
---|
🟢 | @iptv/playlist | ~11 μs | ~201 μs | ~894 μs | ~1.94 ms | ~5.41 ms | ~67 ms | ~681 ms |
---|
| m3u-parser-generator | ~17 μs | ~226 μs | ~1.23 ms | ~3.66 ms | ~17 ms | ~153 ms | ~1.68 s |
---|
🔴 | iptv-playlist-parser | ~116 μs | ~513 μs | ~2.61 ms | ~5.17 ms | ~57 ms | ~385 ms | ~3.94 s |
---|
I used nanobench to get the above times.
These benchmarks were run on a 2021 MacBook Pro M1 Max (10 cores) with 64 GB of RAM.
🎯 Future Goals
Worker Support
Even though it's fast and it won't block for long, this will block your main thread whilst it runs. I'd like to add support for running the parser in a worker so it doesn't block at all.
🚫 Non-Goals
HLS Parsing
This library is designed to parse and generate media player playlist files only. It is not designed to be a generic m3u parser or generator. It will not parse or generate HLS playlists.
🤝 Contributing
Contributions are welcome! Even better if they align with the future goals.
You'll need to be able to run the tests and benchmarks. To do so, you will need to run the ./create-fixtures.sh
script in the tests/fixtures
directory to generate the necessary fixture files.
To be accepted your PR must pass all tests and not negatively impact the benchmarks. Some commands to help you:
pnpm run test
- Run the vitest suitepnpm run benny
- Run benchmarks with bennypnpm run benchmark
- Run benchmarks with vitestpnpm run nanobench
- Run additional timing benchmarks
This project uses Changesets to manage releases. For you, this just means your PR must come with an appropriate changeset file. If you're not sure how to do this, just ask and I'll be happy to help, or read the changesets documentation on adding a changeset.
📄 License & Credit
This library is licensed under the MIT License and is free to use in both open source and commercial projects.