@amazon/vinyl-hls-parser 1.1.1 → 2.0.0

package/dist/types/ts3.7/parse/parseMediaPlaylist.d.ts

@@ -1,12 +1,19 @@
-import { MediaPlaylist } from '../types/MediaPlaylist';
+import { 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/ts3.7/types/AlternativeRendition.d.ts

@@ -23,6 +23,19 @@ export interface AlternativeRendition {
     readonly default?: boolean;
     /** Whether the client may choose to play this rendition without explicit user selection (AUTOSELECT). */
     readonly autoSelect?: boolean;
+    /**
+     * Whether this is a forced rendition (FORCED=YES): it presents essential
+     * text (e.g. translations of foreign dialogue) that should be shown even
+     * when the user has not enabled subtitles. Only meaningful for SUBTITLES.
+     */
+    readonly forced?: boolean;
+    /**
+     * Media Characteristic Tags (CHARACTERISTICS), a comma-separated list of
+     * Uniform Type Identifiers describing the rendition, e.g.
+     * `public.accessibility.transcribes-spoken-dialog`. Parsed into individual
+     * tags. Absent when the attribute is not present.
+     */
+    readonly characteristics?: readonly string[];
 }
 /**
  * The media type of an alternative rendition (EXT-X-MEDIA TYPE attribute).

package/dist/types/ts3.7/types/HlsDateRange.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The CLASS value that identifies an {@link HlsDateRange} as an HLS Interstitial,
+ * the server-guided ad insertion (SGAI) primitive defined by Apple.
+ *
+ * @see https://developer.apple.com/streaming/GettingStartedWithHLSInterstitials.pdf
+ */
+export declare const HLS_INTERSTITIAL_CLASS = "com.apple.hls.interstitial";
+/**
+ * A parsed EXT-X-DATERANGE tag from an HLS Media Playlist (RFC 8216 §4.3.2.7).
+ *
+ * A Date Range associates a span of the media timeline, anchored to a wall-clock
+ * START-DATE, with a set of application-defined attributes. It is the transport
+ * for HLS Interstitials (SGAI): an interstitial is a Date Range whose
+ * {@link classId} is {@link HLS_INTERSTITIAL_CLASS} and which carries the
+ * `X-ASSET-URI` or `X-ASSET-LIST` client attributes describing the ad content.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.2.7
+ */
+export interface HlsDateRange {
+    /** A unique identifier for this Date Range within the playlist (ID). */
+    readonly id: string;
+    /** The `CLASS` attribute, a client-defined category for the range, if present. */
+    readonly classId?: string;
+    /** The ISO-8601 wall-clock time at which the range begins (START-DATE). */
+    readonly startDate: string;
+    /** The ISO-8601 wall-clock time at which the range ends (END-DATE), if present. */
+    readonly endDate?: string;
+    /** The duration of the range in seconds (DURATION), if present. */
+    readonly duration?: number;
+    /**
+     * The expected duration of the Date Range in seconds.
+     * This attribute SHOULD be used to indicate the expected duration of a Date Range whose actual
+     * duration is not yet known.
+     * It must be positive.
+     */
+    readonly plannedDuration?: number;
+    /**
+     * Whether the END-DATE of a live range equals the START-DATE of the
+     * range that follows it (END-ON-NEXT=YES). Ranges with this flag must
+     * carry a {@link classId} and omit {@link duration} and {@link endDate}.
+     */
+    readonly endOnNext?: boolean;
+    /**
+     * The client-defined `X-` attributes of the range, keyed by their full
+     * attribute name (e.g. `X-ASSET-URI`). Values are the raw parsed strings
+     * with surrounding quotes removed. Numeric and hex `X-` attributes are
+     * kept verbatim so callers can interpret them per their own schema.
+     */
+    readonly clientAttributes: Readonly<Record<string, string>>;
+}
+//# sourceMappingURL=HlsDateRange.d.ts.map

package/dist/types/ts3.7/types/{MainPlaylist.d.ts → HlsMainPlaylist.d.ts}

@@ -2,14 +2,14 @@ import { AlternativeRendition } from './AlternativeRendition';
 import { SessionData } from './SessionData';
 import { VariantStream } from './VariantStream';
 /**
- * A parsed HLS Master Playlist (also called Multivariant Playlist) as defined by RFC 8216.
+ * A parsed HLS Main Playlist (also called Multivariant Playlist) as defined by RFC 8216.
  *
- * A Master Playlist provides a set of variant streams, each representing the same content at
+ * A Main Playlist provides a set of variant streams, each representing the same content at
  * different bitrates or resolutions, along with alternative renditions and session-level metadata.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.4
  */
-export interface MainPlaylist {
+export interface HlsMainPlaylist {
     /** The variant streams available in this presentation (EXT-X-STREAM-INF). */
     readonly variants: readonly VariantStream[];
     /** Alternative renditions such as additional audio languages or subtitles (EXT-X-MEDIA). */
@@ -19,4 +19,4 @@ export interface MainPlaylist {
     /** Variables defined via EXT-X-DEFINE. Keys are variable names, values are their resolved values. */
     readonly defines?: Readonly<Record<string, string>>;
 }
-//# sourceMappingURL=MainPlaylist.d.ts.map
+//# sourceMappingURL=HlsMainPlaylist.d.ts.map

package/dist/types/ts3.7/types/{MediaPlaylist.d.ts → HlsMediaPlaylist.d.ts}

@@ -1,3 +1,4 @@
+import { HlsDateRange } from './HlsDateRange';
 import { HlsSegment } from './HlsSegment';
 /**
  * A parsed HLS Media Playlist as defined by RFC 8216.
@@ -6,7 +7,7 @@ import { HlsSegment } from './HlsSegment';
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4
  */
-export interface MediaPlaylist {
+export interface HlsMediaPlaylist {
     /** The HLS protocol version required by this playlist (EXT-X-VERSION). */
     readonly version: number;
     /** The upper bound on the duration of any segment in the playlist, in seconds (EXT-X-TARGETDURATION). */
@@ -14,12 +15,18 @@ export interface MediaPlaylist {
     /** The sequence number of the first segment in the playlist (EXT-X-MEDIA-SEQUENCE). */
     readonly mediaSequence: number;
     /** The mutability type of the playlist: VOD (static), EVENT (append-only), or LIVE (sliding window). */
-    readonly playlistType: MediaPlaylistType;
+    readonly playlistType: HlsMediaPlaylistType;
     /** Whether the playlist is complete, indicated by the presence of EXT-X-ENDLIST. */
     readonly ended: boolean;
     /** The ordered list of media segments in this playlist. */
     readonly segments: readonly HlsSegment[];
+    /**
+     * The Date Ranges declared in this playlist (EXT-X-DATERANGE), in the order
+     * they appear. HLS Interstitials (SGAI ad breaks) are carried as Date Ranges
+     * whose classId is `com.apple.hls.interstitial`.
+     */
+    readonly dateRanges: readonly HlsDateRange[];
 }
 /** The mutability type of Media Playlist. */
-export type MediaPlaylistType = 'VOD' | 'EVENT' | 'LIVE';
-//# sourceMappingURL=MediaPlaylist.d.ts.map
+export type HlsMediaPlaylistType = 'VOD' | 'EVENT' | 'LIVE';
+//# sourceMappingURL=HlsMediaPlaylist.d.ts.map

package/dist/types/ts4.1/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/ts4.1/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/ts4.1/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/ts4.1/types/AlternativeRendition.d.ts

@@ -23,6 +23,19 @@ export interface AlternativeRendition {
     readonly default?: boolean;
     /** Whether the client may choose to play this rendition without explicit user selection (AUTOSELECT). */
     readonly autoSelect?: boolean;
+    /**
+     * Whether this is a forced rendition (FORCED=YES): it presents essential
+     * text (e.g. translations of foreign dialogue) that should be shown even
+     * when the user has not enabled subtitles. Only meaningful for SUBTITLES.
+     */
+    readonly forced?: boolean;
+    /**
+     * Media Characteristic Tags (CHARACTERISTICS), a comma-separated list of
+     * Uniform Type Identifiers describing the rendition, e.g.
+     * `public.accessibility.transcribes-spoken-dialog`. Parsed into individual
+     * tags. Absent when the attribute is not present.
+     */
+    readonly characteristics?: readonly string[];
 }
 /**
  * The media type of an alternative rendition (EXT-X-MEDIA TYPE attribute).

package/dist/types/ts4.1/types/HlsDateRange.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The CLASS value that identifies an {@link HlsDateRange} as an HLS Interstitial,
+ * the server-guided ad insertion (SGAI) primitive defined by Apple.
+ *
+ * @see https://developer.apple.com/streaming/GettingStartedWithHLSInterstitials.pdf
+ */
+export declare const HLS_INTERSTITIAL_CLASS = "com.apple.hls.interstitial";
+/**
+ * A parsed EXT-X-DATERANGE tag from an HLS Media Playlist (RFC 8216 §4.3.2.7).
+ *
+ * A Date Range associates a span of the media timeline, anchored to a wall-clock
+ * START-DATE, with a set of application-defined attributes. It is the transport
+ * for HLS Interstitials (SGAI): an interstitial is a Date Range whose
+ * {@link classId} is {@link HLS_INTERSTITIAL_CLASS} and which carries the
+ * `X-ASSET-URI` or `X-ASSET-LIST` client attributes describing the ad content.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.2.7
+ */
+export interface HlsDateRange {
+    /** A unique identifier for this Date Range within the playlist (ID). */
+    readonly id: string;
+    /** The `CLASS` attribute, a client-defined category for the range, if present. */
+    readonly classId?: string;
+    /** The ISO-8601 wall-clock time at which the range begins (START-DATE). */
+    readonly startDate: string;
+    /** The ISO-8601 wall-clock time at which the range ends (END-DATE), if present. */
+    readonly endDate?: string;
+    /** The duration of the range in seconds (DURATION), if present. */
+    readonly duration?: number;
+    /**
+     * The expected duration of the Date Range in seconds.
+     * This attribute SHOULD be used to indicate the expected duration of a Date Range whose actual
+     * duration is not yet known.
+     * It must be positive.
+     */
+    readonly plannedDuration?: number;
+    /**
+     * Whether the END-DATE of a live range equals the START-DATE of the
+     * range that follows it (END-ON-NEXT=YES). Ranges with this flag must
+     * carry a {@link classId} and omit {@link duration} and {@link endDate}.
+     */
+    readonly endOnNext?: boolean;
+    /**
+     * The client-defined `X-` attributes of the range, keyed by their full
+     * attribute name (e.g. `X-ASSET-URI`). Values are the raw parsed strings
+     * with surrounding quotes removed. Numeric and hex `X-` attributes are
+     * kept verbatim so callers can interpret them per their own schema.
+     */
+    readonly clientAttributes: Readonly<Record<string, string>>;
+}
+//# sourceMappingURL=HlsDateRange.d.ts.map

package/dist/types/{current/types/MainPlaylist.d.ts → ts4.1/types/HlsMainPlaylist.d.ts}

@@ -2,14 +2,14 @@ import type { AlternativeRendition } from './AlternativeRendition';
 import type { SessionData } from './SessionData';
 import type { VariantStream } from './VariantStream';
 /**
- * A parsed HLS Master Playlist (also called Multivariant Playlist) as defined by RFC 8216.
+ * A parsed HLS Main Playlist (also called Multivariant Playlist) as defined by RFC 8216.
  *
- * A Master Playlist provides a set of variant streams, each representing the same content at
+ * A Main Playlist provides a set of variant streams, each representing the same content at
  * different bitrates or resolutions, along with alternative renditions and session-level metadata.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.4
  */
-export interface MainPlaylist {
+export interface HlsMainPlaylist {
     /** The variant streams available in this presentation (EXT-X-STREAM-INF). */
     readonly variants: readonly VariantStream[];
     /** Alternative renditions such as additional audio languages or subtitles (EXT-X-MEDIA). */
@@ -19,4 +19,4 @@ export interface MainPlaylist {
     /** Variables defined via EXT-X-DEFINE. Keys are variable names, values are their resolved values. */
     readonly defines?: Readonly<Record<string, string>>;
 }
-//# sourceMappingURL=MainPlaylist.d.ts.map
+//# sourceMappingURL=HlsMainPlaylist.d.ts.map

package/dist/types/{current/types/MediaPlaylist.d.ts → ts4.1/types/HlsMediaPlaylist.d.ts}

@@ -1,3 +1,4 @@
+import type { HlsDateRange } from './HlsDateRange';
 import type { HlsSegment } from './HlsSegment';
 /**
  * A parsed HLS Media Playlist as defined by RFC 8216.
@@ -6,7 +7,7 @@ import type { HlsSegment } from './HlsSegment';
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4
  */
-export interface MediaPlaylist {
+export interface HlsMediaPlaylist {
     /** The HLS protocol version required by this playlist (EXT-X-VERSION). */
     readonly version: number;
     /** The upper bound on the duration of any segment in the playlist, in seconds (EXT-X-TARGETDURATION). */
@@ -14,12 +15,18 @@ export interface MediaPlaylist {
     /** The sequence number of the first segment in the playlist (EXT-X-MEDIA-SEQUENCE). */
     readonly mediaSequence: number;
     /** The mutability type of the playlist: VOD (static), EVENT (append-only), or LIVE (sliding window). */
-    readonly playlistType: MediaPlaylistType;
+    readonly playlistType: HlsMediaPlaylistType;
     /** Whether the playlist is complete, indicated by the presence of EXT-X-ENDLIST. */
     readonly ended: boolean;
     /** The ordered list of media segments in this playlist. */
     readonly segments: readonly HlsSegment[];
+    /**
+     * The Date Ranges declared in this playlist (EXT-X-DATERANGE), in the order
+     * they appear. HLS Interstitials (SGAI ad breaks) are carried as Date Ranges
+     * whose classId is `com.apple.hls.interstitial`.
+     */
+    readonly dateRanges: readonly HlsDateRange[];
 }
 /** The mutability type of Media Playlist. */
-export type MediaPlaylistType = 'VOD' | 'EVENT' | 'LIVE';
-//# sourceMappingURL=MediaPlaylist.d.ts.map
+export type HlsMediaPlaylistType = 'VOD' | 'EVENT' | 'LIVE';
+//# sourceMappingURL=HlsMediaPlaylist.d.ts.map

package/dist/types/ts4.7/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/ts4.7/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/ts4.7/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/ts4.7/types/AlternativeRendition.d.ts

@@ -23,6 +23,19 @@ export interface AlternativeRendition {
     readonly default?: boolean;
     /** Whether the client may choose to play this rendition without explicit user selection (AUTOSELECT). */
     readonly autoSelect?: boolean;
+    /**
+     * Whether this is a forced rendition (FORCED=YES): it presents essential
+     * text (e.g. translations of foreign dialogue) that should be shown even
+     * when the user has not enabled subtitles. Only meaningful for SUBTITLES.
+     */
+    readonly forced?: boolean;
+    /**
+     * Media Characteristic Tags (CHARACTERISTICS), a comma-separated list of
+     * Uniform Type Identifiers describing the rendition, e.g.
+     * `public.accessibility.transcribes-spoken-dialog`. Parsed into individual
+     * tags. Absent when the attribute is not present.
+     */
+    readonly characteristics?: readonly string[];
 }
 /**
  * The media type of an alternative rendition (EXT-X-MEDIA TYPE attribute).

package/dist/types/ts4.7/types/HlsDateRange.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The CLASS value that identifies an {@link HlsDateRange} as an HLS Interstitial,
+ * the server-guided ad insertion (SGAI) primitive defined by Apple.
+ *
+ * @see https://developer.apple.com/streaming/GettingStartedWithHLSInterstitials.pdf
+ */
+export declare const HLS_INTERSTITIAL_CLASS = "com.apple.hls.interstitial";
+/**
+ * A parsed EXT-X-DATERANGE tag from an HLS Media Playlist (RFC 8216 §4.3.2.7).
+ *
+ * A Date Range associates a span of the media timeline, anchored to a wall-clock
+ * START-DATE, with a set of application-defined attributes. It is the transport
+ * for HLS Interstitials (SGAI): an interstitial is a Date Range whose
+ * {@link classId} is {@link HLS_INTERSTITIAL_CLASS} and which carries the
+ * `X-ASSET-URI` or `X-ASSET-LIST` client attributes describing the ad content.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.2.7
+ */
+export interface HlsDateRange {
+    /** A unique identifier for this Date Range within the playlist (ID). */
+    readonly id: string;
+    /** The `CLASS` attribute, a client-defined category for the range, if present. */
+    readonly classId?: string;
+    /** The ISO-8601 wall-clock time at which the range begins (START-DATE). */
+    readonly startDate: string;
+    /** The ISO-8601 wall-clock time at which the range ends (END-DATE), if present. */
+    readonly endDate?: string;
+    /** The duration of the range in seconds (DURATION), if present. */
+    readonly duration?: number;
+    /**
+     * The expected duration of the Date Range in seconds.
+     * This attribute SHOULD be used to indicate the expected duration of a Date Range whose actual
+     * duration is not yet known.
+     * It must be positive.
+     */
+    readonly plannedDuration?: number;
+    /**
+     * Whether the END-DATE of a live range equals the START-DATE of the
+     * range that follows it (END-ON-NEXT=YES). Ranges with this flag must
+     * carry a {@link classId} and omit {@link duration} and {@link endDate}.
+     */
+    readonly endOnNext?: boolean;
+    /**
+     * The client-defined `X-` attributes of the range, keyed by their full
+     * attribute name (e.g. `X-ASSET-URI`). Values are the raw parsed strings
+     * with surrounding quotes removed. Numeric and hex `X-` attributes are
+     * kept verbatim so callers can interpret them per their own schema.
+     */
+    readonly clientAttributes: Readonly<Record<string, string>>;
+}
+//# sourceMappingURL=HlsDateRange.d.ts.map

package/dist/types/{ts4.1/types/MainPlaylist.d.ts → ts4.7/types/HlsMainPlaylist.d.ts}

@@ -2,14 +2,14 @@ import type { AlternativeRendition } from './AlternativeRendition';
 import type { SessionData } from './SessionData';
 import type { VariantStream } from './VariantStream';
 /**
- * A parsed HLS Master Playlist (also called Multivariant Playlist) as defined by RFC 8216.
+ * A parsed HLS Main Playlist (also called Multivariant Playlist) as defined by RFC 8216.
  *
- * A Master Playlist provides a set of variant streams, each representing the same content at
+ * A Main Playlist provides a set of variant streams, each representing the same content at
  * different bitrates or resolutions, along with alternative renditions and session-level metadata.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.4
  */
-export interface MainPlaylist {
+export interface HlsMainPlaylist {
     /** The variant streams available in this presentation (EXT-X-STREAM-INF). */
     readonly variants: readonly VariantStream[];
     /** Alternative renditions such as additional audio languages or subtitles (EXT-X-MEDIA). */
@@ -19,4 +19,4 @@ export interface MainPlaylist {
     /** Variables defined via EXT-X-DEFINE. Keys are variable names, values are their resolved values. */
     readonly defines?: Readonly<Record<string, string>>;
 }
-//# sourceMappingURL=MainPlaylist.d.ts.map
+//# sourceMappingURL=HlsMainPlaylist.d.ts.map

package/dist/types/ts4.7/types/{MediaPlaylist.d.ts → HlsMediaPlaylist.d.ts}

@@ -1,3 +1,4 @@
+import type { HlsDateRange } from './HlsDateRange';
 import type { HlsSegment } from './HlsSegment';
 /**
  * A parsed HLS Media Playlist as defined by RFC 8216.
@@ -6,7 +7,7 @@ import type { HlsSegment } from './HlsSegment';
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4
  */
-export interface MediaPlaylist {
+export interface HlsMediaPlaylist {
     /** The HLS protocol version required by this playlist (EXT-X-VERSION). */
     readonly version: number;
     /** The upper bound on the duration of any segment in the playlist, in seconds (EXT-X-TARGETDURATION). */
@@ -14,12 +15,18 @@ export interface MediaPlaylist {
     /** The sequence number of the first segment in the playlist (EXT-X-MEDIA-SEQUENCE). */
     readonly mediaSequence: number;
     /** The mutability type of the playlist: VOD (static), EVENT (append-only), or LIVE (sliding window). */
-    readonly playlistType: MediaPlaylistType;
+    readonly playlistType: HlsMediaPlaylistType;
     /** Whether the playlist is complete, indicated by the presence of EXT-X-ENDLIST. */
     readonly ended: boolean;
     /** The ordered list of media segments in this playlist. */
     readonly segments: readonly HlsSegment[];
+    /**
+     * The Date Ranges declared in this playlist (EXT-X-DATERANGE), in the order
+     * they appear. HLS Interstitials (SGAI ad breaks) are carried as Date Ranges
+     * whose classId is `com.apple.hls.interstitial`.
+     */
+    readonly dateRanges: readonly HlsDateRange[];
 }
 /** The mutability type of Media Playlist. */
-export type MediaPlaylistType = 'VOD' | 'EVENT' | 'LIVE';
-//# sourceMappingURL=MediaPlaylist.d.ts.map
+export type HlsMediaPlaylistType = 'VOD' | 'EVENT' | 'LIVE';
+//# sourceMappingURL=HlsMediaPlaylist.d.ts.map