Skip to content

Equalizer Customization

The EqualizerPlugin (from @nomercy-entertainment/nomercy-player-core) inserts a 10-band peaking EQ into the Web Audio graph. This page covers custom presets, band manipulation, and state persistence.

Prerequisites

EqualizerPlugin requires AudioGraphPlugin. Register AudioGraphPlugin first.

AudioGraphPlugin works with both backends but fully connects the graph to AudioContext only on webaudio. On audio-element, it creates a MediaElementAudioSourceNode lazily.

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

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

Band frequencies

FrequencyNotes
'Pre'Pre-gain (unity = 0)
70 HzSub-bass
180 HzBass
320 HzLow-mid
600 HzMid
1000 HzUpper-mid
3000 HzPresence
6000 HzBrilliance
12000 HzAir
14000 HzHigh air
16000 HzCeiling

Band gain range: −12 dB to +12 dB. Pre-gain range: −1 to +3 (0 = unity gain).

Preset design guide

19 built-in presets are included (access via eq.presets()). To add custom presets, use addCustomPreset() or supply them in EqualizerOptions.presets:

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

const myPresets: EqPreset[] = [
  {
    name: 'Podcast',
    values: [
      { frequency: 70, gain: -3 },
      { frequency: 180, gain: -2 },
      { frequency: 600, gain: 2 },
      { frequency: 1000, gain: 4 },
      { frequency: 3000, gain: 3 },
    ],
  },
  {
    name: 'Bass Boost',
    values: [
      { frequency: 70, gain: 6 },
      { frequency: 180, gain: 4 },
      { frequency: 320, gain: 2 },
    ],
  },
];

player.addPlugin(EqualizerPlugin, { presets: myPresets });

Preset values is a partial list, so only the frequencies listed are updated; other bands keep their current gain. This lets a preset target a subset of the chain without resetting the rest.

At runtime, add or update a preset without re-registering the plugin:

TypeScript
const eq = player.getPlugin(EqualizerPlugin)!;
eq.addCustomPreset({ name: 'My Mix', values: [{ frequency: 70, gain: 4 }] });
eq.preset('My Mix');

Runtime band manipulation

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

const eq = player.getPlugin(EqualizerPlugin)!;

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

// Write a single band:
eq.band(70, 6); // boost 70 Hz by 6 dB
eq.band({ frequency: 70, gain: 6 }); // equivalent object form

// Apply a preset by name:
eq.preset('Rock');

// Read the active preset name:
const activeName = eq.preset();

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

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

Listening to EQ changes

EqualizerPlugin emits band:changed for each band mutation and change for the full snapshot:

TypeScript
player.on('plugin:equalizer:band:changed', ({ band }) => {
  updateSliderAt(band.frequency, band.gain);
});

player.on('plugin:equalizer:change', ({ bands, selectedPreset }) => {
  renderFullEqState(bands, selectedPreset);
});

Persistence

Persistence is opt-in: set persistKey in EqualizerPlugin options and EQ state (bands, selected preset, pre-gain, custom presets) is saved on every change and restored on the next use().

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

The default storage backend is LocalStorageBackend. Override by passing a custom backend in setup():

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

// Ephemeral, resets on page reload:
player.setup({ storage: new MemoryStorageBackend() });

Pre-gain

Pre-gain is a global gain stage applied before the filter chain. A value of 0 is unity gain (the default). Positive values boost, negative values cut. Use it to compensate for overall loudness increase when boosting multiple bands:

TypeScript
const eq = player.getPlugin(EqualizerPlugin)!;
eq.preGain(-0.3); // slight reduction to prevent clipping with heavy boosts

The pre-gain slider range is −1 to +3 (wider than band sliders). The underlying GainNode receives preGain + 1 so 0 maps to 1.0 (unity).

See also