Skip to Content
defold-typescript libraries
Lerg

Lerg/extension-openal/openal

3D positional audio for Defold through OpenAL: WAV sound sources with position, pitch, gain and looping, heard from one listener.

  • GitHub: Lerg/extension-openal — pinned to 618292f
    1. This repo publishes no releases or tags. Add a commit archive URL — for the pinned commit, https://github.com/Lerg/extension-openal/archive/618292f0bff56b6cd38652a97baf90ba89b56e91.zip — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as openal from "openal"

Functions

init()

Opens the default audio device and creates the context every other call works through. Call it once, before creating sources.

get_info(): Info

Reads which OpenAL implementation is running.

Returns

  • Info

set_distance_model(distance_model: "inverse" | "inverse_clamped" | "linear" | "linear_clamped" | "exponent" | "exponent_clamped" | "none")

Sets the model every source's attenuation with distance is calculated by.

Parameters

  • distance_model: "inverse" | "inverse_clamped" | "linear" | "linear_clamped" | "exponent" | "exponent_clamped" | "none" — The attenuation model; a name outside the seven is ignored.

new_source(resource: Opaque<"buffer">): Source | undefined

Creates a sound source and loads a WAV file into it. Only a mono sound is positioned; a stereo one plays as if it were at the listener.

Parameters

  • resource: Opaque<"buffer"> — The WAV file's data, as resource.load returns it.

Returns

  • Source | undefined — The source, or undefined when the data cannot be loaded as a WAV file.

remove_source(source: Source | undefined)

Destroys a source and frees its sound. Reading or writing the source's properties afterwards is an error.

Parameters

  • source: Source | undefined — The source to destroy; undefined is ignored, so a failed {@link new_source} result can be passed as is.

Variables

doppler_factor: number

Scales the Doppler effect; a higher value makes it more noticeable. A value that is not positive is ignored.

speed_of_sound: number

The speed of sound the Doppler effect is calculated with. A value that is not positive is ignored.

listener: Listener

The point every sound is heard from.

Types

Info

Info.vendor: string

Who made the implementation.

Info.version: string

The implementation's version.

Info.renderer: string

The renderer the implementation plays through.

Info.extensions: string

The OpenAL extensions the implementation supports, separated by spaces.

Source

Source.play()

Starts playback.

Source.pause()

Pauses playback.

Source.rewind()

Moves playback back to the start of the sound.

Source.stop()

Stops playback.

Source.x: number

X position.

Source.y: number

Y position.

Source.z: number

Z position.

Source.vx: number

X component of the velocity.

Source.vy: number

Y component of the velocity.

Source.vz: number

Z component of the velocity.

Source.dx: number

X component of the direction the sound cone points in.

Source.dy: number

Y component of the direction.

Source.dz: number

Z component of the direction.

Source.pitch: number

Pitch adjustment, 1 by default.

Source.gain: number

Gain from 0 to 1.

Source.max_distance: number

The distance past which the source no longer attenuates under a clamped distance model, 1000 by default.

Source.rolloff_factor: number

How fast the source attenuates with distance.

Source.reference_distance: number

The distance at which the volume drops by half before rolloff_factor and max_distance apply, 50 by default.

Source.min_gain: number

The lowest gain the source attenuates to.

Source.max_gain: number

The highest gain the source plays at.

Source.cone_outer_gain: number

The gain outside the sound cone.

Source.cone_inner_angle: number

Inner angle of the sound cone, in degrees.

Source.cone_outer_angle: number

Outer angle of the sound cone, in degrees.

Source.time: number

Playback position in seconds; setting it seeks.

Source.is_looping: boolean

Whether the sound repeats indefinitely, false by default.

Source.is_relative: boolean

Whether the position is relative to the listener, false by default.

Source.state: "initial" | "playing" | "paused" | "stopped"

The playback state.

Listener

Listener.x: number

X position.

Listener.y: number

Y position.

Listener.z: number

Z position.

Listener.vx: number

X component of the velocity.

Listener.vy: number

Y component of the velocity.

Listener.vz: number

Z component of the velocity.

Listener.orientation_at_x: number

X component of the "at" vector, the direction the listener faces.

Listener.orientation_at_y: number

Y component of the "at" vector.

Listener.orientation_at_z: number

Z component of the "at" vector.

Listener.orientation_up_x: number

X component of the "up" vector.

Listener.orientation_up_y: number

Y component of the "up" vector.

Listener.orientation_up_z: number

Z component of the "up" vector.

On this page