mediaxml

A general purpose module for working with XML that includes first class support for media manifests like ADI, mRSS, and SCTE-236.

Status

:warning: Under active development

Installation

$ npm install mediaxml

Usage

See the Usage Guide.

API

See the API Documentation.

Getting Started

The mediaxml module provides various implementations of XML formats for describing media packages, manifests, and feeds such as RSS, mRSS, ADI, and XMLTV.

Simple Example

In the example below, we parse a rss feed and enumerate all of the items in the document's channel.

const path = require('path')
const rss = require('mediaxml/rss')
const fs = require('fs')

const stream = fs.createReadStream('feed.rss')
const document = rss.createDocument(stream)

document.ready(() => {
  for (const item of document.channel.items) {
    console.log(item.title, item.description, item.link)
  }
})

Parsing Documents

Parsing a XML document using streams:

const { Parser } = require('mediaxml/parser')
const path = require('path')
const fs = require('fs')

const stream = fs.createReadStream('epg.xml')
const parser = new Parser()

stream.pipe(parser.createWriteStream()).on('finish', () => {
  console.log(parser.rootNode.sourceInfoUrl, parser.rootNode.sourceInfoName)
  console.log(parser.rootNode.children)
  parser.createReadStream().pipe(process.stdout)
})

Querying the Document Object Model

The query API is a powerful tool for querying the document object model produced by the parser using JSONata query syntax with a preprocessor syntax.

const { rootNode } = parser

// query root node decendent nodes with tag name "channel"
const channels = rootNode.query('[name="channel"]')

// query root node decendent nodes with a tag name "programme"
const programmes = rootNode.query('[name="programme"]')

// query all nodes in document with tag name "category"
// and select the text content (selected with the `:text` preprocessor function)
const categories = rootNode.query('**[name="category"]:text')

// query all nodes in document with tag name "programme"
// an `start` attribute (selected with the `attr()` preprocessor function)
// integer value greater than todays
const programmesInFuture = rootNode.query(`[
  name = "programmes" AND
  $int(attr(start)) > $int("${Date()}")
]`)

Creating Documents

const { createDocument } = require('mediaxml/document')

const document = createDocument({ nodeName: 'ADI' })
const metadata = document.createChild('Metadata')

metadata.createChild('AMS', {
  Asset_Class: 'package',
  Provider_ID: 'mylifetime.com',
  Provider: 'LIFETIMEMOVIECLUB_HD_UNIFIED',
  Product: 'SVOD',
  ...
})

metadata.createChild('App_Data', {
  App: 'SVOD',
  Name: 'Metadata_Spec_Version',
  Value: 'CableLabsVOD1'
})

metadata.createChild('App_Data', {
  App: 'SVOD',
  Name: 'Provider_Content_Tier',
  Value: 'LIFETIMEMOVIECLUB_HD_UNIFIED'
})

console.log(document.toString())
// <ADI>
//   <Metadata>
//     <AMS Asset_Class="package" Product="SVOD" Provider="LIFETIMEMOVIECLUB_HD_UNIFIED" Provider_ID="mylifetime.com" Verb="" Version_Major="3" Version_Minor="0" Creation_Date="2020-09-29" Description="AcquiredMovie_FriendsWhoKill_241958-package" Asset_ID="LFHP2419582007240000" Asset_Name="LFHP2419582007240000_AMVE_HD" />
//     <App_Data App="SVOD" Name="Metadata_Spec_Version" Value="CableLabsVOD1.1" />
//     <App_Data App="SVOD" Name="Provider_Content_Tier" Value="LIFETIMEMOVIECLUB_HD_UNIFIED" />
//   </Metadata>
// </ADI>

Query API

Querying XML document nodes:

const { createReadStream } = require('fs')
const { Document } = require('mediaxml/document')

const document = Document.from(createReadStream('file.xml'))
document.ready(() => {
  const textNodes = document.query('**[is text and is not empty]')
})

Query mRSS document objects:

const { createReadStream } = require('fs')
const { Document } = require('mediaxml/mrss')

cont document = Document.from(createReadStream('file.rss'))
document.ready(() => {
  const items = document.query('channel.items')
  const titles = items.query('title') // items is a `Fragment` with a `query()` function
  const urls = items.query('mediaContent.url[contains "mp4"]')
})

REPL

A REPL is provided for interactive querying of data in a XML tree.

The REPL can be started by simply running the mxml:

$ mxml
Welcome to the MediaXML 0.2.0 CLI
Please report bugs to https://github.com/mediaxml/mediaxml/issues
mxml(-)>

Importing a file can be done with the import keyword. This will import an XML file into the REPL context.

mxml(-)> import "./example/mrss/feed.xml"
mxml(-)> this
<rss>
  <channel>
    <title>Calm Meditation</title>
    <link>http://sample-firetv-web-app.s3-website-us-west-2.amazonaws.com</link>
    <language>en-us</language>
    ...

In the REPL, you can use the query syntax (JSONata with sugar) to query data.

mxml(-)> **[is node and text contains "amazonaws.com"] // searches all nodes with '**' wildcard operator
<link>http://sample-firetv-web-app.s3-website-us-west-2.amazonaws.com</link>
<link>http://sample-firetv-web-app.s3-website-us-west-2.amazonaws.com</link>
<url>http://sample-firetv-web-app.s3-website-us-west-2.amazonaws.com/images/calmmeditationlogo_small.png</url>
<link>http://sample-firetv-web-app.s3-website-us-west-2.amazonaws.com/shade/</link>
<guid isPermaLink="false">http://sample-firetv-web-app.s3-website-us-west-2.amazonaws.com/shade/</guid>
<link>http://sample-firetv-web-app.s3-website-us-west-2.amazonaws.com/spectators/</link>
<guid isPermaLink="false">http://sample-firetv-web-app.s3-website-us-west-2.amazonaws.com/spectators/</guid>

Documentation

See the Official Documentation for more information.

See Also

• Media RSS Specification
• CableLabs ADI 1 Specification
• CableLabs ADI 1 Various Mappings
• SCTE-236 - Content Metadata Specification
• XMLTV DTD
• XMLTV Format

Contributing

For more information, please refer to our CONTRIBUTING guide.

License

MIT