Sounds API Specification

1 Overview

Sounds API can be used to play sounds (predefined system sounds or custom sounds), define new sounds, customize the application specific keyboard sounds and query the information of system sounds.

API category	public
API type	c++
Existed since	Legacy S60 0.9
API libraries	avkon.lib
Location	`/sf/mw/classicui/classicui_pub/sounds_api`
Buildfiles	`/sf/mw/classicui/classicui_pub/sounds_api/group/bld.inf`

1.1 Description

Sounds API is meant to be used by system and end-user applications. The API provides a simple way to play predefined system sounds or application specific custom sounds. Examples of system sounds include key click tone, warning tone, power off tone and battery low tone. An application can also use the Sounds API to define its own custom sounds by using a special resource structure. These custom sounds can then played directly, or used as key sounds overriding the default key click tones.

An application can customize its default keyboard sounds in quite a detailed level. It can define what sound is played when a certain hardware key is pressed, but it can also define the sounds for different key events of a certain key. There are three event types existing, which are "short", "long" and "repeat" events. For example, an application can define that left arrow key generates standard key click sound when it is pressed down, but does not generate any long or repeat sounds. This is very common use case when using Sounds API, i.e. just to disable key sounds of desired keys or events.

Customizing the keyboard sounds is done with key sound contexts. A key sound context defines a mapping between device keys and key sounds, i.e. telling which sound to play when certain key event occurs. Key sound contexts are stored in so called key sound stack, which is maintained by the Key Sound Server. Applications can perform common stack operations for key sound contexts, including e.g. push and pop operations. Only the topmost key sound context in the stack can be active.

Sounds API can also be used for querying the information of system sounds. This information can then be used e.g. to play system sounds directly with the classes offered by Multimedia Framework.

The logical type of the Sounds API is library API, so the API provides stand-alone implementation units (classes, methods, functions) that are used by the client.

The technical type of the API is method call API, so the client needs only use local objects. However, there is underlying client-server architecture with communications to Key Sound Server, but the user of Sounds API does not need to know the details about that.

1.1.1 Emulator support

This API is not supported in the WINS/WINSCW emulator environment.

1.2 Changes

Sounds API is an SDK API and was first published in S60 release 0.9. This document is valid from S60 release 3.2 onwards.

There are no constraints.

1.3 Use Cases

The main use cases of Sounds API are:

Obtaining keyboard sound system instance.
Playing sounds.
Playing a sound by using a SID (Sound ID).
Stopping a sound.

Defining application specific sounds.
Defining a sound resource.
Registering a sound resource.

Customizing key sounds of an application.
Defining a key sound context.
Pushing a context to the key sound stack.
Popping a context from the key sound stack.

Obtaining system sound information.

1.4 Class Structure

Summary of API classes and header files
Classes	Files

CAknKeySoundSystem /epoc32/include/mw/aknsoundsystem.h CAknSoundInfo /epoc32/include/mw/aknSoundinfo.h

The main class of Sounds API is CAknSoundSystem , which is the client interface to Key Sound Server. Applications can obtain a pointer to the CAknKeySoundSystem instance from the CAknAppUi base class or they can create a new instance by using CAknKeySoundSystem::NewL() . However, this document only concentrates on the first approach, because it is sufficient for the most use cases.

The client can use the CAknKeySoundSystem instance mainly to play or stop sounds, register its own sounds to Key Sound Server and push or pop sound contexts to override the default key sounds of the application. The client can also request the data of AVKON system sounds encapsulated in CAknSoundInfo objects.

UML diagram of CAknSoundSystem class

CAknSoundInfo class encapsulates the information of AVKON system sounds. The sounds are identified by Sound IDs (SIDs). There are three types of sounds supported, which are tone, tone sequence and file types. A tone sound contains just frequency and duration of the sound, sequence sound can have multiple tones in a sequence, and file sound refers to a file, for example a WAV file or some other format recognized by Multimedia Framework. CAknSoundInfo class has public data members for representing all of these three sound types. Only the relevant parameters are used at a time, depending on the sound type. For example, a tone sound uses the iFrequency and iDuration fields, and does not use the iSequence field at all.

UML diagram of CAknSoundInfo class

2 Using The 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.

2.1 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();
    }

2.2 Playing sounds

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

2.2.1 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);

2.2.2 Stopping a sound

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

iKeySounds->StopSound(EAvkonSIDErrorTone);

2.3 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.

2.3.1 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;
            }
        };
    }

2.3.2 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);
    }

2.4 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.

2.4.1 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;}
        };
    }

2.4.2 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.

2.4.3 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();
    }

2.5 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.

2.6 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.

2.7 Memory and Performance Considerations

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.

2.8 Extensions to the API

There are no extensions for the API.

2.9 Limitations of the API

There are no limitations in the API

3 Glossary

3.1 Abbreviations

SID

Sound ID.

3.2 Definitions

Key sound context	A mapping between device keys and sound IDs. Defines what sound to play when a certain key is pressed. Applications can define custom key sound contexts to override the default context.
Key sound stack	A stack in Key Sound Server containing key sound contexts. Only the topmost context can be active. Applications can make push and pop operations for sound contexts.
Sound ID	Defines an identifier for a Sound Info entry. Application specific SIDs should be in range (1..999). System SIDs have values starting from 1000.