Skip to main content

Interface: VisualizerOptions

Defined in: packages/player/src/visualizer.ts:37

Tuning for VisualizerController.subscribe.

Properties​

attack?​

readonly optional attack?: number;

Defined in: packages/player/src/visualizer.ts:105

Smoothing coefficient applied when a band rises, in (0, 1]. Higher is snappier. Default 0.65.

autoGain?​

readonly optional autoGain?: boolean;

Defined in: packages/player/src/visualizer.ts:100

Track the programme level and shift the dB window to follow it. Default false.

Remarks​

The other opt-in display aid, and off for the same reason: with it on, bar height stops meaning a level and starts meaning "loud relative to how loud this has been lately", which is not a representation of the audio. Turn it on when you would rather a quiet recording still filled the display than have the display tell the truth about it.

When on it is bounded (-6 to +18 dB), backs off four times faster than it builds, and holds still below AGC_SILENCE_DB so it can never amplify a noise floor into a full-height display. VisualizerFrame.gainDb always reports what it is doing.

bands?​

readonly optional bands?: number;

Defined in: packages/player/src/visualizer.ts:44

Number of log-spaced output bands. Default 32.

fftSize?​

readonly optional fftSize?: number;

Defined in: packages/player/src/visualizer.ts:52

Transform length in samples; a power of two. Default 2048.

Bigger means finer frequency resolution (2048 at 48 kHz is ~23 Hz per bin) and a longer window, so transients smear a little more. 1024 is snappier, 4096 resolves bass better.

fps?​

readonly optional fps?: number;

Defined in: packages/player/src/visualizer.ts:42

Frames per second. Default DEFAULT_VISUALIZER_FPS (30), clamped to VisualizerCapabilities.maxFps (60).

maxDb?​

readonly optional maxDb?: number;

Defined in: packages/player/src/visualizer.ts:68

Band power in dBFS mapped to 1. Default -10.

maxHz?​

readonly optional maxHz?: number;

Defined in: packages/player/src/visualizer.ts:72

Highest band edge in Hz, clamped to Nyquist. Default 16000.

minDb?​

readonly optional minDb?: number;

Defined in: packages/player/src/visualizer.ts:66

Band power in dBFS mapped to 0. Default -40.

These are true dBFS: the native transform is calibrated so a full-scale sine reads exactly 1.0 (0 dBFS), which the C++ suite asserts against a real transform. The default window is the one place this module makes a choice about presentation, because a dB axis has to start somewhere — and it was chosen by measurement, not taste. On a modern commercial master (48 kHz AAC, 2048-point transform, 20 log bands) the quiet bands measure around -35 dBFS and the loud ones around -17, so a -40…-10 window puts real content across the height with headroom left for transients. Nothing else is applied by default: no tilt, no gain, no cosmetic curve.

minHz?​

readonly optional minHz?: number;

Defined in: packages/player/src/visualizer.ts:70

Lowest band edge in Hz. Default 32.

peakGravity?​

readonly optional peakGravity?: number;

Defined in: packages/player/src/visualizer.ts:119

How fast a peak-hold cap accelerates downward, per frame. Default 0.004.

This is gravity, not a decay rate: the cap hangs still for peakHoldFrames, then falls with an accelerating velocity, which is the classic Winamp ballistic. A plain exponential decay droops instead of dropping and reads as sluggish.

peakHoldFrames?​

readonly optional peakHoldFrames?: number;

Defined in: packages/player/src/visualizer.ts:124

Frames a peak cap hangs at its high-water mark before it starts to fall. Default 15 (half a second at the default 30 fps).

release?​

readonly optional release?: number;

Defined in: packages/player/src/visualizer.ts:110

Smoothing coefficient applied when a band falls, in (0, 1]. Lower decays more slowly. Default 0.12.

tiltDbPerOctave?​

readonly optional tiltDbPerOctave?: number;

Defined in: packages/player/src/visualizer.ts:83

Spectral tilt in dB per octave, referenced to 1 kHz. Default 0.

An opt-in display aid, off by default because the default has to be the real spectrum. Music's power falls at roughly 3 dB per octave (which is why "pink" noise, not white, sounds even), so 3 flattens that slope and makes the top of the display as active as the bottom. It is a lie about the audio, told deliberately — useful for a decorative bar display, wrong for anything you would read a number off.

waveform?​

readonly optional waveform?: boolean;

Defined in: packages/player/src/visualizer.ts:129

Also deliver time-domain samples. Default false — it doubles the per-frame payload, and a bar visualiser does not need it.