@amazon/vinyl-hls-parser 1.0.0

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

@@ -0,0 +1,25 @@
+import type { HlsSegment } from './HlsSegment';
+/**
+ * A parsed HLS Media Playlist as defined by RFC 8216.
+ *
+ * A Media Playlist contains a list of media segments that, when played sequentially, form a continuous stream.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4
+ */
+export interface MediaPlaylist {
+    /** 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). */
+    readonly targetDuration: number;
+    /** 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;
+    /** 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 mutability type of Media Playlist. */
+export type MediaPlaylistType = 'VOD' | 'EVENT' | 'LIVE';
+//# sourceMappingURL=MediaPlaylist.d.ts.map

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

@@ -0,0 +1,19 @@
+/**
+ * Session-level metadata in an HLS Master Playlist (EXT-X-SESSION-DATA).
+ *
+ * Carries application-defined key/value data that applies to the entire presentation,
+ * such as content identifiers or localized metadata.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.4.4
+ */
+export interface SessionData {
+    /** A unique identifier for this session data entry (DATA-ID). */
+    readonly dataId: string;
+    /** The data value as a string (VALUE). Mutually exclusive with {@link uri}. */
+    readonly value?: string;
+    /** A URI pointing to a JSON resource containing the data (URI). Mutually exclusive with {@link value}. */
+    readonly uri?: string;
+    /** The language of the data as a BCP 47 tag (LANGUAGE). */
+    readonly language?: string;
+}
+//# sourceMappingURL=SessionData.d.ts.map

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

@@ -0,0 +1,31 @@
+/**
+ * A variant stream in an HLS Master Playlist (EXT-X-STREAM-INF).
+ *
+ * Each variant represents the same presentation at a particular bitrate and resolution,
+ * optionally referencing alternative rendition groups for audio, video, subtitles, or closed captions.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.4.2
+ */
+export interface VariantStream {
+    /** The peak bitrate of the variant stream in bits per second (BANDWIDTH). */
+    readonly bandwidth: number;
+    /** The URI of the Media Playlist for this variant. */
+    readonly uri: string;
+    /** A comma-separated list of codec strings describing the media in this variant (CODECS). */
+    readonly codecs?: string;
+    /** The horizontal resolution of the video in pixels (RESOLUTION width). */
+    readonly width?: number;
+    /** The vertical resolution of the video in pixels (RESOLUTION height). */
+    readonly height?: number;
+    /** The maximum frame rate of the video in frames per second (FRAME-RATE). */
+    readonly frameRate?: number;
+    /** The GROUP-ID of the audio alternative renditions to use with this variant (AUDIO). */
+    readonly audioGroup?: string;
+    /** The GROUP-ID of the video alternative renditions to use with this variant (VIDEO). */
+    readonly videoGroup?: string;
+    /** The GROUP-ID of the subtitle alternative renditions to use with this variant (SUBTITLES). */
+    readonly subtitlesGroup?: string;
+    /** The GROUP-ID of the closed-caption alternative renditions to use with this variant (CLOSED-CAPTIONS). */
+    readonly closedCaptionsGroup?: string;
+}
+//# sourceMappingURL=VariantStream.d.ts.map

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

@@ -0,0 +1,7 @@
+/** Auto-generated from build scripts */
+import './setup';
+import './parse/parseUtil.test';
+import './parse/parseMediaPlaylist.test';
+import './parse/parseMainPlaylist.test';
+import './parse/parseAttributes.test';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../test/unit/index.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,OAAO,SAAS,CAAA;AAChB,OAAO,wBAAwB,CAAA;AAC/B,OAAO,iCAAiC,CAAA;AACxC,OAAO,gCAAgC,CAAA;AACvC,OAAO,8BAA8B,CAAA"}

package/dist/unit/types/current/index.js

@@ -0,0 +1,6 @@
+/** Auto-generated from build scripts */
+import './setup';
+import './parse/parseUtil.test';
+import './parse/parseMediaPlaylist.test';
+import './parse/parseMainPlaylist.test';
+import './parse/parseAttributes.test';

package/dist/unit/types/current/parse/parseAttributes.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parseAttributes.test.d.ts.map

package/dist/unit/types/current/parse/parseAttributes.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseAttributes.test.d.ts","sourceRoot":"","sources":["../../../../../test/unit/parse/parseAttributes.test.ts"],"names":[],"mappings":""}

package/dist/unit/types/current/parse/parseAttributes.test.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { StringReader } from '@amazon/vinyl-util';
+import { parseAttributes } from '@amazon/vinyl-hls-parser';
+describe('parseAttributes', () => {
+    it('parses simple key-value pairs', () => {
+        const reader = new StringReader('BANDWIDTH=1280000,CODECS="avc1.42e00a"');
+        const attrs = parseAttributes(reader);
+        expect(attrs['BANDWIDTH']).toBe('1280000');
+        expect(attrs['CODECS']).toBe('avc1.42e00a');
+    });
+    it('handles quoted values with embedded commas', () => {
+        const reader = new StringReader('CODECS="avc1.42e00a,mp4a.40.2",BANDWIDTH=1280000');
+        const attrs = parseAttributes(reader);
+        expect(attrs['CODECS']).toBe('avc1.42e00a,mp4a.40.2');
+        expect(attrs['BANDWIDTH']).toBe('1280000');
+    });
+    it('handles a single unquoted attribute', () => {
+        const reader = new StringReader('BANDWIDTH=1280000');
+        const attrs = parseAttributes(reader);
+        expect(attrs['BANDWIDTH']).toBe('1280000');
+    });
+    it('handles a single quoted attribute', () => {
+        const reader = new StringReader('URI="segment.ts"');
+        const attrs = parseAttributes(reader);
+        expect(attrs['URI']).toBe('segment.ts');
+    });
+    it('returns empty record for empty input', () => {
+        const reader = new StringReader('');
+        const attrs = parseAttributes(reader);
+        expect(Object.keys(attrs).length).toBe(0);
+    });
+    it('handles multiple quoted values', () => {
+        const reader = new StringReader('TYPE=AUDIO,GROUP-ID="audio",NAME="English",LANGUAGE="en"');
+        const attrs = parseAttributes(reader);
+        expect(attrs['TYPE']).toBe('AUDIO');
+        expect(attrs['GROUP-ID']).toBe('audio');
+        expect(attrs['NAME']).toBe('English');
+        expect(attrs['LANGUAGE']).toBe('en');
+    });
+    it('skips empty key', () => {
+        const reader = new StringReader('=value,KEY=test');
+        const attrs = parseAttributes(reader);
+        expect(Object.keys(attrs).length).toBe(0);
+    });
+    it('handles missing equals sign', () => {
+        const reader = new StringReader('NOEQUALS');
+        const attrs = parseAttributes(reader);
+        expect(Object.keys(attrs).length).toBe(0);
+    });
+    it('handles quoted value without closing quote', () => {
+        const reader = new StringReader('KEY="unclosed');
+        const attrs = parseAttributes(reader);
+        expect(attrs['KEY']).toBe('unclosed');
+    });
+    it('stops at newline', () => {
+        const reader = new StringReader('KEY=value\nIGNORED=ignored');
+        const attrs = parseAttributes(reader);
+        expect(attrs['KEY']).toBe('value');
+        expect(attrs['IGNORED']).toBeUndefined();
+    });
+    it('stops at carriage return', () => {
+        const reader = new StringReader('KEY=value\rIGNORED=ignored');
+        const attrs = parseAttributes(reader);
+        expect(attrs['KEY']).toBe('value');
+        expect(attrs['IGNORED']).toBeUndefined();
+    });
+});

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parseMainPlaylist.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parseMainPlaylist.test.d.ts","sourceRoot":"","sources":["../../../../../test/unit/parse/parseMainPlaylist.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,194 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { StringParseError, ValidationError } from '@amazon/vinyl-util';
+import { parseMainPlaylist } from '@amazon/vinyl-hls-parser';
+describe('parseMainPlaylist', () => {
+    it('throws StringParseError when #EXTM3U is missing', () => {
+        expect(() => parseMainPlaylist('invalid')).toThrowError(StringParseError);
+    });
+    it('parses variant streams with bandwidth and uri', () => {
+        const manifest = [
+            '#EXTM3U',
+            '#EXT-X-STREAM-INF:BANDWIDTH=1280000',
+            'low/index.m3u8',
+            '#EXT-X-STREAM-INF:BANDWIDTH=2560000',
+            'mid/index.m3u8',
+        ].join('\n');
+        const result = parseMainPlaylist(manifest);
+        expect(result.variants.length).toBe(2);
+        expect(result.variants[0].bandwidth).toBe(1280000);
+        expect(result.variants[0].uri).toBe('low/index.m3u8');
+        expect(result.variants[1].bandwidth).toBe(2560000);
+        expect(result.variants[1].uri).toBe('mid/index.m3u8');
+    });
+    it('parses variant streams with optional attributes', () => {
+        const manifest = [
+            '#EXTM3U',
+            '#EXT-X-STREAM-INF:BANDWIDTH=1280000,CODECS="avc1.42e00a,mp4a.40.2",RESOLUTION=640x360,FRAME-RATE=29.97,AUDIO="audio-group",VIDEO="video-group",SUBTITLES="subs"',
+            'variant.m3u8',
+        ].join('\n');
+        const result = parseMainPlaylist(manifest);
+        const v = result.variants[0];
+        expect(v.bandwidth).toBe(1280000);
+        expect(v.codecs).toBe('avc1.42e00a,mp4a.40.2');
+        expect(v.width).toBe(640);
+        expect(v.height).toBe(360);
+        expect(v.frameRate).toBe(29.97);
+        expect(v.audioGroup).toBe('audio-group');
+        expect(v.videoGroup).toBe('video-group');
+        expect(v.subtitlesGroup).toBe('subs');
+    });
+    it('parses alternative renditions', () => {
+        const manifest = [
+            '#EXTM3U',
+            '#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio",NAME="English",LANGUAGE="en",DEFAULT=YES,AUTOSELECT=YES,URI="audio/en.m3u8"',
+            '#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio",NAME="Spanish",LANGUAGE="es",DEFAULT=NO,AUTOSELECT=NO',
+        ].join('\n');
+        const result = parseMainPlaylist(manifest);
+        expect(result.alternativeRenditions.length).toBe(2);
+        const en = result.alternativeRenditions[0];
+        expect(en.type).toBe('AUDIO');
+        expect(en.groupId).toBe('audio');
+        expect(en.name).toBe('English');
+        expect(en.language).toBe('en');
+        expect(en.default).toBe(true);
+        expect(en.autoSelect).toBe(true);
+        expect(en.uri).toBe('audio/en.m3u8');
+        const es = result.alternativeRenditions[1];
+        expect(es.default).toBe(false);
+        expect(es.autoSelect).toBe(false);
+        expect(es.uri).toBeUndefined();
+    });
+    it('parses session data', () => {
+        const manifest = [
+            '#EXTM3U',
+            '#EXT-X-SESSION-DATA:DATA-ID="com.example.title",VALUE="Episode 1",LANGUAGE="en"',
+            '#EXT-X-SESSION-DATA:DATA-ID="com.example.poster",URI="/poster.jpg"',
+        ].join('\n');
+        const result = parseMainPlaylist(manifest);
+        expect(result.sessionData.length).toBe(2);
+        expect(result.sessionData[0].dataId).toBe('com.example.title');
+        expect(result.sessionData[0].value).toBe('Episode 1');
+        expect(result.sessionData[0].language).toBe('en');
+        expect(result.sessionData[0].uri).toBeUndefined();
+        expect(result.sessionData[1].dataId).toBe('com.example.poster');
+        expect(result.sessionData[1].uri).toBe('/poster.jpg');
+        expect(result.sessionData[1].value).toBeUndefined();
+    });
+    it('skips blank lines and comments', () => {
+        const manifest = [
+            '#EXTM3U',
+            '',
+            '# This is a comment',
+            '#EXT-X-STREAM-INF:BANDWIDTH=1280000',
+            '',
+            'low/index.m3u8',
+        ].join('\n');
+        const result = parseMainPlaylist(manifest);
+        expect(result.variants.length).toBe(1);
+        expect(result.variants[0].uri).toBe('low/index.m3u8');
+    });
+    it('handles lines with only whitespace', () => {
+        const manifest = [
+            '#EXTM3U',
+            '   ',
+            '\t\t',
+            '#EXT-X-STREAM-INF:BANDWIDTH=1280000',
+            '  \t  ',
+            'low/index.m3u8',
+        ].join('\n');
+        const result = parseMainPlaylist(manifest);
+        expect(result.variants.length).toBe(1);
+        expect(result.variants[0].uri).toBe('low/index.m3u8');
+    });
+    it('handles empty manifest after header', () => {
+        const manifest = '#EXTM3U\n';
+        const result = parseMainPlaylist(manifest);
+        expect(result.variants.length).toBe(0);
+        expect(result.alternativeRenditions.length).toBe(0);
+        expect(result.sessionData.length).toBe(0);
+    });
+    it('handles line with only whitespace in main playlist', () => {
+        const manifest = `#EXTM3U
+   
+#EXT-X-STREAM-INF:BANDWIDTH=1280000
+low/index.m3u8`;
+        const result = parseMainPlaylist(manifest);
+        expect(result.variants.length).toBe(1);
+    });
+    it('handles line that becomes empty after trimming', () => {
+        // Create a line with non-breaking space that might not be caught by skipWhitespaceLine
+        const manifest = '#EXTM3U\n\u00A0\n#EXT-X-STREAM-INF:BANDWIDTH=1280000\nlow/index.m3u8';
+        const result = parseMainPlaylist(manifest);
+        expect(result.variants.length).toBe(1);
+    });
+    it('skips unrecognized tags', () => {
+        const manifest = [
+            '#EXTM3U',
+            '#EXT-X-INDEPENDENT-SEGMENTS',
+            '#EXT-X-STREAM-INF:BANDWIDTH=1280000',
+            'low/index.m3u8',
+        ].join('\n');
+        const result = parseMainPlaylist(manifest);
+        expect(result.variants.length).toBe(1);
+    });
+    it('tolerates leading whitespace before #EXTM3U', () => {
+        const manifest = '  \n#EXTM3U\n#EXT-X-STREAM-INF:BANDWIDTH=1280000\nlow/index.m3u8';
+        const result = parseMainPlaylist(manifest);
+        expect(result.variants.length).toBe(1);
+    });
+    it('returns empty arrays when no variants, renditions, or session data', () => {
+        const result = parseMainPlaylist('#EXTM3U\n');
+        expect(result.variants.length).toBe(0);
+        expect(result.alternativeRenditions.length).toBe(0);
+        expect(result.sessionData.length).toBe(0);
+    });
+    it('handles invalid resolution format', () => {
+        const manifest = [
+            '#EXTM3U',
+            '#EXT-X-STREAM-INF:BANDWIDTH=1280000,RESOLUTION=640',
+            'variant.m3u8',
+        ].join('\n');
+        expect(() => parseMainPlaylist(manifest)).toThrowError(ValidationError);
+    });
+    it('handles invalid resolution values', () => {
+        const manifest = [
+            '#EXTM3U',
+            '#EXT-X-STREAM-INF:BANDWIDTH=1280000,RESOLUTION=0x360',
+            'variant.m3u8',
+        ].join('\n');
+        expect(() => parseMainPlaylist(manifest)).toThrowError(ValidationError);
+    });
+    it('parses valid resolution correctly', () => {
+        const manifest = [
+            '#EXTM3U',
+            '#EXT-X-STREAM-INF:BANDWIDTH=1280000,RESOLUTION=1920x1080',
+            'variant.m3u8',
+        ].join('\n');
+        const result = parseMainPlaylist(manifest);
+        expect(result.variants[0].width).toBe(1920);
+        expect(result.variants[0].height).toBe(1080);
+    });
+    it('parses #EXT-X-DEFINE variables', () => {
+        const manifest = [
+            '#EXTM3U',
+            '#EXT-X-DEFINE:NAME="baseUrl",VALUE="https://cdn.example.com/"',
+            '#EXT-X-STREAM-INF:BANDWIDTH=500000',
+            'low.m3u8',
+        ].join('\n');
+        const result = parseMainPlaylist(manifest);
+        expect(result.defines).toEqual({ baseUrl: 'https://cdn.example.com/' });
+    });
+    it('ignores #EXT-X-DEFINE without VALUE', () => {
+        const manifest = [
+            '#EXTM3U',
+            '#EXT-X-DEFINE:NAME="incomplete"',
+            '#EXT-X-STREAM-INF:BANDWIDTH=500000',
+            'low.m3u8',
+        ].join('\n');
+        const result = parseMainPlaylist(manifest);
+        expect(result.defines).toEqual({});
+    });
+});

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parseMediaPlaylist.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parseMediaPlaylist.test.d.ts","sourceRoot":"","sources":["../../../../../test/unit/parse/parseMediaPlaylist.test.ts"],"names":[],"mappings":""}