@hanifhan1f/vidstack 1.12.13

package/src/providers/hls/hls.ts

@@ -0,0 +1,290 @@
+import type * as HLS from 'hls.js';
+import { effect, peek } from 'maverick.js';
+import { camelToKebabCase, DOMEvent, isString, listenEvent } from 'maverick.js/std';
+
+import type { MediaContext } from '../../core/api/media-context';
+import type { Src } from '../../core/api/src-types';
+import { QualitySymbol } from '../../core/quality/symbols';
+import { TextTrackSymbol } from '../../core/tracks/text/symbols';
+import { TextTrack } from '../../core/tracks/text/text-track';
+import { ListSymbol } from '../../foundation/list/symbols';
+import { RAFLoop } from '../../foundation/observers/raf-loop';
+import { IS_CHROME } from '../../utils/support';
+import type { HLSConstructor, HLSInstanceCallback } from './types';
+
+const toDOMEventType = (type: string) => camelToKebabCase(type);
+
+export class HLSController {
+  #video: HTMLVideoElement;
+  #ctx: MediaContext;
+  #instance: HLS.default | null = null;
+  #stopLiveSync: (() => void) | null = null;
+
+  config: Partial<HLS.HlsConfig> = {};
+  #callbacks = new Set<HLSInstanceCallback>();
+
+  get instance() {
+    return this.#instance;
+  }
+
+  constructor(video: HTMLVideoElement, ctx: MediaContext) {
+    this.#video = video;
+    this.#ctx = ctx;
+  }
+
+  setup(ctor: HLSConstructor) {
+    const { streamType } = this.#ctx.$state;
+
+    const isLive = peek(streamType).includes('live'),
+      isLiveLowLatency = peek(streamType).includes('ll-');
+
+    this.#instance = new ctor({
+      lowLatencyMode: isLiveLowLatency,
+      backBufferLength: isLiveLowLatency ? 4 : isLive ? 8 : undefined,
+      renderTextTracksNatively: false,
+      ...this.config,
+    });
+
+    const dispatcher = this.#dispatchHLSEvent.bind(this);
+    for (const event of Object.values(ctor.Events)) this.#instance.on(event, dispatcher);
+
+    this.#instance.on(ctor.Events.ERROR, this.#onError.bind(this));
+    for (const callback of this.#callbacks) callback(this.#instance);
+
+    this.#ctx.player.dispatch('hls-instance', {
+      detail: this.#instance,
+    });
+
+    this.#instance.attachMedia(this.#video);
+    this.#instance.on(ctor.Events.AUDIO_TRACK_SWITCHED, this.#onAudioSwitch.bind(this));
+    this.#instance.on(ctor.Events.LEVEL_SWITCHED, this.#onLevelSwitched.bind(this));
+    this.#instance.on(ctor.Events.LEVEL_LOADED, this.#onLevelLoaded.bind(this));
+    this.#instance.on(ctor.Events.LEVEL_UPDATED, this.#onLevelUpdated.bind(this));
+    this.#instance.on(ctor.Events.NON_NATIVE_TEXT_TRACKS_FOUND, this.#onTracksFound.bind(this));
+    this.#instance.on(ctor.Events.CUES_PARSED, this.#onCuesParsed.bind(this));
+
+    this.#ctx.qualities[QualitySymbol.enableAuto] = this.#enableAutoQuality.bind(this);
+
+    listenEvent(this.#ctx.qualities, 'change', this.#onUserQualityChange.bind(this));
+    listenEvent(this.#ctx.audioTracks, 'change', this.#onUserAudioChange.bind(this));
+
+    this.#stopLiveSync = effect(this.#liveSync.bind(this));
+  }
+
+  #createDOMEvent<T>(type: string, data: T): DOMEvent<T> {
+    return new DOMEvent<any>(toDOMEventType(type), { detail: data });
+  }
+
+  #liveSync() {
+    if (!this.#ctx.$state.live()) return;
+    const raf = new RAFLoop(this.#liveSyncPosition.bind(this));
+    raf.start();
+    return raf.stop.bind(raf);
+  }
+
+  #liveSyncPosition() {
+    this.#ctx.$state.liveSyncPosition.set(this.#instance?.liveSyncPosition ?? Infinity);
+  }
+
+  #dispatchHLSEvent(type: string, data: any) {
+    this.#ctx.player?.dispatch(this.#createDOMEvent(type, data));
+  }
+
+  #onTracksFound(eventType: string, data: HLS.NonNativeTextTracksData) {
+    const event = this.#createDOMEvent(eventType, data);
+
+    let currentTrack = -1;
+
+    for (let i = 0; i < data.tracks.length; i++) {
+      const nonNativeTrack = data.tracks[i],
+        init = nonNativeTrack.subtitleTrack ?? nonNativeTrack.closedCaptions,
+        track = new TextTrack({
+          id: `hls-${nonNativeTrack!.kind}-${i}`,
+          src: init?.url,
+          label: nonNativeTrack!.label,
+          language: init?.lang,
+          kind: nonNativeTrack!.kind as TextTrackKind,
+          default: nonNativeTrack.default,
+        });
+
+      track[TextTrackSymbol.readyState] = 2;
+      track[TextTrackSymbol.onModeChange] = () => {
+        if (track.mode === 'showing') {
+          this.#instance!.subtitleTrack = i;
+          currentTrack = i;
+        } else if (currentTrack === i) {
+          this.#instance!.subtitleTrack = -1;
+          currentTrack = -1;
+        }
+      };
+
+      this.#ctx.textTracks.add(track, event);
+    }
+  }
+
+  #onCuesParsed(eventType: string, data: HLS.CuesParsedData) {
+    const index = this.#instance?.subtitleTrack,
+      track = this.#ctx.textTracks.getById(`hls-${data.type}-${index}`);
+
+    if (!track) return;
+
+    const event = this.#createDOMEvent(eventType, data);
+
+    for (const cue of data.cues) {
+      cue.positionAlign = 'auto';
+      track.addCue(cue, event);
+    }
+  }
+
+  #onAudioSwitch(eventType: string, data: HLS.AudioTrackSwitchedData) {
+    const track = this.#ctx.audioTracks[data.id];
+    if (track) {
+      const trigger = this.#createDOMEvent(eventType, data);
+      this.#ctx.audioTracks[ListSymbol.select](track, true, trigger);
+    }
+  }
+
+  #onLevelSwitched(eventType: string, data: HLS.LevelSwitchedData) {
+    const quality = this.#ctx.qualities[data.level];
+    if (quality) {
+      const trigger = this.#createDOMEvent(eventType, data);
+      this.#ctx.qualities[ListSymbol.select](quality, true, trigger);
+    }
+  }
+
+  #onLevelUpdated(eventType: string, data: HLS.LevelUpdatedData): void {
+    if (data.details.totalduration > 0) {
+      this.#ctx.$state.inferredLiveDVRWindow.set(data.details.totalduration);
+    }
+  }
+
+  #onLevelLoaded(eventType: string, data: HLS.LevelLoadedData): void {
+    if (this.#ctx.$state.canPlay()) return;
+
+    const { type, live, totalduration: duration, targetduration } = data.details,
+      trigger = this.#createDOMEvent(eventType, data);
+
+    this.#ctx.notify(
+      'stream-type-change',
+      live
+        ? type === 'EVENT' && Number.isFinite(duration) && targetduration >= 10
+          ? 'live:dvr'
+          : 'live'
+        : 'on-demand',
+      trigger,
+    );
+
+    this.#ctx.notify('duration-change', duration, trigger);
+
+    const media = this.#instance!.media!;
+
+    if (this.#instance!.currentLevel === -1) {
+      this.#ctx.qualities[QualitySymbol.setAuto](true, trigger);
+    }
+
+    for (const remoteTrack of this.#instance!.audioTracks) {
+      const localTrack = {
+        id: remoteTrack.id.toString(),
+        label: remoteTrack.name,
+        language: remoteTrack.lang || '',
+        kind: 'main',
+      };
+
+      this.#ctx.audioTracks[ListSymbol.add](localTrack, trigger);
+    }
+
+    for (const level of this.#instance!.levels) {
+      const videoQuality = {
+        id: level.id?.toString() ?? level.height + 'p',
+        width: level.width,
+        height: level.height,
+        codec: level.codecSet,
+        bitrate: level.bitrate,
+      };
+
+      this.#ctx.qualities[ListSymbol.add](videoQuality, trigger);
+    }
+
+    media.dispatchEvent(new DOMEvent<void>('canplay', { trigger }));
+  }
+
+  #onError(eventType: string, data: HLS.ErrorData) {
+    if (__DEV__) {
+      this.#ctx.logger
+        ?.errorGroup(`[vidstack] HLS error \`${eventType}\``)
+        .labelledLog('Media Element', this.#instance?.media)
+        .labelledLog('HLS Instance', this.#instance)
+        .labelledLog('Event Type', eventType)
+        .labelledLog('Data', data)
+        .labelledLog('Src', peek(this.#ctx.$state.source))
+        .labelledLog('Media Store', { ...this.#ctx.$state })
+        .dispatch();
+    }
+
+    if (data.fatal) {
+      switch (data.type) {
+        case 'mediaError':
+          this.#instance?.recoverMediaError();
+          break;
+        default:
+          this.#onFatalError(data.error);
+          break;
+      }
+    }
+  }
+
+  #onFatalError(error: Error) {
+    this.#ctx.notify('error', {
+      message: error.message,
+      code: 1,
+      error: error,
+    });
+  }
+
+  #enableAutoQuality() {
+    if (this.#instance) this.#instance.currentLevel = -1;
+  }
+
+  #onUserQualityChange() {
+    const { qualities } = this.#ctx;
+
+    if (!this.#instance || qualities.auto) return;
+
+    this.#instance[qualities.switch + 'Level'] = qualities.selectedIndex;
+
+    /**
+     * Chrome has some strange issue with detecting keyframes inserted before the current
+     * playhead position. This can cause playback to freeze until a new keyframe. It seems
+     * setting the current time forces chrome to seek back to the last keyframe and adjust
+     * playback. Weird fix, but it works!
+     */
+    if (IS_CHROME) {
+      this.#video.currentTime = this.#video.currentTime;
+    }
+  }
+
+  #onUserAudioChange() {
+    const { audioTracks } = this.#ctx;
+    if (this.#instance && this.#instance.audioTrack !== audioTracks.selectedIndex) {
+      this.#instance.audioTrack = audioTracks.selectedIndex;
+    }
+  }
+
+  onInstance(callback: HLSInstanceCallback) {
+    this.#callbacks.add(callback);
+    return () => this.#callbacks.delete(callback);
+  }
+
+  loadSource(src: Src) {
+    if (!isString(src.src)) return;
+    this.#instance?.loadSource(src.src);
+  }
+
+  destroy() {
+    this.#instance?.destroy();
+    this.#instance = null;
+    this.#stopLiveSync?.();
+    this.#stopLiveSync = null;
+    if (__DEV__) this.#ctx?.logger?.info('🏗️ Destroyed HLS instance');
+  }
+}

package/src/providers/hls/lib-loader.ts

@@ -0,0 +1,178 @@
+import { DOMEvent, isFunction, isString, isUndefined } from 'maverick.js/std';
+
+import type { MediaContext } from '../../core/api/media-context';
+import { coerceToError } from '../../utils/error';
+import { loadScript } from '../../utils/network';
+import type { HLSConstructor, HLSConstructorLoader, HLSLibrary } from './types';
+
+interface LoadHLSConstructorCallbacks {
+  onLoadStart?: () => void;
+  onLoaded?: (ctor: HLSConstructor) => void;
+  onLoadError?: (err: Error) => void;
+}
+
+export class HLSLibLoader {
+  #lib: HLSLibrary;
+  #ctx: MediaContext;
+  #callback: (ctor: HLSConstructor) => void;
+
+  constructor(lib: HLSLibrary, ctx: MediaContext, callback: (ctor: HLSConstructor) => void) {
+    this.#lib = lib;
+    this.#ctx = ctx;
+    this.#callback = callback;
+    this.#startLoading();
+  }
+
+  async #startLoading() {
+    if (__DEV__) this.#ctx.logger?.info('🏗️ Loading HLS Library');
+
+    const callbacks: LoadHLSConstructorCallbacks = {
+      onLoadStart: this.#onLoadStart.bind(this),
+      onLoaded: this.#onLoaded.bind(this),
+      onLoadError: this.#onLoadError.bind(this),
+    };
+
+    // If not a string it'll return undefined.
+    let ctor = await loadHLSScript(this.#lib, callbacks);
+
+    // If it's not a remote source, it must of been passed in directly as a static/dynamic import.
+    if (isUndefined(ctor) && !isString(this.#lib)) ctor = await importHLS(this.#lib, callbacks);
+
+    // We failed loading the constructor.
+    if (!ctor) return null;
+
+    // Not supported.
+    if (!ctor.isSupported()) {
+      const message = '[vidstack] `hls.js` is not supported in this environment';
+      if (__DEV__) this.#ctx.logger?.error(message);
+      this.#ctx.player.dispatch(new DOMEvent<void>('hls-unsupported'));
+      this.#ctx.notify('error', { message, code: 4 });
+      return null;
+    }
+
+    return ctor;
+  }
+
+  #onLoadStart() {
+    if (__DEV__) {
+      this.#ctx.logger
+        ?.infoGroup('Starting to load `hls.js`')
+        .labelledLog('URL', this.#lib)
+        .dispatch();
+    }
+
+    this.#ctx.player.dispatch(new DOMEvent<void>('hls-lib-load-start'));
+  }
+
+  #onLoaded(ctor: HLSConstructor) {
+    if (__DEV__) {
+      this.#ctx.logger
+        ?.infoGroup('Loaded `hls.js`')
+        .labelledLog('Library', this.#lib)
+        .labelledLog('Constructor', ctor)
+        .dispatch();
+    }
+
+    this.#ctx.player.dispatch(
+      new DOMEvent<HLSConstructor>('hls-lib-loaded', {
+        detail: ctor,
+      }),
+    );
+
+    this.#callback(ctor);
+  }
+
+  #onLoadError(e) {
+    const error = coerceToError(e);
+
+    if (__DEV__) {
+      this.#ctx.logger
+        ?.errorGroup('[vidstack] Failed to load `hls.js`')
+        .labelledLog('Library', this.#lib)
+        .labelledLog('Error', e)
+        .dispatch();
+    }
+
+    this.#ctx.player.dispatch(
+      new DOMEvent<any>('hls-lib-load-error', {
+        detail: error,
+      }),
+    );
+
+    this.#ctx.notify('error', {
+      message: error.message,
+      code: 4,
+      error,
+    });
+  }
+}
+
+async function importHLS(
+  loader: HLSConstructor | HLSConstructorLoader | undefined,
+  callbacks: LoadHLSConstructorCallbacks = {},
+): Promise<HLSConstructor | undefined> {
+  if (isUndefined(loader)) return undefined;
+
+  callbacks.onLoadStart?.();
+
+  // Must be static.
+  if (loader.prototype && loader.prototype !== Function) {
+    callbacks.onLoaded?.(loader as HLSConstructor);
+    return loader as HLSConstructor;
+  }
+
+  try {
+    const ctor = (await (loader as HLSConstructorLoader)())?.default;
+
+    if (ctor && !!ctor.isSupported) {
+      callbacks.onLoaded?.(ctor);
+    } else {
+      throw Error(
+        __DEV__
+          ? '[vidstack] failed importing `hls.js`. Dynamic import returned invalid constructor.'
+          : '',
+      );
+    }
+
+    return ctor;
+  } catch (err) {
+    callbacks.onLoadError?.(err as Error);
+  }
+
+  return undefined;
+}
+
+/**
+ * Loads `hls.js` from the remote source given via `library` into the window namespace. This
+ * is because `hls.js` in {currentYear} still doesn't provide a ESM export. This method will
+ * return `undefined` if it fails to load the script. Listen to `hls-lib-load-error` to be
+ * notified of any failures.
+ */
+async function loadHLSScript(
+  src: unknown,
+  callbacks: LoadHLSConstructorCallbacks = {},
+): Promise<HLSConstructor | undefined> {
+  if (!isString(src)) return undefined;
+
+  callbacks.onLoadStart?.();
+
+  try {
+    await loadScript(src);
+
+    if (!isFunction((window as any).Hls)) {
+      throw Error(
+        __DEV__
+          ? '[vidstack] failed loading `hls.js`. Could not find a valid `Hls` constructor on window'
+          : '',
+      );
+    }
+
+    const ctor = (window as any).Hls as HLSConstructor;
+    callbacks.onLoaded?.(ctor);
+    return ctor;
+  } catch (err) {
+    callbacks.onLoadError?.(err as Error);
+  }
+
+  return undefined;
+}

package/src/providers/hls/loader.ts

@@ -0,0 +1,33 @@
+import type { Src } from '../../core/api/src-types';
+import { isHLSSrc } from '../../utils/mime';
+import { isHLSSupported } from '../../utils/support';
+import type { MediaProviderLoader } from '../types';
+import { VideoProviderLoader } from '../video/loader';
+import type { HLSProvider } from './provider';
+
+export class HLSProviderLoader
+  extends VideoProviderLoader
+  implements MediaProviderLoader<HLSProvider>
+{
+  static supported = isHLSSupported();
+
+  override readonly name = 'hls';
+
+  override canPlay(src: Src) {
+    return HLSProviderLoader.supported && isHLSSrc(src);
+  }
+
+  override async load(context) {
+    if (__SERVER__) {
+      throw Error('[vidstack] can not load hls provider server-side');
+    }
+
+    if (__DEV__ && !this.target) {
+      throw Error(
+        '[vidstack] `<video>` element was not found - did you forget to include `<media-provider>`?',
+      );
+    }
+
+    return new (await import('./provider')).HLSProvider(this.target, context);
+  }
+}

package/src/providers/hls/provider.ts

@@ -0,0 +1,137 @@
+import { peek, type Dispose } from 'maverick.js';
+import { isString } from 'maverick.js/std';
+
+import type { Src } from '../../core/api/src-types';
+import { preconnect } from '../../utils/network';
+import { isHLSSupported } from '../../utils/support';
+import type { MediaProviderAdapter } from '../types';
+import { VideoProvider } from '../video/provider';
+import { HLSController } from './hls';
+import { HLSLibLoader } from './lib-loader';
+import type { HLSConstructor, HLSInstanceCallback, HLSLibrary } from './types';
+
+const JS_DELIVR_CDN = 'https://cdn.jsdelivr.net';
+
+/**
+ * The HLS provider introduces support for HLS streaming via the popular `hls.js`
+ * library. HLS streaming is either [supported natively](https://caniuse.com/?search=hls) (generally
+ * on iOS), or in environments that [support the Media Stream API](https://caniuse.com/?search=mediastream).
+ *
+ * @docs {@link https://www.vidstack.io/docs/player/providers/hls}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video}
+ * @see {@link https://github.com/video-dev/hls.js/blob/master/docs/API.md}
+ * @example
+ * ```html
+ * <media-player
+ *   src="https://files.vidstack.io/hls/index.m3u8"
+ *   poster="https://files.vidstack.io/poster.png"
+ * >
+ *   <media-provider></media-provider>
+ * </media-player>
+ * ```
+ */
+export class HLSProvider extends VideoProvider implements MediaProviderAdapter {
+  protected override $$PROVIDER_TYPE = 'HLS';
+
+  #ctor: HLSConstructor | null = null;
+  readonly #controller = new HLSController(this.video, this.ctx);
+
+  /**
+   * The `hls.js` constructor.
+   */
+  get ctor() {
+    return this.#ctor;
+  }
+
+  /**
+   * The current `hls.js` instance.
+   */
+  get instance() {
+    return this.#controller.instance;
+  }
+
+  /**
+   * Whether `hls.js` is supported in this environment.
+   */
+  static supported = isHLSSupported();
+
+  override get type() {
+    return 'hls';
+  }
+
+  get canLiveSync() {
+    return true;
+  }
+
+  #library: HLSLibrary = `${JS_DELIVR_CDN}/npm/hls.js@^1.5.0/dist/hls${
+    __DEV__ ? '.js' : '.min.js'
+  }`;
+
+  /**
+   * The `hls.js` configuration object.
+   *
+   * @see {@link https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning}
+   */
+  get config() {
+    return this.#controller.config;
+  }
+
+  set config(config) {
+    this.#controller.config = config;
+  }
+
+  /**
+   * The `hls.js` constructor (supports dynamic imports) or a URL of where it can be found.
+   *
+   * @defaultValue `https://cdn.jsdelivr.net/npm/hls.js@^1.0.0/dist/hls.min.js`
+   */
+  get library() {
+    return this.#library;
+  }
+
+  set library(library) {
+    this.#library = library;
+  }
+
+  preconnect(): void {
+    if (!isString(this.#library)) return;
+    preconnect(this.#library);
+  }
+
+  override setup() {
+    super.setup();
+    new HLSLibLoader(this.#library, this.ctx, (ctor) => {
+      this.#ctor = ctor;
+      this.#controller.setup(ctor);
+      this.ctx.notify('provider-setup', this);
+      const src = peek(this.ctx.$state.source);
+      if (src) this.loadSource(src);
+    });
+  }
+
+  override async loadSource(src: Src, preload?: HTMLMediaElement['preload']) {
+    if (!isString(src.src)) {
+      this.removeSource();
+      return;
+    }
+
+    this.media.preload = preload || '';
+    this.appendSource(src as Src<string>, 'application/x-mpegurl');
+    this.#controller.loadSource(src);
+    this.currentSrc = src as Src<string>;
+  }
+
+  /**
+   * The given callback is invoked when a new `hls.js` instance is created and right before it's
+   * attached to media.
+   */
+  onInstance(callback: HLSInstanceCallback): Dispose {
+    const instance = this.#controller.instance;
+    if (instance) callback(instance);
+    return this.#controller.onInstance(callback);
+  }
+
+  destroy() {
+    this.#controller.destroy();
+  }
+}

package/src/providers/hls/types.ts

@@ -0,0 +1,10 @@
+import type * as HLS from 'hls.js';
+
+import type { HLSProviderEvents } from './events';
+
+export { type HLSProviderEvents };
+
+export type HLSConstructor = typeof HLS.default;
+export type HLSConstructorLoader = () => Promise<{ default: HLSConstructor } | undefined>;
+export type HLSLibrary = HLSConstructor | HLSConstructorLoader | string | undefined;
+export type HLSInstanceCallback = (hls: HLS.default) => void;

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

@@ -0,0 +1,60 @@
+let audioContext: AudioContext | null = null,
+  gainNodes: GainNode[] = [],
+  elAudioSources: MediaElementAudioSourceNode[] = [];
+
+export function getOrCreateAudioCtx(): AudioContext {
+  return (audioContext ??= new AudioContext());
+}
+
+export function createGainNode() {
+  const audioCtx = getOrCreateAudioCtx(),
+    gainNode = audioCtx.createGain();
+
+  gainNode.connect(audioCtx.destination);
+  gainNodes.push(gainNode);
+
+  return gainNode;
+}
+
+export function createElementSource(el: HTMLMediaElement, gainNode?: GainNode) {
+  const audioCtx = getOrCreateAudioCtx(),
+    src = audioCtx.createMediaElementSource(el);
+
+  if (gainNode) {
+    src.connect(gainNode);
+  }
+
+  elAudioSources.push(src);
+
+  return src;
+}
+
+export function destroyGainNode(node: GainNode) {
+  const idx = gainNodes.indexOf(node);
+
+  if (idx !== -1) {
+    gainNodes.splice(idx, 1);
+    node.disconnect();
+
+    freeAudioCtxWhenAllResourcesFreed();
+  }
+}
+
+export function destroyElementSource(src: MediaElementAudioSourceNode) {
+  const idx = elAudioSources.indexOf(src);
+
+  if (idx !== -1) {
+    elAudioSources.splice(idx, 1);
+    src.disconnect();
+
+    freeAudioCtxWhenAllResourcesFreed();
+  }
+}
+
+export function freeAudioCtxWhenAllResourcesFreed() {
+  if (audioContext && gainNodes.length === 0 && elAudioSources.length === 0) {
+    audioContext.close().then(() => {
+      audioContext = null;
+    });
+  }
+}