@amazon/vinyl 4.0.0 → 4.0.1-next.20261016184530

package/dist/vinylTestUtil/types/current/ui/requireUserInteraction.d.ts

@@ -1,5 +1,9 @@
 /**
- * Displays a prompt awaiting user interaction, resolving after a click, keypress, or touch event.
+ * Displays a full-page prompt, resolving after a click or key press.
+ *
+ * @param onInteraction If provided, invoked from within the click or key event handler, so that it may start media
+ * playback or resume an AudioContext. If its promise rejects, the error is logged and the prompt remains until the
+ * next interaction.
  */
-export declare function requireUserInteraction(): Promise<void>;
+export declare function requireUserInteraction(onInteraction?: () => Promise<void>): Promise<void>;
 //# sourceMappingURL=requireUserInteraction.d.ts.map

package/dist/vinylTestUtil/types/current/ui/requireUserInteraction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requireUserInteraction.d.ts","sourceRoot":"","sources":["../../../../../test/vinylTestUtil/ui/requireUserInteraction.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB5D"}
+{"version":3,"file":"requireUserInteraction.d.ts","sourceRoot":"","sources":["../../../../../test/vinylTestUtil/ui/requireUserInteraction.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CACxC,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/vinylTestUtil/types/current/ui/requireUserInteraction.js

@@ -3,23 +3,39 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 /**
- * Displays a prompt awaiting user interaction, resolving after a click, keypress, or touch event.
+ * Displays a full-page prompt, resolving after a click or key press.
+ *
+ * @param onInteraction If provided, invoked from within the click or key event handler, so that it may start media
+ * playback or resume an AudioContext. If its promise rejects, the error is logged and the prompt remains until the
+ * next interaction.
  */
-export async function requireUserInteraction() {
-    const audioPrompt = document.getElementById('unlockAudioPrompt');
-    audioPrompt.style.removeProperty('display');
-    const body = document.body;
-    body.focus();
+export async function requireUserInteraction(onInteraction) {
+    const prompt = document.getElementById('unlockAudioPrompt');
+    prompt.style.removeProperty('display');
+    prompt.querySelector('button')?.focus();
     await new Promise((resolve) => {
-        const done = () => {
-            body.removeEventListener('click', done);
-            body.removeEventListener('keypress', done);
-            body.removeEventListener('touchend', done);
-            return resolve(void 0);
+        let handling = false;
+        const handler = (event) => {
+            if (handling)
+                return;
+            handling = true;
+            const result = onInteraction?.() ?? Promise.resolve();
+            result
+                .then(() => {
+                prompt.removeEventListener('click', handler);
+                document.removeEventListener('keydown', handler);
+                resolve();
+            })
+                .catch((error) => {
+                console.warn(`The ${event.type} (isTrusted: ${event.isTrusted}) was not accepted as a user gesture; ` +
+                    'interact again.', error);
+            })
+                .finally(() => {
+                handling = false;
+            });
         };
-        body.addEventListener('click', done);
-        body.addEventListener('keypress', done);
-        body.addEventListener('touchend', done);
+        prompt.addEventListener('click', handler);
+        document.addEventListener('keydown', handler);
     });
-    audioPrompt.style.display = 'none';
+    prompt.style.display = 'none';
 }

package/dist/vinylTestUtil/types/current/util/playback/expectTrackPlays.d.ts

@@ -1,6 +1,12 @@
 import type { VinylPlayer } from '@amazon/vinyl';
 import { type TrackLoadOptions } from '@amazon/vinyl';
-export declare function expectTrackPlays(player: VinylPlayer<any>): Promise<void>;
+export interface ExpectTrackPlaysOptions {
+    /**
+     * Multiplies the time allowed to play, for environments that play slower than real time. Default: 1
+     */
+    readonly timeoutScale?: number;
+}
+export declare function expectTrackPlays(player: VinylPlayer<any>, { timeoutScale }?: ExpectTrackPlaysOptions): Promise<void>;
 /**
  * Asserts that every track in a playlist plays.
  * Has assertions for queue events, playback events, time updates, duration,
@@ -8,6 +14,7 @@ export declare function expectTrackPlays(player: VinylPlayer<any>): Promise<void
  *
  * @param player
  * @param playlist
+ * @param options
  */
-export declare function expectPlaylistPlays<T extends TrackLoadOptions>(player: VinylPlayer<T>, playlist: T[]): Promise<void>;
+export declare function expectPlaylistPlays<T extends TrackLoadOptions>(player: VinylPlayer<T>, playlist: T[], { timeoutScale }?: ExpectTrackPlaysOptions): Promise<void>;
 //# sourceMappingURL=expectTrackPlays.d.ts.map

package/dist/vinylTestUtil/types/current/util/playback/expectTrackPlays.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expectTrackPlays.d.ts","sourceRoot":"","sources":["../../../../../../test/vinylTestUtil/util/playback/expectTrackPlays.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAarD,wBAAsB,gBAAgB,CAClC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,GACzB,OAAO,CAAC,IAAI,CAAC,CAqCf;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,gBAAgB,EAChE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,QAAQ,EAAE,CAAC,EAAE,GACd,OAAO,CAAC,IAAI,CAAC,CA4Bf"}
+{"version":3,"file":"expectTrackPlays.d.ts","sourceRoot":"","sources":["../../../../../../test/vinylTestUtil/util/playback/expectTrackPlays.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAarD,MAAM,WAAW,uBAAuB;IACpC;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,wBAAsB,gBAAgB,CAClC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,EACxB,EAAE,YAAgB,EAAE,GAAE,uBAA4B,GACnD,OAAO,CAAC,IAAI,CAAC,CAuCf;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,gBAAgB,EAChE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,QAAQ,EAAE,CAAC,EAAE,EACb,EAAE,YAAgB,EAAE,GAAE,uBAA4B,GACnD,OAAO,CAAC,IAAI,CAAC,CA8Bf"}

package/dist/vinylTestUtil/types/current/util/playback/expectTrackPlays.js

@@ -12,7 +12,7 @@ import { expectTrackPlaysUntil } from './expectTrackPlaysUntil';
  * track.
  */
 const PLAYBACK_DURATION = 6;
-export async function expectTrackPlays(player) {
+export async function expectTrackPlays(player, { timeoutScale = 1 } = {}) {
     const { dispose, add } = createDisposer();
     const ended = add(createEventSpy(player, 'ended'));
     const timeUpdate = add(createEventSpy(player, 'timeUpdate'));
@@ -27,7 +27,7 @@ export async function expectTrackPlays(player) {
     if (player.duration > PLAYBACK_DURATION) {
         // For longer tracks, play from the beginning, then seek to near the end
         // All tracks will play for at most PLAYBACK_DURATION seconds.
-        await expectTrackPlaysUntil(player, player.currentTime + PLAYBACK_DURATION / 2);
+        await expectTrackPlaysUntil(player, player.currentTime + PLAYBACK_DURATION / 2, undefined, { timeoutScale });
         const time = player.duration - PLAYBACK_DURATION / 2;
         await player.seekTo(time);
     }
@@ -36,7 +36,7 @@ export async function expectTrackPlays(player) {
     // the expectation will fail due to the next track starting.
     // Add a large buffer for the timeout; Seeking in a progressive track
     // can take a long time on some browsers.
-    await ended.next(PLAYBACK_DURATION + 10);
+    await ended.next((PLAYBACK_DURATION + 10) * timeoutScale);
     expect(player.currentTime).toBeCloseToWithin(duration, 3);
     expect(player.ended).withContext('ended').toBeTrue();
     // Expect at least one update per second. This varies among platforms.
@@ -50,11 +50,12 @@ export async function expectTrackPlays(player) {
  *
  * @param player
  * @param playlist
+ * @param options
  */
-export async function expectPlaylistPlays(player, playlist) {
+export async function expectPlaylistPlays(player, playlist, { timeoutScale = 1 } = {}) {
     const { dispose, add } = createDisposer();
     // Add a significant buffer to the timeout; progressive tracks can take a long time to load after a seek.
-    const trackTimeout = PLAYBACK_DURATION + 60; // Timeout to give each track
+    const trackTimeout = (PLAYBACK_DURATION + 60) * timeoutScale; // Timeout to give each track
     const queueEnded = add(createEventSpy(player, 'queueEnded'));
     const queueChange = add(createEventSpy(player, 'queueChange'));
     const trackChange = add(createEventSpy(player, 'trackActivated'));
@@ -73,8 +74,10 @@ export async function expectPlaylistPlays(player, playlist) {
         const nextTrack = isLastTrack
             ? queueEnded.next(trackTimeout)
             : trackChange.next(trackTimeout);
-        await expectTrackPlays(player);
-        await nextTrack;
+        await Promise.all([
+            expectTrackPlays(player, { timeoutScale }),
+            nextTrack,
+        ]);
         assertQueueChangeCount(isLastTrack ? 0 : 1);
     }
     dispose();

package/dist/vinylTestUtil/types/current/util/playback/expectTrackPlaysUntil.d.ts

@@ -7,6 +7,9 @@ import type { ReadonlyPlaybackController } from '@amazon/vinyl';
  * @param endTime
  * @param timeout A timeout beyond the expected amount of time to play.
  * This does not affect waiting for ready state.
+ * @param timeoutScale Multiplies the time allowed to play, for environments that play slower than real time.
  */
-export declare function expectTrackPlaysUntil(player: ReadonlyPlaybackController, endTime: number, timeout?: number): Promise<void>;
+export declare function expectTrackPlaysUntil(player: ReadonlyPlaybackController, endTime: number, timeout?: number, { timeoutScale }?: {
+    readonly timeoutScale?: number;
+}): Promise<void>;
 //# sourceMappingURL=expectTrackPlaysUntil.d.ts.map

package/dist/vinylTestUtil/types/current/util/playback/expectTrackPlaysUntil.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expectTrackPlaysUntil.d.ts","sourceRoot":"","sources":["../../../../../../test/vinylTestUtil/util/playback/expectTrackPlaysUntil.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAA;AAO/D;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACvC,MAAM,EAAE,0BAA0B,EAClC,OAAO,EAAE,MAAM,EACf,OAAO,SAAK,iBA2Bf"}
+{"version":3,"file":"expectTrackPlaysUntil.d.ts","sourceRoot":"","sources":["../../../../../../test/vinylTestUtil/util/playback/expectTrackPlaysUntil.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAA;AAO/D;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACvC,MAAM,EAAE,0BAA0B,EAClC,OAAO,EAAE,MAAM,EACf,OAAO,SAAK,EACZ,EAAE,YAAgB,EAAE,GAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,iBA2BhE"}

package/dist/vinylTestUtil/types/current/util/playback/expectTrackPlaysUntil.js

@@ -16,8 +16,9 @@ const affordanceAfter = 3;
  * @param endTime
  * @param timeout A timeout beyond the expected amount of time to play.
  * This does not affect waiting for ready state.
+ * @param timeoutScale Multiplies the time allowed to play, for environments that play slower than real time.
  */
-export async function expectTrackPlaysUntil(player, endTime, timeout = 20) {
+export async function expectTrackPlaysUntil(player, endTime, timeout = 20, { timeoutScale = 1 } = {}) {
     await onPlaying(player);
     // Safari does not always have an updated currentTime after a seeked event. Await the next time update before
     // asserting currentTime values.
@@ -29,7 +30,7 @@ export async function expectTrackPlaysUntil(player, endTime, timeout = 20) {
     const startedBeforeEnd = player.currentTime < endTime;
     await assertFrequency();
     let elapsed = 0;
-    const maxTime = endTime - player.currentTime + timeout;
+    const maxTime = (endTime - player.currentTime + timeout) * timeoutScale;
     while (!player.ended && player.currentTime < endTime && elapsed < maxTime) {
         await sleep(sleepInterval);
         elapsed += sleepInterval;

package/dist/vinylTestUtil/types/ts3.7/media/FrequencyAnalyzer.d.ts

@@ -29,6 +29,11 @@ export declare class FrequencyAnalyzer implements LogTarget {
      */
     assertFrequency(timeout?: number): Promise<void>;
 }
+/**
+ * The volume integ tests play at when checkAudio is set. Analyzers do not work at volume 0 or muted, and the
+ * measured dB is affected at very low volumes.
+ */
+export declare const ANALYZER_VOLUME = 0.01;
 /**
  * A query param, if present, will indicate that audio should be analyzed. Does not work in CI environments.
  */
@@ -39,12 +44,10 @@ export declare const shouldCheckAudio: boolean;
  */
 export declare function assertFrequency(): Promise<void>;
 /**
- * Displays an interaction prompt if checkAudio is present in the query params.
+ * Attaches an analyzer to the shared media element if checkAudio is present in the query params.
  *
- * The checkAudio query param, if present, indicates that the actual sound output should be analyzed. This requires
- * a user gesture unless the UA doesn't require it. Most browsers require the gesture, but some platforms this
- * requirement may be skipped with a flag. Note that Google deprecated --autoplay-policy=no-user-gesture-required
- * March 2023, but older versions may still support it.
+ * The checkAudio query param, if present, indicates that the actual sound output should be analyzed. The analyzer is
+ * created after the media element is unlocked, so `initializeMediaUnlock` must be called first.
  */
 export declare function initializeFrequencyAnalyzer(): void;
 //# sourceMappingURL=FrequencyAnalyzer.d.ts.map

package/dist/vinylTestUtil/types/ts3.7/media/unlockMediaElement.d.ts

@@ -1,6 +1,15 @@
 /**
- * In response to a user-gesture, 'unlocks' the media element by playing and immediately pausing a src track.
+ * 'Unlocks' the media element by playing and immediately pausing a src track, and resumes the AudioContext.
  * This allows play() to settle on the media element without a user gesture later.
+ *
+ * Must be called synchronously from a user gesture handler. Rejects if the browser did not accept the gesture.
  */
 export declare function unlockMediaElement(): Promise<void>;
+/**
+ * In a browser, prompts for a click before any spec runs, unlocking the shared media element in response.
+ *
+ * Starting playback without a user gesture is only allowed for muted media, and some browsers (Safari 27)
+ * end progressive playback that starts silently without one, so integ tests play unmuted after this unlock.
+ */
+export declare function initializeMediaUnlock(): void;
 //# sourceMappingURL=unlockMediaElement.d.ts.map

package/dist/vinylTestUtil/types/ts3.7/player/mediaRef.d.ts

@@ -1,6 +1,13 @@
+/**
+ * The volume integ tests play at: low enough not to be heard, but not 0 or muted. Safari 27 ends progressive
+ * playback that starts silently without a user gesture, and the media element is unlocked at this volume.
+ */
+export declare const MEDIA_VOLUME = 0.0001;
 /**
  * For reliable integ tests on 3P devices, there should be a single media element.
  * When using the media element, unload any sources and reset any state after each test.
+ *
+ * The element is unmuted at {@link MEDIA_VOLUME}; see `initializeMediaUnlock`.
  */
 export declare const mediaRef: import("@amazon/vinyl-util").Lazy<HTMLMediaElement>;
 //# sourceMappingURL=mediaRef.d.ts.map

package/dist/vinylTestUtil/types/ts3.7/ui/requireUserInteraction.d.ts

@@ -1,5 +1,9 @@
 /**
- * Displays a prompt awaiting user interaction, resolving after a click, keypress, or touch event.
+ * Displays a full-page prompt, resolving after a click or key press.
+ *
+ * @param onInteraction If provided, invoked from within the click or key event handler, so that it may start media
+ * playback or resume an AudioContext. If its promise rejects, the error is logged and the prompt remains until the
+ * next interaction.
  */
-export declare function requireUserInteraction(): Promise<void>;
+export declare function requireUserInteraction(onInteraction?: () => Promise<void>): Promise<void>;
 //# sourceMappingURL=requireUserInteraction.d.ts.map

package/dist/vinylTestUtil/types/ts3.7/util/playback/expectTrackPlays.d.ts

@@ -1,6 +1,12 @@
 import { VinylPlayer } from '@amazon/vinyl';
 import { TrackLoadOptions } from '@amazon/vinyl';
-export declare function expectTrackPlays(player: VinylPlayer<any>): Promise<void>;
+export interface ExpectTrackPlaysOptions {
+    /**
+     * Multiplies the time allowed to play, for environments that play slower than real time. Default: 1
+     */
+    readonly timeoutScale?: number;
+}
+export declare function expectTrackPlays(player: VinylPlayer<any>, { timeoutScale }?: ExpectTrackPlaysOptions): Promise<void>;
 /**
  * Asserts that every track in a playlist plays.
  * Has assertions for queue events, playback events, time updates, duration,
@@ -8,6 +14,7 @@ export declare function expectTrackPlays(player: VinylPlayer<any>): Promise<void
  *
  * @param player
  * @param playlist
+ * @param options
  */
-export declare function expectPlaylistPlays<T extends TrackLoadOptions>(player: VinylPlayer<T>, playlist: T[]): Promise<void>;
+export declare function expectPlaylistPlays<T extends TrackLoadOptions>(player: VinylPlayer<T>, playlist: T[], { timeoutScale }?: ExpectTrackPlaysOptions): Promise<void>;
 //# sourceMappingURL=expectTrackPlays.d.ts.map

package/dist/vinylTestUtil/types/ts3.7/util/playback/expectTrackPlaysUntil.d.ts

@@ -7,6 +7,9 @@ import { ReadonlyPlaybackController } from '@amazon/vinyl';
  * @param endTime
  * @param timeout A timeout beyond the expected amount of time to play.
  * This does not affect waiting for ready state.
+ * @param timeoutScale Multiplies the time allowed to play, for environments that play slower than real time.
  */
-export declare function expectTrackPlaysUntil(player: ReadonlyPlaybackController, endTime: number, timeout?: number): Promise<void>;
+export declare function expectTrackPlaysUntil(player: ReadonlyPlaybackController, endTime: number, timeout?: number, { timeoutScale }?: {
+    readonly timeoutScale?: number;
+}): Promise<void>;
 //# sourceMappingURL=expectTrackPlaysUntil.d.ts.map

package/dist/vinylTestUtil/types/ts4.1/media/FrequencyAnalyzer.d.ts

@@ -29,6 +29,11 @@ export declare class FrequencyAnalyzer implements LogTarget {
      */
     assertFrequency(timeout?: number): Promise<void>;
 }
+/**
+ * The volume integ tests play at when checkAudio is set. Analyzers do not work at volume 0 or muted, and the
+ * measured dB is affected at very low volumes.
+ */
+export declare const ANALYZER_VOLUME = 0.01;
 /**
  * A query param, if present, will indicate that audio should be analyzed. Does not work in CI environments.
  */
@@ -39,12 +44,10 @@ export declare const shouldCheckAudio: boolean;
  */
 export declare function assertFrequency(): Promise<void>;
 /**
- * Displays an interaction prompt if checkAudio is present in the query params.
+ * Attaches an analyzer to the shared media element if checkAudio is present in the query params.
  *
- * The checkAudio query param, if present, indicates that the actual sound output should be analyzed. This requires
- * a user gesture unless the UA doesn't require it. Most browsers require the gesture, but some platforms this
- * requirement may be skipped with a flag. Note that Google deprecated --autoplay-policy=no-user-gesture-required
- * March 2023, but older versions may still support it.
+ * The checkAudio query param, if present, indicates that the actual sound output should be analyzed. The analyzer is
+ * created after the media element is unlocked, so `initializeMediaUnlock` must be called first.
  */
 export declare function initializeFrequencyAnalyzer(): void;
 //# sourceMappingURL=FrequencyAnalyzer.d.ts.map

package/dist/vinylTestUtil/types/ts4.1/media/unlockMediaElement.d.ts

@@ -1,6 +1,15 @@
 /**
- * In response to a user-gesture, 'unlocks' the media element by playing and immediately pausing a src track.
+ * 'Unlocks' the media element by playing and immediately pausing a src track, and resumes the AudioContext.
  * This allows play() to settle on the media element without a user gesture later.
+ *
+ * Must be called synchronously from a user gesture handler. Rejects if the browser did not accept the gesture.
  */
 export declare function unlockMediaElement(): Promise<void>;
+/**
+ * In a browser, prompts for a click before any spec runs, unlocking the shared media element in response.
+ *
+ * Starting playback without a user gesture is only allowed for muted media, and some browsers (Safari 27)
+ * end progressive playback that starts silently without one, so integ tests play unmuted after this unlock.
+ */
+export declare function initializeMediaUnlock(): void;
 //# sourceMappingURL=unlockMediaElement.d.ts.map

package/dist/vinylTestUtil/types/ts4.1/player/mediaRef.d.ts

@@ -1,6 +1,13 @@
+/**
+ * The volume integ tests play at: low enough not to be heard, but not 0 or muted. Safari 27 ends progressive
+ * playback that starts silently without a user gesture, and the media element is unlocked at this volume.
+ */
+export declare const MEDIA_VOLUME = 0.0001;
 /**
  * For reliable integ tests on 3P devices, there should be a single media element.
  * When using the media element, unload any sources and reset any state after each test.
+ *
+ * The element is unmuted at {@link MEDIA_VOLUME}; see `initializeMediaUnlock`.
  */
 export declare const mediaRef: import("@amazon/vinyl-util").Lazy<HTMLMediaElement>;
 //# sourceMappingURL=mediaRef.d.ts.map

package/dist/vinylTestUtil/types/ts4.1/ui/requireUserInteraction.d.ts

@@ -1,5 +1,9 @@
 /**
- * Displays a prompt awaiting user interaction, resolving after a click, keypress, or touch event.
+ * Displays a full-page prompt, resolving after a click or key press.
+ *
+ * @param onInteraction If provided, invoked from within the click or key event handler, so that it may start media
+ * playback or resume an AudioContext. If its promise rejects, the error is logged and the prompt remains until the
+ * next interaction.
  */
-export declare function requireUserInteraction(): Promise<void>;
+export declare function requireUserInteraction(onInteraction?: () => Promise<void>): Promise<void>;
 //# sourceMappingURL=requireUserInteraction.d.ts.map

package/dist/vinylTestUtil/types/ts4.1/util/playback/expectTrackPlays.d.ts

@@ -1,6 +1,12 @@
 import type { VinylPlayer } from '@amazon/vinyl';
 import type { TrackLoadOptions } from '@amazon/vinyl';
-export declare function expectTrackPlays(player: VinylPlayer<any>): Promise<void>;
+export interface ExpectTrackPlaysOptions {
+    /**
+     * Multiplies the time allowed to play, for environments that play slower than real time. Default: 1
+     */
+    readonly timeoutScale?: number;
+}
+export declare function expectTrackPlays(player: VinylPlayer<any>, { timeoutScale }?: ExpectTrackPlaysOptions): Promise<void>;
 /**
  * Asserts that every track in a playlist plays.
  * Has assertions for queue events, playback events, time updates, duration,
@@ -8,6 +14,7 @@ export declare function expectTrackPlays(player: VinylPlayer<any>): Promise<void
  *
  * @param player
  * @param playlist
+ * @param options
  */
-export declare function expectPlaylistPlays<T extends TrackLoadOptions>(player: VinylPlayer<T>, playlist: T[]): Promise<void>;
+export declare function expectPlaylistPlays<T extends TrackLoadOptions>(player: VinylPlayer<T>, playlist: T[], { timeoutScale }?: ExpectTrackPlaysOptions): Promise<void>;
 //# sourceMappingURL=expectTrackPlays.d.ts.map

package/dist/vinylTestUtil/types/ts4.1/util/playback/expectTrackPlaysUntil.d.ts

@@ -7,6 +7,9 @@ import type { ReadonlyPlaybackController } from '@amazon/vinyl';
  * @param endTime
  * @param timeout A timeout beyond the expected amount of time to play.
  * This does not affect waiting for ready state.
+ * @param timeoutScale Multiplies the time allowed to play, for environments that play slower than real time.
  */
-export declare function expectTrackPlaysUntil(player: ReadonlyPlaybackController, endTime: number, timeout?: number): Promise<void>;
+export declare function expectTrackPlaysUntil(player: ReadonlyPlaybackController, endTime: number, timeout?: number, { timeoutScale }?: {
+    readonly timeoutScale?: number;
+}): Promise<void>;
 //# sourceMappingURL=expectTrackPlaysUntil.d.ts.map

package/dist/vinylTestUtil/types/ts4.7/media/FrequencyAnalyzer.d.ts

@@ -35,6 +35,11 @@ export declare class FrequencyAnalyzer implements LogTarget {
      */
     assertFrequency(timeout?: number): Promise<void>;
 }
+/**
+ * The volume integ tests play at when checkAudio is set. Analyzers do not work at volume 0 or muted, and the
+ * measured dB is affected at very low volumes.
+ */
+export declare const ANALYZER_VOLUME = 0.01;
 /**
  * A query param, if present, will indicate that audio should be analyzed. Does not work in CI environments.
  */
@@ -45,12 +50,10 @@ export declare const shouldCheckAudio: boolean;
  */
 export declare function assertFrequency(): Promise<void>;
 /**
- * Displays an interaction prompt if checkAudio is present in the query params.
+ * Attaches an analyzer to the shared media element if checkAudio is present in the query params.
  *
- * The checkAudio query param, if present, indicates that the actual sound output should be analyzed. This requires
- * a user gesture unless the UA doesn't require it. Most browsers require the gesture, but some platforms this
- * requirement may be skipped with a flag. Note that Google deprecated --autoplay-policy=no-user-gesture-required
- * March 2023, but older versions may still support it.
+ * The checkAudio query param, if present, indicates that the actual sound output should be analyzed. The analyzer is
+ * created after the media element is unlocked, so `initializeMediaUnlock` must be called first.
  */
 export declare function initializeFrequencyAnalyzer(): void;
 //# sourceMappingURL=FrequencyAnalyzer.d.ts.map

package/dist/vinylTestUtil/types/ts4.7/media/unlockMediaElement.d.ts

@@ -1,6 +1,15 @@
 /**
- * In response to a user-gesture, 'unlocks' the media element by playing and immediately pausing a src track.
+ * 'Unlocks' the media element by playing and immediately pausing a src track, and resumes the AudioContext.
  * This allows play() to settle on the media element without a user gesture later.
+ *
+ * Must be called synchronously from a user gesture handler. Rejects if the browser did not accept the gesture.
  */
 export declare function unlockMediaElement(): Promise<void>;
+/**
+ * In a browser, prompts for a click before any spec runs, unlocking the shared media element in response.
+ *
+ * Starting playback without a user gesture is only allowed for muted media, and some browsers (Safari 27)
+ * end progressive playback that starts silently without one, so integ tests play unmuted after this unlock.
+ */
+export declare function initializeMediaUnlock(): void;
 //# sourceMappingURL=unlockMediaElement.d.ts.map

package/dist/vinylTestUtil/types/ts4.7/player/mediaRef.d.ts

@@ -1,6 +1,13 @@
+/**
+ * The volume integ tests play at: low enough not to be heard, but not 0 or muted. Safari 27 ends progressive
+ * playback that starts silently without a user gesture, and the media element is unlocked at this volume.
+ */
+export declare const MEDIA_VOLUME = 0.0001;
 /**
  * For reliable integ tests on 3P devices, there should be a single media element.
  * When using the media element, unload any sources and reset any state after each test.
+ *
+ * The element is unmuted at {@link MEDIA_VOLUME}; see `initializeMediaUnlock`.
  */
 export declare const mediaRef: import("@amazon/vinyl-util").Lazy<HTMLMediaElement>;
 //# sourceMappingURL=mediaRef.d.ts.map

package/dist/vinylTestUtil/types/ts4.7/ui/requireUserInteraction.d.ts

@@ -1,5 +1,9 @@
 /**
- * Displays a prompt awaiting user interaction, resolving after a click, keypress, or touch event.
+ * Displays a full-page prompt, resolving after a click or key press.
+ *
+ * @param onInteraction If provided, invoked from within the click or key event handler, so that it may start media
+ * playback or resume an AudioContext. If its promise rejects, the error is logged and the prompt remains until the
+ * next interaction.
  */
-export declare function requireUserInteraction(): Promise<void>;
+export declare function requireUserInteraction(onInteraction?: () => Promise<void>): Promise<void>;
 //# sourceMappingURL=requireUserInteraction.d.ts.map

package/dist/vinylTestUtil/types/ts4.7/util/playback/expectTrackPlays.d.ts

@@ -1,6 +1,12 @@
 import type { VinylPlayer } from '@amazon/vinyl';
 import { type TrackLoadOptions } from '@amazon/vinyl';
-export declare function expectTrackPlays(player: VinylPlayer<any>): Promise<void>;
+export interface ExpectTrackPlaysOptions {
+    /**
+     * Multiplies the time allowed to play, for environments that play slower than real time. Default: 1
+     */
+    readonly timeoutScale?: number;
+}
+export declare function expectTrackPlays(player: VinylPlayer<any>, { timeoutScale }?: ExpectTrackPlaysOptions): Promise<void>;
 /**
  * Asserts that every track in a playlist plays.
  * Has assertions for queue events, playback events, time updates, duration,
@@ -8,6 +14,7 @@ export declare function expectTrackPlays(player: VinylPlayer<any>): Promise<void
  *
  * @param player
  * @param playlist
+ * @param options
  */
-export declare function expectPlaylistPlays<T extends TrackLoadOptions>(player: VinylPlayer<T>, playlist: T[]): Promise<void>;
+export declare function expectPlaylistPlays<T extends TrackLoadOptions>(player: VinylPlayer<T>, playlist: T[], { timeoutScale }?: ExpectTrackPlaysOptions): Promise<void>;
 //# sourceMappingURL=expectTrackPlays.d.ts.map

package/dist/vinylTestUtil/types/ts4.7/util/playback/expectTrackPlaysUntil.d.ts

@@ -7,6 +7,9 @@ import type { ReadonlyPlaybackController } from '@amazon/vinyl';
  * @param endTime
  * @param timeout A timeout beyond the expected amount of time to play.
  * This does not affect waiting for ready state.
+ * @param timeoutScale Multiplies the time allowed to play, for environments that play slower than real time.
  */
-export declare function expectTrackPlaysUntil(player: ReadonlyPlaybackController, endTime: number, timeout?: number): Promise<void>;
+export declare function expectTrackPlaysUntil(player: ReadonlyPlaybackController, endTime: number, timeout?: number, { timeoutScale }?: {
+    readonly timeoutScale?: number;
+}): Promise<void>;
 //# sourceMappingURL=expectTrackPlaysUntil.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@amazon/vinyl",
-    "version": "4.0.0",
+    "version": "4.0.1-next.20261016184530",
     "description": "An HTML5 streaming media player",
     "repository": {
         "type": "git",
@@ -81,6 +81,7 @@
         "test": "tsx ../../node_modules/jasmine/bin/jasmine --config=test/unit/jasmine.config.json",
         "test:coverage": "c8 npm run test",
         "test:browserstack": "npm run build:release && tsx buildSrc/runBrowserStack.ts",
+        "test:integ": "npm run build:release && tsx buildSrc/runInteg.ts",
         "benchmark:abr": "tsx test/abrBenchmark/run.ts",
         "start": "tsx buildSrc/build.ts --serve",
         "start:release": "tsx buildSrc/build.ts --serve --release",
@@ -90,18 +91,18 @@
         "oxlint:write": "oxlint --type-aware --fix"
     },
     "devDependencies": {
-        "@amazon/vinyl-browserstack": "^4.0.0",
-        "@amazon/vinyl-build-utils": "^4.0.0",
+        "@amazon/vinyl-browserstack": "4.0.1-next.20261016184530",
+        "@amazon/vinyl-build-utils": "4.0.1-next.20261016184530",
         "commander": "^15.0.0"
     },
     "dependencies": {
-        "@amazon/vinyl-di": "^4.0.0",
-        "@amazon/vinyl-hls-parser": "^4.0.0",
-        "@amazon/vinyl-mpd-parser": "^4.0.0",
-        "@amazon/vinyl-observable": "^4.0.0",
-        "@amazon/vinyl-transmux": "^4.0.0",
-        "@amazon/vinyl-util": "^4.0.0",
-        "@amazon/vinyl-validation": "^4.0.0"
+        "@amazon/vinyl-di": "4.0.1-next.20261016184530",
+        "@amazon/vinyl-hls-parser": "4.0.1-next.20261016184530",
+        "@amazon/vinyl-mpd-parser": "4.0.1-next.20261016184530",
+        "@amazon/vinyl-observable": "4.0.1-next.20261016184530",
+        "@amazon/vinyl-transmux": "4.0.1-next.20261016184530",
+        "@amazon/vinyl-util": "4.0.1-next.20261016184530",
+        "@amazon/vinyl-validation": "4.0.1-next.20261016184530"
     },
     "publishConfig": {
         "access": "public"