Skip to main content

updateSoundOptions

Merge new values into the play options a sound keeps. The next play of that sound starts with them, so you do not have to pass the same options on every call.

updateSoundOptions(soundId: string, options: Partial<PlayOptions>): void;

Parameters​

ParameterTypeDefaultDescription
soundIdstringrequiredID of a loaded sound.
optionsPartial<PlayOptions>requiredThe options to change. Anything you leave out keeps its current value. See playOptions.

Returns​

Nothing.

Example​

import { SoundHub } from 'soundhub';

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

soundHub.updateSoundOptions('rain', { loop: true, volume: 0.4, playbackRate: 0.9 });

// Plays looped, at 0.4 volume and 0.9 speed
soundHub.play('rain');

// Options passed to play() still win for that call
soundHub.play('rain', { volume: 1 });

Good to know​

  • It stores the options and does not touch the audio of a sound that is already playing. Use setSoundVolume or setPlaybackRate for a live change.
  • Options read while a sound runs can still act early. Setting loop: false on a playing, non-seamless loop makes it end the next time it reaches the end.
  • Setting maxLoops also resets the sound's loop counter.
  • Dispatches SoundEventsEnum.OPTIONS_UPDATED ('options_updated') with the options you passed.
  • Buffered sounds only. For a stream or an id that is not loaded, it does nothing and dispatches no event.

See also​

  • playOptions: every option you can set.
  • play: pass options for one call instead.
  • setLoop: switch looping on or off.