Playing Sounds and Music

In many games and applications you will want to play a sound. This may be backing music in a game, sound effects or alerts which require user input. The MoSync SDK provides an audio API to help you do that.

Sound files can come from two places, either sounds you've packaged up with your application when you've distributed it, or they can be downloaded over the data network at runtime. Either way, you need to create a resource which the API can recognise and pass to the operating system.

The 'Adding Resources to a Project' goes into a detail on how to add sound files to your project at build-time for packaging with your release. In short, a sound file needs to be added as either a .media or a .umedia resource with a MIME type.

Due to limitations in the platform-provided API's there are a set of restrictions. Currently, it's not possible to play MP3 files on the Windows Mobile platform and the API only supports playing of one sound at a time. If you want to make sure that all MoSync supported devices will be able to play your resources it is recommended that you use wav files.

To play sound files you have downloaded, then the easiest way is with the AudioDownloader. There is an example which downloads and plays an MP3 file in the tutorial 'Downloading Audio from the Internet'.

Specifying MIME types

Whether you are planning on packaging audio with your application, or planning on downloading it, it is essential that you specify the MIME type of the audio before you want to play it. The two tutorials linked above contain much more detail about how to do this in each scenario, but this is the short version.

Specifying MIME types at build-time

If you are packaging your audio, you will have an entry in the resource file which looks something like this:

.res MUSIC
.media "audio/mpeg", "music.mp3"

The directive .media means that it will be treated as a loaded binary resource. That is, it will be loaded into the application memory when the application starts. Alternatively, you can use .umedia which will mean that the audio is loaded on demand, but there will be a slight delay.

After the .media directive, then there is the MIME type as a string. You can find common MIME types on Wikipedia. The final part is the file name you want to enclose.

Specifying MIME types at run time

If you are downloading and playing sounds at run time, then you should probably use the AudioDownloader class. This is create and configure an appropriate resource for you. When you specify the URL to download from, you also specify the MIME type. The web server you are downloading from (assuming it is a web server) may also provide the MIME type, and may also overwrite your MIME specification.

Playing Audio Files

To play a sound you use the maSoundPlay function.

maSoundPlay(RES_SOUND);

Just provide the correct resource and the audio file will start playing immediatly if successful. If the function returns any negative value it means that it failed.

If you, for some reason, wish to stop playing the sound you just use the maSoundStop function.

maSoundStop();

If you wish to restart the sound you can use this:

if(maSoundIsPlaying())
maSoundStop();
maSoundPlay(RES_AUDIO, 0, maGetDataSize(RES_AUDIO));

First you can check if your sound is still playing. If so, you can stop it before playing it again. maSoundPlay always plays the sound from the beginning.

Audio volume in MoSync is defined as values between 0 and 100, where 100 is the maximum volume. To get the volume you use:

int volume = maSoundGetVolume();

and to set the volume you use:

maSoundSetVolume(volume);

Example Source Code

/**
 * @file PlayAudio.cpp
 *
 * This program shows how one can work with playing sounds and music.
 *
 * Todo: You need to add an audio resource file which you want to play.
 * In this example we have used Resource.lst file with following contents:
 * < .res RES_AUDIO
 *   .media "Audio/x-waf", "mobilesorcery2.wav"  >
 *
 * @Author Anders Malm
 */

#include <MAUtil/Moblet.h>
#include "MAHeaders.h"

using namespace MAUtil;

/*
 * Moblet class for playing music.
 */
class MyMoblet : public Moblet
{
public:
    MyMoblet();
    void keyPressEvent(int keyCode);
    void setVolume(int change);
};

/*
 * The constructor for Moblet class
 */
MyMoblet::MyMoblet()
{
    MAExtent e = maGetScrSize();
    maSetColor(0x0);
    maFillRect(0, 0, EXTENT_X(e), EXTENT_Y(e));
    maSetColor(0xffffff);
    maDrawText(0, 0, "Press 5 to Restart sound");
    maDrawText(0, 20, "Press 8 to Stop sound");
    maDrawText(0, 40, "Press 7 to Decrease volume ");
    maDrawText(0, 60, "Press 9 to Increase volume ");
    maDrawText(0, 80, "Press 0 to Exit");
    maUpdateScreen();

    // Panic message in case of failure.
    if(maSoundPlay(RES_AUDIO, 0, maGetDataSize(RES_AUDIO)) < 0)
        maPanic(0,"error playing sound!");
}

/*
 * For controlling music volume.
 */
void MyMoblet::setVolume(int change)
{
    int volume = maSoundGetVolume();
    volume += change;
    if(volume<0) volume = 0;
    else if(volume>100) volume = 100;

    maSoundSetVolume(volume);
}

/*
 * Key press events
 * Pressing key 0, Exits the program.
 * Pressing key 8, Stops playing sound.
 * Pressing key 5, Starts playing sound.
 * Pressing Keys 7 and 9, sets volume down and up respectively.
 */
void MyMoblet::keyPressEvent(int keyCode)
{
    switch(keyCode)
    {
        case MAK_0:
            maExit(0);
            break;
        case MAK_8:
            maSoundStop();
            break;
        case MAK_5:
            if(maSoundIsPlaying())
                maSoundStop();
            maSoundPlay(RES_AUDIO, 0, maGetDataSize(RES_AUDIO));
            break;
        case MAK_7:
            setVolume(-10);
            break;
        case MAK_9:
            setVolume(10);
            break;
    }
}

/**
 * Main execution of the program starts from here.
 */
extern "C" int MAMain()
{
    Moblet::run(new MyMoblet());
    return 0;
};

Specifying MIME types

Specifying MIME types at build-time

Specifying MIME types at run time

Playing Audio Files

Example Source Code

MoSync Documentation

Navigation

User login