Libraries.Sound.Audio Documentation
The Audio class can be used to play sound files and change how they are played. Before playing audio, a file must be loaded first. For most audio, this is done with a normal Load action. If you want to load a long audio file, like a song or music, you can use the advanced LoadToStream action instead. The Audio class will support audio files with the .wav or .ogg extensions. If you try to load a different file type, or try to play audio before you've loaded a file, a generic runtime Error will be thrown. After you're done with the Audio, you should call Dispose() to let the system know you're done with the file.
Example Code
use Libraries.Sound.Audio
use Libraries.System.File
// We need to first create Audio and File objects to use.
Audio audio
File file
// We have to set our file so its path is the file we want to use for Audio.
// When writing your own code, test.wav should be replaced with your file.
file:SetPath("test.wav")
// Now that our file is set up, we can load that file as audio.
audio:Load(file)
// After we load the file, we can play it with a call to PlayUntilDone().
audio:PlayUntilDone()
Inherits from: Libraries.Language.Object
Actions Documentation
AddToQueue(Libraries.Sound.AudioSamples samples)
The AddToQueue action adds AudioSamples to the end of the data stored in this Audio object. To use this, the Audio must have been initialized using LoadToStream using an AudioSamples object, or must not have been initialized yet. This action can't be combined with actions that load a file into the Audio.
Parameters
- Libraries.Sound.AudioSamples: The AudioSamples to add to the end of the Audio data.
Example
use Libraries.Sound.AudioSamples
use Libraries.Sound.Audio
Audio audio
AudioSamples samples1
AudioSamples samples2
AudioSamples samples3
samples1:Load("Sonata-Part1.ogg")
samples2:Load("Sonata-Part2.ogg")
samples3:Load("Sonata-Part3.ogg")
audio:LoadToStream(samples1)
audio:AddToQueue(samples2)
audio:AddToQueue(samples3)
audio:Play()
repeat while audio:IsPlaying()
audio:Stream()
end
Compare(Libraries.Language.Object object)
This action compares two object hash codes and returns an integer. The result is larger if this hash code is larger than the object passed as a parameter, smaller, or equal. In this case, -1 means smaller, 0 means equal, and 1 means larger. This action was changed in Quorum 7 to return an integer, instead of a CompareResult object, because the previous implementation was causing efficiency issues.
Parameters
- Libraries.Language.Object: The object to compare to.
Return
integer: The Compare result, Smaller, Equal, or Larger.
Example
Object o
Object t
integer result = o:Compare(t) //1 (larger), 0 (equal), or -1 (smaller)
DisableDoppler()
DisableDoppler will stop the audio from automatically calculating doppler shift.
Example
use Libraries.Sound.Audio
Audio audio
audio:Load("Sound.wav")
// The doppler effect is only noticable if the audio has velocity.
audio:SetVelocity(4, 0, -2)
// Because we disable the doppler effect here, the velocity we just set will
// have no effect.
audio:DisableDoppler()
DisableListenerDoppler()
DisableListenerDoppler will make the audio engine stop using the velocity of the listener when calculating doppler effect. This will NOT stop the engine from using the velocity of other audio objects that do have doppler enabled when calculating the doppler shift. The listener is universal to all audio objects, so disabling doppler effect on the listener will be in effect during calculation of doppler shift for ALL audio objects.
Example
use Libraries.Sound.Audio
Audio audio
audio:Load("Whale.wav")
// In order to hear the doppler effect in action, the listener needs
// to have velocity.
audio:SetListenerVelocity(5, 0, 4)
// Because we are now disabling the doppler effect on the listener, the
// velocity we gave it will have no effect.
audio:DisableListenerDoppler()
DisableLooping()
DisableLooping will ensure that an audio file stops playing when it reaches the end of the sound, instead of repeating. This is the default behavior, so it is only necessary to call this if there was a call to EnableLooping earlier in the program.
Example
use Libraries.Sound.Audio
// To use audio, we'll first need to create an object for it.
Audio audio
// We need to load our audio before we change whether or not it will loop.
audio:Load("test.wav")
// We now enable looping. This will make the sound repeat forever until we
// stop it or call "audio:DisableLooping()".
audio:EnableLooping()
// Our audio is currently set to loop. We can disable it again using DisableLooping().
audio:DisableLooping()
Dispose()
The Dispose action will stop a sound if it is playing and then free the memory that is in use by the computer. You should always use Dispose after you are finished with a sound or at the end of your program to let the computer know you are done with the audio file. After calling Dispose from an audio object, you can then load a new audio file into it.
Example
use Libraries.Sound.Audio
// To use audio, we'll first need to create an object for it.
Audio audio
// In this example, we'll use LoadToStream, but Dispose can also be called
// on audio files prepared using Load!
audio:LoadToStream("Sounds/LongSong.ogg")
audio:Play()
repeat while audio:IsPlaying()
audio:Stream()
end
// At this point, the entire song will be done playing, so we can Dispose
// the audio to let the system know we're done playing that audio file.
audio:Dispose()
EnableDoppler()
EnableDoppler will make the audio automatically calculate doppler shift for this audio. Doppler is enabled by default for audio, but will have no effect until the user provides the velocity of the audio via an action, such as SetVelocity(Vector3).
Example
use Libraries.Sound.Audio
Audio audio
audio:Load("Sound.wav")
// We need to set the velocity of the audio in order to hear the doppler effect.
audio:SetVelocity(4, 0, -2)
// Doppler is already enabled by default, so this call would only be needed
// if we had previously disabled the doppler effect on this audio.
audio:EnableDoppler()
EnableListenerDoppler()
EnableListenerDoppler will make the audio engine consider the velocity of the listener when calculating doppler effects. The listener is universal to all audio objects, which means that if you enable doppler calculations for the listener, it will enable it when calculating doppler for ALL audio objects. By default, the listener already has doppler enabled, but this will have no effect until the listener is given a velocity.
Example
use Libraries.Sound.Audio
Audio audio
audio:Load("Whale.wav")
// In order to hear the doppler effect in action, the listener needs
// to have velocity.
audio:SetListenerVelocity(5, 0, 4)
// We now enable the doppler effect for the listener -- by default, this
// is already on, so this is only needed if we'd previously disabled it.
audio:EnableListenerDoppler()
EnableLooping()
EnableLooping will set the audio to continuously repeat itself when reaching the end of the audio instead of stopping.
Example
use Libraries.Sound.Audio
// To use audio, we'll first need to create an object for it.
Audio audio
// We need to load our audio before we change whether or not it will loop.
audio:Load("test.wav")
// We now enable looping. This will make the sound repeat forever until we
// stop it or call "audio:DisableLooping()".
audio:EnableLooping()
Equals(Libraries.Language.Object object)
This action determines if two objects are equal based on their hash code values.
Parameters
- Libraries.Language.Object: The to be compared.
Return
boolean: True if the hash codes are equal and false if they are not equal.
Example
use Libraries.Language.Object
use Libraries.Language.Types.Text
Object o
Text t
boolean result = o:Equals(t)
GetBalance()
GetBalance will return the current balance value of the sound. A value of -1 represents audio fully from the left speaker. A value of 1 represents audio fully from the right speaker. A value of 0 represents audio equally from both speakers.
Return
number:
Example
use Libraries.Sound.Audio
// To use audio, we'll first need to create an object for it.
Audio audio
// We always have to load a sound before use.
audio:Load("ding.wav")
// For this example, we will set the balance to -1.
audio:SetBalance(-1)
// We can get the balance back as a number using the GetBalance() action.
number balance = audio:GetBalance()
GetCurrentAudioSamples()
This action returns which AudioSample is currently queued when used on an Audio object that is streaming AudioSamples.
Return
Libraries.Sound.AudioSamples: The currently queued AudioSamples.
GetDefaultMaximumVolumeDistance()
This action returns the default maximum volume distance for all newly created Audio objects. It will not change the maximum volume distance of any Audio objects that have already been loaded.
Return
number: The default maximum volume distance to use for all newly loaded Audio objects.
Example
use Libraries.Sound.Audio
Audio audio1
Audio audio2
// We test to see what the default maximum volume distance is using audio1.
output "The default rolloff rate is " + audio1:GetDefaultMaximumVolumeDistance()
audio2:SetDefaultMaximumVolumeDistance(0.5)
// Even though we changed the default max volume distance using audio2,
// we can still see the changed default using audio1.
output "Now the default rolloff rate is " + audio1:GetDefaultMaximumVolumeDistance()
GetDefaultRolloffRate()
This action returns the default rolloff rate of newly loaded Audio objects. It can be changed using the SetDefaultRolloffRate action. The default value is shared across all Audio objects.
Return
number:
Example
use Libraries.Sound.Audio
Audio audio1
Audio audio2
// We test to see what the default rolloff rate is using audio1.
output "The default rolloff rate is " + audio1:GetDefaultRolloffRate()
audio2:SetDefaultRolloffRate(0.5)
// Even though we changed the default rolloff rate using audio2,
// we can still see the changed default using audio1.
output "Now the default rolloff rate is " + audio1:GetDefaultRolloffRate()
GetFade()
GetFade will return the current fade value of the sound. A value of -1 represents audio fully from the rear channel. A value of 1 represents audio fully from the front channel. A value of 0 represents audio equally from both channels.
Return
number:
Example
use Libraries.Sound.Audio
// To use audio, we'll first need to create an object for it.
Audio audio
// We always have to load a sound before use.
audio:Load("ding.wav")
// For this example, we will set the fade to -1.
audio:SetFade(-1)
// We can get the fade back as a number using the GetFade() action.
number fade = audio:GetFade()
GetHashCode()
This action gets the hash code for an object.
Return
integer: The integer hash code of the object.
Example
Object o
integer hash = o:GetHashCode()
GetListenerDirection()
This action will get the direction that the listener is currently facing in.
Return
Example
use Libraries.Sound.Audio
use Libraries.Compute.Vector3
// We load an audio object and set its position to 1 meter in front of the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 0, 1)
// Now we set the listener to face the right by calling SetListenerDirection.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerDirection(1, 0, 0)
// The audio is now located to the left of the listener's "ears", so when we
// play it, it should play through the left speaker.
audio:PlayUntilDone()
// Once we've set the direction of the listener, we can get back each
// of the values we've set it with using the GetListenerDirection actions.
// We can do this using any Audio object - it won't affect the result.
Vector3 direction = audio:GetListenerDirection()
output "The direction of the listener is " + direction:GetX() + ", " + direction:GetY() + ", " + direction:GetZ()
GetListenerDirectionX()
This action will get the x-component of the direction that the listener is currently facing in.
Return
number:
Example
use Libraries.Sound.Audio
// We load an audio object and set its position to 1 meter in front of the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 0, 1)
// Now we set the listener to face the right by calling SetListenerDirection.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerDirection(1, 0, 0)
// The audio is now located to the left of the listener's "ears", so when we
// play it, it should play through the left speaker.
audio:PlayUntilDone()
// Once we've set the direction of the listener, we can get back each
// of the values we've set it with using the GetListenerDirection actions.
// We can do this using any Audio object - it won't affect the result.
number x = audio:GetListenerDirectionX()
output "The direction of the listener on the x-axis is " + x
GetListenerDirectionY()
This action will get the y-component of the direction that the listener is currently facing in.
Return
number:
Example
use Libraries.Sound.Audio
// We load an audio object and set its position to 1 meter in front of the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 0, 1)
// Now we set the listener to face the right by calling SetListenerDirection.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerDirection(1, 0, 0)
// The audio is now located to the left of the listener's "ears", so when we
// play it, it should play through the left speaker.
audio:PlayUntilDone()
// Once we've set the direction of the listener, we can get back each
// of the values we've set it with using the GetListenerDirection actions.
// We can do this using any Audio object - it won't affect the result.
number y = audio:GetListenerDirectionY()
output "The direction of the listener on the y-axis is " + y
GetListenerDirectionZ()
This action will get the z-component of the direction that the listener is currently facing in.
Return
number:
Example
use Libraries.Sound.Audio
// We load an audio object and set its position to 1 meter in front of the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 0, 1)
// Now we set the listener to face the right by calling SetListenerDirection.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerDirection(1, 0, 0)
// The audio is now located to the left of the listener's "ears", so when we
// play it, it should play through the left speaker.
audio:PlayUntilDone()
// Once we've set the direction of the listener, we can get back each
// of the values we've set it with using the GetListenerDirection actions.
// We can do this using any Audio object - it won't affect the result.
number z = audio:GetListenerDirectionZ()
output "The direction of the listener on the z-axis is " + z
GetListenerPosition()
This action will return the current coordinates of the listener in virtual 3D space. The returned result will be stored in a new Vector3.
Return
Example
use Libraries.Sound.Audio
use Libraries.Compute.Vector3
// In this example, we will use two audio objects.
Audio buzzer
buzzer:Load("Buzzer.wav")
Audio bell
bell:Load("Bell.ogg")
// We will now set the listener's position. Although we can set all 3
// coordinates with this action, we will set just the x-coordinate for
// this example. This is the same as using SetListenerX(3)
Vector3 vector
vector:Set(3, 0, 0)
buzzer:SetListenerPosition(vector)
// Now when we play our audio, both sounds should come from the left
// side in 3D space - this is because both sounds are at their default
// location of 0, 0, 0, but the listener is 3 units to the right.
buzzer:PlayUntilDone()
bell:PlayUntilDone()
// We can get the listener's position back by using GetListenerPosition.
// It doesn't matter what Audio object we call this from - the result is the same.
Vector3 position = bell:GetListenerPosition()
output "Listener position is " + position:GetX() + ", " + position:GetY() + ", " + position:GetZ()
GetListenerUp()
This action will get the direction that the listener currently considers "up".
Return
Example
use Libraries.Sound.Audio
use Libraries.Compute.Vector3
// We load an audio object and set its position to 1 meter above the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 1, 0)
// The listener's default direction is straight forward, with the "up" direction
// being along the positive y-axis. For this example, we'll set the "up"
// direction to be along the negative x-axis. This effectively means the
// listener is lying on their left side, with their left ear pointed towards the
// ground and their right ear pointed up towards the sky.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerUp(-1, 0, 0)
// Although the sound is located above the listener, since the listener has
// their right ear pointed upwards, the audio will play through the right speaker.
audio:PlayUntilDone()
// We can retrieve the direction the listener considers to be "up" at
// any time by using the GetListenerUp actions. Just like setting the
// "up", it doesn't matter which Audio object is used to retrieve it.
Vector3 up = audio:GetListenerUp()
output "The up direction of the audio along the x-axis is " + up:GetX() + ", " + up:GetY() + ", " + up:GetZ()
GetListenerUpX()
This action will get the x-component of the direction that the listener currently considers "up".
Return
number:
Example
use Libraries.Sound.Audio
// We load an audio object and set its position to 1 meter above the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 1, 0)
// The listener's default direction is straight forward, with the "up" direction
// being along the positive y-axis. For this example, we'll set the "up"
// direction to be along the negative x-axis. This effectively means the
// listener is lying on their left side, with their left ear pointed towards the
// ground and their right ear pointed up towards the sky.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerUp(-1, 0, 0)
// Although the sound is located above the listener, since the listener has
// their right ear pointed upwards, the audio will play through the right speaker.
audio:PlayUntilDone()
// We can retrieve the direction the listener considers to be "up" at
// any time by using the GetListenerUp actions. Just like setting the
// "up", it doesn't matter which Audio object is used to retrieve it.
number x = audio:GetListenerUpX()
output "The up direction of the audio along the x-axis is " + x
GetListenerUpY()
This action will get the y-component of the direction that the listener currently considers "up".
Return
number:
Example
use Libraries.Sound.Audio
// We load an audio object and set its position to 1 meter above the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 1, 0)
// The listener's default direction is straight forward, with the "up" direction
// being along the positive y-axis. For this example, we'll set the "up"
// direction to be along the negative x-axis. This effectively means the
// listener is lying on their left side, with their left ear pointed towards the
// ground and their right ear pointed up towards the sky.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerUp(-1, 0, 0)
// Although the sound is located above the listener, since the listener has
// their right ear pointed upwards, the audio will play through the right speaker.
audio:PlayUntilDone()
// We can retrieve the direction the listener considers to be "up" at
// any time by using the GetListenerUp actions. Just like setting the
// "up", it doesn't matter which Audio object is used to retrieve it.
number y = audio:GetListenerUpY()
output "The up direction of the audio along the y-axis is " + y
GetListenerUpZ()
This action will get the z-component of the direction that the listener currently considers "up".
Return
number:
Example
use Libraries.Sound.Audio
// We load an audio object and set its position to 1 meter above the
// default listener position.
Audio audio
audio:Load("Chime.wav")
audio:SetPosition(0, 1, 0)
// The listener's default direction is straight forward, with the "up" direction
// being along the positive y-axis. For this example, we'll set the "up"
// direction to be along the negative x-axis. This effectively means the
// listener is lying on their left side, with their left ear pointed towards the
// ground and their right ear pointed up towards the sky.
// We can do this using any Audio object - it won't affect the result.
audio:SetListenerUp(-1, 0, 0)
// Although the sound is located above the listener, since the listener has
// their right ear pointed upwards, the audio will play through the right speaker.
audio:PlayUntilDone()
// We can retrieve the direction the listener considers to be "up" at
// any time by using the GetListenerUp actions. Just like setting the
// "up", it doesn't matter which Audio object is used to retrieve it.
number z = audio:GetListenerUpZ()
output "The up direction of the audio along the z-axis is " + z
GetListenerVelocity()
This action will return the current velocity of the listener in virtual 3D space. The returned result will be stored in a new Vector3.
Return
Example
use Libraries.Sound.Audio
use