whale-sfx

Audio functions and primitives. They are mostly thin wrappers around OpenAL API.

const whl = require("whale-core");
const sfx = require("whale-sfx");

// ...

var device = new sfx.Device(); // Constructs default device.
var context = new sfx.Context(device);
sfx.makeCurrent(context);

var opusFileData = whl.fs.openFile("sound.ogg").read();
var sample = sfx.loadOggOpus(opusFileData);
var buffer = new sfx.Buffer(sample);

var source = new sfx.Source();
source.setBuffer(buffer);
source.play();

// Wait for a while, so sound system doesn't get uninitialized before sounds stops playing.
whl.delay(1000); // ms

whl.finalize(source);
whl.finalize(buffer);
sfx.makeCurrent(); // Deselects current context.
whl.finalize(context);
whl.finalize(device);
class whale-sfx.Buffer(sample)
Arguments:

Buffer represents audio data that is ready for use with Sources.

Each buffer is associated with a specific device, and can be shared between multiple sources. When buffer is created, it is automatically associated with the device of currently selected Context().

class whale-sfx.Context(device)
Arguments:

Context represents a state of an audio scene. It describes parameters (location, orientation, etc.) of listener and sound Sources.

Context always has one listener, but it can have multiple sound sources.

Before a context gets destroyed, all associated audio sources need to be destroyed first.

It is impossible to destroy currently selected context. User needs to make sure a different context is selected, or that no context is selected (by calling makeCurrent() without parameters).

class whale-sfx.Device()
class whale-sfx.Device(name)
Arguments:

  • name (String()) – Device name.

Represents an audio device. Its primary function is to create audio Contexts.

Device is created based on a name. List of available device names can be obtained with enumerateDevices(). If name is not specified, a default device is created.

Before a device gets destroyed, all associated buffers and contexts need to be destroyed first.

class whale-sfx.Sample()

Represents raw audio data and its parameters.

Currently, objects of this type are not meant to be created manually. Users are expected to load their samples with loadOggOpus().

Sample.channels
Type:

Number

Number of audio channels. Currently, only 1 or 2 channels are supported.

Sample.samplingRate
Type:

Number

Sampling rate in Hz.

Sample.bitsPerSample
Type:

Number

Audio bit depth of each sample point. Typical values would be 8 or 16.

Sample.data
Type:

whale-core.Buffer()

Raw audio data.

class whale-sfx.Source()

Represents audio source.

Source.play()

Plays sound.

Source.setBuffer(buffer)
Arguments:

Associates an audio buffer with a sound source.

whale-sfx.defaultDevice()
Return type:

String

Returns the name of the default audio device.

whale-sfx.enumerateDevices()
Return type:

Iterable[String]

Returns a list of available audio devices.

whale-sfx.loadOggOpus(buffer)
Arguments:
Return type:

whale-sfx.Sample()

Decodes Opus file data, and creates a sample object.

whale-sfx.makeCurrent()
Return type:

Boolean

Deselects current audio context. It is mostly used as a part of context destruction process.

whale-sfx.makeCurrent(context)
Arguments:
Return type:

Boolean

Selects current audio context.

whale-sfx.openalVendor()
Return type:

String

Returns information about OpenAL library vendor.

whale-sfx.openalVersion()
Return type:

String

Returns information about OpenAL library version.

whale-sfx.openalRenderer()
Return type:

String

Returns information about OpenAL library renderer.

whale-sfx.openalExtensions()
Return type:

String

Returns information about available OpenAL library extensions.