hp

hls-parser

A simple library to read/write HLS playlists

Showing:

Popularity

Downloads/wk

6.8K

GitHub Stars

97

Maintenance

Last Commit

5mos ago

Contributors

14

Package

Dependencies

0

Size (min+gzip)

13.9KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

Build Status Coverage Status Dependency Status Development Dependency Status Known Vulnerabilities npm Downloads XO code style

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

NPM

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
    })
  ]
});
// 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

NameTypeRequiredDefaultDescription
strstringYesN/AA 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

NameTypeRequiredDefaultDescription
objMasterPlaylist or MediaPlaylist (See Data format below.)YesN/AAn 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

NameTypeRequiredDefaultDescription
objObjectYes{}An object holding option values which will be used to overwrite the internal option values.
supported options
NameTypeDefaultDescription
strictModebooleanfalseIf true, the function throws an error when parse/stringify failed. If false, the function just logs the error and continues to run.
allowClosedCaptionsNonebooleanfalseIf 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
silentbooleanfalseIf 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 structure

Data

PropertyTypeRequiredDefaultDescription
typestringYesN/AEither playlist or segment or part}

Playlist (extends Data)

PropertyTypeRequiredDefaultDescription
isMasterPlaylistbooleanYesN/Atrue if this playlist is a master playlist
uristringNoundefinedPlaylist URL
versionnumberNoundefinedSee EXT-X-VERSION
independentSegmentsbooleanNofalseSee EXT-X-INDEPENDENT-SEGMENTS
startobject({offset: number, precise: boolean})NoundefinedSee EXT-X-START
sourcestringNoundefinedThe unprocessed text of the playlist

MasterPlaylist (extends Playlist)

PropertyTypeRequiredDefaultDescription
variants[Variant]No[]See EXT-X-STREAM-INF and EXT-X-I-FRAME-STREAM-INF
currentVariantnumberNoundefinedArray 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

PropertyTypeRequiredDefaultDescription
uristringYesN/AURI of the variant playlist
isIFrameOnlybooleanNoundefinedtrue if the variant is an I-frame media playlist. See EXT-X-I-FRAME-STREAM-INF
bandwidthnumberYesN/ASee BANDWIDTH attribute in EXT-X-STREAM-INF
averageBandwidthnumberNoundefinedSee AVERAGE-BANDWIDTH attribute in EXT-X-STREAM-INF
scorenumberNoundefinedSee SCORE attribute in EXT-X-STREAM-INF
codecsstringNoundefinedSee CODECS attribute in EXT-X-STREAM-INF
resolutionobject ({width: number, height: number})NoundefinedSee RESOLUTION attribute in EXT-X-STREAM-INF
frameRatenumberNoundefinedSee FRAME-RATE attribute in EXT-X-STREAM-INF
hdcpLevelstringNoundefinedSee HDCP-LEVEL attribute in EXT-X-STREAM-INF
allowedCpc[object ({format: string, cpcList: [string]})]NoundefinedSee ALLOWED-CPC attribute in EXT-X-STREAM-INF
videoRangestring {"SDR","HLG","PQ"}NoundefinedSee VIDEO-RANGE attribute in EXT-X-STREAM-INF
stableVariantIdstringNoundefinedSee 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
currentRenditionsobject ({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

PropertyTypeRequiredDefaultDescription
typestringYesN/ASee TYPE attribute in EXT-X-MEDIA
uristringNoundefinedSee URI attribute in EXT-X-MEDIA
groupIdstringYesN/ASee GROUP-ID attribute in EXT-X-MEDIA
languagestringNoundefinedSee LANGUAGE attribute in EXT-X-MEDIA
assocLanguagestringNoundefinedSee ASSOC-LANGUAGE attribute in EXT-X-MEDIA
namestringYesN/ASee NAME attribute in EXT-X-MEDIA
isDefaultbooleanNofalseSee DEFAULT attribute in EXT-X-MEDIA
autoselectbooleanNofalseSee AUTOSELECT attribute in EXT-X-MEDIA
forcedbooleanNofalseSee FORCED attribute in EXT-X-MEDIA
instreamIdstringNoundefinedSee INSTREAM-ID attribute in EXT-X-MEDIA
characteristicsstringNoundefinedSee CHARACTERISTICS attribute in EXT-X-MEDIA
channelsstringNoundefinedSee CHANNELS attribute in EXT-X-MEDIA

SessionData

PropertyTypeRequiredDefaultDescription
idstringYesN/ASee DATA-ID attribute in EXT-X-SESSION-DATA
valuestringNoundefinedSee VALUE attribute in EXT-X-SESSION-DATA
uristringNoundefinedSee URI attribute in EXT-X-SESSION-DATA
languagestringNoundefinedSee LANGUAGE attribute in EXT-X-SESSION-DATA

MediaPlaylist (extends Playlist)

PropertyTypeRequiredDefaultDescription
targetDurationnumberYesN/ASee EXT-X-TARGETDURATION
mediaSequenceBasenumberNo0See EXT-X-MEDIA-SEQUENCE
discontinuitySequenceBasenumberNo0See EXT-X-DISCONTINUITY-SEQUENCE
endlistbooleanNofalseSee EXT-X-ENDLIST
playlistTypestringNoundefinedSee EXT-X-PLAYLIST-TYPE
isIFramebooleanNoundefinedSee EXT-X-I-FRAMES-ONLY
segments[Segment]No[]A list of available segments
prefetchSegments[PrefetchSegment]No[]A list of available prefetch segments
lowLatencyCompatibilityobject ({canBlockReload: boolean, canSkipUntil: number, holdBack: number, partHoldBack: number})NoundefinedSee CAN-BLOCK-RELOAD, CAN-SKIP-UNTIL, HOLD-BACK, and PART-HOLD-BACK attributes in EXT-X-SERVER-CONTROL
partTargetDurationnumberNo*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
skipnumberNo0See EXT-X-SKIP

Segment (extends Data)

PropertyTypeRequiredDefaultDescription
uristringYes*N/AURI of the media segment. *Not required if the segment contains EXT-X-PRELOAD-HINT tag
durationnumberYes*N/ASee EXTINF *Not required if the segment contains EXT-X-PRELOAD-HINT tag
titlestringNoundefinedSee EXTINF
byterangeobject ({length: number, offset: number})NoundefinedSee EXT-X-BYTERANGE
discontinuitybooleanNoundefinedSee EXT-X-DISCONTINUITY
mediaSequenceNumbernumberNo0See the description about 'Media Sequence Number' in 3. Media Segments
discontinuitySequencenumberNo0See the description about 'Discontinuity Sequence Number' in 6.2.1. General Server Responsibilities
keyKeyNoundefinedSee EXT-X-KEY
mapMediaInitializationSectionNoundefinedSee EXT-X-MAP
programDateTimeDateNoundefinedSee EXT-X-PROGRAM-DATE-TIME
dateRangeDateRangeNoundefinedSee 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)

PropertyTypeRequiredDefaultDescription
hintbooleanNofalsetrue indicates a hinted resource (TYPE=PART) See EXT-X-PRELOAD-HINT
uristringYesN/ASee URI attribute in EXT-X-PART
durationnumberYes*N/ASee DURATION attribute in EXT-X-PART *Not required if hint is true
independentbooleanNoundefinedSee INDEPENDENT attribute in EXT-X-PART
byterangeobject ({length: number, offset: number})NoundefinedSee BYTERANGE attribute in EXT-X-PART
gapbooleanNoundefinedSee GAP attribute in EXT-X-PART

PrefetchSegment (extends Data)

PropertyTypeRequiredDefaultDescription
uristringYesN/ASee value of EXT-X-PREFETCH
discontinuitybooleanNoundefinedSee EXT-X-PREFETCH-DISCONTINUITY
mediaSequenceNumbernumberNo0See the description about 'Media Sequence Number' in 3. Media Segments
discontinuitySequencenumberNo0See the description about 'Discontinuity Sequence Number' in 6.2.1. General Server Responsibilities

Key

PropertyTypeRequiredDefaultDescription
methodstringYesN/ASee METHOD attribute in EXT-X-KEY
uristringNoundefinedSee URI attribute in EXT-X-KEY
ivBuffer(length=16)NoundefinedSee IV attribute in EXT-X-KEY
formatstringNoundefinedSee KEYFORMAT attribute in EXT-X-KEY
formatVersionstringNoundefinedSee KEYFORMATVERSIONS attribute in EXT-X-KEY

MediaInitializationSection

PropertyTypeRequiredDefaultDescription
hintbooleanNofalsetrue indicates a hinted resource (TYPE=MAP) See EXT-X-PRELOAD-HINT
uristringYesN/ASee URI attribute in EXT-X-MAP
byterangeobject ({length: number, offset: number})NoundefinedSee BYTERANGE attribute in EXT-X-MAP

DateRange

PropertyTypeRequiredDefaultDescription
idstringYesN/ASee ID attribute in EXT-X-DATERANGE
classIdstringNoundefinedSee CLASS attribute in EXT-X-DATERANGE
startDateNoundefinedSee START-DATE attribute in EXT-X-DATERANGE
endDateNoundefinedSee END-DATE attribute in EXT-X-DATERANGE
durationnumberNoundefinedSee DURATION attribute in EXT-X-DATERANGE
plannedDurationnumberNoundefinedSee PLANNED-DURATION attribute in EXT-X-DATERANGE
endOnNextbooleanNoundefinedSee END-ON-NEXT attribute in EXT-X-DATERANGE
attributesobjectNo{}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.

PropertyTypeRequiredDefaultDescription
typestringYesN/A{'OUT', 'IN', 'RAW'}
durationnumberNoundefinedRequired if the type is 'OUT'
tagNamestringNoundefinedHolds the tag name if any unsupported tag are found. Required if the type is 'RAW'
valuestringNoundefinedHolds a raw (string) value for the unsupported tag.

RenditionReport

PropertyTypeRequiredDefaultDescription
uristringYesN/ASee URI attribute in EXT-X-RENDITION-REPORT
lastMSNnumberNoundefinedSee LAST-MSN attribute in EXT-X-RENDITION-REPORT
lastPartnumberNoundefinedSee LAST-PART attribute in EXT-X-RENDITION-REPORT

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100