mpd-parser

What is mpd-parser?

The mpd-parser npm package is used to parse MPEG-DASH (Dynamic Adaptive Streaming over HTTP) MPD (Media Presentation Description) files. It provides tools to read and interpret the structure and content of MPD files, which are XML-based manifests that describe media content and how it should be streamed.

What are mpd-parser's main functionalities?

Parsing MPD files

This feature allows you to parse an MPD XML string into a JavaScript object. The code sample demonstrates how to use the `mpd-parser` package to parse a simple MPD XML string and log the resulting JavaScript object.

const mpdParser = require('mpd-parser');
const mpdXml = '<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" type="static" mediaPresentationDuration="PT0H4M40.414S" minBufferTime="PT1.500S"><Period><AdaptationSet mimeType="video/mp4" codecs="avc1.4d401e" width="640" height="360" frameRate="30" startWithSAP="1" segmentAlignment="true"><Representation id="1" bandwidth="500000"><BaseURL>video/</BaseURL><SegmentList timescale="1000" duration="2000"><SegmentURL media="segment1.m4s" /><SegmentURL media="segment2.m4s" /></SegmentList></Representation></AdaptationSet></Period></MPD>';
const parsedManifest = mpdParser.parse(mpdXml);
console.log(parsedManifest);

Generating MPD files

This feature allows you to generate an MPD XML string from a JavaScript object. The code sample demonstrates how to use the `mpd-parser` package to convert a JavaScript object representing an MPD manifest into an XML string.

const mpdParser = require('mpd-parser');
const manifestObject = {
  type: 'static',
  mediaPresentationDuration: 'PT0H4M40.414S',
  minBufferTime: 'PT1.500S',
  periods: [
    {
      adaptationSets: [
        {
          mimeType: 'video/mp4',
          codecs: 'avc1.4d401e',
          width: 640,
          height: 360,
          frameRate: 30,
          startWithSAP: 1,
          segmentAlignment: true,
          representations: [
            {
              id: '1',
              bandwidth: 500000,
              baseURL: 'video/',
              segmentList: {
                timescale: 1000,
                duration: 2000,
                segmentURLs: [
                  { media: 'segment1.m4s' },
                  { media: 'segment2.m4s' }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
};
const mpdXml = mpdParser.generate(manifestObject);
console.log(mpdXml);

Other packages similar to mpd-parser

dashjs

Dash.js is a reference client implementation for the playback of MPEG-DASH via JavaScript and compliant browsers. It provides a more comprehensive solution for DASH playback, including features like adaptive bitrate streaming, DRM support, and more. Unlike mpd-parser, which focuses on parsing and generating MPD files, dash.js is designed for full playback functionality.

shaka-player

Shaka Player is an open-source JavaScript library for adaptive video streaming. It supports DASH and HLS and includes features like offline storage, DRM, and live streaming. Shaka Player is more feature-rich compared to mpd-parser, which is focused solely on MPD parsing and generation.

README

mpd-parser

mpd parser

Table of Contents

• Installation
• Usage
  • Parsed Output
• Including the Parser
  • <script> Tag
  • Browserify
  • RequireJS/AMD
• License

Installation

npm install --save mpd-parser

Usage

// get your manifest in whatever way works best
// for example, by reading the file from the filesystem in node
// or using fetch in a browser like so:

const manifestUri = 'https://example.com/dash.xml';
const res = await fetch(manifestUri);
const manifest = await res.text();

// A callback function to handle events like errors or warnings
const eventHandler = ({ type, message }) => console.log(`${type}: ${message}`);

var parsedManifest = mpdParser.parse(manifest, { manifestUri, eventHandler });

If dealing with a live stream, then on subsequent calls to parse, the previously parsed manifest object should be provided as an option to parse using the previousManifest option:

const newParsedManifest = mpdParser.parse(
  manifest,
  // parsedManifest comes from the prior example
  { manifestUri, previousManifest: parsedManifest }
);

Parsed Output

The parser ouputs a plain javascript object with the following structure:

Manifest {
  allowCache: boolean,
  contentSteering: {
    defaultServiceLocation: string,
    proxyServerURL: string,
    queryBeforeStart: boolean,
    serverURL: string
  },
  endList: boolean,
  mediaSequence: number,
  discontinuitySequence: number,
  playlistType: string,
  playlists: [
    {
      attributes: {},
      Manifest
    }
  ],
  mediaGroups: {
    AUDIO: {
      'GROUP-ID': {
        default: boolean,
        autoselect: boolean,
        language: string,
        uri: string,
        instreamId: string,
        characteristics: string,
        forced: boolean
      }
    },
    VIDEO: {},
    'CLOSED-CAPTIONS': {},
    SUBTITLES: {}
  },
  dateTimeString: string,
  dateTimeObject: Date,
  targetDuration: number,
  totalDuration: number,
  discontinuityStarts: [number],
  segments: [
    {
      byterange: {
        length: number,
        offset: number
      },
      duration: number,
      attributes: {},
      discontinuity: number,
      uri: string,
      timeline: number,
      key: {
        method: string,
        uri: string,
        iv: string
      },
      map: {
        uri: string,
        byterange: {
          length: number,
          offset: number
        }
      },
      'cue-out': string,
      'cue-out-cont': string,
      'cue-in': string
    }
  ]
}

Including the Parser

To include mpd-parser on your website or web application, use any of the following methods.

<script> Tag

This is the simplest case. Get the script in whatever way you prefer and include it on your page.

<script src="//path/to/mpd-parser.min.js"></script>
<script>
  var mpdParser = window['mpd-parser'];
  var parsedManifest = mpdParser.parse(manifest, { manifestUri });
</script>

Browserify

When using with Browserify, install mpd-parser via npm and require the parser as you would any other module.

var mpdParser = require('mpd-parser');

var parsedManifest = mpdParser.parse(manifest, { manifestUri });

With ES6:

import { parse } from 'mpd-parser';

const parsedManifest = parse(manifest, { manifestUri });

RequireJS/AMD

When using with RequireJS (or another AMD library), get the script in whatever way you prefer and require the parser as you normally would:

require(['mpd-parser'], function(mpdParser) {
  var parsedManifest = mpdParser.parse(manifest, { manifestUri });
});

License

Apache-2.0. Copyright (c) Brightcove, Inc

Changelog

1.3.1 (2024-10-09)

Bug Fixes

• ensure vtt tracks language is set correctly (#181) (b48d2a5)

<a name="1.3.0"></a>

Features

• parse mp4protection ContentProtection tags (#179) (0813929)

Chores

• update vhs-utils dependency (#178) (8c3ec26)

<a name="1.2.2"></a>