Equalizer

10-band parametric EQ provided by EqualizerPlugin (re-exported from the player core). Import it from @nomercy-entertainment/nomercy-music-player/plugins.

The idea

The equalizer is a set of tone controls you drop into the audio while it’s playing. The actual audio plumbing lives in AudioGraphPlugin, the part that holds the AudioContext and wires everything together, so you add that one first. The equalizer just hooks its ten filters into that chain, and there is nothing to shape until the chain exists, which is the whole reason for the ordering.

Most of the time you won’t be touching bands from code. You put the sliders in front of your users and let them play. Each band pushes one frequency up or down by up to 12 dB, and pre-gain pulls the whole signal down a little so big boosts don’t distort. The presets are just handy starting points we ship so nobody has to dial in “Rock” by hand. Set a persistKey and the plugin remembers wherever they leave it. Everything below is the reference for when you want finer control.

Requirements

EqualizerPlugin requires AudioGraphPlugin. Register AudioGraphPlugin first.

TypeScript

import { AudioGraphPlugin, EqualizerPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

const player = nmMPlayer('main')
  .addPlugin(AudioGraphPlugin)
  .addPlugin(EqualizerPlugin)
  .setup({ playlist: myTracks });

19 built-in presets are included (Classical, Club, Dance, Flat, Rock, Pop, and more). Pass presets in options to extend or override them.

Options

Option	Type	Default	Description
`bands`	`ReadonlyArray<EqBand>`	10 standard frequencies + pre-gain	Initial band layout. Element 0 must be `{ frequency: 'Pre', gain }`.
`preset`	`string`	`undefined`	Name of a built-in or custom preset to apply immediately on `use()`.
`presets`	`ReadonlyArray<EqPreset>`	`undefined`	Additional or replacement presets merged into the catalogue. Built-ins remain unless overridden by name.
`sliderValues`	`EqSliderValues`	`undefined`	Override min/max/step ranges for slider helper methods. Default ±12 dB for bands, −1 to +3 for pre-gain.
`persistKey`	`string`	`undefined`	Storage key for automatic persistence. Band state, selected preset, and custom presets are saved on every change and restored on `use()`.
`autoLoad`	`boolean`	`true`	Read persisted state on `use()`. Set to `false` to always start from `bands` / `preset` opts.
`autoSave`	`boolean`	`true` when `persistKey` is set	Persist state after every `band()` / `preGain()` / `preset()` call.
`smoothingTimeConstantSeconds`	`number`	`0.05`	Time constant (seconds) for `AudioParam.setTargetAtTime` gain ramps. Smaller = snappier; larger = silkier transitions.

Band frequencies

The plugin uses 10 peaking filter bands plus a pre-gain pseudo-band:

Frequency	Notes
`'Pre'`	Pre-gain stage
70 Hz
180 Hz
320 Hz
600 Hz
1000 Hz
3000 Hz
6000 Hz
12000 Hz
14000 Hz
16000 Hz

Band gain range: −12 dB to +12 dB. Pre-gain range: −1 to +3.

Methods

TypeScript

import { EqualizerPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

const eq = player.getPlugin(EqualizerPlugin)!;

// Read a band gain by frequency (Hz or 'Pre'):
const bassGain = eq.band(70);
const preGain = eq.preGain();

// Set a band by frequency:
eq.band(70, 6); // boost 70 Hz by 6 dB
eq.preGain(0.5); // raise pre-gain

// Apply a built-in or custom preset by name:
eq.preset('Rock');

// Read current preset name:
const name = eq.preset();

// Read all bands as EqBand[] snapshot:
const allBands = eq.bands();

// Reset to initial state:
eq.reset();

// Add a custom preset at runtime:
eq.addCustomPreset({
  name: 'My Preset',
  values: [
    { frequency: 70, gain: 4 },
    { frequency: 3000, gain: -2 },
  ],
});

Events

Event	Payload	Description
`ready`	`void`	Fired at end of `use()` once the filter chain is wired and any persisted state is restored.
`band:changed`	`{ band: EqBand }`	Fired when a single band’s gain changes.
`preset:changed`	`{ name: string \| undefined }`	Fired when a preset is applied or cleared. `name` is `undefined` after `reset()`.
`change`	`{ bands: EqBand[]; selectedPreset: string \| undefined }`	Aggregate event after any mutation, carrying the full band snapshot.
`saved`	`void`	Fired after state is successfully written to storage.

TypeScript

// Fires for every band change:
player.on('plugin:equalizer:band:changed', ({ band }) => {
  updateSlider(band);
});

// Fires after any mutation:
player.on('plugin:equalizer:change', ({ bands, selectedPreset }) => {
  renderEqState(bands, selectedPreset);
});

// Fires when a preset is selected or cleared:
player.on('plugin:equalizer:preset:changed', ({ name }) => {
  highlightPreset(name);
});

Persistence

Set persistKey in EqualizerPlugin options to enable automatic persistence. EQ state (bands, selected preset, custom presets) saves on every change and restores on the next setup().

TypeScript

player.addPlugin(EqualizerPlugin, { persistKey: 'my-app-eq' });