@hanifhan1f/vidstack 1.12.13

package/src/providers/html/audio/audio-gain.ts

@@ -0,0 +1,100 @@
+import type { AudioGainAdapter } from '../../types';
+import {
+  createElementSource,
+  createGainNode,
+  destroyElementSource,
+  destroyGainNode,
+  getOrCreateAudioCtx,
+} from './audio-context';
+
+export class AudioGain implements AudioGainAdapter {
+  #media: HTMLMediaElement;
+  #onChange: (gain: number | null) => void;
+  #gainNode: GainNode | null = null;
+  #srcAudioNode: MediaElementAudioSourceNode | null = null;
+
+  get currentGain() {
+    return this.#gainNode?.gain?.value ?? null;
+  }
+
+  get supported() {
+    return true;
+  }
+
+  constructor(media: HTMLMediaElement, onChange: (gain: number | null) => void) {
+    this.#media = media;
+    this.#onChange = onChange;
+  }
+
+  setGain(gain: number) {
+    const currGain = this.currentGain;
+
+    // Nothing was changed.
+    if (gain === this.currentGain) {
+      return;
+    }
+
+    // Disable audio gain, "1" means - no audio gain.
+    if (gain === 1 && currGain !== 1) {
+      this.removeGain();
+      return;
+    }
+
+    if (!this.#gainNode) {
+      this.#gainNode = createGainNode();
+
+      // Reconnect the element source to the gain node after audio gain was unset.
+      if (this.#srcAudioNode) {
+        this.#srcAudioNode.connect(this.#gainNode);
+      }
+    }
+
+    if (!this.#srcAudioNode) {
+      this.#srcAudioNode = createElementSource(this.#media, this.#gainNode);
+    }
+
+    this.#gainNode.gain.value = gain;
+    this.#onChange(gain);
+  }
+
+  removeGain() {
+    if (!this.#gainNode) return;
+
+    // Connect el audio source to the default audio output, before destroying the gain node.
+    if (this.#srcAudioNode) {
+      this.#srcAudioNode.connect(getOrCreateAudioCtx().destination);
+    }
+
+    this.#destroyGainNode();
+    this.#onChange(null);
+  }
+
+  destroy() {
+    this.#destroySrcNode();
+    this.#destroyGainNode();
+  }
+
+  #destroySrcNode() {
+    if (!this.#srcAudioNode) return;
+
+    try {
+      destroyElementSource(this.#srcAudioNode);
+    } catch (e) {
+      // Ignore any error
+    } finally {
+      this.#srcAudioNode = null;
+    }
+  }
+
+  #destroyGainNode() {
+    if (!this.#gainNode) return;
+
+    try {
+      destroyGainNode(this.#gainNode);
+    } catch (e) {
+      // Ignore any error
+    } finally {
+      this.#gainNode = null;
+    }
+  }
+}

package/src/providers/html/html/342/200/223media-events.ts

@@ -0,0 +1,338 @@
+import { effect, onDispose, peek } from 'maverick.js';
+import { DOMEvent, EventsController, isNil, listenEvent } from 'maverick.js/std';
+
+import type { MediaContext } from '../../core/api/media-context';
+import type { MediaCanPlayDetail } from '../../core/api/media-events';
+import type { MediaErrorCode } from '../../core/api/types';
+import { PageVisibility } from '../../foundation/observers/page-visibility';
+import { RAFLoop } from '../../foundation/observers/raf-loop';
+import { isHLSSrc } from '../../utils/mime';
+import { getNumberOfDecimalPlaces } from '../../utils/number';
+import { IS_IOS, IS_SAFARI } from '../../utils/support';
+import type { HTMLMediaProvider } from './provider';
+
+export class HTMLMediaEvents {
+  #provider: HTMLMediaProvider;
+  #ctx: MediaContext;
+  #waiting = false;
+  #attachedLoadStart = false;
+  #attachedCanPlay = false;
+  #timeRAF = new RAFLoop(this.#onAnimationFrame.bind(this));
+  #pageVisibility = new PageVisibility();
+  #events: EventsController<HTMLMediaElement>;
+
+  get #media() {
+    return this.#provider.media;
+  }
+
+  constructor(provider: HTMLMediaProvider, ctx: MediaContext) {
+    this.#provider = provider;
+    this.#ctx = ctx;
+    this.#events = new EventsController(provider.media);
+
+    this.#attachInitialListeners();
+
+    this.#pageVisibility.connect();
+    effect(this.#attachTimeUpdate.bind(this));
+
+    onDispose(this.#onDispose.bind(this));
+  }
+
+  #onDispose() {
+    this.#attachedLoadStart = false;
+    this.#attachedCanPlay = false;
+    this.#timeRAF.stop();
+    this.#events.abort();
+    this.#devHandlers?.clear();
+  }
+
+  /**
+   * The `timeupdate` event fires surprisingly infrequently during playback, meaning your progress
+   * bar (or whatever else is synced to the currentTime) moves in a choppy fashion. This helps
+   * resolve that by retrieving time updates in a request animation frame loop.
+   */
+  #lastSeenTime = 0;
+  #seekedTo = -1;
+  #onAnimationFrame() {
+    const newTime = this.#media.currentTime;
+
+    // Avoid stuttering on Safari (after a seek operation time may drift backwards for a few frames).
+    const didStutter = IS_SAFARI && newTime - this.#seekedTo < 0.35;
+
+    if (!didStutter && this.#lastSeenTime !== newTime) {
+      this.#updateCurrentTime(newTime);
+      this.#lastSeenTime = newTime;
+    }
+  }
+
+  #attachInitialListeners() {
+    if (__DEV__) {
+      this.#ctx.logger?.info('attaching initial listeners');
+    }
+
+    this.#attachEventListener('loadstart', this.#onLoadStart);
+    this.#attachEventListener('abort', this.#onAbort);
+    this.#attachEventListener('emptied', this.#onEmptied);
+    this.#attachEventListener('error', this.#onError);
+    this.#attachEventListener('volumechange', this.#onVolumeChange);
+
+    if (__DEV__) this.#ctx.logger?.debug('attached initial media event listeners');
+  }
+
+  #attachLoadStartListeners() {
+    if (this.#attachedLoadStart) return;
+
+    if (__DEV__) {
+      this.#ctx.logger?.info('attaching load start listeners');
+    }
+
+    this.#attachEventListener('loadeddata', this.#onLoadedData);
+    this.#attachEventListener('loadedmetadata', this.#onLoadedMetadata);
+    this.#attachEventListener('canplay', this.#onCanPlay);
+    this.#attachEventListener('canplaythrough', this.#onCanPlayThrough);
+    this.#attachEventListener('durationchange', this.#onDurationChange);
+    this.#attachEventListener('play', this.#onPlay);
+    this.#attachEventListener('progress', this.#onProgress);
+    this.#attachEventListener('stalled', this.#onStalled);
+    this.#attachEventListener('suspend', this.#onSuspend);
+    this.#attachEventListener('ratechange', this.#onRateChange);
+
+    this.#attachedLoadStart = true;
+  }
+
+  #attachCanPlayListeners() {
+    if (this.#attachedCanPlay) return;
+
+    if (__DEV__) {
+      this.#ctx.logger?.info('attaching can play listeners');
+    }
+
+    this.#attachEventListener('pause', this.#onPause);
+    this.#attachEventListener('playing', this.#onPlaying);
+    this.#attachEventListener('seeked', this.#onSeeked);
+    this.#attachEventListener('seeking', this.#onSeeking);
+    this.#attachEventListener('ended', this.#onEnded);
+    this.#attachEventListener('waiting', this.#onWaiting);
+
+    this.#attachedCanPlay = true;
+  }
+
+  #devHandlers = __DEV__ ? new Map<string, (event: Event) => void>() : undefined;
+  #handleDevEvent = __DEV__ ? this.#onDevEvent.bind(this) : undefined;
+  #attachEventListener(eventType: keyof HTMLElementEventMap, handler: (event: Event) => void) {
+    if (__DEV__) this.#devHandlers!.set(eventType, handler);
+    this.#events.add(eventType, __DEV__ ? this.#handleDevEvent! : handler.bind(this));
+  }
+
+  #onDevEvent(event: Event) {
+    if (!__DEV__) return;
+
+    this.#ctx.logger
+      ?.debugGroup(`📺 provider fired \`${event.type}\``)
+      .labelledLog('Provider', this.#provider)
+      .labelledLog('Event', event)
+      .labelledLog('Media Store', { ...this.#ctx.$state })
+      .dispatch();
+
+    this.#devHandlers!.get(event.type)?.call(this, event);
+  }
+
+  #updateCurrentTime(time: number, trigger?: Event) {
+    // Avoid errors where `currentTime` can have higher precision.
+    const newTime = Math.min(time, this.#ctx.$state.seekableEnd());
+    this.#ctx.notify('time-change', newTime, trigger);
+  }
+
+  #onLoadStart(event: Event) {
+    if (this.#media.networkState === 3) {
+      this.#onAbort(event);
+      return;
+    }
+
+    this.#attachLoadStartListeners();
+    this.#ctx.notify('load-start', undefined, event);
+  }
+
+  #onAbort(event: Event) {
+    this.#ctx.notify('abort', undefined, event);
+  }
+
+  #onEmptied() {
+    this.#ctx.notify('emptied', undefined, event);
+  }
+
+  #onLoadedData(event: Event) {
+    this.#ctx.notify('loaded-data', undefined, event);
+  }
+
+  #onLoadedMetadata(event: Event) {
+    // Reset.
+    this.#lastSeenTime = 0;
+    this.#seekedTo = -1;
+
+    this.#attachCanPlayListeners();
+
+    this.#ctx.notify('loaded-metadata', undefined, event);
+
+    // iOS Safari and Native HLS do not reliably fire `canplay` event.
+    if (IS_IOS || (IS_SAFARI && isHLSSrc(this.#ctx.$state.source()))) {
+      this.#ctx.delegate.ready(this.#getCanPlayDetail(), event);
+    }
+  }
+
+  #getCanPlayDetail(): MediaCanPlayDetail {
+    return {
+      provider: peek(this.#ctx.$provider)!,
+      duration: this.#media.duration,
+      buffered: this.#media.buffered,
+      seekable: this.#media.seekable,
+    };
+  }
+
+  #onPlay(event: Event) {
+    if (!this.#ctx.$state.canPlay) return;
+    this.#ctx.notify('play', undefined, event);
+  }
+
+  #onPause(event: Event) {
+    // Avoid seeking events triggering pause.
+    if (this.#media.readyState === 1 && !this.#waiting) return;
+    this.#waiting = false;
+    this.#timeRAF.stop();
+    this.#ctx.notify('pause', undefined, event);
+  }
+
+  #onCanPlay(event: Event) {
+    this.#ctx.delegate.ready(this.#getCanPlayDetail(), event);
+  }
+
+  #onCanPlayThrough(event: Event) {
+    if (this.#ctx.$state.started()) return;
+    this.#ctx.notify('can-play-through', this.#getCanPlayDetail(), event);
+  }
+
+  #onPlaying(event: Event) {
+    // This event can incorrectly fire on Safari.
+    if (this.#media.paused) return;
+    this.#waiting = false;
+    this.#ctx.notify('playing', undefined, event);
+    this.#timeRAF.start();
+  }
+
+  #onStalled(event: Event) {
+    this.#ctx.notify('stalled', undefined, event);
+    if (this.#media.readyState < 3) {
+      this.#waiting = true;
+      this.#ctx.notify('waiting', undefined, event);
+    }
+  }
+
+  #onWaiting(event: Event) {
+    if (this.#media.readyState < 3) {
+      this.#waiting = true;
+      this.#ctx.notify('waiting', undefined, event);
+    }
+  }
+
+  #onEnded(event: Event) {
+    this.#timeRAF.stop();
+    this.#updateCurrentTime(this.#media.duration, event);
+    this.#ctx.notify('end', undefined, event);
+    if (this.#ctx.$state.loop()) {
+      const hasCustomControls = isNil(this.#media.controls);
+      // Forcefully hide controls to prevent flashing when looping. Calling `play()` at end
+      // of media may show a flash of native controls on iOS, even if `controls` property is not set.
+      if (hasCustomControls) this.#media.controls = false;
+    }
+  }
+
+  #attachTimeUpdate() {
+    const isPaused = this.#ctx.$state.paused(),
+      isPageHidden = this.#pageVisibility.visibility === 'hidden',
+      shouldListenToTimeUpdates = isPaused || isPageHidden;
+
+    if (shouldListenToTimeUpdates) {
+      listenEvent(this.#media, 'timeupdate', this.#onTimeUpdate.bind(this));
+    }
+  }
+
+  #onTimeUpdate(event: Event) {
+    this.#updateCurrentTime(this.#media.currentTime, event);
+  }
+
+  #onDurationChange(event: Event) {
+    if (this.#ctx.$state.ended()) {
+      this.#updateCurrentTime(this.#media.duration, event);
+    }
+
+    this.#ctx.notify('duration-change', this.#media.duration, event);
+  }
+
+  #onVolumeChange(event: Event) {
+    const detail = {
+      volume: this.#media.volume,
+      muted: this.#media.muted,
+    };
+
+    this.#ctx.notify('volume-change', detail, event);
+  }
+
+  #onSeeked(event: Event) {
+    this.#seekedTo = this.#media.currentTime;
+
+    this.#updateCurrentTime(this.#media.currentTime, event);
+
+    this.#ctx.notify('seeked', this.#media.currentTime, event);
+
+    // HLS: If precision has increased by seeking to the end, we'll call `play()` to properly end.
+    if (
+      Math.trunc(this.#media.currentTime) === Math.trunc(this.#media.duration) &&
+      getNumberOfDecimalPlaces(this.#media.duration) >
+        getNumberOfDecimalPlaces(this.#media.currentTime)
+    ) {
+      this.#updateCurrentTime(this.#media.duration, event);
+
+      if (!this.#media.ended) {
+        this.#ctx.player.dispatch(
+          new DOMEvent<void>('media-play-request', {
+            trigger: event,
+          }),
+        );
+      }
+    }
+  }
+
+  #onSeeking(event: Event) {
+    this.#ctx.notify('seeking', this.#media.currentTime, event);
+  }
+
+  #onProgress(event: Event) {
+    const detail = {
+      buffered: this.#media.buffered,
+      seekable: this.#media.seekable,
+    };
+
+    this.#ctx.notify('progress', detail, event);
+  }
+
+  #onSuspend(event: Event) {
+    this.#ctx.notify('suspend', undefined, event);
+  }
+
+  #onRateChange(event: Event) {
+    this.#ctx.notify('rate-change', this.#media.playbackRate, event);
+  }
+
+  #onError(event: Event) {
+    const error = this.#media.error;
+    if (!error) return;
+
+    const detail = {
+      message: error.message,
+      code: error.code as MediaErrorCode,
+      mediaError: error,
+    };
+
+    this.#ctx.notify('error', detail, event);
+  }
+}

package/src/providers/html/native-audio-tracks.ts

@@ -0,0 +1,91 @@
+import { listenEvent } from 'maverick.js/std';
+
+import type { MediaContext } from '../../core/api/media-context';
+import type { AudioTrack } from '../../core/tracks/audio/audio-tracks';
+import type { AudioTrackChangeEvent } from '../../core/tracks/audio/events';
+import { ListSymbol } from '../../foundation/list/symbols';
+import type { HTMLMediaProvider } from './provider';
+
+interface NativeAudioTrack {
+  id: string;
+  label: string;
+  language: string;
+  kind: string;
+  enabled: boolean;
+}
+
+interface NativeAudioEvent extends Event {
+  track: NativeAudioTrack;
+}
+
+interface NativeAudioTrackList extends Iterable<NativeAudioTrack> {
+  onaddtrack: ((event: NativeAudioEvent) => void) | null;
+  onremovetrack: ((event: NativeAudioEvent) => void) | null;
+  onchange: ((event: NativeAudioEvent) => void) | null;
+  getTrackById(id: string): NativeAudioTrack | null;
+}
+
+export class NativeAudioTracks {
+  #provider: HTMLMediaProvider;
+  #ctx: MediaContext;
+
+  get #nativeTracks(): NativeAudioTrackList {
+    return (this.#provider.media as any).audioTracks;
+  }
+
+  constructor(provider: HTMLMediaProvider, ctx: MediaContext) {
+    this.#provider = provider;
+    this.#ctx = ctx;
+
+    this.#nativeTracks.onaddtrack = this.#onAddNativeTrack.bind(this);
+    this.#nativeTracks.onremovetrack = this.#onRemoveNativeTrack.bind(this);
+    this.#nativeTracks.onchange = this.#onChangeNativeTrack.bind(this);
+
+    listenEvent(this.#ctx.audioTracks, 'change', this.#onChangeTrack.bind(this));
+  }
+
+  #onAddNativeTrack(event: NativeAudioEvent) {
+    const nativeTrack = event.track;
+
+    if (nativeTrack.label === '') return;
+
+    const id = nativeTrack.id.toString() || `native-audio-${this.#ctx.audioTracks.length}`,
+      audioTrack: AudioTrack = {
+        id,
+        label: nativeTrack.label,
+        language: nativeTrack.language,
+        kind: nativeTrack.kind,
+        selected: false,
+      };
+
+    this.#ctx.audioTracks[ListSymbol.add](audioTrack, event);
+    if (nativeTrack.enabled) audioTrack.selected = true;
+  }
+
+  #onRemoveNativeTrack(event: NativeAudioEvent) {
+    const track = this.#ctx.audioTracks.getById(event.track.id);
+    if (track) this.#ctx.audioTracks[ListSymbol.remove](track, event);
+  }
+
+  #onChangeNativeTrack(event: NativeAudioEvent) {
+    let enabledTrack = this.#getEnabledNativeTrack();
+    if (!enabledTrack) return;
+    const track = this.#ctx.audioTracks.getById(enabledTrack.id);
+    if (track) this.#ctx.audioTracks[ListSymbol.select](track, true, event);
+  }
+
+  #getEnabledNativeTrack(): NativeAudioTrack | undefined {
+    return Array.from(this.#nativeTracks).find((track) => track.enabled);
+  }
+
+  #onChangeTrack(event: AudioTrackChangeEvent) {
+    const { current } = event.detail;
+    if (!current) return;
+    const track = this.#nativeTracks.getTrackById(current.id);
+    if (track) {
+      const prev = this.#getEnabledNativeTrack();
+      if (prev) prev.enabled = false;
+      track.enabled = true;
+    }
+  }
+}

package/src/providers/html/provider.ts

@@ -0,0 +1,141 @@
+import { createScope, onDispose } from 'maverick.js';
+import { isString, setAttribute } from 'maverick.js/std';
+
+import type { MediaContext } from '../../core/api/media-context';
+import type { HTMLMediaSrc, Src } from '../../core/api/src-types';
+import { isMediaStream } from '../../utils/mime';
+import type { MediaProviderAdapter } from '../types';
+import { AudioGain } from './audio/audio-gain';
+import { HTMLMediaEvents } from './html–media-events';
+import { NativeAudioTracks } from './native-audio-tracks';
+
+/**
+ * This HTML media provider adapts the underlying media element such as `<audio>` or `<video>` to
+ * satisfy the media provider interface.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement}
+ */
+export class HTMLMediaProvider implements MediaProviderAdapter {
+  readonly scope = createScope();
+
+  currentSrc: Src<HTMLMediaSrc> | null = null;
+
+  readonly audioGain: AudioGain;
+
+  constructor(
+    readonly media: HTMLMediaElement,
+    protected readonly ctx: MediaContext,
+  ) {
+    this.audioGain = new AudioGain(media, (gain) => {
+      this.ctx.notify('audio-gain-change', gain);
+    });
+  }
+
+  setup() {
+    new HTMLMediaEvents(this, this.ctx);
+
+    if ('audioTracks' in this.media) new NativeAudioTracks(this, this.ctx);
+
+    onDispose(() => {
+      this.audioGain.destroy();
+
+      // We need to remove all media sources incase another provider uses the same media element.
+      this.media.srcObject = null;
+      this.media.removeAttribute('src');
+      for (const source of this.media.querySelectorAll('source')) source.remove();
+
+      this.media.load();
+    });
+  }
+
+  get type() {
+    return '';
+  }
+
+  setPlaybackRate(rate: number) {
+    this.media.playbackRate = rate;
+  }
+
+  async play() {
+    return this.media.play();
+  }
+
+  async pause() {
+    return this.media.pause();
+  }
+
+  setMuted(muted: boolean) {
+    this.media.muted = muted;
+  }
+
+  setVolume(volume: number) {
+    this.media.volume = volume;
+  }
+
+  setCurrentTime(time: number) {
+    this.media.currentTime = time;
+  }
+
+  setPlaysInline(inline: boolean) {
+    setAttribute(this.media, 'playsinline', inline);
+  }
+
+  async loadSource({ src, type }: Src, preload?: HTMLMediaElement['preload']) {
+    this.media.preload = preload || '';
+
+    if (isMediaStream(src)) {
+      this.removeSource();
+      this.media.srcObject = src;
+    } else {
+      this.media.srcObject = null;
+      if (isString(src)) {
+        if (type !== '?') {
+          this.appendSource({ src, type });
+        } else {
+          this.removeSource();
+          this.media.src = this.#appendMediaFragment(src);
+        }
+      } else {
+        this.removeSource();
+        this.media.src = window.URL.createObjectURL(src as MediaSource | Blob);
+      }
+    }
+
+    this.media.load();
+    this.currentSrc = { src: src as HTMLMediaSrc, type };
+  }
+
+  /**
+   * Append source so it works when requesting AirPlay since hls.js will remove it.
+   */
+  protected appendSource(src: Src<string>, defaultType?: string) {
+    const prevSource = this.media.querySelector('source[data-vds]'),
+      source = prevSource ?? document.createElement('source');
+
+    setAttribute(source, 'src', this.#appendMediaFragment(src.src));
+    setAttribute(source, 'type', src.type !== '?' ? src.type : defaultType);
+    setAttribute(source, 'data-vds', '');
+
+    if (!prevSource) this.media.append(source);
+  }
+
+  protected removeSource() {
+    this.media.querySelector('source[data-vds]')?.remove();
+  }
+
+  #appendMediaFragment(src: string) {
+    const { clipStartTime, clipEndTime } = this.ctx.$state,
+      startTime = clipStartTime(),
+      endTime = clipEndTime();
+
+    if (startTime > 0 && endTime > 0) {
+      return `${src}#t=${startTime},${endTime}`;
+    } else if (startTime > 0) {
+      return `${src}#t=${startTime}`;
+    } else if (endTime > 0) {
+      return `${src}#t=0,${endTime}`;
+    }
+
+    return src;
+  }
+}