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

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

$3

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

$3

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

$3

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

$3

Retrieves the current option values

#### return value
A cloned object containing the current option values

$3

An object that holds all the classes described below.

Data format

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

!data structure

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3


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