Getting Started
soundhub is a TypeScript library that wraps the Web Audio API in a single
SoundHub class. It handles loading, playback, volume, fading, panning, spatial
positioning, sprites, groups and events, without you having to wire up audio
nodes by hand. It also ducks music under a voice and varies repeated sounds.
The main package is 23 KB gzipped and has no dependencies. Two optional entry
points sit next to it: soundhub/ui with interface sounds that need no files
(1.5 KB), and soundhub/howler, which runs Howler.js code on soundhub (3.7 KB).
Coming from Howler.js? Start with Migrating from Howler.js.
Every method on the interface has its own page in this documentation. Use the sidebar to browse by topic, or the search box in the header to jump straight to a method.
Installation
npm install soundhub
yarn add soundhub
Your first sound
import { SoundHub, SoundEventsEnum, type SoundEvent } from 'soundhub';
const soundHub = new SoundHub();
soundHub.addEventListener(SoundEventsEnum.LOADED, (event: SoundEvent) => {
console.log('Sound loaded', event);
});
await soundHub.loadSounds([{ id: 'music', url: '/sounds/music.mp3' }]);
soundHub.play('music');
Most browsers suspend the audio context until the visitor clicks, taps or presses a key.
Trigger your first play() from a real user action, or call
resumeContext once the visitor interacts with the page.
Where to go next
Try it live
Want to hear it before you install anything? The live demo lets you play with volume, panning, fading, sprites and spatial audio in the browser.
Many pages in this documentation also carry a Try it section with a working
player, so you can hear what a method does while you read about it. Start with
play or fadeIn.
New in 6.5.0
| What | Where |
|---|---|
Turn music down while a voice plays, with duck('music', { when: 'voice' }) | Ducking · duck |
| Several takes under one name, with a pitch and volume spread | Variations · createVariations |
Add an AudioBuffer you already have as a sound | addBuffer |
soundhub/ui: twelve interface sounds rendered in the browser | Interface sounds |
soundhub/howler: the Howler.js API on a shared hub | Migrating from Howler.js |
Two new events, duck_started and duck_ended, for 40 in all | soundEvents |
New in 6.4.0
| What | Where |
|---|---|
| Every time is a position in the file, at any playback rate, for buffered sounds and streams alike | getCurrentTime · seek |
| A muted sound stays muted when you play it again | mute · toggleMute |
defaultVolume and defaultPan apply to each sound, not a second time to the master | SoundHubConfig |
| Eight more fixes, among them playing again after a fade to silence and a rate change without an event | Changelog |
New in 6.3.0
| What | Where |
|---|---|
Types that work with moduleResolution node16 and nodenext, and a CommonJS build for require() | Changelog |
| Hover text in your editor for every method and option | SoundHubConfig · PlayOptions |
| Ten fixes, among them muting twice, fading out a stream and playing again after a seek | Changelog |
New in 6.2.0
| What | Where |
|---|---|
overlap, the new name for createNewInstance | PlayOptions |
| A list of urls per sound, so the browser picks the format | loadSound · canPlay |
| Register a sound now, fetch it later | registerSound · getLoadState |
| A listener you can move through the scene | setListenerPosition |
| Sounds that point somewhere, for the cone settings | setSpatialOrientation |
| Request headers, an idle timeout and an instance ceiling | SoundHubConfig |