The Palm OS Sound Manager controls two independent sound facilities:
- Simple sound: Single voice, monophonic, square-wave sound synthesis, useful for system beeps.
- Sampled sound: Stereo, multi-format, sampled data recording and playback. Sampled sounds can be generated programmatically or read from a soundfile.
These facilities are independent of each other. Although you can play a simple sound and a sampled sound at the same, their respective APIs have no effect on each other. For example, you can't use the sampled sound volume-setting function (SndStreamSetVolume()
) to change the volume of a simple sound.
Comparing the two facilities, simple sound is easy to understand and requires very little programming: In most cases, you load up a structure, call a function, and out pops a beep. Correspondingly, the sound itself is primitive. (An example of simple sound programming is given in "Sound Preferences," below.)
Sampled sound, on the other hand, is (or can be) much richer, but requires more planning than simple sound. How much more depends on what you're doing. Playing samples from a soundfile isn't much more difficult than playing a simple sound, but you have to supply a soundfile. Generating samples programmatically—and recording sound—requires more work: You have to implement a callback function that knows something about sound data.
IMPORTANT: One significant difference between simple sounds and sampled sounds is that they use different volume scales: Simple sound volumes are in the range [0, 64]; sampled sound volumes are [0, 1024].
The remainder of this chapter is limited to a discussion of simple sounds. More complex sounds fall under the heading of "Multimedia"; see Exploring Palm OS: Multimedia for complete conceptual and reference information.
Playing Simple Sounds
There are three ways to play a simple sound:
- You can play a single tone of a given pitch, amplitude, and duration by calling
SndDoCmd()
. - You can play a pre-defined system sound ("Information," "Warning," "Error," and so on) through
SndPlaySystemSound()
. - You can play a tune by passing in a Level 0 Standard MIDI File (SMF) through the
SndPlaySmf()
function. For example, the alarm sounds used in the built-in Date Book application are MIDI records stored in the System MIDI database. For information on MIDI and the SMF format, go to the official MIDI website,http://www.midi.org
.
Sound Preferences
If you're adding short, "informative" sounds to your application, such as system beeps, alarms, and the like, you should first consider using the (simple) system sounds that are defined by the Palm OS, as listed in the reference documentation for the SndPlaySystemSound()
function.
If you want to create your own system-like sounds, you should at least respect the user's preferences settings with regard to sound volume. There are a number of sound preference constants:
-
prefSysSoundVolume
is the default system volume. -
prefGameSoundVolume
is used for game sounds. -
prefAlarmSoundVolume
is used for alarms.
To apply a sound preference setting to a simple sound volume, you have to retrieve the setting and apply it yourself. For example, here we retrieve the alarm sound volume and use it to set the volume of a simple sound:
/* Create a 'sound command' structure. This will encode the parameters of the tone we want to generate. */ SndCommandType sndCommand; /* Ask for the 'play a tone' command. */ sndCommand.cmd = sndCmdFreqDurationAmp; /* Set the frequency and duration. */ sndCommand.param1 = 1760; sndCommand.param2 = 500; /* Now get the alarm volume and set it in the struct. */ sndCommand.param3 = PrefGetPreference (prefAlarmSoundVolume); /* Play the tone. */ SndDoCmd( 0, &sndCommand, true);
For greatest compatibility with multiple versions of the sound preferences mechanism, your application should check the version of Palm OS on which it is running. See "The Operating System Version Feature" for more information. For more information on preferences in general, see Chapter 33, "Preferences."
For reference information on the Sound Manager APIs, see Exploring Palm OS: Multimedia.