Sound Sprites

A sound sprite is one audio file that holds many short sounds, each at its own start and end time. You load the file once, name the ranges, and play them by name. That means one request instead of dozens, and one asset to manage.

How it works

Load the file with loadSound. Sprites need the decoded samples, so a stream from loadStream will not do.
Name the ranges with setSoundSprite. Each range is [start, end] in seconds.
Play one with playSprite.

Every range becomes a sound of its own, with the id <soundId>_<key> and a copy of those samples in its own buffer. The powerUp range of 'game-sounds' is the sound 'game-sounds_powerUp'. Anything that takes a sound id works on it: stop, setSoundVolume, isPlaying, or an event filter like { soundId: 'game-sounds_powerUp' }.

The hub also records the ranges on the owner sound. That record is what getSpriteConfig returns and what removeSpriteSound uses to turn a key into sprite ids.

Example

import { SoundHub } from 'soundhub';

const soundHub = new SoundHub();
await soundHub.loadSound('game-sounds', '/audio/8-bit-game-sounds.mp3');

// Start and end time in seconds
soundHub.setSoundSprite('game-sounds', {
  nextLevel: [0, 2],
  powerUp:   [2.5, 4.5],
  jump:      [4.5, 5.5],
  fail:      [6, 8.5],
  catch:     [8.5, 9.2],
  danger:    [16.5, 18.5],
  victory:   [20.5, 22.5],
  attack:    [28, 29.5],
});

soundHub.playSprite('game-sounds', 'powerUp', { volume: 0.8 });

// Any PlayOptions work, as with play()
soundHub.playSprite('game-sounds', 'victory', {
  volume: 1.0,
  playbackRate: 1.5,
  overlap: false,
});

// Read the ranges back
soundHub.getSpriteConfig('game-sounds');
// { nextLevel: [0, 2], powerUp: [2.5, 4.5], ... }

// Remove one sprite: its sound, its instances and its key
soundHub.removeSpriteSound('danger');

Try it

Pick a sprite from the loaded sound and adjust the playback options.

Try it

One file, eight sounds

Idle

PlayOptions for playSprite

Each pad plays a slice of the same file. The bar shows where each slice sits. A sprite plays as its own sound, 'game-sounds_jump' for example, so that is the id to stop.

Code

Your clicks show up here as soundhub calls

The sprite methods

Method	What it does
`setSoundSprite(id, sprite)`	Adds ranges to a sound and creates a sprite sound for each. Setting a key again replaces that sprite.
`playSprite(id, spriteKey, options?)`	Plays `<id>_<spriteKey>` with the usual play options.
`getSpriteConfig(id)`	Returns the recorded ranges, or `undefined`.
`removeSpriteSound(spriteKey)`	Stops and removes a sprite and its instances, and drops its key from the config. Takes a key or a full sprite id, no sound id.
`removeSpriteConfig(id)`	Clears the record only. Sprite sounds already created stay playable.

Good to know

Since 6.3.2 setSoundSprite adds to the recorded config instead of replacing it, so you can register sprites in several calls. Setting a key that exists stops the old sprite sound and its instances and takes them off the master before the new one is made.
Since 6.3.2 removeSpriteSound also removes the key from the config and disconnects the sprite's gain node.
A sprite takes the owner's volume, pan and play options at the moment it is created. Changing the owner later does not change existing sprites.
removeSpriteSound('jump') removes the jump sprite of every sound that has that key. Use the full id, such as 'game-sounds_jump', to target one.
Every sprite created dispatches SoundEventsEnum.SPRITE_SET ('sprite_set').

How it works​

Example​

Try it​

The sprite methods​

Good to know​

See also​

How it works

Example

Try it

The sprite methods

Good to know

See also