Skip to content

Plugin: Spectrum

SpectrumPlugin (id 'spectrum') reads Audio Graph’s analyser node once per animation frame and produces a VisualizationFrame: frequency and waveform buffers (both byte and float), per-band energy (bass / mid / treble), and beat/BPM fields when a beat provider is registered. Visualization is the primary consumer, but any plugin can read frames directly.

Options

OptionTypeDefaultPurpose
fftSize512 | 1024 | 2048 | 4096inherits Audio Graph’s analyserAnalysis resolution.
smoothingTimeConstantnumberinherits Audio Graph’s analyserAnalyser smoothing.
stereobooleanfalseAllocate separate left/right analysers instead of one summed channel.
frameRatenumber—Reserved, currently unused.

Events

frame ({ frame: VisualizationFrame; energy: { bass, mid, treble } }), opts:changed.

Rules & restrictions

  • static requires = [AudioGraphPlugin] — throws core:plugin/missing-dep without it.
  • stereo: true allocates two extra AnalyserNodes and four extra typed-array buffers per frame, only turn it on when a consumer actually needs per-channel data.
  • Synthetic mode (syntheticMode(true) + pushFrame(frame)) exists for passive NoMercy Connect receivers that have no local audio stream to analyse: it bypasses the AnalyserNode entirely and re-emits the last pushed frame verbatim. time/deltaMs on a synthetic frame are not overridden by the canvas RAF clock the way a real-analysis frame’s are.

How to extend it

TypeScript
import nmplayer from '@nomercy-entertainment/nomercy-video-player'; // nomercy-music-player's factory works identically
import { AudioGraphPlugin, SpectrumPlugin } from '@nomercy-entertainment/nomercy-player-core';

const player = nmplayer('player');

player.addPlugin(AudioGraphPlugin);
player.addPlugin(SpectrumPlugin, { stereo: false });
await player.ready();

const spectrum = player.getPlugin(SpectrumPlugin);
console.log(spectrum!.bandEnergy(20, 250)); // energy in the bass range, right now

Next steps