{"id":20892697,"url":"https://github.com/ektotv/playlist","last_synced_at":"2025-05-12T22:32:00.926Z","repository":{"id":178166493,"uuid":"661248614","full_name":"ektotv/playlist","owner":"ektotv","description":"An extremely fast M3U playlist parser and generator for Node and the browser.","archived":false,"fork":false,"pushed_at":"2024-09-08T22:50:35.000Z","size":1521,"stargazers_count":14,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-09-08T23:44:03.022Z","etag":null,"topics":["iptv","m3u","m3u8","parser","playlist"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@iptv/playlist","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ektotv.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-02T08:55:24.000Z","updated_at":"2024-09-08T22:49:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"a751c4bb-5608-4bb3-bef4-7fdd79ee8f78","html_url":"https://github.com/ektotv/playlist","commit_stats":null,"previous_names":["ektotv/playlist"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ektotv%2Fplaylist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ektotv%2Fplaylist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ektotv%2Fplaylist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ektotv%2Fplaylist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ektotv","download_url":"https://codeload.github.com/ektotv/playlist/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225156991,"owners_count":17429701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["iptv","m3u","m3u8","parser","playlist"],"created_at":"2024-11-18T10:13:38.058Z","updated_at":"2025-05-12T22:32:00.827Z","avatar_url":"https://github.com/ektotv.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./logo-dark.svg\"\u003e\n    \u003cimg alt=\"Playlist. TypeScript tools for working with M3U playlist data.\" src=\"./logo.svg\"\u003e\n  \u003c/picture\u003e\n\n# @iptv/playlist\n\nAn extremely fast M3U playlist parser and generator for Node and the browser. \u003cbr\u003eLightweight, dependency-free, and easy to use.\n\n---\n\n[![npm](https://img.shields.io/npm/v/@iptv/playlist?style=flat-square)](https://www.npmjs.com/package/@iptv/playlist)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/ektotv/playlist/ci.yml?branch=main\u0026style=flat-square)](https://github.com/ektotv/playlist/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/evoactivity/7c8deb6342792baafac8834185e96476/raw/iptv_playlist_coverage.json\u0026style=flat-square)](https://github.com/ektotv/playlist/tree/main/tests)\n[![GitHub](https://img.shields.io/github/license/ektotv/playlist?style=flat-square)](LICENSE.md)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n- **Extremely** fast M3U parser and generator\n- Lightweight (1.34 kB gzipped)\n- No dependencies\n- ESM and CommonJS support\n- Supports Node and the browser\n- Supports **any** M3U `#EXTINF` \u0026 `#EXTM3U` attribute\n- Did I mention [it's fast](#-performance)?\n\n---\n\n## 📥 Installation\n\nTo install this library, use the following command:\n\n```bash\n# pnpm\npnpm add @iptv/playlist\n\n# npm\nnpm install @iptv/playlist\n\n# yarn\nyarn add @iptv/playlist\n```\n\n---\n\n## 🔧 Usage\n\nTo use this library in your project, first import the functions you need:\n\n```typescript\nimport { parseM3U, writeM3U } from '@iptv/playlist';\n```\n\nThen, you can parse an M3U file and receive back an `M3uPlaylist` object:\n\n\u003cdetails\u003e\n  \u003csummary\u003eExample M3U File\u003c/summary\u003e\n\nExamples will be based on this M3U file, it can be found in the [tests/fixtures](tests/fixtures) directory.\n\n```m3u\n#EXTM3U\n#EXTINF:-1 tvg-id=\"Channel1\" tvg-name=\"Channel 1\" tvg-language=\"English\" group-title=\"News\",Channel 1\nhttp://server:port/channel1\n```\n\n\u003c/details\u003e\n\n```typescript\nconst m3u = `...`; // M3U file contents\nconst playlist: M3uPlaylist = parseM3U(m3u);\nconst channels: M3uChannel[] = playlist.channels;\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eExample output of `parseM3U()`\u003c/summary\u003e\n\n```typescript\n{\n  channels: [\n    {\n      tvgId: 'Channel1',\n      tvgName: 'Channel 1',\n      tvgLanguage: 'English',\n      groupTitle: 'News',\n      duration: -1,\n      name: 'Channel 1',\n      url: 'http://server:port/channel1',\n      extras: {\n        'your-custom-attribute': 'your-custom-value'\n      }\n    },\n  ],\n  headers: {}\n}\n```\n\n\u003c/details\u003e\n\nYou can also generate an M3U file from a `M3uPlaylist` object:\n\n```typescript\nconst playlistObject: M3uPlaylist = {\n  channels: [\n    {\n      tvgId: 'Channel1',\n      tvgName: 'Channel 1',\n      tvgLanguage: 'English',\n      groupTitle: 'News',\n      duration: -1,\n      name: 'Channel 1',\n      url: 'http://server:port/channel1',\n      extras: {\n        'your-custom-attribute': 'your-custom-value',\n      },\n    },\n  ],\n  headers: {},\n};\nconst m3u = writeM3U(playlistObject);\nconsole.log(m3u); // #EXTM3U ...\n```\n\n### Standard Attributes\n\nThis library supports all standard attributes for the `#EXTINF` and `#EXTM3U` tags. They will be parsed, camelCased and added as properties on the `M3uChannel` object.\n\n### Custom Attributes\n\nThis 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.\n\n```m3u\n#EXTM3U\n#EXTINF:-1 tvg-id=\"Channel1\" tvg-name=\"Channel 1\" tvg-language=\"English\" group-title=\"News\" custom-attribute=\"hello\",Channel 1\nhttp://server:port/channel1\n```\n\n```typescript\nconst m3u = `...`; // M3U file contents\nconst playlist: M3uPlaylist = parseM3U(m3u);\nconst channel: M3uChannel = playlist.channels[0];\nconsole.log(channel.extras); // { 'custom-attribute': 'hello' }\n```\n\n---\n\n## ⚡ Performance\n\nThis library has been optimized for parsing and generating M3U files quickly and efficiently. In my benchmarks, it performs better than [iptv-playlist-parser](https://www.npmjs.com/package/iptv-playlist-parser), [iptv-playlist-generator](https://www.npmjs.com/package/iptv-playlist-generator) and [m3u-parser-generator](https://www.npmjs.com/package//m3u-parser-generator).\n\n### Benchmarks\n\n#### Parsing M3U file (small.m3u8)\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n        \u003cth align=\"left\"\u003e\u003c/th\u003e\n        \u003cth align=\"left\"\u003eLibrary\u003c/th\u003e\n        \u003cth align=\"left\"\u003eOps/sec\u003c/th\u003e\n      \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth\u003e🟢\u003c/th\u003e\n      \u003cth align=\"left\"\u003e@iptv/playlist\u003c/th\u003e\n      \u003ctd align=\"right\"\u003e1,363,859\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\u003c/th\u003e\n      \u003cth align=\"left\"\u003em3u-parser-generator\u003c/th\u003e\n      \u003ctd align=\"right\"\u003e607,573\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e🔴\u003c/th\u003e\n      \u003cth align=\"left\"\u003eiptv-playlist-parser\u003c/th\u003e\n      \u003ctd align=\"right\"\u003e244,150\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n#### Writing M3U file (small.m3u8)\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth align=\"left\"\u003e\u003c/th\u003e\n      \u003cth align=\"left\"\u003eLibrary\u003c/th\u003e\n      \u003cth align=\"left\"\u003eOps/sec\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth align=\"left\"\u003e🟢\u003c/th\u003e\n      \u003cth align=\"left\"\u003e@iptv/playlist\u003c/th\u003e\n      \u003ctd align=\"right\"\u003e10,514,760\u003c/td\u003e\n    \u003c/tr\u003e\n     \u003ctr\u003e\n      \u003cth align=\"left\"\u003e\u003c/th\u003e\n      \u003cth align=\"left\"\u003eiptv-playlist-generator\u003c/th\u003e\n      \u003ctd align=\"right\"\u003e3,119,304\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth align=\"left\"\u003e🔴\u003c/th\u003e\n      \u003cth align=\"left\"\u003em3u-parser-generator\u003c/th\u003e\n      \u003ctd align=\"right\"\u003e1,816,358\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n#### Time spent parsing different M3U files\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth align=\"left\"\u003e\u003c/th\u003e\n      \u003cth align=\"left\"\u003eChannels\u003c/th\u003e\n      \u003cth align=\"right\"\u003e1\u003c/th\u003e\n      \u003cth align=\"right\"\u003e100\u003c/th\u003e\n      \u003cth align=\"right\"\u003e500\u003c/th\u003e\n      \u003cth align=\"right\"\u003e1,000\u003c/th\u003e\n      \u003cth align=\"right\"\u003e10,000\u003c/th\u003e\n      \u003cth align=\"right\"\u003e100,000\u003c/th\u003e\n      \u003cth align=\"right\"\u003e1,000,000\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth align=\"left\"\u003e🟢\u003c/th\u003e\n      \u003cth align=\"left\"\u003e@iptv/playlist\u003c/th\u003e\n      \u003ctd align=\"right\"\u003e~11 μs\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~201 μs\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~894 μs\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~1.94 ms\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~5.41 ms\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~67 ms\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~681 ms\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth align=\"left\"\u003e\u003c/th\u003e\n      \u003cth align=\"left\"\u003em3u-parser-generator\u003c/th\u003e\n      \u003ctd align=\"right\"\u003e~17 μs\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~226 μs\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~1.23 ms\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~3.66 ms\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~17 ms\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~153 ms\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~1.68 s\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth align=\"left\"\u003e🔴\u003c/th\u003e\n      \u003cth align=\"left\"\u003eiptv-playlist-parser\u003c/th\u003e\n      \u003ctd align=\"right\"\u003e~116 μs\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~513 μs\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~2.61 ms\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~5.17 ms\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~57 ms\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~385 ms\u003c/td\u003e\n      \u003ctd align=\"right\"\u003e~3.94 s\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003cp\u003e\u003csup\u003eI used nanobench to get the above times.\u003c/sup\u003e\u003c/p\u003e\n\n\u003cp\u003e\u003csup\u003eThese benchmarks were run on a 2021 MacBook Pro M1 Max (10 cores) with 64 GB of RAM.\u003c/sup\u003e\u003c/p\u003e\n\n---\n\n## 🎯 Future Goals\n\n### Worker Support\n\nEven 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.\n\n## 🚫 Non-Goals\n\n### HLS Parsing\n\nThis 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.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Even better if they align with the [future goals](#-future-goals).\n\nYou'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.\n\nTo be accepted your PR must pass all tests and not negatively impact the benchmarks. Some commands to help you:\n\n- `pnpm run test` - Run the vitest suite\n- `pnpm run benny` - Run benchmarks with benny\n- `pnpm run benchmark` - Run benchmarks with vitest\n- `pnpm run nanobench` - Run additional timing benchmarks\n\nThis project uses [Changesets](https://github.com/changesets/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](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md).\n\n## 📄 License \u0026 Credit\n\nThis library is licensed under the [MIT License](https://github.com/ektotv/playlist/LICENSE.md) and is free to use in both open source and commercial projects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fektotv%2Fplaylist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fektotv%2Fplaylist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fektotv%2Fplaylist/lists"}