@amazon/vinyl 1.2.0 → 1.2.2

package/dist/types/current/ad/AdBreakInfo.d.ts

@@ -0,0 +1,160 @@
+import type { TrackUri } from '../track/Track';
+import type { ValueProvider } from '@amazon/vinyl-util';
+export interface TrackAds {
+    /**
+     * The URI of the parent track.
+     */
+    readonly trackUri: TrackUri;
+    /**
+     * An array of the ad breaks for this track.
+     */
+    readonly adBreaks: AdBreakList;
+}
+/**
+ * Where an ad break is scheduled relative to the main content.
+ *
+ *  - `preroll`  - before content playback begins (start time at or near 0).
+ *  - `midroll`  - during content playback.
+ *  - `postroll` - at the end of content playback.
+ */
+export type AdBreakPlacement = 'preroll' | 'midroll' | 'postroll';
+/**
+ * Restrictions on user interaction during an ad break.
+ */
+export interface AdRestriction {
+    /**
+     * When true, the user should not be allowed to skip this ad.
+     *
+     * This is not enforced by the player; the application is expected
+     * to respect this flag when showing ad skip controls.
+     */
+    readonly skip?: boolean;
+    /**
+     * When true, the user should not be allowed to seek past this ad.
+     */
+    readonly jump?: boolean;
+}
+/**
+ * A provider-agnostic description of a single ad break on the media timeline.
+ *
+ * An ad break is a span of the presentation that carries advertising rather
+ * than primary content. The same shape is produced from HLS Interstitials
+ * (EXT-X-DATERANGE with `CLASS="com.apple.hls.interstitial"`) and, in the
+ * future, from DASH SCTE-35 splice signals, so applications observe one
+ * interface regardless of the streaming protocol.
+ *
+ * Times are expressed on the player's media timeline, in seconds, so they can
+ * be compared directly against the media's current time.
+ */
+export interface AdBreakInfo {
+    /**
+     * A stable identifier for this ad break, unique within the current media
+     * presentation. Derived from the source signal (e.g. the HLS DATERANGE ID).
+     */
+    readonly id: string;
+    /**
+     * The start time of the ad break on the media timeline, in seconds.
+     */
+    readonly startTime: number;
+    /**
+     * The duration of the ad break in seconds, or null when unknown (e.g. a
+     * still-open live break that has not yet resolved its end).
+     */
+    readonly duration: number | null;
+    /**
+     * The scheduled placement of the break relative to primary content.
+     */
+    readonly placement: AdBreakPlacement;
+    /**
+     * The individual ad assets that make up this break, in playback order.
+     */
+    readonly ads: ValueProvider<AdList>;
+    /**
+     * Restrictions on user interaction during this ad break.
+     */
+    readonly restrict: AdRestriction;
+    /**
+     * When true, this break plays at most once for the presentation and is not
+     * replayed even if the playhead re-crosses it (e.g. after a seek back). When
+     * false, the break may replay each time the playhead re-enters its region.
+     *
+     * (An HLS interstitial sets this from a `CUE=ONCE` hint.)
+     */
+    readonly once: boolean;
+    /**
+     * The offset, in seconds, from this break's scheduled {@link startTime} at
+     * which primary content resumes after the break. A signed value: 0 resumes
+     * in place (the break is purely additive). `null` means no resume offset was
+     * specified, in which case content resumes advanced by the break's actual
+     * playout duration (i.e. the break replaces that much primary content) —
+     * this is distinct from an explicit 0.
+     *
+     * (An HLS interstitial sets this from `X-RESUME-OFFSET`.)
+     */
+    readonly resumeOffset: number | null;
+    /**
+     * The maximum total playout time of the whole break, in seconds, summed
+     * across all of its ads, or `null` when the break's playout is uncapped.
+     * Distinct from {@link duration} (the break's timeline span) and from an
+     * individual {@link AdInfo.duration}.
+     *
+     * (An HLS interstitial sets this from `X-PLAYOUT-LIMIT`.)
+     */
+    readonly playoutLimit: number | null;
+    /**
+     * How far ahead of this break's {@link startTime}, in seconds, the player
+     * should resolve and preload the break's ad assets so they are ready when
+     * the playhead reaches it. `null` when the source specifies no offset, in
+     * which case the controller falls back to its `preloadAheadTime` option.
+     * Applies to midroll and postroll breaks; prerolls are preloaded up front.
+     *
+     * (An HLS interstitial sets this from `X-RESOLUTION-TIME-OFFSET`.)
+     */
+    readonly resolutionTimeOffset: number | null;
+    /**
+     * The window during which the user may skip this break, or a provider
+     * resolving to `null` when the break carries no skip window (skippability is
+     * then governed by {@link AdRestriction.skip}). Resolved lazily because, like
+     * {@link ads}, it may require fetching the break's asset list.
+     *
+     * (An HLS interstitial sets this from the `X-ASSET-LIST` `SKIP-CONTROL`.)
+     */
+    readonly skipControl: ValueProvider<SkipControl | null>;
+}
+/**
+ * Describes when a user may skip an ad break: skipping becomes available
+ * {@link offset} seconds into the break and remains offered for {@link duration}
+ * seconds (or the rest of the break when null).
+ */
+export interface SkipControl {
+    /** Seconds from the break start at which skipping becomes available. */
+    readonly offset: number;
+    /**
+     * Seconds the skip control remains offered after {@link offset}, or `null`
+     * to offer it for the remainder of the break.
+     */
+    readonly duration: number | null;
+}
+/**
+ * An ad break list, sorted by start time ascendingly.
+ */
+export type AdBreakList = readonly AdBreakInfo[];
+/**
+ * A single ad within an {@link AdBreakInfo}.
+ */
+export interface AdInfo {
+    /** A stable identifier for this ad within its break. */
+    readonly id: string;
+    /** The start time of this ad on the media timeline, in seconds. */
+    readonly startTime: number;
+    /** The duration of this ad in seconds, or null when unknown. */
+    readonly duration: number | null;
+    /**
+     * The URI of the ad asset, when the source signal provides one directly
+     * (e.g. an HLS interstitial `X-ASSET-URI`). Null when the ad is described
+     * only indirectly.
+     */
+    readonly uri: TrackUri | null;
+}
+export type AdList = readonly AdInfo[];
+//# sourceMappingURL=AdBreakInfo.d.ts.map

package/dist/types/current/ad/AdBreakInfo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdBreakInfo.d.ts","sourceRoot":"","sources":["../../../../src/ad/AdBreakInfo.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAEvD,MAAM,WAAW,QAAQ;IACrB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAE3B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAA;AAEjE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IAEvB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IACxB;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAE1B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAEhC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;IAEpC;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAEnC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAEhC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IAEtB;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAEpC;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAEpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAA;IAE5C;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC1D;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IAEvB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,WAAW,EAAE,CAAA;AAEhD;;GAEG;AACH,MAAM,WAAW,MAAM;IACnB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAE1B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAA;CAChC;AAED,MAAM,MAAM,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA"}

package/dist/types/current/ad/AdBreakInfo.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/types/current/ad/AdController.d.ts

@@ -0,0 +1,229 @@
+import type { ChangeEvent } from '../event/ChangeEvent';
+import { type ReadonlyEventHost } from '@amazon/vinyl-util';
+import { type AdBreakInfo, type AdInfo, type TrackAds } from './AdBreakInfo';
+import type { AdsProvider } from './AdsProvider';
+/**
+ * Events dispatched by an {@link AdController}. These are provider-agnostic:
+ * an application listens once and receives the same events whether the ads
+ * originate from HLS Interstitials or DASH SCTE-35.
+ */
+export interface AdEventMap {
+    /**
+     * Emitted when the set of known ad breaks for the current media changes,
+     * for example when a live manifest reveals a new break.
+     */
+    readonly currentTrackAdsChange: ChangeEvent<TrackAds | null>;
+    /**
+     * Dispatched when the playhead approaches a midroll or postroll break —
+     * within the break's resolution/preload window — so its ad assets can be
+     * resolved and warmed ahead of entry. Fires once per break as it is
+     * approached (again after a seek back re-arms a replayable break). Prerolls
+     * are preloaded up front and do not emit this.
+     */
+    readonly adPreload: AdBreakEvent;
+    /**
+     * Dispatched when an ad break has been entered — its ads may still be
+     * resolving. An ad break may contain one or more ads.
+     */
+    readonly adBreakEntered: AdBreakEvent;
+    /**
+     * Dispatched when the current ad break has completed: all of its ads
+     * played, were skipped, it hit its playout limit, or it had no ads. Carries
+     * the position at which primary content resumes.
+     */
+    readonly adBreakCompleted: AdBreakCompleteEvent;
+    /**
+     * Dispatched when an ad region has been entered.
+     */
+    readonly adEntered: AdEvent;
+    /**
+     * Dispatched when an ad has started playing.
+     */
+    readonly adPlaying: AdEvent;
+    /**
+     * Dispatched on each playback progress tick while an ad is active, carrying
+     * the elapsed and remaining time for both the current ad and the whole ad
+     * break. Applications should prefer this over deriving ad timing from the
+     * media element's duration.
+     */
+    readonly adTimeUpdate: AdTimeUpdateEvent;
+    /**
+     * Dispatched when an ad has played through 25%.
+     */
+    readonly adFirstQuartile: AdProgressEvent;
+    /**
+     * Dispatched when an ad has played through 50%.
+     */
+    readonly adMidpoint: AdProgressEvent;
+    /**
+     * Dispatched when an ad has played through 75%.
+     */
+    readonly adThirdQuartile: AdProgressEvent;
+    /**
+     * Dispatched when an ad has played through 100%.
+     * Will be dispatched before adCompleted.
+     */
+    readonly adEnded: AdProgressEvent;
+    /**
+     * Dispatched when an ad has stopped playing for any reason such as
+     * ended, error, or skipped.
+     */
+    readonly adCompleted: AdCompleteEvent;
+    /**
+     * An ad list or an individual ad failed to complete.
+     */
+    readonly adError: AdErrorEvent;
+}
+export interface AdErrorEvent {
+    /**
+     * The current ad break when the ad failed to load.
+     */
+    readonly adBreak: AdBreakInfo;
+    /**
+     * If set, the error was from an individual ad.
+     * If not set, the failure was in loading the ad list.
+     */
+    readonly currentAd: AdInfo | null;
+    /**
+     * The source error.
+     */
+    readonly error: any;
+}
+export interface AdEvent {
+    /** The parent ad break */
+    readonly adBreak: AdBreakInfo;
+    /** The ad that triggered this event. */
+    readonly ad: AdInfo;
+    /** The zero-based position of this ad within its break. */
+    readonly index: number;
+    /** The total number of ads in this break. */
+    readonly totalAds: number;
+}
+export interface AdProgressEvent extends AdEvent {
+    /**
+     * The average continuous playback rate for the quartile.
+     * Typically, 1.0 unless playbackRate was altered.
+     */
+    readonly playbackRateAvg: number;
+}
+export interface AdTimeUpdateEvent extends AdEvent {
+    /** Seconds the current ad has played. */
+    readonly adCurrentTime: number;
+    /**
+     * Seconds remaining in the current ad, or null when the ad's duration is
+     * unknown.
+     */
+    readonly adTimeRemaining: number | null;
+    /**
+     * Seconds the current ad break has played, summed across all of its ads so
+     * far (including the current one).
+     */
+    readonly breakCurrentTime: number;
+    /**
+     * Seconds remaining in the current ad break as a whole, or null when the
+     * break's total duration is unknown.
+     */
+    readonly breakTimeRemaining: number | null;
+    /**
+     * Whether the current ad may be skipped right now — false while skipping is
+     * restricted or the break's skip window has not yet opened. Applications
+     * should gate their skip control on this.
+     */
+    readonly canSkip: boolean;
+    /**
+     * Seconds until the ad becomes skippable, or null when there is no pending
+     * skip window (it is already skippable, or skipping is never offered).
+     */
+    readonly skipIn: number | null;
+}
+export interface AdCompleteEvent extends AdEvent {
+    /** The current ad break. */
+    readonly adBreak: AdBreakInfo;
+    /** The reason the ad changed, e.g. 'ended' for completed naturally, or 'skipped' */
+    readonly reason: AdChangeReason;
+}
+export interface AdBreakEvent {
+    /** The ad break. */
+    readonly adBreak: AdBreakInfo;
+}
+export interface AdBreakCompleteEvent extends AdBreakEvent {
+    /**
+     * The absolute media-timeline position, in seconds, at which primary content
+     * resumes after this break. The controller has already resolved the break's
+     * resume offset and playout, so consumers use this position directly.
+     */
+    readonly resumePosition: number;
+    /** The reason the ad break changed, e.g. 'ended' for completed naturally, or 'skipped' */
+    readonly reason: AdChangeReason;
+}
+export type AdChangeReason = 'ended' | 'skipped' | 'contentChange' | 'error';
+export declare const ALL_AD_EVENTS: readonly ["currentTrackAdsChange", "adPreload", "adBreakEntered", "adBreakCompleted", "adFirstQuartile", "adEntered", "adPlaying", "adTimeUpdate", "adMidpoint", "adThirdQuartile", "adEnded", "adCompleted", "adError"];
+/**
+ * Read-only view of the ad breaks for the current media and which break, if
+ * any, currently contains the playhead.
+ */
+export interface ReadonlyAdController extends ReadonlyEventHost<AdEventMap> {
+    /**
+     * The ad breaks known for the current media.
+     */
+    readonly currentTrackAds: TrackAds | null;
+    /**
+     * The ad break currently containing the playhead, or null when the
+     * playhead is in primary content.
+     */
+    readonly currentAdBreak: AdBreakInfo | null;
+    /**
+     * The ad currently playing within the active break, or null.
+     */
+    readonly currentAd: AdInfo | null;
+}
+/**
+ * Tracks the ad breaks for the current media and reports when the playhead
+ * enters and exits them.
+ *
+ * The controller is deliberately agnostic of HLS/DASH discovery details: its
+ * input is a list of {@link AdBreakInfo} sourced from an {@link AdsProvider}
+ * (set via {@link setAdsProvider}); it derives the active break from the
+ * playhead by observing the playback controller.
+ */
+export interface AdController extends ReadonlyAdController {
+    /**
+     * Sets the source of ad breaks, or null when no source is active. A
+     * `ReadonlyTrack` satisfies {@link AdsProvider} directly, so the current
+     * playing track can be passed as-is.
+     */
+    setAdsProvider(provider: AdsProvider | null): void;
+    /**
+     * Skips the entire active ad break, advancing past all remaining ads.
+     * No-op when no ad break is active.
+     */
+    skipAdBreak(): void;
+    /**
+     * Skips the currently playing ad. If there are more ads in the break,
+     * the next ad begins. If it's the last ad, the break ends.
+     * No-op when no ad break is active.
+     */
+    skipAd(): void;
+    /**
+     * Skips the current ad with 'error' for the completed reason.
+     * Emits an 'adError' event.
+     * If there are more ads in the break,
+     * the next ad begins. If it's the last ad, the break ends.
+     *
+     * No-op when no ad break is active.
+     */
+    failAd(error: Error): void;
+    /**
+     * Activates the preroll ads.
+     * Does nothing if there is no preroll.
+     * Resolves with the active preroll, or null if there wasn't one.
+     */
+    enterPreroll(): Promise<AdBreakInfo | null>;
+    /**
+     * Activates the next postroll ad.
+     * Does nothing if there is no postroll.
+     * Resolves with the active postroll, or null if there wasn't one.
+     */
+    enterPostroll(): Promise<AdBreakInfo | null>;
+}
+//# sourceMappingURL=AdController.d.ts.map

package/dist/types/current/ad/AdController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdController.d.ts","sourceRoot":"","sources":["../../../../src/ad/AdController.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACvB;;;OAGG;IACH,QAAQ,CAAC,qBAAqB,EAAE,WAAW,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAA;IAE5D;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAA;IAEhC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,YAAY,CAAA;IAErC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,oBAAoB,CAAA;IAE/C;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAE3B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAA;IAExC;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;IAEzC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IAEpC;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;IAEzC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IAEjC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAA;IAErC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CACjC;AAED,MAAM,WAAW,YAAY;IACzB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAE7B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IAEjC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAA;CACtB;AAED,MAAM,WAAW,OAAO;IACpB,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAE7B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,eAAgB,SAAQ,OAAO;IAC5C;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACnC;AAED,MAAM,WAAW,iBAAkB,SAAQ,OAAO;IAC9C,yCAAyC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAE9B;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAEvC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IAEjC;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAA;IAE1C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IAEzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACjC;AAED,MAAM,WAAW,eAAgB,SAAQ,OAAO;IAC5C,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAE7B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAClC;AAED,MAAM,WAAW,YAAY;IACzB,oBAAoB;IACpB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAChC;AAED,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACtD;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAE/B,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAClC;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,eAAe,GAAG,OAAO,CAAA;AAE5E,eAAO,MAAM,aAAa,0NAcwB,CAAA;AAElD;;;GAGG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB,CAAC,UAAU,CAAC;IACvE;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,QAAQ,GAAG,IAAI,CAAA;IAEzC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,WAAW,GAAG,IAAI,CAAA;IAE3C;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACpC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAa,SAAQ,oBAAoB;IACtD;;;;OAIG;IACH,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAAA;IAElD;;;OAGG;IACH,WAAW,IAAI,IAAI,CAAA;IAEnB;;;;OAIG;IACH,MAAM,IAAI,IAAI,CAAA;IAEd;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IAE1B;;;;OAIG;IACH,YAAY,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;IAE3C;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC/C"}

package/dist/types/current/ad/AdController.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export const ALL_AD_EVENTS = [
+    'currentTrackAdsChange',
+    'adPreload',
+    'adBreakEntered',
+    'adBreakCompleted',
+    'adFirstQuartile',
+    'adEntered',
+    'adPlaying',
+    'adTimeUpdate',
+    'adMidpoint',
+    'adThirdQuartile',
+    'adEnded',
+    'adCompleted',
+    'adError',
+];

package/dist/types/current/ad/AdControllerImpl.d.ts

@@ -0,0 +1,162 @@
+import { EventHostImpl } from '@amazon/vinyl-util';
+import { type AdBreakInfo, type AdInfo, type TrackAds } from './AdBreakInfo';
+import type { AdController, AdEventMap } from './AdController';
+import type { ReadonlyPlaybackController } from '../playback/ReadonlyPlaybackController';
+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;
+}
+export interface AdControllerImplOptions {
+    /**
+     * After an ad is set, the number of seconds to wait for playback to begin
+     * before marking the ad as failed.
+     * Default: 15
+     */
+    readonly adLoadTimeout: number;
+    /**
+     * How many seconds ahead of a midroll or postroll break to emit `adPreload`
+     * (so its ad assets can be warmed before the playhead reaches it). Used only
+     * when the break itself carries no {@link AdBreakInfo.resolutionTimeOffset};
+     * a break's own offset always takes precedence.
+     * Default: 10
+     */
+    readonly preloadAheadTime: number;
+}
+export declare const defaultAdControllerImplOptions: AdControllerImplOptions;
+/**
+ * Provider-agnostic {@link AdController}. Holds the discovered ad breaks and
+ * derives enter/exit region events from playhead time updates.
+ *
+ * This controller is the *model* for ad playback: it knows which breaks exist,
+ * which break contains the playhead, and which ad within that break is current.
+ * It does NOT create, preload, or activate any tracks — that is the
+ * responsibility of the {@link TrackController}.
+ *
+ * A break is considered active while `startTime <= currentTime < endTime`,
+ * where `endTime` is `startTime + duration`. Breaks whose duration is unknown
+ * (null) or breaks which restrict `jump` will become active at
+ * `currentTime > startTime`
+ *
+ * This class contains no HLS- or DASH-specific logic; discovery code maps its
+ * protocol's signals to {@link AdBreakInfo} exposed by an
+ * {@link AdsProvider.getAds}, which this controller reads once the provider is
+ * set via {@link AdController.setAdsProvider} (and re-reads on `adsChange`).
+ */
+export declare class AdControllerImpl extends EventHostImpl<AdEventMap> implements AdController {
+    private readonly deps;
+    get [Symbol.toStringTag](): string;
+    private readonly options;
+    private _trackAds;
+    private adsProviderSub;
+    private adsProvider;
+    private midrollAds;
+    private preloadableBreaks;
+    private readonly preloadedBreakIds;
+    private lastPlaybackTime;
+    private pendingAdBreaks;
+    private readonly completeAdBreakIds;
+    private readonly spentBreakIds;
+    private readonly disposer;
+    private adBreakState;
+    private loadingNext;
+    constructor(deps: AdControllerImplDeps, options?: Partial<AdControllerImplOptions>);
+    clearCompletedAds(): void;
+    private isBreakSuppressed;
+    /** The media-time the current ad has actually played, or 0 if not playing. */
+    private adElapsed;
+    /**
+     * Computes whether the current ad may be skipped and, when not yet, how many
+     * seconds remain until it can. A `skip` restriction blocks it outright;
+     * otherwise a resolved skip window gates it by the elapsed break playout, and
+     * with no window the ad is freely skippable.
+     */
+    private resolveSkipState;
+    get currentTrackAds(): TrackAds | null;
+    private setTrackAds;
+    /**
+     * Returns a function that returns true if the ads provider has changed
+     * since the callback was created.
+     */
+    private providerInterrupted;
+    setAdsProvider(provider: AdsProvider | null): void;
+    enterPreroll(): Promise<AdBreakInfo | null>;
+    enterPostroll(): Promise<AdBreakInfo | null>;
+    private enterRoll;
+    private get hasProvider();
+    skipAdBreak(): void;
+    /**
+     * Marks an ad break as completed (or 'spent' and replayable), emits an `adBreakCompleted` event.
+     */
+    private completeAdBreak;
+    get currentAdBreak(): AdBreakInfo | null;
+    /**
+     * Marks an ad as completed and emits an `adCompleted` event.
+     */
+    private completeAd;
+    /**
+     * Polls the next pending ad and activates it.
+     * When there are no remaining ads, activates the next ad break (if any).
+     */
+    private nextAdOrBreak;
+    get currentAd(): AdInfo | null;
+    private get adState();
+    private startAd;
+    /**
+     * Checks if the playhead has entered a time to activate a midroll ad.
+     */
+    private onTimeUpdate;
+    /**
+     * Emits `adPreload` once for each midroll/postroll break the playhead is
+     * approaching — within (the break's {@link AdBreakInfo.resolutionTimeOffset}
+     * or, when absent, the `preloadAheadTime` option) seconds before its start —
+     * so a consumer can resolve and warm the break's assets before entry.
+     * Suppressed (played-once/spent) breaks are skipped.
+     */
+    private checkAdPreload;
+    /**
+     * Main content with ad breaks is playing, check if we have entered a midroll region.
+     */
+    private checkMidrollIngress;
+    /**
+     * Emits events for `adTimeUpdate`, `adFirstQuartile`, `adMidpoint`, and
+     * `adThirdQuartile`.
+     * (Does not emit `adCompleted`)
+     */
+    private emitAdProgressEvents;
+    private emitTimeUpdate;
+    /**
+     * 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;
+    skipAd(): void;
+    failAd(error: Error): void;
+    private endAd;
+    get disposed(): boolean;
+    /**
+     * Disposes this controller, removes all listeners.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=AdControllerImpl.d.ts.map

package/dist/types/current/ad/AdControllerImpl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdControllerImpl.d.ts","sourceRoot":"","sources":["../../../../src/ad/AdControllerImpl.ts"],"names":[],"mappings":"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"}