SoundHubConfig

The options you pass when you create a SoundHub. Every option is optional. Anything you leave out gets the default from DEFAULT_CONFIG, which soundhub exports as well.

export interface SoundHubConfig {
  autoUnlock?: boolean;
  autoMuteOnHidden?: boolean;
  autoResumeOnFocus?: boolean;
  autoSuspend?: boolean;
  autoSuspendDelay?: number;
  /** @deprecated Renamed to `overlap`. Still honoured, and removed in v7. `overlap` wins when both are set. */
  createNewInstance?: boolean;
  overlap?: boolean;

  // Loading
  webAudioPreferred?: boolean;
  html5AudioFallback?: boolean;
  maxParallelLoads?: number;
  retryDelay?: number;
  fetchHeaders?: Record<string, string>;
  fetchRetries?: number;
  fetchTimeout?: number;
  corsProxy?: string;
  fetchStrategy?: 'direct-first' | 'proxy-first' | 'direct-only';
  maxAudioSize?: number;
  audioCache?: boolean;
  crossOrigin?: "anonymous" | "use-credentials" | null;
  credentialStrategy?: 'auto' | 'omit' | 'include';

  maxInstancesPerSound?: number;
  masterLimiter?: boolean;

  debug?: boolean;
  /** @deprecated Never read by the hub. Set `duration` in the play options instead. Removed in v7. */
  defaultDuration?: number;
  defaultPan?: number;
  defaultPanSpatialPosition?: { x: number; y: number; z: number };
  defaultPanType?: SoundPanType;
  defaultPlaybackRate?: number;
  defaultStartTime?: number;
  defaultVolume?: number;
  fadeInDuration?: number;
  fadeOutDuration?: number;
  loopSounds?: boolean;
  maxLoops?: number;
  pannerNodeConfig?: SoundPannerConfig;
  spatialAudio?: boolean;
  trackProgress?: boolean;
}

The source carries a doc comment on every field; they are left out here and summed up in the tables below.

Playback defaults

These set the starting values of every sound you load. A single play() call can still override them through PlayOptions.

Property	Type	Default	Description
`defaultVolume`	`number`	`1`	Volume for new sounds, 0 to 1. Clamped to that range. Also sets the starting global volume, see Good to know.
`defaultPlaybackRate`	`number`	`1`	Playback rate for new sounds.
`defaultStartTime`	`number`	`0`	Second to start new sounds from.
`defaultPan`	`number`	`0`	Stereo pan for new sounds, `-1` (left) to `1` (right). Also sets the starting global pan.
`defaultPanType`	`SoundPanType`	`SoundPanType.Stereo`	Stereo or spatial panning for new sounds.
`defaultPanSpatialPosition`	`{ x, y, z }`	`{ x: 0, y: 0, z: 0 }`	3D position for new sounds.
`fadeInDuration`	`number`	`0.5`	Seconds for `fadeGlobalIn` when you give no duration. A negative value becomes `0`.
`fadeOutDuration`	`number`	`0.5`	Seconds for `fadeOut` and `fadeGlobalOut` when you give no duration. A negative value becomes `0`.
`loopSounds`	`boolean`	`false`	Loop new sounds.
`maxLoops`	`number`	`-1`	How many times a looping sound plays. `0` or `-1` loops forever.
`overlap`	`boolean`	`false`	Let every `play()` start an independent instance, so a sound can overlap itself instead of restarting. Called `createNewInstance` before 6.2.0; the old name still works.
`maxInstancesPerSound`	`number`	`0`	Most instances of one sound that may play at once. Reaching it stops the oldest. `0` is no ceiling.
`trackProgress`	`boolean`	`true`	Dispatch `progress` events while a sound plays, for a seek bar or a timer.
`defaultDuration`	`number`	`undefined`	Deprecated and never read. Set `duration` in the play options instead.

Output

Property	Type	Default	Description
`masterLimiter`	`boolean`	`false`	Put a limiter just before the output so many sounds at once cannot clip. See Master Limiter.
`spatialAudio`	`boolean`	`true`	Enable spatial audio. Turned off automatically when the browser does not support it.
`pannerNodeConfig`	`SoundPannerConfig`	`DEFAULT_PANNER_CONFIG`	Distance and cone settings for 3D sound, see below and Spatial Audio.

DEFAULT_PANNER_CONFIG is:

Field	Default
`panningModel`	`PanningModel.HRTF`
`distanceModel`	`DistanceModel.Inverse`
`refDistance`	`1`
`maxDistance`	`10000`
`rolloffFactor`	`1`
`coneInnerAngle`	`360`
`coneOuterAngle`	`360`
`coneOuterGain`	`0`

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`	Decode with the Web Audio API first.
`html5AudioFallback`	`boolean`	`true`	Try an HTML5 audio element when the Web Audio load fails.
`maxParallelLoads`	`number`	`10`	How many sounds load at the same time.
`retryDelay`	`number`	`0.5`	Seconds between retries of a failed fetch.
`audioCache`	`boolean`	`true`	Let the browser cache fetched audio. With `false` fetches use `cache: 'no-cache'`.
`maxAudioSize`	`number`	`52428800`	Largest file to load, in bytes (50 MB). Checked against the `Content-Length` header.

Network

Property	Type	Default	Description
`fetchRetries`	`number`	`2`	Retries for a failed fetch.
`fetchTimeout`	`number`	`8`	Seconds before a fetch is given up.
`fetchHeaders`	`Record<string, string>`	`undefined`	Extra request headers for every audio fetch, such as an `Authorization` header for files behind a token.
`corsProxy`	`string`	`undefined`	Prefix for a CORS proxy, used for remote URLs according to `fetchStrategy`. For example `"https://corsproxy.io/?"`. Run your own proxy in production.
`fetchStrategy`	`'direct-first' \| 'proxy-first' \| 'direct-only'`	`'direct-first'`	Fetch the URL first and fall back to the proxy, the other way round, or never use the proxy.
`crossOrigin`	`'anonymous' \| 'use-credentials' \| null`	`null`	The `crossOrigin` setting for the HTML5 fallback and for streams. `null` ends up as `'anonymous'` on those elements.
`credentialStrategy`	`'auto' \| 'omit' \| 'include'`	`'auto'`	Whether fetches send cookies. `'auto'` tries with credentials first when `crossOrigin` is `'use-credentials'`, and without them otherwise.

Mobile and page lifecycle

Property	Type	Default	Description
`autoUnlock`	`boolean`	`true`	Unlock audio on the first touch or click, for mobile browsers that start muted. Only set up on touch and mobile devices.
`autoMuteOnHidden`	`boolean`	`true`	Mute everything while the page or tab is hidden.
`autoResumeOnFocus`	`boolean`	`true`	Unmute when the page comes back, if `autoMuteOnHidden` muted it. A mute you set yourself stays.
`autoSuspend`	`boolean`	`false`	Suspend the audio context after a stretch of silence, so a phone stops spending battery on an idle audio graph. The next `play()` wakes it up.
`autoSuspendDelay`	`number`	`30`	Seconds of silence before `autoSuspend` kicks in. Values under `1` are treated as `1`.

Debugging

Property	Type	Default	Description
`debug`	`boolean`	`false`	Log what the hub does to the console. Change it later with `setDebugMode`.

Example

import { SoundHub } from 'soundhub';

const soundHub = new SoundHub({
  masterLimiter: true,
  overlap: true,
  maxInstancesPerSound: 8,
  fetchHeaders: { Authorization: 'Bearer my-token' },
  debug: true,
});

const config = soundHub.getConfig();

config.masterLimiter;    // true, your value
config.maxParallelLoads; // 10, the default

Try it

Change the configuration and create a hub with it. Each option is applied to a freshly created SoundHub, so you can hear the difference straight away.

Try it

Try a configuration

Idle

new SoundHub( … )

Each run builds a new SoundHub and destroys the previous one. Options that only matter while loading, such as fetchRetries, are not audible here.

Code

Your clicks show up here as soundhub calls

Good to know

defaultVolume and defaultPan apply to each new sound only. The master starts at volume 1 and pan 0, and reset puts it back there. Before 6.4.0 they were applied to the master as well, so defaultVolume: 0.8 was heard as about 0.64.
The constructor copies your object, so you can reuse it for another hub. It clamps defaultVolume to 0 to 1, turns a negative fade duration into 0, copies createNewInstance into overlap when only the old name is set, and switches spatialAudio off when the browser cannot do it.
autoResumeOnFocus only does something while autoMuteOnHidden is on, because the visibility handler is only set up then.
There is no method to swap the configuration after the hub is created. Change behaviour with the dedicated methods instead, such as setDebugMode, setGlobalVolume, setMasterLimiter and setProgressUpdateInterval.

Playback defaults​

Output​

Loading​

Network​

Mobile and page lifecycle​

Debugging​

Example​

Try it​

Good to know​

See also​

Playback defaults

Output

Loading

Network

Mobile and page lifecycle

Debugging

Example

Try it

Good to know

See also