@iptv/xmltv
Advanced tools
An extremely fast XMLTV parser and generator for Node and the browser.
Lightweight, dependency-free, and easy to use.
The average XMLTV file is pretty large, smaller ones around 20MB and larger ones exceeding hundreds of megabytes. The purpose of this library is to facilitate rapid parsing and creation of these files.
To install this library, use the following command:
# pnpm
pnpm add @iptv/xmltv
# npm
npm install @iptv/xmltv
# yarn
yarn add @iptv/xmltv
To use this library in your project, first import the functions you need:
import { parseXmltv, writeXmltv } from '@iptv/xmltv';
Then, you can parse an XMLTV file and receive back an Xmltv object:
Examples will be based on this XMLTV file, it can be found in the tests/fixtures directory.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tv SYSTEM "xmltv.dtd">
<tv date="20220401000000 +0000" source-info-name="example" source-info-url="example.com" source-data-url="example.com/a" generator-info-name="Example Generator"
generator-info-url="example generator url">
<channel id="channel_one">
<display-name lang="en">Channel One</display-name>
<icon src="https://example.com/channel_one_icon.jpg" width="100" height="100" />
<url system="example">https://example.com/channel_one</url>
<url system="other_system">https://example.com/channel_one_alternate</url>
</channel>
<channel id="channel_two">
<display-name>Channel Two: Minimum valid channel</display-name>
</channel>
<programme start="20220331180000 +0000" stop="20220331190000 +0000" channel="channel_one"
pdc-start="20220331180000 +0000" vps-start="20220331180000 +0000" showview="12345"
videoplus="67890" clumpidx="0/1">
<title lang="en">Programme One</title>
<sub-title lang="en">Pilot</sub-title>
<desc lang="en">This programme entry showcases all possible features of the DTD</desc>
<credits>
<director>Samuel Jones</director>
<actor role="Walter Johnson">David Thompson</actor>
<actor role="Karl James" guest="yes"> Ryan Lee <image type="person">https://www.example.com/xxx.jpg</image>
<url system="moviedb">https://www.example.com/person/204</url>
</actor>
<writer>Samuel Jones</writer>
<adapter>William Brown</adapter>
<producer>Emily Davis</producer>
<composer>Max Wright</composer>
<editor>Nora Peterson</editor>
<presenter>Amanda Johnson</presenter>
<commentator>James Wilson</commentator>
<guest>Lucas Martin</guest>
<guest>Emily Parker</guest>
<guest>Oliver Nelson</guest>
</credits>
<date>20220401000000 +0000</date>
<category lang="en">Crime</category>
<category lang="en">Drama</category>
<keyword lang="en">methamphetamine</keyword>
<keyword lang="en">cancer</keyword>
<language>English</language>
<orig-language lang="en">French</orig-language>
<length units="minutes">60</length>
<icon src="https://example.com/programme_one_icon.jpg" width="100" height="100" />
<url system="tvdb">https://example.com/programme_one</url>
<url> https://example.com/programme_one_2</url>
<country>US</country>
<episode-num system="onscreen">S01E01</episode-num>
<episode-num system="xmltv_ns">1.1.</episode-num>
<video>
<present>yes</present>
<colour>no</colour>
<aspect>16:9</aspect>
<quality>HDTV</quality>
</video>
<audio>
<present>yes</present>
<stereo>Dolby Digital</stereo>
</audio>
<previously-shown start="20220331180000 +0000" channel="channel_two" />
<premiere>First time on British TV</premiere>
<last-chance lang="en">Last time on this channel</last-chance>
<new />
<subtitles type="teletext">
<language>English</language>
</subtitles>
<subtitles type="onscreen">
<language lang="en">Spanish</language>
</subtitles>
<rating system="BBFC">
<value>15</value>
<icon src="15_symbol.png" />
</rating>
<star-rating system="TV Guide">
<value> 4/5</value>
<icon src="stars.png" />
</star-rating>
<review type="text" source="Rotten Tomatoes" reviewer="Joe Bloggs" lang="en">This is a fantastic show!</review>
<review type="url" source="Rotten Tomatoes" reviewer="Joe Bloggs" lang="en">https://example.com/programme_one_review</review>
<image type="poster" size="1" orient="P" system="tvdb">https://tvdb.com/programme_one_poster_1.jpg</image>
<image type="backdrop" size="3" orient="L" system="tvdb"> https://tvdb.com/programme_one_backdrop_3.jpg</image>
</programme>
<programme start="20220331180000 +0000"
channel="channel_one">
<title>Programme Two: The minimum valid programme</title>
</programme>
</tv>
const xml = `...`; // XMLTV file contents
const xmltv: Xmltv = parseXmltv(xml);
const programmes: XmltvProgramme[] = xmltv.programmes;
const channels: XmltvChannel[] = xmltv.channels;
{
channels: [
{
displayName: [
{
_value: "Channel One",
lang: "en",
},
],
icon: [
{
height: 100,
src: "https://example.com/channel_one_icon.jpg",
width: 100,
},
],
id: "channel_one",
url: [
{
_value: "https://example.com/channel_one",
system: "example",
},
{
_value: "https://example.com/channel_one_alternate",
system: "other_system",
},
],
},
{
displayName: [
{
_value: "Channel Two: Minimum valid channel",
},
],
id: "channel_two",
},
],
date: new Date("2022-04-01T00:00:00.000Z"),
generatorInfoName: "Example Generator",
generatorInfoUrl: "example generator url",
programmes: [
{
audio: {
present: true,
stereo: "Dolby Digital",
},
category: [
{
_value: "Crime",
lang: "en",
},
{
_value: "Drama",
lang: "en",
},
],
channel: "channel_one",
clumpidx: "0/1",
country: {
_value: "US",
},
credits: {
actor: [
{
_value: "David Thompson",
role: "Walter Johnson",
},
{
_value: "Ryan Lee",
guest: true,
image: [
{
_value: "https://www.example.com/xxx.jpg",
type: "person",
},
],
role: "Karl James",
url: [
{
_value: "https://www.example.com/person/204",
system: "moviedb",
},
],
},
],
adapter: [
{
_value: "William Brown",
},
],
commentator: [
{
_value: "James Wilson",
},
],
composer: [
{
_value: "Max Wright",
},
],
director: [
{
_value: "Samuel Jones",
},
],
editor: [
{
_value: "Nora Peterson",
},
],
guest: [
{
_value: "Lucas Martin",
},
{
_value: "Emily Parker",
},
{
_value: "Oliver Nelson",
},
],
presenter: [
{
_value: "Amanda Johnson",
},
],
producer: [
{
_value: "Emily Davis",
},
],
writer: [
{
_value: "Samuel Jones",
},
],
},
date: new Date("2022-04-01T00:00:00.000Z"),
desc: [
{
_value:
"This programme entry showcases all possible features of the DTD",
lang: "en",
},
],
episodeNum: [
{
_value: "S01E01",
system: "onscreen",
},
{
_value: "1.1.",
system: "xmltv_ns",
},
],
icon: [
{
height: 100,
src: "https://example.com/programme_one_icon.jpg",
width: 100,
},
],
image: [
{
_value: "https://tvdb.com/programme_one_poster_1.jpg",
orient: "P",
size: 1,
system: "tvdb",
type: "poster",
},
{
_value: "https://tvdb.com/programme_one_backdrop_3.jpg",
orient: "L",
size: 3,
system: "tvdb",
type: "backdrop",
},
],
keyword: [
{
_value: "methamphetamine",
lang: "en",
},
{
_value: "cancer",
lang: "en",
},
],
language: {
_value: "English",
},
lastChance: {
_value: "Last time on this channel",
lang: "en",
},
length: {
_value: 60,
units: "minutes",
},
new: true,
origLanguage: {
_value: "French",
lang: "en",
},
pdcStart: new Date("2022-03-31T18:00:00.000Z"),
premiere: {
_value: "First time on British TV",
},
previouslyShown: {
channel: "channel_two",
start: new Date("2022-03-31T18:00:00.000Z"),
},
rating: [
{
icon: [
{
src: "15_symbol.png",
},
],
system: "BBFC",
value: "15",
},
],
review: [
{
_value: "This is a fantastic show!",
lang: "en",
reviewer: "Joe Bloggs",
source: "Rotten Tomatoes",
type: "text",
},
{
_value: "https://example.com/programme_one_review",
lang: "en",
reviewer: "Joe Bloggs",
source: "Rotten Tomatoes",
type: "url",
},
],
showview: "12345",
starRating: [
{
icon: [
{
src: "stars.png",
},
],
system: "TV Guide",
value: "4/5",
},
],
start: new Date("2022-03-31T18:00:00.000Z"),
stop: new Date("2022-03-31T19:00:00.000Z"),
subTitle: [
{
_value: "Pilot",
lang: "en",
},
],
subtitles: [
{
language: {
_value: "English",
},
type: "teletext",
},
{
language: {
_value: "Spanish",
lang: "en",
},
type: "onscreen",
},
],
title: [
{
_value: "Programme One",
lang: "en",
},
],
url: [
{
_value: "https://example.com/programme_one",
system: "tvdb",
},
{
_value: "https://example.com/programme_one_2",
},
],
video: {
aspect: "16:9",
colour: false,
present: true,
quality: "HDTV",
},
videoplus: "67890",
vpsStart: new Date("2022-03-31T18:00:00.000Z"),
},
{
channel: "channel_one",
start: new Date("2022-03-31T18:00:00.000Z"),
title: [
{
_value: "Programme Two: The minimum valid programme",
},
],
},
],
sourceDataUrl: "example.com/a",
sourceInfoName: "example",
sourceInfoUrl: "example.com",
};
You can also generate an XMLTV file from an Xmltv tree:
const xml = writeXmltv(xmltvObject);
console.log(xml); // <tv>...</tv>
Or from a XMLTV DOM tree:
const xml = writeXmltv(xmltvDom, { fromDom: true });
console.log(xml); // <tv>...</tv>
If you want to go even faster you can parse the file into a DOM tree and then traverse it yourself:
const xml = '...'; // XMLTV file contents
const parsed = parseXmltv(xml, { asDom: true });
// or import { parser } from '@iptv/xmltv';
// const parsed = parser(xml);
// `parsed` is now a list of XmltvNode objects
// which can be traversed using the `children` property
// and attributes can be accessed using the `attributes` property
// (see the XmltvNode interface for more details)
// this is not the most efficient way to do this, but it's a good example
const programmes = parsed
.find((node) => {
// find the <tv> tag
return node.tagName === 'tv';
})
.children.filter((node) => {
// filter it's children for <programme> tags
return node.tagName === 'programme';
})
.map((programme) => {
// return a Programme object for each <programme> tag
return {
title: programme.children.find((t) => t.tagName === 'title').children[0],
start: new Date(programme.attributes.start),
stop: new Date(programme.attributes.stop),
channel: programme.attributes.channel,
};
});
This library has been optimized for parsing and generating XMLTV files quickly and efficiently. In my benchmarks, it performs better than other popular XMLTV libraries, including epg-parser and xmltv. It also beats fast-xml-parser.
The speed of this library is down to the implementation of the XML DOM tree parser tXml. To learn more about the optimisations made by tXml please read this blog post by @TobiasNickel.
| Library | Ops/sec | |
|---|---|---|
| @iptv/xmltv | 1,094,286 | |
| 🟢 | @iptv/xmltv (DOM only) | 1,246,439 |
| fast-xml-parser | 426,947 | |
| 🔴 | epg-parser | 96,468 |
| xmltv | 14,750 |
| Library | Ops/sec | |
|---|---|---|
| 🟢 | @iptv/xmltv | 2,920,103 |
| 🔴 | fast-xml-parser | 1,257,938 |
| Channels | 1 | 100 | 100 | 100 | 100 | 100 | 1 | |
|---|---|---|---|---|---|---|---|---|
| Programmes | 0 | 100 | 10,000 | 100,000 | 250,000 | 500,000 | 1,000,000 | |
| 🟢 | @iptv/xmltv | ~60 μs | ~1.24 ms | ~39 ms | ~342 ms | ~980 ms | ~2.15 s | ~5.37 s |
| 🔴 | epg-parser | ~362 μs | ~9.83 ms | ~256 ms | ~2.25 s | ~6.26 s | ~13 s | ~28 s |
I used nanobench to get the above times. Nanobench doesn't support the xmltv's event based architecture, so is not included in file parsing timings.
These benchmarks were run on a 2021 MacBook Pro M1 Max (10 cores) with 64 GB of RAM.
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.
My initial intent writing this library was to build a streaming parser, however I found the approach of tXml to be much faster than other methods I tried. There are some issues upstream I'd like to help fix before I can add streaming support but it is something I'd like to do.
A command line program that can be piped around to convert files from one format to another.
This library is designed to parse and generate XMLTV files only. It is not designed to be a generic XML parser or generator. If you need to parse generic XML files, you should use the excellent tXml library instead.
The shape of the Xmltv type is designed to match the XMLTV DTD as closely as possible. If you need a different object you can traverse the DOM tree yourself and convert it to your desired shape.
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 additional benchmarkspnpm run benchmark - Run the benchmarks with vitestpnpm run nanobench - Run additional benchmarksThis 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.
This library is licensed under the MIT License and is free to use in both open source and commercial projects.
The parser is based on the tXml library by @TobiasNickel.
0.1.5
53395c5 Thanks @evoactivity! - Fixes parsing of ISO date substrings (YYYY, YYYYMM, YYYYMMDD) which are valid for the programme <date> tagFAQs
An extremely fast XMLTV parser and generator for Node and the browser.
The npm package @iptv/xmltv receives a total of 360 weekly downloads. As such, @iptv/xmltv popularity was classified as not popular.
We found that @iptv/xmltv demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."