<audio-spectrum-analyzer>

The spectrum analyzer is an inspectable live frequency plot beside one <audio-player>. Hover or use the keyboard to probe a frequency, freeze the visual frame, or compare held per-bin peaks. For a time-axis spectrogram of a decoded clip, use computeSpectrogram with <audio-view type="spectrogram">.

@webmusic/audio/analyze/element<audio-spectrum-analyzer>

Parameters

playerUnique audio-player selector in the current root. The tool borrows its analyser only while playing.frozenHold the currently drawn FFT frame for inspection.peak-holdOverlay the highest observed bin levels until Reset peaks.min-frequencyLower frequency of the logarithmic display.max-frequencyUpper frequency of the logarithmic display, limited by source Nyquist.aria-labelAccessible name of the inspection surface.

<audio-player>

srcURL of an audio file. Loading it replaces the selected clip; removing it clears a clip that came from src.formatForces the decode format. Changing it can only land through a reload of src.controlsVisibility only: the transport stays mounted and subscribed, so hiding it keeps the playhead.loopBare (or "true"/"loop") loops the whole clip; "a,b" — also "a-b"/"a:b" — loops those seconds. Applied live.enginebuffer decodes into memory, media streams through an <audio> element; auto prefers media above ten minutes.preserves-pitchHolds pitch while rate ≠ 1 on the media engine; a documented no-op on the buffer engine.volumeLinear master volume, clamped to 0–4 and applied live.ratePlayback speed, clamped to 0.25–4 and applied live.panStereo position, clamped to -1–1 and applied live.preloadWarms context, graph and decoded buffer on mount. `preload="none"` opts out, as on <audio>.

<audio-spectrum-analyzer></audio-spectrum-analyzer>

Import

<script type="module">
  import {defineAudioPlayerElement} from '@webmusic/audio/play/element';
  import {defineAudioSpectrumAnalyzerElement} from '@webmusic/audio/analyze/element';
  defineAudioPlayerElement();
  defineAudioSpectrumAnalyzerElement();
</script>

<audio-player id="session" src="/mp3/Arabesque%20No.1.mp3" controls></audio-player>
<audio-spectrum-analyzer player="#session" min-frequency="20" max-frequency="20000" peak-hold></audio-spectrum-analyzer>

The demo pairs one player with the plot. Start playback for live frames; Freeze, Peak hold, Reset peaks and the focusable frequency probe act on the real tool. Copy includes both elements, and Reset restores their demo settings. The probe accepts pointer movement, Arrow keys, Home/End for range ends, and Shift+Arrow for octave steps.

Signal and lifetime

The element borrows the bound player’s AnalyserNode while playing, or uses a caller-supplied .analyser in preference to it. It samples about every 50 ms and maps that node’s existing FFT bins onto a logarithmic frequency axis. The display ranges do not change the borrowed node’s fftSize, smoothingTimeConstant or other FFT settings. Its values are getByteFrequencyData() bins converted through the borrowed node’s current minDecibels/maxDecibels range; they are not calibrated sound-pressure levels.

Freezing stops frame polling and keeps the inspected frame until unfreeze or a transport/source change. Peak hold retains the largest displayed bin values until Reset peaks or a source change. Pause, seek, source replacement and missing input clear the current frame; a stalled frame source is reported as unavailable. Disconnect stops only this element’s polling and subscriptions, not the player or its graph. player must resolve uniquely in the current Document or ShadowRoot, including when a target appears later.

API

Member	Kind	Behavior
`player`	attribute	Unique selector for the playback owner whose analyser is borrowed while playing.
`frozen`	boolean attribute	Hold the current frame and stop this tool’s polling; default absent.
`peak-hold`	boolean attribute	Show held spectrum peaks alongside the live bins; default absent.
`min-frequency`	attribute	Lower displayed frequency in Hz; default `20`. Invalid or below-1 values use `20`.
`max-frequency`	attribute	Upper displayed frequency in Hz; default `20000`. Invalid or at-most-1 values use `20000`. Display is limited by the input’s Nyquist frequency.
`aria-label`	attribute	Accessible group name; default `Spectrum analyzer`.
`.analyser`	property	Explicit caller-owned `AnalyserNode` takes precedence over the player input.
`.frozen`, `.peakHold`	properties	Reflected booleans for frame freeze and peak hold.
`.minFrequency`, `.maxFrequency`	properties	Reflected displayed frequency limits in Hz.
`.selectedFrequency`	read-only property	Last probed frequency in Hz; initial value `1000`.
`.frame`	read-only property	Latest `{bins, sampleRate, fftSize, minDb, maxDb}` frame, or `undefined` when unavailable.
`.resetPeaks()`	method	Clear held spectrum peaks without changing the audio source.
`webaudio:spectrumprobe`	event	`{frequency, decibels?}` after a pointer or keyboard probe; bubbles and is composed.
`webaudio:error`	event	`{error: Error}` for an input, frame or presenter failure; bubbles and is composed.

Styling

The full-width host honors native hidden. Its outer surface uses the --wm-component-* tokens, with --wm-audio-spectrum-analyzer-surface-* overrides for this tag. The spectrum presenter exposes --wm-spectrum-height, --wm-spectrum-plot-background and related --wm-spectrum-* colors for the plot and controls.