Skip to content

Overview

dispose() tears down a player instance completely. It is idempotent, so a second call is a no-op. After dispose() the instance is permanently dead, and re-use requires constructing a new player.

Signature

TypeScript
player.dispose(): void

What it does

  1. Checks that the player is not already disposed or disposing; if so, returns immediately.
  2. Transitions the phase to disposing.
  3. Drains the policy cleanup queue in registration order. The cleanup queue holds every subscription, event listener, interval, and RAF handle that setup()’s _wire* helpers registered. Each is called inside a try/catch, so a misbehaving cleanup function surfaces a warning event but does not block the rest of the queue.
  4. Clears the cleanup queue.
  5. If ready() never resolved, rejects the ready() promise with core:player/disposed.
  6. Emits dispose.
  7. Transitions the phase to disposed.
  8. Removes all event listeners via off('all').

Cleanup queue contract

Every cross-cutting concern registered during setup() pushes a cleanup function onto _policyCleanup:

  • Network monitor subscription
  • Visibility monitor subscription
  • Wake-lock release (if held)
  • Metrics interval
  • Progress throttle handler
  • Preload/transition listeners

Plugin lifecycles are separate. Plugin teardown is handled by removePlugin() and LifecycleRegistry, which runs before dispose() drains the policy queue when setup() calls dispose() internally.

Example

TypeScript
const player = nmplayer('main').setup({ ... });

// Later: SPA route change, component unmount, etc.
player.dispose();

// Attempting to call transport methods after dispose throws:
// PlayerError: core:player/disposed

See also