API Reference / Reading
Type Alias: Reading
ts
type Reading = {
bpm: number;
bpmExact: number;
confidence: number | null;
candidates: readonly Candidate[];
audio: AudioSpan;
engine: EngineName;
};Defined in: contract/types.ts:199
One measurement: the tempo the engine reports for a span of audio.
Remarks
The same type in realtime and offline, whichever engine runs: every field means the same thing in all four. A reading is a measurement, not a state. Whether the analyzer trusts it is state.status.
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
bpm | readonly | number | The reported tempo, in BPM, inside tempoRange. Always equal to candidates[0].bpm. Other candidates may fall outside the range: a half or double often does. | contract/types.ts:204 |
bpmExact | readonly | number | The same tempo unrounded, in BPM: the engine's own estimate before it is rounded to bpm. For timing, not for display. A beat grid or a marker export laid on bpm drifts: a real 127.6 BPM shown as 128 puts the markers about 0.56 s off after 3 minutes. Lay the grid on 60 / bpmExact seconds instead, and keep showing bpm. Each engine measures it, never derives it from bpm: peaks takes the vote-weighted mean of the unrounded interval tempos within 1 BPM of bpm, and tempogram the interpolated top of its tempo curve. So it is within 1.5 BPM of bpm, and Math.round(bpmExact) can differ from bpm by one when the peaks votes straddle two whole numbers: bpm is the whole number with the most votes, not a rounding of bpmExact. | contract/types.ts:215 |
confidence | readonly | number | null | The chance, 0 to 1, that bpm is within 4% of the true tempo right now: 0.8 is right about 80% of the time. Each engine's raw score (peaks the share of interval votes within ±1 BPM, tempogram its accumulated salience) goes through that engine's table in core/calibration.ts, so on the default range values from either engine, realtime or offline, mean the same thing. A reading at half or double the tempo counts as wrong. Fitted on the benchmark's dev half (benchmark/results/rba-106-calibration-dev.md), then checked once on the real-time readings of its held-out half, which it had not seen: the tempogram's table held there (benchmark/results/rba-106-calibration-heldout-verdict.md). Offline readings were not part of that check. Peaks' table was fitted on dev only. Treat the values as an estimate for music like the benchmark's. null: unmeasured, when bpm is outside 90 to 180 or when the analysis ran on a custom tempo range. Both halves were read by analyses on the default range, 90 to 180 BPM, so the calibration says nothing about any other: a custom range changes which candidate each engine picks, so even a reading inside 90 to 180 BPM from a 60 to 200 analysis has a score nobody measured. The confidence is then null rather than a number with no proven meaning. On the default range it is always a number, and an explicit {min: 90, max: 180} is the default range. | contract/types.ts:233 |
candidates | readonly | readonly Candidate[] | At most 5, candidates[0] first with relation top, the rest in the engine's rank order, each labelled with its CandidateRelation to the top tempo. Never empty. | contract/types.ts:238 |
audio | readonly | AudioSpan | - | contract/types.ts:239 |
engine | readonly | EngineName | - | contract/types.ts:240 |