Kappapps SDK

Appearance

Class: KAudio ​

Overlay sound player, built on the Web Audio API: downloads the file, decodes it, normalizes its volume to a target level, optionally applies effects (speed, pitch, echo, radio, reverb…) and then plays it.

Remarks ​

You rarely instantiate KAudio directly: go through k.medias.playAudio(source, volume, effects) or through KMedia for a library media of type sounds. All methods are chainable.

Example ​

ts
// Play a sound at 80% volume with a "radio" effect
await k.medias.playAudio('https://example.tld/alert.mp3', 80, ['radio']);

See ​

KMedia for the generic media, KVideo and KImage.

Implements ​

Properties ​

audioBuffer ​

ts
audioBuffer: AudioBuffer = null;

Decoded audio buffer ready to be played, or null before loading.

effects ​

ts
effects: KAudioEffect[] = [];

gainNode ​

ts
gainNode: GainNode = null;

Gain node applying the normalized volume, or null before loading.

loaded ​

ts
loaded: boolean = false;

true once the sound has been downloaded, decoded and is ready to play.

source ​

ts
source: string;

sourceNode ​

ts
sourceNode: AudioBufferSourceNode = null;

Web Audio source node that plays the decoded buffer, or null before loading.

timeline ​

ts
timeline: MediaTimeline = {};

volume ​

ts
volume: number = 50;

DBFS ​

ts
static DBFS: number = -14;

Target loudness level (in dBFS) to which each sound is normalized before the volume is applied, to even out the perceived level from one sound to another.

Methods ​

play() ​

ts
play(): Promise<KAudio>;

Preloads if needed, then plays the sound. Honors the timeline: starts at timeline.startAt and stops at timeline.endAt (in milliseconds) when set.

Returns ​

Promise<KAudio>

A promise resolved with this KAudio once playback has started.

Throws ​

Rejects (and emits the error event) if loading or decoding fails.

See ​

playSync to wait for the sound to finish.

Implementation of ​

KMedia.play

playSync() ​

ts
playSync(): Promise<KAudio>;

Plays the sound and waits for it to finish (natural end or via the timeline) before resolving.

Returns ​

Promise<KAudio>

A promise resolved with this KAudio once the sound has finished.

Throws ​

Rejects if a loading / playback error occurs.

Example ​

ts
// Chain two sounds one after the other
await k.medias.playAudio('a.mp3').then(a => a.playSync());

See ​

play to not wait for the end.

Implementation of ​

KMedia.playSync

preload() ​

ts
preload(): Promise<KAudio>;

Downloads, decodes and prepares the sound (with its effects) without playing it.

Returns ​

Promise<KAudio>

A promise resolved with this KAudio (chainable).

See ​

play to preload then play.

Implementation of ​

KMedia.preload

remove() ​

ts
remove(): KAudio;

Stops the sound, then disconnects the audio nodes (source and gain) to release the resources.

Returns ​

KAudio

This KAudio (chainable).

Implementation of ​

KMedia.remove

setVolume() ​

ts
setVolume(volume): KAudio;

Sets the playback volume (reapplied on top of the loudness normalization).

Parameters ​

volume ​

number

Target volume, from 0 to 100.

Returns ​

KAudio

This KAudio (chainable).

Implementation of ​

KMedia.setVolume

stop() ​

ts
stop(): KAudio;

Immediately stops playback of the sound. No effect if the sound is already stopped.

Returns ​

KAudio

This KAudio (chainable).

See ​

remove to stop and release the audio nodes.

Implementation of ​

KMedia.stop