AudioVisualizerController
Feeds a visualization preset the sound of an audio or video element, or of a MediaStream, while it plays.
Reach for it to show levels or a waveform next to a player. The controller measures the sound and runs the frame loop; a preset decides how it looks, and you can swap presets while it plays.
Import
import {
AudioVisualizerController,
createAudioVisualizerController,
bars,
wave,
} from '@ecopages/radiant-ui/controllers';Try it
Play the tone, then switch the preset. Bars writes a --level custom property on four elements that the page styles, Canvas bars and Wave draw on a canvas the preset creates in the same box, and Dots is the preset written in Writing a preset.
<div data-example="audio-visualizer">
<button type="button" data-play>Play</button>
<button type="button" data-preset="bars-dom" aria-pressed="true">Bars</button>
<button type="button" data-preset="bars-canvas" aria-pressed="false">Canvas bars</button>
<button type="button" data-preset="wave" aria-pressed="false">Wave</button>
<div data-visual><span></span><span></span><span></span><span></span></div>
<audio></audio>
</div>import { AudioVisualizerController, bars, wave } from '@ecopages/radiant-ui/controllers';
export function mount(root: HTMLElement): () => void {
const audio = root.querySelector('audio')!;
const visual = root.querySelector<HTMLElement>('[data-visual]')!;
audio.src = createToneUrl(); // a short generated WAV; any audio source works
audio.loop = true;
const visualizer = new AudioVisualizerController({
getMedia: () => audio,
getTarget: () => visual,
preset: bars({ mode: 'dom', selector: 'span' }),
});
visualizer.attach();
root.querySelector('[data-preset="wave"]')!.addEventListener('click', () =>
visualizer.setPreset(wave({ fill: true })),
);
return () => {
visualizer.destroy();
audio.pause();
};
}mount runs once for each example element on the page, and the function it returns undoes it; see how the examples run. The page script also builds the tone and wires the play button and the other presets.
The bars are plain elements the page styles with the level:
[data-visual] span {
transform: scaleY(var(--level, 0.12));
transform-origin: bottom;
}Config
| Option | Description |
|---|---|
getMedia | The audio or video element. Resolved on every attach(); null attaches nothing. Give this or getStream, never both. |
getStream | A MediaStream instead of an element; see Visualizing a MediaStream. Resolved on attach() and refresh(). |
getTarget | The element the preset mounts into: the container of the bars, or the element a canvas is created in. null is retried on play. |
preset | An AudioVisualizerPreset: bars(...), wave(...) or your own. |
getEnabled | Optional. Checked when playback starts and on every frame; false keeps the preset at rest. |
onState | Optional. Called with idle, running, reduced or opaque each time getState() changes, never per frame. |
Methods: refresh() resolves the getters and getEnabled again and starts or stops to match; call it when the host renders the media element late, or when what getEnabled returns changes while the media plays. setPreset(preset) rests and destroys the old preset, mounts the new one and keeps drawing if the media is playing. resume() asks the audio context to run from inside a click or key handler and starts the loop once it does; see Lifecycle. getState() is 'running' while the loop draws, 'reduced' while attached and the user prefers reduced motion, 'blocked' while the media plays a source that is cross-origin without CORS (never for a stream), and 'idle' otherwise. refresh() does nothing before attach() and after destroy(); destroy() is synchronous, unlike MediaController.destroy(), because a visualizer owns nothing the media needs.
Presets
A preset is an object with mount(target), draw(frame), rest() and destroy(), and optionally fftSize and smoothing; Writing a preset has the contract.
| Preset | What it does | Options |
|---|---|---|
bars({ mode: 'dom' }) | Writes each band's level as --level (0 to 1) on the target's bar elements and removes it on rest. With no bands, each element gets one of as many log-spaced bands as there are elements. | selector (default: direct children), bands (Hz ranges), floor (default 0.12), and the level options below |
bars({ mode: 'canvas' }) | Draws vertical bars on a canvas it creates in the target. | count (default 24), bands, floor, gap, color, the level options and the look options below |
wave() | Draws the waveform as a smooth line on a canvas it creates in the target. | lineWidth (default 2), fill, color, padding (default 0) |
Both bars modes shape the level of a band, the analyser's byte as 0 to 1, with these options; the defaults leave it as it is:
| Option | Description |
|---|---|
floorLevel | The analyser level at or below which a band is off. Default 0. The analyser's scale is loud, so music rarely falls under 0.2 and a bar never empties until this is above the noise of the media. |
range | The analyser span above floorLevel that fills the bar. Default 1. A smaller range reaches the top sooner. |
curve | An exponent on the scaled level. Default 1. Above 1 pushes quiet bands down and keeps peaks high, which is what leaves gaps inside the sound. |
adapt | Scales against the loudest band of the last moments, a running maximum that falls by this many full scales per second (0.2 is slow), in place of range, so a quiet track still reaches the top. Default: off. |
floor | The lowest level a solid or dom bar shows, default 0.12. Segmented bars ignore it: a band that is off lights no segment. |
The canvas bars come in four variants, chosen with variant; every one takes the same level shaping above, so they move alike:
| Variant | Look |
|---|---|
led | LED segments lit from the bottom (segments, default 12; segmentGap). The default when segments is set. |
solid | Continuous bars with rounded tops (ends: 'round' is its default; ends: 'square' for flat tops). |
line | Hairline bars of lineWidth CSS pixels (default 2), centered in wide slots (gap default 6). |
mirror | Continuous bars that grow up and down from the middle; with colorEnd, the gradient runs from color at the middle line to colorEnd at both edges. |
Without variant the bars are as in earlier versions: led when segments is set, otherwise a plain solid bar with square ends and a floor minimum. With a variant, a bar has no minimum height: a band under floorLevel is not drawn, and the bars do not start with a stub when the music starts. At rest, idle: 'floor' draws one dim hairline per bar (the lowest segment for led), 'clear' nothing. peaks draw a cap above each bar, and below it too for mirror, but none on a bar that is off. padding, gap, color, colorEnd, the pixel ratio and reduced motion work the same in every variant.
The canvas bars take these options for a look closer to a hardware meter; each has a default that keeps the plain bars:
| Option | Description |
|---|---|
padding | CSS pixels kept free around the bars inside the canvas. Default 0. wave() takes the same option, so a wave can run edge to edge or sit inside a margin. |
variant | 'led', 'solid', 'line' or 'mirror'; see the table above. Default: led when segments is set, otherwise the plain solid bar. |
lineWidth | CSS pixels of a line bar. Default 2. |
segments | Splits each bar into this many LED segments, lit from the bottom as the level rises. Default 12 for variant: 'led'; otherwise a solid bar. |
segmentGap | CSS pixels between segments. Default 1. |
ends | 'square' or 'round': the shape of a bar (rounded tops), or of each segment (a pill). Default 'round' for solid and mirror, otherwise 'square'. |
colorEnd | A custom property name or CSS color. The bars fade from color at the bottom to this at the top. Default: one color. |
peaks | { hold, fall }: a cap above each bar that holds the highest recent level for hold ms (default 450), then falls fall bar heights per second (default 1.2). Default: none. |
idle | 'clear' (default) draws nothing at rest; 'floor' draws a baseline from the moment the preset is mounted, with no caps: solid bars at their floor height, segmented bars as their lowest segment only, dimmed. |
The controller never draws under prefers-reduced-motion, so the peak caps never fall there; idle: 'floor' is what keeps the bars on screen, as a static row. The canvas path does no DOM work per frame: it draws on the canvas, takes the colors from custom properties once per frame and keeps the pixel ratio handling of createCanvasSurface.
Canvas presets fill the target, so give it a height and no other content: the canvas is added after what is there. They follow the canvas's own size and the device pixel ratio (browser zoom, another screen), remove the canvas on destroy, and read color at draw time: a CSS custom property name such as --primary (the default) or any CSS color. A theme or light and dark change shows on the next frame.
Lifecycle
attach() listens to the media element's play, pause, ended and emptied, and mounts the preset. The animation-frame loop runs only while the media plays; the host wires nothing else. If the media is already playing at attach(), the loop starts at once. destroy() ends the loop and the listeners, rests and destroys the preset. A destroyed controller can attach again.
Routing is permanent. The first time an element is visualized, its source node is connected straight to the speakers of one shared AudioContext, for the element's whole life: an element can feed only one source node, and there is no way to give it back to the browser's own output. Each controller reads the sound through an analyser of its own, with its own fftSize and smoothing, which is disconnected when it stops or is destroyed. The context is never suspended or closed, so a player keeps playing after its visualizer is destroyed; the cost is an audio thread that keeps running once any media has been visualized.
So the sound is unchanged only while a visualized element keeps same-origin or CORS-enabled sources (crossorigin plus CORS headers), redirects included, for its whole life. What happens otherwise:
- A later source that is cross-origin without
crossoriginplays as silence. The controller sees it by the URL and reportsopaque; a same-origin URL that redirects to another origin cannot be seen, and is silent with no report. - A context that the browser suspends or interrupts (iOS Safari on lock or a call) silences the media until it runs again. Call
resume()from a user gesture.
Before an element has been routed, the controller stays idle and leaves the media on its native output, then tries again on the next play, volumechange, resume() or change of the context's state, when:
- The browser has not allowed the context to start (autoplay policy before a user gesture). A
playthat follows a click or key press starts it. - The media is cross-origin and has no
crossoriginattribute (opaquewhile it plays;reducedwins over it). A source node turns such media into silence, so it needscrossoriginand a server that sends CORS headers. - The context cannot be created, or the element already feeds a source node that other code made.
If the browser suspends or interrupts the context while it draws, the loop stops and the state is idle until the context runs again and the media plays.
resume() is for the host's click or key handler: it creates the context if needed and calls its resume() inside the gesture, then starts the loop. Chromium accepts a play after a gesture, but WebKit is stricter about which call counts and also leaves a context interrupted after a lock; the method exists for that, and has not been verified on a device.
With a host, createAudioVisualizerController(host, config) does the same on connect and disconnect; see bindController.
Visualizing a MediaStream
Pass getStream in place of getMedia to visualize a microphone, a recording in progress or any other MediaStream. Give exactly one of the two: both is a compile error. The generated stream below is an oscillator rendered into a MediaStreamAudioDestinationNode, so the example needs no microphone and makes no sound. Start it, then stop it.
const visualizer = new AudioVisualizerController({
getStream: () => recorder.getStream(), // null until recording starts
getTarget: () => visual,
preset: bars({ mode: 'canvas', count: 32, segments: 8, peaks: {}, idle: 'floor' }),
});
visualizer.attach();
startButton.addEventListener('click', () => visualizer.resume());The snippet assumes a recorder, or any other stream source, with a getStream() method and an onState callback; build it with onState: () => visualizer.refresh() so the visualizer follows the recording, and with any other source call refresh() yourself when the stream changes. The stream is resolved on attach() and again on every refresh(), which is how a host that has no stream until recording starts tells the controller. While the getter returns null the preset stays mounted and at rest. A different stream replaces the old one: the old source is disconnected, the preset rests, and the loop starts on the new stream. The frame loop runs while the stream has a live audio track, so a stream with no live audio track, such as one whose tracks the host stopped, leaves the state idle and draws nothing until a stream with a live track arrives.
What differs from an element:
- The stream goes to the analyser only. An element's source is also connected to the speakers, to keep it audible, but a microphone played back is feedback, so the controller never connects a stream to the destination.
- The host owns the stream.
destroy()disconnects the controller's source and leaves every track live; stop the tracks yourself. - The shared
AudioContextis the same as the element path's, never closed, and it starts only inside a user gesture: callresume()from the click that starts the stream. - There is no
crossoriginhandling and the state is neveropaque.
Preset utilities
The utilities the built-in presets use are exported for presets you write:
| Export | What it does |
|---|---|
logBands(count, min?, max?) | count contiguous log-spaced FrequencyBands ([low, high] in Hz), 60 Hz to 8 kHz by default. |
bandPeak(frequency, rate, fftSize, band) | The loudest bin of frame.frequency in a band, 0 to 1. A band narrower than a bin, or above the Nyquist frequency, still reads one bin, so a band is never empty. |
createCanvasSurface(target, onResize?) | An aria-hidden canvas filling the target, sized from its own box and the device pixel ratio, with context, width, height, clear(), resolveColor(color) and destroy(). onResize runs after each resize, which clears the canvas. |
stepPeak(peak, level, now, elapsed, timing) | Moves a peak cap that rises with the level, holds for timing.hold ms and falls timing.fall bar heights per second. It writes into peak, so a frame allocates nothing. |
litSegments(level, segments), segmentBounds(index, segments, gap, top, height) | How many LED segments a level lights, and the top and height of one segment in a bar. |
Writing a preset
A preset is an object, so a package can export presets and nothing else of the controller. The contract, in the order the controller calls it:
| Field | Who calls it and when |
|---|---|
mount(target) | Once the preset is in use: when the controller attaches, or on the first play if the target was not there yet, and from setPreset. It can run again on the same object after destroy(). Create what you need inside target and nothing outside it. |
draw(frame) | On every animation frame while the loop runs: the media plays (or a stream is set), the context runs, motion is not reduced and getEnabled allows it. frame is { frequency, waveform, sampleRate, fftSize }. |
rest() | When the loop stops (pause, end, a stream replaced or null, a suspended context), and in place of draw() while the user prefers reduced motion (state reduced) or getEnabled is false. It can run on a preset that was never mounted. Show a static idle look, or nothing. |
destroy() | When setPreset replaces the preset, after its rest(), and when the controller is destroyed. Remove everything mount added; leave no listener, observer or timer. |
fftSize? | The analyser resolution, a power of two from 32 to 32768, default 1024. Read when the loop starts and when the preset is swapped while it runs. frame.frequency has fftSize / 2 bins of sampleRate / fftSize Hz; frame.waveform has fftSize samples. |
smoothing? | The analyser's smoothing of the spectrum between frames, 0 to 1, default 0.8. Read at the same moments. |
The bytes in frame run from 0 to 255 and the waveform is centered on 128. Both buffers are reused for every frame: read them in draw() and keep no reference.
A canvas preset creates its canvas with createCanvasSurface in mount, draws on surface.context in draw, clears in rest and destroys the surface in destroy; the surface follows the box and the device pixel ratio, so the preset never reads either. A DOM preset keeps the elements the host rendered and writes to them, as bars({ mode: 'dom' }) does with a --level custom property that the page's CSS turns into a transform; it creates nothing per frame and removes what it wrote in rest and destroy.
This preset draws one dot per band, and is the Dots button in the first example:
import {
bandPeak,
createCanvasSurface,
logBands,
type AudioFrame,
type AudioVisualizerPreset,
type CanvasSurface,
} from '@ecopages/radiant-ui/controllers';
export function dots(count = 12): AudioVisualizerPreset {
const bands = logBands(count);
let surface: CanvasSurface | null = null;
return {
mount: (target) => {
surface = createCanvasSurface(target);
},
draw(frame: AudioFrame) {
const canvas = surface as CanvasSurface;
const { context, width, height } = canvas;
canvas.clear();
context.fillStyle = canvas.resolveColor('--primary');
bands.forEach((band, index) => {
const level = bandPeak(frame.frequency, frame.sampleRate, frame.fftSize, band);
const radius = 2 + level * (height / 2 - 2);
context.beginPath();
context.arc(((index + 0.5) * width) / count, height / 2, radius, 0, Math.PI * 2);
context.fill();
});
},
rest: () => surface?.clear(),
destroy() {
surface?.destroy();
surface = null;
},
};
}rest() can run on a preset that was never mounted, which is why it and destroy() check the surface and draw() does not.
Rules for a preset that stays smooth:
- Theme through custom properties. Take colors with
surface.resolveColor('--primary')(or any token), once per frame, never as a hard-coded color: a theme or light and dark change then shows on the next frame. A property that is not defined falls back to the canvas's text color. - Reduced motion. The controller reports
reducedand never callsdraw(); it callsrest(). Makerest()a static look you are happy to leave on screen, as theidle: 'floor'option of the canvas bars does. - Allocate nothing per frame. Build arrays and objects in the factory or in
mount, and reuse them indraw(), asstepPeakwrites into a peak object. - Read no layout in
draw(). Take the size fromsurface.widthandsurface.height, never fromgetBoundingClientRect()orclientWidth, and read a color once per frame at most. - Clean up completely.
destroy()undoesmount, andsetPresetmay mount the same object again.
Swap presets while the media plays with visualizer.setPreset(preset): the old preset is rested and destroyed, the new one is mounted and draws from the next frame.
To share presets, publish a package that exports a factory returning an AudioVisualizerPreset (export function spectrum(options): AudioVisualizerPreset), imports only from @ecopages/radiant-ui/controllers, and lists @ecopages/radiant-ui as a peer dependency. The naming convention is radiant-visualizer-<name>. There is no preset registry and no lookup by name: the host imports the factory and passes the result to preset or setPreset.
Not stable yet: AudioFrame may gain fields (a timestamp, for example), mount may receive options, and the signatures of stepPeak, segmentBounds and the onResize argument of createCanvasSurface may change in a minor release. A preset that uses only the fields and the lifecycle above is the safest to write.
Accessibility
The visualization is decorative. The controller and the presets set no ARIA, and a canvas they create is aria-hidden="true". Do not put text in an element a canvas preset mounts into: the canvas is hidden from assistive technology, and the text would not be. What you provide: the player controls and their labels, and any live region or text that announces playback state. With prefers-reduced-motion: reduce the controller starts no loop and no graph, and the preset stays at rest. It follows a change of the preference while attached.
Protected hooks
None. Change behavior through the config callbacks and by writing a preset.