@hanifhan1f/vidstack 1.12.13

package/src/core/api/media-request-events.ts

@@ -0,0 +1,323 @@
+import type { DOMEvent } from 'maverick.js/std';
+
+import type { ScreenOrientationLockType } from '../../foundation/orientation/types';
+
+export interface MediaRequestEvents {
+  'media-airplay-request': MediaAirPlayRequestEvent;
+  'media-audio-track-change-request': MediaAudioTrackChangeRequestEvent;
+  'media-clip-start-change-request': MediaClipStartChangeRequestEvent;
+  'media-clip-end-change-request': MediaClipEndChangeRequestEvent;
+  'media-duration-change-request': MediaDurationChangeRequestEvent;
+  'media-enter-fullscreen-request': MediaEnterFullscreenRequestEvent;
+  'media-exit-fullscreen-request': MediaExitFullscreenRequestEvent;
+  'media-enter-pip-request': MediaEnterPIPRequestEvent;
+  'media-exit-pip-request': MediaExitPIPRequestEvent;
+  'media-google-cast-request': MediaGoogleCastRequestEvent;
+  'media-live-edge-request': MediaLiveEdgeRequestEvent;
+  'media-loop-request': MediaLoopRequestEvent;
+  'media-user-loop-change-request': MediaUserLoopChangeRequestEvent;
+  'media-orientation-lock-request': MediaOrientationLockRequestEvent;
+  'media-orientation-unlock-request': MediaOrientationUnlockRequestEvent;
+  'media-mute-request': MediaMuteRequestEvent;
+  'media-pause-request': MediaPauseRequestEvent;
+  'media-pause-controls-request': MediaPauseControlsRequestEvent;
+  'media-play-request': MediaPlayRequestEvent;
+  'media-quality-change-request': MediaQualityChangeRequestEvent;
+  'media-rate-change-request': MediaRateChangeRequestEvent;
+  'media-audio-gain-change-request': MediaAudioGainChangeRequestEvent;
+  'media-resume-controls-request': MediaResumeControlsRequestEvent;
+  'media-seek-request': MediaSeekRequestEvent;
+  'media-seeking-request': MediaSeekingRequestEvent;
+  'media-start-loading': MediaStartLoadingRequestEvent;
+  'media-poster-start-loading': MediaPosterStartLoadingRequestEvent;
+  'media-text-track-change-request': MediaTextTrackChangeRequestEvent;
+  'media-unmute-request': MediaUnmuteRequestEvent;
+  'media-volume-change-request': MediaVolumeChangeRequestEvent;
+}
+
+/**
+ * Fired when requesting the AirPlay picker to open.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaAirPlayRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting the media poster to begin loading. This will only take effect if the
+ * `posterLoad` strategy on the player is set to `custom`.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaPosterStartLoadingRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting to change the `mode` on a text track at the given index in the
+ * `TextTrackList` on the player.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaTextTrackChangeRequestEvent
+  extends DOMEvent<{
+    index: number;
+    mode: TextTrackMode;
+  }> {}
+
+/**
+ * Fired when requesting the media to be muted.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaMuteRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting the media to be unmuted.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaUnmuteRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Whether to request fullscreen on the media (i.e., `<media-player>`). The `prefer-media` option
+ * will first see if the native fullscreen API is available, if not it'll try the media provider.
+ */
+export type MediaFullscreenRequestTarget = 'prefer-media' | 'media' | 'provider';
+
+/**
+ * Fired when requesting to change the current audio track to the given index in the
+ * `AudioTrackList` on the player.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaAudioTrackChangeRequestEvent extends DOMEvent<number> {}
+
+/**
+ * Fired when requesting to change the clip start time. The event `detail` specifies the new start
+ * time in seconds.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaClipStartChangeRequestEvent extends DOMEvent<number> {}
+
+/**
+ * Fired when requesting to change the clip end time. The event `detail` specifies the new end
+ * time in seconds.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaClipEndChangeRequestEvent extends DOMEvent<number> {}
+
+/**
+ * Fired when requesting to change the length of the media. The event `detail` specifies the
+ * new length in seconds.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaDurationChangeRequestEvent extends DOMEvent<number> {}
+
+/**
+ * Fired when requesting media to enter fullscreen. The event `detail` can specify the
+ * fullscreen target, which can be the media or provider (defaults to `prefer-media`).
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaEnterFullscreenRequestEvent extends DOMEvent<MediaFullscreenRequestTarget> {}
+
+/**
+ * Fired when requesting media to exit fullscreen. The event `detail` can specify the fullscreen
+ * target, which can be the media or provider (defaults to `prefer-media`).
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaExitFullscreenRequestEvent extends DOMEvent<MediaFullscreenRequestTarget> {}
+
+/**
+ * Fired when requesting media to enter picture-in-picture mode.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaEnterPIPRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting media to exit picture-in-picture mode.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaExitPIPRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting Google Cast.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaGoogleCastRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting media to seek to the live edge (i.e., set the current time to the current
+ * live time).
+ */
+export interface MediaLiveEdgeRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting media playback to begin/resume.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaPlayRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting to change the current video quality to the given index in the
+ * `VideoQualityList` on the player.
+ *
+ * @bubbles
+ * @composed
+ * @detail qualityIndex
+ */
+export interface MediaQualityChangeRequestEvent extends DOMEvent<number> {}
+
+/**
+ * Fired when requesting to change the current playback rate.
+ *
+ * @bubbles
+ * @composed
+ * @detail rate
+ */
+export interface MediaRateChangeRequestEvent extends DOMEvent<number> {}
+
+/**
+ * Fired when requesting to change the current audio gain.
+ *
+ * @bubbles
+ * @composed
+ * @detail gain
+ */
+export interface MediaAudioGainChangeRequestEvent extends DOMEvent<number> {}
+
+/**
+ * Fired when requesting media playback to temporarily stop.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaPauseRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting a time change. In other words, moving the play head to a new position.
+ *
+ * @bubbles
+ * @composed
+ * @detail seekTo
+ */
+export interface MediaSeekRequestEvent extends DOMEvent<number> {}
+
+/**
+ * Fired when seeking/scrubbing to a new playback position.
+ *
+ * @bubbles
+ * @composed
+ * @detail time
+ */
+export interface MediaSeekingRequestEvent extends DOMEvent<number> {}
+
+/**
+ * Fired when requesting media to begin loading. This will only take effect if the `load`
+ * strategy on the player is set to `custom`.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaStartLoadingRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting the media volume to be set to a new level.
+ *
+ * @bubbles
+ * @composed
+ * @detail volume
+ */
+export interface MediaVolumeChangeRequestEvent extends DOMEvent<number> {}
+
+/**
+ * Fired when controls visibility tracking may resume. This is typically called after requesting
+ * tracking to pause via `media-pause-controls-request`.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaResumeControlsRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when controls visibility tracking should pause. This is typically used when a control
+ * is being actively interacted with, and we don't want the controls to be hidden before
+ * the interaction is complete (eg: scrubbing, or settings is open).
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaPauseControlsRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting the poster _should_ be rendered by the media provider. This should be
+ * fired if a custom poster is _not_ being used.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaShowPosterRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when requesting the poster should _not_ be rendered by the media provider. This
+ * should be fired if a custom poster element is being used (e.g., `media-poster`).
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaHidePosterRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Internal event that is fired by a media provider when requesting media playback to restart after
+ * reaching the end. This event also helps notify the player that media will be looping.
+ *
+ * @internal
+ * @bubbles
+ * @composed
+ */
+export interface MediaLoopRequestEvent extends DOMEvent<void> {}
+
+/**
+ * Fired when the user loop preference changes.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaUserLoopChangeRequestEvent extends DOMEvent<boolean> {}
+
+/**
+ * Fired when requesting the screen orientation to be locked to a certain type.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaOrientationLockRequestEvent extends DOMEvent<ScreenOrientationLockType> {}
+
+/**
+ * Fired when requesting the screen orientation to be unlocked.
+ *
+ * @bubbles
+ * @composed
+ */
+export interface MediaOrientationUnlockRequestEvent extends DOMEvent<void> {}

package/src/core/api/player-controller.ts

@@ -0,0 +1,10 @@
+import { ViewController } from 'maverick.js';
+import type { MediaPlayerEvents } from './player-events';
+import type { MediaPlayerProps } from './player-props';
+import type { MediaPlayerState } from './player-state';
+
+export class MediaPlayerController extends ViewController<
+  MediaPlayerProps,
+  MediaPlayerState,
+  MediaPlayerEvents
+> {}

package/src/core/api/player-events.ts

@@ -0,0 +1,49 @@
+import type { DOMEvent } from 'maverick.js/std';
+
+import type { MediaPlayer } from '../../components/player';
+import type { LoggerEvents } from '../../foundation/logger/events';
+import type { DASHProviderEvents } from '../../providers/dash/events';
+import type { GoogleCastEvents } from '../../providers/google-cast/events';
+import type { HLSProviderEvents } from '../../providers/hls/events';
+import type { VideoPresentationEvents } from '../../providers/video/presentation/events';
+import type { MediaEvents } from './media-events';
+import type { MediaRequestEvents } from './media-request-events';
+
+export interface MediaPlayerEvents
+  extends MediaEvents,
+    MediaRequestEvents,
+    MediaUserEvents,
+    LoggerEvents,
+    VideoPresentationEvents,
+    HLSProviderEvents,
+    DASHProviderEvents,
+    GoogleCastEvents {
+  'media-player-connect': MediaPlayerConnectEvent;
+  /** @internal */
+  'find-media-player': FindMediaPlayerEvent;
+  /** @internal */
+  'vds-font-change': Event;
+}
+
+/**
+ * Fired when the player element `<media-player>` connects to the DOM.
+ *
+ * @bubbles
+ * @composed
+ * @detail player
+ */
+export interface MediaPlayerConnectEvent extends DOMEvent<MediaPlayer> {}
+
+export interface FindMediaPlayerEventDetail {
+  (player: MediaPlayer | null): void;
+}
+
+/**
+ * @internal
+ * @bubbles
+ * @composed
+ * @detail callback
+ */
+export interface FindMediaPlayerEvent extends DOMEvent<FindMediaPlayerEventDetail> {}
+
+export interface MediaUserEvents {}

package/src/core/api/player-props.ts

@@ -0,0 +1,233 @@
+import type { Writable } from 'type-fest';
+
+import type { LogLevel } from '../../foundation/logger/log-level';
+import type { ScreenOrientationLockType } from '../../foundation/orientation/types';
+import type { GoogleCastOptions } from '../../providers/google-cast/types';
+import { MEDIA_KEY_SHORTCUTS } from '../keyboard/controller';
+import type { MediaKeyShortcuts, MediaKeyTarget } from '../keyboard/types';
+import type { MediaStorage } from '../state/media-storage';
+import type { MediaState } from './player-state';
+import type { MediaSrc } from './src-types';
+import type { MediaLoadingStrategy, MediaPosterLoadingStrategy } from './types';
+
+export const mediaPlayerProps: MediaPlayerProps = {
+  artist: '',
+  artwork: null,
+  autoplay: false,
+  autoPlay: false,
+  clipStartTime: 0,
+  clipEndTime: 0,
+  controls: false,
+  currentTime: 0,
+  crossorigin: null,
+  crossOrigin: null,
+  duration: -1,
+  fullscreenOrientation: 'landscape',
+  googleCast: {},
+  load: 'visible',
+  posterLoad: 'visible',
+  logLevel: __DEV__ ? 'warn' : 'silent',
+  loop: false,
+  muted: false,
+  paused: true,
+  playsinline: false,
+  playsInline: false,
+  playbackRate: 1,
+  poster: '',
+  preload: 'metadata',
+  preferNativeHLS: false,
+  src: '',
+  title: '',
+  controlsDelay: 2000,
+  hideControlsOnMouseLeave: false,
+  viewType: 'unknown',
+  streamType: 'unknown',
+  volume: 1,
+  liveEdgeTolerance: 10,
+  minLiveDVRWindow: 60,
+  keyDisabled: false,
+  keyTarget: 'player',
+  keyShortcuts: MEDIA_KEY_SHORTCUTS,
+  storage: null,
+};
+
+export interface MediaStateAccessors
+  extends Pick<MediaState, 'paused' | 'muted' | 'volume' | 'currentTime' | 'playbackRate'> {}
+
+export type PlayerSrc = MediaSrc | MediaSrc[];
+
+export interface MediaPlayerProps
+  // Prefer picking off the `MediaStore` type to ensure docs are kept in-sync.
+  extends Pick<
+    Writable<MediaState>,
+    | 'artist'
+    | 'artwork'
+    | 'autoPlay'
+    | 'clipStartTime'
+    | 'clipEndTime'
+    | 'controls'
+    | 'currentTime'
+    | 'loop'
+    | 'muted'
+    | 'paused'
+    | 'playsInline'
+    | 'poster'
+    | 'preload'
+    | 'playbackRate'
+    | 'viewType'
+    | 'volume'
+    | 'title'
+    // live
+    | 'streamType'
+    | 'liveEdgeTolerance'
+    | 'minLiveDVRWindow'
+  > {
+  /** @deprecated - Use `autoPlay` */
+  autoplay: boolean;
+  /** @deprecated - Use `crossOrigin` */
+  crossorigin: string | true | null;
+  /**
+   * Defines how the media element handles cross-origin requests, thereby enabling the
+   * configuration of the CORS requests for the element's fetched data.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin}
+   */
+  crossOrigin: true | MediaState['crossOrigin'];
+  /**
+   * A `double` indicating the total playback length of the media in seconds. If this is not
+   * provided it will be determined when the media loaded.
+   */
+  duration: number;
+  /**
+   * The URL and optionally type of the current media resource/s to be considered for playback.
+   *
+   * @see {@link https://vidstack.io/docs/player/core-concepts/loading#sources}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/src}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/srcObject}
+   */
+  src: PlayerSrc;
+  /**
+   * The current log level. Values in order of priority are: `silent`, `error`, `warn`, `info`,
+   * and `debug`.
+   */
+  logLevel: LogLevel;
+  /**
+   * Indicates when the provider can begin loading media.
+   *
+   * - `eager`: media will be loaded immediately.
+   * - `idle`: media will be loaded after the page has loaded and `requestIdleCallback` is fired.
+   * - `visible`: media will delay loading until the provider has entered the viewport.
+   * - `custom`: media will wait for the `startLoading()` method or `media-start-loading` event.
+   * - `play`: media will delay loading until there is a play request.
+   *
+   *  @see {@link https://vidstack.io/docs/player/core-concepts/loading#load-strategies}
+   */
+  load: MediaLoadingStrategy;
+  /**
+   * Indicates when the player can begin loading the poster.
+   *
+   * - `eager`: poster will be loaded immediately.
+   * - `idle`: poster will be loaded after the page has loaded and `requestIdleCallback` is fired.
+   * - `visible`: poster will delay loading until the provider has entered the viewport.
+   * - `custom`: poster will wait for the `startLoadingPoster()` method or `media-poster-start-loading` event.
+   *
+   *  @see {@link https://vidstack.io/docs/player/core-concepts/loading#load-strategies}
+   */
+  posterLoad: MediaPosterLoadingStrategy;
+  /**
+   * The default amount of delay in milliseconds while media playback is progressing without user
+   * activity to indicate an idle state and hide controls.
+   */
+  controlsDelay: number;
+  /**
+   * Whether controls visibility should be toggled when the mouse enters and leaves the player
+   * container.
+   */
+  hideControlsOnMouseLeave: boolean;
+  /**
+   * This method will indicate the orientation to lock the screen to when in fullscreen mode and
+   * the Screen Orientation API is available.
+   */
+  fullscreenOrientation: ScreenOrientationLockType | 'none' | undefined;
+  /**
+   * Google Cast options.
+   *
+   * @see {@link https://developers.google.com/cast/docs/reference/web_sender/cast.framework.CastOptions}
+   */
+  googleCast: GoogleCastOptions;
+  /** @deprecated - Use `playsInline`. */
+  playsinline: boolean;
+  /**
+   * Whether native HLS support is preferred over using `hls.js`. We recommend setting this to
+   * `false` to ensure a consistent and configurable experience across browsers. In addition, our
+   * live stream support and DVR detection is much better with `hls.js` so choose accordingly.
+   *
+   * This should generally only be set to `true` if (1) you're working with HLS streams, and (2)
+   * you want AirPlay to work via the native Safari controls (i.e., `controls` attribute is
+   * present on the `<media-player>` element).
+   */
+  preferNativeHLS: boolean;
+  /**
+   * Whether keyboard support is disabled for the media player globally. This property won't disable
+   * standard ARIA keyboard controls for individual components when focused.
+   *
+   * @defaultValue 'false'
+   */
+  keyDisabled: boolean;
+  /**
+   * The target on which to listen for keyboard events (e.g., `keydown`):
+   *
+   * - `document`: the player will listen for events on the entire document. In the case that
+   * multiple players are on the page, only the most recently active player will receive input.
+   * - `player`: the player will listen for events on the player itself or one of its children
+   * were recently interacted with.
+   *
+   * @defaultValue `player`
+   */
+  keyTarget: MediaKeyTarget;
+  /**
+   * Extends global media player keyboard shortcuts. The shortcuts can be specified as a
+   * space-separated list of combinations (e.g., `p Control+Space`), array, or callbacks. See the
+   * provided doc link for more information.
+   *
+   * Do note, if `aria-keyshortcuts` is specified on a component then it will take precedence
+   * over the respective value set here.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts}
+   * @example
+   * ```ts
+   * player.keyShortcuts = {
+   *  // Space-separated list.
+   *  togglePaused: 'k Space',
+   *  toggleMuted: 'm',
+   *  toggleFullscreen: 'f',
+   *  togglePictureInPicture: 'i',
+   *  toggleCaptions: 'c',
+   *  // Array.
+   *  seekBackward: ['j', 'J', 'ArrowLeft'],
+   *  seekForward: ['l', 'L', 'ArrowRight'],
+   *  volumeUp: 'ArrowUp',
+   *  volumeDown: 'ArrowDown',
+   *  speedUp: '>',
+   *  slowDown: '<',
+   *  // Callback.
+   *  fooBar: {
+   *    keys: ['k', 'Space'],
+   *    callback(event) {}
+   *   },
+   * }
+   * ```
+   */
+  keyShortcuts: MediaKeyShortcuts;
+  /**
+   * Determines whether volume, time, and other player settings should be saved to storage
+   * and used when initializing media. The two options for enabling storage are:
+   *
+   * 1. You can provide a string which will use our local storage solution and the given string as
+   * a key prefix.
+   *
+   * 2. Or, you can provide your own storage solution (e.g., database) by implementing
+   * the `MediaStorage` interface and providing the object/class.
+   */
+  storage: string | MediaStorage | null;
+}