Skip to main content

createVariations

Added in 6.5.0

Give several takes of a sound one name. From then on play(name) picks one of the takes, with a random pitch and volume inside the ranges you set. See Variations for when to use it.

createVariations(id: string, members: string[], options?: VariationOptions): void;

Parameters​

ParameterTypeDefaultDescription
idstringrequiredThe name to play the takes under. It must not be the id of a sound or stream.
membersstring[]requiredThe ids of the takes. Any loaded sound, including a sprite such as 'ui_click'.
optionsVariationOptions{}How a take is picked and how much it varies, see below.

VariationOptions​

PropertyTypeDefaultDescription
order'random' | 'shuffle' | 'cycle''random''random' picks any take except the one that just played. 'shuffle' plays every take once, in a random order, before any repeats. 'cycle' plays them in the order given.
pitch[number, number]noneA random playback rate between the two, as [min, max].
volume[number, number]noneA random volume factor between the two, as [min, max].
overlapbooleantrueLet the takes overlap each other.

The full type is on the VariationOptions page.

Returns​

Nothing.

Example​

import { SoundHub } from 'soundhub';

const soundHub = new SoundHub();
await soundHub.loadSounds([
  { id: 'step1', url: '/audio/step1.mp3' },
  { id: 'step2', url: '/audio/step2.mp3' },
  { id: 'step3', url: '/audio/step3.mp3' },
]);

soundHub.createVariations('footstep', ['step1', 'step2', 'step3'], {
  pitch: [0.95, 1.05],
  volume: [0.8, 1],
});

soundHub.play('footstep'); // one of the three, never the same one twice in a row
soundHub.play('footstep');

Takes from one sprite​

await soundHub.loadSound('impacts', '/audio/impacts.mp3');
soundHub.setSoundSprite('impacts', {
  hit1: [0, 0.4],
  hit2: [0.5, 0.9],
  hit3: [1, 1.4],
});

soundHub.createVariations('hit', ['impacts_hit1', 'impacts_hit2', 'impacts_hit3'], {
  order: 'shuffle',
});

Play options still apply​

// The pitch spread multiplies the rate you pass, the volume spread the volume
soundHub.play('footstep', { volume: 0.5, playbackRate: 1.2, pan: -0.3 });

Good to know​

  • play(name) returns the Sound of the take it picked. With overlap on, that is an instance such as 'step2:4'.
  • The pitch factor multiplies the playbackRate you pass to play, or 1. The volume factor multiplies the volume you pass to play, or 1.
  • Without a volume range, a take plays at its own volume. With one, the factor multiplies the volume passed to play, or the take's own volume when play gets none. A take you turned down with setSoundVolume stays down.
  • An overlap or createNewInstance you pass to play wins over the overlap option.
  • stop on the name stops every take it started, instances included.
  • The name works as a target or a trigger in duck.
  • Other methods, such as pause or setSoundVolume, do not know the name. Use the ids of the takes for those.
  • A name that is already a sound or stream throws, and so does an empty list of takes.
  • Calling it again with the same name replaces the set and starts the order over.
  • The takes are not checked when you create the set. A take that is not loaded fails when it is picked, the way play fails for any unknown id.

See also​