whoughton / hls-parser

A simple library to read/write HLS playlists

hls-parser

Provides synchronous functions to read/write HLS playlists (conforms to the HLS spec rev.23)

Install

Usage

const HLS = require('hls-parser'); // For node
// For browsers, just use dist/hls-parser.min.js defined as a UMD module.

// Parse the playlist
const playlist = HLS.parse(textData);
// You can access the playlist as a JS object
if (playlist.isMasterPlaylist) {
  // Master playlist
} else {
  // Media playlist
}
// Create a new playlist
const {MediaPlaylist, Segment} = HLS.types;
const obj = new MediaPlaylist({
  targetDuration: 9,
  playlistType: 'VOD',
  segments: [
    new Segment({
      uri: 'low/1.m3u8'
      duration: 9,
      mediaSequenceNumber: 0,
      discontinuitySequence: 0
    })
  ]
}));
// Convert the object into a text
const text = HLS.stringify(obj);

API

HLS.parse(str)

Converts a text playlist into a structured JS object

params

Name	Type	Required	Default	Description
str	string	Yes	N/A	A text data that conforms to the HLS playlist spec

return value

An instance of either MasterPlaylist or MediaPlaylist (See Data format below.)

HLS.stringify(obj)

Converts a JS object into a plain text playlist

params

Name	Type	Required	Default	Description
obj	MasterPlaylist or MediaPlaylist (See Data format below.)	Yes	N/A	An object returned by HLS.parse() or a manually created object

return value

A text data that conforms to the HLS playlist spec

HLS.types

An object that holds all the classes described below.

Data format

This section describes the structure of the object returned by parse() method.

Data

Property	Type	Required	Default	Description
type	string	Yes	N/A	Either playlist or segment}

Playlist (extends Data)

Property	Type	Required	Default	Description
isMasterPlaylist	boolean	Yes	N/A	true if this playlist is a master playlist
uri	string	No	undefined	Playlist URL
version	number	No	undefined	See EXT-X-VERSION
independentSegments	boolean	No	false	See EXT-X-INDEPENDENT-SEGMENTS
start	object({offset: number, precise: boolean})	No	undefined	See EXT-X-START
source	string	No	undefined	The unprocessed text of the playlist

MasterPlaylist (extends Playlist)

Property	Type	Required	Default	Description
variants	[Variant]	No	[]	See EXT-X-STREAM-INF and EXT-X-I-FRAME-STREAM-INF
currentVariant	number	No	undefined	Array index that points to the chosen item in variants
sessionDataList	[SessionData]	No	[]	See EXT-X-SESSION-DATA
sessionKeyList	[Key]	No	[]	See EXT-X-SESSION-KEY

Variant

Property	Type	Required	Default	Description
uri	string	Yes	N/A	URI of the variant playlist
isIFrameOnly	boolean	No	undefined	true if the variant is an I-frame media playlist. See EXT-X-I-FRAME-STREAM-INF
bandwidth	number	Yes	N/A	See BANDWIDTH attribute in EXT-X-STREAM-INF
averageBandwidth	number	No	undefined	See AVERAGE-BANDWIDTH attribute in EXT-X-STREAM-INF
codecs	string	No	undefined	See CODECS attribute in EXT-X-STREAM-INF
resolution	object ({width: number, height: number})	No	undefined	See RESOLUTION attribute in EXT-X-STREAM-INF
frameRate	number	No	undefined	See FRAME-RATE attribute in EXT-X-STREAM-INF
hdcpLevel	string	No	undefined	See HDCP-LEVEL attribute in EXT-X-STREAM-INF
audio	[Rendition(type='AUDIO')]	No	[]	See AUDIO attribute in EXT-X-STREAM-INF
video	[Rendition(type='VIDEO')]	No	[]	See VIDEO attribute in EXT-X-STREAM-INF
subtitles	[Rendition(type='SUBTITLES')]	No	[]	See SUBTITLES attribute in EXT-X-STREAM-INF
closedCaptions	[Rendition(type='CLOSED-CAPTIONS')]	No	[]	See CLOSED-CAPTIONS attribute in EXT-X-STREAM-INF
currentRenditions	object ({audio: number, video: number, subtitles: number, closedCaptions: number})	No	{}	A hash object that contains array indices that points to the chosen Rendition for each type

Rendition

Property	Type	Required	Default	Description
type	string	Yes	N/A	See TYPE attribute in EXT-X-MEDIA
uri	string	No	undefined	See URI attribute in EXT-X-MEDIA
groupId	string	Yes	N/A	See GROUP-ID attribute in EXT-X-MEDIA
language	string	No	undefined	See LANGUAGE attribute in EXT-X-MEDIA
assocLanguage	string	No	undefined	See ASSOC-LANGUAGE attribute in EXT-X-MEDIA
name	string	Yes	N/A	See NAME attribute in EXT-X-MEDIA
isDefault	boolean	No	false	See DEFAULT attribute in EXT-X-MEDIA
autoselect	boolean	No	false	See AUTOSELECT attribute in EXT-X-MEDIA
forced	boolean	No	false	See FORCED attribute in EXT-X-MEDIA
instreamId	string	No	undefined	See INSTREAM-ID attribute in EXT-X-MEDIA
characteristics	string	No	undefined	See CHARACTERISTICS attribute in EXT-X-MEDIA
channels	string	No	undefined	See CHANNELS attribute in EXT-X-MEDIA

SessionData

Property	Type	Required	Default	Description
id	string	Yes	N/A	See DATA-ID attribute in EXT-X-SESSION-DATA
value	string	No	undefined	See VALUE attribute in EXT-X-SESSION-DATA
uri	string	No	undefined	See URI attribute in EXT-X-SESSION-DATA
language	string	No	undefined	See LANGUAGE attribute in EXT-X-SESSION-DATA

MediaPlaylist (extends Playlist)

Property	Type	Required	Default	Description
targetDuration	number	Yes	N/A	See EXT-X-TARGETDURATION
mediaSequenceBase	number	No	0	See EXT-X-MEDIA-SEQUENCE
discontinuitySequenceBase	number	No	0	See EXT-X-DISCONTINUITY-SEQUENCE
endlist	boolean	No	false	See EXT-X-ENDLIST
playlistType	string	No	undefined	See EXT-X-PLAYLIST-TYPE
isIFrame	boolean	No	undefined	See EXT-X-I-FRAMES-ONLY
segments	[Segment]	No	[]	A list of available segments

Segment (extends Data)

Property	Type	Required	Default	Description
uri	string	Yes	N/A	URI of the media segment
duration	number	Yes	N/A	See EXTINF
title	string	No	undefined	See EXTINF
byterange	object ({length: number, offset: number})	No	undefined	See EXT-X-BYTERANGE
discontinuity	boolean	No	undefined	See EXT-X-DISCONTINUITY
mediaSequenceNumber	number	Yes	N/A	See the description about 'Media Sequence Number' in 3. Media Segments
discontinuitySequence	number	Yes	N/A	See the description about 'Discontinuity Sequence Number' in 6.2.1. General Server Responsibilities
key	Key	No	undefined	See EXT-X-KEY
map	MediaInitializationSection	No	undefined	See EXT-X-MAP
programDateTime	Date	No	undefined	See EXT-X-PROGRAM-DATE-TIME
dateRange	DateRange	No	undefined	See EXT-X-DATERANGE

Key

Property	Type	Required	Default	Description
method	string	Yes	N/A	See METHOD attribute in EXT-X-KEY
uri	string	No	undefined	See URI attribute in EXT-X-KEY
iv	Buffer(length=16)	No	undefined	See IV attribute in EXT-X-KEY
format	string	No	undefined	See KEYFORMAT attribute in EXT-X-KEY
formatVersion	string	No	undefined	See KEYFORMATVERSIONS attribute in EXT-X-KEY

MediaInitializationSection

Property	Type	Required	Default	Description
uri	string	Yes	N/A	See URI attribute in EXT-X-MAP
byterange	object ({length: number, offset: number})	No	undefined	See BYTERANGE attribute in EXT-X-MAP

DateRange

Property	Type	Required	Default	Description
id	string	Yes	N/A	See ID attribute in EXT-X-DATERANGE
classId	string	No	undefined	See CLASS attribute in EXT-X-DATERANGE
start	Date	Yes	N/A	See START-DATE attribute in EXT-X-DATERANGE
end	Date	No	undefined	See END-DATE attribute in EXT-X-DATERANGE
duration	number	No	undefined	See DURATION attribute in EXT-X-DATERANGE
plannedDuration	number	No	undefined	See PLANNED-DURATION attribute in EXT-X-DATERANGE
endOnNext	boolean	No	undefined	See END-ON-NEXT attribute in EXT-X-DATERANGE
attributes	object	No	{}	A hash object that holds SCTE35 attributes and user defined attributes. See SCTE35-* and X- attributes in EXT-X-DATERANGE