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

Summary

Actions Summary Table

ActionsDescription
AddToQueue(Libraries.Sound.AudioSamples samples)The AddToQueue action adds AudioSamples to the end of the data stored in this Audio object.
Compare(Libraries.Language.Object object)This action compares two object hash codes and returns a CompareResult.
DisableDoppler()DisableDoppler will stop the audio from automatically calculating doppler shift.
DisableListenerDoppler()DisableListenerDoppler will make the audio engine stop using the velocity of the listener when calculating doppler effect.
DisableLooping()DisableLooping will ensure that an audio file stops playing when it reaches the end of the sound, instead of repeating.
Dispose()The Dispose action will stop a sound if it is playing and then free the memory that is in use by the computer.
EnableDoppler()EnableDoppler will make the audio automatically calculate doppler shift for this audio.
EnableListenerDoppler()EnableListenerDoppler will make the audio engine consider the velocity of the listener when calculating doppler effects.
EnableLooping()EnableLooping will set the audio to continuously repeat itself when reaching the end of the audio instead of stopping.
Equals(Libraries.Language.Object object)This action determines if two objects are equal based on their hash code values.
GetBalance()GetBalance will return the current balance value of the sound.
GetCurrentAudioSamples()This action returns which AudioSample is currently queued when used on an Audio object that is streaming AudioSamples.
GetDefaultMaximumVolumeDistance()This action returns the default maximum volume distance for all newly created Audio objects.
GetDefaultRolloffRate()This action returns the default rolloff rate of newly loaded Audio objects.
GetFade()GetFade will return the current fade value of the sound.
GetHashCode()This action gets the hash code for an object.
GetListenerDirection()This action will get the direction that the listener is currently facing in.
GetListenerDirectionX()This action will get the x-component of the direction that the listener is currently facing in.
GetListenerDirectionY()This action will get the y-component of the direction that the listener is currently facing in.
GetListenerDirectionZ()This action will get the z-component of the direction that the listener is currently facing in.
GetListenerPosition()This action will return the current coordinates of the listener in virtual 3D space.
GetListenerUp()This action will get the direction that the listener currently considers "up".
GetListenerUpX()This action will get the x-component of the direction that the listener currently considers "up".
GetListenerUpY()This action will get the y-component of the direction that the listener currently considers "up".
GetListenerUpZ()This action will get the z-component of the direction that the listener currently considers "up".
GetListenerVelocity()This action will return the current velocity of the listener in virtual 3D space.
GetListenerVelocityX()This action will return the current x velocity of the listener in virtual 3D space.
GetListenerVelocityY()This action will return the current y velocity of the listener in virtual 3D space.
GetListenerVelocityZ()This action will return the current z velocity of the listener in virtual 3D space.
GetListenerX()This action will return the current x coordinate of the listener in virtual 3D space.
GetListenerY()This action will return the current x coordinate of the listener in virtual 3D space.
GetListenerZ()This action will return the current x coordinate of the listener in virtual 3D space.
GetMaximumVolumeDistance()The GetMaximumVolumeDistance action returns how far away the listener may be from the Audio and still hear the Audio at full volume.
GetPitch()Returns the currently set pitch.
GetPosition()GetPosition will return the position of the Audio in 3D space.
GetRolloffRate()The GetRolloffRate action returns the rate at which 3D positional audio becomes quieter when positioned far away from the listener.
GetRotation()GetRotation gets the current degree of rotation of the sound.
GetSampleOffset()This action returns how many samples have been played from the Audio.
GetVelocity()GetVelocity returns a Vector3 object describing the velocity of this Audio object in 3D space.
GetVelocityX()GetVelocityX returns the velocity of this Audio object along the X axis in 3D space.
GetVelocityY()GetVelocityY returns the velocity of this Audio object along the Y axis in 3D space.
GetVelocityZ()GetVelocityZ returns the velocity of this Audio object along the Z axis in 3D space.
GetVolume()The GetVolume action returns the currently set volume.
GetX()GetX returns the current location of the sound in the X plane in virtual 3D space.
GetY()GetY returns the current location of the sound in the Y plane in virtual 3D space.
GetZ()GetZ returns the current location of the sound in the Z plane in virtual 3D space.
IsDopplerEnabled()IsDopplerEnabled will return whether or not the audio is currently set to use the doppler effect while playing.
IsListenerDopplerEnabled()This action will return whether or not the listener is currently using its velocity during doppler shift calculations.
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.
IsLoopingEnabled()This action will return true or false based on whether or not the audio has been set to loop.
IsPlaying()IsPlaying returns a boolean based on the sound's current state.
IsStreaming()IsStreaming will return if an audio file was loaded as a streaming audio file.
Load(text filePath)For convenience, Load can also be called using just a file name.
Load(Libraries.System.File file)The Load action will retrieve an audio file to be used by the Audio class.
Load(Libraries.Sound.AudioSamples samples)The Load action will take the given AudioSamples and load its data into this Audio object for use.
LoadToStream(Libraries.System.File file)The LoadToStream action will prepare an audio file to be streamed.
LoadToStream(Libraries.Sound.AudioSamples samples)The LoadToStream action will take the given AudioSamples and load it into the Audio.
LoadToStream(text filePath)The LoadToStream action can also be called using just a path to where a file is located for convenience.
Pause()The Pause action will temporarily stop playing a sound, and remember where the sound was during its playback.
Play()Once we've prepared our audio file with either the Load or LoadToStream actions, we can play the file.
PlayUntilDone()If you want to make a program wait until your audio has stopped playing to continue, use the PlayUntilDone action.
RemoveFromQueue(Libraries.Sound.AudioSamples samples)The RemoveFromQueue action removes AudioSamples from the data stored in this Audio object.
Resume()The Resume action will resume playing an audio file that was paused.
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.
SetBalance(number position)SetBalance will change how the sound is played through stereo speakers or headphones.
SetDefaultMaximumVolumeDistance(number distance)This action sets the default maximum volume distance for all newly created Audio objects.
SetDefaultRolloffRate(number rolloff)This action sets the default rolloff rate of newly loaded Audio objects.
SetFade(number fade)SetFade will change how the sound is played through speakers that have forward and back channels.
SetListenerDirection(number x, number y, number z)SetListenerDirection sets the direction the listener is facing in virtual 3D space.
SetListenerDirection(Libraries.Compute.Vector3 direction)SetListenerDirection sets the direction the listener is facing in virtual 3D space.
SetListenerPosition(Libraries.Compute.Vector3 vector)SetListenerPosition sets the X, Y, and Z coordinates of the listener in 3D space.
SetListenerPosition(number x, number y, number z)SetListenerPosition sets the X, Y, and Z coordinates of the listener in 3D space.
SetListenerUp(number x, number y, number z)SetListenerUp sets the direction which is considered to be directly "up" from the listener.
SetListenerUp(Libraries.Compute.Vector3 up)SetListenerUp sets the direction which is considered to be directly "up" from the listener.
SetListenerVelocity(Libraries.Compute.Vector3 vector)SetListenerVelocity will set the listener's velocity in 3D space.
SetListenerVelocity(number x, number y, number z)SetListenerVelocity will set the listener's velocity in 3D space.
SetListenerVelocityX(number x)SetListenerVelocityX will set the listener's velocity along the x-axis.
SetListenerVelocityY(number x)SetListenerVelocityY will set the listener's velocity along the y-axis.
SetListenerVelocityZ(number z)SetListenerVelocityZ will set the listener's velocity along the z-axis.
SetListenerX(number x)SetListenerX sets the x-coordinate of the listener in 3D space.
SetListenerY(number y)SetListenerY sets the y-coordinate of the listener in 3D space.
SetListenerZ(number z)SetListenerZ sets the z-coordinate of the listener in 3D space.
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.
SetPitch(number pitch)The SetPitch action sets the pitch of the sound.
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.
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.
SetRolloffRate(number rolloff)The SetRolloffRate action sets the rate at which 3D positional audio becomes quieter when positioned far away from the listener.
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.
SetVelocity(Libraries.Compute.Vector3 velocity)SetVelocity will set the velocity of the audio in 3D space along the X, Y, and Z axes.
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.
SetVelocityX(number x)SetVelocityX will set the velocity of the audio along the x-axis in 3D space.
SetVelocityY(number y)SetVelocityY will set the velocity of the audio along the y-axis in 3D space.
SetVelocityZ(number z)SetVelocityZ will set the velocity of the audio along the z-axis in 3D space.
SetVolume(number volume)The SetVolume action adjusts the volume of a sound.
SetX(number newX)SetX places the sound at a specific X coordinate in 3D virtual space.
SetY(number newY)SetY places the sound at a specific Y coordinate in 3D virtual space.
SetZ(number newZ)SetZ places the sound at a specific Z coordinate in 3D virtual space.
Stop()The Stop action will stop audio if it is currently playing.
Stream()The Stream action is used to load and play the next chunk of data for a file that was prepared using LoadToStream.

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.

Example Code

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

Parameters

Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns a CompareResult. The compare result is either larger if this hash code is larger than the object passed as a parameter, smaller, or equal.

Example Code

use Libraries.Language.Support.CompareResult
        Object o
        Object t
        CompareResult result = o:Compare(t)

Parameters

Return

Libraries.Language.Support.CompareResult: The Compare result, Smaller, Equal, or Larger.

DisableDoppler()

DisableDoppler will stop the audio from automatically calculating doppler shift.

Example Code

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 Code

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 Code

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 Code

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 Code

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 Code

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 Code

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.

Example Code

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

Parameters

Return

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

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.

Example Code

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()

Return

number:

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.

Example Code

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()

Return

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

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.

Example Code

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()

Return

number:

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.

Example Code

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()

Return

number:

GetHashCode()

This action gets the hash code for an object.

Example Code

Object o
        integer hash = o:GetHashCode()

Return

integer: The integer hash code of the object.

GetListenerDirection()

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

Example Code

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()

Return

Libraries.Compute.Vector3:

GetListenerDirectionX()

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

Example Code

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

Return

number:

GetListenerDirectionY()

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

Example Code

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

Return

number:

GetListenerDirectionZ()

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

Example Code

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

Return

number:

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.

Example Code

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()

Return

Libraries.Compute.Vector3:

GetListenerUp()

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

Example Code

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()

Return

Libraries.Compute.Vector3:

GetListenerUpX()

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

Example Code

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

Return

number:

GetListenerUpY()

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

Example Code

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

Return

number:

GetListenerUpZ()

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

Example Code

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

Return

number:

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.

Example Code

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()

Return

Libraries.Compute.Vector3:

GetListenerVelocityX()

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

Example Code

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

Return

number:

GetListenerVelocityY()

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

Example Code

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

Return

number:

GetListenerVelocityZ()

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

Example Code

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

Return

number:

GetListenerX()

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

Example Code

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

Return

number:

GetListenerY()

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

Example Code

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

Return

number:

GetListenerZ()

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

Example Code

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

Return

number:

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().

Example Code

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()

Return

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

GetPitch()

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

Example Code

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."

Return

number: The currently set 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.

Example Code

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()

Return

Libraries.Compute.Vector3:

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.

Example Code

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()

Return

number: The current rolloff rate of this Audio.

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.

Example Code

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()

Return

number:

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!

Example Code

use Libraries.Sound.Audio

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

        audio:SetVelocityX(30)

        number speed = audio:GetVelocityX()

Return

number:

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!

Example Code

use Libraries.Sound.Audio

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

        audio:SetVelocityY(30)

        number speed = audio:GetVelocityY()

Return

number:

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!

Example Code

use Libraries.Sound.Audio

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

        audio:SetVelocityZ(30)

        number speed = audio:GetVelocityZ()

Return

number:

GetVolume()

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

Example Code

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()

Return

number:

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.

Example Code

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()

Return

number:

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.

Example Code

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()

Return

number:

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.

Example Code

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()

Return

number:

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.

Example Code

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()

Return

boolean:

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.

Example Code

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()

Return

boolean:

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.

Example Code

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()

Return

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

IsLoopingEnabled()

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

Example Code

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()

Return

boolean:

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.

Example Code

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

Return

boolean:

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.

Example Code

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()

Return

boolean:

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

Load(Libraries.Sound.AudioSamples samples)

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

Example Code

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

    AudioSamples samples
    Audio audio

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

Parameters

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.

Example Code

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

Parameters

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.

Example Code

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

Parameters

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.

Example Code

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

Parameters

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 Code

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 Code

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.

Example Code

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

Parameters

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 Code

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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)

Parameters

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.

Example Code

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)

Parameters

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.

Example Code

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)

Parameters

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.

Example Code

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)

Parameters

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.

Example Code

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)

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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().

Example Code

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()

Parameters

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).

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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!

Example Code

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)

Parameters

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!

Example Code

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)

Parameters

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!

Example Code

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)

Parameters

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!

Example Code

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)

Parameters

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!

Example Code

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)

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

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.

Example Code

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()

Parameters

Stop()

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

Example Code

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 Code

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