This section is going to be rather small because, well frankly, LibGDX makes audio incredibly easy. Unlike previous tutorials, this one is going to contain a number of snippets. LibGDX supports 3 audio formats: ogg, mp3 and wav. MP3 is a format that is mired in legal issues, while WAV is a rather large ( file size ) format, leaving OGG as often the best choice. That said, when it comes to being broadly supported ( especially in browsers ), Ogg can have issues. This of course is why multiple formats exist and continue to be used!
Playing Sound Effects
Loading a sound file is trivial. Like you did earlier with fonts or graphic formats, you need to add the files to assets folder in the android project folder. Like earlier, I followed convention and put everything in the data sub directory like so:
As you can see, I added a file of each format, mp3.mp3, ogg.ogg and wav.wav.
Loading any of these files is incredibly simple:
Sound wavSound = Gdx.audio.newSound(Gdx.files.internal("data/wav.wav"));
Sound oggSound = Gdx.audio.newSound(Gdx.files.internal("data/ogg.ogg"));
Sound mp3Sound = Gdx.audio.newSound(Gdx.files.internal("data/mp3.mp3"));
This returns a Sound object using the specified file name. Once you have a Sound, playing is trivial:
wavSound.play();
You also have the option of setting the play volume when calling play, such as:
oggSound.play(0.5f);
This plays the oggSound object at 50% volume for example.
In addition to play() you can also loop() to well, loop a Sound continuously. When you play a sound it returns an id that you can use to interact with the sound. Consider:
long id = mp3Sound.loop();
Timer.schedule(new Task(){
@Override
public void run(){
mp3Sound.stop(id);
}
}, 5.0f);
Here you start an mp3 file looping, which returns an id value. Then we schedule a task to run 5 seconds later to stop the sound from playing. Notice how in the call to stop() an id is passed? This allows you to manage a particular instance of a sound playing. This is because you can play the same Sound object a number of times simultaneously. One important thing to be aware of, Sound objects are a managed resource, so when you are done with them, dispose().
wavSound.dispose(); oggSound.dispose(); mp3Sound.dispose();
Once you have a sound, there are a number of manipulations you can do. You can alter the pitch:
long id = wavSound.play(); wavSound.setPitch(id,0.5f);
The first parameter is the sound id to alter, the second value is the new pitch ( speed ). The value should be > 0.5 and < 2.0. Less than 1 is slower, greater than 1 is faster.
You can alter the volume:
long id = wavSound.play(); wavSound.setVolume(id,1.0f);
Once again, you pass the id of the sound, as well as the volume to play at. A value of 0 is silent, while 1 is full volume. As well you can set the Pan ( stereo position ), like so:
long id = wavSound.play(); wavSound.setPan(id, 1f, 1f);
In this case the parameters are the sound file id, the pan value ( 1 is full left, 0 is center, –1 is full right ) as well as the volume. You can also specify the pitch, pan and volume when calling play() or loop(). One important note, none of these methods are guaranteed to work on the WebGL/HTML5 backend. Additionally file format support varies between browsers ( and is very annoying! ).
Streaming music
In addition to playing sound effects, LibGDX also offers support for playing music ( or longer duration sound effects! ). The big difference is LibGDX will stream the effect in this case, greatly lowering the demands on memory. This is done using the Music class. Fortunately it’s remarkably simple:
Music mp3Music = Gdx.audio.newMusic(Gdx.files.internal("data/RideOfTheValkyries.mp3"));
mp3Music.play();
And that’s all you need to stream an audio file. The controls are a bit different for a Music file. First off, there is no id, so this means you can play multiple instances of a single Music file at once. Second, there are a series of VCR style control options. Here is a rather impractical example of playing a Music file:
Music mp3Music = Gdx.audio.newMusic(Gdx.files.internal("data/RideOfTheValkyries.mp3"));
mp3Music.play();
mp3Music.setVolume(1.0f);
mp3Music.pause();
mp3Music.stop();
mp3Music.play();
Gdx.app.log("SONG",Float.toString(mp3Music.getPosition()));
After our Music file is loaded, we start it, then set the volume to 100%. Next we pause, then stop, then play our music file again. As you can see from the log() call, you can get the current playback position of the Music object by calling getPosition(). This returns the current elapsed time into the song in seconds. You may be wondering exactly what the difference is between pause() and stop()? Calling play() after pause() will continue playing the song at the current position. Calling play() after calling stop() will restart the song.
Once again, Music is a managed resource, so you need to dispose() it when done or you will leak memory.
Recording and playing PCM audio
LibGDX also has the ability to work at a lower level using raw PCM data. Basically this is a short (16bit) or float (32bit) array of values composing the wavform to play back. This allows you to create audio effects programmatically. You can also record audio into PCM form. Consider the following example:
AudioDevice playbackDevice = Gdx.audio.newAudioDevice(44100, true); AudioRecorder recordingDevice = Gdx.audio.newAudioRecorder(44100, true); short[] samples = new short[44100 * 10]; // 10 seconds mono audio recordingDevice.read(samples, 0, samples.length); playbackDevice.writeSamples(samples, 0, samples.length); recordingDevice.dispose(); playbackDevice.dispose();
This example creates an AudioDevice and AudioRecorder. In both functions you pass the desired sampling rate ( 44.1khz is CD audio quality ) as well as a bool representing if you want mono ( single channel ) or stereo ( left/right ) audio. Next we create an array to record our audio into. In this example, we want 10 seconds worth of audio at the 44.1khz sampling rate. We then record the audio by calling the read() method of the AudioRecorder object. We pass in the array to write to, the offset within the array to start at and finally the total sample length. We then playback the audio we just recording by calling writeSamples, using the exact same parameters. Both AudioDevice and AudioRecorder are managed resources and thus need to be disposed.
There are a few very important things to be aware of. First, PCM audio is NOT available on HTML5. Second, if you are recording in Stereo, you need to double the size of your array. The data in the array for a stereo waveform is interleaved. For example, the first byte in the array is the very first float of the left sound channel, then the next float is the first value in the right channel, the next float is the second float of the left sound channel, and so on.