Sounds API: Using the Sounds API

For using the Sounds API, a pointer to the CAknKeySoundSystem instance needs to be obtained first. It can then be used to play sounds, register sounds, push sound contexts and query the information of system sounds. When the client has finished using the CAknKeySoundSystem instance, there is no need to delete the instance if it is obtained from the CAknAppUi base class.

Obtaining keyboard sound system instance

A pointer to a CAknKeySoundSystem instance can be obtained from by using the CAknAppUiBase::KeySounds() method. Hence, if the application is derived from CAknAppUi, a pointer can be obtained e.g. as following:

// HEADER FILE



// Forward declaration.

class CAknKeySoundSystem;

...

// Create a private member variable to appui class.

private:

    CAknKeySoundSystem* iKeySounds;



// CPP FILE

#include <aknsoundsystem.h>

...

void CMyAppAppUi::ConstructL()

    {

    ...

    // Obtain an instance from CAknAppUi base class.

    iKeySounds = KeySounds();

    }

Playing sounds

CAknKeySoundSystem provides methods for playing and stopping sounds. The sounds are identified by Sound IDs

Playing a sound by using a SID (Sound ID)

CAknKeySoundSystem::PlaySound() can be used to play a sound by giving it a Sound ID (SID), which is an identifier for a sound information entry. There is a distinction between predefined AVKON system SIDs and user-defined custom SIDs. The values 1000 and above are reserved for system SIDs, and the values below 1000 can be used by custom SIDs. (See TAvkonSystemSID enumeration in Avkon.hrh for a list of predefined AVKON system SIDs and their values.)

The following example shows how to play EAvkonSIDErrorTone system SID:

iKeySounds->PlaySound(EAvkonSIDErrorTone);

Stopping a sound

If a sound is playing, it can be stopped with the CAknKeySoundSystem::StopSound() method:

iKeySounds->StopSound(EAvkonSIDErrorTone);

Defining application specific sounds

If application needs its own custom sounds, it must first define them in its resource file. After that, the resource needs to be registered to Key Sound Server.

Defining a sound resource

Applications can define their own sounds, which can be then played via the CAknKeySoundSystem::PlaySound() method or included in an application specific key sound context to override the default system key sounds within an application.

The AVKON_SOUND_INFO resource from Avkon.rh is used to define a SID. Each SID can be associated with a tone, tone sequence or a sound file. A tone is specified by a frequency and duration in microseconds. The tone sequence format is product specific and is not covered here. A file can be for example in WAV format or in some other format recognized by Multimedia Framework.

The parameters of the AVKON_SOUND_INFO resource are as follows:

• WORD signature1 and signature2
  • These fields are for internal use to distinguish which Symbian resource compiler version was used. The user must not change these fields.
• WORD sid
  • Unique SID (Sound ID). This is the number that is referenced in the AVKON_SKEY_INFO resource or given to the PlaySound() method.
• WORD priority
  • The sound priority used by the device driver to determine priority. Use only the sound priorities defined by the device driver, which are also defined in Avkon.hrh. Defaults to EAvkonKeyClickPriority.
• WORD preference
  • This variable holds similar preference values as used with the CMdaAudioToneUtility and CMdaAudioPlayerUtility classes. Preference is used in addition to priority to tell what to do with a sound in case of a simultaneous playing request. The tone can be e.g. mixed or not played at all. Preference value defaults to EAvkonKeyClickPreference. Symbian preference values are defined in MmfBase.h and S60 preference values are defined in Avkon.hrh.
• LTEXT file
  • The file name of a sound file. The sound file must be a file type recognized by Multimedia Framework.
• WORD frequency
  • The frequency of the tone to be played.
• LONG ms
  • The duration of the tone to be played in microseconds.
• WORD sequencelength
  • The length of the sound sequence definition in bytes.
• BYTE sequence[]
  • A byte array that defines a sound sequence.
• BYTE volume
  • The volume of the sound [0..9]. Key tones do not obey this field, but their volume is controlled by the Profiles application.

An example how to define two new SIDs in a resource file is shown below. The first SID is in tone format and the second one uses a sound file (which must exist in the given path). In the first SID, the priority and preference are omitted, so they default to key click priority and preference.

RESOURCE AVKON_SOUND_INFO_LIST r_myapp_sound_list

    {

    list =

        {

        // Tone SID.

        AVKON_SOUND_INFO

            {

            sid = 1; // Accepted range for custom SIDs is [1..999]. 

            frequency = 8000; 

            ms = 100000; // 0.1 s 

            },

        // File SID.

        AVKON_SOUND_INFO

            {

            sid = 2; // Accepted range for custom SIDs is [1..999].

            priority = EAvkonKeyClickPriority;

            preference = EAknAudioPrefDefaultTone;

            file = "c:\\mytone.wav";

            volume = 5;

            }

        };

    }

Registering a sound resource

Once the sound info list resource is defined, it must be registered to the Key Sound Server. After that, the SIDs can played e.g. by calling the PlaySound() method with the Sound ID as a parameter:

void CMyAppAppUi::ConstructL()

    {

    ...

    iKeySounds->AddAppSoundInfoListL(R_MYAPP_SOUND_LIST);

    }



void CMyAppAppUi::SomeMethod()

    {

    ...

    iKeySounds->PlaySound(1);

    }

Customizing key sounds of an application

Customizing the application specific key sounds contains two steps. First, a sound context must be defined in the application's resource file. After that, the context must be pushed to the key sound stack to make it active. If the context is not needed anymore, it should be popped out from the key sound stack.

Defining a key sound context

A sound context defines what sound is played when a particular key is pressed. By default, an application has a default system sound context activated, but it can be overridden with an application specific sound context.

When a key is pressed and held down, three types of events are generated. First, a "down" event is generated, and followed by a "long" event after a few moments (ca. 0.6 seconds). After that, the key keeps generating "repeat" events until it is released. All of these can be customized in a key sound context. An example is shown below. Always use scan codes in the AVKON_SKEY_LIST resource:

RESOURCE AVKON_SKEY_LIST r_myapp_sound_context

    {

    list =

        {

        // Set SID 1 for numeric key '4'. Set the same sound for long and repeat events also.

        AVKON_SKEY_INFO {key = '4'; sid = 1;},

        AVKON_SKEY_INFO {key = '4'; sid = 1; type = ESKeyTypeLong;},

        AVKON_SKEY_INFO {key = '4'; sid = 1; type = ESKeyTypeRepeat;},



        // Set SID 2 for numeric key '5'. Disable long and repeat sounds.

        AVKON_SKEY_INFO {key = '5'; sid = 2;},

        AVKON_SKEY_INFO {key = '5'; sid = EAvkonSIDNoSound; type = ESKeyTypeLong;},

        AVKON_SKEY_INFO {key = '5'; sid = EAvkonSIDNoSound; type = ESKeyTypeRepeat;},



        // Set system SID "battery low tone" for numeric key '6' (all events).

        AVKON_SKEY_INFO {key = '6'; sid = EAvkonSIDBatteryLowTone;},

        AVKON_SKEY_INFO {key = '6'; sid = EAvkonSIDBatteryLowTone; type = ESKeyTypeLong;},

        AVKON_SKEY_INFO {key = '6'; sid = EAvkonSIDBatteryLowTone; type = ESKeyTypeRepeat;},



        // Set system SID "standard key click" for left arrow key. Disable long and repeat sounds.

        AVKON_SKEY_INFO {key = EStdKeyLeftArrow; sid = EAvkonSIDStandardKeyClick;},

        AVKON_SKEY_INFO {key = EStdKeyLeftArrow; sid = EAvkonSIDNoSound; type = ESKeyTypeLong;},

        AVKON_SKEY_INFO {key = EStdKeyLeftArrow; sid = EAvkonSIDNoSound; type = ESKeyTypeRepeat;},



        // Same as above for right arrow key. This time use EAvkonSIDDefaultSound for same result.

        AVKON_SKEY_INFO {key = EStdKeyRightArrow; sid = EAvkonSIDDefaultSound;},

        AVKON_SKEY_INFO {key = EStdKeyRightArrow; sid = EAvkonSIDNoSound; type = ESKeyTypeLong;},

        AVKON_SKEY_INFO {key = EStdKeyRightArrow; sid = EAvkonSIDNoSound; type = ESKeyTypeRepeat;},



        // Disable all sounds for Send key (the green key).

        AVKON_SKEY_INFO {key = EStdKeyYes; sid = EAvkonSIDNoSound;},

        AVKON_SKEY_INFO {key = EStdKeyYes; sid = EAvkonSIDNoSound; type = ESKeyTypeLong;},

        AVKON_SKEY_INFO {key = EStdKeyYes; sid = EAvkonSIDNoSound; type = ESKeyTypeRepeat;}

        };

    }

Pushing a context to the key sound stack

The sound context must be pushed to key sound stack to have effect. This is usually done in the constructor of the application UI class. Note that because this sound context contains application specific SIDs, AddAppSoundInfoListL() has to be called before PushContextL():

void CMyAppAppUi::ConstructL()

    {

    ...

    iKeySounds->AddAppSoundInfoListL(R_MYAPP_SOUND_LIST);

    ...

    iKeySounds->PushContextL(R_MYAPP_SOUND_CONTEXT);

    }

Now, the keys listed in the context resource should have customized sounds within the application. Note that the key sound system activates automatically the default sound context when the application is changed or when e.g. the Options menu or Fast Swap window is opened on top of the application. When the application is reactivated or these windows are closed, the application specific sound context will be active again.

A common use for custom sound contexts is just to disable the sounds for some keys or all of them. This can be done by listing all the keys whose sounds should be disabled, and using EAvkonSIDNoSound system SID for them. Another alternative is to push the predefined AVKON sound context R_AVKON_SILENT_SKEY_LIST to the key sound stack to disable all key sounds.

Popping a context from the key sound stack

The application specific key sound context can be popped from the key sound stack any time. Usually this should be done at least in the destructor of the application UI:

CMyAppAppUi::~CMyAppAppUi()

    {

    ...

    iKeySounds->PopContext();

    }

Obtaining system sound information

The information of AVKON system sounds can be obtained by using the RequestSoundInfoL() method. Applications must not read AVKON resources directly as the resource format can change without any notice, but instead use this method. The method takes AVKON system SID and a reference to CAknSoundInfo as parameters:

CAknSoundInfo* soundInfo = CAknSoundInfo::NewL();

TInt err = KeySounds()->RequestSoundInfoL(EAvkonSIDChargingBatteryTone, *soundInfo);

The CAknSoundInfo object contains public data members for the following information:

• Sound type (tone, tone sequence or file)
• Priority
• Preference
• Volume
• Duration
• Sequence (for sequence sounds)
• File name (for file sounds)

With this information, it is possible e.g. to query whether the sound format is tone, tone sequence or file and play the sound directly by using either CMdaAudioToneUtility or CMdaAudioPlayerUtility according to the format. Using the Multimedia Framework classes directly can give more information e.g. about the playing status. This includes, for example, callback functions indicating when preparing or playing has been completed and information about possible errors during the playing process.

Error handling

Some methods may leave, for example if running out of memory. A client application can handle these errors similarly as a normal Symbian OS platform application.

Memory overhead

For key sound contexts, it is recommended to use only tone (or tone sequence) format instead of file format, especially with large audio files. For performance reasons, the key press sounds (the SIDs that use key click priority and preference) are loaded into the memory of Key Sound Server only once, and multiple playing requests (key presses) use the same instance. For other sounds, the sound is loaded into memory every time when it is played, and deleted immediately after that for saving memory.

Extensions to the API

There are no extensions for the API.

Limitations of the API

There are no limitations in the API