Sounds API
Changes in Sounds API documentation
Changes
There are no changes.
Purpose
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.
Constraints
There are no constraints.
Classification and release information
Sounds API is an SDK API. This
document is valid from S60 3rd Edition, Feature Pack 2 onwards.
Emulator support
This API is not supported in the WINS/WINSCW emulator environment.
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:
-
Obtaining keyboard sound system instance.
-
Playing sounds.
-
Defining application specific sounds.
-
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.
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.
Related APIs
-
CAknAppUi
-
CAknKeySoundSystem
-
CAknKeySoundSystem::NewL()
-
CAknSoundInfo
-
CAknSoundSystem
-
iDuration
-
iFrequency
-
iSequence
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();
}
Related APIs
-
CAknAppUi
-
CAknAppUiBase::KeySounds()
-
CAknKeySoundSystem
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
values 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);
Related APIs
-
CAknKeySoundSystem::PlaySound()
-
EAvkonSIDErrorTone
-
TAvkonSystemSID
Stopping a sound
If a sound is playing, it can be stopped with the
CAknKeySoundSystem::StopSound()
method:
iKeySounds->StopSound(EAvkonSIDErrorTone);
Related APIs
-
CAknKeySoundSystem::StopSound()
Related APIs
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:
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;
}
};
}
Related APIs
-
AVKON_SKEY_INFO
-
AVKON_SOUND_INFO
-
CAknKeySoundSystem::PlaySound()
-
CMdaAudioPlayerUtility
-
CMdaAudioToneUtility
-
EAvkonKeyClickPreference
-
EAvkonKeyClickPriority
-
PlaySound()
-
signature2
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);
}
Related APIs
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;}
};
}
Related APIs
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.
Related APIs
-
AddAppSoundInfoListL()
-
EAvkonSIDNoSound
-
PushContextL()
-
R_AVKON_SILENT_SKEY_LIST
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.
Related APIs
-
CAknSoundInfo
-
CMdaAudioPlayerUtility
-
CMdaAudioToneUtility
-
RequestSoundInfoL()
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 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
Related APIs
-
CAknAppUi
-
CAknKeySoundSystem
Glossary
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.
|
|
