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)

Install

Usage

import { parse, types, stringify } from 'hls-parser';

// Parse the playlist
const playlist = 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} = types;
const obj = new MediaPlaylist({
  targetDuration: 9,
  playlistType: 'VOD',
  segments: [
    new Segment({
      uri: 'low/1.m3u8',
      duration: 9
    })
  ]
});
// Convert the object into a text
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, postProcess)

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 | | postProcess | PostProcess | No | undefined | A function to be called for each segment or variant to manipulate the output. |

PostProcess

| Property | Type | Required | Default | Description | | ---------------- | ------------- | -------- | ------- | ------------- | | segmentProcessor | (lines: string[], start: number, end: number, segment: Segment, i: number) => void | No | undefined | A function to manipulate the segment output. | | variantProcessor | (lines: string[], start: number, end: number, variant: Variant, i: number) => void | No | undefined | A function to manipulate the variant output. |

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

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 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 |

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 | | 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 | | gap | boolean | No | undefined | See EXT-X-GAP |

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 | ArrayBuffer(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 |