Stream Registry - NoMercy Docs

Overview

The stream registry maps format identifiers (e.g. 'hls', 'native') to factory functions that create backend playback instances. Factories are tried in reverse registration order, most-recently-registered first, so a custom factory takes priority over the core’s built-in hls and native factories.

Default factories (hls, native) are registered lazily at streamsReady during setup, or on first access to the registry.

`registerStream(factory, prepend?)`

Parameter	Type	Description
`factory`	`IStreamFactory`	Factory object with `id` and `create`
`prepend`	`boolean`	Push to the back of the queue (lower priority)

Returns: this (the player, for chaining)

TypeScript

import type { IStreamFactory } from '@nomercy-entertainment/nomercy-player-core';

const dashFactory: IStreamFactory = {
  id: 'dash',
  canPlay: (url) => url.endsWith('.mpd'),
  create: (opts) => new DashBackend(opts),
};

player.registerStream(dashFactory);

`unregisterStream(id)`

Remove a registered factory by id. No-op when the id is not registered.

Returns: this

`streams()`

Snapshot of registered factory ids in resolution order (highest-priority first).

Returns: ReadonlyArray<string>

`getStreamFactory(id)`

Look up a registered factory by id.

Returns: IStreamFactory | undefined

IStreamFactory interface

TypeScript

interface IStreamFactory {
  /** Stable identifier for this factory. Must be unique in the registry. */
  readonly id: string;

  /**
   * Return true when this factory can handle the given URL and content-type.
   * The optional capabilities argument lets the factory decline when the
   * device cannot decode what the URL points to.
   * Factories are tried in reverse-registration order; the first to return
   * true is used. Returning false passes control to the next factory.
   */
  canPlay(url: string, contentType?: string, capabilities?: StreamCapabilities): boolean;

  /** Instantiate an IStreamSource for the given options. */
  create(opts: StreamFactoryOptions): IStreamSource;
}

IStreamSource interface

The contract every backend must satisfy. Only the methods the player calls need to be implemented; opt-in surfaces (getLevels, setLevel, etc.) are called conditionally.

TypeScript

interface IStreamSource {
  readonly kind: 'native' | 'hls' | 'dash';

  /** Wire this source to a media element. Resolves once metadata is available. */
  attach(element: HTMLMediaElement): Promise<void>;

  /** Remove this source from the element without releasing internal state. */
  detach(): void;

  /** Detach and release all internal state. The instance is unusable after this. */
  destroy(): void;

  /** Current lifecycle state. */
  state(): StreamSourceState;

  /** All renditions reported by the manifest. Empty for fixed-bitrate sources. */
  getLevels?(): StreamLevel[];

  /** Force a specific rendition index. Pass -1 to return to ABR. */
  setLevel?(idx: number): void;

  /** Rendition currently driving playback, or undefined before the first switch. */
  getCurrentLevel?(): StreamLevel | undefined;

  /** Replace the default ABR selector with a custom function. */
  setLevelStrategy?(fn: (levels: StreamLevel[], ctx: { bandwidth: number; bufferedSeconds: number }) => number): void;

  on<E extends StreamEvent>(event: E, fn: (data: StreamEventPayloadMap[E]) => void): void;
  off<E extends StreamEvent>(event: E, fn: (data: StreamEventPayloadMap[E]) => void): void;
}

Built-in factories

Id	Description
`'hls'`	hls.js adaptive bitrate streaming
`'native'`	Browser-native `<video>` / `<audio>` playback

The hls factory is registered with higher priority, so it is tried first. The native factory is the fallback for formats the browser handles natively (MP4, WebM, Ogg, MP3, etc.).