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

Step 1: Getting the tutorial resources

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.

Step 2: Loading and playing audio

Here is our init.lua:

  scene1 = Engine.LoadScene( "level1.pak" )

  while ( Engine.Run() == true ) do
  end

Lets load and play some audio!

  scene1 = Engine.LoadScene( "level1.pak" )

  sound1 = Audio.LoadSound( "resources/track5_stereo.ogg" )
  Audio.PlaySound( sound1, 1.0 )

  while ( Engine.Run() == true ) do
  end

On the first new line, we load our stereo ogg file. On the next line, we play it. Audio.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 ;).

Step 3: Playing a sound in the 3d environment

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. Our new script will look like this:

  scene1 = Engine.LoadScene( "level1.pak" )
  Context.HideMouse( true )

  sound1 = Audio.LoadSound( "resources/track5_mono.ogg" )
  entity1 = Scene.GetEntityByName( scene1, "Cube.002" )
  Audio.PlayEntitySound( entity1, sound1, 1.0 )

  camera1 = Scene.GetActiveCamera( scene1 )

  while ( Engine.Run() == true ) do

    if ( Context.GetKeyState(KEY_W) == DOWN ) then
      Actor.MoveLocal( camera1, 0.0, 0.0, -12.0 )
    end

    if ( Context.GetKeyState(KEY_S) == DOWN ) then
      Actor.MoveLocal( camera1, 0.0, 0.0, 12.0 )
    end

    if ( Context.GetKeyState(KEY_A) == DOWN ) then
      Actor.MoveLocal( camera1, -12.0, 0.0, 0.0 )
    end

    if ( Context.GetKeyState(KEY_D) == DOWN ) then
      Actor.MoveLocal( camera1, 12.0, 0.0, 0.0 )
    end

    mf = Context.GetMouseForce()
    Actor.Rotate( camera1, 0.0, 0.0, -mf.x * 10.0 )
    Actor.RotateLocal( camera1, -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 Scene.GetEntityByName and then instead of calling Audio.PlaySound we call Audio.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 CorEngine 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.

Step 4: Controlling the sound

You will probably want to stop, pause and resume sounds at some point. Fortunately Audio.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.

  scene1 = Engine.LoadScene( "level1.pak" )

  sound1  = Audio.LoadSound( "resources/track5_stereo.ogg" )
  source1 = Audio.LoopSound( sound1, 1.0 )

  while ( Engine.Run() == true ) do
    if ( Context.GetKeyState(KEY_SPACE) == PRESSED ) then
      Audio.StopSound( source1 )
    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, Audio.SetVolume lets you control the global volume of the audio, Audio.SetRolloff will let you set the rolloff of 3d audio and with Audio.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.