Sounds API
Changes in Sounds API documentation
ChangesThere are no changes.
PurposeSounds 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.
ConstraintsThere 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 supportThis API is not supported in the WINS/WINSCW emulator environment.
API descriptionSounds 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 casesThe 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 structureThe 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 APIFor 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 instanceA 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 soundIf 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 soundsIf 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 resourceApplications 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 resourceOnce 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 applicationCustomizing 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 contextA 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 stackThe 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 stackThe 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 informationThe 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 handlingSome 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 overheadFor 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 APIThere 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.
|
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|