OpenAL Extension

Provides 3D audio, pitch control and other stuff.

Quick example

local res = resource.load("/sounds/sound.wav")
local pos = go.get_position()
self.soundSource = openal.new_source(res)
self.soundSource.x, self.soundSource.y = pos.x, pos.y
self.soundSource.is_looping = true
self.soundSource:play()

Video demonstration: https://www.youtube.com/watch?v=5vgHMGr8cpw

Setup

Add OpenAL as a Defold library dependency. Open game.project and in the dependencies field (in the project section) add:

https://github.com/Lerg/extension-openal/archive/master.zip

Add WAV files as resources (specify resources directory in game.project).

Disable Defold’s sound system by using sound_null.appmanifest in the game.project file under Native Extensions -> App Manifest.

Properties

openal.doppler_factor

Float, positive. Adjusts the Doppler effect. Higher value makes the effect more noticeable.

openal.speed_of_sound

Float, positive. Get or set the speed of sound.

openal.listener

Table. The Listener object. Described below.

Functions

openal.get_info()

Returns a table with information on OpenAL implementation.

Fields:

• vendor
• version
• renderer
• extensions

openal.set_distance_model(distance_model)

distance_model - string.

Sets a distance model by which all sound attenuation is calculated.

Available models:

• "inverse"
• "inverse_clamped"
• "linear"
• "linear_clamped"
• "exponent"
• "exponent_clamped"
• "none"

openal.new_source(resource)

resource - resource that represents a WAV file.

Returns a Source object.

Creates a sound source object and loads a WAV file into it. The Source object is described below. Only mono WAV files will be positioned. Stereo files will be played as if they are at the listener's position.

openal.remove_source(source)

source - a Source object.

Destroys the sound source and frees the memory.

Objects

Listener

Represents the listener - a point to which all the sounds come to.

Properties

listener.x

Float. X position.

listener.y

Float. Y position.

listener.z

Float. Z position.

listener.vx

Float. X component of the listener's velocity.

listener.vy

Float. Y component of the listener's velocity.

listener.vz

Float. Z component of the listener's velocity.

listener.orientation_at_x

Float. X component of the listener's "at" orientation.

listener.orientation_at_y

Float. Y component of the listener's "at" orientation.

listener.orientation_at_x

Float. Z component of the listener's "at" orientation.

listener.orientation_up_x

Float. X component of the listener's "up" orientation.

listener.orientation_up_y

Float. Y component of the listener's "up" orientation.

listener.orientation_up_z

Float. Z component of the listener's "up" orientation.

Source

Represents a sound source.

Properties

source.x

Float. X position.

source.y

Float. Y position.

source.z

Float. Z position.

source.vx

Float. X component of the source's velocity.

source.vy

Float. Y component of the source's velocity.

source.vz

Float. Z component of the source's velocity.

source.dx

Float. X component of the source's direction.

source.dy

Float. Y component of the source's direction.

source.dz

Float. Z component of the source's direction.

source.pitch

Float. Pitch adjustment, default is 1.0.

source.gain

Float. Gain adjustment, a value from 0 to 1.0, default is 1.0.

source.max_distance

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

source.rolloff_factor

Float. The rolloff rate for the source, default is 1.0.

source.reference_distance

Float. The distance under which the volume for the source would normally drop by half (before being influenced by source.rolloff_factor or source.max_distance), default is 50.0.

source.min_gain

Float. The minimum gain for this source.

source.max_gain

Float. The maximum gain for this source.

source.cone_outer_gain

Float. The gain when outside the oriented cone.

source.cone_inner_angle

Float. The gain when inside the oriented cone.

source.cone_outer_angle

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

source.is_looping

Boolean. If true, the sound will be repeated indefinitely, default is false.

source.is_relative

Boolean. If true, the sound will be positioned relative to the listener, default is false.

source.time

Float. Get or set the sound playback progress in seconds.

source.state

String. Get this source's state. Possible values: "initial", "playing", "paused", "stopped".

Functions

source:play()

Starts the playback of the sound from this source.

source:pause()

Pauses the playback.

source:rewind()

Resets the playback to the start of the sound.

source:stop()

Stops the playback.