Configuration

All options passed to nmMPlayer(id).setup(opts). The type is MusicPlayerConfig<T> which extends BasePlayerConfig from the player core.

backend

backend?: 'audio-element' | 'webaudio'

Which audio backend to activate on first use. Default: 'audio-element'.

• 'audio-element', AudioElementBackend. Uses a native <audio> element. Crossfade is driven by a requestAnimationFrame loop (~50 fps, not sample-accurate). Safe on iOS and any context where Web Audio is unavailable or restricted.
• 'webaudio', WebAudioBackend. Routes audio through a Web Audio API AudioContext graph. Crossfade is sample-accurate via linearRampToValueAtTime, required for full EQ chain access.

You can switch backends at runtime: await player.backend('webaudio').

backendFactory

backendFactory?: (kind: AudioBackendKind, config: MusicPlayerConfig<T>) => IAudioBackend

Inject a custom audio backend. The factory receives the resolved kind and full config, and returns an IAudioBackend instance.

When backendFactory is set, the default AudioElementBackend / WebAudioBackend resolution is bypassed. The factory still receives the kind so it can branch on it or ignore it entirely.

import type { IAudioBackend } from '@nomercy-entertainment/nomercy-music-player/adapters/audio-backend';

player.setup({
  backend: 'audio-element',
  backendFactory: (kind, config) => {

    return new MyCapacitorAudioBackend(kind, config);
  },
});

crossfadeDefaults

crossfadeDefaults?: {
  duration: number;
  curve?: 'linear' | 'equal-power';
}

Default crossfade parameters applied when no explicit options are passed to crossfadeTo().

• duration, crossfade length in seconds. There is no default; pass a value explicitly when using this option.
• curve, gain ramp curve for the automatic AutoAdvance transition. 'equal-power' (default) keeps perceived loudness constant; 'linear' creates a ~3 dB dip at the midpoint. A manual crossfadeTo() call always ramps linearly and ignores this option.

player.setup({
  crossfadeDefaults: {
    duration: 5,
    curve: 'equal-power',
  },
});

playlist

playlist?: T[] | string

Initial track list. Pass an array of MusicPlaylistItem-compatible objects, or a URL to fetch and parse a playlist at setup time. When using a URL, the player fetches it via the configured auth pipeline.

Defaults to an empty queue when omitted.

player.setup({
  baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Music',
  playlist: [
    {
      id: 'kjc-01',
      name: 'Thaw You Out',
      url: '/D/Derek%20Clegg/%5B2010%5D%20KJC/01%20Thaw%20You%20Out.mp3',
      cover: '/D/Derek%20Clegg/%5B2010%5D%20KJC/01%20Thaw%20You%20Out.jpg',
      lyricsUrl: '/D/Derek%20Clegg/%5B2010%5D%20KJC/01%20Thaw%20You%20Out.lrc',
      artist: 'Derek Clegg',
      album: 'KJC',
    },
    {
      id: 'kjc-02',
      name: 'Hope',
      url: '/D/Derek%20Clegg/%5B2010%5D%20KJC/02%20Hope.mp3',
      cover: '/D/Derek%20Clegg/%5B2010%5D%20KJC/02%20Hope.jpg',
      lyricsUrl: '/D/Derek%20Clegg/%5B2010%5D%20KJC/02%20Hope.lrc',
      artist: 'Derek Clegg',
      album: 'KJC',
    },
  ],
});

trackEndingSoonThreshold

trackEndingSoonThreshold?: number

Seconds before natural end at which the trackEndingSoon event fires. Default: 10.

AutoAdvancePlugin listens to this event for preload and crossfade cues. Lower values give less time to preload and crossfade; higher values give more lead time at the cost of prematurely signalling the end.

player.setup({
  trackEndingSoonThreshold: 15, // fire 15 seconds before end
});

Auth (auth)

auth?: {
  bearerToken?: string | (() => string | Promise<string>);
  refreshOnUnauthenticated?: () => Promise<void>;
  signRequest?: (request: Request) => Request | Promise<Request>;
  headers?: Record<string, string | (() => string) | (() => Promise<string>)>;
}

Auth pipeline for authenticated audio fetches (media URL + any HLS manifests and segments the backend issues).

• bearerToken, static token string or a function (sync or async) that returns one. Injected as Authorization: Bearer <token>.
• refreshOnUnauthenticated, called once on a 401. Returns Promise<void>. After it resolves, the player re-reads bearerToken and retries the original request once. On a 403, the error propagates and refreshOnUnauthenticated is never called.
• signRequest, HMAC or custom signing. Called after bearerToken is applied.
• headers, static headers appended to every request.

player.setup({
  auth: {
    bearerToken: () => myAuth.getAccessToken(),
    refreshOnUnauthenticated: async () => {
      await myAuth.refresh();
    },
  },
});

Base URL (baseUrl)

baseUrl?: string

Base URL prepended to relative audio source URLs. Default: none (URLs used as-is).

Logging

logLevel

logLevel?: 'silent' | 'error' | 'warn' | 'info' | 'debug' | 'trace'

Log verbosity. Default: 'info'.

logger

logger?: ILogger

Custom logger. Defaults to the core’s console logger. Inject a Pino, Winston, or Bunyan adapter for production log routing.

Storage (storage)

storage?: IStorage

Where plugins persist their state (for example EqualizerPlugin band/preset state). Defaults to LocalStorageBackend. The core does not persist volume/shuffle/repeat itself.

import { LocalStorageBackend, MemoryStorageBackend } from '@nomercy-entertainment/nomercy-player-core';

// Default:
player.setup({ storage: new LocalStorageBackend() });

// Testing, ephemeral, no cross-tab persistence:
player.setup({ storage: new MemoryStorageBackend() });

Platform (platform)

platform?: IPlatform

Platform abstraction bundle. Defaults to browserPlatform from the player core.

For native-shell environments (Capacitor, Electron), override individual sub-ports:

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

player.setup({
  platform: {
    ...browserPlatform,
    network: myCapacitorNetworkMonitor,
  },
});

Music player sub-ports: wakeLock, network, visibility, capabilities. Fullscreen and PiP are video-only sub-ports and are not present in the music player platform contract.

i18n

language

language?: string

Initial language code (BCP 47, e.g. 'en', 'nl'). Default: browser navigator.language.

translations

translations?: Translations

Inline translation strings merged with the player’s built-in strings.

See also

• MusicPlaylistItem, fields accepted in the playlist array
• Backends overview, when to pick 'audio-element' vs 'webaudio'
• Crossfade, crossfadeTo(), crossfadeStart, crossfadeComplete
• Events, trackEndingSoon payload and timing