Skip to content

Plugin: Audio Graph

AudioGraphPlugin (id 'audio-graph') owns the Web Audio signal chain: it creates or reuses the player’s AudioContext, mounts a MediaElementAudioSourceNode from the backend, and wires source → destination. Every other audio-processing plugin in the kit builds on this same chain rather than creating its own, though not identically: the equalizer and mixer insert themselves into the serial chain via insertEffect() / pre() / post(), the spectrum plugin parallel-taps the shared AnalyserNode instead of joining the serial path, and the visualization plugin depends only on canvas and spectrum, it never touches AudioGraphPlugin directly.

Options

OptionTypeDefaultPurpose
latencyHintAudioContextLatencyCategory'playback'Forwarded to the AudioContext constructor.
fftSize256 | 512 | ... | 163842048Analyser node size for plugins that read frequency/waveform data.
smoothingnumber (0-1)0.8Analyser smoothing time constant.

Events

context:ready ({ sampleRate }), context:closed, chain:rebuilt, unsupported ({ reason }).

Rules & restrictions

  • Register this plugin first. Every other audio plugin declares static requires = [AudioGraphPlugin] and throws core:plugin/missing-dep at registration if it isn’t present.
  • Browser autoplay policy: the AudioContext starts 'suspended' and is resumed only on the first play event, so it must fire during or right after a user gesture. There’s no workaround, the browser enforces this regardless of what the kit does.
  • Throws a BrowserPolicyError and emits unsupported when AudioContext is unavailable in the runtime (rare, but true for some embedded WebViews).
  • outputNode() throws a PluginError if called before use() has run.

How to extend it

Effects insert themselves via insertEffect(node, position?) (or the pre(node) / post(node) shorthands): the plugin owns node ordering so two independent effect plugins don’t have to coordinate insertion points with each other.

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

const player = nmplayer('player');

player.addPlugin(AudioGraphPlugin, { fftSize: 4096 });
await player.ready();

const graph = player.getPlugin(AudioGraphPlugin);
const gain = graph!.context().createGain();
graph!.insertEffect(gain, 'post'); // spliced in after the source, before destination

Next steps