Skip to main content

VariationOptions

Added in 6.5.0

VariationOptions is the object you pass as the third argument to createVariations. Every field is optional.

export interface VariationOptions {
  /**
   * How the next take is picked.
   * '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.
   * Default: 'random'.
   */
  order?: 'random' | 'shuffle' | 'cycle';
  /** A random playback rate between these two, as [min, max]. [0.95, 1.05] is a subtle spread. */
  pitch?: [number, number];
  /** A random volume factor between these two, as [min, max]. Multiplies the volume passed to play(), or 1. */
  volume?: [number, number];
  /** Let the takes overlap each other. Default: true, since that is what repeated effects want. */
  overlap?: boolean;
}
PropertyTypeDefaultDescription
order'random' | 'shuffle' | 'cycle''random'How the next take is picked, see below.
pitch[number, number]noneA random playback rate between min and max for each play. It multiplies the playbackRate passed to play, or 1.
volume[number, number]noneA random volume factor between min and max. It multiplies the volume passed to play, or 1.
overlapbooleantrueEvery play gets its own instance, so a take does not cut off the one before it. An overlap passed to play wins.

VariationOptions is exported from soundhub as a type.

The three orders​

orderWith takes A, B and C you might hear
'random'A C A B C B A C. Any take, but never the same one twice in a row.
'shuffle'B A C, C A B, A B C. Every take once per round, and a round never opens with the take that closed the one before.
'cycle'A B C A B C. Always in the order you gave.

With a single take every order plays that take.

Picking the ranges​

  • A pitch of [0.95, 1.05] is hard to hear as a pitch change, but it is enough to stop a repeated sound from sounding like a loop. [0.9, 1.1] is clearly audible.
  • A pitch below 1 also makes a take longer, and above 1 shorter.
  • A volume of [0.8, 1] varies the level without making any take stand out.

Example​

import { SoundHub, type VariationOptions } from 'soundhub';

const subtle: VariationOptions = { pitch: [0.95, 1.05], volume: [0.8, 1] };

soundHub.createVariations('footstep', ['step1', 'step2', 'step3', 'step4'], subtle);
soundHub.createVariations('coin', ['coin1', 'coin2'], { ...subtle, order: 'cycle' });

See also​