Skip to main content

playSprite

Play one sprite of a sound by its key. Use it after setSoundSprite has cut the file into named ranges.

playSprite(id: string, spriteKey: string, options?: PlayOptions, skipDispatchEvent?: boolean): void;

Parameters​

ParameterTypeDefaultDescription
idstringrequiredID of the sound the sprites were set on.
spriteKeystringrequiredName of the sprite, as used in setSoundSprite.
optionsPlayOptions{}The same options as play, such as volume, playbackRate, loop or overlap. See PlayOptions.
skipDispatchEventbooleanfalseLeave out the started event for this play.

Returns​

Nothing.

Example​

import { SoundHub } from 'soundhub';

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

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 });

soundHub.playSprite('game-sounds', 'victory', {
  volume: 1.0,
  playbackRate: 1.5,
  overlap: false,
});

Try it​

Try it

One file, eight sounds

Idle

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

Good to know​

  • This is a shortcut for play('<id>_<spriteKey>', options). The sprite is a sound of its own with that id, so stop, pause and event filters use 'game-sounds_powerUp', not the owner's id.
  • Hub-wide defaults from SoundHubConfig apply as they do for any other sound.
  • With overlap: true every call starts a new instance ('game-sounds_jump:1', 'game-sounds_jump:2' and so on), which suits effects the player can trigger quickly.
  • An unknown key is handled like an unknown id in play(): the error is logged, stored for getLastError and dispatched as an error event. On a stream from loadStream this method throws, because streams have no sprites.

See also​