BlendELF, Tutorial 9, Audio

This tutorial builds on the first tutorial, so be sure to do that first! [Tutorial 1, BlendELF Basics]

In this tutorial you will learn to use the BlendELF Audio system

For this tutorial, you will need mono/stereo .ogg files (or .wav if you prefer it). Sample ogg files are provided at: tutorial9_resources.zip.

Extract the sample ogg files track5_stereo.ogg and track5_mono.ogg into the folder where your init.lua is. That being said, you can put them elsewhere too, but then you will have to adjust the path where they are opened from in your init.lua (or any other script for that matter) accordingly. In this tutorial, we assume that the files are in the same folder as your init.lua.

Here is our init.lua from Tutorial 1:

Lets load and play some audio!

On the first new line, we load our stereo ogg file. On the next line, we play it. elf.PlaySound takes two parameters: the sound to play and the volume. In the upper code, we set the volume to the highest possible value, 1.0.

Try running the code, if everything went well, you should be hearing some nice music in stereo ;).

To play an sound in the 3d environment, we need an entity to play it from. We know that an entity with the name Cube.002 exists in the level1.pak, so lets use it to play the sound. Also to be able to demonstrate the effect better, lets add some camera movement from Tutorial 3. Our new script will look like this:

scn = elf.LoadScene("level1.pak") elf.HideMouse(true) snd = elf.LoadSound("track5_mono.ogg") ent = elf.GetEntityByName(scn, "Cube.002") elf.PlayEntitySound(ent, snd, 1.0) while elf.Run() == true do cam = elf.GetSceneActiveCamera(scn) if elf.GetKeyState(elf.KEY_W) == elf.DOWN then elf.MoveActorLocal(cam, 0.0, 0.0, -12.0) end if elf.GetKeyState(elf.KEY_S) == elf.DOWN then elf.MoveActorLocal(cam, 0.0, 0.0, 12.0) end if elf.GetKeyState(elf.KEY_A) == elf.DOWN then elf.MoveActorLocal(cam, -12.0, 0.0, 0.0) end if elf.GetKeyState(elf.KEY_D) == elf.DOWN then elf.MoveActorLocal(cam, 12.0, 0.0, 0.0) end mf = elf.GetMouseForce() elf.RotateActor(cam, 0.0, 0.0, -mf.x*10.0) elf.RotateActorLocal(cam, -mf.y*10.0, 0.0, 0.0) end

This time we load the mono version of track5 because stereo sound won't work in the 3d environment. Next we get the entity with elf.GetEntityByName and then instead of calling elf.PlaySound we call elf.PlayEntitySound which takes three parameters: the entity that the sound will play from, the sound and the volume. Also we hid the mouse so that the camera mouse movement will work. You can exit from BlendELF with F10 or Alt + F4 even if your mouse can't reach the X control of the window ;).

Try the code and move the camera around, you should be hearing some 3d sound from one of the spheres ;).

NOTE: 3D SOUNDS HAVE TO BE MONO / 2D SOUNDS HAVE TO BE STEREO Stereo sounds will never be played in 3d and will fall back to 2d playing.

You will probably want to stop, pause and resume sounds at some point. Fortunately elf.Play/Loop* functions return a handle to the audio source so you can do just that. Lets make a script which lets you stop a looping sound with space.

elf.LoadScene("level1.pak") snd = elf.LoadSound("track5_stereo.ogg") src = elf.LoopSound(snd, 1.0) while elf.Run() == true do if elf.GetKeyState(elf.KEY_SPACE) == elf.PRESSED then elf.StopSound(src) end end

Try the code, space should stop the sound now.

Finally, check the API doc for more information of the audio functionality. For example, elf.SetAudioVolume lets you control the global volume of the audio, elf.SetAudioRolloff will let you set the rolloff of 3d audio and with elf.IsSoundPlaying you can check if a sound source is playing or not.

Thats it! I hope you enjoyed the tutorial, and if you have any comments about it, please post to the forums.