Skip to main content

updateSoundUrl

Swap the file behind a sound id. The old sound is stopped and dropped, and the new url is loaded under the same id. Use it for a quality switch or a different language track.

updateSoundUrl(id: string, newUrl: string): Promise<void>;

Parameters​

ParameterTypeDefaultDescription
idstringrequiredID of a loaded sound.
newUrlstringrequiredUrl of the new file. A single url only, not a list.

Returns​

Promise<void>: resolves when the new file is loaded. It also resolves, without doing anything, for an id that is not loaded. It does not reject when the new load fails.

Example​

import { SoundHub, SoundEventsEnum } from 'soundhub';

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

soundHub.addEventListener(SoundEventsEnum.UPDATED_URL, (event) => {
  console.log(`${event.soundId} now plays the new file`);
});

await soundHub.updateSoundUrl('music', '/audio/theme-high.mp3');
soundHub.play('music');

Good to know​

  • The old sound is stopped without a stopped event. When the new file has loaded, an updated_url event is dispatched.
  • The sound comes back as a fresh entry with default play options. Options set earlier with updateSoundOptions and its sprite config are not carried over.
  • The old entry is removed before the new file is fetched. If the new load fails the id is left without audio. The error is logged, stored for getLastError and dispatched as an error event, but the promise still resolves. Check getLoadState afterwards.
  • The url list on file becomes just newUrl.
  • Buffered sounds only. For a stream id it does nothing.

See also​