Sound

The `Sound` class for voice, music, and effect playback, covering volume, muting, rate, seeking, and fading.

This page is under construction.

Beta feature, subject to change.

Sound controls the sound of the game

Static Method

voice

Create a voice sound

const voice = Sound.voice({
    src: 'voice.mp3',
});

// is equivalent to
const voice = new Sound({
    src: 'voice.mp3',
    type: SoundType.Voice,
});

type is a default here, not an override. Pass one to put the line on a bus beneath voice — which is how a game gives each member of its cast a volume of its own.

const line = Sound.voice({src: 'alice-01.mp3', type: 'alice'});

arg0: Partial<ISoundUserConfig> | string - The config of the sound or the source of the sound, see ISoundUserConfig
Returns Sound

bgm

Create a bgm sound. type defaults to bgm and may name any bus beneath it.

arg0: Partial<ISoundUserConfig> | string - The config of the sound or the source of the sound, see ISoundUserConfig
Returns Sound

Create a sound. type defaults to sound and may name any bus beneath it.

arg0: Partial<ISoundUserConfig> | string - The config of the sound or the source of the sound, see ISoundUserConfig
Returns Sound

Public Method

constructor

Overload 1 of 2

config?: Partial<ISoundUserConfig> - See ISoundUserConfig

Overload 2 of 2

src?: string - The source of the sound

Chainable Method

play

Play the sound and wait for it to finish

const sound = new Sound({
    src: 'sound.mp3',
});
scene.action([
    sound.play(1000), // play and fade in 1 second
]);

A clip on any bus may be played this way, including a bgm one. type selects which volume control governs the clip and nothing else, so putting an ambience track on bgm — so the player's music slider controls it — and then playing it from an ordinary line is a legitimate thing to want.

This is not the same as scene.setBackgroundMusic(). A clip played here is not in the scene's background-music slot, so leaving the scene will not stop it and no cross-fade is arranged for it. Playing a bgm-typed clip this way logs a console.warn saying exactly that; it is a nudge, not an error. Before 0.22.0 it threw and failed the whole story at chain-build time.

duration?: number - Fade duration in milliseconds

stop

Stop the sound. After stopping, the sound will go back to the beginning

duration?: number - Fade duration in milliseconds

setVolume

Set the volume of the sound. Given a duration, the change is a fade rather than a jump.

const sound = new Sound({
    src: 'sound.mp3',
    volume: 0,
});
scene.action([
    sound
        .play()
        .setVolume(1, 1000), // fade in 1 second
]);

volume: number - Volume, from 0 to 1
duration?: number - Fade duration in milliseconds

mute

Mute or unmute the sound without stopping playback.

scene.action([
    bgm.play(),
    bgm.mute(),
    bgm.unmute(),
]);

muted?: boolean - true to mute the sound, false to restore volume (defaults to true)
Returns Proxied<Sound, Chained<LogicAction.Actions>> - Chained Sound instance

unmute

Alias of mute(false) to restore the original volume.

Returns Proxied<Sound, Chained<LogicAction.Actions>> - Chained Sound instance

setRate

Set the rate of the sound

rate: number - Rate, base is 1

pause

duration?: number - Fade duration in milliseconds

resume

fade?: number - Fade duration in milliseconds

seek

Jump to a position in the clip, in seconds, and keep playing from there. This is the write counterpart to reading the play head — a music-player screen or a "skip the intro" line needs it.

scene.action([
    theme.seek(30),
]);

A no-op on a sound that is not currently playing: there is nothing to move. The loop region (see endTime) survives the jump, so seeking inside a looping track does not quietly turn it into a one-shot.

time: number - Position in seconds, measured from the start of the file (not from the in point)
Returns Proxied<Sound, Chained<LogicAction.Actions>> - Chained Sound instance

Sound

On this page