Slappy - 3D Sound API for Nim.

nimble install slappy

API reference

About

Big thanks to yglukhov's sound library!

This library provides higher level interface to the OpenAL library.

Slappy provides the standard features of:

• 3d positions of sounds.
• 3d position of listener.
• Doppler shift.
• Acoustic attenuation.

Slappy also provides some extra features such as:

• A much more nim-like api.
• .wav and .ogg loading.
• Sound priority. (in progress)
• Max number of the same sound played. (in progress)
• Fade in and fade out. (in progress)
• Ability to queued sounds. (in progress)

Example:

# rotate sound in 3d
let sound = newSound("tests/drums.mono.wav")
var source = sound.play()
source.looping = true
echo "rotating sound in 3d, 1 rotation"
for i in 0..360:
  let a = float(i) / 180 * PI
  source.pos = vec3(sin(a), cos(a), 0)
  sleep(20)
source.stop()
sleep(500)

See test.nim for more details.

Basic concepts

Listener

Listener is the main ear of abstract person in the 3d world.

Listener has the following properties:

• gain - Volume on which the listener hears.
• pos - Position
• vel - Velocity
• mat - Orientation matrix

You get one global Listener.

Sound

Sound the recording of the sound that can be played.

Sound can be loaded with: sound = newSound("path/to/wav.or.ogg")

Sound has the following functions:

• play() - Creates a Source objects that has the sound playing.

Sound has the following properties, that are read only:

• bits - Bit rate or number of bits per sample.
• size - Number of byte the sound takes up.
• freq - Frequency or the samples per second rate.
• channels - Number of channels, only 1 or 2 supported. WARNING: 2 channel sounds can't be positioned in 3d
• samples - Number of samples, a sample is a single integer that sets the position of the speaker membrane.
• duration - duration of the sound in seconds.

Source

Source represents the sound playing in a 3d world, kind of like an abstract speaker.

Source has the following functions:

• stop() - Stop the sound.
• play() - Start playing the sound (if it was stopped before).

Source has the following properties:

• pitch - How fast the sound plays, or how low or high it sounds.
• gain - Volume of the sound.
• maxDistance - Inverse Clamped Distance Model, where sound will not longer be played.
• rolloffFactor - Set roll off rate for the source.
• halfDistance - The distance under which the volume for the source would normally drop by half.
• minGain - The minimum gain for this source.
• maxGain - The minimum gain for this source.
• playing - Is the sound playing.
• looping - Should the sound loop.
• pos - Position
• vel - Velocity
• mat - Orientation matrix
• playback - playback position in seconds (offset)

API: slappy

import slappy

type Listener

Listener = object

type Sound

Sound = ref object
 id: ALuint

type Source

Source = ref object
 id: ALuint

var listener

listener = Listener()

proc gain=

Set Master gain. Value should be positive.

proc gain=(listener: Listener; v: float32)

proc gain

Get master gain.

proc gain(listener: Listener): float32

proc pos=

Set position of the main listener.

proc pos=(listener: Listener; pos: Vec3)

proc pos

Get position of the main listener.

proc pos(listener: Listener): Vec3

proc vel=

Set velocity of the main listener.

proc vel=(listener: Listener; vel: Vec3)

proc vel

Get velocity of the main listener.

proc vel(listener: Listener): Vec3

proc mat=

Set orientation of the main listener.

proc mat=(listener: Listener; mat: Mat4)

proc mat

Get orientation of the main listener.

proc mat(listener: Listener): Mat4

proc playing

proc playing(source: Source): bool {.inline.}

proc stop

proc stop(source: Source)

proc play

proc play(source: Source)

proc pitch=

proc pitch=(source: Source; v: float32)

proc pitch

proc pitch(source: Source): float32

proc gain=

proc gain=(source: Source; v: float32)

proc gain

proc gain(source: Source): float32

proc maxDistance=

Set the Inverse Clamped Distance Model to set the distance where there will no longer be any attenuation of the source.

proc maxDistance=(source: Source; v: float32)

proc maxDistance

proc maxDistance(source: Source): float32

proc rolloffFactor=

Set rolloff rate for the source. Default is 1.0.

proc rolloffFactor=(source: Source; v: float32)

proc rolloffFactor

proc rolloffFactor(source: Source): float32

proc halfDistance=

The distance under which the volume for the source would normally drop by half (before being influenced by rolloff factor or maxDistance).

proc halfDistance=(source: Source; v: float32)

proc halfDistance

proc halfDistance(source: Source): float32

proc minGain=

The minimum gain for this source.

proc minGain=(source: Source; v: float32)

proc minGain

proc minGain(source: Source): float32

proc maxGain=

The minimum gain for this source.

proc maxGain=(source: Source; v: float32)

proc maxGain

proc maxGain(source: Source): float32

proc coneOuterGain=

The gain when outside the oriented cone.

proc coneOuterGain=(source: Source; v: float32)

proc coneOuterGain

proc coneOuterGain(source: Source): float32

proc coneInnerAngle=

Inner angle of the sound cone, in degrees. Default is 360.

proc coneInnerAngle=(source: Source; v: float32)

proc coneInnerAngle

proc coneInnerAngle(source: Source): float32

proc coneOuterAngle=

Outer angle of the sound cone, in degrees. Default is 360.

proc coneOuterAngle=(source: Source; v: float32)

proc coneOuterAngle

proc coneOuterAngle(source: Source): float32

proc looping=

proc looping=(source: Source; v: bool)

proc looping

proc looping(source: Source): bool

proc playback=

Set playback position in seconds (offset).

proc playback=(source: Source; v: float32)

proc playback

Get the playback position in seconds (offset).

proc playback(source: Source): float32

proc pos=

Set source position.

proc pos=(source: Source; pos: Vec3)

proc pos

proc pos(source: Source): Vec3

proc vel=

proc vel=(source: Source; vel: Vec3)

proc vel

proc vel(source: Source): Vec3

proc mat=

proc mat=(source: Source; mat: Mat4)

proc mat

proc mat(source: Source): Mat4

proc slappyInit

Call this on start of your program.

proc slappyInit()

proc slappyClose

Call this on exit.

proc slappyClose()

proc slappyTick

Updates all sources and sounds.

proc slappyTick()

proc newSound

proc newSound(): Sound

proc newSound

proc newSound(filePath: string): Sound {.raises: [Defect, IOError, OSError, Exception, ValueError], tags: [ReadIOEffect, WriteIOEffect].}

proc bits

Gets the bit rate or bits per sample, only 8bits and 16bits per sample supported.

proc bits(sound: Sound): int {.inline.}

proc size

Gets the size of the sound buffer in bytes.

proc size(sound: Sound): int {.inline.}

proc freq

Gets the frequency or the samples per second rate.

proc freq(sound: Sound): int {.inline.}

proc channels

Gets number of channels, only 1 or 2 are supported. WARNING: 2 channel sounds can't be positioned in 3d.

proc channels(sound: Sound): int {.inline.}

proc samples

Gets number of samples.

proc samples(sound: Sound): int {.inline.}

proc duration

Gets duration of the sound in seconds.

proc duration(sound: Sound): float32 {.inline.}

proc play

proc play(sound: Sound): Source