SoundHubConfig

SoundHubConfig defines the options you pass when creating a SoundHub. Every option is optional; anything you leave out falls back to the default below.

const soundHub = new SoundHub({
  defaultVolume: 0.8,
  masterLimiter: true,
  debug: true,
});

Try it

Change the configuration and create a manager with it. Each option below is applied to a freshly created SoundHub, so you can hear the difference immediately.

No manager created yet

Note: each run creates a brand new SoundHub and destroys the previous one, which is exactly what the config affects. Options that only apply while loading, such as fetchRetries, will not be audible here.

Playback defaults

These set the starting point for every sound you load. Individual calls to play() can still override them through PlayOptions.

Property	Type	Default	Description
`defaultVolume`	`number`	`1`	Starting volume for new sounds (0 to 1)
`defaultPlaybackRate`	`number`	`1`	Starting playback rate
`defaultStartTime`	`number`	`0`	Offset in seconds where playback begins
`defaultDuration`	`number`	`undefined`	How long to play, in seconds. Undefined plays the full sound
`defaultPan`	`number`	`0`	Stereo pan, -1 (left) to 1 (right)
`defaultPanType`	`SoundPanType`	`Stereo`	Stereo or spatial panning, see `SoundPanType`
`defaultPanSpatialPosition`	`{ x, y, z }`	`{ x: 0, y: 0, z: 0 }`	Starting 3D position
`fadeInDuration`	`number`	`0.5`	Default fade-in length in seconds
`fadeOutDuration`	`number`	`0.5`	Default fade-out length in seconds
`loopSounds`	`boolean`	`false`	Loop every sound by default
`maxLoops`	`number`	`-1`	Number of loops when looping. `0` or `-1` is infinite
`createNewInstance`	`boolean`	`false`	Let each `play()` create an independent instance, so the same sound can overlap with itself
`trackProgress`	`boolean`	`true`	Emit `PROGRESS` events during playback

Output

Property	Type	Default	Description
`masterLimiter`	`boolean`	`false`	Insert a limiter before the output so overlapping sounds cannot clip. See Master Limiter
`spatialAudio`	`boolean`	`true`	Enable 3D spatial audio features, when the browser supports them
`pannerNodeConfig`	`SoundPannerConfig`	see below	Distance and cone settings for 3D sound, see Spatial Audio

tip

masterLimiter is off by default so that upgrading never changes how an existing project sounds. Turn it on when you play several sounds at the same time, such as a playable instrument or a busy game scene.

Loading

Property	Type	Default	Description
`webAudioPreferred`	`boolean`	`true`	Prefer the Web Audio API over the HTML5 audio fallback
`html5AudioFallback`	`boolean`	`true`	Fall back to an `Audio` element when Web Audio loading fails
`maxParallelLoads`	`number`	`10`	How many sounds to fetch at the same time
`retryDelay`	`number`	`0.5`	Delay between retry attempts, in seconds
`audioCache`	`boolean`	`true`	Allow the browser to cache the fetched audio
`maxAudioSize`	`number`	`52428800`	Refuse files larger than this, in bytes (50 MB)

Network

Property	Type	Default	Description
`fetchRetries`	`number`	`2`	Retries per failed fetch
`fetchTimeout`	`number`	`8`	Fetch timeout in seconds
`corsProxy`	`string`	`undefined`	URL of a CORS proxy for cross-origin audio
`fetchStrategy`	`'direct-first' \| 'proxy-first' \| 'direct-only'`	`'direct-first'`	Whether to try the direct URL or the proxy first
`crossOrigin`	`'anonymous' \| 'use-credentials' \| null`	`null`	`crossOrigin` attribute for the HTML5 fallback
`credentialStrategy`	`'auto' \| 'omit' \| 'include'`	`'auto'`	Which credentials mode to fetch with

Mobile and page lifecycle

Property	Type	Default	Description
`autoUnlock`	`boolean`	`true`	Unlock audio on the first user gesture, needed on mobile browsers
`autoMuteOnHidden`	`boolean`	`true`	Mute when the tab goes to the background
`autoResumeOnFocus`	`boolean`	`true`	Unmute when the tab becomes visible again

Debugging

Property	Type	Default	Description
`debug`	`boolean`	`false`	Log what the sound manager is doing to the console

Reading the configuration back

getConfig() returns the merged configuration, so you see the defaults as well as your own values:

const soundHub = new SoundHub({ defaultVolume: 0.8 });

const config = soundHub.getConfig();

console.log(config.defaultVolume);  // 0.8, your value
console.log(config.maxParallelLoads); // 10, the default
console.log(config.masterLimiter);  // false, the default

The returned object is a copy, so changing it does not affect the manager. Use the dedicated methods instead:

soundHub.setDebugMode(true);
soundHub.setGlobalVolume(0.5);
soundHub.setMasterLimiter(true);
soundHub.setProgressUpdateInterval(100);

Try it​

Playback defaults​

Output​

Loading​

Network​

Mobile and page lifecycle​

Debugging​

Reading the configuration back​

Related​