npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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-module

ESM 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();
  • start doubles as a source switch: the old source keeps going until the new one is ready, and a failed start changes nothing. stop() is idempotent; dispose() is final.
  • createAudio({ bandCount }) sets the length of bands and bandOnsets (default 3).
  • bandOnsets[i] is { strength, count } for band i (low to high): the same as onset, but detected within that band's frequency range alone. Each band is an independent detector: a rise confined to the low end can fire bandOnsets[0] without firing onset, and onset.count is 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 by trim and release; counts never reset, not on stop/start nor 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 on level and bands, default 1) and audio.release (time constant of the fall, in seconds, default 0.25) are settable at any time.
  • audio.hold (default false) freezes auto-gain: while true, the noise floor and peak of level and 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. level and bands still follow the sound, against the frozen auto-gain; turning hold off resumes adapting from where it stopped. Held auto-gain survives a switch and a stop followed by a start: 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). Without hold, both start auto-gain afresh. A first start with hold already on sets auto-gain on its first read, which then stays frozen. Only dispose discards held auto-gain. Onsets and no-signal are 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 and no-signal are unaffected.
  • audio.devices() lists inputs after the first live start; audio.settings holds 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 unsubscribe

Failures 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-module

The consumer's package.json keeps the published semver range.

License

MIT