# format

> 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.

```bash
npm install @audio-ui/engine
```

```ts
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`.

```ts
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:

```ts
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
```