m3u8-parser

m3u8 parser

• Installation
• Usage
  • Constructor Options
  • Parsed Output
• Supported Tags
  • Basic Playlist Tags
  • Media Segment Tags
  • Media Playlist Tags
  • Main Playlist Tags
  • Experimental Tags
    • EXT-X-CUE-OUT
    • EXT-X-CUE-OUT-CONT
    • EXT-X-CUE-IN
  • Not Yet Supported
  • Custom Parsers
• Including the Parser
  • <script> Tag
  • Browserify
  • RequireJS/AMD
• License

Installation

1npm install --save m3u8-parser

The npm installation is preferred, but Bower works, too.

1bower install  --save m3u8-parser

Usage

1var manifest = [
2  '#EXTM3U',
3  '#EXT-X-VERSION:3',
4  '#EXT-X-TARGETDURATION:6',
5  '#EXT-X-MEDIA-SEQUENCE:0',
6  '#EXT-X-DISCONTINUITY-SEQUENCE:0',
7  '#EXTINF:6,',
8  '0.ts',
9  '#EXTINF:6,',
10  '1.ts',
11  '#EXT-X-PROGRAM-DATE-TIME:2019-02-14T02:14:00.106Z'
12  '#EXTINF:6,',
13  '2.ts',
14  '#EXT-X-ENDLIST'
15].join('\n');
16
17var parser = new m3u8Parser.Parser();
18
19parser.push(manifest);
20parser.end();
21
22var parsedManifest = parser.manifest;

Constructor Options

The constructor optinally takes an options object with two properties. These are needed when using #EXT-X-DEFINE for variable replacement.

1var parser = new m3u8Parser.Parser({
2  url: 'https://exmaple.com/video.m3u8?param_a=34&param_b=abc',
3  mainDefinitions: {
4    param_c: 'def'
5  }
6});

• options.url string The URL from which the playlist was fetched. If the request was redirected this should be the final URL. This is required if using QUERYSTRING rules with #EXT-X-DEFINE.
• options.mainDefinitions object An object of definitions from the main playlist. This is required if using IMPORT rules with #EXT-X-DEFINE.

Parsed Output

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

1Manifest {
2  allowCache: boolean,
3  endList: boolean,
4  mediaSequence: number,
5  dateRanges: [],
6  discontinuitySequence: number,
7  playlistType: string,
8  custom: {},
9  playlists: [
10    {
11      attributes: {},
12      Manifest
13    }
14  ],
15  mediaGroups: {
16    AUDIO: {
17      'GROUP-ID': {
18        NAME: {
19          default: boolean,
20          autoselect: boolean,
21          language: string,
22          uri: string,
23          instreamId: string,
24          characteristics: string,
25          forced: boolean
26        }
27      }
28    },
29    VIDEO: {},
30    'CLOSED-CAPTIONS': {},
31    SUBTITLES: {}
32  },
33  dateTimeString: string,
34  dateTimeObject: Date,
35  targetDuration: number,
36  totalDuration: number,
37  discontinuityStarts: [number],
38  segments: [
39    {
40      title: string,
41      byterange: {
42        length: number,
43        offset: number
44      },
45      duration: number,
46      programDateTime:  number,
47      attributes: {},
48      discontinuity: number,
49      uri: string,
50      timeline: number,
51      key: {
52        method: string,
53        uri: string,
54        iv: string
55      },
56      map: {
57        uri: string,
58        byterange: {
59          length: number,
60          offset: number
61        }
62      },
63      'cue-out': string,
64      'cue-out-cont': string,
65      'cue-in': string,
66      custom: {}
67    }
68  ]
69}

Supported Tags

Basic Playlist Tags

• EXTM3U
• EXT-X-VERSION

Media Segment Tags

• EXTINF
• EXT-X-BYTERANGE
• EXT-X-DISCONTINUITY
• EXT-X-KEY
• EXT-X-MAP
• EXT-X-PROGRAM-DATE-TIME
• EXT-X-DATERANGE
• EXT-X-I-FRAMES-ONLY

Media Playlist Tags

• EXT-X-TARGETDURATION
• EXT-X-MEDIA-SEQUENCE
• EXT-X-DISCONTINUITY-SEQUENCE
• EXT-X-ENDLIST
• EXT-X-PLAYLIST-TYPE
• EXT-X-START
• EXT-X-INDEPENDENT-SEGMENTS
• EXT-X-DEFINE

Main Playlist Tags

• EXT-X-MEDIA
• EXT-X-STREAM-INF
• EXT-X-I-FRAME-STREAM-INF
• EXT-X-CONTENT-STEERING
• EXT-X-DEFINE

Experimental Tags

m3u8-parser supports 3 additional Media Segment Tags not present in the HLS specification.

EXT-X-CUE-OUT

The EXT-X-CUE-OUT indicates that the following media segment is a break in main content and the start of interstitial content. Its format is:

#EXT-X-CUE-OUT:<duration>

where duration is a decimal-floating-point or decimal-integer number that specifies the total duration of the interstitial in seconds.

EXT-X-CUE-OUT-CONT

The EXT-X-CUE-OUT-CONT indicates that the following media segment is a part of interstitial content and not the main content. Every media segment following a media segment with an EXT-X-CUE-OUT tag SHOULD have an EXT-X-CUE-OUT-CONT applied to it until there is an EXT-X-CUE-IN tag. A media segment between a EXT-X-CUE-OUT and EXT-X-CUE-IN segment without a EXT-X-CUE-OUT-CONT is assumed to be part of the interstitial. Its format is:

#EXT-X-CUE-OUT-CONT:<n>/<duration>

where n is a decimal-floating-point or decimal-integer number that specifies the time in seconds the first sample of the media segment lies within the interstitial content and duration is a decimal-floating-point or decimal-integer number that specifies the total duration of the interstitial in seconds. n SHOULD be the sum of EXTINF durations for all preceding media segments up to the EXT-X-CUE-OUT tag for the current interstitial. duration SHOULD match the duration specified in the EXT-X-CUE-OUT tag for the current interstitial.'

EXT-X-CUE-IN

The EXT-X-CUE-IN indicates the end of the interstitial and the return of the main content. Its format is:

#EXT-X-CUE-IN

There SHOULD be a closing EXT-X-CUE-IN tag for every EXT-X-CUE-OUT tag. If a second EXT-X-CUE-OUT tag is encountered before an EXT-X-CUE-IN tag, the client MAY choose to ignore the EXT-X-CUE-OUT and treat it as part of the interstitial, or reject the playlist.

Example media playlist using EXT-X-CUE- tags.

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXTINF:10,
0.ts
#EXTINF:10,
1.ts
#EXT-X-CUE-OUT:30
#EXTINF:10,
2.ts
#EXT-X-CUE-OUT-CONT:10/30
#EXTINF:10,
3.ts
#EXT-X-CUE-OUT-CONT:20/30
#EXTINF:10,
4.ts
#EXT-X-CUE-IN
#EXTINF:10,
5.ts
#EXTINF:10,
6.ts
#EXT-X-ENDLIST

Not Yet Supported

• EXT-X-SESSION-DATA
• EXT-X-SESSION-KEY

Custom Parsers

To add a parser for a non-standard tag the parser object allows for the specification of custom tags using regular expressions. If a custom parser is specified, a custom object is appended to the manifest object.

1const manifest = [
2  '#EXTM3U',
3  '#EXT-X-VERSION:3',
4  '#VOD-FRAMERATE:29.97',
5  ''
6].join('\n');
7
8const parser = new m3u8Parser.Parser();
9parser.addParser({
10  expression: /^#VOD-FRAMERATE/,
11  customType: 'framerate'
12});
13
14parser.push(manifest);
15parser.end();
16parser.manifest.custom.framerate // "#VOD-FRAMERATE:29.97"

Custom parsers may additionally be provided a data parsing function that take a line and return a value.

1const manifest = [
2  '#EXTM3U',
3  '#EXT-X-VERSION:3',
4  '#VOD-FRAMERATE:29.97',
5  ''
6].join('\n');
7
8const parser = new m3u8Parser.Parser();
9parser.addParser({
10  expression: /^#VOD-FRAMERATE/,
11  customType: 'framerate',
12  dataParser: function(line) {
13    return parseFloat(line.split(':')[1]);
14  }
15});
16
17parser.push(manifest);
18parser.end();
19parser.manifest.custom.framerate // 29.97

Custom parsers may also extract data at a segment level by passing segment: true to the options object. Having a segment level custom parser will add a custom object to the segment data.

1const manifest = [
2    '#EXTM3U',
3    '#VOD-TIMING:1511816599485',
4    '#EXTINF:8.0,',
5    'ex1.ts',
6    ''
7  ].join('\n');
8
9const parser = new m3u8Parser.Parser();
10parser.addParser({
11  expression: /#VOD-TIMING/,
12  customType: 'vodTiming',
13  segment: true
14});
15
16parser.push(manifest);
17parser.end();
18parser.manifest.segments[0].custom.vodTiming // #VOD-TIMING:1511816599485

Custom parsers may also map a tag to another tag. The old tag will not be replaced and all matching registered mappers and parsers will be executed.

1const manifest = [
2    '#EXTM3U',
3    '#EXAMPLE',
4    '#EXTINF:8.0,',
5    'ex1.ts',
6    ''
7  ].join('\n');
8
9const parser = new m3u8Parser.Parser();
10parser.addTagMapper({
11  expression: /#EXAMPLE/,
12  map(line) {
13    return `#NEW-TAG:123`;
14  }
15});
16parser.addParser({
17  expression: /#NEW-TAG/,
18  customType: 'mappingExample',
19  segment: true
20});
21
22parser.push(manifest);
23parser.end();
24parser.manifest.segments[0].custom.mappingExample // #NEW-TAG:123

Including the Parser

To include m3u8-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.

1<script src="//path/to/m3u8-parser.min.js"></script>
2<script>
3  var parser = new m3u8Parser.Parser();
4</script>

Browserify

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

1var m3u8Parser = require('m3u8-parser');
2
3var parser = new m3u8Parser.Parser();

With ES6:

1import { Parser } from 'm3u8-parser';
2
3const parser = new Parser();

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:

1require(['m3u8-parser'], function(m3u8Parser) {
2  var parser = new m3u8Parser.Parser();
3});

License

Apache-2.0. Copyright (c) Brightcove, Inc