@amazon/vinyl 1.2.1 → 1.2.2

package/dist/types/ts4.7/playback/createStallMonitor.d.ts

@@ -0,0 +1,45 @@
+import { type Timestamp } from '@amazon/vinyl-util';
+import type { ReadonlyPlaybackController } from './ReadonlyPlaybackController';
+import { StallEndedReason } from './ReadonlyPlaybackController';
+export interface StallMonitorOptions {
+    /**
+     * Seconds the play head must be frozen (no `timeUpdate`) while playing before a stall is
+     * reported. Default: 1
+     */
+    readonly stallThreshold?: number;
+    /**
+     * How often (seconds) the play head freeze is checked. Default: 0.25
+     */
+    readonly pollInterval?: number;
+}
+export interface StallEndedInfo {
+    /** Time of the last `timeUpdate` observed before the play head froze. */
+    readonly started: Timestamp;
+    /** Time the stall ended. */
+    readonly ended: Timestamp;
+    /** Total seconds the play head was frozen. */
+    readonly duration: number;
+    /** Why the stall ended. */
+    readonly reason: StallEndedReason;
+}
+export interface StallMonitorCallbacks {
+    /** Called when a stall is first detected. */
+    readonly onStallEntered: () => void;
+    /** Called when a detected stall ends. */
+    readonly onStallEnded: (info: StallEndedInfo) => void;
+}
+/**
+ * Watches a {@link ReadonlyPlaybackController} for stalls while playing: the play head freezing
+ * (no `timeUpdate`) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
+ *
+ * Detection only runs once playback has actually been observed (a `playing` event) and is
+ * suspended on `pause`/`seeking`/`emptied` until playback is observed again — so a stall is never
+ * reported during initial loading or while awaiting a seek. A detected stall ends when the play
+ * head advances again (`playing`) or playback stops for another reason (`pause`/`seeking`/
+ * `emptied`); {@link StallEndedInfo.duration} is measured from the last `timeUpdate` before the
+ * freeze, so it reflects the full frozen time rather than only the time past the threshold.
+ *
+ * Returns a function that stops the monitor.
+ */
+export declare function createStallMonitor(controller: ReadonlyPlaybackController, callbacks: StallMonitorCallbacks, options?: StallMonitorOptions): () => void;
+//# sourceMappingURL=createStallMonitor.d.ts.map

package/dist/types/ts4.7/streaming/AudioOptions.d.ts

@@ -1,4 +1,5 @@
 import type { ObjectSchema } from '@amazon/vinyl-validation';
+import type { Maybe } from '@amazon/vinyl-util';
 /**
  * Criteria used to pick which audio rendition to play.
  */
@@ -33,6 +34,32 @@ export interface AudioOptions {
      * The audio selection criteria (language / descriptive).
      */
     readonly selection?: AudioSelection;
+    /**
+     * When `true`, disables the audio sampling-rate support filter, so audio
+     * renditions whose sampling rate exceeds what the platform reports (via the
+     * `AudioContext` output rate) are kept and offered to playback anyway.
+     * `false` (the default) applies the filter. Changing this re-filters the
+     * timeline immediately.
+     */
+    readonly disableSampleRateFilter?: boolean;
+    /**
+     * The maximum audio sampling rate (Hz) the sampling-rate filter treats as
+     * supported. When set, it takes precedence over the platform's
+     * `AudioContext`-reported output rate. Ignored when
+     * {@link disableSampleRateFilter} is `true`. Changing this re-filters the
+     * timeline immediately. `null`/`undefined` falls back to the reported rate.
+     */
+    readonly maxSampleRate?: Maybe<number>;
+    /**
+     * The minimum audio sampling rate (Hz) the sampling-rate filter treats as
+     * supported. When set, renditions below it are filtered out as a soft floor
+     * (if every audio rendition is below it, the highest is kept so playback is
+     * never stranded). Applied alongside the max cap whenever the filter runs,
+     * regardless of how the max was determined; ignored when
+     * {@link disableSampleRateFilter} is `true`. Changing this re-filters the
+     * timeline immediately.
+     */
+    readonly minSampleRate?: Maybe<number>;
 }
 export declare const defaultAudioOptions: AudioOptions;
 export declare const audioOptionsValidator: ObjectSchema<AudioOptions>;

package/dist/types/ts4.7/streaming/LoadMetric.d.ts

@@ -1,14 +1,17 @@
 import type { Timestamp } from '@amazon/vinyl-util';
 import type { TrackUri } from '../track/Track';
+import type { ContentType } from './MediaQualityMetadata';
 /**
  * The stage of the track-load journey a {@link LoadSpanMeasurement} describes.
  *
  * - `manifest`: fetching and parsing the DASH/HLS manifest.
+ * - `keySetup`: the EME/CDM setup, from session creation to the CDM's first
+ *   license message. Precedes and is contiguous with `license`.
  * - `license`: the DRM license request/response exchange.
  * - `initSegment`: fetching the initialization segment.
  * - `firstSegment`: fetching the first media segment.
  */
-export type LoadSpanKind = 'manifest' | 'license' | 'initSegment' | 'firstSegment';
+export type LoadSpanKind = 'manifest' | 'keySetup' | 'license' | 'initSegment' | 'firstSegment';
 /**
  * A timed span for one stage of a track load.
  *
@@ -35,6 +38,17 @@ export interface LoadSpanMeasurement {
      * buffering DRM info is set).
      */
     readonly trackUri?: TrackUri;
+    /**
+     * The MIME type of the content this span was measured for, when known. Set
+     * for DRM `license` spans so a certificate exchange and the per-content-type
+     * license exchanges are distinguishable.
+     */
+    readonly mimeType?: string;
+    /**
+     * The content type this span was measured for, when known. Set alongside
+     * {@link mimeType} for DRM `license` spans.
+     */
+    readonly contentType?: ContentType;
 }
 /**
  * A {@link LoadSpanMeasurement} attributed to the track it was measured for.

package/dist/types/ts4.7/streaming/createTimelineContentTypesValue.d.ts

@@ -0,0 +1,21 @@
+import type { ContentTypesValue } from './ContentTypesValue';
+import type { MediaTimeline } from './MediaTimeline';
+import type { ObservableValue } from '@amazon/vinyl-observable';
+export interface TimelineContentTypesValueDeps {
+    /**
+     * The filtered, playable timeline. Content types are derived from the
+     * qualities that survive filtering, so a content type whose renditions are
+     * all filtered out (e.g. every audio rendition dropped by the sample-rate
+     * filter) is not reported — it never gates readiness and no source buffer
+     * is expected for it, so the remaining content types still play.
+     */
+    readonly mediaTimelineTransformed: ObservableValue<Promise<MediaTimeline>>;
+}
+/**
+ * Provides the MSE content types to create source buffers for, derived from the
+ * qualities that survive timeline filtering rather than the raw manifest. Only
+ * `'audio'`/`'video'` are reported; text is a sidecar pipeline, never an MSE
+ * source buffer.
+ */
+export declare function createTimelineContentTypesValue(deps: TimelineContentTypesValueDeps): ContentTypesValue;
+//# sourceMappingURL=createTimelineContentTypesValue.d.ts.map

package/dist/types/ts4.7/text/discoverDashTextTracks.d.ts

@@ -5,8 +5,8 @@ import type { TextTrackInfo } from './TextTrack';
  *
  * Considers an `<AdaptationSet>` to carry text when one of:
  *  - `contentType="text"`
- *  - `mimeType` starts with `text/` (e.g. `text/vtt`)
- *  - `mimeType` is `application/mp4` *and* the codec/role indicates text
+ *  - its `mimeType`, or that of one of its `<Representation>`s, starts with
+ *    `text/` (e.g. `text/vtt`)
  *
  * Within a text adaptation set, each `<Representation>` becomes one
  * {@link TextTrackInfo}. The `BaseURL` chain (MPD → Period → AdaptationSet →

package/dist/types/ts4.7/track/mse/MseTrack.d.ts

@@ -26,7 +26,6 @@ export declare class MseTrack extends TrackBase {
     get [Symbol.toStringTag](): string;
     protected readonly deps: MseTrackDeps;
     private readonly streams;
-    private readonly disposeAbort;
     private lastPreloadOptions;
     private activateOptions;
     private readonly allFetchedRanges;

package/dist/unit/types/current/ad/AdControllerImpl.test.js

@@ -6,11 +6,22 @@ import { AdControllerImpl } from '@amazon/vinyl';
 import { MockPlaybackController, MockTrack } from '@amazon/vinyl/vinylTestUtil';
 describe('AdControllerImpl', () => {
     let playbackController;
+    let controllers;
     beforeEach(() => {
         playbackController = new MockPlaybackController();
+        controllers = [];
+    });
+    // Dispose every controller a spec created. An activated-but-unstarted ad
+    // arms a `sleep(adLoadTimeout)` timer.
+    afterEach(() => {
+        for (const c of controllers)
+            if (!c.disposed)
+                c.dispose();
     });
     function createController() {
-        return new AdControllerImpl({ playbackController });
+        const c = new AdControllerImpl({ playbackController });
+        controllers.push(c);
+        return c;
     }
     function updateTime(time) {
         playbackController.currentTime = time;
@@ -301,6 +312,21 @@ describe('AdControllerImpl', () => {
             await flush();
             expect(c.currentAdBreak).toBeNull();
         });
+        it('ignores a late provider ad-discovery resolution after dispose', async () => {
+            const c = createController();
+            let resolveAds = () => { };
+            const track = new MockTrack();
+            track.uri = 't1';
+            track.active = true;
+            track.getAds = () => new Promise((res) => {
+                resolveAds = res;
+            });
+            c.setAdsProvider(track); // refreshAds() runs; getAds() stays pending
+            c.dispose();
+            resolveAds(trackAds(makeBreak())); // refreshAds .then: interrupted (disposed)
+            await flush();
+            expect(c.currentTrackAds).toBeNull();
+        });
     });
     it('emits currentTrackAdsChange with the TrackAds when a parent track is set', async () => {
         const c = createController();
@@ -500,6 +526,44 @@ describe('AdControllerImpl', () => {
             await flush();
             expect(c.currentAdBreak).toBeNull();
         });
+        it('still enters a pending break when skipped while its ads resolve', async () => {
+            const c = createController();
+            let resolveAds = () => undefined;
+            const entered = [];
+            await setContent(c, trackAds(makeBreak({
+                id: 'b1',
+                startTime: 0,
+                duration: 30,
+                ads: () => new Promise((resolve) => {
+                    resolveAds = resolve;
+                }),
+            }), makeBreak({
+                id: 'b2',
+                startTime: 1,
+                duration: 30,
+                ads: [
+                    {
+                        id: 'a2',
+                        startTime: 1,
+                        duration: 10,
+                        uri: 'ad2.m3u8',
+                    },
+                ],
+            })));
+            c.on('adBreakEntered', (e) => entered.push(e.adBreak.id));
+            // Both breaks contain the playhead, so both become pending and the
+            // first is entered while its ad list is still in flight.
+            updateTime(2);
+            await flush();
+            expect(entered).toEqual(['b1']);
+            c.skipAdBreak();
+            resolveAds([]);
+            await flush();
+            // Nothing else drains the pending list, and a non-empty list blocks
+            // further midroll ingress, so b2 must be entered here.
+            expect(entered).toEqual(['b1', 'b2']);
+            expect(c.currentAdBreak?.id).toBe('b2');
+        });
     });
     describe('a break with no ads', () => {
         it('completes immediately with a resume position and plays no ad', async () => {
@@ -727,6 +791,34 @@ describe('AdControllerImpl', () => {
             await flush();
             expect(thirds).toEqual(['a1']);
         });
+        it('dispatches each quartile at most once per ad', async () => {
+            const c = createController();
+            const events = [];
+            c.on('adFirstQuartile', () => events.push('first'));
+            c.on('adMidpoint', () => events.push('mid'));
+            c.on('adThirdQuartile', () => events.push('third'));
+            await setContent(c, trackAds(makeBreak({ startTime: 0, duration: 10 })));
+            updateTime(0);
+            await flush();
+            playbackController.dispatch('playing', {});
+            playbackController.duration = 10;
+            playbackController.playbackRate = 1;
+            // Every subsequent timeUpdate is still past each threshold, so an
+            // unlatched check would report the quartile again.
+            for (const [percent, time] of [
+                [0.3, 3],
+                [0.4, 4],
+                [0.6, 6],
+                [0.7, 7],
+                [0.8, 8],
+                [0.9, 9],
+            ]) {
+                playbackController.currentTimePercent = percent;
+                updateTime(time);
+                await flush();
+            }
+            expect(events).toEqual(['first', 'mid', 'third']);
+        });
         it('does not emit quartiles or throw when the ad duration is zero', async () => {
             // Regression: a zero reported duration must not divide-by-zero into
             // NaN progress and must not emit bogus quartile events.
@@ -870,7 +962,6 @@ describe('AdControllerImpl', () => {
             await setContent(c, trackAds(makeBreak({
                 startTime: 10,
                 duration: 20,
-                // Null per-ad duration so the per-ad cap does not end it.
                 ads: [
                     {
                         id: 'a1',
@@ -964,7 +1055,11 @@ describe('AdControllerImpl', () => {
         });
     });
     describe('ad duration and playout limits', () => {
-        it('advances to the next ad when one reaches its declared duration', async () => {
+        it('advances to the next ad on the ad media ended, not its declared duration', async () => {
+            // Each ad asset is its own source; a non-final ad advances on its own
+            // media `ended`. The declared per-ad duration must NOT end it early —
+            // a packager may under-declare it (whole-second rounding), which would
+            // otherwise truncate the real asset.
             const c = createController();
             await setContent(c, trackAds(makeBreak({
                 startTime: 0,
@@ -973,7 +1068,7 @@ describe('AdControllerImpl', () => {
                     {
                         id: 'a1',
                         startTime: 0,
-                        duration: 5,
+                        duration: 5, // declared, server-rounded
                         uri: 'ad1.m3u8',
                     },
                     {
@@ -988,10 +1083,54 @@ describe('AdControllerImpl', () => {
             await flush();
             expect(c.currentAd?.id).toBe('a1');
             playbackController.dispatch('playing', {}); // timeStart = 0
-            updateTime(6); // elapsed 6 >= a1.duration 5 → advance
+            // Past the declared 5s, still within a1's real content — must NOT advance.
+            updateTime(6);
+            await flush();
+            expect(c.currentAd?.id).toBe('a1');
+            // a1's media ends -> advance to a2.
+            playbackController.dispatch('ended', {
+                previous: false,
+                current: true,
+            });
             await flush();
             expect(c.currentAd?.id).toBe('a2');
         });
+        it('does not cut the final/only ad at its declared duration; it ends on media ended', async () => {
+            // The ad server declares DURATION in whole seconds, but the asset's
+            // real content is longer (6.732s here). The only ad must play to its
+            // media `ended`, not be truncated at the rounded declared duration.
+            const c = createController();
+            const ended = [];
+            c.on('adEnded', (e) => ended.push(e.ad.id));
+            await setContent(c, trackAds(makeBreak({
+                startTime: 0,
+                duration: 30,
+                ads: [
+                    {
+                        id: 'a1',
+                        startTime: 0,
+                        duration: 6, // declared, server-rounded
+                        uri: 'ad1.m3u8',
+                    },
+                ],
+            })));
+            updateTime(0);
+            await flush();
+            expect(c.currentAd?.id).toBe('a1');
+            playbackController.dispatch('playing', {}); // timeStart = 0
+            // Past the declared 6s, into the real content — must NOT end yet.
+            updateTime(6.5);
+            await flush();
+            expect(c.currentAd?.id).toBe('a1');
+            expect(ended).toEqual([]);
+            // Real media end at 6.732 ends the ad.
+            playbackController.dispatch('ended', {
+                previous: false,
+                current: true,
+            });
+            expect(ended).toEqual(['a1']);
+            expect(c.currentAdBreak).toBeNull();
+        });
         it('ends the whole break when the playout limit is reached, dropping remaining ads', async () => {
             const c = createController();
             const resumes = [];
@@ -1027,6 +1166,65 @@ describe('AdControllerImpl', () => {
             // content still resumes at the cue point (0), not startTime + playout.
             expect(resumes.at(-1)).toBe(0);
         });
+        it('does not cut at the playout limit when the ad is within tolerance of its media end', async () => {
+            // The budget is reached, but the ad's real media end is <1s away, so
+            // it should finish on its own `ended` rather than be clipped. The
+            // tolerance keys off the playback-reported duration, not ad.duration.
+            const c = createController();
+            await setContent(c, trackAds(makeBreak({
+                startTime: 0,
+                duration: null,
+                playoutLimit: 8,
+                ads: [
+                    {
+                        id: 'a1',
+                        startTime: 0,
+                        duration: 20,
+                        uri: 'ad1.m3u8',
+                    },
+                ],
+            })));
+            updateTime(0);
+            await flush();
+            playbackController.dispatch('playing', {}); // timeStart = 0
+            // Media is 8.5s long; at the 8s budget only 0.5s of media remains.
+            playbackController.duration = 8.5;
+            updateTime(8); // cumulative 8 >= limit 8, but within 1s of media end
+            await flush();
+            expect(c.currentAdBreak).not.toBeNull();
+            expect(c.currentAd?.id).toBe('a1');
+            // It finishes on its own media `ended`.
+            playbackController.dispatch('ended', {
+                previous: false,
+                current: true,
+            });
+            await flush();
+            expect(c.currentAdBreak).toBeNull();
+        });
+        it('cuts at the playout limit when the ad has more than the tolerance of media left', async () => {
+            const c = createController();
+            await setContent(c, trackAds(makeBreak({
+                startTime: 0,
+                duration: null,
+                playoutLimit: 8,
+                ads: [
+                    {
+                        id: 'a1',
+                        startTime: 0,
+                        duration: 20,
+                        uri: 'ad1.m3u8',
+                    },
+                ],
+            })));
+            updateTime(0);
+            await flush();
+            playbackController.dispatch('playing', {}); // timeStart = 0
+            // Media is 20s long; at the 8s budget 12s of media remains → cut.
+            playbackController.duration = 20;
+            updateTime(8);
+            await flush();
+            expect(c.currentAdBreak).toBeNull();
+        });
     });
     describe('CUE=ONCE and replay', () => {
         it('replays a non-ONCE break after the playhead seeks back before it', async () => {

package/dist/unit/types/current/ad/discoverHlsInterstitials.test.js

@@ -199,7 +199,8 @@ describe('discoverHlsInterstitials', () => {
             const ads = await resolveValueProvider(breaks[0].ads);
             expect(fetchSpy.calls.argsFor(0)[0]).toBe('https://example.com/ads.json');
             expect(ads.length).toBe(2);
-            expect(ads[0].uri).toBe('https://cdn.example.com/media/mid1.m3u8');
+            // Relative to the asset list, not to the media playlist.
+            expect(ads[0].uri).toBe('https://example.com/mid1.m3u8');
             expect(ads[0].duration).toBe(10);
             expect(ads[1].uri).toBe('https://cdn.example.com/mid2.m3u8');
             expect(ads[1].duration).toBeNull();

package/dist/unit/types/current/drm/DrmControllerImpl.test.js

@@ -2,7 +2,7 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { createEmptyMediaQualityMetadata, DrmControllerImpl, DrmError, DrmKeySystem, DrmRobustness, LICENSE_TIMEOUT, ReportableMediaError, } from '@amazon/vinyl';
+import { createEmptyMediaQualityMetadata, DrmControllerImpl, DrmError, DrmKeySystem, DrmRobustness, EXCESSIVE_SESSION_COUNT, LICENSE_TIMEOUT, ReportableMediaError, } from '@amazon/vinyl';
 import { createEventSpy, useMockLogger } from '@amazon/vinyl-util/testUtil';
 import { Abort, base64ToByteArray, bufferToBase64, Deferred, ErrorLevel, ErrorOrigin, never, nextEventAsPromise, ReportableError, setUserAgent, utf16ToUint16Array, } from '@amazon/vinyl-util';
 import { flushPromises, implementEventFakes, MockHTMLAudioElement, MockMediaError, useMockTime, } from '@amazon/vinyl-util/browserTestUtil';
@@ -331,6 +331,17 @@ describe('DrmControllerImpl', () => {
                 expect(sessions.map((session) => session.dispose.calls.count())).toEqual([1, 1, 1, 1, 1, 1]); // Expect all sessions to have been disposed
                 expect(drmController.activeSessions).toEqual(0);
             });
+            it('does not close sessions again after dispose', async () => {
+                const abort = new Abort();
+                drmController.setBufferingDrmInfo(drmInfo, abort);
+                await emitEncrypted();
+                const session = mediaKeys.createSession.calls.mostRecent()
+                    .returnValue;
+                drmController.dispose();
+                const disposeCount = session.dispose.calls.count();
+                abort.abort();
+                expect(session.dispose.calls.count()).toBe(disposeCount);
+            });
         });
     });
     describe('when an encrypted event is observed', () => {
@@ -1048,6 +1059,24 @@ describe('DrmControllerImpl', () => {
             expect(drmController.isEmeSupported()).toBeFalse();
         });
     });
+    describe('excessive sessions', () => {
+        it('warns once when the open session count exceeds the threshold', async () => {
+            drmController.setBufferingDrmInfo(drmInfo);
+            // Distinct init data per event so each opens its own session.
+            for (let i = 0; i < EXCESSIVE_SESSION_COUNT; i++) {
+                await emitEncrypted(new Uint8Array([i]));
+            }
+            expect(drmController.activeSessions).toBe(EXCESSIVE_SESSION_COUNT);
+            expect(logger.value.warn).not.toHaveBeenCalled();
+            // Crossing the threshold warns.
+            await emitEncrypted(new Uint8Array([EXCESSIVE_SESSION_COUNT]));
+            expect(drmController.activeSessions).toBe(EXCESSIVE_SESSION_COUNT + 1);
+            expect(logger.value.warn).toHaveBeenCalledTimes(1);
+            // Further sessions past the threshold don't re-warn.
+            await emitEncrypted(new Uint8Array([EXCESSIVE_SESSION_COUNT + 1]));
+            expect(logger.value.warn).toHaveBeenCalledTimes(1);
+        });
+    });
     describe('closeSessions', () => {
         it('clears active sessions', async () => {
             const sessionCloseSpy = createEventSpy(drmController, 'sessionClose');

package/dist/unit/types/current/playback/createStallDetector.test.d.ts

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

package/dist/unit/types/current/playback/createStallDetector.test.d.ts.map

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