@amazon/vinyl 2.0.4 → 3.0.1

package/dist/vinylTestUtil/types/ts3.7/mock/player/MockVinylPlayerDependencies.d.ts

@@ -19,6 +19,8 @@ export declare function createMockVinylDependencies(): {
     readonly capabilities: MockCapabilities;
     readonly drmController: MockDrmController;
     readonly media: HTMLMediaElement;
+    readonly textTrackProvider: import("@amazon/vinyl").MediaTextTrackProvider;
+    readonly textTrackRenderer: null;
     readonly createDashFactories: (_loadOptions: import("@amazon/vinyl").DashTrackLoadOptions) => import("@amazon/vinyl-di").Factories<{
         readonly textTrackController: import("../..").MockTextTrackController;
         readonly contentTypesValue: import("@amazon/vinyl-observable").MutableValueImpl<Promise<Set<import("@amazon/vinyl").ContentType>>>;
@@ -32,9 +34,8 @@ export declare function createMockVinylDependencies(): {
         readonly playbackController: MockPlaybackController;
         readonly drmController: MockDrmController;
         readonly mediaQualityMetadataResolver: jasmine.Spy<import("@amazon/vinyl").DashMediaQualityMetadataResolver>;
-        readonly preferredAudioLanguage: import("@amazon/vinyl-observable").MutableValueImpl<string | readonly string[] | null>;
+        readonly audio: import("@amazon/vinyl-observable").MutableValueImpl<import("@amazon/vinyl").AudioOptions>;
         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>;
     }>;
     readonly createHlsFactories: (_loadOptions: import("@amazon/vinyl").HlsTrackLoadOptions) => any;

package/dist/vinylTestUtil/types/ts3.7/mock/text/MockTextTrackController.d.ts

@@ -3,8 +3,8 @@ import { MockEventHost } from '@amazon/vinyl-util/testUtil';
 export declare class MockTextTrackController extends MockEventHost implements TextTrackController {
     textTracks: readonly TextTrackInfo[];
     activeTextTrack: TextTrackInfo | null;
-    setActiveTextTrack: import("@amazon/vinyl-util/browserTestUtil").Spy2<(id: string | null) => void>;
-    suspend: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
-    resume: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
+    active: boolean;
+    deactivate: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
+    activate: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
 }
 //# sourceMappingURL=MockTextTrackController.d.ts.map

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

@@ -18,9 +18,8 @@ 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 audio: import("@amazon/vinyl-observable").MutableValueImpl<import("@amazon/vinyl").AudioOptions>;
     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>;

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

@@ -16,9 +16,8 @@ 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 audio: import("@amazon/vinyl-observable").MutableValueImpl<import("@amazon/vinyl").AudioOptions>;
     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>;

package/dist/vinylTestUtil/types/ts4.1/mock/player/MockVinylPlayerDependencies.d.ts

@@ -19,6 +19,8 @@ export declare function createMockVinylDependencies(): {
     readonly capabilities: MockCapabilities;
     readonly drmController: MockDrmController;
     readonly media: HTMLMediaElement;
+    readonly textTrackProvider: import("@amazon/vinyl").MediaTextTrackProvider;
+    readonly textTrackRenderer: null;
     readonly createDashFactories: (_loadOptions: import("@amazon/vinyl").DashTrackLoadOptions) => import("@amazon/vinyl-di").Factories<{
         readonly textTrackController: import("../..").MockTextTrackController;
         readonly contentTypesValue: import("@amazon/vinyl-observable").MutableValueImpl<Promise<Set<import("@amazon/vinyl").ContentType>>>;
@@ -32,9 +34,8 @@ export declare function createMockVinylDependencies(): {
         readonly playbackController: MockPlaybackController;
         readonly drmController: MockDrmController;
         readonly mediaQualityMetadataResolver: jasmine.Spy<import("@amazon/vinyl").DashMediaQualityMetadataResolver>;
-        readonly preferredAudioLanguage: import("@amazon/vinyl-observable").MutableValueImpl<string | readonly string[] | null>;
+        readonly audio: import("@amazon/vinyl-observable").MutableValueImpl<import("@amazon/vinyl").AudioOptions>;
         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>;
     }>;
     readonly createHlsFactories: (_loadOptions: import("@amazon/vinyl").HlsTrackLoadOptions) => any;

package/dist/vinylTestUtil/types/ts4.1/mock/text/MockTextTrackController.d.ts

@@ -3,8 +3,8 @@ import { MockEventHost } from '@amazon/vinyl-util/testUtil';
 export declare class MockTextTrackController extends MockEventHost implements TextTrackController {
     textTracks: readonly TextTrackInfo[];
     activeTextTrack: TextTrackInfo | null;
-    setActiveTextTrack: import("@amazon/vinyl-util/browserTestUtil").Spy2<(id: string | null) => void>;
-    suspend: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
-    resume: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
+    active: boolean;
+    deactivate: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
+    activate: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
 }
 //# sourceMappingURL=MockTextTrackController.d.ts.map

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

@@ -18,9 +18,8 @@ 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 audio: import("@amazon/vinyl-observable").MutableValueImpl<import("@amazon/vinyl").AudioOptions>;
     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>;

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

@@ -16,9 +16,8 @@ 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 audio: import("@amazon/vinyl-observable").MutableValueImpl<import("@amazon/vinyl").AudioOptions>;
     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>;

package/dist/vinylTestUtil/types/ts4.7/mock/player/MockVinylPlayerDependencies.d.ts

@@ -19,6 +19,8 @@ export declare function createMockVinylDependencies(): {
     readonly capabilities: MockCapabilities;
     readonly drmController: MockDrmController;
     readonly media: HTMLMediaElement;
+    readonly textTrackProvider: import("@amazon/vinyl").MediaTextTrackProvider;
+    readonly textTrackRenderer: null;
     readonly createDashFactories: (_loadOptions: import("@amazon/vinyl").DashTrackLoadOptions) => import("@amazon/vinyl-di").Factories<{
         readonly textTrackController: import("../..").MockTextTrackController;
         readonly contentTypesValue: import("@amazon/vinyl-observable").MutableValueImpl<Promise<Set<import("@amazon/vinyl").ContentType>>>;
@@ -32,9 +34,8 @@ export declare function createMockVinylDependencies(): {
         readonly playbackController: MockPlaybackController;
         readonly drmController: MockDrmController;
         readonly mediaQualityMetadataResolver: jasmine.Spy<import("@amazon/vinyl").DashMediaQualityMetadataResolver>;
-        readonly preferredAudioLanguage: import("@amazon/vinyl-observable").MutableValueImpl<string | readonly string[] | null>;
+        readonly audio: import("@amazon/vinyl-observable").MutableValueImpl<import("@amazon/vinyl").AudioOptions>;
         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>;
     }>;
     readonly createHlsFactories: (_loadOptions: import("@amazon/vinyl").HlsTrackLoadOptions) => any;

package/dist/vinylTestUtil/types/ts4.7/mock/text/MockTextTrackController.d.ts

@@ -3,8 +3,8 @@ import { MockEventHost } from '@amazon/vinyl-util/testUtil';
 export declare class MockTextTrackController extends MockEventHost implements TextTrackController {
     textTracks: readonly TextTrackInfo[];
     activeTextTrack: TextTrackInfo | null;
-    setActiveTextTrack: import("@amazon/vinyl-util/browserTestUtil").Spy2<(id: string | null) => void>;
-    suspend: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
-    resume: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
+    active: boolean;
+    deactivate: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
+    activate: import("@amazon/vinyl-util/browserTestUtil").Spy2<() => void>;
 }
 //# sourceMappingURL=MockTextTrackController.d.ts.map

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

@@ -18,9 +18,8 @@ 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 audio: import("@amazon/vinyl-observable").MutableValueImpl<import("@amazon/vinyl").AudioOptions>;
     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>;

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

@@ -16,9 +16,8 @@ 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 audio: import("@amazon/vinyl-observable").MutableValueImpl<import("@amazon/vinyl").AudioOptions>;
     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>;

package/docs/USAGE.md

@@ -454,37 +454,63 @@ 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
+### Selecting captions
 
-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`).
+Caption selection is **declarative**: it is driven entirely by the `text` option
+(`VinylOptions.text`), so a choice persists across track changes (e.g. across an
+ad break) and re-resolves against whatever the next source exposes. There is no
+imperative `setActiveTextTrack` call.
+
+```typescript
+type CaptionMode = 'on' | 'off' | 'forced'
 
-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.
+interface TextTrackSelection {
+    id?: string | null // exact track id (wins over the other criteria)
+    kind?: TextTrackKind | null // restrict to a kind, e.g. 'captions'
+    language?: string | readonly string[] | null // preferred language(s)
+    forced?: boolean | null // explicit forced-ness filter (overrides the mode)
+}
 
-### API
+interface TextTrackControllerOptions {
+    enabled?: CaptionMode | null // default 'forced'
+    selection?: TextTrackSelection | null
+}
+```
+
+- `enabled` gates rendering: `'off'` shows nothing, `'forced'` shows only forced
+  (narrative) tracks, `'on'` shows the full subtitle track. The default is
+  `'forced'`.
+- `selection.language` unset (or empty) falls back to the platform's
+  `navigator.languages`.
+- `selection.forced`, when set, is an explicit filter that overrides the
+  forced/full split implied by `enabled`.
+
+```typescript
+// Default (no config): forced captions in the platform's preferred languages.
+
+// Full subtitles in a specific language:
+player.configure({ text: { enabled: 'on', selection: { language: 'en' } } })
+
+// Forced narrative captions only, for a language:
+player.configure({ text: { enabled: 'forced', selection: { language: 'es' } } })
+
+// A specific discovered track by id:
+player.configure({ text: { enabled: 'on', selection: { id: someTrack.id } } })
+
+// Turn captions off:
+player.configure({ text: { enabled: 'off' } })
+```
+
+The player still exposes the discovered list, the active selection, and change
+events (read-only):
 
 ```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)
 })
@@ -496,19 +522,44 @@ player.on('textTrackError', (event) => {
 })
 ```
 
-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.
+### 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 full 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`).
 
-### Generating Test Content
+Because `enabled` defaults to `'forced'`, out of the box the player shows a
+forced track for the platform's preferred languages when one is discovered, and
+nothing otherwise.
+
+### Rendering
+
+When a track is selected, Vinyl fetches the WebVTT, parses it, and adds the cues
+to a `TextTrack` on the underlying media element via
+`HTMLMediaElement.addTextTrack`. By default that track is `'showing'` and the
+**browser renders** the cues (styleable only through the limited `::cue`
+pseudo-element).
+
+For full control over caption styling and placement, inject a
+`TextTrackRenderer` — Vinyl ships `HtmlTextTrackRenderer`, which paints cues as
+an HTML overlay you position yourself:
+
+```typescript
+import { createVinylPlayer, HtmlTextTrackRenderer } from '@amazon/vinyl'
+
+const captions = new HtmlTextTrackRenderer()
+const player = createVinylPlayer({ media, textTrackRenderer: captions })
+videoContainer.appendChild(captions.element) // position it over the video
+```
 
-`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.
+With a renderer injected, the DOM `TextTrack` is kept `'hidden'` (used only for
+cue timing) and the renderer paints the active cues, honoring each cue's WebVTT
+settings (`position` / `line` / `size` / `align` / `vertical`), cue payload tags
+(`<c.class>`, `<i>`, `<b>`, `<v>`, `<lang>`, …), and `STYLE`-block `::cue`
+rules. Implement the `TextTrackRenderer` interface for a fully custom renderer.
 
 ## Ad Breaks (Server-Guided Ad Insertion)
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@amazon/vinyl",
-    "version": "2.0.4",
+    "version": "3.0.1",
     "description": "An HTML5 streaming media player",
     "repository": {
         "type": "git",
@@ -90,17 +90,17 @@
         "oxlint:write": "oxlint --type-aware --fix"
     },
     "devDependencies": {
-        "@amazon/vinyl-build-utils": "^2.0.4",
+        "@amazon/vinyl-build-utils": "^3.0.1",
         "commander": "^9.5.0"
     },
     "dependencies": {
-        "@amazon/vinyl-di": "^2.0.4",
-        "@amazon/vinyl-hls-parser": "^2.0.4",
-        "@amazon/vinyl-mpd-parser": "^2.0.4",
-        "@amazon/vinyl-observable": "^2.0.4",
-        "@amazon/vinyl-transmux": "^2.0.4",
-        "@amazon/vinyl-util": "^2.0.4",
-        "@amazon/vinyl-validation": "^2.0.4"
+        "@amazon/vinyl-di": "^3.0.1",
+        "@amazon/vinyl-hls-parser": "^3.0.1",
+        "@amazon/vinyl-mpd-parser": "^3.0.1",
+        "@amazon/vinyl-observable": "^3.0.1",
+        "@amazon/vinyl-transmux": "^3.0.1",
+        "@amazon/vinyl-util": "^3.0.1",
+        "@amazon/vinyl-validation": "^3.0.1"
     },
     "publishConfig": {
         "access": "public"