Quorum audio objects have the ability to be set in a position in a virtual 3D space. 3D space is often represented in math and other applications with 3D (x, y, z) coordinate system. An example of a 3D coordinate system is below.
Quorum uses a virtual 3D coordinate system very much like this one to set sounds in 3D space. Audio objects have x, y, and z-coordinates that can be set through the SetX, SetY, and SetZ actions. These three actions each take a single number parameter that represents the value of that coordinate. Audio objects also have corresponding GetX, GetY, and GetZ actions that return the requested coordinate.
Using positional audio can allow us to do some cool things in our programs. For example, we can use an audio object in a game, set its initial position, and then update its position in the game update loop. An example is below.
use Libraries.Game.Game use Libraries.Sound.Audio class Main is Game Audio audio action Main StartGame() end action CreateGame audio:Load("Sounds/Firework.ogg") // give the audio some initial coordinates audio:SetX(-1) audio:SetY(-1) audio:SetZ(-1) audio:Play() end action Update(number seconds) // calculate the new x, y, and z coordinates based off the current coordinates. //In this example, the x, y, and z coordinates are increased by 0.25 every second. number newX = audio:GetX() + 0.30 * seconds number newY = audio:GetY() + 0.30 * seconds number newZ = audio:GetZ() + 0.30 * seconds // using the newly calculated coordinates, update the position of the object audio:SetX(newX) audio:SetY(newY) audio:SetZ(newZ) end end
Using positional audio can allow us to do some cool things in our programs
audio:SetListenerPosition(0, 1, -1) audio:SetListenerDirection(0, -1, 1)
We can also represent our position and direction as a Vector3.
Below is an example of a program that adds a sound to a moving box. The default settings for Doppler (on) and Listener are used, but we can try any of the code fragments from the two previous sections to understand how Doppler and Listener position/direction affect our game.
use Libraries.Game.Game use Libraries.Game.Graphics.Model use Libraries.Game.Graphics.Color use Libraries.Game.Audio3D class Main is Game Audio3D audio Model model action Main StartGame() end action CreateGame Color color model:LoadBox(0.5, 0.5, 0.5, color:Green()) Add(model) audio:Load("Sounds/Robot.ogg") audio:EnableLooping() //adds the audio to the model so position is automatically calculated model:Add(audio) model:SetX(-5) audio:Play() end action Update(number seconds) //Moves the model a small amount in each frame model:Move(0.025, 0, 0) end end
Using the Doppler Shift and also Listener Position and Direction
Quorum can only play audio files in the ".wav" or ".ogg" formats. Ensure that the audio file is one of these formats. If it is not, there are many free programs available that will convert the file to one of these formats.
In order to play an audio object, a file must be loaded to it. Ensure that a file is loaded to the audio object before calling its Play action.
The SetBalance, SetPitch, and Rotate actions only work on mono sounds. Ensure that the sound is not stereo. If it is, there are many free programs available that will convert sound files from stereo to mono.
The SetX, SetY, and SetZ actions only work on mono sounds. Ensure that the sound is not stereo. If it is, there are many free programs available that will convert sound files from stereo to mono.
In the next tutorial, we will discuss Playing Longer Audio: Streaming, which describes how to play audio files Quorum.