soundEvents

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.

Also log PROGRESS (fires continuously while playing)

No events yet. Press play.

The events

You can listen to the following Sound Events:

export enum SoundEventsEnum {
    ENDED = 'ended',
    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',
    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_POSITION_CHANGED = 'spatial_position_changed',
    SPATIAL_POSITION_RESET = 'spatial_position_reset',
    SPRITE_SET = 'sprite_set',
    STARTED = 'started',
    STOPPED = 'stopped',
    UNLOADED = 'unloaded',
    UNMUTE_GLOBAL = 'unmute_global',
    UNMUTED = 'unmuted',
    UPDATED_URL = 'updated_url',
    VOLUME_CHANGED = 'volume_changed',
  }

SoundEvent properties

Note, not all properties are passed to the SoundEvent. It depends what event is used.

export interface SoundEvent {
  currentTime?: number;
  duration?:number;
  error?: Error;
  instanceId?: string; // Add this for instance tracking
  isMaster?: boolean;
  isMuted?: boolean;
  options?: PlayOptions;
  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;
  sound?: Sound;
  soundId?: string;
  timestamp?: number;
  type: SoundEventsEnum;
  volume?: number;
}

Basic example:

const mySoundHub = new SoundHub();

mySoundHub.addEventListener(SoundEventsEnum.PAUSED, (event: SoundEvent) => {
    // For example the SoundEventsEnum.PAUSED event has only these properties:
    console.log(event.type);
    console.log(event.soundid);
    console.log(event.timestamp);
    console.log(event.sound); // Sound object
});

Advanced example

const mySoundHub = new SoundHub();

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

    // Track progress for specific sound instances using a filter in the addEventListener.
mySoundHub.addEventListener(
    SoundEventsEnum.PROGRESS,
    (event: SoundEvent) => {
    console.log(`Progress for instance ${event.instanceId}: ${event.progress}`, event.volume);
    },
    { originalId: 'piano-note-c' } // Optional: Filter by originalId
);