feat(site): API reference pages for media elements (#1342)

packages/core/src/dom/media/dash/index.ts

@@ -41,6 +41,11 @@ export class DashMedia
     super.destroy();
   }
 
+  /**
+   * Underlying playback engine — the dash.js `MediaPlayerClass` instance. An
+   * advanced escape hatch for direct engine access; normal playback is driven
+   * through this element's own properties and methods.
+   */
   get engine() {
     return this.#engine;
   }

packages/core/src/dom/media/hls/index.ts

@@ -49,6 +49,10 @@ export const hlsMediaDefaultProps: HlsMediaProps = {
 
 class HlsMediaEvent extends Event {}
 
+/**
+ * @fires streamtypechange - Fired when the detected stream type changes. Read `streamType` for the new value.
+ * @fires targetlivewindowchange - Fired when the target live window changes. Read `targetLiveWindow` for the new value.
+ */
 export class HlsMedia extends HTMLVideoElementHost implements HlsMediaProps {
   #delegate: HlsJsMedia | NativeHlsMedia | null = null;
   #mediaElement: HTMLVideoElement | null = null;
@@ -84,10 +88,20 @@ export class HlsMedia extends HTMLVideoElementHost implements HlsMediaProps {
     this.removeEventListener('loadstart', this.#stopTargetLoadStartEvent);
   }
 
+  /**
+   * Underlying playback engine — the hls.js `Hls` instance when playing via
+   * MSE, otherwise `null`. An advanced escape hatch for direct engine access;
+   * normal playback is driven through this element's own properties and methods.
+   */
   get engine() {
     return this.#delegate?.engine ?? null;
   }
 
+  /**
+   * Playback configuration: a preferred playback path, an explicit content
+   * type, and options forwarded to hls.js. Reassigning reloads the engine when
+   * an engine-relevant option changes.
+   */
   get config(): HlsMediaConfig {
     return super.config;
   }
@@ -101,18 +115,22 @@ export class HlsMedia extends HTMLVideoElementHost implements HlsMediaProps {
     return this.#delegate?.error ?? null;
   }
 
+  /** Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. */
   get videoTracks() {
     return this.#delegate instanceof HlsJsMedia ? this.#delegate.videoTracks : undefined;
   }
 
+  /** Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. */
   get audioTracks() {
     return this.#delegate instanceof HlsJsMedia ? this.#delegate.audioTracks : undefined;
   }
 
+  /** Selectable quality levels, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. */
   get videoRenditions() {
     return this.#delegate instanceof HlsJsMedia ? this.#delegate.videoRenditions : undefined;
   }
 
+  /** Selectable audio variants, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. */
   get audioRenditions() {
     return this.#delegate instanceof HlsJsMedia ? this.#delegate.audioRenditions : undefined;
   }

packages/core/src/dom/media/native-hls/index.ts

@@ -25,6 +25,10 @@ class NativeHlsMediaBase extends HTMLVideoElementHost implements Omit<NativeHlsM
   #src = nativeHlsMediaDefaultProps.src;
   #preload = nativeHlsMediaDefaultProps.preload;
 
+  /**
+   * Underlying playback engine — always `null`. Native HLS has no JS engine;
+   * the browser handles playback directly.
+   */
   get engine() {
     return null;
   }
@@ -38,6 +42,7 @@ class NativeHlsMediaBase extends HTMLVideoElementHost implements Omit<NativeHlsM
     if (this.target) this.target.src = src;
   }
 
+  /** Preload type (`'none'` / `'metadata'` / `'auto'`). */
   get preload() {
     return this.#preload;
   }

packages/core/src/dom/media/native-hls/live.ts

@@ -2,6 +2,9 @@ import type { Constructor } from '@videojs/utils/types';
 import type { NativeMediaHost } from './errors';
 import { getStreamInfoFromSrc, looksLikeM3u8 } from './m3u8-utils';
 
+/**
+ * @fires targetlivewindowchange - Fired when the target live window changes. Read `targetLiveWindow` for the new value.
+ */
 export function NativeHlsMediaLiveMixin<Base extends Constructor<NativeMediaHost>>(BaseClass: Base) {
   // Native HLS does not expose manifest-level `HOLD-BACK` / `PART-HOLD-BACK`
   // through a JS API, so we fetch the m3u8 ourselves and parse the relevant
@@ -15,11 +18,19 @@ export function NativeHlsMediaLiveMixin<Base extends Constructor<NativeMediaHost
     #disconnect: AbortController | null = null;
     #currentSrc = '';
 
+    /**
+     * Seekable range size for live content. `0` for standard live, `Infinity`
+     * for DVR, `NaN` for on-demand or unknown.
+     */
     get targetLiveWindow() {
       return this.#targetLiveWindow;
     }
 
-    // Derived on each read from the current `seekable.end` and cached offset.
+    /**
+     * Presentation time marking the start of the Live Edge Window. Derived on
+     * each read from the current `seekable.end` and cached offset; `NaN` when
+     * the stream is not live or the offset is unavailable.
+     */
     get liveEdgeStart() {
       if (this.#liveEdgeStartOffset === undefined) return Number.NaN;
       const target = this.target as HTMLVideoElement | null;

packages/core/src/dom/media/native-hls/stream-type.ts

@@ -2,12 +2,16 @@ import type { Constructor } from '@videojs/utils/types';
 import { type MediaStreamType, MediaStreamTypes } from '../../../core/media/types';
 import type { NativeMediaHost } from './errors';
 
+/**
+ * @fires streamtypechange - Fired when the detected stream type changes. Read `streamType` for the new value.
+ */
 export function NativeHlsMediaStreamTypeMixin<Base extends Constructor<NativeMediaHost>>(BaseClass: Base) {
   class NativeHlsMediaStreamType extends (BaseClass as Constructor<NativeMediaHost>) {
     #streamType: MediaStreamType = MediaStreamTypes.UNKNOWN;
     #isUserStreamType = false;
     #disconnect: AbortController | null = null;
 
+    /** Current stream type (`'on-demand'` / `'live'` / `'unknown'`). */
     get streamType(): MediaStreamType {
       return this.#streamType;
     }