pnpm add @audio-ui/core
import { createPpmBallistics, createVuBallistics, FLOOR_DB, iecDeflection, levelPosition, /* … */ } from "@audio-ui/core/meter";| Adapters | @audio-ui/react/meter, @audio-ui/elements/meter |
|---|
| Export | Kind | What it is |
|---|---|---|
createPpmBallistics | function | A PPM meter: it rises in attackSeconds, a time constant, and falls at a steady releaseDbPerSecond, so a peak reads long enough to be seen. |
createVuBallistics | function | A VU meter: its pointer follows the voltage of the level as a mass on a spring does, symmetrically, taking riseSeconds to first reach 99% of a step and overshooting it by 1.3%, as the standard says. |
FLOOR_DB | const | The lowest reading a meter shows, in dB: below it the level is silence. |
MeterBallistics | interface | How a meter's reading follows the level it measures, over time. |
iecDeflection | function | The deflection of an IEC 60268-18 style digital peak meter, from 0 at -70 dB to 100 at 0 dB: each stretch of the scale gets more room than the one below, so the top 20 dB take half the length. |
LevelScale | type | How a level in dB is spread along the meter's length: evenly, or the way digital peak meters spread it, with room at the top where it matters. |
LevelScaleFunction | type | A custom curve: any increasing function of the level, rescaled to the meter's range. |
levelPosition | function | A function from a level to its position along the length, 0 at min and 1 at max. |
vuDeflection | function | The deflection of a VU meter's pointer. |
channelView | function | What a channel shows for its reading in frame: the length of its bar, its peak mark, whether it warns or clips, and its text. |
createMeterConfig | function | Builds the config a meter reads its levels with: the position along its length, and how levels are written. |
DEFAULT_METER_FORMAT | const | Levels read to one decimal: finer than a meter can be read, and a plain number rather than a share of the range. |
MeterChannelNodes | interface | The DOM nodes of one channel that a live source writes to. |
MeterChannelPart | type | A part of a channel that a live source writes to. |
MeterChannelView | interface | What one channel shows for a level: everything both the React render and the per-frame DOM writes derive from. |
MeterConfig | interface | What createMeterConfig returns: the range, the warning and clipping levels, the position of a level along the meter, and how a level is written. |
MeterFrame | interface | One reading of the meter: a level per channel, and optionally a peak-hold level per channel. |
MeterOrientation | type | Which way a meter's bars run. |
paintChannel | function | Write one channel's view straight to its nodes, touching only what changed. |
setPresence | function | Sets attribute on node as an empty attribute, or removes it. |
Usage
A meter has no gesture, so it has no controller. What it has is a scale, ballistics and a channel to paint.
The scale
createMeterConfig holds how levels are placed and written: min, max, warnThreshold, clipThreshold, and scale, which is "iec" (the deflection of a digital peak meter, with room at the top), "linear", or a function. position(level) gives a level's place on the meter, from 0 to 1:
import { createMeterConfig } from "@audio-ui/core/meter";
const config = createMeterConfig({ min: -60, max: 6, scale: "iec", clipThreshold: 0 });
config.position(-18); // 0.467iecDeflection and vuDeflection are the two standard curves on their own, and levelPosition(scale, min, max) makes the function position is.
Ballistics
The levels come from a live source, and the meter has no clock of its own, so how a reading moves is yours to choose. A ballistic follows a level frame by frame:
import { createPpmBallistics, createVuBallistics } from "@audio-ui/core/meter";
const vu = createVuBallistics(); // 300 ms to reach 99% of a step, overshooting it by 1.3%
const ppm = createPpmBallistics(); // a 5 ms attack, then a fall of 20 dB in 1.5 s
const reading = vu.step(levelDb, elapsedSeconds);step(level, seconds) moves the reading toward a level over a frame and returns it; reset(value) puts it somewhere at once. Below FLOOR_DB a reading is silence.
Painting a channel
channelView(frame, index, config) is what a channel shows for a reading: the length of its bar, its peak mark, whether it is at the warning level or clipping, and its text. paintChannel(nodes, view, index, orientation) writes that straight to the channel's DOM nodes, touching only what changed, so a meter repaints every frame with no render of its framework.
The Meter draws these in React.