@amazon/vinyl 1.2.0 → 2.0.0

package/dist/types/ts4.7/vinyl/VinylOptions.d.ts

@@ -1,6 +1,9 @@
 import { type QualitySelectorImplOptions } from '../streaming/abr/QualitySelectorImpl';
 import type { ObjectSchema } from '@amazon/vinyl-validation';
+import type { CodecOverrides } from '../util/media/codecOverrides';
+import { type RestrictableContentType } from '../streaming/MediaQualityMetadata';
 import { type LoudnessNormalizationControllerImplOptions } from '../playback/loudness/LoudnessNormalizationControllerImplOptions';
+import { type VttCueStyle } from '../text/VttCueStyle';
 export interface VinylOptions {
     /**
      * Configuration for the default adaptive bitrate selector.
@@ -8,11 +11,72 @@ export interface VinylOptions {
     readonly abr: QualitySelectorImplOptions;
     readonly loudnessNormalization: LoudnessNormalizationControllerImplOptions;
     /**
-     * Preferred language for audio content, using a code as defined by RFC 5646 (e.g. 'en', 'ja').
-     * When set, only adaptation sets / variants matching this language (or without a language tag)
-     * are kept. Null means no language preference (all languages are kept).
+     * Preferred language(s) for audio content, as RFC 5646 codes (e.g. `'en'`,
+     * `'ja'`, `'fr-CA'`). May be a single tag or an ordered list of tags —
+     * earlier entries are preferred, with the best relatedness match kept for
+     * each period (audio without a language tag is always kept). `null` (the
+     * default) is NOT "no preference": it orders by the platform's
+     * `navigator.languages`. To keep every language, this option is not the
+     * mechanism — omit language content or pass a tag matching all.
      */
-    readonly preferredAudioLanguage: string | null;
+    readonly preferredAudioLanguage: string | readonly string[] | null;
+    /**
+     * Preferred language(s) for text tracks (subtitles / closed captions), as
+     * RFC 5646 codes (e.g. `'en'`, `'ja'`, `'fr-CA'`). May be a single tag or
+     * an ordered list of tags — earlier entries are preferred, with the best
+     * relatedness match chosen among the discovered text tracks. When set, the
+     * matching text track is selected automatically and the choice carries
+     * across track changes (e.g. across an ad break), mirroring how
+     * {@link preferredAudioLanguage} drives audio selection.
+     *
+     * Unlike audio, `null` (the default) means *no caption preference*: it does
+     * NOT fall back to `navigator.languages` and does NOT force captions on —
+     * forced narrative subtitles still auto-display as usual. Setting it to a
+     * language turns captions on in that language; setting it back to `null`
+     * after a prior selection turns captions off.
+     */
+    readonly preferredTextLanguage: string | readonly string[] | null;
+    /**
+     * Opt in to audio-description (a.k.a. described-video / DVS) audio: audio
+     * renditions carrying an accessibility "describes video" characteristic that
+     * narrate on-screen action. `false` (the default) keeps them out of the
+     * automatic default-audio selection — they are chosen only when this is set.
+     * When `true`, a description rendition is preferred where one exists for the
+     * selected language. Changing this reselects audio immediately.
+     */
+    readonly preferDescriptiveAudio: boolean;
+    /**
+     * Explicit codec allow/deny overrides that bypass browser support
+     * detection. Keys are RFC 6381 codec strings or prefixes (e.g. `"hvc1"`),
+     * values are `'allow'` or `'deny'`. An `'allow'` forces a codec to be
+     * treated as supported; a `'deny'` forces it to be treated as unsupported.
+     * Empty by default (support is determined solely by the browser and the
+     * known-false-report list).
+     */
+    readonly codecOverrides: CodecOverrides;
+    /**
+     * Allow list restricting which media content types (`'audio'`, `'video'`)
+     * are streamed. When set, only streams whose content type is in the list
+     * are created; all other media streams are ignored. For example,
+     * `['audio']` streams audio but never video. Changing this reloads the
+     * track using only the allowed content types. Null (the default) means no
+     * restriction (all available media content types are streamed).
+     *
+     * Text tracks (subtitles / closed captions) are not affected by this allow
+     * list; they are governed by caption selection and always remain
+     * available.
+     */
+    readonly allowedContentTypes: readonly RestrictableContentType[] | null;
+    /**
+     * Layout style applied to rendered WebVTT cues (the settable `VTTCue`
+     * positioning properties: size, line, position, align, etc.). Applied to
+     * each cue as it is added, on platforms that support `VTTCue`.
+     *
+     * Defaults to `{ size: 90 }`, insetting the cue box from the full video
+     * width so long lines don't clip at the screen edges in fullscreen (which
+     * `::cue` CSS cannot fix). Set to `null` to keep the browser defaults.
+     */
+    readonly textCueStyle: VttCueStyle | null;
 }
 export declare const defaultVinylOptions: VinylOptions;
 export declare const vinylOptionsValidator: ObjectSchema<VinylOptions>;

package/dist/types/ts4.7/vinyl/VinylPlayer.d.ts

@@ -5,6 +5,7 @@ import type { PlaybackController } from '../playback/PlaybackController';
 import { type PlaybackControllerEventMap, type PlaybackNetworkState, type PlaybackReadyState } from '../playback/ReadonlyPlaybackController';
 import type { VinylTrackLoadOptions } from '../track/createVinylTrackFactories';
 import { type ReadonlyTrack, type TrackUri } from '../track/Track';
+import type { SeekRange } from '../track/SeekRange';
 import { type TrackController, type TrackControllerEventMap } from '../track/TrackController';
 import type { InferLoadOptionsFromFactory, TrackLoadOptions } from '../track/TrackFactory';
 import type { DefaultVinylFactories, InferVinylOverrideDependencyType, VinylDependencyOptions } from './createVinylFactories';
@@ -13,13 +14,17 @@ import type { Capabilities } from '../client/Capabilities';
 import { type ContentType, type MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
 import type { ReadonlyPlaybackStreamingState } from './ReadonlyPlaybackStreamingState';
 import { type StreamingEventMap } from '../streaming/StreamingEventMap';
+import type { LoadMetricEventMap } from '../streaming/LoadMetric';
 import type { InferObservableValueType } from '@amazon/vinyl-observable';
 import type { VinylOptions } from './VinylOptions';
 import type { ChangeEvent } from '../event/ChangeEvent';
+import { type TextTrackEventMap, type TextTrackInfo } from '../text/TextTrack';
+import { type AdEventMap } from '../ad/AdController';
+import type { AdBreakInfo, AdInfo, TrackAds } from '../ad/AdBreakInfo';
 /**
  * Events the Vinyl Player emits.
  */
-export interface VinylPlayerEventMap<TrackLoadOptionsType extends TrackLoadOptions = VinylTrackLoadOptions> extends PlaybackControllerEventMap, TrackControllerEventMap<TrackLoadOptionsType>, StreamingEventMap {
+export interface VinylPlayerEventMap<TrackLoadOptionsType extends TrackLoadOptions = VinylTrackLoadOptions> extends PlaybackControllerEventMap, TrackControllerEventMap<TrackLoadOptionsType>, StreamingEventMap, TextTrackEventMap, AdEventMap, LoadMetricEventMap {
     /**
      * Dispatched when {@link VinylPlayer.resetPending} changes.
      *
@@ -67,7 +72,6 @@ export declare class VinylPlayer<TrackLoadOptionsType extends TrackLoadOptions =
      */
     protected redispatchCurrentTrackEvents(): void;
     private initializeAutoResetHandling;
-    private initializePreferredLanguageHandling;
     /**
      * Returns the current player options.
      * Use `configure` to set.
@@ -120,6 +124,11 @@ export declare class VinylPlayer<TrackLoadOptionsType extends TrackLoadOptions =
     set preservesPitch(value: boolean);
     get readyState(): PlaybackReadyState;
     get seekable(): ReadonlyRanges;
+    /**
+     * The seekable range on the media timeline for the current track, or null
+     * when no track is loaded or the timeline is not yet resolved.
+     */
+    get seekRange(): SeekRange | null;
     get seeking(): boolean;
     get volume(): number;
     set volume(value: number);
@@ -127,8 +136,8 @@ export declare class VinylPlayer<TrackLoadOptionsType extends TrackLoadOptions =
     pause(): void;
     play(): Promise<void>;
     seekTo(time: number, tolerance?: number): Promise<void>;
-    reset(): void;
-    get currentTrack(): ReadonlyTrack | null;
+    reset(hard?: boolean): void;
+    get activeTrack(): ReadonlyTrack | null;
     get queue(): readonly TrackLoadOptionsType[];
     preload(...loadOptionsList: TrackLoadOptionsType[]): void;
     load(...loadOptionsList: TrackLoadOptionsType[]): void;
@@ -202,6 +211,56 @@ export declare class VinylPlayer<TrackLoadOptionsType extends TrackLoadOptions =
      * The currently playing quality, or null if no media is playing.
      */
     getPlaybackQuality(contentType: ContentType): MediaQualityMetadata | null;
+    /**
+     * The list of currently discovered sidecar text tracks for the active
+     * media. Empty when there is no current track or the current track
+     * carries no text.
+     */
+    get textTracks(): readonly TextTrackInfo[];
+    /**
+     * The currently active text track, or null if no track is selected.
+     */
+    get activeTextTrack(): TextTrackInfo | null;
+    /**
+     * Selects the text track with the given id, or clears the active text
+     * track when called with null. No-op when the current track does not
+     * surface text tracks or the id is unknown.
+     */
+    setActiveTextTrack(id: string | null): void;
+    private emitTextTrackChangeEventsFor;
+    /**
+     * The current track's ad breaks.
+     *
+     * Listen to {@link AdEventMap.currentTrackAdsChange} for changes.
+     */
+    get currentTrackAds(): TrackAds | null;
+    /**
+     * The ad break currently containing the playhead, or null when the
+     * playhead is in primary content.
+     *
+     * Listen to {@link AdEventMap.adBreakEntered} and
+     * {@link AdEventMap.adBreakCompleted} for transitions.
+     */
+    get currentAdBreak(): AdBreakInfo | null;
+    /**
+     * The ad currently playing within the active break, or null when the
+     * playhead is in primary content.
+     *
+     * Listen to {@link AdEventMap.adEntered} and {@link AdEventMap.adCompleted} for transitions.
+     */
+    get currentAd(): AdInfo | null;
+    /**
+     * Skips the currently playing ad. If there are more ads in the break,
+     * the next ad begins; otherwise the break ends and content resumes.
+     * No-op when no ad break is active.
+     */
+    skipAd(): void;
+    /**
+     * Skips the entire active ad break, advancing past all remaining ads
+     * and resuming content playback.
+     * No-op when no ad break is active.
+     */
+    skipAdBreak(): void;
     /**
      * Returns true if this player has been disposed.
      */

package/dist/types/ts4.7/vinyl/createVinylFactories.d.ts

@@ -11,6 +11,7 @@ import type { TrackControllerImplDeps, TrackControllerImplOptions } from '../tra
 import { TrackControllerImpl } from '../track/TrackController';
 import type { VinylPatchOptions } from './VinylPatchOptions';
 import { type QualitySelectorImplOptions } from '../streaming/abr/QualitySelectorImpl';
+import { AdControllerImpl, type AdControllerImplDeps, type AdControllerImplOptions } from '../ad/AdControllerImpl';
 import { type DrmOptions } from '../drm/DrmOptions';
 import { commonEmeFactory } from '../drm/commonEme/CommonEmeFactory';
 import { DrmControllerImpl, type DrmControllerImplDeps } from '../drm/DrmControllerImpl';
@@ -20,6 +21,7 @@ import type { Dependencies, Factories } from '@amazon/vinyl-di';
 import type { ContentStreamingOptions } from '../streaming/ContentStreamingOptions';
 import { type VinylOptions } from './VinylOptions';
 import type { ObservableValue } from '@amazon/vinyl-observable';
+import { defaultAdLoadOptionsResolver } from '../ad/defaultAdLoadOptionsResolver';
 /**
  * Configuration used by the default dependency factories for Vinyl.
  *
@@ -60,6 +62,10 @@ export interface VinylDependencyOptions {
      * Configuration for auto-reset behavior.
      */
     readonly autoReset?: Partial<AutoResetControllerImplOptions>;
+    /**
+     * Configuration for the ad controller.
+     */
+    readonly adController?: Partial<AdControllerImplOptions>;
 }
 /**
  * Creates the dependency factories for a standard player.
@@ -82,19 +88,22 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
     capabilities: (deps: CapabilitiesImplDeps) => CapabilitiesImpl;
     requestInterceptor: () => typeof noop;
     trackFactory: (deps: VinylTrackFactoryDeps) => import("..").TrackFactory<import("..").SourceObjectTrackLoadOptions | import("..").SourceTrackLoadOptions | import("..").DashTrackLoadOptions | import("..").HlsTrackLoadOptions>;
+    adTrackLoadOptionsProvider: () => typeof defaultAdLoadOptionsResolver;
     trackController: (deps: TrackControllerImplDeps<any>) => TrackControllerImpl<any>;
     drmKeySystemResolver: () => import("..").DrmKeySystemResolver;
     drmController: (deps: DrmControllerImplDeps) => DrmControllerImpl;
     commonEme: typeof commonEmeFactory;
     autoResetController: (deps: AutoResetControllerImplDeps) => AutoResetControllerImpl;
+    adController: (deps: AdControllerImplDeps) => AdControllerImpl;
     createDashFactories: (deps: import("..").DashFactoryDeps) => (loadOptions: import("..").DashTrackLoadOptions) => {
-        contentTypesValue: typeof import("..").createDashContentTypesValue;
+        baseContentTypesValue: typeof import("..").createDashContentTypesValue;
+        contentTypesValue: typeof import("..").createAllowedContentTypesValue;
         baseUrlSelector: () => import("..").BaseUrlSelector;
         segmentRequestInit: () => import("@amazon/vinyl-util").Maybe<Readonly<Omit<RequestInit, "signal">>>;
         manifestProvider: (deps: {
             readonly requestInterceptor: import("@amazon/vinyl-util").RequestInterceptor;
         }) => import("..").DashManifestProvider;
-        manifestController: (deps: import("..").DashManifestControllerImplDeps) => import("..").DashManifestController;
+        manifestController: (deps: import("..").ManifestControllerImplDeps<import("..").DashManifestData>) => import("..").ManifestControllerImpl<import("..").DashManifestData>;
         mediaSourceFactory: () => typeof import("..").createMediaSource;
         mediaQualityMetadataResolver: (deps: import("..").DashMediaQualityMetadataResolverDeps) => import("..").DashMediaQualityMetadataResolver;
         mediaSourceController: (deps: import("..").MediaSourceControllerImplDeps) => import("..").MediaSourceControllerImpl;
@@ -111,25 +120,43 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
         qualitySelector: (deps: {
             options: ObservableValue<Pick<VinylOptions, "abr">>;
         }) => import("..").QualitySelectorImpl;
+        preferredAudioLanguage: (deps: {
+            options: ObservableValue<Pick<VinylOptions, "preferredAudioLanguage">>;
+        }) => ObservableValue<string | readonly string[] | null>;
+        allowedContentTypes: (deps: {
+            options: ObservableValue<Pick<VinylOptions, "allowedContentTypes">>;
+        }) => ObservableValue<readonly import("..").RestrictableContentType[] | null>;
+        preferDescriptiveAudio: (deps: {
+            options: ObservableValue<Pick<VinylOptions, "preferDescriptiveAudio">>;
+        }) => ObservableValue<boolean>;
+        abr: (deps: {
+            options: ObservableValue<Pick<VinylOptions, "abr">>;
+        }) => ObservableValue<QualitySelectorImplOptions>;
         manifestTransformed: typeof import("..").createDefaultDashManifestTransformer;
         mediaTimeline: (deps: import("..").BuildDashMediaTimelineDeps & {
             readonly manifestTransformed: ObservableValue<Promise<import("..").DashManifestData>>;
         }) => ObservableValue<Promise<import("..").MediaTimeline>>;
         mediaTimelineTransformed: typeof import("..").createDefaultMediaTimelineTransformer;
-        options: import("@amazon/vinyl-di").Factory<ObservableValue<{
-            readonly abr: QualitySelectorImplOptions;
-            readonly preferredAudioLanguage: string | null;
-        }>>;
+        textTrackController: (deps: {
+            readonly media: HTMLMediaElement;
+            readonly manifestTransformed: ObservableValue<Promise<import("..").DashManifestData>>;
+            readonly options: ObservableValue<Pick<VinylOptions, "preferredTextLanguage" | "textCueStyle">>;
+        }) => import("..").SidecarTextTrackController;
+        options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "abr" | "preferredAudioLanguage" | "preferredTextLanguage" | "preferDescriptiveAudio" | "allowedContentTypes" | "textCueStyle">>>;
         playbackController: import("@amazon/vinyl-di").Factory<import("..").PlaybackController>;
         playbackSource: import("@amazon/vinyl-di").Factory<import("..").PlaybackSource>;
         drmKeySystemResolver: import("@amazon/vinyl-di").Factory<import("..").DrmKeySystemResolver>;
         requestInterceptor: import("@amazon/vinyl-di").Factory<import("@amazon/vinyl-util").RequestInterceptor>;
         drmController: import("@amazon/vinyl-di").Factory<import("..").DrmController>;
         capabilities: import("@amazon/vinyl-di").Factory<import("..").Capabilities>;
+        media: import("@amazon/vinyl-di").Factory<HTMLMediaElement>;
+        adController: import("@amazon/vinyl-di").Factory<import("..").AdController>;
     };
     createHlsFactories: (deps: import("..").HlsFactoryDeps) => (loadOptions: import("..").HlsTrackLoadOptions) => {
-        contentTypesValue: typeof import("..").createHlsContentTypesValue;
-        manifestController: () => import("..").HlsManifestControllerImpl;
+        baseContentTypesValue: typeof import("..").createHlsContentTypesValue;
+        contentTypesValue: typeof import("..").createAllowedContentTypesValue;
+        manifestProvider: () => import("..").HlsManifestProvider;
+        manifestController: (deps: import("..").ManifestControllerImplDeps<import("..").HlsManifestData>) => import("..").ManifestControllerImpl<import("..").HlsManifestData>;
         manifestTransformed: typeof import("..").createDefaultHlsManifestTransformer;
         mediaQualityMetadataResolver: () => import("..").HlsMediaQualityMetadataResolver;
         mediaSourceFactory: () => typeof import("..").createMediaSource;
@@ -148,20 +175,36 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
         qualitySelector: (deps: {
             options: ObservableValue<Pick<VinylOptions, "abr">>;
         }) => import("..").QualitySelectorImpl;
+        preferredAudioLanguage: (deps: {
+            options: ObservableValue<Pick<VinylOptions, "preferredAudioLanguage">>;
+        }) => ObservableValue<string | readonly string[] | null>;
+        allowedContentTypes: (deps: {
+            options: ObservableValue<Pick<VinylOptions, "allowedContentTypes">>;
+        }) => ObservableValue<readonly import("..").RestrictableContentType[] | null>;
+        preferDescriptiveAudio: (deps: {
+            options: ObservableValue<Pick<VinylOptions, "preferDescriptiveAudio">>;
+        }) => ObservableValue<boolean>;
+        abr: (deps: {
+            options: ObservableValue<Pick<VinylOptions, "abr">>;
+        }) => ObservableValue<QualitySelectorImplOptions>;
         mediaTimeline: (deps: import("..").BuildHlsMediaTimelineDeps & {
             readonly manifestTransformed: ObservableValue<Promise<import("..").HlsManifestData>>;
         }) => ObservableValue<Promise<import("..").MediaTimeline>>;
         mediaTimelineTransformed: typeof import("..").createDefaultMediaTimelineTransformer;
-        options: import("@amazon/vinyl-di").Factory<ObservableValue<{
-            readonly abr: QualitySelectorImplOptions;
-            readonly preferredAudioLanguage: string | null;
-        }>>;
+        textTrackController: (deps: {
+            readonly media: HTMLMediaElement;
+            readonly manifestTransformed: ObservableValue<Promise<import("..").HlsManifestData>>;
+            readonly options: ObservableValue<Pick<VinylOptions, "preferredTextLanguage" | "textCueStyle">>;
+        }) => import("..").SidecarTextTrackController;
+        options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "abr" | "preferredAudioLanguage" | "preferredTextLanguage" | "preferDescriptiveAudio" | "allowedContentTypes" | "textCueStyle">>>;
         playbackController: import("@amazon/vinyl-di").Factory<import("..").PlaybackController>;
         playbackSource: import("@amazon/vinyl-di").Factory<import("..").PlaybackSource>;
         drmKeySystemResolver: import("@amazon/vinyl-di").Factory<import("..").DrmKeySystemResolver>;
         requestInterceptor: import("@amazon/vinyl-di").Factory<import("@amazon/vinyl-util").RequestInterceptor>;
         drmController: import("@amazon/vinyl-di").Factory<import("..").DrmController>;
         capabilities: import("@amazon/vinyl-di").Factory<import("..").Capabilities>;
+        media: import("@amazon/vinyl-di").Factory<HTMLMediaElement>;
+        adController: import("@amazon/vinyl-di").Factory<import("..").AdController>;
     };
 };
 /**

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

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

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

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

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

@@ -0,0 +1,10 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { expectTypeStrictlyEquals } from '@amazon/vinyl-util/browserTestUtil';
+describe('ALL_AD_EVENTS', () => {
+    it('provides a comprehensive list of all ad controller state events', () => {
+        expectTypeStrictlyEquals(true);
+    });
+});

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

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

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

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