Skip to content

luxe API (2025.1.2)

luxe: audio module

Audio

import "luxe: audio" for Audio

The Audio module let's you play audio.

Audio is a service API, and isn't a modifier system. There is e.g the Sound modifier for placing sounds in the world.

Most things in Audio work on an instance (handle) of a sound. You get one of those from play or loop, and then can modify or query it. It's always safe to call any function on an instance, even if it's finished playing.

A quick look:

//play them
var sound = Audio.play(Asset.audio("assets/sound"))
var music = Audio.loop(Asset.audio("assets/music"))

//later...
Audio.volume(music, 0.5)

//later still...
Audio.stop(music)

That's it!

  • set_listener(pos: Float3, forward: Float3, up: Float3, velocity: Float3)
  • play(source: AudioAsset, volume: Num)
  • play(source: AudioAsset, as3D: Bool, bus: AudioBus, volume: Num)
  • play(source: AudioAsset)
  • loop(source: AudioAsset, volume: Num)
  • loop(source: AudioAsset, as3D: Bool, bus: AudioBus, volume: Num)
  • loop(source: AudioAsset)
  • stop(instance: AudioInstance)
  • playing(instance: AudioInstance)
  • pan(instance: AudioInstance, pan: Num)
  • pan_of(instance: AudioInstance)
  • volume(instance: AudioInstance, volume: Num)
  • volume_of(instance: AudioInstance)
  • pitch(instance: AudioInstance, pitch: Num)
  • pitch_of(instance: AudioInstance)
  • pause(instance: AudioInstance, paused: Bool)
  • pause_of(instance: AudioInstance)
  • set3D(instance: AudioInstance, pos: Float3, vel: Float3, dopper_factor: Float, attenuation: AudioAttenuation, range: Float2, rolloff: Num)

Audio.set_listener(pos: Float3, forward: Float3, up: Float3, velocity: Float3) returns unknown

Set the world space listener position directly

Audio.play(source: AudioAsset, volume: Num) returns AudioInstance

Plays audio from the specified source at volume volume. Returns a handle to an audio instance that you can modify or stop.

Audio.define_source("sound", "assets/sound.wav")
Audio.play("sound", 1)

Audio.play(source: AudioAsset, as3D: Bool, bus: AudioBus, volume: Num) returns AudioInstance

Plays audio from the specified source with as3D and bus at volume volume. The bus comes from create_bus, and 0 means global/default bus. If as3D is true, use set3D on the handle returned to configure position/velocity. Returns a handle to an audio instance that you can modify or stop.

Audio.define_source("sound", "assets/sound.wav")
Audio.play("sound", true, 0, 1)

Audio.play(source: AudioAsset) returns AudioInstance

Plays audio from the specified source at volume 1.0. Returns a handle to an audio instance that you can modify or stop.

Audio.define_source("sound", "assets/sound.wav")
Audio.play("sound")

Audio.loop(source: AudioAsset, volume: Num) returns AudioInstance

Begins looping audio for id at volume volume. Returns a handle to an audio instance that you can modify or stop.

var music = Audio.loop("music", 1.0)

Audio.loop(source: AudioAsset, as3D: Bool, bus: AudioBus, volume: Num) returns AudioInstance

Begins looping audio for id with as3D and bus at volume volume. The bus comes from create_bus, and 0 means global/default bus. If as3D is true, use set3D on the handle returned to configure position/velocity.
Returns a handle to an audio instance that you can modify or stop.

var music = Audio.loop("music", false, 0, 1.0)

Audio.loop(source: AudioAsset) returns AudioInstance

Begins looping audio for id at volume 1.0. Returns a handle to an audio instance that you can modify or stop.

var music = Audio.loop("music")

Audio.stop(instance: AudioInstance) returns None

Stops an AudioInstance.

var music = Audio.loop("music")
Audio.stop(music)

Audio.playing(instance: AudioInstance) returns Bool

Returns true if an AudioInstance is playing.

var music = Audio.loop("music")
Log.print(Audio.playing(music)) //true
Audio.stop(music)
Log.print(Audio.playing(music)) //false

Audio.pan(instance: AudioInstance, pan: Num) returns None

Sets the current pan value for the given instance.

Negative values for pan will move the audio to the left speakers, while positive values will move the audio to the right speakers.

A value of 0 will reset to the audio sample back to center.

var sound = Audio.play("sound")
Audio.pan(sound, -2.0)

Audio.pan_of(instance: AudioInstance) returns Num

Returns the current pan value for the given instance.

var sound = Audio.play("sound")
Audio.pan(sound, 2.0)
Log.print(Audio.pan_of(sound)) // returns 2.0

Audio.volume(instance: AudioInstance, volume: Num) returns None

Sets the volume for a given instance.

Intended volumes range from 0..1, with 1 meaning 100% volume, and 0 meaning silence. Volume values higher than 1 are valid (> 100%).

var sound = Audio.play("sound") // Volume is 1.0
Audio.volume(sound, 0.5)        // Volume is now 0.5

Audio.volume_of(instance: AudioInstance) returns Num

Returns the current volume for the given instance.

var sound = Audio.play("sound")
Log.print(Audio.volume_of(sound)) // returns 1

Audio.pitch(instance: AudioInstance, pitch: Num) returns None

Adjusts the pitch of instance, making the sample sound higher or lower-pitched. Pitch values below 1 will lower the pitch of the sample, while pitch values above 1 raise it.

A value of 1 will cause the sample to be played at its source pitch.

Pitch changes will affect playback duration, causing lower-pitched samples to have longer durations and higher-pitched samples to have shorter durations, because the audio is not resampled (when using this function).

A pitch of 0 (or smaller) will be ignored.

var sound = Audio.play("sound")
Audio.pitch(sound, 1)

Audio.pitch_of(instance: AudioInstance) returns Num

Returns the current pitch for instance.

var sound = Audio.play("sound")
Audio.pitch(sound, 3)
Log.print(Audio.pitch_of(sound)) // returns 3

Audio.pause(instance: AudioInstance, paused: Bool) returns None

Sets whether the audio instance is playing, pausing it when not. Once you set an instance to not play you can resume it later.

var sound = Audio.play("sound")
Audio.pause(sound, false) //pauses

Audio.pause_of(instance: AudioInstance) returns Bool

Returns whether an instance is paused.

var sound = Audio.play("sound")
Log.print(Audio.pause_of(sound)) //true
Audio.pause(sound, false) //pause
Log.print(Audio.pause_of(sound)) //false

Audio.set3D(instance: AudioInstance, pos: Float3, vel: Float3, dopper_factor: Float, attenuation: AudioAttenuation, range: Float2, rolloff: Num) returns None

Sets 3D parameters of the the audio instance. Note that you need to use play with the 3d flag to make the sound 3d otherwise this has no effect.

var sound = Audio.play("sound")
var pos = [0,0,0]
var vel = [0,0,0]
var doppler = 1.0
var attn = AudioAttenuation.none
var range = [1, 100] // min / max distance for attenuation
var rolloff = 1.0
Audio.set3D(sound, pos, vel, doppler, attn, range, rolloff)

AudioAttenuation

import "luxe: audio" for AudioAttenuation

Read more details with graphs here https://solhsa.com/soloud/concepts3d.html#attenuation

AudioAttenuation.none returns unknown

No attenuation based on distance. The default

AudioAttenuation.inverse_distance returns unknown

The higher the rolloff factor, the more steeply the volume drops. At low enough rolloff factor, the volume never drops near zero. Values over 1 recommended (unless you have special needs). Values less than equal to zero result in undefined behavior. Increasing the minimum distance pushes the start of the attenuation further. It also causes the curve to change. Note that the minimum distance must be above 0. The maximum distance simply cuts the attenuation at the volume level it has reached at that point.

AudioAttenuation.linear_distance returns unknown

The rolloff factor for linear distance simply sets the maximum volume reduction. Using values outside the 0..1 range causes undefined behavior. The minimum and maximum distance works as one might expect. Minimum distance must be less or equal to maximum distance.

AudioAttenuation.exponential_distance returns unknown

The higher the rolloff factor, the more steeply the volume drops. At low enough rolloff factor, the volume never drops near zero. Values over 1 recommended (unless you have special needs). Values less than equal to zero result in really weird behavior. Increasing the minimum distance pushes the start of the attenuation further. It also causes the curve to change. Note that the minimum distance must be above 0. The maximum distance simply cuts the attenuation at the volume level it has reached at that point.

Bus

import "luxe: audio" for Bus

no docs found

Bus.set_channels(bus: AudioBus, value: Num) returns None

Set the number of channels for the bus

Bus.set_volume(bus: AudioBus, value: Num) returns None

Set the volume for the bus

Bus.get_volume(bus: AudioBus) returns Num

Get the volume for the bus