Overview
setup(config) is the entry point for every player instance.
It is synchronous in its first pass (wiring, seeding state, emitting beforeSetup) and asynchronous in the pipeline it kicks off (which emits ready when done).
You can call setup() immediately and safely enqueue addPlugin() and queue() calls before ready, they are buffered and applied during the right pipeline stage.
Signature
player.setup(config: BasePlayerConfig): this
Returns the player instance for chaining.
Throws: core:lifecycle/already-setup if called twice without dispose() first; core:player/disposed if called after dispose().
Setup pipeline
The async pipeline fires events in this order.
Each stage has a paired error event; any unhandled error rejects the ready() promise.
| Stage event | Error event | What happens |
|---|---|---|
beforeSetup | Last chance to add plugins before the pipeline starts | |
setupStart | setupStartError | Phase to setup, container element resolved |
configResolved | configResolvedError | Options normalised and validated |
pluginsRegistering | pluginsRegisteringError | Queued plugins registered in priority order |
pluginsRegistered | pluginsRegisteredError | All plugins’ use() promises settled |
streamsReady | streamsReadyError | Default stream factories (hls, native) registered |
authReady | authReadyError | Auth config resolved; token factory called once to warm |
playlistReady | playlistResolveError | config.playlist URL fetched (if string) or items queued (if array) |
mediaReady | mediaReadyError | First item loaded into backend (when config.playlist had items) |
ready | Player is ready to accept commands |
Key config fields
The full BasePlayerConfig is documented in Key Interfaces, BasePlayerConfig. Most common fields:
| Field | Type | Default | Description |
|---|---|---|---|
baseUrl | string | none | Prepended to relative media URLs in playlist items |
logLevel | 'silent' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'info' | Log verbosity |
auth | AuthConfig | none | Bearer token, headers, refresh function |
playlist | BasePlaylistItem[] | string | none | Initial playlist (items or URL to fetch) |
storage | IStorage | LocalStorageBackend | Pluggable storage backend |
platform | IPlatform | browserPlatform | Platform abstraction |
expose | boolean | false | Attach instance to window.player for debugging |
wakeLock | 'auto' | 'always' | 'never' | 'auto' (video) / 'never' (music) | Screen wake-lock policy |
onOffline | 'pause' | 'continue-buffered' | 'ignore' | 'continue-buffered' | Behaviour when network goes offline |
progressIntervalMs | number | 5000 | How often the throttled progress event fires |
metricsIntervalMs | number | 10000 | How often playback:metrics fires (0 = off) |
mutationGuards | false | 'all' | string[] | undefined | Mutation advisory control |
cast | CastConfig | none | Chromecast configuration |
ready()
Returns a promise that resolves when the setup pipeline reaches ready, or rejects if any stage fails or dispose() is called first.
Memoised, so repeated calls return the same promise.
const player = nmplayer('main').setup({
baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Films',
auth: { bearerToken: () => myAuth.getToken() },
playlist: [{ id: '1', title: 'Sintel', url: '/Sintel.(2010)/Sintel.(2010).NoMercy.m3u8' }],
});
await player.ready();
await player.play();
setupState()
Coarse lifecycle readiness as a SetupState enum value.
| Phase(s) | Return value |
|---|---|
idle | SetupState.NOT_SETUP |
setup | SetupState.SETTING_UP |
disposing, disposed | SetupState.DISPOSED |
| anything else | SetupState.READY |