@amazon/vinyl 3.2.0 → 3.2.1

package/dist/types/ts3.7/ad/AdControllerImpl.d.ts

@@ -7,6 +7,15 @@ import { AdsProvider } from './AdsProvider';
  * The % playhead start tolerance for playback progress when emitting ad progress events.
  */
 export declare const AD_START_TOLERANCE = 0.05;
+/**
+ * When a break's X-PLAYOUT-LIMIT budget is reached, an ad whose real media end is
+ * within this many seconds is allowed to finish on its own `ended` rather than
+ * being cut. The limit is a coarse, often whole-second budget while the media's
+ * true length is fractional, so without this grace an ad effectively as long as
+ * its budget would be clipped a fraction short. The tolerance is measured against
+ * the playback-reported (media) duration, not the ad's declared duration.
+ */
+export declare const PLAYOUT_LIMIT_TOLERANCE = 1;
 export interface AdControllerImplDeps {
     readonly playbackController: ReadonlyPlaybackController;
 }
@@ -129,8 +138,15 @@ export declare class AdControllerImpl extends EventHostImpl<AdEventMap> implemen
     private emitAdProgressEvents;
     private emitTimeUpdate;
     /**
-     * Ads breaks can have a playout limit that may cut off ad playback.
-     * End the ad if that limit is reached.
+     * Enforces the break-level playout limit (X-PLAYOUT-LIMIT): a budget shared
+     * across all of the break's ads. When cumulative playout reaches it, the
+     * whole break ends, dropping any ads that have not started.
+     *
+     * This is deliberately NOT a per-ad cap. Each ad asset is its own source and
+     * ends on its media `ended` (see the 'ended' handler), which is what advances
+     * a multi-ad break. Ending an ad at its declared per-ad DURATION instead would
+     * truncate the real asset whenever a packager under-declares it — e.g. rounds
+     * a 6.732s asset down to a whole-second 6 — cutting off the fractional tail.
      */
     private enforcePlayoutLimits;
     private setPendingBreaks;

package/dist/types/ts4.1/ad/AdControllerImpl.d.ts

@@ -7,6 +7,15 @@ import type { AdsProvider } from './AdsProvider';
  * The % playhead start tolerance for playback progress when emitting ad progress events.
  */
 export declare const AD_START_TOLERANCE = 0.05;
+/**
+ * When a break's X-PLAYOUT-LIMIT budget is reached, an ad whose real media end is
+ * within this many seconds is allowed to finish on its own `ended` rather than
+ * being cut. The limit is a coarse, often whole-second budget while the media's
+ * true length is fractional, so without this grace an ad effectively as long as
+ * its budget would be clipped a fraction short. The tolerance is measured against
+ * the playback-reported (media) duration, not the ad's declared duration.
+ */
+export declare const PLAYOUT_LIMIT_TOLERANCE = 1;
 export interface AdControllerImplDeps {
     readonly playbackController: ReadonlyPlaybackController;
 }
@@ -129,8 +138,15 @@ export declare class AdControllerImpl extends EventHostImpl<AdEventMap> implemen
     private emitAdProgressEvents;
     private emitTimeUpdate;
     /**
-     * Ads breaks can have a playout limit that may cut off ad playback.
-     * End the ad if that limit is reached.
+     * Enforces the break-level playout limit (X-PLAYOUT-LIMIT): a budget shared
+     * across all of the break's ads. When cumulative playout reaches it, the
+     * whole break ends, dropping any ads that have not started.
+     *
+     * This is deliberately NOT a per-ad cap. Each ad asset is its own source and
+     * ends on its media `ended` (see the 'ended' handler), which is what advances
+     * a multi-ad break. Ending an ad at its declared per-ad DURATION instead would
+     * truncate the real asset whenever a packager under-declares it — e.g. rounds
+     * a 6.732s asset down to a whole-second 6 — cutting off the fractional tail.
      */
     private enforcePlayoutLimits;
     private setPendingBreaks;

package/dist/types/ts4.7/ad/AdControllerImpl.d.ts

@@ -7,6 +7,15 @@ import type { AdsProvider } from './AdsProvider';
  * The % playhead start tolerance for playback progress when emitting ad progress events.
  */
 export declare const AD_START_TOLERANCE = 0.05;
+/**
+ * When a break's X-PLAYOUT-LIMIT budget is reached, an ad whose real media end is
+ * within this many seconds is allowed to finish on its own `ended` rather than
+ * being cut. The limit is a coarse, often whole-second budget while the media's
+ * true length is fractional, so without this grace an ad effectively as long as
+ * its budget would be clipped a fraction short. The tolerance is measured against
+ * the playback-reported (media) duration, not the ad's declared duration.
+ */
+export declare const PLAYOUT_LIMIT_TOLERANCE = 1;
 export interface AdControllerImplDeps {
     readonly playbackController: ReadonlyPlaybackController;
 }
@@ -129,8 +138,15 @@ export declare class AdControllerImpl extends EventHostImpl<AdEventMap> implemen
     private emitAdProgressEvents;
     private emitTimeUpdate;
     /**
-     * Ads breaks can have a playout limit that may cut off ad playback.
-     * End the ad if that limit is reached.
+     * Enforces the break-level playout limit (X-PLAYOUT-LIMIT): a budget shared
+     * across all of the break's ads. When cumulative playout reaches it, the
+     * whole break ends, dropping any ads that have not started.
+     *
+     * This is deliberately NOT a per-ad cap. Each ad asset is its own source and
+     * ends on its media `ended` (see the 'ended' handler), which is what advances
+     * a multi-ad break. Ending an ad at its declared per-ad DURATION instead would
+     * truncate the real asset whenever a packager under-declares it — e.g. rounds
+     * a 6.732s asset down to a whole-second 6 — cutting off the fractional tail.
      */
     private enforcePlayoutLimits;
     private setPendingBreaks;

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/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();
     });