<audio-meter>

<audio-meter> is the compact, always-visible Analyze monitor for a live signal. Use it to watch normalized level or spectrum activity at a glance beside an <audio-player>. For sampled dBFS history, a peak threshold and freeze, choose <audio-level-analyzer>; for frequency probing, choose <audio-spectrum-analyzer>. The meter is not a LUFS or inter-sample true-peak measurement.

@webmusic/audio/analyze/element<audio-meter>

Parameters

playerBorrow the central player output analyser; late insertion and source replacement are observed.modeChoose normalized level or FFT bars; changing modes remounts the presenter.barsSpectrum bar count, minimum 4; remounts the presenter.aria-labelAccessible monitor name.fft-sizePower-of-two FFT size for an owned tap only; does not retune a borrowed analyser.smoothing-time-constantOwned analyser smoothing; a borrowed analyser keeps its own setting.level-scaleMultiplier for the normalized RMS and peak display.peak-decayAbsolute per-read decrement of the held scaled-RMS marker.

<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-meter></audio-meter>

Import

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

<audio-player id="session" src="/mp3/Arabesque%20No.1.mp3" controls></audio-player>
<audio-meter player="#session"></audio-meter>

The demo pairs one real player with this meter. Its Parameters switch level and spectrum display modes and tune the monitor. Copy includes both Elements; Reset restores the demo settings. @webmusic/audio/analyze/auto also registers the tag. Existing view/element and view/auto imports remain compatibility paths to the same implementation and must not register a second meter.

Signal and ownership

The player selector must match one element in the meter’s Document or ShadowRoot. The meter borrows the player’s current analyser, follows late upgrade and source replacement, and never owns its transport. .player can instead borrow a nonvisual player directly and takes precedence over the selector. A missing or ambiguous selector leaves the meter empty; invalid selector syntax emits webaudio:error.

For another live graph, assign .analyser to borrow an AnalyserNode, or assign .context to create an owned transparent input -> analyser -> output tap. The caller supplies that context and connects the tap into its graph; the meter does not create an AudioContext. Direct .analyser or .context input takes precedence over player binding until cleared. Assigning a nonempty .player clears direct input. Disconnect or rebind releases the presenter, subscriptions and only owned tap nodes; it never closes or disconnects the borrowed player, analyser or context.

// For a caller-owned graph that should pass through the meter:
import type {AudioMeterElement} from '@webmusic/audio/analyze/element';

const context = new AudioContext();
const meter = document.querySelector('audio-meter') as AudioMeterElement | null;
if (!meter) throw new Error('Audio meter is missing');
meter.context = context;
const input = meter.input;
const output = meter.output;
if (!input || !output) throw new Error('Audio meter tap is unavailable');
const sourceNode: AudioNode = context.createGain(); // replace with your source
sourceNode.connect(input);
output.connect(context.destination);

The level fill is scaled RMS. Its held marker retains scaled RMS with an absolute decrement per read, not elapsed-time decay or instantaneous sample-peak hold. Spectrum bars aggregate the borrowed analyser’s current FFT bins. The displayed values are normalized, not dBFS, LUFS or calibrated SPL. The presenter’s frame loop reads while connected; changing a source builds a replacement before releasing the prior tap, and failed replacement preserves the working route.

API

Member	Kind	Behavior
`player`	attribute	Unique selector for one player Element in the current root; default absent. Late insertion, upgrade, replacement and removal are observed.
`mode`	attribute	`level` (default) or `spectrum`; other values use level. Changing it remounts the presenter, not the audio graph.
`bars`	attribute	Spectrum bar count, minimum `4`, default `28`; changing it remounts the presenter.
`aria-label`	attribute	Accessible meter name; updates without remounting the presenter.
`fft-size`	attribute	Owned tap analyser FFT size, power of two from `32` to `32768`; default `1024`. Does not retune a borrowed analyser.
`smoothing-time-constant`	attribute	Owned tap analyser smoothing in `0..1`; default `0.8`. Does not retune a borrowed analyser.
`level-scale`	attribute	Non-negative multiplier for displayed RMS/peak; default `1.8`.
`peak-decay`	attribute	Non-negative absolute decrement of the held scaled-RMS marker per read; default `0.012`.
`.player`	property	Borrow an `AudioMeterPlayer`; takes precedence over selector binding. Clearing it returns to the selector.
`.analyser`	property	Borrow an existing `AnalyserNode` without connecting or disconnecting it; the getter exposes the current analyser, if any.
`.context`	property	Caller-supplied `BaseAudioContext` used to build an owned transparent tap.
`.input`, `.output`	read-only properties	Stable tap splice points when using `.context`; absent for a borrowed analyser.
`webaudio:error`	event	The thrown error value is passed directly as `detail` for tuning, read or cleanup failures; bubbles and is composed.

Removing a tuning attribute restores its default. Invalid live tuning reports an error and keeps the previous working graph and settings. The controller’s input/output ports remain stable during valid tuning changes. Subclasses may override the protected createMeterController, createMeterBinding, mountMeterUI and onMeterError hooks; they do not change the tag’s resource ownership by default.

The presenter’s level and spectrum surfaces use an accessible name supplied by aria-label. This meter has no built-in transport or parameter gestures. The surrounding application controls its mode and tuning attributes; its readout itself does not seek or alter audio.

Styling

The host has an open shadow root. Its outer surface uses --wm-audio-meter-surface-background, --wm-audio-meter-surface-border, --wm-audio-meter-surface-padding and --wm-audio-meter-surface-radius, then the corresponding --wm-meter-surface-* and shared --wm-component-* fallbacks. The neutral meter presenter uses public --wm-meter-* colors and dimensions. Legacy --wameter-bg, --wameter-track, --wameter-fill, --wameter-peak and --wameter-height aliases remain effective. Its root exposes part="wrap"; the presenter’s other documented parts remain available inside the shadow root.

audio-meter {
  --wm-meter-fill: #258a80;
  --wm-meter-peak: #cb6541;
  --wm-meter-height: 3rem;
}