Skip to content

Overview

Plugin registration methods manage the full plugin lifecycle: queuing before setup, inline registration after setup, dependency / version checks, same-id swap via static replaces, cascade removal, and translation merging.

addPlugin(PluginClass, opts?)

Register a plugin with the player. Returns the player for chaining.

Pre-setup or mid-setup (idle / setup phase): the plugin is queued and registered during the pluginsRegistering pipeline stage. Ordering within the queue follows registration order; dependency checks are evaluated at registration time across both registered and queued plugins so pre-setup ordering does not matter.

Post-setup: registration runs inline (fire-and-forget). Listen for plugin:installed or plugin:failed to know when it settled.

ParameterTypeDescription
PluginClassPluginCtorWithIdA class with static readonly id: string
optsP['opts']Typed options, inferred from the plugin class

Returns: this (the player instance)

Throws:

CodeCause
core:lifecycle/use-plugin-after-disposeCalled after dispose()
core:plugin/duplicate-idA plugin with the same id is already registered or queued
core:plugin/missing-depstatic requires lists a plugin that is not registered (and not optional)
core:plugin/version-mismatchA required dependency’s version is below minVersion
core:plugin/incompatible-core-versionstatic minCoreVersion exceeds the running core version
TypeScript
import { EqualizerPlugin } from '@nomercy-entertainment/nomercy-player-core';

player
  .setup({ ... })
  .addPlugin(EqualizerPlugin, { preset: 'flat' });

getPlugin(PluginClass)

Look up a registered plugin instance by class. Returns the instance typed as the class’s instance type, or undefined when not registered. Prefer this over getPluginById when the class is in scope.

Returns: P | undefined

TypeScript
const eq = player.getPlugin(EqualizerPlugin);
eq?.band(250, 6); // set 250 Hz band to +6 dB, fully typed

getPluginById(id)

Look up a registered plugin instance by string id. Use when the class is not in scope (e.g. cross-plugin discovery).

Returns: P | undefined (generic, defaults to object)

removePlugin(PluginClass, opts?)

Remove a plugin by class. Disposes its instance, drops its lifecycle resources, removes its translations, and emits plugin:disposed.

Cascade behaviour: when other plugins depend on the one being removed, they are removed first (recursively). Pass { cascade: false } to opt out, and the call will throw core:plugin/has-dependents instead.

Returns: void

removePluginById(id, opts?)

String-id version of removePlugin. Also clears any pending queue entry so a queued-then-removed plugin won’t register later.

plugins()

All registered plugin instances in registration order (both enabled and disabled). Returns a fresh array, so mutating it does not affect the player’s internal list.

Returns: ReadonlyArray<Plugin>

enabledPlugins()

Registered plugins that are currently enabled, ordered by static priority descending. Ties break by registration order. Used internally for before* dispatch chains.

Returns: ReadonlyArray<Plugin>

Plugin static contract

Static fieldTypeDescription
idstringRequired. Unique identifier ('vendor:name' convention)
versionstringSemver string for dependency checks
prioritynumberHigher = earlier in dispatch order
requiresRequireSpec[]Dependency declarations (class or { plugin, optional, minVersion })
replacesstringId of the plugin this one replaces
minCoreVersionstringMinimum core version required
advisoriesPluginAdvisory[]Mutation advisory declarations
translationsTranslationsTranslation bundle (eager or lazy via translationsFromGlob)

See also