@amazon/vinyl-hls-parser 1.1.1 → 2.0.0

package/dist/types/current/index.d.ts

@@ -1,13 +1,14 @@
 /** Auto-generated from build scripts */
-export * from './types/VariantStream';
-export * from './types/SessionData';
-export * from './types/MediaPlaylist';
-export * from './types/MainPlaylist';
-export * from './types/HlsSegment';
-export * from './types/EncryptionKey';
-export * from './types/AlternativeRendition';
-export * from './parse/parseUtil';
-export * from './parse/parseMediaPlaylist';
-export * from './parse/parseMainPlaylist';
 export * from './parse/parseAttributes';
+export * from './parse/parseMainPlaylist';
+export * from './parse/parseMediaPlaylist';
+export * from './parse/parseUtil';
+export * from './types/AlternativeRendition';
+export * from './types/EncryptionKey';
+export * from './types/HlsDateRange';
+export * from './types/HlsMainPlaylist';
+export * from './types/HlsMediaPlaylist';
+export * from './types/HlsSegment';
+export * from './types/SessionData';
+export * from './types/VariantStream';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/current/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,mBAAmB,CAAA;AACjC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,2BAA2B,CAAA;AACzC,cAAc,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,mBAAmB,CAAA;AACjC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA"}

package/dist/types/current/index.js

@@ -1,12 +1,13 @@
 /** Auto-generated from build scripts */
-export * from './types/VariantStream';
-export * from './types/SessionData';
-export * from './types/MediaPlaylist';
-export * from './types/MainPlaylist';
-export * from './types/HlsSegment';
-export * from './types/EncryptionKey';
-export * from './types/AlternativeRendition';
-export * from './parse/parseUtil';
-export * from './parse/parseMediaPlaylist';
-export * from './parse/parseMainPlaylist';
 export * from './parse/parseAttributes';
+export * from './parse/parseMainPlaylist';
+export * from './parse/parseMediaPlaylist';
+export * from './parse/parseUtil';
+export * from './types/AlternativeRendition';
+export * from './types/EncryptionKey';
+export * from './types/HlsDateRange';
+export * from './types/HlsMainPlaylist';
+export * from './types/HlsMediaPlaylist';
+export * from './types/HlsSegment';
+export * from './types/SessionData';
+export * from './types/VariantStream';

package/dist/types/current/parse/parseMainPlaylist.d.ts

@@ -1,10 +1,15 @@
-import type { MainPlaylist } from '../types/MainPlaylist';
+import type { HlsMainPlaylist } from '../types/HlsMainPlaylist';
 /**
  * Parses an HLS master playlist from M3U8 text.
  *
  * @param text The raw M3U8 manifest string.
- * @returns A readonly MainPlaylist structure.
+ * @param queryParams Optional query parameters from the playlist's own URL,
+ *   used to resolve `#EXT-X-DEFINE:QUERYPARAM="name"` entries (RFC 8216
+ *   §4.4.5.1). Resolved values are exposed via {@link HlsMainPlaylist.defines} so
+ *   child media playlists can `IMPORT` them. Interstitial ad manifests (e.g.
+ *   AWS MediaTailor) carry session tokens this way.
+ * @returns A readonly HlsMainPlaylist structure.
  * @throws StringParseError if the manifest is malformed.
  */
-export declare function parseMainPlaylist(text: string): MainPlaylist;
+export declare function parseMainPlaylist(text: string, queryParams?: Readonly<Record<string, string>>): HlsMainPlaylist;
 //# sourceMappingURL=parseMainPlaylist.d.ts.map

package/dist/types/current/parse/parseMainPlaylist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseMainPlaylist.d.ts","sourceRoot":"","sources":["../../../../src/parse/parseMainPlaylist.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAYxD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAkH5D"}
+{"version":3,"file":"parseMainPlaylist.d.ts","sourceRoot":"","sources":["../../../../src/parse/parseMainPlaylist.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAa/D;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC7B,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC/C,eAAe,CAwIjB"}

package/dist/types/current/parse/parseMainPlaylist.js

@@ -2,8 +2,9 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { StringReader, ValidationError } from '@amazon/vinyl-util';
+import { StringReader, substitute, ValidationError } from '@amazon/vinyl-util';
 import { renditionTypeValidator } from '../types/AlternativeRendition';
+import { HLS_VARIABLE_PATTERN } from './parseMediaPlaylist';
 import { parseAttributes } from './parseAttributes';
 import { readLine, skipWhitespaceLine, addIfPresent } from './parseUtil';
 const EXTM3U = '#EXTM3U';
@@ -15,10 +16,15 @@ const EXT_X_DEFINE = '#EXT-X-DEFINE:';
  * Parses an HLS master playlist from M3U8 text.
  *
  * @param text The raw M3U8 manifest string.
- * @returns A readonly MainPlaylist structure.
+ * @param queryParams Optional query parameters from the playlist's own URL,
+ *   used to resolve `#EXT-X-DEFINE:QUERYPARAM="name"` entries (RFC 8216
+ *   §4.4.5.1). Resolved values are exposed via {@link HlsMainPlaylist.defines} so
+ *   child media playlists can `IMPORT` them. Interstitial ad manifests (e.g.
+ *   AWS MediaTailor) carry session tokens this way.
+ * @returns A readonly HlsMainPlaylist structure.
  * @throws StringParseError if the manifest is malformed.
  */
-export function parseMainPlaylist(text) {
+export function parseMainPlaylist(text, queryParams) {
     const reader = new StringReader(text);
     reader.white();
     if (!reader.stringIf(EXTM3U)) {
@@ -51,7 +57,7 @@ export function parseMainPlaylist(text) {
             }
             variants.push(addIfPresent({
                 bandwidth: Number(attrs['BANDWIDTH']),
-                uri,
+                uri: substituteHlsVariables(uri, defines),
                 ...(attrs['FRAME-RATE'] && {
                     frameRate: Number(attrs['FRAME-RATE']),
                 }),
@@ -71,6 +77,9 @@ export function parseMainPlaylist(text) {
             const attrs = parseAttributes(attrReader);
             const type = attrs['TYPE'];
             renditionTypeValidator.assert(type);
+            if (attrs['URI']) {
+                attrs['URI'] = substituteHlsVariables(attrs['URI'], defines);
+            }
             alternativeRenditions.push(addIfPresent({
                 type,
                 groupId: attrs['GROUP-ID'],
@@ -81,6 +90,15 @@ export function parseMainPlaylist(text) {
                 ...(attrs['AUTOSELECT'] && {
                     autoSelect: attrs['AUTOSELECT'] === 'YES',
                 }),
+                ...(attrs['FORCED'] && {
+                    forced: attrs['FORCED'] === 'YES',
+                }),
+                ...(attrs['CHARACTERISTICS'] && {
+                    characteristics: attrs['CHARACTERISTICS']
+                        .split(',')
+                        .map((c) => c.trim())
+                        .filter((c) => c.length > 0),
+                }),
             }, attrs, {
                 URI: 'uri',
                 LANGUAGE: 'language',
@@ -102,7 +120,17 @@ export function parseMainPlaylist(text) {
             const attrStr = trimmed.substring(EXT_X_DEFINE.length);
             const attrReader = new StringReader(attrStr);
             const attrs = parseAttributes(attrReader);
-            if (attrs['NAME'] && attrs['VALUE']) {
+            const queryParamName = attrs['QUERYPARAM'];
+            if (queryParamName) {
+                // Per RFC 8216 §4.4.5.1: QUERYPARAM copies the value from the
+                // named query parameter of the playlist's own URL. Ignore
+                // silently if the parameter is absent.
+                const queryValue = queryParams?.[queryParamName];
+                if (queryValue !== undefined) {
+                    defines[queryParamName] = queryValue;
+                }
+            }
+            else if (attrs['NAME'] && attrs['VALUE']) {
                 defines[attrs['NAME']] = attrs['VALUE'];
             }
         }
@@ -110,6 +138,16 @@ export function parseMainPlaylist(text) {
     }
     return { variants, alternativeRenditions, sessionData, defines };
 }
+/**
+ * Applies EXT-X-DEFINE variable substitution (per RFC 8216 §4.2) to a manifest
+ * value, replacing `{$NAME}` tokens with the values declared earlier in the
+ * playlist. Returns the input unchanged when no variables have been declared.
+ */
+function substituteHlsVariables(value, variables) {
+    if (!value || Object.keys(variables).length === 0)
+        return value;
+    return substitute(value, variables, HLS_VARIABLE_PATTERN);
+}
 /**
  * Parses a resolution string (e.g., "1920x1080") into width and height numbers.
  * Throws ValidationError for invalid formats per HLS spec.

package/dist/types/current/parse/parseMediaPlaylist.d.ts

@@ -1,12 +1,19 @@
-import type { MediaPlaylist } from '../types/MediaPlaylist';
+import type { HlsMediaPlaylist } from '../types/HlsMediaPlaylist';
 export declare const HLS_VARIABLE_PATTERN: RegExp;
 /**
  * Parses an HLS media playlist from M3U8 text.
  *
  * @param text The raw M3U8 manifest string.
- * @param variables Optional variable definitions from the master playlist's #EXT-X-DEFINE tags.
- * @returns A readonly MediaPlaylist structure.
+ * @param variables Optional variable definitions from the parent multivariant
+ *   playlist's #EXT-X-DEFINE tags. Media-playlist `#EXT-X-DEFINE:IMPORT="name"`
+ *   entries resolve against this map. Local `#EXT-X-DEFINE:NAME=,VALUE=`
+ *   entries are also supported and take precedence.
+ * @param queryParams Optional query parameters from the playlist's own URL,
+ *   used to resolve `#EXT-X-DEFINE:QUERYPARAM="name"` entries (RFC 8216
+ *   §4.4.5.1). Interstitial ad manifests (e.g. AWS MediaTailor) commonly carry
+ *   session tokens this way and reference them as `{$name}` in child URIs.
+ * @returns A readonly HlsMediaPlaylist structure.
  * @throws StringParseError if the manifest is malformed.
  */
-export declare function parseMediaPlaylist(text: string, variables?: Readonly<Record<string, string>>): MediaPlaylist;
+export declare function parseMediaPlaylist(text: string, variables?: Readonly<Record<string, string>>, queryParams?: Readonly<Record<string, string>>): HlsMediaPlaylist;
 //# sourceMappingURL=parseMediaPlaylist.d.ts.map

package/dist/types/current/parse/parseMediaPlaylist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseMediaPlaylist.d.ts","sourceRoot":"","sources":["../../../../src/parse/parseMediaPlaylist.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAI1D,eAAO,MAAM,oBAAoB,QAAkB,CAAA;AAenD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC7C,aAAa,CA+Jf"}
+{"version":3,"file":"parseMediaPlaylist.d.ts","sourceRoot":"","sources":["../../../../src/parse/parseMediaPlaylist.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAQjE,eAAO,MAAM,oBAAoB,QAAmB,CAAA;AAiBpD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC5C,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC/C,gBAAgB,CAiMlB"}

package/dist/types/current/parse/parseMediaPlaylist.js

@@ -6,7 +6,11 @@ import { StringReader, substitute } from '@amazon/vinyl-util';
 import { encryptionMethodValidator } from '../types/EncryptionKey';
 import { parseAttributes } from './parseAttributes';
 import { readLine, skipWhitespaceLine, addIfPresent } from './parseUtil';
-export const HLS_VARIABLE_PATTERN = /\{\$([^}]+)}/g;
+// The variable-name class excludes `{` (and `}`) so a match attempt can't
+// scan across token boundaries. With `[^}]` a crafted value such as
+// `{$|{$|{$|…` makes replace() do polynomial work (ReDoS); `[^{}]` keeps it
+// linear, and HLS variable names never contain `{`/`}`.
+export const HLS_VARIABLE_PATTERN = /\{\$([^{}]+)}/g;
 const EXTM3U = '#EXTM3U';
 const EXTINF = '#EXTINF:';
 const EXT_X_TARGETDURATION = '#EXT-X-TARGETDURATION:';
@@ -19,15 +23,28 @@ const EXT_X_BYTERANGE = '#EXT-X-BYTERANGE:';
 const EXT_X_DISCONTINUITY = '#EXT-X-DISCONTINUITY';
 const EXT_X_PROGRAM_DATE_TIME = '#EXT-X-PROGRAM-DATE-TIME:';
 const EXT_X_MAP = '#EXT-X-MAP:';
+const EXT_X_DEFINE = '#EXT-X-DEFINE:';
+const EXT_X_DATERANGE = '#EXT-X-DATERANGE:';
 /**
  * Parses an HLS media playlist from M3U8 text.
  *
  * @param text The raw M3U8 manifest string.
- * @param variables Optional variable definitions from the master playlist's #EXT-X-DEFINE tags.
- * @returns A readonly MediaPlaylist structure.
+ * @param variables Optional variable definitions from the parent multivariant
+ *   playlist's #EXT-X-DEFINE tags. Media-playlist `#EXT-X-DEFINE:IMPORT="name"`
+ *   entries resolve against this map. Local `#EXT-X-DEFINE:NAME=,VALUE=`
+ *   entries are also supported and take precedence.
+ * @param queryParams Optional query parameters from the playlist's own URL,
+ *   used to resolve `#EXT-X-DEFINE:QUERYPARAM="name"` entries (RFC 8216
+ *   §4.4.5.1). Interstitial ad manifests (e.g. AWS MediaTailor) commonly carry
+ *   session tokens this way and reference them as `{$name}` in child URIs.
+ * @returns A readonly HlsMediaPlaylist structure.
  * @throws StringParseError if the manifest is malformed.
  */
-export function parseMediaPlaylist(text, variables) {
+export function parseMediaPlaylist(text, variables, queryParams) {
+    const defines = { ...(variables ?? {}) };
+    const substituteVars = (v) => Object.keys(defines).length === 0
+        ? v
+        : substitute(v, defines, HLS_VARIABLE_PATTERN);
     const reader = new StringReader(text);
     reader.white();
     if (!reader.stringIf(EXTM3U)) {
@@ -45,6 +62,7 @@ export function parseMediaPlaylist(text, variables) {
     let pendingDiscontinuity = false;
     let pendingDateTime;
     const segments = [];
+    const dateRanges = [];
     let sequenceCounter = 0;
     while (reader.hasNext()) {
         if (skipWhitespaceLine(reader))
@@ -63,9 +81,7 @@ export function parseMediaPlaylist(text, variables) {
                     continue;
                 const nextLine = readLine(reader).trim();
                 if (!nextLine.startsWith('#')) {
-                    uri = variables
-                        ? substitute(nextLine, variables, HLS_VARIABLE_PATTERN)
-                        : nextLine;
+                    uri = substituteVars(nextLine);
                     break;
                 }
                 // Process tags that come between EXTINF and URI
@@ -168,6 +184,37 @@ export function parseMediaPlaylist(text, variables) {
         else if (trimmed.startsWith(EXT_X_PROGRAM_DATE_TIME)) {
             pendingDateTime = trimmed.substring(EXT_X_PROGRAM_DATE_TIME.length);
         }
+        else if (trimmed.startsWith(EXT_X_DEFINE)) {
+            const attrStr = trimmed.substring(EXT_X_DEFINE.length);
+            const attrReader = new StringReader(attrStr);
+            const attrs = parseAttributes(attrReader);
+            const importName = attrs['IMPORT'];
+            const queryParamName = attrs['QUERYPARAM'];
+            if (importName) {
+                // Per RFC 8216 §4.4.2.3: IMPORT copies the value from the
+                // parent multivariant's DEFINE map. Ignore silently if unknown.
+                const imported = variables?.[importName];
+                if (imported !== undefined)
+                    defines[importName] = imported;
+            }
+            else if (queryParamName) {
+                // Per RFC 8216 §4.4.5.1: QUERYPARAM copies the value from the
+                // named query parameter of the playlist's own URL. Ignore
+                // silently if the parameter is absent.
+                const queryValue = queryParams?.[queryParamName];
+                if (queryValue !== undefined) {
+                    defines[queryParamName] = queryValue;
+                }
+            }
+            else if (attrs['NAME'] && attrs['VALUE']) {
+                defines[attrs['NAME']] = attrs['VALUE'];
+            }
+        }
+        else if (trimmed.startsWith(EXT_X_DATERANGE)) {
+            const dateRange = parseHlsDateRange(trimmed.substring(EXT_X_DATERANGE.length), substituteVars);
+            if (dateRange)
+                dateRanges.push(dateRange);
+        }
         // Unrecognized tags and comments are silently skipped
     }
     return {
@@ -177,6 +224,63 @@ export function parseMediaPlaylist(text, variables) {
         playlistType,
         ended,
         segments,
+        dateRanges,
+    };
+}
+/**
+ * Attribute names that map to typed {@link HlsDateRange} fields and are therefore
+ * excluded from the free-form {@link HlsDateRange.clientAttributes} bag.
+ */
+const DATERANGE_RESERVED_ATTRS = new Set([
+    'ID',
+    'CLASS',
+    'START-DATE',
+    'END-DATE',
+    'DURATION',
+    'PLANNED-DURATION',
+    'END-ON-NEXT',
+]);
+/**
+ * Parses the attribute list of an EXT-X-DATERANGE tag. Returns undefined when
+ * the tag is missing the required ID or START-DATE attributes (per RFC 8216
+ * §4.3.2.7 a Date Range without both is not usable), so malformed tags are
+ * skipped rather than throwing.
+ *
+ * The `X-` client-defined attributes are collected verbatim into
+ * {@link HlsDateRange.clientAttributes}. Interstitial attributes such as
+ * `X-ASSET-URI` frequently reference EXT-X-DEFINE variables, so string values
+ * are passed through the same substitution applied to segment URIs.
+ */
+function parseHlsDateRange(attrStr, substituteVars) {
+    const attrs = parseAttributes(new StringReader(attrStr));
+    const id = attrs['ID'];
+    // START-DATE may be absent (the Record index type hides this), so gate on
+    // key presence rather than a nullish fallback.
+    const startDate = 'START-DATE' in attrs ? attrs['START-DATE'] : '';
+    // END-ON-NEXT ranges anchor to the following range and may legitimately
+    // omit START-DATE; RFC requires ID and CLASS in that case.
+    const endOnNext = attrs['END-ON-NEXT'] === 'YES';
+    if (!id)
+        return undefined;
+    if (!startDate && !endOnNext)
+        return undefined;
+    const clientAttributes = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (DATERANGE_RESERVED_ATTRS.has(key))
+            continue;
+        clientAttributes[key] = substituteVars(value);
+    }
+    return {
+        id,
+        startDate,
+        ...(attrs['CLASS'] && { classId: attrs['CLASS'] }),
+        ...(attrs['END-DATE'] && { endDate: attrs['END-DATE'] }),
+        ...(attrs['DURATION'] && { duration: Number(attrs['DURATION']) }),
+        ...(attrs['PLANNED-DURATION'] && {
+            plannedDuration: Number(attrs['PLANNED-DURATION']),
+        }),
+        ...(endOnNext && { endOnNext: true }),
+        clientAttributes,
     };
 }
 /**