soundEvents

The hub reports what it does through events. There are 40 event types, each a member of SoundEventsEnum, and every event object is a SoundEvent. Listen with addEventListener or once.

The events

export enum SoundEventsEnum {
    CONTEXT_RESUMED = 'context_resumed',
    CONTEXT_SUSPENDED = 'context_suspended',
    ENDED = 'ended',
    DUCK_ENDED = 'duck_ended',
    DUCK_STARTED = 'duck_started',
    ERROR = 'error',
    FADE_IN_COMPLETED = 'fade_in_completed',
    FADE_MASTER_IN_COMPLETED = 'fade_master_in_completed',
    FADE_MASTER_OUT_COMPLETED = 'fade_master_out_completed',
    FADE_OUT_COMPLETED = 'fade_out_completed',
    GLOBAL_SPATIAL_POSITION_CHANGED = 'global_spatial_position_changed',
    LISTENER_CHANGED = 'listener_changed',
    LOADED = 'loaded',
    LOADING = 'loading',
    LOOP_COMPLETED = 'loop_completed',
    MASTER_PAN_CHANGED = 'master_pan_changed',
    MASTER_VOLUME_CHANGED = 'master_volume_changed',
    MUTE_GLOBAL = 'mute_global',
    MUTED = 'muted',
    OPTIONS_UPDATED = 'options_updated',
    PAN_CHANGED = 'pan_changed',
    PAN_RESET = 'pan_reset',
    PAUSED = 'paused',
    PLAYBACK_RATE_CHANGED = 'playback_rate_changed',
    PROGRESS = 'progress',
    RESET = 'reset',
    RESUMED = 'resumed',
    SEEKED = 'seeked',
    SPATIAL_ORIENTATION_CHANGED = 'spatial_orientation_changed',
    SPATIAL_POSITION_CHANGED = 'spatial_position_changed',
    SPATIAL_POSITION_RESET = 'spatial_position_reset',
    SPRITE_SET = 'sprite_set',
    STARTED = 'started',
    STOPPED = 'stopped',
    UNLOADED = 'unloaded',
    UNLOCKED = 'unlocked',
    UNMUTE_GLOBAL = 'unmute_global',
    UNMUTED = 'unmuted',
    UPDATED_URL = 'updated_url',
    VOLUME_CHANGED = 'volume_changed',
  }

What fires each one

Event	Fires when
context_resumed	resumeContext wakes the audio context, or a play wakes it from autoSuspend.
context_suspended	suspendContext runs, or autoSuspend puts the context to sleep.
ended	A sound or stream plays to its end.
duck_started	A duck target goes down because a trigger started. Carries the target as soundId and the ducked level as volume. Added in 6.5.0
duck_ended	A duck target comes back up after the last trigger stopped, or unduck removed a duck that was down. Carries the target as soundId and volume: 1. Added in 6.5.0
error	Anything goes wrong in a hub method. The same error is stored for getLastError.
fade_in_completed	A fadeIn finishes.
fade_out_completed	A fadeOut finishes.
fade_master_in_completed	A fadeGlobalIn finishes.
fade_master_out_completed	A fadeGlobalOut finishes.
global_spatial_position_changed	setMasterSpatialPosition or resetMasterSpatialPosition runs.
listener_changed	The listener moves or turns through setListenerPosition, setListenerOrientation or resetListener. Carries position, orientation and up.
loading	A fetch for a sound starts. Together with loaded that is enough for a loading indicator.
loaded	A sound is decoded, or a stream is ready to play.
loop_completed	A looping sound finishes one pass.
master_pan_changed	setGlobalPan runs.
master_volume_changed	setGlobalVolume runs, and during master fades.
mute_global	muteAllSounds runs.
unmute_global	unmuteAllSounds runs.
muted	mute runs on one sound.
unmuted	unmute runs on one sound.
options_updated	updateSoundOptions runs.
pan_changed	setPan runs.
pan_reset	resetPan or resetGlobalPan runs.
paused	pause runs.
resumed	resume runs.
playback_rate_changed	setPlaybackRate runs.
progress	Repeatedly while a sound plays with trackProgress on.
reset	reset or resetSound runs.
seeked	seek runs.
spatial_orientation_changed	setSpatialOrientation or setMasterSpatialOrientation runs.
spatial_position_changed	setSpatialPosition runs.
spatial_position_reset	resetSpatialPosition runs.
sprite_set	setSoundSprite creates a sprite, once per sprite.
started	A sound starts through play or playSprite.
stopped	stop runs.
unloaded	unloadSound removes a sound or stream.
unlocked	A mobile browser releases audio on the first touch. The moment to hide a "tap for sound" overlay.
updated_url	updateSoundUrl runs.
volume_changed	setSoundVolume runs, and during per-sound fades.

SoundEvent properties

Not every property is set on every event. Which ones you get depends on the event type.

export interface SoundEvent {
  channels?: number;
  currentTime?: number;
  duration?:number;
  error?: Error;
  instanceId?: string; // Add this for instance tracking
  isMaster?: boolean;
  isMuted?: boolean;
  loadState?: SoundLoadState;
  options?: PlayOptions;
  orientation?: { x: number; y: number; z: number };
  originalId?: string; // Add this to track the original sound ID
  pan?: number;
  pannerConfig?: SoundPannerConfig;
  playbackRate?: number;
  position?: { x: number; y: number; z: number };
  previousPan?: number;
  progress?: number; // ratio from 0 to 1
  progressInfo?: SoundProgressStateInfo;
  resetOptions?: SoundResetOptions;
  sampleRate?: number;
  bufferSize?: number;
  fileSize?: number;
  sound?: Sound;
  soundId?: string;
  state?: SoundStateInfo;
  timestamp?: number;
  type: SoundEventsEnum;
  up?: { x: number; y: number; z: number };
  url?: string;
  volume?: number;
}

Example

import { SoundHub, SoundEventsEnum, type SoundEvent } from 'soundhub';

const soundHub = new SoundHub();
await soundHub.loadSound('music', '/audio/theme.mp3');

soundHub.addEventListener(SoundEventsEnum.PAUSED, (event: SoundEvent) => {
  // A paused event carries these:
  console.log(event.type);      // 'paused'
  console.log(event.soundId);   // 'music'
  console.log(event.timestamp);
  console.log(event.sound);     // the Sound object
}, { soundId: 'music' });

soundHub.play('music');
soundHub.pause('music');

Progress for every instance of one sound

await soundHub.loadSound('piano-note-c', '/audio/piano-c.mp3');

soundHub.addEventListener(SoundEventsEnum.PROGRESS, (event: SoundEvent) => {
  console.log(`Instance ${event.instanceId}: ${event.progress}`);
}, { originalId: 'piano-note-c' });

soundHub.play('piano-note-c', {
  trackProgress: true,
  overlap: true,
  pan: Math.random() * 2 - 1,
});

Try it

Control the sound and watch the events arrive in real time. Turn on PROGRESS to see how often that one fires compared to the rest.

Try it

Watch the events arrive

Idle

Also log progress, which fires all the time while playing

No events yet. Press Play.

Code

Your clicks show up here as soundhub calls

Good to know

• Only started, ended and progress carry originalId and instanceId. Filter other events by soundId.
• Several methods, such as play, pause, stop, seek, fadeIn and setSoundVolume, take an optional skipDispatchEvent argument to leave their event out.
• Events from a sprite carry the sprite id, such as 'game-sounds_jump', as soundId.
• progress fires every few milliseconds. Set the rate with setProgressUpdateInterval.

See also

• addEventListener: listen for an event, with a filter.
• once: listen for the next event only.
• dispatchEvent: send an event yourself.
• soundProgressStateInfo: the shape of progressInfo.