@sr-labs/audio-module
v0.4.0
Published
Browser audio input and live feature extraction as a per-frame pull snapshot. Framework-free.
Readme
@sr-labs/audio-module
Browser audio input and live feature extraction, exposed as a pull reading: level, low-to-high
bands, onset (strength and a never-resetting count), bandOnsets (the same, one per band) and status, all numbers in [0, 1]. Framework-free: no
three.js, no app vocabulary. Part of the @sr-labs packages.
Sources: live input (getUserMedia) and a local audio file.
Install
pnpm add @sr-labs/audio-module # or npm i @sr-labs/audio-moduleESM only, ships its own .d.ts. Runs in the browser: live input needs a secure context (https:// or
localhost) and start needs a user gesture.
Usage
import { createAudio } from '@sr-labs/audio-module';
const audio = createAudio(); // no side effects until start()
// Inside a user gesture (a click):
await audio.start({ kind: 'live' }); // or { kind: 'live', deviceId }, or { kind: 'file', file }
// Every read. One reused object: do not hold it past the next read.
const { level, bands, onset, bandOnsets, status } = audio.read();startdoubles as a source switch: the old source keeps going until the new one is ready, and a failedstartchanges nothing.stop()is idempotent;dispose()is final.createAudio({ bandCount })sets the length ofbandsandbandOnsets(default 3).bandOnsets[i]is{ strength, count }for bandi(low to high): the same asonset, but detected within that band's frequency range alone. Each band is an independent detector: a rise confined to the low end can firebandOnsets[0]without firingonset, andonset.countis not the sum of the band counts. Strength is in [0, 1] for the read that found it and 0 on every other read, untouched bytrimandrelease; counts never reset, not onstop/startnor a switch. With the default 3 bands,bandOnsets[0]covers roughly 30-240 Hz, the low end. The more bands, the narrower each one, and the noisier its onsets.audio.trim(linear display gain onlevelandbands, default 1) andaudio.release(time constant of the fall, in seconds, default 0.25) are settable at any time.audio.hold(defaultfalse) freezes auto-gain: while true, the noise floor and peak ofleveland of every band stand still, so a quiet passage after a loud one stays low and a steady sound keeps reading instead of fading to zero.levelandbandsstill follow the sound, against the frozen auto-gain; turningholdoff resumes adapting from where it stopped. Held auto-gain survives a switch and astopfollowed by astart: the next source is read against the same floor and peak (a much hotter or quieter source reads high or low until you release hold). Withouthold, both start auto-gain afresh. A firststartwithholdalready on sets auto-gain on its first read, which then stays frozen. Onlydisposediscards held auto-gain. Onsets andno-signalare unaffected.audio.adaptation(default 1, settable at any time) is how fast auto-gain follows the sound: 2 is twice as fast, 0.5 half as fast, 0 never lets the floor rise or the peak sink (the floor still drops at once to a quieter sound). Non-finite values are ignored and negatives become 0. Onsets andno-signalare unaffected.audio.devices()lists inputs after the first livestart;audio.settingsholds the effective capture settings.
Status
| Status | Meaning |
| ----------- | -------------------------------------------------------------- |
| idle | Not started, stopped, or a start was rejected. |
| starting | The first start is pending; a switch skips it. |
| running | Analysing a source. |
| no-signal | Running, but silent for 2 seconds; back to running on sound. |
| muted | The live track was muted by the browser or the device. |
| suspended | The AudioContext is not running (for example, tab policy). |
| ended | The source stopped existing: the device disconnected, or the file failed to decode. |
When several hold at once, the status is the first of ended, suspended, muted, then no-signal or
running: a track still muted when the context resumes reads muted, not running.
An ended source always comes with an error saying why (disconnected or decode); the values decay to zero
and nothing reconnects by itself. The module only
analyses when read, so no-signal begins and ends on a read(): a consumer that stops reading (a hidden tab)
gets no status change until it reads again.
Events and errors
const off = audio.on('status', (status) => {});
audio.on('devices', (devices) => {});
audio.on('error', (error) => console.warn(error.code));
off(); // every `on` returns its unsubscribeFailures reject start with an AudioInputError whose code is one of insecure-context, unsupported,
not-allowed, needs-gesture, not-found, unavailable, decode or aborted, and the same error goes to
audio.on('error', …) — except aborted, which is expected and never reported. A running source that ends
emits disconnected (a live device unplugged, or access withdrawn) or decode (a file that stops decoding) on
audio.on('error', …) only.
not-allowed means microphone access was refused; needs-gesture means the browser blocked a file because
start was not called from a user gesture, and retrying from a click works. not-found means there is no input
device at all; unavailable means a device exists but could not be opened (busy in another application, or
failing as the browser opens it). A deviceId is a hint: if that device is gone, the browser picks another,
and audio.settings.deviceId says which. isAudioError(value) narrows an unknown value to it.
Testing against it
import { createFakeAudio } from '@sr-labs/audio-module/testing';
const audio = createFakeAudio();
audio.setReading({ level: 0.8, bands: [0.9, 0.2, 0.1] });
audio.bumpOnset();
audio.bumpBandOnset(0); // band onset: count + 1, strength 1 (RangeError outside bandCount)
audio.setReading({ bandOnsetStrengths: [1, 0, 0] });
audio.rejectNextStart('not-allowed');The fake follows the same rules as the real module (one reused reading, a switch skips starting, a
rejected start changes nothing) and records what it was asked to do (starts, stops, disposed).
Versioning
Semver, 0.x until the contract is proven in a consumer. While 0.x, a minor bump may change the contract, so
pin with ~0.1.0. Releases are git tags vX.Y.Z.
Developing
pnpm install
pnpm test # vitest: analysis maths, lifecycle against a fake browser
pnpm typecheck
pnpm build # ESM + .d.ts in dist/The analysis (src/analysis.ts) is pure and tested with synthetic spectra; the lifecycle (src/createAudio.ts)
takes the browser through an injectable environment, so it is tested without one.
To try a change in a consumer, link it locally without committing the link:
pnpm build
cd ../<consumer> && pnpm link ../audio-moduleThe consumer's package.json keeps the published semver range.
