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.

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');

Browsers block audio until the user interacts

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

Topic	Start here
⏯️ Playback	play · pause · stop · seek
🎛️ All sounds at once	stopAllSounds · pauseAllSounds
🔊 Volume & mute	setSoundVolume · setGlobalVolume · toggleMute
🌗 Fading	fadeIn · fadeOut
🔁 Looping & playback rate	setLoop · setPlaybackRate
📥 Loading sounds	loadSounds · loadSound
📊 State & progress	isPlaying · getProgress · startProgressTracking
🎚️ Pan & balance	setPan · setGlobalPan
🎯 Spatial audio	setSpatialPosition · isSpatialAudioSupported
🎶 Sound sprites	Sound sprites · setSoundSprite
👥 Sound groups	createSoundGroup · addToSoundGroup
🎧 Audio context & nodes	resumeContext · getMasterOutput
🛡️ Master limiter	Master limiter · setMasterLimiter
📡 Events	addEventListener · SoundEvent
🔄 Reset & cleanup	reset · destroy
🔧 Utilities	getConfig · setDebugMode
📘 Types & Interfaces	PlayOptions · SoundHubConfig

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.