@amazon/vinyl 1.2.0 → 2.0.0

package/dist/vinylTestUtil/types/ts4.7/mock/track/MockTrack.d.ts

@@ -1,13 +1,19 @@
-import { type ContentType, type MediaQualityMetadata, type Track, type TrackEventMap } from '@amazon/vinyl';
+import { type AdController, type ContentType, type MediaQualityMetadata, type SeekRange, type TextTrackController, type Track, type TrackAds, type TrackEventMap } from '@amazon/vinyl';
 import { RangesImpl } from '@amazon/vinyl-util';
 import { MockEventHost } from '@amazon/vinyl-util/testUtil';
 export declare class MockTrack extends MockEventHost<TrackEventMap> implements Track {
     get [Symbol.toStringTag](): string;
+    ads: TrackAds | null;
+    /**
+     * Resolves the track's ads. Mirrors the real async `getAds()` contract; the
+     * `ads` field is the backing value (defaulting to an empty break list).
+     */
+    getAds(): Promise<TrackAds>;
     uri: string;
     type: string;
     active: boolean;
     fetchedRanges: RangesImpl;
-    preload: import("@amazon/vinyl-util/browserTestUtil").Spy2<(trackOptions: import("@amazon/vinyl").TrackPreloadOptions, loadOptions: import("@amazon/vinyl-util").AnyRecord) => void>;
+    preload: import("@amazon/vinyl-util/browserTestUtil").Spy2<(trackOptions: import("@amazon/vinyl").TrackPreloadOptions, loadOptions: import("@amazon/vinyl-util").Maybe<import("@amazon/vinyl").TrackConfigOptions>) => void>;
     contentTypes: Set<ContentType>;
     qualities: readonly MediaQualityMetadata[] | null;
     qualitiesUnfiltered: readonly MediaQualityMetadata[] | null;
@@ -16,10 +22,13 @@ export declare class MockTrack extends MockEventHost<TrackEventMap> implements T
     getPlaybackQuality: import("@amazon/vinyl-util/browserTestUtil").Spy2<(contentType: ContentType) => MediaQualityMetadata | null>;
     extra: any;
     error: Error | null;
-    activate: import("@amazon/vinyl-util/browserTestUtil").Spy2<(loadOptions: import("@amazon/vinyl-util").AnyRecord) => void>;
+    textTrackController: TextTrackController | null;
+    adController: AdController | null;
+    seekRange: SeekRange | null;
+    activate: import("@amazon/vinyl-util/browserTestUtil").Spy2<(loadOptions: import("@amazon/vinyl-util").Maybe<import("@amazon/vinyl").TrackConfigOptions>) => void>;
     deactivate: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
     clearPrefetch: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
-    reset: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
+    reset: import("@amazon/vinyl-util/browserTestUtil").Spy2<(hard?: boolean) => void>;
     disposed: boolean;
     /**
      * Installs fakes for activate and deactivate to set active status.

package/dist/vinylTestUtil/types/ts4.7/mock/track/MockTrackController.d.ts

@@ -1,7 +1,8 @@
 import type { Track, TrackController, TrackControllerEventMap, TrackLoadOptions } from '@amazon/vinyl';
 import { MockEventHost } from '@amazon/vinyl-util/testUtil';
 export declare class MockTrackController<TrackLoadOptionsType extends TrackLoadOptions = TrackLoadOptions> extends MockEventHost<TrackControllerEventMap<TrackLoadOptionsType>> implements TrackController<TrackLoadOptionsType> {
-    currentTrack: Track | null;
+    activeTrack: Track | null;
+    currentAdTrack: Track | null;
     queue: any[];
     clearPrefetch: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
     clearQueue: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
@@ -15,6 +16,6 @@ export declare class MockTrackController<TrackLoadOptionsType extends TrackLoadO
     next: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
     preload: import("@amazon/vinyl-util/browserTestUtil").Spy2<(...loadOptionsList: readonly any[]) => void>;
     unload: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
-    reset: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
+    reset: import("@amazon/vinyl-util/browserTestUtil").Spy2<(hard?: boolean) => void>;
 }
 //# sourceMappingURL=MockTrackController.d.ts.map

package/dist/vinylTestUtil/types/ts4.7/mock/track/dash/createMockDashDependencies.d.ts

@@ -4,7 +4,9 @@ import { MockMediaSourceController } from '../../streaming/buffering/MockMediaSo
 import { MockPlaybackSource } from '../../playback/MockPlaybackSource';
 import { MockPlaybackController } from '../../playback/MockPlaybackController';
 import { MockDrmController } from '../../drm/MockDrmController';
+import { MockTextTrackController } from '../../text/MockTextTrackController';
 export declare function createMockDashDependencies(): {
+    readonly textTrackController: MockTextTrackController;
     readonly contentTypesValue: import("@amazon/vinyl-observable").MutableValueImpl<Promise<Set<ContentType>>>;
     readonly contentStreamFactory: jasmine.Spy<((contentType: ContentType) => import("@amazon/vinyl").ContentStream) & ((contentType: ContentType) => any)>;
     readonly manifestController: MockDashManifestController;
@@ -16,6 +18,10 @@ export declare function createMockDashDependencies(): {
     readonly playbackController: MockPlaybackController;
     readonly drmController: MockDrmController;
     readonly mediaQualityMetadataResolver: jasmine.Spy<DashMediaQualityMetadataResolver>;
+    readonly preferredAudioLanguage: import("@amazon/vinyl-observable").MutableValueImpl<string | readonly string[] | null>;
+    readonly allowedContentTypes: import("@amazon/vinyl-observable").MutableValueImpl<readonly import("@amazon/vinyl").RestrictableContentType[] | null>;
+    readonly preferDescriptiveAudio: import("@amazon/vinyl-observable").MutableValueImpl<boolean>;
+    readonly abr: import("@amazon/vinyl-observable").MutableValueImpl<import("@amazon/vinyl").QualitySelectorImplOptions>;
 };
 export type MockDashDependencies = ReturnType<typeof createMockDashDependencies>;
 //# sourceMappingURL=createMockDashDependencies.d.ts.map

package/dist/vinylTestUtil/types/ts4.7/mock/track/hls/createMockHlsDependencies.d.ts

@@ -16,6 +16,10 @@ export declare function createMockHlsDependencies(): {
     readonly playbackController: MockPlaybackController;
     readonly drmController: MockDrmController;
     readonly mediaQualityMetadataResolver: jasmine.Spy<HlsMediaQualityMetadataResolver>;
+    readonly preferredAudioLanguage: import("@amazon/vinyl-observable").MutableValueImpl<string | readonly string[] | null>;
+    readonly allowedContentTypes: import("@amazon/vinyl-observable").MutableValueImpl<readonly import("@amazon/vinyl").RestrictableContentType[] | null>;
+    readonly preferDescriptiveAudio: import("@amazon/vinyl-observable").MutableValueImpl<boolean>;
+    readonly abr: import("@amazon/vinyl-observable").MutableValueImpl<import("@amazon/vinyl").QualitySelectorImplOptions>;
 };
 export type MockHlsDependencies = ReturnType<typeof createMockHlsDependencies>;
 //# sourceMappingURL=createMockHlsDependencies.d.ts.map

package/docs/ADS.md

@@ -0,0 +1,264 @@
+# Ad Interstitials
+
+The Amazon Vinyl player supports server-guided ad insertion (SGAI) via HLS
+Interstitials (`EXT-X-DATERANGE` with `CLASS="com.apple.hls.interstitial"`). Ad
+breaks are discovered from the manifest, exposed through a provider-agnostic
+model, and played back transparently on the same media element as content.
+
+DASH SCTE-35 ad support is planned as a fast follow and will surface through the
+same `AdController` model, so application code written against this API will not
+need to change.
+
+## The model
+
+Ads are described by a small, provider-agnostic model. Applications observe it
+through the player; they never deal with HLS- or DASH-specific tags.
+
+- **`AdBreakInfo`** — a span of the timeline that carries advertising instead of
+  primary content. It has an `id`, a `startTime` and `duration` (in seconds on
+  the media timeline), a `placement` (`preroll` | `midroll` | `postroll`), a
+  `restrict` rule set (each of `skip`/`jump` optional), and an `ads` resolver.
+  It also carries fields that govern replay and resumption: `once` (play the
+  break at most once, never replaying it when the playhead re-crosses),
+  `resumeOffset` (where primary content resumes relative to the break start;
+  `null` advances by the break's actual playout duration, `0` resumes in place),
+  `playoutLimit` (a cap on the break's total playout, or `null` when uncapped),
+  `resolutionTimeOffset` (how far ahead of the break its assets should be
+  resolved and preloaded; `null` falls back to the controller's
+  `preloadAheadTime` option — see [Preloading](#preloading)), and a
+  `skipControl` resolver (resolving to the window — `{ offset, duration }` —
+  during which the ad may be skipped, or `null` when the break carries none).
+  These are provider-agnostic; an HLS interstitial, for example, populates them
+  from its `CUE=ONCE`, `X-RESUME-OFFSET`, `X-PLAYOUT-LIMIT`,
+  `X-RESOLUTION-TIME-OFFSET`, and `X-ASSET-LIST` `SKIP-CONTROL` signals.
+- **`AdInfo`** — a single ad within a break, with its own `id`, `startTime`,
+  `duration`, and asset `uri` (or `null`). Playback of an ad is capped at its
+  `duration` when that is known.
+- **`ads`** — a `ValueProvider<AdList>`; resolve it (via `resolveValueProvider`)
+  to the break's `readonly AdInfo[]`. Asset lists fetched lazily (e.g. an HLS
+  `X-ASSET-LIST`) resolve on first call and cache; breaks whose assets are known
+  up front resolve immediately.
+
+Ad assets are full tracks. An ad can be another HLS manifest, an MP4, or any
+source the player can otherwise play. The track type is inferred from the asset
+URL's extension today; MIME-type probing for extension-less URLs is a planned
+follow-up.
+
+## Player API
+
+```typescript
+// The ad breaks discovered for the current media (a TrackAds carrying the
+// break list), or null before any are known.
+player.currentTrackAds // TrackAds | null
+
+// The break currently containing the playhead, or null in primary content.
+player.currentAdBreak // AdBreakInfo | null
+
+// The ad currently playing within the active break, or null.
+player.currentAd // AdInfo | null
+
+// While an ad plays it is the active track, so `activeTrack` refers to the ad
+// track (not content) during a break. `currentAdBreak != null` likewise tells
+// you an ad is currently playing.
+player.activeTrack // ReadonlyTrack | null
+
+// Skip the current ad. If more ads remain in the break the next one begins;
+// otherwise the break ends and content resumes. No-op with no active break.
+player.skipAd()
+
+// Skip the entire active break and resume content. No-op with no active break.
+player.skipAdBreak()
+```
+
+### Events
+
+All of these are dispatched by the `AdController` and redispatched on the
+player, so you can listen on `player` directly.
+
+```typescript
+// The set of known ad breaks changed (e.g. a live manifest revealed one).
+player.on('currentTrackAdsChange', ({ previous, current }) => {
+    /* current: TrackAds | null */
+})
+
+// The playhead is approaching a midroll/postroll break (within its
+// resolution/preload window) and its assets are being warmed. Not emitted for
+// prerolls (they are warmed up front). See Preloading.
+player.on('adPreload', ({ adBreak }) => {
+    /* … */
+})
+
+// An ad break was entered — its ads may still be resolving.
+player.on('adBreakEntered', ({ adBreak }) => {
+    /* … */
+})
+
+// The active ad break completed (all ads played, were skipped, it hit its
+// playout limit, or it had no ads). `resumePosition` is the absolute
+// media-timeline position where content resumes; `reason` is one of
+// 'ended' | 'skipped' | 'contentChange' | 'error'.
+player.on('adBreakCompleted', ({ adBreak, resumePosition, reason }) => {
+    /* … */
+})
+
+// An individual ad within the break became active / started playing. Each
+// carries { adBreak, ad, index, totalAds }.
+player.on('adEntered', (e) => {
+    /* … */
+})
+player.on('adPlaying', (e) => {
+    /* … */
+})
+
+// Per-tick ad timing while a break plays. Carries elapsed and remaining time
+// for the current ad and for the whole break, plus the skip state — `canSkip`
+// (whether the ad may be skipped right now) and `skipIn` (seconds until it can
+// be, or null). Prefer this over deriving ad timing from the media element.
+player.on('adTimeUpdate', (e) => {
+    /* e.adCurrentTime, e.adTimeRemaining, e.breakCurrentTime,
+       e.breakTimeRemaining, e.canSkip, e.skipIn */
+})
+
+// Ad progress milestones. `adEnded` fires at 100%, just before `adCompleted`.
+// Each carries { adBreak, ad, index, totalAds, playbackRateAvg }.
+player.on('adFirstQuartile', (e) => {})
+player.on('adMidpoint', (e) => {})
+player.on('adThirdQuartile', (e) => {})
+player.on('adEnded', (e) => {})
+
+// An ad stopped playing for any reason (ended, skipped, error). Carries
+// { adBreak, ad, index, totalAds, reason }.
+player.on('adCompleted', ({ ad, reason }) => {
+    /* … */
+})
+
+// An ad list failed to load, or an individual ad failed. `currentAd` is set
+// only when a specific ad failed (null when the list itself failed to load).
+player.on('adError', ({ adBreak, currentAd, error }) => {
+    /* … */
+})
+```
+
+Gate a Skip control on `canSkip` and show a countdown from `skipIn` until the
+skip window opens.
+
+## How playback works
+
+Ad breaks are played on the **same media element** as content — there is no
+second video element. When the playhead enters a break, the `TrackController`:
+
+1. Suspends the content track, remembering the resume position.
+2. Creates (or reuses a preloaded) ad track and activates it.
+3. Sequences through the break's ads. Each ad plays to its end (or is skipped),
+   then the next ad activates.
+4. When the break ends, reactivates the content track at the resume position the
+   break dictates (ads either replace embedded content or resume from the prior
+   position).
+
+### Preloading
+
+Ad tracks are preloaded so they start promptly on entry:
+
+- **Prerolls** are warmed up front — when their parent content track is
+  preloaded (on `load`, prefetch, or `preload`) — since they play immediately.
+- **Midrolls and postrolls** are warmed as the playhead approaches them. The
+  `AdController` emits an **`adPreload`** event once the playhead comes within a
+  break's lead time: its own `resolutionTimeOffset` (from an HLS
+  `X-RESOLUTION-TIME-OFFSET`) when present, otherwise the
+  `AdControllerImplOptions.preloadAheadTime` (default 10 seconds). The
+  `TrackController` handles that event by resolving and warming the break's ad
+  tracks. Seeking back before a break re-arms its preload, so it warms again on
+  the next approach; a played-once (or spent) break is not re-warmed.
+
+Preloaded ad tracks are pegged to their parent content track — they carry a
+prefetch priority just above it and are disposed when that parent is evicted
+from the track cache (or the cache is cleared), so the ad-track store cannot
+grow without bound.
+
+### Placement notes
+
+- **Preroll** ads play before content begins.
+- **Midroll** ads play when the playhead crosses into the break.
+- **Postroll** ads play at the end of content. Because a postroll's start sits
+  at (or just past) the content's end, the playhead rarely reports a time inside
+  it before the content's `ended` fires — so the player treats a content `ended`
+  as the trigger to play a pending postroll before finishing the queue.
+
+## Restrictions
+
+A break may carry restrictions (from an HLS `X-RESTRICT`) describing what the
+**application** should allow. The player itself never blocks `skipAd`,
+`skipAdBreak`, or seeking — it always honors the API — but it surfaces the
+break's rules so applications can decide whether to expose those controls:
+
+```typescript
+const activeBreak = player.currentAdBreak
+const canSkip = !activeBreak?.restrict.skip // hide the Skip button when true
+const canSeek = !activeBreak?.restrict.jump // disable seeking past the ad
+```
+
+## Detecting track completion
+
+> **This is the most important integration note.** Read it if you act on track
+> completion yourself.
+
+If you rely on Vinyl's queue (`load`, `enqueue`, `next`), you do not need to do
+anything — the player suppresses queue advancement during ads, plays the ad, and
+resumes content automatically.
+
+If your application drives its own logic off completion — advancing your own
+queue, logging a play, updating UI — do **not** listen to the raw media `ended`
+event. It fires for every ad as well as for content, and a track's content
+`ended` fires _before_ its postroll plays, so even a content `ended` does not
+mean the track is done. **Treating either as track completion is the classic
+bug.**
+
+Use the **`trackEnded`** event instead. It fires once, when the current track
+has fully finished — after its postroll if any — and never for an ad or for
+content ending ahead of a postroll:
+
+```typescript
+player.on('trackEnded', () => {
+    // The track (including any postroll) finished. Safe to log a completed play
+    // or advance your own queue. Fires for every track as the queue advances;
+    // `queueEnded` additionally fires only after the final track.
+})
+```
+
+## Manifest variable substitution
+
+HLS ad manifests (e.g. AWS MediaTailor) frequently rely on `EXT-X-DEFINE`
+variable substitution, including:
+
+- `NAME` / `VALUE` — a literal definition.
+- `IMPORT` — inherit a value defined in the parent multivariant playlist.
+- `QUERYPARAM` — take a value from a named query parameter on the playlist's own
+  URL (common for session tokens on ad manifests).
+
+Vinyl resolves all three when parsing, so `{$token}` references in ad segment
+and rendition URIs are substituted before the ad track fetches them. No
+application configuration is required.
+
+## Example
+
+```typescript
+import { createVinylPlayer } from '@amazon/vinyl'
+
+const player = createVinylPlayer({ media: videoElement })
+
+// Reflect ad state in your UI.
+player.on('adBreakEntered', ({ adBreak }) => {
+    showAdOverlay({ canSkip: !adBreak.restrict.skip })
+})
+player.on('adBreakCompleted', () => {
+    hideAdOverlay()
+})
+
+// Advance your own queue only on true track completion (handles ads + postroll).
+player.on('trackEnded', () => {
+    playNextInMyQueue()
+})
+
+player.load({ type: 'hls', uri: 'https://example.com/episode.m3u8' })
+await player.play()
+```

package/docs/USAGE.md

@@ -198,7 +198,7 @@ To append tracks to the current queue without affecting playback, use `enqueue`.
 Usage example:
 
 ```typescript
-player.on('currentTrackChange', () => {
+player.on('trackActivated', () => {
     if (player.queue.length < 2) {
         // Queue is nearing exhaustion, append more tracks
         player.enqueue(
@@ -221,22 +221,25 @@ player.on('currentTrackChange', () => {
 
 ### Track Events
 
-There are two events related to track queues.
-
 See `TrackControllerEventMap` in API Docs for full documentation.
 
-`queueEnded` - Emitted when the last track of the playback queue has ended.
-
-`currentTrackChange` - Emitted when the current track has changed.
+- `trackActivated` - Emitted when a track becomes active (carries the track).
+- `trackDeactivated` - Emitted when the active track is torn down, because it
+  was superseded by another track or unloaded.
+- `trackEnded` - Emitted once a track has fully finished, _after_ its postroll
+  ad if any. Prefer this over `ended` to detect true track completion.
+- `queueEnded` - Emitted when the last track of the playback queue has ended.
 
 When the last track in the queue has ended, it will not automatically be
 unloaded. To automatically unload when the queue ends, one could write:
 
 `player.on('queueEnded', () => player.unload())`
 
-When a track ends, an `ended` event is emitted. This event is emitted before the
-queue moves to the next track. If an `ended` handler changes the queue, the
-automatic track transition will be canceled.
+When a track ends, a low-level `ended` event is emitted before the queue moves
+to the next track; if an `ended` handler changes the queue, the automatic track
+transition is canceled. Note that `ended` also fires for each ad (ads share the
+media element) and, for a track with a postroll, fires _before_ the postroll
+plays — so use `trackEnded` (above) to detect that a track is actually done.
 
 For example, to interrupt an automatic queue transition, one could write:
 
@@ -430,3 +433,133 @@ player.configure({ abr: { maxBandwidth: 0 } })
 // Remove the cap.
 player.configure({ abr: { maxBandwidth: null } })
 ```
+
+## Sidecar Text Tracks
+
+Vinyl discovers WebVTT subtitle tracks delivered alongside HLS or DASH content
+("sidecar" subtitles) and exposes them through `VinylPlayer`.
+
+### Discovery
+
+For HLS, the player reads `EXT-X-MEDIA:TYPE=SUBTITLES` renditions from the
+multivariant playlist. The rendition's `URI` may point at a `.vtt` file directly
+or at a media playlist (`.m3u8`) whose segments are individual `.vtt` files;
+both forms are supported.
+
+For DASH, the player reads `<AdaptationSet contentType="text">` (or any
+`<AdaptationSet>` with a `text/*` `mimeType`). Each `<Representation>`'s
+`BaseURL` chain is resolved against the manifest URL to produce the absolute
+text track URL. Segmented text codecs (`stpp`, `wvtt`) are not surfaced in v1.
+
+Discovery happens automatically when a track loads — applications need only
+listen for the `textTracksChange` event or read `player.textTracks`.
+
+### Forced subtitles
+
+A track flagged `forced` carries essential text (e.g. translations of
+foreign-language dialogue) that is meant to display even when the user has not
+enabled subtitles. A `forced` track shares its `language` with the full track,
+so selection distinguishes them by the `forced` flag rather than language alone.
+Media characteristics / accessibility roles are surfaced in `characteristics`
+(HLS `CHARACTERISTICS`, DASH `Role`/`Accessibility`).
+
+Until the application makes an explicit selection, the player auto-selects a
+forced track when one is discovered (preferring the default track's language).
+Any `setActiveTextTrack` call — including `setActiveTextTrack(null)` to turn
+captions off — is treated as an explicit choice and disables the auto-select.
+
+### API
+
+```typescript
+// Inspect available text tracks for the current media.
+console.log(player.textTracks)
+// → [{ id, kind: 'subtitles', language: 'en', label: 'English', default: true,
+//      forced: false, characteristics: [], uri: 'https://.../subs/en.vtt',
+//      mimeType: 'text/vtt' }, ...]
+
+// Activate a track.
+player.setActiveTextTrack(player.textTracks[0].id)
+
+// Inspect or clear the active track.
+console.log(player.activeTextTrack)
+player.setActiveTextTrack(null)
+
+// React to changes.
+player.on('textTracksChange', (event) => {
+    console.log('Text tracks updated:', event.current)
+})
+player.on('activeTextTrackChange', (event) => {
+    console.log('Active text track:', event.current)
+})
+player.on('textTrackError', (event) => {
+    console.warn('Failed to load track', event.track.label, event.error)
+})
+```
+
+When a track is activated, Vinyl fetches the WebVTT, parses it, and adds the
+resulting cues to a `TextTrack` on the underlying `<video>` / `<audio>` element
+via `HTMLMediaElement.addTextTrack`. The browser handles cue rendering according
+to the `default` controls or any custom UI you build on top of the DOM
+`TextTrack` API.
+
+### Generating Test Content
+
+`DMTestAssetBuilder` generates English / Spanish / Japanese sidecar VTT files
+for every produced HLS and DASH asset. The text-track wiring lives in
+`src/addTextTracks.ts`; running `npm run generate` produces VTT files in
+`subs/<lang>.vtt` next to each manifest, with the manifest patched to reference
+them.
+
+## Ad Breaks (Server-Guided Ad Insertion)
+
+Vinyl surfaces server-guided ad breaks through a single, provider-agnostic API
+on `VinylPlayer`. Today this is driven by HLS Interstitials (SGAI); the same API
+is intended to also carry DASH SCTE-35 splices, so applications observe one
+interface regardless of the streaming protocol.
+
+### Discovery
+
+For HLS, the player reads `EXT-X-DATERANGE` tags with
+`CLASS="com.apple.hls.interstitial"` from the media playlist. Each interstitial
+is mapped to an abstract `AdBreakInfo`:
+
+- Its wall-clock `START-DATE` is converted to a media-timeline start time by
+  correlating it with the playlist's `EXT-X-PROGRAM-DATE-TIME` anchor.
+- Its duration is resolved from `DURATION`, else the `START-DATE`/`END-DATE`
+  span, else `PLANNED-DURATION`.
+- An `X-ASSET-URI` yields a single resolved ad; an `X-ASSET-LIST` yields a break
+  whose assets are resolved asynchronously (empty `ads` up front).
+- The break is classified as `preroll`, `midroll`, or `postroll`.
+
+Discovery happens automatically when a track loads — applications need only
+listen for the `currentTrackAdsChange` event or read `player.currentTrackAds`.
+
+### API
+
+```typescript
+// Inspect the ad breaks known for the current media (ordered by start time).
+console.log(player.currentTrackAds)
+// → { trackUri, adBreaks: [{ id, startTime: 12, duration: 15,
+//      placement: 'midroll', restrict, once, resumeOffset,
+//      ads /* resolver → AdInfo[] */ }, ...] }
+
+// Inspect the break currently containing the playhead, if any.
+console.log(player.currentAdBreak)
+
+// React to changes and boundary crossings.
+player.on('currentTrackAdsChange', (event) => {
+    console.log('Ad breaks updated:', event.current)
+})
+player.on('adBreakEntered', ({ adBreak }) => {
+    console.log('Entered ad break', adBreak.id)
+})
+player.on('adBreakCompleted', ({ adBreak, resumePosition }) => {
+    console.log('Completed ad break', adBreak.id, '→ resume at', resumePosition)
+})
+```
+
+`adBreakEntered` fires when the playhead enters a break; `adBreakCompleted`
+fires when it finishes (all ads played, were skipped, or it had none), carrying
+the `resumePosition` at which content resumes. Breaks with an unknown duration
+surface in `currentTrackAds` but never mark the playhead as inside a break until
+their span resolves. See [ADS.md](./ADS.md) for the full ad event set.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@amazon/vinyl",
-    "version": "1.2.0",
+    "version": "2.0.0",
     "description": "An HTML5 streaming media player",
     "repository": {
         "type": "git",
@@ -71,17 +71,15 @@
     "scripts": {
         "analyzeExports": "tsx buildSrc/analyzeExports.ts",
         "analyzeExports:write": "tsx buildSrc/analyzeExports.ts --write",
-        "clean": "rimraf --glob dist .eslintcache \"**/*.tsbuildinfo\"",
+        "clean": "rimraf --glob dist \"**/*.tsbuildinfo\"",
         "indexFiles:check": "tsx buildSrc/writeIndexFiles.ts --check",
         "indexFiles:write": "tsx buildSrc/writeIndexFiles.ts",
         "build": "tsx buildSrc/build.ts",
         "build:release": "tsx buildSrc/build.ts --release",
         "prettier:check": "prettier . --ignore-path ../../.prettierignore --cache --check",
         "prettier:write": "prettier . --ignore-path ../../.prettierignore --cache --write",
-        "eslint:check": "eslint . --cache --max-warnings=0",
-        "eslint:write": "eslint . --cache --fix",
-        "lint": "npm run indexFiles:check && npm run eslint:check && npm run prettier:check",
-        "lint:write": "npm run indexFiles:write && npm run eslint:write && npm run prettier:write",
+        "lint": "npm run indexFiles:check && npm run oxlint:check && npm run prettier:check",
+        "lint:write": "npm run indexFiles:write && npm run oxlint:write && npm run prettier:write",
         "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",
@@ -89,20 +87,22 @@
         "start": "tsx buildSrc/build.ts --serve",
         "start:release": "tsx buildSrc/build.ts --serve --release",
         "watch": "tsx buildSrc/build.ts --watch",
-        "watch:release": "tsx buildSrc/build.ts --watch --release"
+        "watch:release": "tsx buildSrc/build.ts --watch --release",
+        "oxlint:check": "oxlint --type-aware --deny-warnings",
+        "oxlint:write": "oxlint --type-aware --fix"
     },
     "devDependencies": {
-        "@amazon/vinyl-build-utils": "^1.2.0",
+        "@amazon/vinyl-build-utils": "^2.0.0",
         "commander": "^9.5.0"
     },
     "dependencies": {
-        "@amazon/vinyl-di": "^1.2.0",
-        "@amazon/vinyl-hls-parser": "^1.2.0",
-        "@amazon/vinyl-mpd-parser": "^1.2.0",
-        "@amazon/vinyl-observable": "^1.2.0",
-        "@amazon/vinyl-transmux": "^1.2.0",
-        "@amazon/vinyl-util": "^1.2.0",
-        "@amazon/vinyl-validation": "^1.2.0"
+        "@amazon/vinyl-di": "^2.0.0",
+        "@amazon/vinyl-hls-parser": "^2.0.0",
+        "@amazon/vinyl-mpd-parser": "^2.0.0",
+        "@amazon/vinyl-observable": "^2.0.0",
+        "@amazon/vinyl-transmux": "^2.0.0",
+        "@amazon/vinyl-util": "^2.0.0",
+        "@amazon/vinyl-validation": "^2.0.0"
     },
-    "gitHead": "fbb8f1c60c5ada4a11f13954bb6bcb52f3cb0c5a"
+    "gitHead": "88ece0504b080347bbea6f240cf587ee863b7ff3"
 }

package/dist/types/current/track/hls/HlsManifestProvider.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"HlsManifestProvider.d.ts","sourceRoot":"","sources":["../../../../../src/track/hls/HlsManifestProvider.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAE3E,MAAM,MAAM,mBAAmB,GAAG,CAC9B,KAAK,CAAC,EAAE,aAAa,KACpB,OAAO,CAAC,eAAe,CAAC,CAAA;AAE7B,MAAM,WAAW,eAAe;IAC5B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;IAEnC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAA;CACrE"}

package/dist/unit/types/current/track/dash/DashManifestController.test.d.ts

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

package/dist/unit/types/current/track/dash/DashManifestController.test.d.ts.map

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