@amazon/vinyl 1.0.0

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

@@ -0,0 +1,39 @@
+import { type ChangeEvent, type ReadonlyPlaybackController } from '@amazon/vinyl';
+/**
+ * Waits until the playbackController is in a playing state.
+ *
+ * @param playbackController The playbackController reference. Can be the player.
+ * @param timeout The timeout (in seconds) before the promise will reject with a timeout.
+ */
+export declare function onPlaying(playbackController: ReadonlyPlaybackController, timeout?: number): Promise<void>;
+/**
+ * Resolves when the playbackController has enough data to play audio without stopping.
+ *
+ * @param playbackController The playbackController reference. Can be the player.
+ * @param timeout The timeout (in seconds) before the promise will reject with a timeout.
+ */
+export declare function onCanPlayThrough(playbackController: ReadonlyPlaybackController, timeout?: number): Promise<void>;
+/**
+ * Returns a promise that resolves when the playbackController is next in an 'ended' state.
+ *
+ * @param playbackController The playbackController reference. Can be the player.
+ * @param timeout The timeout beyond the remaining track time in which the promise will be
+ * rejected with a timeout error.
+ * @param metadataTimeout The timeout to await metadata, if metadata is not currently loaded.
+ */
+export declare function onEnded(playbackController: ReadonlyPlaybackController, timeout?: number, metadataTimeout?: number): Promise<void>;
+/**
+ * Returns a promise that resolves after the next 'timeUpdate' event.
+ *
+ * @param playbackController The playbackController reference. Can be the player.
+ * @param timeout The timeout (in seconds) before the promise will reject with a timeout.
+ */
+export declare function onTimeUpdate(playbackController: ReadonlyPlaybackController, timeout?: number): Promise<ChangeEvent<number>>;
+/**
+ * Returns a promise that resolves when the duration is non-zero.
+ *
+ * @param playbackController The playbackController reference. Can be the player.
+ * @param timeout The timeout (in seconds) before the promise will reject with a timeout.
+ */
+export declare function onDuration(playbackController: ReadonlyPlaybackController, timeout?: number): Promise<void>;
+//# sourceMappingURL=eventPromises.d.ts.map

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

@@ -0,0 +1,3 @@
+import { type VinylPlayer } from '@amazon/vinyl';
+export declare function expectTrackCanSeekTo(player: VinylPlayer, time: number): Promise<void>;
+//# sourceMappingURL=expectTrackCanSeek.d.ts.map

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

@@ -0,0 +1,13 @@
+import type { VinylPlayer } from '@amazon/vinyl';
+import { type TrackLoadOptions } from '@amazon/vinyl';
+export declare function expectTrackPlays(player: VinylPlayer<any>): Promise<void>;
+/**
+ * Asserts that every track in a playlist plays.
+ * Has assertions for queue events, playback events, time updates, duration,
+ * track changes.
+ *
+ * @param player
+ * @param playlist
+ */
+export declare function expectPlaylistPlays<T extends TrackLoadOptions>(player: VinylPlayer<T>, playlist: T[]): Promise<void>;
+//# sourceMappingURL=expectTrackPlays.d.ts.map

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

@@ -0,0 +1,12 @@
+import type { ReadonlyPlaybackController } from '@amazon/vinyl';
+/**
+ * Plays until a given end time. If the end time is not reached in an acceptable
+ * time frame, the test fails.
+ *
+ * @param player
+ * @param endTime
+ * @param timeout A timeout beyond the expected amount of time to play.
+ * This does not affect waiting for ready state.
+ */
+export declare function expectTrackPlaysUntil(player: ReadonlyPlaybackController, endTime: number, timeout?: number): Promise<void>;
+//# sourceMappingURL=expectTrackPlaysUntil.d.ts.map

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

@@ -0,0 +1,23 @@
+import type { ReadonlyPlaybackController } from '@amazon/vinyl';
+/**
+ * Expects that the play head does not progress from the current time.
+ * This is done with some flexibility; iOS for example after a pause may take some time to settle.
+ */
+export declare function expectTimeDoesNotElapse(player: ReadonlyPlaybackController): Promise<void>;
+/**
+ * Expects that time progresses at least 0.5s within a timeout.
+ */
+export declare function expectTimeElapses(player: ReadonlyPlaybackController): Promise<void>;
+/**
+ * Expects the player to be in a paused state.
+ */
+export declare function expectPausedState(player: ReadonlyPlaybackController): void;
+/**
+ * Expects the player to be in a playing state.
+ */
+export declare function expectPlayingState(player: ReadonlyPlaybackController): void;
+/**
+ * Expects the current state to be pending play.
+ */
+export declare function expectPendingPlaying(player: ReadonlyPlaybackController): void;
+//# sourceMappingURL=playbackStateExpectations.d.ts.map

package/docs/ARCHITECTURE.md

@@ -0,0 +1,175 @@
+# Architecture
+
+Amazon Vinyl is an HTML5 playback engine designed for high-performance streaming
+of DASH and HLS content. The architecture follows a modular design with clear
+separation of concerns, enabling extensibility through dependency injection.
+
+## Core Components
+
+```
+                            +-------------+
+                            | VinylPlayer |
+                            +------+------+
+                                   |
+                    +--------------+-----------------+
+                    |              |                 |
+                    v              v                 v
+            +---------------+ +----------+   +----------------+
+            |TrackController| |Playback  |   |DrmController   |
+            |               | |Controller|   |                |
+            +-------+-------+ +----+-----+   +-------+--------+
+                    |              |                 |
+                    v              v                 v
+            +---------------+ +-----------+   +-----------+
+            | Track         | | Media     |   | EME       |
+            | (Dash/Hls)    | | Element   |   | (Browser) |
+            |               | | (Browser) |   |           |
+            +-------+-------+ +-----------+   +-----------+
+                    |   |
+                    |   +----------------------+
+                    v                          v
+            +-------------------+     +----------------+
+            |BufferingController|     |SourceBuffer    |
+            |                   |     |Controller      |
+            +----------+--------+     +--------+-------+
+                       |                       |
+                       v                       v
+            +-------------------+     +----------------+
+            |SegmentController  |     |SourceBuffer    |
+            |                   |     |(Browser)       |
+            +----------+--------+     +----------------+
+                       |
+                       v
+            +-------------------+
+            |SegmentProvider    |
+            |                   |
+            +-------------------+
+```
+
+## Component Ownership
+
+### VinylPlayer
+
+Main entry point that orchestrates all streaming components and provides the
+public API.
+
+- **Owns**: TrackController, PlaybackController, DrmController
+- **Dependencies**: AutoResetController, QualitySelector
+- **Role**: Main orchestrator and public API
+- **Responsibilities**:
+    - Coordinate component lifecycle
+    - Expose unified playback interface
+    - Handle global error management
+
+### TrackController
+
+Manages the lifecycle of streaming tracks and maintains a playback queue.
+
+- **Owns**: Track instances (e.g. SourceTrack/DashTrack/HlsTrack), Track cache
+- **Dependencies**: TrackFactory
+- **Role**: Track lifecycle and queue management
+- **Responsibilities**:
+    - Validate and create tracks
+    - Manage playback queue
+    - Handle track transitions
+
+### PlaybackController
+
+Controls the HTML5 media element and manages playback state transitions.
+
+- **Owns**: HTML5 Media Element
+- **Dependencies**: PlaybackSource
+- **Role**: Media element control and state management
+- **Responsibilities**:
+    - Control play/pause/seek operations
+    - Monitor playback state changes
+    - Handle media element events
+
+### DrmController
+
+Handles encrypted content by managing DRM licenses and key exchanges.
+
+- **Owns**: License sessions, Key management
+- **Dependencies**: EME APIs, License servers
+- **Role**: Content decryption and license management
+- **Responsibilities**:
+    - Handle DRM initialization
+    - Manage license requests
+    - Process key messages
+
+### Track (DashTrack/HlsTrack)
+
+Protocol-specific implementation that coordinates manifest parsing and media
+streaming.
+
+- **Owns**: ManifestController, BufferingController, SegmentController
+- **Dependencies**: ManifestProvider, RepresentationProvider
+- **Role**: Protocol-specific streaming logic
+- **Responsibilities**:
+    - Coordinate sub-controllers for manifest resolution and parsing, segment
+      fetching, buffering, and encryption
+    - Handle protocol-specific features
+    - Handle track lifecycle
+    - Provide streaming quality and prefetch status and updates
+
+### BufferingController
+
+Manages the MediaSource buffer by coordinating segment appending and buffer
+health.
+
+- **Owns**: Segment append queue, Buffer state
+- **Dependencies**: SourceBufferController, SegmentController,
+  PlaybackController
+- **Role**: Media source buffer management
+- **Responsibilities**:
+    - Coordinate segment appending
+    - Handle buffer quotas
+
+### SegmentController
+
+Manages segment caching and prioritization while coordinating with providers for
+media locations.
+
+- **Owns**: Segment cache, Priority queue
+- **Dependencies**: SegmentProvider, QualitySelector
+- **Role**: Segment caching and prioritization
+- **Responsibilities**:
+    - Prioritize segment requests
+    - Manage segment cache
+
+### SegmentProvider
+
+Resolves media segment locations and handles the actual fetching of segment
+data.
+
+- **Owns**: Network requests, Segment timeline
+- **Dependencies**: ManifestController, NetworkQueue
+- **Role**: Media segment resolution and fetching
+- **Responsibilities**:
+    - Resolve segment URLs from manifest
+    - Fetch segment data over network
+    - Handle segment-specific transformations
+
+### QualitySelector
+
+Determines optimal playback quality based on network conditions.
+
+- **Owns**: Quality selection algorithm
+- **Dependencies**: NetworkMetrics, DeviceCapabilities, BufferHealth
+- **Role**: Adaptive bitrate selection
+- **Responsibilities**:
+    - Monitor network performance
+    - Select appropriate quality levels
+    - Adapt to changing conditions
+
+### ManifestController
+
+Parses and manages streaming manifests, handling updates and transformations.
+
+- **Owns**: Manifest data, Parser instances
+- **Dependencies**: ManifestProvider, ManifestTransformer
+- **Role**: Manifest parsing and refresh management
+- **Responsibilities**:
+    - Load and parse streaming manifests (MPD/M3U8)
+    - Handle manifest updates
+    - Transform manifest data

package/docs/AUTO_RESET.md

@@ -0,0 +1,77 @@
+# Auto Reset Logic
+
+The Amazon Vinyl player includes automatic error recovery through the
+`AutoResetController`, which monitors for playback errors and attempts to
+recover from transient failures.
+
+## How It Works
+
+### Error Detection
+
+- The `VinylPlayer` forwards all error events to the `AutoResetController`
+- Only `SERVICE_INTERNAL` `ReportableError` instances trigger auto-reset
+  behavior
+- Other error types (e.g., `SERVICE_EXTERNAL`, `MEDIA`, `API`) are ignored
+
+### Reset Triggers
+
+The controller monitors for retry opportunities and emits reset events in these
+scenarios:
+
+1. **Network Recovery**: Immediately when the device comes back online
+2. **Timed Retry**: After `retryInterval` seconds if the device is online and
+   retry limit not exceeded
+3. **User Actions**: Immediately on user-initiated playback events:
+    - `play`
+    - `pause`
+    - `seeking`
+    - `playing`
+
+### Reset Process
+
+When a reset is triggered:
+
+1. All controllers are reset by `VinylPlayer`: `DrmController`,
+   `PlaybackController`, `TrackController`
+2. Error state is cleared
+3. Retry counter is reset to 0 (for user actions only)
+4. A `reset` event is dispatched
+
+### Retry Limits
+
+- Maximum retries: `maxRetries` (default: 30)
+- Retry interval: `retryInterval` seconds (default: 30)
+- User actions reset the retry counter, allowing unlimited user-initiated
+  retries
+
+## Configuration
+
+```typescript
+const player = createVinylPlayer({
+    autoResetController: {
+        enabled: true, // Enable/disable auto-reset (default: true)
+        maxRetries: 30, // Max automatic retries (default: 30)
+        retryInterval: 30, // Seconds between retries (default: 30)
+    },
+})
+```
+
+## Integration Points
+
+- **VinylPlayer**: Forwards errors to controller, listens for reset events
+- **DrmController**: Retries failed license requests on reset
+- **PlaybackController**: Handles media element recovery
+- **TrackController**: Resets current track state
+- **NetworkState**: Monitors online/offline status
+
+## Debugging
+
+Enable debug logging (?vinylLogLevel=debug) to monitor auto-reset behavior:
+
+```typescript
+// Look for these log messages (filter on 'reset'):
+// "setError" - Error monitoring started
+// "online, emitting reset" - Network recovery triggered
+// "interval, emitting reset" - Timeout retry triggered
+// "max retries exhausted" - Retry limit reached
+```

package/docs/DASH_MANIFEST_TRANSFORM_GUIDE.md

@@ -0,0 +1,236 @@
+# DASH Manifest Transform Extension Guide (Advanced)
+
+This guide explains how to extend or modify DASH manifest transformations in
+Amazon Vinyl.
+
+## Overview
+
+DASH manifest transformers sort and modify DASH manifests before playback. The
+system uses a functional architecture where transformers are composable
+functions over `ObservableValue<Promise<DashManifestData>>`.
+
+Quality filtering (MIME type, key system, sample rate) is handled separately by
+the media timeline transformer, not the manifest transformer. The manifest
+transformer focuses on structural sorting and representation-level filtering.
+
+## Default Implementation
+
+`createDefaultDashManifestTransformer()` sorts:
+
+- Adaptation sets by `selectionPriority` (descending)
+- Representations by `qualityRanking` (ascending), then `bandwidth` (descending)
+
+The result is mapped over the manifest controller observable.
+
+## Creating Custom Filters
+
+### Representation Filters
+
+Filter representations based on properties like bandwidth:
+
+```typescript
+import { filterDashRepresentations, mapManifestTransform } from '@amazon/vinyl'
+import { MediaUnsupportedError } from '@amazon/vinyl-util'
+
+function filterHighBitrate(manifest: DashManifest) {
+    return filterDashRepresentations(
+        (representation) => representation.bandwidth <= 1_000_000,
+        () => {
+            throw new MediaUnsupportedError(
+                'No representations within bitrate range',
+                'bitrate_filter'
+            )
+        },
+        manifest
+    )
+}
+```
+
+### Adaptation Set Filters
+
+Filter entire adaptation sets:
+
+```typescript
+import { filterDashAdaptationSets } from '@amazon/vinyl'
+import { MediaUnsupportedError } from '@amazon/vinyl-util'
+
+function filterVideoOnly(manifest: DashManifest) {
+    return filterDashAdaptationSets(
+        (adaptationSet) =>
+            adaptationSet.mimeType?.startsWith('video/') ?? false,
+        () => {
+            throw new MediaUnsupportedError(
+                'No video adaptation sets found',
+                'video_only'
+            )
+        },
+        manifest
+    )
+}
+```
+
+## Creating Custom Transformers
+
+### Transform Function
+
+Use `flowAsync` to compose multiple filter/sort steps, and
+`mapManifestTransform` to apply them over a manifest observable:
+
+```typescript
+import {
+    filterDashRepresentations,
+    sortDashRepresentations,
+    mapManifestTransform,
+} from '@amazon/vinyl'
+import { flowAsync } from '@amazon/vinyl-util'
+import type { ObservableValue } from '@amazon/vinyl-observable'
+import type { DashManifestData } from '@amazon/vinyl'
+
+function createCustomTransformer(
+    manifestController: ObservableValue<Promise<DashManifestData>>
+) {
+    const transformManifest = flowAsync(
+        (m) => filterDashRepresentations(customPredicate, throwCustomError, m),
+        (m) => sortDashRepresentations(customComparator, m)
+    )
+
+    return mapManifestTransform(manifestController, transformManifest)
+}
+```
+
+### Filter Factory
+
+Transformers are factory functions with the signature
+`(ObservableValue<Promise<DashManifestData>>) => ObservableValue<Promise<DashManifestData>>`.
+This allows composition with `flow`:
+
+```typescript
+import { mapManifestTransform, filterDashRepresentations } from '@amazon/vinyl'
+
+function createCustomFilter(deps: CustomDeps) {
+    return (
+        manifestController: ObservableValue<Promise<DashManifestData>>
+    ): ObservableValue<Promise<DashManifestData>> =>
+        mapManifestTransform(manifestController, (manifest) =>
+            filterDashRepresentations(
+                (rep) => customPredicate(deps, rep),
+                throwCustomError,
+                manifest
+            )
+        )
+}
+```
+
+For filters that depend on additional reactive inputs, use `combineData`:
+
+```typescript
+import { combineData } from '@amazon/vinyl-observable'
+import { filterDashRepresentations } from '@amazon/vinyl'
+
+function createConfigFilter(deps: {
+    readonly configProvider: ObservableValue<FilterConfig>
+}): (
+    manifestAndPath: ObservableValue<Promise<DashManifestData>>
+) => ObservableValue<Promise<DashManifestData>> {
+    return (manifestAndPath) =>
+        combineData({
+            manifestAndPath,
+            config: deps.configProvider,
+        }).map(async ({ manifestAndPath, config }) => {
+            const { manifest, baseUrl } = await manifestAndPath
+            return {
+                baseUrl,
+                manifest: filterDashRepresentations(
+                    (rep) => rep.bandwidth <= config.maxBitrate,
+                    throwConfigFilterError,
+                    manifest
+                ),
+            }
+        })
+}
+```
+
+### Composing Transformers with flow
+
+```typescript
+import { flow } from '@amazon/vinyl-util'
+
+function createMyManifestTransformer(
+    deps: MyTransformerDeps
+): ObservableValue<Promise<DashManifestData>> {
+    return flow(
+        createCustomFilter(deps),
+        createSortTransformer()
+    )(createDefaultDashManifestTransformer(deps))
+}
+```
+
+## Integration with createVinylPlayer
+
+Override the `manifestTransformed` factory to inject custom transformations
+after the default sorting:
+
+```typescript
+import {
+    createVinylPlayer,
+    createDefaultDashManifestTransformer,
+    createDashFactories,
+    filterDashRepresentations,
+    mapManifestTransform,
+    type DashManifestTransformerDeps,
+} from '@amazon/vinyl'
+import { flowAsync } from '@amazon/vinyl-util'
+import { MediaUnsupportedError } from '@amazon/vinyl-util'
+
+function filterStereoOnly(manifest: DashManifest) {
+    return filterDashRepresentations(
+        (rep) =>
+            !rep.AudioChannelConfiguration ||
+            Number(rep.AudioChannelConfiguration.value) <= 2,
+        () => {
+            throw new MediaUnsupportedError(
+                'Only stereo audio supported',
+                'stereo_only'
+            )
+        },
+        manifest
+    )
+}
+
+const player = createVinylPlayer(
+    { media: new Audio() },
+    {
+        createDashFactories: (options) => (deps) => (loadOptions) => ({
+            ...createDashFactories(options)(deps)(loadOptions),
+            manifestTransformed: (
+                transformDeps: DashManifestTransformerDeps
+            ) => {
+                const transformManifest = flowAsync(filterStereoOnly)
+
+                return mapManifestTransform(
+                    createDefaultDashManifestTransformer(transformDeps),
+                    transformManifest
+                )
+            },
+        }),
+    }
+)
+```
+
+## Utility Functions
+
+- `filterDashAdaptationSets()` - Filter adaptation sets with error handling
+- `filterDashRepresentations()` - Filter representations with error handling
+- `sortDashAdaptationSets()` - Sort adaptation sets by comparator
+- `sortDashRepresentations()` - Sort representations by comparator
+- `manifestIsPlayable()` - Check if manifest has playable content
+- `mapManifestTransform()` - Apply a
+  `(DashManifest) => MaybePromise<DashManifest>` over a manifest observable,
+  preserving baseUrl
+
+## Best Practices
+
+1. **Error Handling**: Always provide meaningful error codes and messages
+2. **Performance**: Use async filters only for expensive operations (e.g. DRM)
+3. **Composition**: Prefer small, focused filter factories composed with `flow`
+4. **Immutability**: Filter utilities clone manifests internally