@amazon/vinyl 3.1.0 → 3.2.1

package/dist/types/ts4.7/vinyl/VinylPlayer.d.ts

@@ -66,6 +66,11 @@ export declare class VinylPlayer<TrackLoadOptionsType extends TrackLoadOptions =
      * @see createVinylPlayer
      */
     protected constructor(factories: Factories<VinylDeps<TrackLoadOptionsType, OptionsType>>);
+    /**
+     * Logs each republished load span once at the verbose level, formatting its
+     * bounds as ISO date strings and its duration in milliseconds.
+     */
+    protected initializeLoadSpanLogging(): void;
     protected redispatchSubControllerEvents(): void;
     /**
      * Certain track events are redispatched on the player for the current track.

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

@@ -896,7 +896,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',
@@ -990,7 +989,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,
@@ -999,7 +1002,7 @@ describe('AdControllerImpl', () => {
                     {
                         id: 'a1',
                         startTime: 0,
-                        duration: 5,
+                        duration: 5, // declared, server-rounded
                         uri: 'ad1.m3u8',
                     },
                     {
@@ -1014,10 +1017,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 = [];
@@ -1053,6 +1100,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/drm/DrmControllerImpl.test.js

@@ -950,28 +950,70 @@ describe('DrmControllerImpl', () => {
             drmController.setBufferingDrmInfo(drmInfo);
             await emitEncrypted(new Uint8Array([1, 2, 3]), 'cenc');
             await emitMessage(0, new ArrayBuffer(1));
-            expect(spy).toHaveBeenCalledOnceWith(objectContaining({
+            expect(spy).toHaveBeenCalledWith(objectContaining({
                 kind: 'license',
                 startTime: any(Number),
                 endTime: any(Number),
             }));
         });
+        it('measures the key setup, contiguous with and before the license', async () => {
+            licenseProvider.and.resolveTo(new Uint8Array([1]).buffer);
+            const spy = createEventSpy(drmController, 'loadSpanMeasured');
+            drmController.setBufferingDrmInfo(drmInfo, { trackUri: 'track-a' });
+            await emitEncrypted(new Uint8Array([1, 2, 3]), 'cenc');
+            await emitMessage(0, new ArrayBuffer(1));
+            const spans = spy.calls.all().map((call) => call.args[0]);
+            expect(spans.map((span) => span.kind)).toEqual([
+                'keySetup',
+                'license',
+            ]);
+            const [keySetup, license] = spans;
+            expect(keySetup.trackUri).toEqual('track-a');
+            expect(keySetup.endTime).toEqual(license.startTime);
+        });
+        it('carries the content mime and content type on the license span', async () => {
+            licenseProvider.and.resolveTo(new Uint8Array([1]).buffer);
+            const spy = createEventSpy(drmController, 'loadSpanMeasured');
+            drmController.setBufferingDrmInfo(drmInfo);
+            await emitEncrypted(new Uint8Array([1, 2, 3]), 'cenc');
+            await emitMessage(0, new ArrayBuffer(1));
+            expect(spy).toHaveBeenCalledWith(objectContaining({
+                kind: 'license',
+                mimeType: 'audio/mp4',
+                contentType: 'audio',
+            }));
+        });
         it('does not measure a failed license exchange', async () => {
             licenseProvider.and.rejectWith(new Error('license failed'));
             const spy = createEventSpy(drmController, 'loadSpanMeasured');
             drmController.setBufferingDrmInfo(drmInfo);
             await emitEncrypted(new Uint8Array([1, 2, 3]), 'cenc');
             await emitMessage(0, new ArrayBuffer(1));
-            expect(spy).not.toHaveBeenCalled();
+            // Setup completed at the message, so keySetup is still measured.
+            expect(spy).not.toHaveBeenCalledWith(objectContaining({ kind: 'license' }));
             errorSpy.calls.reset();
         });
+        it('measures key setup only for the first session of a track load', async () => {
+            licenseProvider.and.resolveTo(new Uint8Array([1]).buffer);
+            const spy = createEventSpy(drmController, 'loadSpanMeasured');
+            drmController.setBufferingDrmInfo(drmInfo, { trackUri: 'track-a' });
+            await emitEncrypted(new Uint8Array([1]), 'cenc');
+            await emitEncrypted(new Uint8Array([2]), 'cenc');
+            expect(mediaKeys.createSession).toHaveBeenCalledTimes(2);
+            await emitMessage(0, new ArrayBuffer(1));
+            await emitMessage(1, new ArrayBuffer(1));
+            const keySetupSpans = spy.calls
+                .all()
+                .filter((call) => call.args[0].kind === 'keySetup');
+            expect(keySetupSpans.length).toEqual(1);
+        });
         it('attributes the license span to the buffering track uri', async () => {
             licenseProvider.and.resolveTo(new Uint8Array([1]).buffer);
             const spy = createEventSpy(drmController, 'loadSpanMeasured');
             drmController.setBufferingDrmInfo(drmInfo, { trackUri: 'track-a' });
             await emitEncrypted(new Uint8Array([1, 2, 3]), 'cenc');
             await emitMessage(0, new ArrayBuffer(1));
-            expect(spy).toHaveBeenCalledOnceWith(objectContaining({
+            expect(spy).toHaveBeenCalledWith(objectContaining({
                 kind: 'license',
                 trackUri: 'track-a',
             }));
@@ -1005,12 +1047,14 @@ describe('DrmControllerImpl', () => {
             // on the controller's current buffering track.
             await emitMessage(1, new ArrayBuffer(1));
             await emitMessage(0, new ArrayBuffer(1));
-            expect(spy).toHaveBeenCalledTimes(2);
-            expect(spy).toHaveBeenCalledWith(objectContaining({
-                kind: 'license',
-                trackUri: 'track-preloaded',
-            }));
-            expect(spy).toHaveBeenCalledWith(objectContaining({ kind: 'license', trackUri: 'track-active' }));
+            const licenseTrackUris = spy.calls
+                .all()
+                .map((call) => call.args[0])
+                .filter((span) => span.kind === 'license')
+                .map((span) => span.trackUri);
+            expect(licenseTrackUris.length).toEqual(2);
+            expect(licenseTrackUris).toContain('track-preloaded');
+            expect(licenseTrackUris).toContain('track-active');
         });
     });
     describe('serverCertificate', () => {

package/dist/unit/types/current/playback/createStallMonitor.test.js

@@ -115,10 +115,48 @@ describe('createStallMonitor', () => {
         expect(onStallEntered).toHaveBeenCalledTimes(2);
         expect(onStallEnded).toHaveBeenCalledTimes(2);
     });
+    it('does not end and re-detect a stall on a non-advancing timeUpdate', async () => {
+        // Browsers emit `timeUpdate` even while the play head is frozen, with an unchanged (or
+        // briefly backward) currentTime. These must not be treated as progress, or the stall is
+        // ended and immediately re-detected, doubling the reported events.
+        monitor();
+        host.dispatch('playing', {});
+        host.dispatch('timeUpdate', { previous: 4, current: 5 });
+        await poll(4); // freeze 1s -> stallEntered
+        expect(onStallEntered).toHaveBeenCalledTimes(1);
+        // Still frozen: currentTime hasn't advanced (unchanged, backward, or sub-epsilon jitter).
+        host.dispatch('timeUpdate', { previous: 5, current: 5 });
+        host.dispatch('timeUpdate', { previous: 5, current: 4.99 });
+        host.dispatch('timeUpdate', { previous: 5, current: 5 + 1e-9 });
+        await poll(4);
+        expect(onStallEnded).not.toHaveBeenCalled();
+        expect(onStallEntered).toHaveBeenCalledTimes(1);
+        // A real forward advance ends the stall exactly once.
+        host.dispatch('timeUpdate', { previous: 5, current: 6 });
+        expect(onStallEnded).toHaveBeenCalledTimes(1);
+        expect(onStallEntered).toHaveBeenCalledTimes(1);
+    });
+    it('does not re-detect a stall immediately after resuming via a playing event', async () => {
+        // Resuming via `playing` must restart the freeze clock. Otherwise the poll, still seeing
+        // the stale pre-freeze progress time, immediately re-enters a stall before the first
+        // post-resume timeUpdate arrives — an extra, spurious stall.
+        monitor();
+        host.dispatch('playing', {});
+        host.dispatch('timeUpdate', { previous: 0, current: 1 });
+        await poll(4); // freeze 1s -> stallEntered
+        expect(onStallEntered).toHaveBeenCalledTimes(1);
+        // Resume with a 'playing' event and no timeUpdate yet.
+        host.dispatch('playing', {});
+        expect(onStallEnded).toHaveBeenCalledTimes(1);
+        // The freeze clock reset on resume, so a sub-threshold gap is not a new stall.
+        await poll(3); // 0.75s < 1s threshold
+        expect(onStallEntered).toHaveBeenCalledTimes(1);
+    });
     it('stops reporting after disposal', async () => {
         monitor();
         host.dispatch('playing', {});
         stop();
+        stop = undefined; // disposal is single-shot; don't dispose again in afterEach
         await poll(8);
         expect(onStallEntered).not.toHaveBeenCalled();
     });

package/dist/unit/types/current/streaming/MseTrack.test.js

@@ -7,7 +7,7 @@ import { createMockDashDependencies, } from '@amazon/vinyl/vinylTestUtil';
 import { createEventSpy, useMockLogger } from '@amazon/vinyl-util/testUtil';
 import { flushPromises } from '@amazon/vinyl-util/browserTestUtil';
 import { externalDependencies } from '@amazon/vinyl-di';
-import { Abort, MediaUnsupportedError } from '@amazon/vinyl-util';
+import { Abort } from '@amazon/vinyl-util';
 var any = jasmine.any;
 describe('MseTrack', () => {
     useMockLogger();
@@ -585,11 +585,12 @@ describe('MseTrack', () => {
             expect(track.qualities).toEqual([qualityMetadata]);
             expect(track.qualitiesUnfiltered).toEqual([qualityMetadata]);
         });
-        it('fails fast when a required content type is entirely filtered out', async () => {
-            // contentTypes (from the manifest) is {audio, video}, but the
-            // transformed timeline has only a video quality — audio was fully
-            // filtered. The audio stream could never create a source buffer, so
-            // the track must fail rather than stall on the readyToAppend wait.
+        it('plays the surviving content type when another is entirely filtered out', async () => {
+            // The content types now come from the FILTERED timeline: with every
+            // audio rendition filtered, only 'video' is required. No audio stream
+            // is created, so the load is never stranded waiting for an audio
+            // source buffer that will never arrive, and the track does not error.
+            deps.contentTypesValue.value = Promise.resolve(new Set(['video']));
             const videoQuality = {
                 ...createEmptyMediaQualityMetadata(),
                 contentType: 'video',
@@ -614,8 +615,10 @@ describe('MseTrack', () => {
             });
             track = createTrack();
             await flushPromises();
-            expect(track.error).toEqual(any(MediaUnsupportedError));
-            expect(track.error.code).toBe('no-playable-audio');
+            expect(track.error).toBeNull();
+            expect(track.contentTypes).toEqual(new Set(['video']));
+            expect(getStream('video')).not.toBeNull();
+            expect(getStream('audio')).toBeNull();
         });
         it('reads qualities from the filtered timeline but qualitiesUnfiltered from the raw one', async () => {
             // The transformed timeline is filtered (e.g. by preferred audio

package/dist/unit/types/current/streaming/mediaTimelineFilter.test.js

@@ -13,81 +13,87 @@ function createQuality(contentType, bandwidth) {
         getSegment: () => Promise.resolve(null),
     };
 }
-describe('filterTimelineQualities', () => {
-    const timeline = {
-        periods: [
-            {
-                startTime: 0,
-                endTime: 10,
-                qualities: [
-                    createQuality('audio', 128000),
-                    createQuality('audio', 256000),
-                    createQuality('video', 500000),
-                ],
-            },
-        ],
+function timelineOf(qualities) {
+    return {
+        periods: [{ startTime: 0, endTime: 10, qualities: [...qualities] }],
         minBufferTime: 2,
         getAdBreaks: () => Promise.resolve([]),
         getDuration: () => Promise.resolve(Infinity),
     };
+}
+function contentTypesOf(timeline) {
+    return new Set(timeline.periods[0].qualities.map((q) => q.metadata.contentType));
+}
+function throwEmpty() {
+    throw new Error('no qualities');
+}
+describe('filterTimelineQualities', () => {
+    const timeline = timelineOf([
+        createQuality('audio', 128000),
+        createQuality('audio', 256000),
+        createQuality('video', 500000),
+    ]);
     it('returns the timeline unchanged when the filter is null', () => {
         // A null predicate (e.g. no language preference) is a no-op.
-        const result = filterTimelineQualities(null, () => {
-            throw new Error('empty');
-        }, timeline);
+        const result = filterTimelineQualities(null, throwEmpty, timeline);
         expect(result).toBe(timeline);
     });
-    it('filters qualities by predicate', () => {
-        const result = filterTimelineQualities((q) => q.contentType === 'audio', () => {
-            throw new Error('empty');
-        }, timeline);
+    it('filters qualities by predicate while keeping every present stream', () => {
+        const result = filterTimelineQualities((q) => q.bandwidth !== 256000, throwEmpty, timeline);
         expect(result.periods[0].qualities.length).toBe(2);
-        expect(result.periods[0].qualities.every((q) => q.metadata.contentType === 'audio')).toBeTrue();
+        expect(contentTypesOf(result)).toEqual(new Set(['audio', 'video']));
     });
     it('preserves minBufferTime', () => {
-        const result = filterTimelineQualities(() => true, () => {
-            throw new Error('empty');
-        }, timeline);
+        const result = filterTimelineQualities(() => true, throwEmpty, timeline);
         expect(result.minBufferTime).toBe(2);
     });
     it('throws when filtering removes all qualities', () => {
-        expect(() => filterTimelineQualities(() => false, () => {
-            throw new Error('no qualities');
-        }, timeline)).toThrowError('no qualities');
+        expect(() => filterTimelineQualities(() => false, throwEmpty, timeline)).toThrowError('no qualities');
+    });
+    it('throws when filtering drops a present video stream to zero', () => {
+        expect(() => filterTimelineQualities((q) => q.contentType === 'audio', throwEmpty, timeline)).toThrowError('no qualities');
+    });
+    it('throws when filtering drops a present audio stream to zero', () => {
+        expect(() => filterTimelineQualities((q) => q.contentType === 'video', throwEmpty, timeline)).toThrowError('no qualities');
+    });
+    it('does not throw when losing only an optional text sidecar stream', () => {
+        const withText = timelineOf([
+            createQuality('audio', 128000),
+            createQuality('video', 500000),
+            createQuality('text', 1000),
+        ]);
+        const result = filterTimelineQualities((q) => q.contentType !== 'text', throwEmpty, withText);
+        expect(contentTypesOf(result)).toEqual(new Set(['audio', 'video']));
     });
 });
 describe('filterTimelineQualitiesAsync', () => {
-    const timeline = {
-        periods: [
-            {
-                startTime: 0,
-                endTime: 10,
-                qualities: [
-                    createQuality('audio', 128000),
-                    createQuality('video', 500000),
-                ],
-            },
-        ],
-        minBufferTime: 2,
-        getAdBreaks: () => Promise.resolve([]),
-        getDuration: () => Promise.resolve(Infinity),
-    };
-    it('filters qualities by async predicate', async () => {
-        const result = await filterTimelineQualitiesAsync((q) => Promise.resolve(q.contentType === 'audio'), () => {
-            throw new Error('empty');
-        }, timeline);
-        expect(result.periods[0].qualities.length).toBe(1);
-        expect(result.periods[0].qualities[0].metadata.contentType).toBe('audio');
+    const timeline = timelineOf([
+        createQuality('audio', 128000),
+        createQuality('audio', 256000),
+        createQuality('video', 500000),
+    ]);
+    it('filters qualities by async predicate while keeping every present stream', async () => {
+        const result = await filterTimelineQualitiesAsync((q) => Promise.resolve(q.bandwidth !== 256000), throwEmpty, timeline);
+        expect(result.periods[0].qualities.length).toBe(2);
+        expect(contentTypesOf(result)).toEqual(new Set(['audio', 'video']));
     });
     it('preserves minBufferTime', async () => {
-        const result = await filterTimelineQualitiesAsync(() => Promise.resolve(true), () => {
-            throw new Error('empty');
-        }, timeline);
+        const result = await filterTimelineQualitiesAsync(() => Promise.resolve(true), throwEmpty, timeline);
         expect(result.minBufferTime).toBe(2);
     });
     it('throws when filtering removes all qualities', async () => {
-        await expectAsync(filterTimelineQualitiesAsync(() => Promise.resolve(false), () => {
-            throw new Error('no qualities');
-        }, timeline)).toBeRejectedWithError('no qualities');
+        await expectAsync(filterTimelineQualitiesAsync(() => Promise.resolve(false), throwEmpty, timeline)).toBeRejectedWithError('no qualities');
+    });
+    it('throws when filtering drops a present video stream to zero', async () => {
+        await expectAsync(filterTimelineQualitiesAsync((q) => Promise.resolve(q.contentType === 'audio'), throwEmpty, timeline)).toBeRejectedWithError('no qualities');
+    });
+    it('does not throw when losing only an optional text sidecar stream', async () => {
+        const withText = timelineOf([
+            createQuality('audio', 128000),
+            createQuality('video', 500000),
+            createQuality('text', 1000),
+        ]);
+        const result = await filterTimelineQualitiesAsync((q) => Promise.resolve(q.contentType !== 'text'), throwEmpty, withText);
+        expect(contentTypesOf(result)).toEqual(new Set(['audio', 'video']));
     });
 });

package/dist/unit/types/current/track/filters/sampleRateFilter.test.js

@@ -192,6 +192,27 @@ describe('withinAudioSampleRateRange minSampleRate floor', () => {
         expect(withinMin(mid, 1, [low, mid])).toBe(true);
         expect(withinMin(low, 0, [low, mid])).toBe(false);
     });
+    it('keeps the highest when every rate (of three) is below the floor', () => {
+        const low = audioQuality([16_000]);
+        const mid = audioQuality([24_000]);
+        const high = audioQuality([32_000]);
+        expect(withinMin(high, 2, [low, mid, high])).toBe(true);
+        expect(withinMin(mid, 1, [low, mid, high])).toBe(false);
+        expect(withinMin(low, 0, [low, mid, high])).toBe(false);
+    });
+    it('keeps the highest below-floor rate when no platform max is reported', () => {
+        // No AudioContext rate, so the floor is the only bound; with every rate
+        // below it, the highest is kept as the fallback.
+        capabilities.sampleRate = null;
+        const low = audioQuality([16_000]);
+        const high = audioQuality([32_000]);
+        expect(withinMin(high, 1, [low, high])).toBe(true);
+        expect(withinMin(low, 0, [low, high])).toBe(false);
+    });
+    it('keeps a single audio rendition below the floor', () => {
+        const only = audioQuality([24_000]);
+        expect(withinMin(only, 0, [only])).toBe(true);
+    });
     it('ignores non-audio qualities in the floor fallback', () => {
         const audio = audioQuality([24_000]); // below the floor
         const video = createEmptyMediaQualityMetadata();
@@ -202,3 +223,57 @@ describe('withinAudioSampleRateRange minSampleRate floor', () => {
         expect(withinMin(video, 1, [audio, video])).toBe(true);
     });
 });
+// The floor and ceiling are soft together: when renditions straddle an empty
+// band (some below the floor, some above the ceiling, none in between) neither
+// bound alone must strand audio.
+describe('withinAudioSampleRateRange straddling an empty band', () => {
+    let capabilities;
+    beforeEach(() => {
+        // The soft ceiling is a non-Firefox behavior; Firefox's 48kHz cap is
+        // hard (covered above), so pin a non-Firefox UA to exercise the fallback.
+        setUserAgent('Chrome');
+        capabilities = new MockCapabilities();
+        // Ceiling at 48kHz; floor at 44.1kHz → acceptable band is [44.1k, 48k].
+        capabilities.sampleRate = 48_000;
+    });
+    function audioQuality(rate) {
+        const quality = createEmptyMediaQualityMetadata();
+        quality.contentType = 'audio';
+        quality.audioSamplingRate = rate;
+        return quality;
+    }
+    function within(metadata, index, array) {
+        return withinAudioSampleRateRange({ capabilities, minSampleRate: 44_100 }, metadata, index, array);
+    }
+    it('keeps the highest decodable rate when one is below the floor and one above the ceiling', () => {
+        const low = audioQuality([22_050]); // below the 44.1kHz floor
+        const high = audioQuality([96_000]); // above the 48kHz ceiling
+        // Empty band → the below-floor rate is decodable and kept; the
+        // above-ceiling rate is dropped, so audio is never stranded.
+        expect(within(low, 0, [low, high])).toBe(true);
+        expect(within(high, 1, [low, high])).toBe(false);
+    });
+    it('keeps the below-floor rate when the ceiling matches the output device rate', () => {
+        // Output device runs at 44.1kHz, so a 48kHz rendition is above the
+        // ceiling while a 22.05kHz rendition is below the floor.
+        capabilities.sampleRate = 44_100;
+        const low = audioQuality([22_050]);
+        const high = audioQuality([48_000]);
+        expect(within(low, 0, [low, high])).toBe(true);
+        expect(within(high, 1, [low, high])).toBe(false);
+    });
+    it('still prefers an in-band rate over the straddle fallback', () => {
+        const low = audioQuality([22_050]); // below floor
+        const mid = audioQuality([44_100]); // in band
+        const high = audioQuality([96_000]); // above ceiling
+        expect(within(mid, 1, [low, mid, high])).toBe(true);
+        expect(within(low, 0, [low, mid, high])).toBe(false);
+        expect(within(high, 2, [low, mid, high])).toBe(false);
+    });
+    it('keeps the lowest when every rate is above the ceiling', () => {
+        const low = audioQuality([88_200]);
+        const high = audioQuality([96_000]);
+        expect(within(low, 0, [low, high])).toBe(true);
+        expect(within(high, 1, [low, high])).toBe(false);
+    });
+});