Sounds API: API 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.

Use cases

The main use cases of Sounds API are:

1. Obtaining keyboard sound system instance.
2. Playing sounds.
   • Playing a sound by using a SID (Sound ID).
   • Stopping a sound.
3. Defining application specific sounds.
   • Defining a sound resource.
   • Registering a sound resource.
4. 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.
5. Obtaining system sound information.

API class structure

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.

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.