Emotionalize Your Mobile Games With Tuny Engine Lite

 Emotionalize Your Mobile Games With Tuny Engine Lite

1. What is Tuny Engine Lite

Tuny Engine Lite is a cross-platform audio library for mobile games. It’s free to be used in any applications, including commercial software. It provides a set of easy to use API for sound mixing and playback on Symbian, Windows Mobile and Windows Desktop platforms.

2. Why use Tuny Engine Lite

With the evolution of hardware, mobile games become more and more complex. The sound quality in a game makes up a lot of the overall experience. Playing a simple sound is just not enough for a good mobile game. Because of the diversity of hardware and software of mobile devices, it’s not easy to implement a cross-platform audio library for moible games. Choosing an existing audio library for your mobile games is an economic and efficient solution. Tuny Engine Lite provides a set of well desinged API for playing and mixing sampled sounds and Nokia ott music, which are enough to play rich game audio for most mobile games.

3. What can Tuny Engine Lite do

Tuny Engine Lite provides the following functions: mixing and playing unlimited number of sampled sounds and ott songs; setting the volume/pan/priority per channel and per sound; pause/resume/stop a channel; create sound from PCM Wav, IMA-ADPCM compressed Wav and Nokia Ott files.

4. Install the library

To use Tuny Engine Lite, you need to download and install it first. It’s developped and maintained by Focusbyte, and you can download it from http://www.focusbyte.com. The SDK is delivered as a single compressed zip file. Unzip it to a directory, making sure to maintain the directory structure stored inside the zip file. You should end up with a tree that contains doc, inc, lib, and examples.

For Symbian projects, you need to copy files in lib/SymbianVx to Symbian’s library folder %EPOCROOT%/Epoc32/Release

5. Configurate project’s settings

You need to add the Tuny Engine Lite library directory to your library path and link with the tunylite library.

For Symbian projects:
Add tunylite.lib and tunylite/inc to your project’s mmp file:

USERINCLUDE ../../../tunylite/inc
LIBRARY tunylite.lib

For Windows Mobile and Windows Desktop projects:
Add tunylite.lib to your project’s library.
Add path to tunylite.lib to your project’s additional library path.

In your code, make sure you include the tuny.h header file:

#include "../../tunylite/inc/tuny.h"

6. Add variables of handles to Tuny Engine objects

Now it’s time to integrate Tuny Engine Lite into your code. In this tutorial we will play a background music and a sound effect. The first thing to do is declaring variables for TunyEngine, TunySound and TunyChannel:

TunyEngine *iEngine;
TunySound *iMusic;
TunySound *iSFX;
TunyChannel iMusicChannel;

7. Create an instance of TunyEngine

You need to create an instance of TunyEngine before using it.

//Create a sound engine instance
TunyResult r;
r = TunyEngine_Create(&iEngine, NULL);
if(r != TUNYERR_NONE)
{
   //Handle error here
   ...
}

The second parameter of TunyEngine_Create is not used in Symbian and Windows platform, so just use NULL.

8. Open TunyEngine

Call TunyEngine_Open to initialize TunyEngine.

if(TunyEngine_Open(iEngine, 12, TUNY_DEFAULT_SAMPLE_RATE, 0, 1) != TUNYERR_NONE)
{
   //Handle error here
   ...
}

The above code will open TunyEngine with 12 mixing channels, default output sample rate, default output buffer size and mono output channel. In all Windows Mobile devices and some Symbian devices that support stereo output, you can pass 2 to the last parameter to open TunyEngine with stereo output.

9. Start TunyEngine

When TunyEngine is opened successfully, call TunyEngine_Start to start mixing and playing:

r = TunyEngine_Start(iEngine);
if(r != TUNYERR_NONE)
{
   //Handle error here
   ...
}

10. Load sound

To play a sound, you must load it from file first. You can load it before TunyEngine is started, but you must load it after TunyEngine is opened.

Code for Symbian platform:

TFileName fn;

//Load Ott music
fn = _L("music.ott");
if(TunyEngine_CreateSound(iEngine, &iMusic, CompleteWithAppPathEpoc(fn), TUNY_CREATE_STREAM) != TUNYERR_NONE)
   User::Panic(kTunyError, KErrGeneral);

//Load a wav sound
fn = _L("sfx.wav");
if(TunyEngine_CreateSound(iEngine, &iSFX, CompleteWithAppPathEpoc(fn), 0) != TUNYERR_NONE)
   User::Panic(kTunyError, KErrGeneral);

Code for Windows platform:

WCHAR fullPath[MAX_PATH];

if(TunyEngine_CreateSound(iEngine, &iMusic, CompleteWithAppPath(L"music.ott", fullPath), TUNY_CREATE_STREAM) != TUNYERR_NONE)
{
   MessageBox(NULL, TEXT("iEngine->CreateSound() failed!/n"), TEXT("Tuny"), MB_OK | MB_ICONERROR);
   FreeAll();
   return 1;
}

if(TunyEngine_CreateSound(iEngine, &iSFX, CompleteWithAppPath(L"sfx.wav", fullPath), 0) != TUNYERR_NONE)
{
   MessageBox(NULL, TEXT("iEngine->CreateSound() failed!/n"), TEXT("Tuny"), MB_OK | MB_ICONERROR);
   FreeAll();
   return 1;
}

CompleteWithAppPathEpoc and CompleteWithAppPath complete a file name with path to application folder. TUNY_CREATE_STREAM indicates TunyEngine_CreateSound to create a streamed sound. Streamed sound is read from file and decoded while playing, while non-streamed sound is read from file and decoded when it’s created. Streamed sound uses less memory but takes more CPU time. For long sounds like music, they should, or even have to, be created as stream, otherwise they will take lots of heap memory. For short sounds like sound effects, they shouldn’t be created as stream, otherwise they will take lots of CPU time. Streamed sound has lag in responding change in some properties, like volume and pan.
Note that Tuny Engine Lite has limitation of creating stream: only ott music is supported. You can’t create stream from wav file.

11. Play sound

You can play a loaded sound by calling TunyEngine_Play after TunyEngine is opened. If you want to change the properties of the sound playing, or want to stop it manually, you need to save the handle of the channel returned by TunyEngine_Play for later use. If you want to change channel properties before it’s played, you can play the sound in paused mode.

The code below plays the background music with 1/2 full volume:

TunyEngine_Play(iEngine, iMusic, &iMusicChannel, TRUE);
TunyChannel_SetProperty(iEngine, iMusicChannel, TUNY_PROPERTY_VOLUME, 0x8000); //Change channel volume before it's played
TunyChannel_SetProperty(iEngine, iMusicChannel, TUNY_PROPERTY_PAUSED, FALSE); //Start playing the channel

The first line of the code above plays iMusic and returns the handle of the channel that playing iMusic in iMusicChannel. This handle of a channel is a unique number that identify a playing channel. If the channel stops, the handle of the channel becomes invalid, and any function calls with this hanndle will return TUNYERR_BAD_HANDLE.
The second line changes the volume of the music channel.
The third line resume the playback of the music channel.

If you just want to leave the played sound alone, use NULL and FALSE for the third and forth parameters. The code below plays the effect sound and leave it alone:

TunyEngine_Play(iEngine, iSFX, NULL, FALSE);

A non-streamed sound can be played at several channels at one time without taking extra heap memory, while streamed sound can be played once at one time.

12. Update TunyEngine in every game loop

You need to call TunyEngine_Update in every game loop to make sound streams work properly.

TunyEngine_Update(iEngine); The interval between two calls to this function shouldn’t longer than the stream buffer size, which has a default value of 1 second. If you do not call this function, or the interval between two calls is longer than stream buffer size, the streamed sounds will be played abnormally, like playing a section of the sound repeatly.

13. Make background music loop

Tuny Engine Lite does not support setting loop properties, so to make the background music loop, you have to replay the music when it reaches end. In this tutorial, we replay the background music if the music channel stops:

int dummy;
if(TunyChannel_GetProperty(iEngine, iMusicChannel, TUNY_PROPERTY_PAUSED, &dummy) == TUNYERR_BAD_HANDLE)
{
   //The background music is stopped, replay it
   TunyEngine_Play(iEngine, iMusic, &iMusicChannel, TRUE);
   TunyChannel_SetProperty(iEngine, iMusicChannel, TUNY_PROPERTY_VOLUME, 0x8000); //Change channel volume before it's played
   TunyChannel_SetProperty(iEngine, iMusicChannel, TUNY_PROPERTY_PAUSED, FALSE); //Start playing the channel
}

14. Free TunySound instances.

When a sound is no longer used, call TunySound_Destroy to free the TunySound instance.
Attention: you must call TunySound_Destroy to free all TunySound instances before calling TunyEngine_Destroy.
Example:

TunySound_Destroy(iMusic);
iMusic = NULL;

If a sound is being played when it’s destroyed, the channels that playing the sound will be stopped before it’s destroyed.

15. Stop, close and free TunyEngine

Call TunyEngine_Stop to stop audio playback and free the acquired system resource of audio output. You can call this function when your game application is brought to background, and call TunyEngine_Start when it’s brought to foreground.
Call TunyEngine_Close to close TunyEngine.
Call TunyEngine_Destroy to free the TunyEngine instance if it is not used anymore. There’s no need to call TunyEngine_Stop and TunyEngine_Close before calling this function, because they are automatically called by this function.

TunyEngine_Destroy(iEngine);
iEngine = NULL;

16. A tip to play MIDI music in Tuny Engine Lite powered Symbian games

Although Tuny Engine Lite does not support MIDI, you can still play MIDI music in your Symbian games: just call TunyEngine_Stop before playing the MIDI music with Symbian’s CMdaAudioPlayerUtility, and call TunyEngine_Start when the MIDI music is stopped. The limitation of this method is you can’t mixing the sound effects with MIDI music. To play the MIDI music and sound effects simultaneously, you need the full version of Tuny Engine, which supports MIDI format file.

<script type=text/javascript> </script> <script src="http://pagead2.googlesyndication.com/pagead/show_ads.js" type=text/javascript> </script>