@hanifhan1f/vidstack 1.12.13

package/src/core/tracks/text/text-track.ts

@@ -0,0 +1,413 @@
+import { DOMEvent, EventsTarget, isArray, isNumber, isString } from 'maverick.js/std';
+import type {
+  CaptionsFileFormat,
+  CaptionsParserFactory,
+  VTTCue,
+  VTTHeaderMetadata,
+  VTTRegion,
+} from 'media-captions';
+
+import { getRequestCredentials } from '../../../utils/network';
+import type { TextTrackEvents } from './events';
+import { TextTrackSymbol } from './symbols';
+import { isCueActive } from './utils';
+
+/**
+ * - 0: Not Loading
+ * - 1: Loading
+ * - 2: Ready
+ * - 3: Error
+ */
+export type TextTrackReadyState = 0 | 1 | 2 | 3;
+
+export interface VTTCueInit
+  extends Omit<Partial<VTTCue>, 'startTime' | 'endTime' | 'text'>,
+    Pick<VTTCue, 'startTime' | 'endTime' | 'text'> {}
+
+export interface VTTRegionInit extends Omit<Partial<VTTRegion>, 'id'>, Pick<VTTRegion, 'id'> {}
+
+export interface VTTContent {
+  cues?: VTTCueInit[];
+  regions?: VTTRegionInit[];
+}
+
+export class TextTrack extends EventsTarget<TextTrackEvents> {
+  static createId(track: TextTrack | TextTrackInit) {
+    return `vds-${track.type}-${track.kind}-${track.src ?? track.label ?? '?'}`;
+  }
+
+  readonly src?: string;
+  readonly content?: TextTrackInit['content'];
+  readonly type?: 'json' | CaptionsFileFormat | CaptionsParserFactory;
+  readonly encoding?: string;
+
+  readonly id = '';
+  readonly label = '';
+  readonly language = '';
+  readonly kind!: TextTrackKind;
+  readonly default = false;
+
+  #canLoad = false;
+  #currentTime = 0;
+  #mode: TextTrackMode = 'disabled';
+  #metadata: VTTHeaderMetadata = {};
+  #regions: VTTRegion[] = [];
+  #cues: VTTCue[] = [];
+  #activeCues: VTTCue[] = [];
+  #cueIds = new Set<string>();
+
+  /** @internal */
+  [TextTrackSymbol.readyState]: TextTrackReadyState = 0;
+
+  /** @internal */
+  [TextTrackSymbol.crossOrigin]?: () => string | null;
+
+  /** @internal */
+  [TextTrackSymbol.onModeChange]: (() => void) | null = null;
+
+  /** @internal */
+  [TextTrackSymbol.native]: {
+    default?: boolean;
+    managed?: boolean;
+    track: {
+      mode: TextTrackMode;
+      addCue(cue: any): void;
+      removeCue(cue: any): void;
+    };
+    remove?(): void;
+  } | null = null;
+
+  get metadata(): Readonly<VTTHeaderMetadata> {
+    return this.#metadata;
+  }
+
+  get regions(): ReadonlyArray<VTTRegion> {
+    return this.#regions;
+  }
+
+  get cues(): ReadonlyArray<VTTCue> {
+    return this.#cues;
+  }
+
+  get activeCues(): ReadonlyArray<VTTCue> {
+    return this.#activeCues;
+  }
+
+  /**
+   * - 0: Not Loading
+   * - 1: Loading
+   * - 2: Ready
+   * - 3: Error
+   */
+  get readyState(): TextTrackReadyState {
+    return this[TextTrackSymbol.readyState];
+  }
+
+  get mode(): TextTrackMode {
+    return this.#mode;
+  }
+
+  set mode(mode) {
+    this.setMode(mode);
+  }
+
+  constructor(init: TextTrackInit) {
+    super();
+
+    for (const prop of Object.keys(init)) this[prop] = init[prop];
+    if (!this.type) this.type = 'vtt';
+
+    if (!__SERVER__ && init.content) {
+      this.#parseContent(init);
+    } else if (!init.src) {
+      this[TextTrackSymbol.readyState] = 2;
+    }
+
+    if (__DEV__ && isTrackCaptionKind(this) && !this.label) {
+      console.warn(`[vidstack] captions text track created without label: \`${this.src}\``);
+    }
+  }
+
+  addCue(cue: VTTCue, trigger?: Event): void {
+    // deduplicate cues with the same id
+    if (cue.id) {
+      if (this.#cueIds.has(cue.id)) return;
+      this.#cueIds.add(cue.id);
+    }
+
+    let i = 0,
+      length = this.#cues.length;
+
+    for (i = 0; i < length; i++) if (cue.endTime <= this.#cues[i].startTime) break;
+
+    if (i === length) this.#cues.push(cue);
+    else this.#cues.splice(i, 0, cue);
+
+    // Avoid infinite loop by adding native text track cues back.
+    if (!(cue instanceof TextTrackCue)) {
+      this[TextTrackSymbol.native]?.track.addCue(cue);
+    }
+
+    this.dispatchEvent(new DOMEvent<VTTCue>('add-cue', { detail: cue, trigger }));
+
+    if (isCueActive(cue, this.#currentTime)) {
+      this[TextTrackSymbol.updateActiveCues](this.#currentTime, trigger);
+    }
+  }
+
+  removeCue(cue: VTTCue, trigger?: Event): void {
+    const index = this.#cues.indexOf(cue);
+    if (index >= 0) {
+      const isActive = this.#activeCues.includes(cue);
+      if (cue.id) this.#cueIds.delete(cue.id);
+      this.#cues.splice(index, 1);
+      this[TextTrackSymbol.native]?.track.removeCue(cue);
+      this.dispatchEvent(new DOMEvent<VTTCue>('remove-cue', { detail: cue, trigger }));
+      if (isActive) {
+        this[TextTrackSymbol.updateActiveCues](this.#currentTime, trigger);
+      }
+    }
+  }
+
+  setMode(mode: TextTrackMode, trigger?: Event) {
+    if (this.#mode === mode) return;
+
+    this.#mode = mode;
+
+    if (mode === 'disabled') {
+      this.#activeCues = [];
+      this.#activeCuesChanged();
+    } else if (this.readyState === 2) {
+      this[TextTrackSymbol.updateActiveCues](this.#currentTime, trigger);
+    } else {
+      this.#load();
+    }
+
+    this.dispatchEvent(new DOMEvent<TextTrack>('mode-change', { detail: this, trigger }));
+    this[TextTrackSymbol.onModeChange]?.();
+  }
+
+  /** @internal */
+  [TextTrackSymbol.updateActiveCues](currentTime: number, trigger?: Event) {
+    this.#currentTime = currentTime;
+    if (this.mode === 'disabled' || !this.#cues.length) return;
+
+    const activeCues: VTTCue[] = [];
+
+    for (let i = 0, length = this.#cues.length; i < length; i++) {
+      const cue = this.#cues[i]!;
+      if (isCueActive(cue, currentTime)) activeCues.push(cue);
+    }
+
+    let changed = activeCues.length !== this.#activeCues.length;
+    if (!changed) {
+      for (let i = 0; i < activeCues.length; i++) {
+        if (!this.#activeCues.includes(activeCues[i])) {
+          changed = true;
+          break;
+        }
+      }
+    }
+
+    this.#activeCues = activeCues;
+    if (changed) this.#activeCuesChanged(trigger);
+  }
+
+  /** @internal */
+  [TextTrackSymbol.canLoad]() {
+    this.#canLoad = true;
+    if (this.#mode !== 'disabled') this.#load();
+  }
+
+  #parseContent(init: TextTrackInit) {
+    import('media-captions').then(({ parseText, VTTCue, VTTRegion }) => {
+      if (!isString(init.content) || init.type === 'json') {
+        this.#parseJSON(init.content!, VTTCue, VTTRegion);
+        if (this.readyState !== 3) this.#ready();
+      } else {
+        const content = init
+          .content!.split('\n')
+          .map((line) => line.trim())
+          .join('\n')
+          .trim();
+        parseText(content, { type: init.type as 'vtt' }).then(({ cues, regions }) => {
+          this.#cues = cues;
+          this.#regions = regions;
+          this.#ready();
+        });
+      }
+    });
+  }
+
+  async #load() {
+    if (!this.#canLoad || this[TextTrackSymbol.readyState] > 0) return;
+
+    this[TextTrackSymbol.readyState] = 1;
+    this.dispatchEvent(new DOMEvent<void>('load-start'));
+
+    if (!this.src) {
+      this.#ready();
+      return;
+    }
+
+    try {
+      const { parseResponse, VTTCue, VTTRegion } = await import('media-captions'),
+        crossOrigin = this[TextTrackSymbol.crossOrigin]?.();
+
+      const response = fetch(this.src, {
+        headers: this.type === 'json' ? { 'Content-Type': 'application/json' } : undefined,
+        credentials: getRequestCredentials(crossOrigin),
+      });
+
+      if (this.type === 'json') {
+        this.#parseJSON(await (await response).text(), VTTCue, VTTRegion);
+      } else {
+        const { errors, metadata, regions, cues } = await parseResponse(response, {
+          type: this.type,
+          encoding: this.encoding,
+        });
+
+        if (errors[0]?.code === 0) {
+          throw errors[0];
+        } else {
+          this.#metadata = metadata;
+          this.#regions = regions;
+          this.#cues = cues;
+        }
+      }
+
+      this.#ready();
+    } catch (error) {
+      this.#error(error);
+    }
+  }
+
+  #ready() {
+    this[TextTrackSymbol.readyState] = 2;
+
+    if (!this.src || this.type !== 'vtt') {
+      const native = this[TextTrackSymbol.native];
+      if (native && !native.managed) {
+        for (const cue of this.#cues) native.track.addCue(cue);
+      }
+    }
+
+    const loadEvent = new DOMEvent<void>('load');
+    this[TextTrackSymbol.updateActiveCues](this.#currentTime, loadEvent);
+    this.dispatchEvent(loadEvent);
+  }
+
+  #error(error: unknown) {
+    this[TextTrackSymbol.readyState] = 3;
+    this.dispatchEvent(new DOMEvent('error', { detail: error }));
+  }
+
+  #parseJSON(json: string | VTTContent, VTTCue, VTTRegion) {
+    try {
+      const { regions, cues } = parseJSONCaptionsFile(json, VTTCue, VTTRegion);
+      this.#regions = regions;
+      this.#cues = cues;
+    } catch (error) {
+      if (__DEV__) {
+        console.error(`[vidstack] failed to parse JSON captions at: \`${this.src}\`\n\n`, error);
+      }
+
+      this.#error(error);
+    }
+  }
+
+  #activeCuesChanged(trigger?: Event) {
+    this.dispatchEvent(new DOMEvent<void>('cue-change', { trigger }));
+  }
+}
+
+export interface TextTrackInit {
+  /**
+   * A unique identifier.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/id}
+   */
+  id?: string;
+  /**
+   * URL of the text track resource. This attribute must be specified and its URL value must have
+   * the same origin as the document — unless the <audio> or <video> parent element of the track
+   * element has a `crossorigin` attribute.
+   */
+  readonly src?: string;
+  /**
+   * Used to directly pass in text track file contents.
+   */
+  readonly content?: string | VTTContent;
+  /**
+   * The captions file format to be parsed or a custom parser factory (functions that returns a
+   * captions parser). Supported types include: 'vtt', 'srt', 'ssa', 'ass', and 'json'.
+   *
+   * @defaultValue 'vtt'
+   */
+  readonly type?: 'json' | CaptionsFileFormat | CaptionsParserFactory;
+  /**
+   * The text encoding type to be used when decoding data bytes to text.
+   *
+   * @defaultValue 'utf-8'
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings}
+   *
+   */
+  readonly encoding?: string;
+  /**
+   * Indicates that the track should be enabled unless the user's preferences indicate that
+   * another track is more appropriate. This may only be used on one track element per media
+   * element.
+   *
+   * @defaultValue false
+   */
+  default?: boolean;
+  /**
+   * The kind of text track this object represents. This decides how the track will be handled
+   * by the player.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/kind}
+   */
+  readonly kind: TextTrackKind;
+  /**
+   * A human-readable label for the text track. This will be displayed to the user.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/label}
+   */
+  readonly label?: string;
+  /**
+   * A string containing a language identifier. For example, `"en-US"` for United States English
+   * or `"pt-BR"` for Brazilian Portuguese.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/language}
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc5646}
+   */
+  readonly language?: string;
+}
+
+const captionRE = /captions|subtitles/;
+export function isTrackCaptionKind(track: TextTrack): boolean {
+  return captionRE.test(track.kind);
+}
+
+export function parseJSONCaptionsFile(
+  json: string | VTTContent,
+  Cue: typeof VTTCue,
+  Region?: typeof VTTRegion,
+) {
+  const content = isString(json) ? JSON.parse(json) : json;
+
+  let regions: VTTRegion[] = [],
+    cues: VTTCue[] = [];
+
+  if (content.regions && Region) {
+    regions = content.regions.map((region) => Object.assign(new Region(), region));
+  }
+
+  if (content.cues || isArray(content)) {
+    cues = (isArray(content) ? content : content.cues)
+      .filter((content) => isNumber(content.startTime) && isNumber(content.endTime))
+      .map((cue) => Object.assign(new Cue(0, 0, ''), cue));
+  }
+
+  return { regions, cues };
+}

package/src/core/tracks/text/text-tracks.ts

@@ -0,0 +1,210 @@
+import debounce from 'just-debounce-it';
+import { DOMEvent, isArray } from 'maverick.js/std';
+
+import { List, type ListReadonlyChangeEvent } from '../../../foundation/list/list';
+import { ListSymbol } from '../../../foundation/list/symbols';
+import type { MediaStorage } from '../../state/media-storage';
+import type { TextTrackModeChangeEvent } from './events';
+import { TextTrackSymbol } from './symbols';
+import { isTrackCaptionKind, TextTrack, type TextTrackInit } from './text-track';
+
+/**
+ * @see {@link https://vidstack.io/docs/player/api/text-tracks}
+ */
+export class TextTrackList extends List<TextTrack, TextTrackListEvents> {
+  #canLoad = false;
+  #defaults: Record<string, TextTrack | undefined> = {};
+  #storage: MediaStorage | null = null;
+  #preferredLang: string | null = null;
+
+  /** @internal */
+  [TextTrackSymbol.crossOrigin]?: () => string | null;
+
+  constructor() {
+    super();
+  }
+
+  get selected() {
+    const track = this.items.find((t) => t.mode === 'showing' && isTrackCaptionKind(t));
+    return track ?? null;
+  }
+
+  get selectedIndex() {
+    const selected = this.selected;
+    return selected ? this.indexOf(selected) : -1;
+  }
+
+  get preferredLang() {
+    return this.#preferredLang;
+  }
+
+  set preferredLang(lang: string | null) {
+    this.#preferredLang = lang;
+    this.#saveLang(lang);
+  }
+
+  add(init: TextTrackInit | TextTrack, trigger?: Event) {
+    const isTrack = init instanceof TextTrack,
+      track = isTrack ? init : new TextTrack(init),
+      kind = init.kind === 'captions' || init.kind === 'subtitles' ? 'captions' : init.kind;
+
+    if (this.#defaults[kind] && init.default) delete init.default;
+
+    track.addEventListener('mode-change', this.#onTrackModeChangeBind);
+
+    this[ListSymbol.add](track, trigger);
+    track[TextTrackSymbol.crossOrigin] = this[TextTrackSymbol.crossOrigin];
+
+    if (this.#canLoad) track[TextTrackSymbol.canLoad]();
+
+    if (init.default) this.#defaults[kind] = track;
+
+    this.#selectTracks();
+
+    return this;
+  }
+
+  remove(track: TextTrack, trigger?: Event) {
+    this.#pendingRemoval = track;
+    if (!this.items.includes(track)) return;
+    if (track === this.#defaults[track.kind]) delete this.#defaults[track.kind];
+    track.mode = 'disabled';
+    track[TextTrackSymbol.onModeChange] = null;
+    track.removeEventListener('mode-change', this.#onTrackModeChangeBind);
+    this[ListSymbol.remove](track, trigger);
+    this.#pendingRemoval = null;
+    return this;
+  }
+
+  clear(trigger?: Event) {
+    for (const track of [...this.items]) {
+      this.remove(track, trigger);
+    }
+
+    return this;
+  }
+
+  getByKind(kind: TextTrackKind | TextTrackKind[]): TextTrack[] {
+    const kinds = Array.isArray(kind) ? kind : [kind];
+    return this.items.filter((track) => kinds.includes(track.kind));
+  }
+
+  /** @internal */
+  [TextTrackSymbol.canLoad]() {
+    if (this.#canLoad) return;
+    for (const track of this.items) track[TextTrackSymbol.canLoad]();
+    this.#canLoad = true;
+    this.#selectTracks();
+  }
+
+  #selectTracks = debounce(async () => {
+    if (!this.#canLoad) return;
+
+    if (!this.#preferredLang && this.#storage) {
+      this.#preferredLang = await this.#storage.getLang();
+    }
+
+    const showCaptions = await this.#storage?.getCaptions(),
+      kinds: (TextTrackKind | TextTrackKind[])[] = [
+        ['captions', 'subtitles'],
+        'chapters',
+        'descriptions',
+        'metadata',
+      ];
+
+    for (const kind of kinds) {
+      const tracks = this.getByKind(kind);
+      if (tracks.find((t) => t.mode === 'showing')) continue;
+
+      const preferredTrack = this.#preferredLang
+        ? tracks.find((track) => track.language === this.#preferredLang)
+        : null;
+
+      const defaultTrack = isArray(kind)
+        ? this.#defaults[kind.find((kind) => this.#defaults[kind]) || '']
+        : this.#defaults[kind];
+
+      const track = preferredTrack ?? defaultTrack,
+        isCaptionsKind = track && isTrackCaptionKind(track);
+
+      if (track && (!isCaptionsKind || showCaptions !== false)) {
+        track.mode = 'showing';
+        if (isCaptionsKind) this.#saveCaptionsTrack(track);
+      }
+    }
+  }, 300);
+
+  #pendingRemoval: TextTrack | null = null;
+  #onTrackModeChangeBind = this.#onTrackModeChange.bind(this);
+  #onTrackModeChange(event: TextTrackModeChangeEvent) {
+    const track = event.detail;
+
+    // We need to check whether track is being removed to not mistakenly save "disabled" mode change.
+    if (this.#storage && isTrackCaptionKind(track) && track !== this.#pendingRemoval) {
+      this.#saveCaptionsTrack(track);
+    }
+
+    if (track.mode === 'showing') {
+      const kinds = isTrackCaptionKind(track) ? ['captions', 'subtitles'] : [track.kind];
+      for (const t of this.items) {
+        if (t.mode === 'showing' && t != track && kinds.includes(t.kind)) {
+          t.mode = 'disabled';
+        }
+      }
+    }
+
+    this.dispatchEvent(
+      new DOMEvent<TextTrack>('mode-change', {
+        detail: event.detail,
+        trigger: event,
+      }),
+    );
+  }
+
+  #saveCaptionsTrack(track: TextTrack) {
+    if (track.mode !== 'disabled') {
+      this.#saveLang(track.language);
+    }
+    this.#storage?.setCaptions?.(track.mode === 'showing');
+  }
+
+  #saveLang(lang: string | null) {
+    this.#storage?.setLang?.((this.#preferredLang = lang));
+  }
+
+  setStorage(storage: MediaStorage | null) {
+    this.#storage = storage;
+  }
+}
+
+export interface TextTrackListEvents {
+  add: TextTrackAddEvent;
+  remove: TextTrackRemoveEvent;
+  'mode-change': TextTrackListModeChangeEvent;
+  'readonly-change': ListReadonlyChangeEvent;
+}
+
+export interface TextTrackListEvent<T> extends DOMEvent<T> {
+  target: TextTrackList;
+}
+
+/**
+ * Fired when a text track has been added to the list.
+ *
+ * @detail newTrack
+ */
+export interface TextTrackAddEvent extends TextTrackListEvent<TextTrack> {}
+
+/**
+ * Fired when a text track has been removed from the list.
+ *
+ * @detail removedTrack
+ */
+export interface TextTrackRemoveEvent extends TextTrackListEvent<TextTrack> {}
+
+/**
+ * Fired when the mode of any text track in the list has changed.
+ *
+ * @detail track
+ */
+export interface TextTrackListModeChangeEvent extends TextTrackListEvent<TextTrack> {}

package/src/core/tracks/text/utils.ts

@@ -0,0 +1,85 @@
+import { getScope, onDispose, scoped, type Dispose } from 'maverick.js';
+import { isString, listenEvent } from 'maverick.js/std';
+import type { VTTCue } from 'media-captions';
+
+import type { TextTrack } from './text-track';
+import type { TextTrackList } from './text-tracks';
+
+export function findActiveCue(cues: readonly VTTCue[], time: number): VTTCue | null {
+  for (let i = 0, len = cues.length; i < len; i++) {
+    if (isCueActive(cues[i], time)) return cues[i];
+  }
+
+  return null;
+}
+
+export function isCueActive(cue: VTTCue, time: number) {
+  return time >= cue.startTime && time < cue.endTime;
+}
+
+export function watchActiveTextTrack(
+  tracks: TextTrackList,
+  kind: TextTrackKind | TextTrackKind[],
+  onChange: (track: TextTrack | null) => void,
+): Dispose {
+  let currentTrack: TextTrack | null = null,
+    scope = getScope();
+
+  function onModeChange() {
+    const kinds = isString(kind) ? [kind] : kind,
+      track = tracks
+        .toArray()
+        .find((track) => kinds.includes(track.kind) && track.mode === 'showing');
+
+    if (track === currentTrack) return;
+
+    if (!track) {
+      onChange(null);
+      currentTrack = null;
+      return;
+    }
+
+    if (track.readyState == 2) {
+      onChange(track);
+    } else {
+      onChange(null);
+      scoped(() => {
+        const off = listenEvent(
+          track,
+          'load',
+          () => {
+            onChange(track);
+            off();
+          },
+          { once: true },
+        );
+      }, scope);
+    }
+
+    currentTrack = track;
+  }
+
+  onModeChange();
+  return listenEvent(tracks, 'mode-change', onModeChange);
+}
+
+export function watchCueTextChange(
+  tracks: TextTrackList,
+  kind: TextTrackKind | TextTrackKind[],
+  callback: (title: string) => void,
+) {
+  watchActiveTextTrack(tracks, kind, (track) => {
+    if (!track) {
+      callback('');
+      return;
+    }
+
+    const onCueChange = () => {
+      const activeCue = track?.activeCues[0];
+      callback(activeCue?.text || '');
+    };
+
+    onCueChange();
+    listenEvent(track, 'cue-change', onCueChange);
+  });
+}

package/src/elements/bundles/cdn/player.core.ts

@@ -0,0 +1,6 @@
+import '../player';
+import '../player-ui';
+import '../../../global/player';
+
+export * from '../../../exports/core';
+export * from '../../../global/player';