Audio quantities as text from @audio-ui/engine, the way the standards and the tools write them: levels in dBFS, dBTP and LUFS, frequencies and sample rates, times, notes, pans, ratios, tempos, channel layouts, each a function of the value and options, and createFormatter to bind a locale, a true minus or a spacing once.
pnpm add @audio-ui/engine
import { formatLevel, formatFrequency, formatSampleRate, formatTime, formatDuration, /* … */ } from "@audio-ui/engine/format";| Export | Kind | What it is |
|---|---|---|
FormatOptions | interface | What every formatter takes, over its own defaults. |
LevelUnit | type | The units of a level: decibels of a gain, of full scale, of a true peak, of a voltage; loudness in LUFS and its range in LU. |
formatLevel | function | A level or a gain: -6.0 dBFS, -23.0 LUFS, +3.0 dB, -1.0 dBTP. |
FrequencyStyle | type | How a frequency is written: by size (auto), always in hertz, or always in kilohertz. |
formatFrequency | function | A frequency: 120 Hz, 1.2 kHz, 12 kHz. |
formatSampleRate | function | A sample rate: 44.1 kHz, 48 kHz, 11.025 kHz: in kilohertz, with the places it needs and no more. |
TimeStyle | type | How a time is written: a clock to the second, a clock to the millisecond, or a length in seconds. |
formatTime | function | A time: 1:05 (clock), 1:05.250 (precise, to the millisecond, with hours past an hour: 1:02:03.500), or 65.25 s (seconds). |
formatDuration | function | A length of time by its size: 120 ms under a second, 1.25 s above. |
formatTempo | function | The tempo, 120 BPM, with a decimal only when it has one. |
NoteOptions | interface | How a note is spelled: sharps or flats, the octave of the middle C (4 in scientific pitch, 3 on Yamaha's), and the typographic ♯ and ♭ or plain # and b. |
formatNote | function | A MIDI note as a name: 60 is C4, 61 C#4, 69 A4. |
PanStyle | type | How a pan is written: L30, C, R30 (lr), or a signed number, -30, 0, +30 (signed). |
formatPan | function | A pan from -1 (left) to 1 (right) as a percentage of the way: L50, C, R100. |
formatPercent | function | A share as a percentage. |
formatRatio | function | A compressor's ratio: 4.0:1, and ∞:1 for a limiter. |
formatChannels | function | The layout of a sound by its channel count: mono, stereo, quad, 5.1, 7.1; any other count as N ch. |
Formatter | interface | The formatters of this module with options bound: each call may still override them. |
createFormatter | function | A set of formatters that share their options: a locale, a true minus, a thin space, a note spelling. |
Usage
Each quantity is one function, with the unit it is written in and the conventions of the field built in: a number and its unit apart by a space (SI, ISO 80000), one decimal for a level (EBU R128, ITU-R BS.1770), kHz with a small k, m:ss.mmm for a time, a middle C of C4.
import {
formatChannels,
formatFrequency,
formatLevel,
formatNote,
formatPan,
formatSampleRate,
formatTime,
} from "@audio-ui/engine/format";
formatLevel(-23, "LUFS"); // "-23.0 LUFS"
formatLevel(-1.04, "dBTP"); // "-1.0 dBTP"
formatLevel(3, "dB"); // "+3.0 dB": a gain carries its sign, a level does not
formatLevel(Number.NEGATIVE_INFINITY, "dBFS"); // "-∞ dBFS"
formatFrequency(1200); // "1.2 kHz"
formatSampleRate(44_100); // "44.1 kHz"
formatTime(65.25, "precise"); // "1:05.250"
formatNote(61); // "C#4"
formatPan(-0.3); // "L30"
formatChannels(6); // "5.1"Options
Every function takes the same options last, over its own defaults:
| Option | What it does |
|---|---|
decimals | The places. A trailing zero is kept, so a column lines up. |
locale | The decimal mark: "fr" writes a comma. A point by default, whatever the browser's locale. |
minus | "unicode" writes the typographic minus U+2212 in place of the hyphen. |
space | What goes between the number and its unit: " " a narrow no-break space, "" none. |
sign | Whether a positive carries a +. |
unit | false writes the number alone, for a scale or a column that says the unit once. |
One set of defaults
createFormatter binds the options you always want, so a product writes its quantities one way everywhere:
import { createFormatter } from "@audio-ui/engine/format";
const format = createFormatter({ locale: "fr", minus: "unicode" });
format.level(-23, "LUFS"); // "−23,0 LUFS"
format.frequency(1500); // "1,5 kHz"
format.time(1.5, "precise"); // "0:01,500"
format.level(-23, "LUFS", { locale: "en" }); // a call can still override