hls-parser
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/hls-parser package

    0.10.4 • Public • Published

    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

    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

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

    data structure

    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

    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

    Install

    npm i hls-parser

    DownloadsWeekly Downloads

    16,517

    Version

    0.10.4

    License

    MIT

    Unpacked Size

    548 kB

    Total Files

    13

    Last publish

    Collaborators

    • kuu