hls-parser

Provides synchronous functions to read/write HLS playlists (conforms to the HLS spec rev.23, the Apple Low-Latency Spec rev. 2020/02/05, and HLS.js's Low-Latency spec)

Usage

import * as HLS from '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
    })
  ]
});
// Convert the object into a text
HLS.stringify(obj);
/*
#EXTM3U
#EXT-X-TARGETDURATION:9
#EXT-X-PLAYLIST-TYPE:VOD
#EXTINF:9,
low/1.m3u8
*/

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.setOptions(obj)`

Updates the option values

params

Name	Type	Required	Default	Description
obj	Object	Yes	{}	An object holding option values which will be used to overwrite the internal option values.

supported options

Name	Type	Default	Description
`strictMode`	boolean	false	If true, the function throws an error when `parse`/`stringify` failed. If false, the function just logs the error and continues to run.
`allowClosedCaptionsNone`	boolean	false	If true, `CLOSED-CAPTIONS` attribute on the `EXT-X-STREAM-INF` tag will be set to the enumerated-string value NONE when there are no closed-captions. See CLOSED-CAPTIONS
`silent`	boolean	false	If true, `console.error` will be suppressed.

`HLS.getOptions()`

Retrieves the current option values

return value

A cloned object containing the current option values

`HLS.types`

An object that holds all the classes described below.

Data format

The following diagram describes the structure of the object returned by parse() method.

Additionally, this data structure has been expanded upon to provide more accurate domain modeling and convenient business logic. These extra classes and relationships are ignored during parsing and serialization.

`Data`

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

`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
`score`	number	No	undefined	See SCORE 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
`allowedCpc`	[object ({format: string, cpcList: [string]})]	No	undefined	See ALLOWED-CPC attribute in EXT-X-STREAM-INF
`videoRange`	string {"SDR","HLG","PQ"}	No	undefined	See VIDEO-RANGE attribute in EXT-X-STREAM-INF
`stableVariantId`	string	No	undefined	See STABLE-VARIANT-ID 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
`playlist`	`MediaPlaylist`	No	undefined	A reference to the `MediaPlaylist` object referenced by the `uri`. This is not populated during parsing or referenced during serialization. It is for convenience and must be initialized separately.

`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
`playlist`	`MediaPlaylist`	No	undefined	A reference to the `MediaPlaylist` object referenced by the `uri`. This is not populated during parsing or referenced during serialization. It is for convenience and must be initialized separately.

`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
`prefetchSegments`	[`PrefetchSegment`]	No	[]	A list of available prefetch segments
`lowLatencyCompatibility`	object ({canBlockReload: boolean, canSkipUntil: number, holdBack: number, partHoldBack: number})	No	undefined	See `CAN-BLOCK-RELOAD`, `CAN-SKIP-UNTIL`, `HOLD-BACK`, and `PART-HOLD-BACK` attributes in EXT-X-SERVER-CONTROL
`partTargetDuration`	number	No*	undefined	*Required if the playlist contains one or more `EXT-X-PART` tags. See EXT-X-PART-INF
`renditionReports`	[`RenditionReport`]	No	[]	Update status of the associated renditions
`skip`	number	No	0	See EXT-X-SKIP

`Segment` (extends `Data`)

Property	Type	Required	Default	Description
`uri`	string	Yes*	N/A	URI of the media segment. *Not required if the segment contains `EXT-X-PRELOAD-HINT` tag
`duration`	number	Yes*	N/A	See EXTINF *Not required if the segment contains `EXT-X-PRELOAD-HINT` tag
`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	No	0	See the description about 'Media Sequence Number' in 3. Media Segments
`discontinuitySequence`	number	No	0	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
`markers`	[`SpliceInfo`]	No	[]	SCTE-35 messages associated with this segment
`parts`	[`PartialSegment`]	No	[]	Partial Segments that constitute this segment

`PartialSegment` (extends `Data`)

Property	Type	Required	Default	Description
`hint`	boolean	No	false	`true` indicates a hinted resource (`TYPE=PART`) See EXT-X-PRELOAD-HINT
`uri`	string	Yes	N/A	See `URI` attribute in EXT-X-PART
`duration`	number	Yes*	N/A	See `DURATION` attribute in EXT-X-PART *Not required if `hint` is `true`
`independent`	boolean	No	undefined	See `INDEPENDENT` attribute in EXT-X-PART
`byterange`	object ({length: number, offset: number})	No	undefined	See `BYTERANGE` attribute in EXT-X-PART
`gap`	boolean	No	undefined	See `GAP` attribute in EXT-X-PART

`PrefetchSegment` (extends `Data`)

Property	Type	Required	Default	Description
`uri`	string	Yes	N/A	See value of EXT-X-PREFETCH
`discontinuity`	boolean	No	undefined	See EXT-X-PREFETCH-DISCONTINUITY
`mediaSequenceNumber`	number	No	0	See the description about 'Media Sequence Number' in 3. Media Segments
`discontinuitySequence`	number	No	0	See the description about 'Discontinuity Sequence Number' in 6.2.1. General Server Responsibilities

`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
`hint`	boolean	No	false	`true` indicates a hinted resource (`TYPE=MAP`) See EXT-X-PRELOAD-HINT
`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`	No	undefined	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

`SpliceInfo`

Only EXT-X-CUE-OUT and EXT-X-CUE-IN tags are supported. Other SCTE-35-related tags are stored as raw (string) values.

Property	Type	Required	Default	Description
`type`	string	Yes	N/A	{'OUT', 'IN', 'RAW'}
`duration`	number	No	undefined	Required if the `type` is 'OUT'
`tagName`	string	No	undefined	Holds the tag name if any unsupported tag are found. Required if the `type` is 'RAW'
`value`	string	No	undefined	Holds a raw (string) value for the unsupported tag.

`RenditionReport`

Property	Type	Required	Default	Description
`uri`	string	Yes	N/A	See `URI` attribute in EXT-X-RENDITION-REPORT
`lastMSN`	number	No	undefined	See `LAST-MSN` attribute in EXT-X-RENDITION-REPORT
`lastPart`	number	No	undefined	See `LAST-PART` attribute in EXT-X-RENDITION-REPORT

`RedundantStream`

Property	Type	Required	Default	Description
`root`	`MasterPlaylist`	No	undefined	The root playlist, derived from the available `sides` playlists
`sides`	[`MasterPlaylist`]	Yes	[]	The redundant `MasterPlaylist`s used to generate the `root` playlist

flocasts/hls-parser

hls-parser

Usage

API

HLS.parse(str)

params

return value

HLS.stringify(obj)

params

return value

HLS.setOptions(obj)

params

supported options

HLS.getOptions()

return value

HLS.types

Data format

Data

Playlist (extends Data)

MasterPlaylist (extends Playlist)

Variant

Rendition

SessionData

MediaPlaylist (extends Playlist)

Segment (extends Data)

PartialSegment (extends Data)

PrefetchSegment (extends Data)

Key

MediaInitializationSection

DateRange

SpliceInfo

RenditionReport

RedundantStream

`HLS.parse(str)`

`HLS.stringify(obj)`

`HLS.setOptions(obj)`

`HLS.getOptions()`

`HLS.types`

`Data`

`Playlist` (extends `Data`)

`MasterPlaylist` (extends `Playlist`)

`Variant`

`Rendition`

`SessionData`

`MediaPlaylist` (extends `Playlist`)

`Segment` (extends `Data`)

`PartialSegment` (extends `Data`)

`PrefetchSegment` (extends `Data`)

`Key`

`MediaInitializationSection`

`DateRange`

`SpliceInfo`

`RenditionReport`

`RedundantStream`