Libraries.Sound.Audio Documentation

The Audio class can be used to play sound files and change how they are played. Before playing audio, a file must be loaded first. For most audio, this is done with a normal Load action. If you want to load a long audio file, like a song or music, you can use the advanced LoadToStream action instead. The Audio class will support audio files with the .wav or .ogg extensions. If you try to load a different file type, or try to play audio before you've loaded a file, a generic runtime Error will be thrown. After you're done with the Audio, you should call Dispose() to let the system know you're done with the file.

Example Code



use Libraries.Sound.Audio
use Libraries.System.File

// We need to first create Audio and File objects to use.
Audio audio
File file

// We have to set our file so its path is the file we want to use for Audio.
// When writing your own code, test.wav should be replaced with your file.
file:SetPath("test.wav")

// Now that our file is set up, we can load that file as audio.
audio:Load(file)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

Inherits from: Libraries.Language.Object

Actions Documentation

AddToQueue(Libraries.Sound.AudioSamples samples)

The AddToQueue action adds AudioSamples to the end of the data stored in this Audio object. To use this, the Audio must have been initialized using LoadToStream using an AudioSamples object, or must not have been initialized yet. This action can't be combined with actions that load a file into the Audio.

Parameters

Example



use Libraries.Sound.AudioSamples
use Libraries.Sound.Audio

Audio audio

AudioSamples samples1
AudioSamples samples2
AudioSamples samples3

samples1:Load("Sonata-Part1.ogg")
samples2:Load("Sonata-Part2.ogg")
samples3:Load("Sonata-Part3.ogg")

audio:LoadToStream(samples1)
audio:AddToQueue(samples2)
audio:AddToQueue(samples3)

audio:Play()
repeat while audio:IsPlaying()
    audio:Stream()
end

Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns an integer. The result is larger if this hash code is larger than the object passed as a parameter, smaller, or equal. In this case, -1 means smaller, 0 means equal, and 1 means larger. This action was changed in Quorum 7 to return an integer, instead of a CompareResult object, because the previous implementation was causing efficiency issues.

Parameters

Return

integer: The Compare result, Smaller, Equal, or Larger.

Example

Object o
Object t
integer result = o:Compare(t) //1 (larger), 0 (equal), or -1 (smaller)

DisableDoppler()

DisableDoppler will stop the audio from automatically calculating doppler shift.

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Sound.wav")

// The doppler effect is only noticable if the audio has velocity.
audio:SetVelocity(4, 0, -2)

// Because we disable the doppler effect here, the velocity we just set will
// have no effect.
audio:DisableDoppler()

DisableListenerDoppler()

DisableListenerDoppler will make the audio engine stop using the velocity of the listener when calculating doppler effect. This will NOT stop the engine from using the velocity of other audio objects that do have doppler enabled when calculating the doppler shift. The listener is universal to all audio objects, so disabling doppler effect on the listener will be in effect during calculation of doppler shift for ALL audio objects.

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Whale.wav")

// In order to hear the doppler effect in action, the listener needs
// to have velocity.
audio:SetListenerVelocity(5, 0, 4)

// Because we are now disabling the doppler effect on the listener, the
// velocity we gave it will have no effect.
audio:DisableListenerDoppler()

DisableLooping()

DisableLooping will ensure that an audio file stops playing when it reaches the end of the sound, instead of repeating. This is the default behavior, so it is only necessary to call this if there was a call to EnableLooping earlier in the program.

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We need to load our audio before we change whether or not it will loop.
audio:Load("test.wav")

// We now enable looping. This will make the sound repeat forever until we
// stop it or call "audio:DisableLooping()".
audio:EnableLooping()

// Our audio is currently set to loop. We can disable it again using DisableLooping().
audio:DisableLooping()

Dispose()

The Dispose action will stop a sound if it is playing and then free the memory that is in use by the computer. You should always use Dispose after you are finished with a sound or at the end of your program to let the computer know you are done with the audio file. After calling Dispose from an audio object, you can then load a new audio file into it.

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// In this example, we'll use LoadToStream, but Dispose can also be called
// on audio files prepared using Load!
audio:LoadToStream("Sounds/LongSong.ogg")

audio:Play()

repeat while audio:IsPlaying()
    audio:Stream()
end

// At this point, the entire song will be done playing, so we can Dispose
// the audio to let the system know we're done playing that audio file.
audio:Dispose()

EnableDoppler()

EnableDoppler will make the audio automatically calculate doppler shift for this audio. Doppler is enabled by default for audio, but will have no effect until the user provides the velocity of the audio via an action, such as SetVelocity(Vector3).

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Sound.wav")

// We need to set the velocity of the audio in order to hear the doppler effect.
audio:SetVelocity(4, 0, -2)

// Doppler is already enabled by default, so this call would only be needed
// if we had previously disabled the doppler effect on this audio.
audio:EnableDoppler()

EnableListenerDoppler()

EnableListenerDoppler will make the audio engine consider the velocity of the listener when calculating doppler effects. The listener is universal to all audio objects, which means that if you enable doppler calculations for the listener, it will enable it when calculating doppler for ALL audio objects. By default, the listener already has doppler enabled, but this will have no effect until the listener is given a velocity.

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Whale.wav")

// In order to hear the doppler effect in action, the listener needs
// to have velocity.
audio:SetListenerVelocity(5, 0, 4)

// We now enable the doppler effect for the listener -- by default, this
// is already on, so this is only needed if we'd previously disabled it.
audio:EnableListenerDoppler()

EnableLooping()

EnableLooping will set the audio to continuously repeat itself when reaching the end of the audio instead of stopping.

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We need to load our audio before we change whether or not it will loop.
audio:Load("test.wav")

// We now enable looping. This will make the sound repeat forever until we
// stop it or call "audio:DisableLooping()".
audio:EnableLooping()

Equals(Libraries.Language.Object object)

This action determines if two objects are equal based on their hash code values.

Parameters

Return

boolean: True if the hash codes are equal and false if they are not equal.

Example

use Libraries.Language.Object
use Libraries.Language.Types.Text
Object o
Text t
boolean result = o:Equals(t)

GetBalance()

GetBalance will return the current balance value of the sound. A value of -1 represents audio fully from the left speaker. A value of 1 represents audio fully from the right speaker. A value of 0 represents audio equally from both speakers.

Return

number:

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("ding.wav")

// For this example, we will set the balance to -1.
audio:SetBalance(-1)

// We can get the balance back as a number using the GetBalance() action.
number balance = audio:GetBalance()

GetCurrentAudioSamples()

This action returns which AudioSample is currently queued when used on an Audio object that is streaming AudioSamples.

Return

Libraries.Sound.AudioSamples: The currently queued AudioSamples.

GetDefaultMaximumVolumeDistance()

This action returns the default maximum volume distance for all newly created Audio objects. It will not change the maximum volume distance of any Audio objects that have already been loaded.

Return

number: The default maximum volume distance to use for all newly loaded Audio objects.

Example



use Libraries.Sound.Audio

Audio audio1
Audio audio2

// We test to see what the default maximum volume distance is using audio1.
output "The default rolloff rate is " + audio1:GetDefaultMaximumVolumeDistance()

audio2:SetDefaultMaximumVolumeDistance(0.5)

// Even though we changed the default max volume distance using audio2,
// we can still see the changed default using audio1.
output "Now the default rolloff rate is " + audio1:GetDefaultMaximumVolumeDistance()

GetDefaultRolloffRate()

This action returns the default rolloff rate of newly loaded Audio objects. It can be changed using the SetDefaultRolloffRate action. The default value is shared across all Audio objects.

Return

number:

Example



use Libraries.Sound.Audio

Audio audio1
Audio audio2

// We test to see what the default rolloff rate is using audio1.
output "The default rolloff rate is " + audio1:GetDefaultRolloffRate()

audio2:SetDefaultRolloffRate(0.5)

// Even though we changed the default rolloff rate using audio2,
// we can still see the changed default using audio1.
output "Now the default rolloff rate is " + audio1:GetDefaultRolloffRate()

GetFade()

GetFade will return the current fade value of the sound. A value of -1 represents audio fully from the rear channel. A value of 1 represents audio fully from the front channel. A value of 0 represents audio equally from both channels.

Return

number:

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("ding.wav")

// For this example, we will set the fade to -1.
audio:SetFade(-1)

// We can get the fade back as a number using the GetFade() action.
number fade = audio:GetFade()

GetHashCode()

This action gets the hash code for an object.

Return

integer: The integer hash code of the object.

Example

Object o
integer hash = o:GetHashCode()

GetListenerDirection()

This action will get the direction that the listener is currently facing in.

Return

Libraries.Compute.Vector3:

Example



use Libraries.Sound.Audio
use Libraries.Compute.Vector3

// We load an audio object and set its position to 1 meter in front of the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 0, 1)

// Now we set the listener to face the right by calling SetListenerDirection.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerDirection(1, 0, 0)

// The audio is now located to the left of the listener's "ears", so when we
// play it, it should play through the left speaker.
audio:PlayUntilDone()

// Once we've set the direction of the listener, we can get back each
// of the values we've set it with using the GetListenerDirection actions.
// We can do this using any Audio object - it won't affect the result.
Vector3 direction = audio:GetListenerDirection()
output "The direction of the listener is " + direction:GetX() + ", " + direction:GetY() + ", " + direction:GetZ()

GetListenerDirectionX()

This action will get the x-component of the direction that the listener is currently facing in.

Return

number:

Example



use Libraries.Sound.Audio

// We load an audio object and set its position to 1 meter in front of the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 0, 1)

// Now we set the listener to face the right by calling SetListenerDirection.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerDirection(1, 0, 0)

// The audio is now located to the left of the listener's "ears", so when we
// play it, it should play through the left speaker.
audio:PlayUntilDone()

// Once we've set the direction of the listener, we can get back each
// of the values we've set it with using the GetListenerDirection actions.
// We can do this using any Audio object - it won't affect the result.
number x = audio:GetListenerDirectionX()
output "The direction of the listener on the x-axis is " + x

GetListenerDirectionY()

This action will get the y-component of the direction that the listener is currently facing in.

Return

number:

Example



use Libraries.Sound.Audio

// We load an audio object and set its position to 1 meter in front of the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 0, 1)

// Now we set the listener to face the right by calling SetListenerDirection.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerDirection(1, 0, 0)

// The audio is now located to the left of the listener's "ears", so when we
// play it, it should play through the left speaker.
audio:PlayUntilDone()

// Once we've set the direction of the listener, we can get back each
// of the values we've set it with using the GetListenerDirection actions.
// We can do this using any Audio object - it won't affect the result.
number y = audio:GetListenerDirectionY()
output "The direction of the listener on the y-axis is " + y

GetListenerDirectionZ()

This action will get the z-component of the direction that the listener is currently facing in.

Return

number:

Example



use Libraries.Sound.Audio

// We load an audio object and set its position to 1 meter in front of the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 0, 1)

// Now we set the listener to face the right by calling SetListenerDirection.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerDirection(1, 0, 0)

// The audio is now located to the left of the listener's "ears", so when we
// play it, it should play through the left speaker.
audio:PlayUntilDone()

// Once we've set the direction of the listener, we can get back each
// of the values we've set it with using the GetListenerDirection actions.
// We can do this using any Audio object - it won't affect the result.
number z = audio:GetListenerDirectionZ()
output "The direction of the listener on the z-axis is " + z

GetListenerPosition()

This action will return the current coordinates of the listener in virtual 3D space. The returned result will be stored in a new Vector3.

Return

Libraries.Compute.Vector3:

Example



use Libraries.Sound.Audio
use Libraries.Compute.Vector3

// In this example, we will use two audio objects. 
Audio buzzer
buzzer:Load("Buzzer.wav")
Audio bell
bell:Load("Bell.ogg")

// We will now set the listener's position. Although we can set all 3
// coordinates with this action, we will set just the x-coordinate for
// this example. This is the same as using SetListenerX(3)
Vector3 vector
vector:Set(3, 0, 0)
buzzer:SetListenerPosition(vector)

// Now when we play our audio, both sounds should come from the left
// side in 3D space - this is because both sounds are at their default
// location of 0, 0, 0, but the listener is 3 units to the right.
buzzer:PlayUntilDone()
bell:PlayUntilDone()

// We can get the listener's position back by using GetListenerPosition.
// It doesn't matter what Audio object we call this from - the result is the same.
Vector3 position = bell:GetListenerPosition()
output "Listener position is " + position:GetX() + ", " + position:GetY() + ", " + position:GetZ()

GetListenerUp()

This action will get the direction that the listener currently considers "up".

Return

Libraries.Compute.Vector3:

Example



use Libraries.Sound.Audio
use Libraries.Compute.Vector3

// We load an audio object and set its position to 1 meter above the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 1, 0)

// The listener's default direction is straight forward, with the "up" direction
// being along the positive y-axis. For this example, we'll set the "up"
// direction to be along the negative x-axis. This effectively means the
// listener is lying on their left side, with their left ear pointed towards the
// ground and their right ear pointed up towards the sky.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerUp(-1, 0, 0)

// Although the sound is located above the listener, since the listener has
// their right ear pointed upwards, the audio will play through the right speaker.
audio:PlayUntilDone()

// We can retrieve the direction the listener considers to be "up" at
// any time by using the GetListenerUp actions. Just like setting the
// "up", it doesn't matter which Audio object is used to retrieve it.
Vector3 up = audio:GetListenerUp()
output "The up direction of the audio along the x-axis is " + up:GetX() + ", " + up:GetY() + ", " + up:GetZ()

GetListenerUpX()

This action will get the x-component of the direction that the listener currently considers "up".

Return

number:

Example



use Libraries.Sound.Audio

// We load an audio object and set its position to 1 meter above the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 1, 0)

// The listener's default direction is straight forward, with the "up" direction
// being along the positive y-axis. For this example, we'll set the "up"
// direction to be along the negative x-axis. This effectively means the
// listener is lying on their left side, with their left ear pointed towards the
// ground and their right ear pointed up towards the sky.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerUp(-1, 0, 0)

// Although the sound is located above the listener, since the listener has
// their right ear pointed upwards, the audio will play through the right speaker.
audio:PlayUntilDone()

// We can retrieve the direction the listener considers to be "up" at
// any time by using the GetListenerUp actions. Just like setting the
// "up", it doesn't matter which Audio object is used to retrieve it.
number x = audio:GetListenerUpX()
output "The up direction of the audio along the x-axis is " + x

GetListenerUpY()

This action will get the y-component of the direction that the listener currently considers "up".

Return

number:

Example



use Libraries.Sound.Audio

// We load an audio object and set its position to 1 meter above the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 1, 0)

// The listener's default direction is straight forward, with the "up" direction
// being along the positive y-axis. For this example, we'll set the "up"
// direction to be along the negative x-axis. This effectively means the
// listener is lying on their left side, with their left ear pointed towards the
// ground and their right ear pointed up towards the sky.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerUp(-1, 0, 0)

// Although the sound is located above the listener, since the listener has
// their right ear pointed upwards, the audio will play through the right speaker.
audio:PlayUntilDone()

// We can retrieve the direction the listener considers to be "up" at
// any time by using the GetListenerUp actions. Just like setting the
// "up", it doesn't matter which Audio object is used to retrieve it.
number y = audio:GetListenerUpY()
output "The up direction of the audio along the y-axis is " + y

GetListenerUpZ()

This action will get the z-component of the direction that the listener currently considers "up".

Return

number:

Example



use Libraries.Sound.Audio

// We load an audio object and set its position to 1 meter above the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 1, 0)

// The listener's default direction is straight forward, with the "up" direction
// being along the positive y-axis. For this example, we'll set the "up"
// direction to be along the negative x-axis. This effectively means the
// listener is lying on their left side, with their left ear pointed towards the
// ground and their right ear pointed up towards the sky.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerUp(-1, 0, 0)

// Although the sound is located above the listener, since the listener has
// their right ear pointed upwards, the audio will play through the right speaker.
audio:PlayUntilDone()

// We can retrieve the direction the listener considers to be "up" at
// any time by using the GetListenerUp actions. Just like setting the
// "up", it doesn't matter which Audio object is used to retrieve it.
number z = audio:GetListenerUpZ()
output "The up direction of the audio along the z-axis is " + z

GetListenerVelocity()

This action will return the current velocity of the listener in virtual 3D space. The returned result will be stored in a new Vector3.

Return

Libraries.Compute.Vector3:

Example



use Libraries.Sound.Audio
use Libraries.Compute.Vector3

Audio flute
flute:Load("Flute.ogg")

Vector3 vector
vector:Set(15, 8, 11)

// The listener is given a velocity of 15 meters per second along the
// x-axis, 8 meters per second along the y-axis, and 11 meters-per-second
// along the z-axis.
flute:SetListenerVelocity(vector)

// We can now retrieve the velocity of the listener by using
// GetListenerVelocity. It doesn't matter what Audio object we
// call this from - the result is the same.
Vector3 velocity = flute:GetListenerVelocity()
output "The listener's velocity is " + velocity:GetX() + ", " + velocity:GetY() + ", " + velocity:GetZ()

GetListenerVelocityX()

This action will return the current x velocity of the listener in virtual 3D space.

Return

number:

Example



use Libraries.Sound.Audio

Audio flute
flute:Load("Flute.ogg")

// The listener is given a velocity of 15 meters per second along the
// x-axis.
flute:SetListenerVelocityX(15)

// We can now retrieve the velocity of the listener along the x-axis by
// using GetListenerVelocityX. It doesn't matter what Audio object we
// call this from - the result is the same.
number x = flute:GetListenerVelocityX()
output "The listener's x velocity is " + x

GetListenerVelocityY()

This action will return the current y velocity of the listener in virtual 3D space.

Return

number:

Example



use Libraries.Sound.Audio

Audio flute
flute:Load("Flute.ogg")

// The listener is given a velocity of 8 meters per second along the
// y-axis.
flute:SetListenerVelocityY(8)

// We can now retrieve the velocity of the listener along the y-axis by
// using GetListenerVelocityY. It doesn't matter what Audio object we
// call this from - the result is the same.
number y = flute:GetListenerVelocityY()
output "The listener's y velocity is " + y

GetListenerVelocityZ()

This action will return the current z velocity of the listener in virtual 3D space.

Return

number:

Example



use Libraries.Sound.Audio

Audio flute
flute:Load("Flute.ogg")

// The listener is given a velocity of 11 meters per second along the
// z-axis.
flute:SetListenerVelocityZ(11)

// We can now retrieve the velocity of the listener along the z-axis by
// using GetListenerVelocityZ. It doesn't matter what Audio object we
// call this from - the result is the same.
number z = flute:GetListenerVelocityZ()
output "The listener's z velocity is " + z

GetListenerX()

This action will return the current x coordinate of the listener in virtual 3D space.

Return

number:

Example



use Libraries.Sound.Audio

// In this example, we will use two audio objects. 
Audio buzzer
buzzer:Load("Buzzer.wav")
Audio bell
bell:Load("Bell.ogg")

// We will now set the listener's x position. We could do this with
// either of our audio objects.
buzzer:SetListenerX(3)

// Now when we play our audio, both sounds should come from the left
// side in 3D space - this is because both sounds are at their default
// location of 0, 0, 0, but the listener is 3 units to the right.
buzzer:PlayUntilDone()
bell:PlayUntilDone()

// We can get the listener's x position back by using GetListenerX.
// It doesn't matter what Audio object we call this from - the result is the same.
number x = bell:GetListenerX()
output "Listener x position is " + x

GetListenerY()

This action will return the current x coordinate of the listener in virtual 3D space.

Return

number:

Example



use Libraries.Sound.Audio

// In this example, we will use two audio objects. 
Audio buzzer
buzzer:Load("Buzzer.wav")
Audio bell
bell:Load("Bell.ogg")

// We will now set the listener's x position. We could do this with
// either of our audio objects.
buzzer:SetListenerX(3)

// Now when we play our audio, both sounds should come from the left
// side in 3D space - this is because both sounds are at their default
// location of 0, 0, 0, but the listener is 3 units to the right.
buzzer:PlayUntilDone()
bell:PlayUntilDone()

// We can get the listener's y position back by using GetListenerY.
// It doesn't matter what Audio object we call this from - the result is the same.
number y = bell:GetListenerY()
output "Listener y position is " + y

GetListenerZ()

This action will return the current x coordinate of the listener in virtual 3D space.

Return

number:

Example



use Libraries.Sound.Audio

// In this example, we will use two audio objects. 
Audio buzzer
buzzer:Load("Buzzer.wav")
Audio bell
bell:Load("Bell.ogg")

// We will now set the listener's x position. We could do this with
// either of our audio objects.
buzzer:SetListenerX(3)

// Now when we play our audio, both sounds should come from the left
// side in 3D space - this is because both sounds are at their default
// location of 0, 0, 0, but the listener is 3 units to the right.
buzzer:PlayUntilDone()
bell:PlayUntilDone()

// We can get the listener's z position back by using GetListenerZ.
// It doesn't matter what Audio object we call this from - the result is the same.
number z = bell:GetListenerZ()
output "Listener z position is " + z

GetMaximumVolumeDistance()

The GetMaximumVolumeDistance action returns how far away the listener may be from the Audio and still hear the Audio at full volume. When a new Audio object is created, its maximum volume distance is equal to the current default distance, which begins as 1.0 and can be set by calling SetDefaultMaximumVolumeDistance().

Return

number: The distance from this Audio where it may be heard at full volume.

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Chime.wav")
// Output the starting maximum volume distance of the audio.
output "The maximum volume distance is " + audio:GetMaximumVolumeDistance()

GetPitch()

Returns the currently set pitch. The default pitch value is 1.0.

Return

number: The currently set pitch value.

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Chime.wav")
// We will play the sound at 75% of its normal pitch.
audio:SetPitch(0.75)
// We can get the pitch value back using GetPitch().
output "The audio is playing at " + audio:GetPitch() + " of its normal pitch value."

GetPosition()

GetPosition will return the position of the Audio in 3D space. The position will be returned as a Vector3 object. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Return

Libraries.Compute.Vector3:

Example



use Libraries.Sound.Audio
use Libraries.Compute.Vector3

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will place the audio at the coordinates 3, -2, 5.
audio:SetPosition(3, -2, 5)

// We can get the position of the audio as a Vector3 with GetPosition().
Vector3 vector = audio:GetPosition()

GetRolloffRate()

The GetRolloffRate action returns the rate at which 3D positional audio becomes quieter when positioned far away from the listener. When an Audio object is created, its rolloff rate is equal to the default value provided by GetDefaultRolloffRate, which begins at 1.0 (but may be changed by the user). Lower rolloff rates cause the sound to fade more slowly over long distances, and higher rolloff rates cause sound to fade more quickly. The rolloff value is always positive.

Return

number: The current rolloff rate of this Audio.

Example



use Libraries.Sound.Audio

// We create and load audio1 before changing the default rolloff rate.
Audio audio1
audio1:Load("Sample1.wav")
output "Before changing the default rate, audio1 has a rolloff rate of " + audio1:GetRolloffRate()

audio1:SetDefaultRolloffRate(0.25)

// We create and load audio2 after changing the default rolloff rate.
Audio audio2
audio2:Load("Sample2.wav")
output "After changing the default rate, audio1 has a rolloff rate of " + audio1:GetRolloffRate()
output "audio2 has a rolloff rate of " + audio2:GetRolloffRate()

GetRotation()

GetRotation gets the current degree of rotation of the sound. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Return

number:

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will rotate the sound so it is to the right of
// the listener.
audio:SetRotation(90)

// We can get the rotation back as a number with GetRotation().
number rotation = audio:GetRotation()

GetSampleOffset()

This action returns how many samples have been played from the Audio. This is supported if a file has been loaded for non-streaming Audio, or if the Audio is streaming AudioSample objects. If the file is not playing or paused then this will return 0.

Return

integer: The number of samples that have been played.

GetVelocity()

GetVelocity returns a Vector3 object describing the velocity of this Audio object in 3D space. The velocity is measured in meters per second. The velocity must be set manually - it will NOT be calculated automatically!

Return

Libraries.Compute.Vector3:

GetVelocityX()

GetVelocityX returns the velocity of this Audio object along the X axis in 3D space. The velocity is measured in meters per second. The velocity must be set manually - it will NOT be calculated automatically!

Return

number:

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Tone.wav")

audio:SetVelocityX(30)

number speed = audio:GetVelocityX()

GetVelocityY()

GetVelocityY returns the velocity of this Audio object along the Y axis in 3D space. The velocity is measured in meters per second. The velocity must be set manually - it will NOT be calculated automatically!

Return

number:

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Tone.wav")

audio:SetVelocityY(30)

number speed = audio:GetVelocityY()

GetVelocityZ()

GetVelocityZ returns the velocity of this Audio object along the Z axis in 3D space. The velocity is measured in meters per second. The velocity must be set manually - it will NOT be calculated automatically!

Return

number:

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Tone.wav")

audio:SetVelocityZ(30)

number speed = audio:GetVelocityZ()

GetVolume()

The GetVolume action returns the currently set volume. A number value of 1.0 represents 100% of normal volume.

Return

number:

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("ding.wav")

// For this example, we will set the audio to 50%, or half, volume.
audio:SetVolume(0.5)

// We can get the volume back as a number using the GetVolume() action.
number volume = audio:GetVolume()

GetX()

GetX returns the current location of the sound in the X plane in virtual 3D space. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Return

number:

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will place the audio at 1.5 units to the left 
// of the listener.
audio:SetX(-1.5)

// We can get the x position of the sound as a number with GetX().
number x = audio:GetX()

GetY()

GetY returns the current location of the sound in the Y plane in virtual 3D space. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Return

number:

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will place the audio at 1.85 units in front of
// the listener.
audio:SetY(1.85)

// We can get the y position of the sound as a number with GetY().
number y = audio:GetY()

GetZ()

GetZ returns the current location of the sound in the Z plane in virtual 3D space. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Return

number:

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will place the audio at 1 unit below the listener.
audio:SetZ(-1)

// We can get the z position of the sound as a number with GetZ().
number z = audio:GetZ()

IsDopplerEnabled()

IsDopplerEnabled will return whether or not the audio is currently set to use the doppler effect while playing. Note that by default, audio will use doppler effects.

Return

boolean:

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Ping.ogg")

// We will store our result in a new boolean variable. Since we haven't
// changed the doppler for the audio, it should return it's default
// state, which is true.
boolean doppler = audio:IsDopplerEnabled()

IsListenerDopplerEnabled()

This action will return whether or not the listener is currently using its velocity during doppler shift calculations. By default, this will be true.

Return

boolean:

Example



use Libraries.Sound.Audio

Audio audio

// We'll store the value in a boolean. Because we haven't disabled the
// doppler, it should give us the default value, which is true.
boolean doppler = audio:IsListenerDopplerEnabled()

IsLoaded()

The IsLoaded action returns true if the Audio has been loaded with some data from either a file or from AudioSamples, and false if it hasn't been loaded yet.

Return

boolean: True if the Audio has been loaded, false otherwise.

Example



use Libraries.Sound.Audio

Audio audio
output "Has audio been loaded yet? " + audio:IsLoaded()
audio:Load("My_Song.wav")
output "Has the audio been loaded now? " + audio:IsLoaded()

IsLoopingEnabled()

This action will return true or false based on whether or not the audio has been set to loop.

Return

boolean:

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We need to load our audio before we change whether or not it will loop.
audio:Load("test.wav")

// We now enable looping. This will make the sound repeat forever until we
// stop it or call "audio:DisableLooping()".
audio:EnableLooping()

// To test if looping is enabled, we can use IsLoopingEnabled().
output "Looping Enabled? " + audio:IsLoopingEnabled()

IsPlaying()

IsPlaying returns a boolean based on the sound's current state. It will return true if the sound is currently playing, or return false if it is not.

Return

boolean:

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("example.ogg")

// After we load the file, we can play it with a call to Play().
audio:Play()

// Because we just told the sound to play, IsPlaying() should return true,
// so we will enter this conditional statement.
if audio:IsPlaying()
    output "The audio is playing!"
end

IsStreaming()

IsStreaming will return if an audio file was loaded as a streaming audio file. If the audio was loaded normally via the Load action, this will return false. If it was loaded with LoadToStream, it will return true.

Return

boolean:

Example



use Libraries.Sound.Audio

// We will have two audio objects for this example.
Audio audio1
Audio audio2

// Our first object will not be streamed. Our second one will be.
audio1:Load("shortSound.ogg")
audio2:LoadToStream("longSound.ogg")

// Now we'll output which of these two audio files are set for streaming.
output "Was audio1 streaming? " + audio1:IsStreaming()
output "Was audio2 streaming? " + audio2:IsStreaming()

Load(text filePath)

For convenience, Load can also be called using just a file name. This is the same as making a file, calling SetPath, and calling Load with that file. Compare the below example to the example for Load when using a file.

Parameters

  • text filePath

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// To load a file that is directly accessible from our project folder, we
// can skip making a file and just pass the fle location directly to the
// Load action.
// This will load the same "beep.ogg" file as in the previous example.
audio:Load("Sounds/beep.ogg")

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

Load(Libraries.System.File file)

The Load action will retrieve an audio file to be used by the Audio class. After we've loaded the file, we can play and stop audio, or change how it's played.

Parameters

Example



use Libraries.Sound.Audio
use Libraries.System.File

// To use audio, we'll first need to create an object for it.
Audio audio

// To load from a file, we'll also need to create one of those.
File file

// In this example, we'll load a file called "beep.ogg" from a folder called
// "Sounds" in our project.
file:SetPath("Sounds/beep.ogg")

// Now that our file is set up, we can load that file as audio.
audio:Load(file)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

Load(Libraries.Sound.AudioSamples samples)

The Load action will take the given AudioSamples and load its data into this Audio object for use.

Parameters

Example



use Libraries.Sound.AudioSamples
use Libraries.Sound.Audio

AudioSamples samples
Audio audio

samples:Load("Chime.wav")
audio:Load(samples)
audio:PlayUntilDone()

LoadToStream(Libraries.System.File file)

The LoadToStream action will prepare an audio file to be streamed. While a normal Load action makes a copy of the sound so it can be played all at once, the LoadToStream action gets sound data in small chunks without making a copy of the entire thing. To play the next "chunk" of data, use the Stream action. This is useful for long sounds or music, where it could take a long time to copy the entire audio file.

Parameters

Example



use Libraries.Sound.Audio
use Libraries.System.File

// To use audio, we'll first need to create an object for it.
Audio audio

// To load from a file, we'll also need to create one of those.
File file

// In this example, we'll load a file called "LongSong.ogg" from a folder 
// called "Sounds" in our project.
file:SetPath("Sounds/LongSong.ogg")

// Since our audio file is large, it makes sense to load it for streaming.
audio:LoadToStream(file)

// After we load the file, we can begin playing it with Play(). This will
// play the first "chunk" of data we loaded from the stream.
audio:Play()

// To play the whole song, we will need to keep loading chunks of data until
// the song is finished. To do this, we will use the repeat structure.

// This will continuously call our code until we have played the whole song.
repeat while audio:IsPlaying()
    // This will load and play the next chunk of sound data.
    audio:Stream()
end

LoadToStream(Libraries.Sound.AudioSamples samples)

The LoadToStream action will take the given AudioSamples and load it into the Audio. Additional samples can then be added to the Audio by using the AddToQueue action.

Parameters

Example



use Libraries.Sound.AudioSamples
use Libraries.Sound.Audio

Audio audio

AudioSamples samples1
AudioSamples samples2
AudioSamples samples3

samples1:Load("Sonata-Part1.ogg")
samples2:Load("Sonata-Part2.ogg")
samples3:Load("Sonata-Part3.ogg")

audio:LoadToStream(samples1)
audio:AddToQueue(samples2)
audio:AddToQueue(samples3)

audio:Play()
repeat while audio:IsPlaying()
    audio:Stream()
end

LoadToStream(text filePath)

The LoadToStream action can also be called using just a path to where a file is located for convenience. This is the same as making a file, calling SetPath, and calling LoadToStream with that file.

Parameters

  • text filePath

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// In this example, we'll load a file called "LongSong.ogg" from a folder 
// called "Sounds" in our project.
// Since our audio file is large, it makes sense to load it for streaming.
audio:LoadToStream("Sounds/LongSong.ogg")

// After we load the file, we can begin playing it with Play(). This will
// play the first "chunk" of data we loaded from the stream.
audio:Play()

// To play the whole song, we will need to keep loading chunks of data until
// the song is finished. To do this, we will use the repeat structure.

// This will continuously call our code until we have played the whole song.
repeat while audio:IsPlaying()
    // This will load and play the next chunk of sound data.
    audio:Stream()
end

Pause()

The Pause action will temporarily stop playing a sound, and remember where the sound was during its playback. Calling Resume will make the sound play again from where it was paused.

Play()

Once we've prepared our audio file with either the Load or LoadToStream actions, we can play the file. If we prepared the file with Load, using the Play action will play the entire song. If we prepared it with LoadToStream, we use Play to start the sound, then we call Stream() repeatedly to play the rest of the sound.

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We will first load a sound normally with the Load command. Most sounds
// should be loaded this way.
audio:Load("ShortSound.wav")

// After we load the file, we can play it with a call to Play().
audio:Play()

// We can also use the Play action with streamed audio.
Audio longAudio
longAudio:LoadToStream("LongSound.wav")

// Using Play() on longAudio will start the stream. We will have to keep
// calling Stream() to play the whole sound.

longAudio:Play()

repeat while longAudio:IsPlaying()
    longAudio:Stream()
end

PlayUntilDone()

If you want to make a program wait until your audio has stopped playing to continue, use the PlayUntilDone action. This action won't work on streamed audio, only on audio loaded with the Load() action. The audio file will always play just once, even if looping is enabled. If this action is used on a streaming audio file, nothing will happen.

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We will first load a sound normally with the Load command. Most sounds
// should be loaded this way.
audio:Load("ShortSound.wav")

// Now that our file is loaded, we can play the sound.
audio:PlayUntilDone()

// This output statement will be called after the entire sound has played.
output "Finished playing audio!"

RemoveFromQueue(Libraries.Sound.AudioSamples samples)

The RemoveFromQueue action removes AudioSamples from the data stored in this Audio object. To use this, the Audio must have been initialized for streaming AudioSamples, either by using LoadToStream(AudioSamples) or AddToQueue(AudioSamples). If the requested AudioSamples wasn't present in the Audio (e.g., because it was never queued or because it was queued and already played), then this action will have no effect.

Parameters

Example



use Libraries.Sound.AudioSamples
use Libraries.Sound.Audio

Audio audio

AudioSamples samples1
AudioSamples samples2
AudioSamples samples3

samples1:Load("Sonata-Part1.ogg")
samples2:Load("Sonata-Part2.ogg")
samples3:Load("Sonata-Part3.ogg")

audio:LoadToStream(samples1)
audio:AddToQueue(samples2)
audio:AddToQueue(samples3)

audio:Play()

// We can remove AudioSamples before or during Audio playback.
audio:RemoveFromQueue(samples2)

repeat while audio:IsPlaying()
    audio:Stream()
end

Resume()

The Resume action will resume playing an audio file that was paused. If the audio was not paused, this action will have no effect.

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("ding.wav")

// After we load the file, we can play it with a call to Play().
audio:Play()

// Now that audio is playing, we can pause it at any time by calling Pause.
audio:Pause()

// We can also resume the audio at any time by calling Resume.
audio:Resume()

Rotate(number rotation)

Rotate increases the degree of rotation of the sound, causing it to progress clockwise around the listener if given a positive value, or counter-clockwise around the listener if the action is given a negative value. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Parameters

  • number rotation

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will rotate the sound so it is to the right of
// the listener.
audio:Rotate(90)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

// Now we will rotate it another 180 degrees, so it will be at 270 degrees.
audio:Rotate(180)
    
// We can call PlayUntilDone() again to hear it in its new position.
audio:PlayUntilDone()

// Once we're finished with an audio file, we need to let the computer know.
audio:Dispose()

SetBalance(number position)

SetBalance will change how the sound is played through stereo speakers or headphones. Values passed to this should always be between -1 and 1. A value of -1 will make the sound play through only the left speaker. A value of 1 will play the sound only through the right speaker. A value of 0 will play the sound equally through both speakers. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Parameters

  • number position

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will set the position with the value -1. This will
// make the sound play through only the left speaker.
audio:SetBalance(-1)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

// Once we're finished with an audio file, we need to let the computer know.
audio:Dispose()

SetDefaultMaximumVolumeDistance(number distance)

This action sets the default maximum volume distance for all newly created Audio objects. It will not change the maximum volume distance of any Audio objects that have already been loaded.

Parameters

  • number distance: The default maximum volume distance to use for all newly loaded Audio objects.

Example



use Libraries.Sound.Audio

Audio audio1
Audio audio2

// We test to see what the default maximum volume distance is using audio1.
output "The default rolloff rate is " + audio1:GetDefaultMaximumVolumeDistance()

audio2:SetDefaultMaximumVolumeDistance(0.5)

// Even though we changed the default max volume distance using audio2,
// we can still see the changed default using audio1.
output "Now the default rolloff rate is " + audio1:GetDefaultMaximumVolumeDistance()

SetDefaultRolloffRate(number rolloff)

This action sets the default rolloff rate of newly loaded Audio objects. It will not change the rolloff rates of any Audio objects which have already been loaded.

Parameters

  • number rolloff: The default rolloff rate to use for all newly loaded Audio objects.

Example



use Libraries.Sound.Audio

// We create and load audio1 before changing the default rolloff rate.
Audio audio1
audio1:Load("Sample1.wav")
output "Before changing the default rate, audio1 has a rolloff rate of " + audio1:GetRolloffRate()

audio1:SetDefaultRolloffRate(0.25)

// We create and load audio2 after changing the default rolloff rate.
Audio audio2
audio2:Load("Sample2.wav")
output "After changing the default rate, audio1 has a rolloff rate of " + audio1:GetRolloffRate()
output "audio2 has a rolloff rate of " + audio2:GetRolloffRate()

SetFade(number fade)

SetFade will change how the sound is played through speakers that have forward and back channels. Values passed to this should always be between -1 and 1. A value of -1 will make the sound play through only the back channel. A value of 1 will play the sound only through the front channel. A value of 0 will play the sound equally through both channels. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Parameters

  • number fade

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will set the fade with the value 1. This will make
// the sound play through only the front channel.
audio:SetFade(1)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

// Once we're finished with an audio file, we need to let the computer know.
audio:Dispose()

SetListenerDirection(number x, number y, number z)

SetListenerDirection sets the direction the listener is facing in virtual 3D space. This will affect which direction audio seems to come through speakers or headphones when listening to 3D audio.

Parameters

  • number x
  • number y
  • number z

Example



use Libraries.Sound.Audio

// We load an audio object and set its position to 1 meter in front of the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 0, 1)

// Now we set the listener to face the right by calling SetListenerDirection.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerDirection(1, 0, 0)

// The audio is now located to the left of the listener's "ears", so when we
// play it, it should play through the left speaker.
audio:PlayUntilDone()

SetListenerDirection(Libraries.Compute.Vector3 direction)

SetListenerDirection sets the direction the listener is facing in virtual 3D space. This will affect which direction audio seems to come through speakers or headphones when listening to 3D audio.

Parameters

Example



use Libraries.Sound.Audio
use Libraries.Compute.Vector3

// We load an audio object and set its position to 1 meter in front of the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 0, 1)

// Now we set the listener to face the right by calling SetListenerDirection.
// We can do this using any Audio object - it won't affect the result.
Vector3 direction
direction:Set(1, 0, 0)
audio:SetListenerDirection(direction)

// The audio is now located to the left of the listener's "ears", so when we
// play it, it should play through the left speaker.
audio:PlayUntilDone()

SetListenerPosition(Libraries.Compute.Vector3 vector)

SetListenerPosition sets the X, Y, and Z coordinates of the listener in 3D space. When audio is played, how it sounds to the user is dependent on both the position of the audio and where the listener is positioned. The listener's position is universal to all audio - or in other words, if you change the position of the listener for one audio object, it adjusts the position of the listener for ALL audio objects.

Parameters

Example



use Libraries.Sound.Audio
use Libraries.Compute.Vector3

// In this example, we will use two audio objects. 
Audio buzzer
buzzer:Load("Buzzer.wav")
Audio bell
bell:Load("Bell.ogg")

// We will now set the listener's position. Although we can set all 3
// coordinates with this action, we will set just the x-coordinate for
// this example. This is the same as using SetListenerX(3)
Vector3 vector
vector:Set(3, 0, 0)
buzzer:SetListenerPosition(vector)

// Now when we play our audio, both sounds should come from the left
// side in 3D space - this is because both sounds are at their default
// location of 0, 0, 0, but the listener is 3 units to the right.
buzzer:PlayUntilDone()
bell:PlayUntilDone()

SetListenerPosition(number x, number y, number z)

SetListenerPosition sets the X, Y, and Z coordinates of the listener in 3D space. When audio is played, how it sounds to the user is dependent on both the position of the audio and where the listener is positioned. The listener's position is universal to all audio - or in other words, if you change the position of the listener for one audio object, it adjusts the position of the listener for ALL audio objects.

Parameters

  • number x
  • number y
  • number z

Example



use Libraries.Sound.Audio

// In this example, we will use two audio objects. 
Audio buzzer
buzzer:Load("Buzzer.wav")
Audio bell
bell:Load("Bell.ogg")

// We will now set the listener's position. Although we can set all 3
// coordinates with this action, we will set just the x-coordinate for
// this example. This is the same as using SetListenerX(3)
buzzer:SetListenerPosition(3, 0, 0)

// Now when we play our audio, both sounds should come from the left
// side in 3D space - this is because both sounds are at their default
// location of 0, 0, 0, but the listener is 3 units to the right.
buzzer:PlayUntilDone()
bell:PlayUntilDone()

SetListenerUp(number x, number y, number z)

SetListenerUp sets the direction which is considered to be directly "up" from the listener. This should always be perpendicular to the direction that the listener is facing. This is used in combination with the listener direction to determine how audio should be played through the user's speakers or headphones.

Parameters

  • number x
  • number y
  • number z

Example



use Libraries.Sound.Audio

// We load an audio object and set its position to 1 meter above the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 1, 0)

// The listener's default direction is straight forward, with the "up" direction
// being along the positive y-axis. For this example, we'll set the "up"
// direction to be along the negative x-axis. This effectively means the
// listener is lying on their left side, with their left ear pointed towards the
// ground and their right ear pointed up towards the sky.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerUp(-1, 0, 0)

// Although the sound is located above the listener, since the listener has
// their right ear pointed upwards, the audio will play through the right speaker.
audio:PlayUntilDone()

SetListenerUp(Libraries.Compute.Vector3 up)

SetListenerUp sets the direction which is considered to be directly "up" from the listener. This should always be perpendicular to the direction that the listener is facing. This is used in combination with the listener direction to determine how audio should be played through the user's speakers or headphones.

Parameters

Example



use Libraries.Sound.Audio
use Libraries.Compute.Vector3

// We load an audio object and set its position to 1 meter above the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 1, 0)

// The listener's default direction is straight forward, with the "up" direction
// being along the positive y-axis. For this example, we'll set the "up"
// direction to be along the negative x-axis. This effectively means the
// listener is lying on their left side, with their left ear pointed towards the
// ground and their right ear pointed up towards the sky.
// We can do this using any Audio object - it won't affect the result.
Vector3 up
up:Set(-1, 0, 0)
audio:SetListenerUp(up)

// Although the sound is located above the listener, since the listener has
// their right ear pointed upwards, the audio will play through the right speaker.
audio:PlayUntilDone()

SetListenerVelocity(Libraries.Compute.Vector3 vector)

SetListenerVelocity will set the listener's velocity in 3D space. Just like individual objects, the listener can have velocity, which will be used during calculation of doppler shift. The listener is universal to all audio objects, which means that setting the listener in one audio object will set it for ALL audio objects. The velocity is measured as meters per second.

Parameters

Example



use Libraries.Sound.Audio
use Libraries.Compute.Vector3

Audio flute
flute:Load("Flute.ogg")

Vector3 vector
vector:Set(15, 8, 11)

// The listener is given a velocity of 15 meters per second along the
// x-axis, 8 meters per second along the y-axis, and 11 meters-per-second
// along the z-axis.
flute:SetListenerVelocity(vector)

SetListenerVelocity(number x, number y, number z)

SetListenerVelocity will set the listener's velocity in 3D space. Just like individual objects, the listener can have velocity, which will be used during calculation of doppler shift. The listener is universal to all audio objects, which means that setting the listener in one audio object will set it for ALL audio objects. The velocity is measured as meters per second.

Parameters

  • number x
  • number y
  • number z

Example



use Libraries.Sound.Audio

Audio flute
flute:Load("Flute.ogg")

// The listener is given a velocity of 15 meters per second along the
// x-axis, 8 meters per second along the y-axis, and 11 meters-per-second
// along the z-axis.
flute:SetListenerVelocity(15, 8, 11)

SetListenerVelocityX(number x)

SetListenerVelocityX will set the listener's velocity along the x-axis. Just like individual objects, the listener can have velocity, which will be used during calculation of doppler shift. The listener is universal to all audio objects, which means that setting the listener in one audio object will set it for ALL audio objects. The velocity is measured as meters per second.

Parameters

  • number x

Example



use Libraries.Sound.Audio

Audio flute
flute:Load("Flute.ogg")

// The listener is given a velocity of 15 meters per second along the
// x-axis.
flute:SetListenerVelocityX(15)

SetListenerVelocityY(number x)

SetListenerVelocityY will set the listener's velocity along the y-axis. Just like individual objects, the listener can have velocity, which will be used during calculation of doppler shift. The listener is universal to all audio objects, which means that setting the listener in one audio object will set it for ALL audio objects. The velocity is measured as meters per second.

Parameters

  • number x

Example



use Libraries.Sound.Audio

Audio flute
flute:Load("Flute.ogg")

// The listener is given a velocity of 8 meters per second along the
// y-axis.
flute:SetListenerVelocityY(8)

SetListenerVelocityZ(number z)

SetListenerVelocityZ will set the listener's velocity along the z-axis. Just like individual objects, the listener can have velocity, which will be used during calculation of doppler shift. The listener is universal to all audio objects, which means that setting the listener in one audio object will set it for ALL audio objects. The velocity is measured as meters per second.

Parameters

  • number z

Example



use Libraries.Sound.Audio

Audio flute
flute:Load("Flute.ogg")

// The listener is given a velocity of 11 meters per second along the
// z-axis.
flute:SetListenerVelocityZ(11)

SetListenerX(number x)

SetListenerX sets the x-coordinate of the listener in 3D space. When audio is played, how it sounds to the user is dependent on both the position of the audio and where the listener is positioned. The listener's position is universal to all audio - or in other words, if you change the position of the listener for one audio object, it adjusts the position of the listener for ALL audio objects.

Parameters

  • number x

Example



use Libraries.Sound.Audio

// In this example, we will use two audio objects. 
Audio buzzer
buzzer:Load("Buzzer.wav")
Audio bell
bell:Load("Bell.ogg")

// We will now set the listener's x position. We could do this with
// either of our audio objects.
buzzer:SetListenerX(3)

// Now when we play our audio, both sounds should come from the left
// side in 3D space - this is because both sounds are at their default
// location of 0, 0, 0, but the listener is 3 units to the right.
buzzer:PlayUntilDone()
bell:PlayUntilDone()

SetListenerY(number y)

SetListenerY sets the y-coordinate of the listener in 3D space. When audio is played, how it sounds to the user is dependent on both the position of the audio and where the listener is positioned. The listener's position is universal to all audio - or in other words, if you change the position of the listener for one audio object, it adjusts the position of the listener for ALL audio objects.

Parameters

  • number y

Example



use Libraries.Sound.Audio

// In this example, we will use two audio objects. 
Audio buzzer
buzzer:Load("Buzzer.wav")
Audio bell
bell:Load("Bell.ogg")

// We will now set the listener's x position. We could do this with
// either of our audio objects.
buzzer:SetListenerY(3)

// Now when we play our audio, both sounds are affected by the new
// position of the listener.
buzzer:PlayUntilDone()
bell:PlayUntilDone()

SetListenerZ(number z)

SetListenerZ sets the z-coordinate of the listener in 3D space. When audio is played, how it sounds to the user is dependent on both the position of the audio and where the listener is positioned. The listener's position is universal to all audio - or in other words, if you change the position of the listener for one audio object, it adjusts the position of the listener for ALL audio objects.

Parameters

  • number z

Example



use Libraries.Sound.Audio

// In this example, we will use two audio objects. 
Audio buzzer
buzzer:Load("Buzzer.wav")
Audio bell
bell:Load("Bell.ogg")

// We will now set the listener's x position. We could do this with
// either of our audio objects.
buzzer:SetListenerZ(3)

// Now when we play our audio, both sounds are affected by the new
// position of the listener.
buzzer:PlayUntilDone()
bell:PlayUntilDone()

SetMaximumVolumeDistance(number distance)

The SetMaximumVolumeDistance action will determine how far the sound can be from the listener before the volume is adjusted due to distance attenuation. If the audio listener is within the maximum volume distance of the audio, the audio will play at full volume. If the listener is farther away than this distance, then distance attenuation is applied relative to how much farther the listener is than this distance. When a new Audio object is created, its maximum volume distance is equal to the current default distance, which begins as 1.0 and can be set by calling SetDefaultMaximumVolumeDistance().

Parameters

  • number distance

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Chime.wav")
// The Audio is placed 10 units away to the right of the listener.
audio:SetX(10)
// The Audio is played using its default maximum volume distance of 1 unit.
audio:PlayUntilDone()
// Now we set the maximum volume distance to 15 units. Since the listener is
// within 15 units of the sound, it will play at maximum volume.
audio:SetMaximumVolumeDistance(15)
audio:PlayUntilDone()

SetPitch(number pitch)

The SetPitch action sets the pitch of the sound. By default, sounds have a pitch value of 1.0 (or 100% normal pitch). Lower values reduce the pitch, while higher values increase the pitch. Changing the pitch also causes the audio to play slower (with low pitch) or faster (with high pitch).

Parameters

  • number pitch: The pitch value to use.

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Chime.wav")
// We will play the sound at 75% of its normal pitch.
audio:SetPitch(0.75)
audio:PlayUntilDone()

SetPosition(Libraries.Compute.Vector3 position)

SetPosition uses the X, Y, and Z coordinates contained in a Vector3 object to place the sound at a specific point in 3D virtual space. The distance and location of the sound relative to the listener's coordinates will affect the volume of the sound as well as how it plays though speakers or headphones. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Parameters

Example



use Libraries.Sound.Audio
use Libraries.Compute.Vector3

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will load our point into a Vector3 object.
Vector3 vector

// Our point will be located 2 units to the left, 4 units in front of, and 1
// unit above the listener.
vector:Set(-2, 4, 1)

// Now we can set our audio's position with the Vector3.
audio:SetPosition(vector)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

// Once we're finished with an audio file, we need to let the computer know.
audio:Dispose()

SetPosition(number newX, number newY, number newZ)

SetPosition places the sound at a specific set of X, Y, and Z coordinates in 3D virtual space. The distance and location of the sound relative to the listener's coordinates of 0, 0, 0 will affect the volume of the sound as well as how it plays though speakers or headphones. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Parameters

  • number newX
  • number newY
  • number newZ

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will place the audio at 2 units to the left, 4 units
// in front of, and 1 unit above the listener.
audio:SetPosition(-2, 4, 1)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

// Once we're finished with an audio file, we need to let the computer know.
audio:Dispose()

SetRolloffRate(number rolloff)

The SetRolloffRate action sets the rate at which 3D positional audio becomes quieter when positioned far away from the listener. When an Audio object is created, its rolloff rate is equal to the default value provided by GetDefaultRolloffRate, which begins at 1.0 (but may be changed by the user). Lower rolloff rates cause the sound to fade more slowly over long distances, and higher rolloff rates cause sound to fade more quickly. The rolloff value must always be positive.

Parameters

  • number rolloff: The rolloff rate to use. Must be positive.

Example



use Libraries.Sound.Audio

Audio audio
audio:Load("Chime.wav")
// We will play the Audio using the default rolloff factor of 1.0, first at
// 1 unit away from the listener, then at 5 units away from the listener.
audio:SetX(1)
audio:PlayUntilDone()
audio:SetX(5)
audio:PlayUntilDone()
// Now we set rolloff factor to 0.25, which will make the volume decrease 4
// times slower than the previous value of 1, and we play the Audio again.
// It should be the same volume when close (e.g. at 1 unit) but noticeably 
// louder than it was previously when it is far away (e.g. at 5 units)
audio:SetRolloffRate(0.25)
audio:SetX(1)
audio:PlayUntilDone()
audio:SetX(5)
audio:PlayUntilDone()

SetRotation(number rotation)

SetRotation sets a sound to play at a point in 3D space such that it has constant volume and is located a given number of degrees from the listener, where 0 degrees is directly in front of the listener and the sound rotates clockwise around the listener. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Parameters

  • number rotation

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will rotate the sound so it is to the right of
// the listener.
audio:SetRotation(90)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

// Once we're finished with an audio file, we need to let the computer know.
audio:Dispose()

SetVelocity(Libraries.Compute.Vector3 velocity)

SetVelocity will set the velocity of the audio in 3D space along the X, Y, and Z axes. The velocity is measured in meters per seconds, and is used to calculate doppler effects. If doppler is disabled, then the audio's velocity is ignored. Note that setting the velocity of audio will NOT automatically update the position of the audio over time!

Parameters

Example



use Libraries.Sound.Audio
use Libraries.Compute.Vector3

// To use audio, we need to create an object for it first.
Audio audio

// In this example, we will set the velocity using a Vector3 object.
Vector3 velocity

// We always have to load a sound before use.
audio:Load("Car.wav")

// We can now set our vector with our velocity. All numbers are measured
// in meters per second.
velocity:Set(20, 5, 8)

// Now we set the velocity of our audio using our vector.
audio:SetVelocity(velocity)

SetVelocity(number x, number y, number z)

SetVelocity will set the velocity of the audio in 3D space along the X, Y, and Z axes. The velocity is measured in meters per seconds, and is used to calculate doppler effects. If doppler is disabled, then the audio's velocity is ignored. Note that setting the velocity of audio will NOT automatically update the position of the audio over time!

Parameters

  • number x
  • number y
  • number z

Example



use Libraries.Sound.Audio

// To use audio, we need to create an object for it first.
Audio audio

// We always have to load a sound before use.
audio:Load("Car.wav")

// Now we set the velocity of our audio. All numbers are measured in
// meters per second.
audio:SetVelocity(20, 5, 8)

SetVelocityX(number x)

SetVelocityX will set the velocity of the audio along the x-axis in 3D space. The velocity is measured in meters per seconds, and is used to calculate doppler effects. If doppler is disabled, then the audio's velocity is ignored. Note that setting the velocity of audio will NOT automatically update the position of the audio over time!

Parameters

  • number x

Example



use Libraries.Sound.Audio

// To use audio, we need to create an object for it first.
Audio audio

// We always have to load a sound before use.
audio:Load("Car.wav")

// For this example, we will make the sound move 20 meters per second
// to the left.
audio:SetVelocityX(20)

SetVelocityY(number y)

SetVelocityY will set the velocity of the audio along the y-axis in 3D space. The velocity is measured in meters per seconds, and is used to calculate doppler effects. If doppler is disabled, then the audio's velocity is ignored. Note that setting the velocity of audio will NOT automatically update the position of the audio over time!

Parameters

  • number y

Example



use Libraries.Sound.Audio

// To use audio, we need to create an object for it first.
Audio audio

// We always have to load a sound before use.
audio:Load("Car.wav")

// For this example, we will make the sound move 20 meters per second
// along the y-axis.
audio:SetVelocityY(20)

SetVelocityZ(number z)

SetVelocityZ will set the velocity of the audio along the z-axis in 3D space. The velocity is measured in meters per seconds, and is used to calculate doppler effects. If doppler is disabled, then the audio's velocity is ignored. Note that setting the velocity of audio will NOT automatically update the position of the audio over time!

Parameters

  • number z

Example



use Libraries.Sound.Audio

// To use audio, we need to create an object for it first.
Audio audio

// We always have to load a sound before use.
audio:Load("Car.wav")

// For this example, we will make the sound move 20 meters per second
// along the z-axis.
audio:SetVelocityZ(20)

SetVolume(number volume)

The SetVolume action adjusts the volume of a sound. It takes a number value to set the volume to a percentage of the original sound volume. A value of 1.0 will play the sound at 100% of standard volume. To reduce the sound by 25%, for example, you would provide the number 0.75, or 75% volume.

Parameters

  • number volume

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("ding.wav")

// For this example, we will set the audio to 50%, or half, volume.
audio:SetVolume(0.5)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

// Once we're finished with an audio file, we need to let the computer know.
audio:Dispose()

SetX(number newX)

SetX places the sound at a specific X coordinate in 3D virtual space. The distance and location of the sound relative to the listener's coordinates of 0, 0, 0 will affect the volume of the sound as well as how it plays though speakers or headphones. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Parameters

  • number newX

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will place the audio at 2.5 units to the right of
// the listener. 
audio:SetX(2.5)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

// Once we're finished with an audio file, we need to let the computer know.
audio:Dispose()

SetY(number newY)

SetY places the sound at a specific Y coordinate in 3D virtual space. The distance and location of the sound relative to the listener's coordinates of 0, 0, 0 will affect the volume of the sound as well as how it plays though speakers or headphones. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Parameters

  • number newY

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will place the audio at 1 unit behind the listener.
audio:SetY(-1)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

// Once we're finished with an audio file, we need to let the computer know.
audio:Dispose()

SetZ(number newZ)

SetZ places the sound at a specific Z coordinate in 3D virtual space. The distance and location of the sound relative to the listener's coordinates of 0, 0, 0 will affect the volume of the sound as well as how it plays though speakers or headphones. Using Balance, Fade, Rotation, or X,Y,Z coordinates are all exclusive of each other, and using one will override any others used previously.

Parameters

  • number newZ

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("noise.ogg")

// For this example, we will place the audio at 1.5 units above the listener.
audio:SetZ(1.5)

// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()

// Once we're finished with an audio file, we need to let the computer know.
audio:Dispose()

Stop()

The Stop action will stop audio if it is currently playing. If it is not playing, it will do nothing.

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// We always have to load a sound before use.
audio:Load("ding.wav")

// After we load the file, we can play it with a call to Play().
audio:Play()

// Now that audio is playing, we can stop it at any time by calling Stop().
audio:Stop()

Stream()

The Stream action is used to load and play the next chunk of data for a file that was prepared using LoadToStream. To play an audio file smoothly this way, Stream should be called in a loop. When the entire audio file has been played, if looping is disabled it will stop playing. If looping is enabled, it will continue playing.

Example



use Libraries.Sound.Audio

// To use audio, we'll first need to create an object for it.
Audio audio

// In this example, we'll load a file called "LongSong.ogg" from a folder 
// called "Sounds" in our project.
// Since our audio file is large, it makes sense to load it for streaming.
audio:LoadToStream("Sounds/LongSong.ogg")

// After we load the file, we can begin playing it with Play(). This will
// play the first "chunk" of data we loaded from the stream.
audio:Play()

// To play the whole song, we will need to keep loading chunks of data until
// the song is finished. To do this, we will use the repeat structure.

// This will continuously call our code until we have played the whole song.
repeat while audio:IsPlaying()
    // This will load and play the next chunk of sound data.
    audio:Stream()
end