This chapter describes the Sound Manager API. It covers:
Sound Manager Structures and Types
Sound Manager Constants
Sound Manager Functions and Macros
Application-Defined Functions
The header files SoundMgr.h
and AudioTypes.h declare the API that this chapter describes.
For more information on the Sound Manager, see Chapter 1, "Sound Manager."
Sound Manager Structures and Types
SndCallbackInfoType Struct
Purpose
Encapsulates a callback function and its argument data. SndCallbackInfoType
is used by the SndSmfCallbacksType
structure, which is used to list the callback functions that are called during SMF playback.
Declared In
SoundMgr.h
Prototype
typedef struct SndCallbackInfoType { MemPtr funcP; uint32_t dwUserData; } SndCallbackInfoType
Fields
-
funcP
- A pointer to the callback function.
-
dwUserData
- Data that's passed as an argument to the callback function.
SndCommandType Struct
Purpose
Encapsulates a sound synthesis operation and its associated parameters. It is used by the SndDoCmd()
function.
Declared In
SoundMgr.h
Prototype
typedef struct SndCommandType { SndCmdIDType cmd; uint8_t reserved; uint16_t padding; int32_t param1; uint16_t param2; uint16_t param3; } SndCommandType
typedef SndCommandType *SndCommandPtr
Fields
-
cmd
- Constant that represents a sound operation. The operations are listed and described in
SndDoCmd()
. -
reserved
- Reserved for future use.
-
padding
- Padding bytes.
-
param1
,param2
,param3
- Operation-specific parameters. The parameters' meanings are described in
SndDoCmd()
.
SndMidiListItemType Struct
Purpose
Locates a MIDI file. This structure is used by the SndCreateMidiList()
function.
Declared In
SoundMgr.h
Prototype
typedef struct SndMidiListItemType { char name[sndMidiNameLength]; uint32_t uniqueRecID; DatabaseID dbH; } SndMidiListItemType
Fields
-
name
- The null-terminated name of the MIDI file.
-
uniqueRecID
- The ID of the record that holds the MIDI file.
-
dbH
- Database ID of the database that holds the record.
SndMidiRecHdrType Struct
Purpose
Encapsulates the header of a MIDI record.
Declared In
SoundMgr.h
Prototype
typedef struct SndMidiRecHdrType { uint32_t signature; uint8_t bDataOffset; uint8_t reserved; uint16_t padding; } SndMidiRecHdrType
Fields
-
signature
- The MIDI record signature. Always set this field to
sndMidiRecSignature
. -
bDataOffset
- Offset, in bytes, from the beginning of the record to the first byte of the MIDI data.
-
reserved
- Reserved for future use. Always set this field to 0.
-
padding
- Padding bytes (not counted toward the record size).
SndPtr Typedef
Purpose
Used to cast a pointer to the sound data used by SndPlayResource()
.
Declared In
SoundMgr.h
Prototype
typedef void *SndPtr
SndSampleType Typedef
Purpose
Used to specify the sample format (size, data type, endianness) of a sampled sound stream. Used by SndStreamCreate()
. See "audio_type_t" for the set of values that this type can contain.
Declared In
SoundMgr.h
Prototype
typedef audio_type_t SndSampleType
SndSmfCallbacksType Struct
Purpose
Contains a set of application-defined functions that are called during MIDI playback. To register your callback functions, call SndPlaySmf()
.
Declared In
SoundMgr.h
Prototype
typedef struct SndSmfCallbacksType { SndCallbackInfoType completion; SndCallbackInfoType blocking; SndCallbackInfoType reserved; } SndSmfCallbacksType
Fields
-
completion
- Completion function; see
SndComplFuncType()
. -
blocking
- Blocking function; see
SndBlockingFuncType()
. -
reserved
- Reserved. Set this field to 0.
SndSmfChanRangeType Struct
Purpose
Defines the range of enabled MIDI channels. Events on MIDI channels outside the enabled range are ignored. By default, no channels are enabled.
Declared In
SoundMgr.h
Prototype
typedef struct SndSmfChanRangeType { uint8_t bFirstChan; uint8_t bLastChan; } SndSmfChanRangeType
Fields
-
bFirstChan
- The first enabled channel in the range [0, 15].
-
bLastChan
- The last enabled channel in the range [0, 15].
IMPORTANT: The
SndSmfChanRangeType
structure expects MIDI channels to be in the range [0, 15]; real MIDI channel values are in the range [1, 16]. Thus, PalmSource MIDI channel 0 is real MIDI channel 1, PalmSource MIDI channel 1 is real MIDI channel 2, and so on.
SndSmfOptionsType Struct
Purpose
Defines MIDI performance parameters.
Declared In
SoundMgr.h
Prototype
typedef struct SndSmfOptionsType { uint32_t dwStartMilliSec; uint32_t dwEndMilliSec; uint16_t amplitude; Boolean interruptible; uint8_t reserved1; uint32_t reserved; } SndSmfOptionsType
Fields
-
dwStartMilliSec
- The "beginning of performance" marker, measured in milliseconds from the beginning of the track. A value of 0 plays the track from the beginning. The time difference between
dwStartMilliSec
and the performance time of the first subsequent MIDI event is respected. For example, ifdwStartMilliSec
is 2000 and the first (subsequent) note-on event is at 3000, there will be a 1000 millisecond "pause" before the note is played. -
dwEndMilliSec
- The "end of performance" marker, measured in milliseconds from the beginning of the track. To play to the end of the track, set this to
sndSmfPlayAllMilliSec
. -
amplitude
- The volume of the track, in the range [0,
sndMaxAmp
].sndMaxAmp
. If set to 0, the MIDI file isn't played. -
interruptible
- If
true
(the default), MIDI playback is interrupted if the user interacts with the controls (digitizer, buttons, etc.), even if the interaction doesn't generate a sound command. Iffalse
, playback is not interrupted. -
reserved1
- Reserved.
-
reserved
- Reserved. Set this field to 0.
Comments
This structure is used with the SndPlaySmf()
function to establish new parameter settings or to return the currently set values, depending on how the function is called. In the case where the structure returns values, only the "performance marker" fields (dwStartMilliSec
and dwEndMilliSec
) are valid.
SndStreamRef Typedef
Purpose
Represents a sampled stream. You create an SndStreamRef
with SndStreamCreate()
.
Declared In
SoundMgr.h
Prototype
typedef uint32_t SndStreamRef
Sound Manager Constants
audio_type_t Enum
Purpose
Defines a set of constants that represent the sample format (size, data type, endianness) of a sampled sound stream. These constant values are used with SndStreamCreate()
and SndStreamCreateExtended()
, as the value of the type SndSampleType
.
The lower four bits of these constants gives the size (in bytes) of a single sample, as shown here:
uint8_t byteSize = formatConstant & 0x0f
Declared In
AudioTypes.h
Constants
-
sndInt8 = 0x01
- Signed 8-bit data.
-
sndUInt8 = 0x11
- Unsigned 8-bit data.
-
sndInt16Big = 0x02
- Signed 16-bit integer data in big-endian format.
-
sndInt16Little = 0x12
- Signed 16-bit integer data in little-endian format.
-
sndInt32Big = 0x04
- Signed 32-bit integer data in big-endian format.
-
sndInt32Little = 0x14
- Signed 32-bit integer data in little-endian format.
-
sndFloatBig = 0x24
- Signed floating-point data in big-endian format.
-
sndFloatLittle = 0x34
- Signed floating-point data in little-endian format.
-
sndInt16 = sndInt16Little
- Signed 16-bit integer data in the device's native endianness.
-
sndInt16Opposite = sndInt16Big
- Signed 16-bit integer data in the endianness opposite to that of the device.
-
sndInt32 = sndInt32Little
- Signed 32-bit integer data in the device's native endianness.
-
sndInt32Opposite = sndInt32Big
- Signed 32-bit integer data in the endianness opposite to that of the device.
-
sndFloat = sndFloatLittle
- Signed floating-point data in the device's native endianness.
-
sndFloatOpposite = sndFloatBig
- Signed floating-point data in the endianness opposite to that of the device.
Comments
In the current implementation the 32-bit and floating point formats aren't supported.
Simple Sound Amplitudes
Purpose
These constants can be supplied to the simple sound functions (such as SndDoCmd()
) when an amplitude value is required. Note that these values are not compatible with the sampled sound amplitude range and thus shouldn't be used with the sampled sound functions.
Declared In
SoundMgr.h
Constants
-
#define sndDefaultAmp sndMaxAmp
- The maximum amplitude (full volume).
-
#define sndMaxAmp 64
- The default amplitude.
SndCmdIDType Enum
Purpose
Contains constants that represent specific sound operations used in simple sound playback with SndDoCmd()
.
Declared In
SoundMgr.h
Constants
-
sndCmdFreqDurationAmp = 1
- Play a tone.
SndDoCmd()
blocks until the tone has finished. -
sndCmdNoteOn
- Initiate a MIDI-defined tone.
SndDoCmd()
returns immediately while the tone plays in the background. Subsequent sound playback requests interrupt the tone. -
sndCmdFrqOn
- Initiate a tone.
SndDoCmd()
returns immediately while the tone plays in the background. Subsequent sound playback requests interrupt the tone. -
sndCmdQuiet
- Stop the playback of the currently generated tone.
SndFormatType Enum
Purpose
Defines a set of constants that represent various sound data encoding formats. Pass one of these constants as the format
argument to SndStreamCreateExtended()
.
Declared In
SoundMgr.h
Constants
-
sndFormatPCM = 0
- Pulse Code Modulation format. This is the "no encoding" format; the data is a series of samples that are linear with regard to amplitude quantization and regular with regard to sampling rate.
-
sndFormatIMA_ADPCM = 'APCM'
- The Interactive Multimedia Association's implementation of "adaptive delta" encoding. The sampling rate is constant, but the quantization is non-linear.
-
sndFormatDVI_ADPCM = 'DPCM'
- Microsoft's adaptive delta implementation. This is the same as IMA ADPCM.
-
sndFormatMP3 = 'MPG3'
- Motion Picture Group Audio Layer III.
-
sndFormatAAC = 'DAAC'
- Dolby Advanced Audio Coding.
-
sndFormatOGG = 'OGGV'
- OGG Vorbis encoding.
Comments
The implementation of SndStreamCreateExtended()
supports sndFormatPCM
data only. To play ADPCM data, use SndPlayResource()
.
sndMidiNameLength
Purpose
Defines the maximum string length, including the null terminator, for the name of a MIDI file or MIDI track.
Declared In
SoundMgr.h
Constants
sndMidiRecHdrSize
Purpose
Defines the header size of a MIDI record.
Declared In
SoundMgr.h
Constants
sndMidiRecSignature
Purpose
Tags a MIDI record. It is used as the value of the signature
field of the SndMidiRecHdrType
structure.
Declared In
SoundMgr.h
Constants
sndSmfPlayAllMilliSec
Purpose
Represents the (temporal) far end of a MIDI file. You can use this constant as the value of the dwEndMilliSec
field of the SndSmfOptionsType
structure before passing the structure to SndPlaySmf()
. This setting tells the function to play the entire file.
Declared In
SoundMgr.h
Constants
SndSmfCmdEnum Enum
Purpose
Defines a set of commands that tell SndPlaySmf()
whether it should play the file or simply return the duration of the file in milliseconds.
Declared In
SoundMgr.h
Constants
-
sndSmfCmdPlay = 1
- Play the specified Standard MIDI File.
-
sndSmfCmdDuration
- Return the duration, in milliseconds, of the specified Standard MIDI File.
SndStreamMode Enum
Purpose
Defines constants that represent the "direction" (input or output) of a sampled sound stream. Use these constants with the SndStreamCreate()
function.
Declared In
SoundMgr.h
Constants
SndStreamWidth Enum
Purpose
Defines constants that represent mono and stereo sampled data streams. Use these constants with the SndStreamCreate()
function.
Declared In
SoundMgr.h
Constants
SndSysBeepType Enum
Purpose
Defines a set of constants that represent pre-defined system beeps. In order to play one of these sounds, pass the corresponding value to SndPlaySystemSound()
.
Declared In
SoundMgr.h
Constants
-
sndInfo = 1
- Signals non-crucial information.
-
sndWarning
- Grabs the user's attention.
-
sndError
- Indicates an illegal operation.
-
sndStartUp
- Played at device start up time.
-
sndAlarm
- Generic alarm sound; note that this is not the Datebook's alarm sound.
-
sndConfirmation
- Indicates approval or acceptance.
-
sndClick
- The button click sound.
-
sndCardInserted
- Played when a card is inserted.
-
sndCardRemoved
- Played when a card is removed.
Sound Error Codes
Purpose
Error codes returned by various Sound Manager functions.
Declared In
SoundMgr.h
Constants
-
#define sndErrBadChannel (sndErrorClass | 2)
- Invalid sound channel.
-
#define sndErrBadParam (sndErrorClass | 1)
- Invalid parameter passed to a function.
-
#define sndErrBadStream (sndErrorClass | 8)
- Invalid data stream.
-
#define sndErrFormat (sndErrorClass | 7)
- Unsupported data format.
-
#define sndErrInterrupted (sndErrorClass | 9)
- Play was interrupted.
-
#define sndErrInvalidStream (sndErrorClass | 11)
- Invalid stream identifier.
-
#define sndErrMemory (sndErrorClass | 3)
- Insufficient memory.
-
#define sndErrNotImpl (sndErrorClass | 10)
- Function not implemented
-
#define sndErrOpen (sndErrorClass | 4)
- Tried to open a channel that's already open.
-
#define sndErrQEmpty (sndErrorClass | 6)
- Internal error.
-
#define sndErrQFull (sndErrorClass | 5)
- The sound queue is full.
Sound Resource Playback Flags
Purpose
Use these flags when calling SndPlayResource()
to specify various settings. Currently, the only setting is function synchronization.
Declared In
SoundMgr.h
Constants
-
#define sndFlagSync 0x00000000
- Tells
SndPlayResource()
to wait until all sound data has been fed to the DAC before returning (meaning that the function will return just a bit before the sound has finished playing). -
#define sndFlagAsync 0x00000001
- Tells
SndPlayResource()
to return immediately while playback continues in a separate thread. -
#define sndFlagNormal sndFlagSync
- A shorthand for the set of "normal" flag settings.
Sound Stream Feature Constants
Purpose
Used to retrieve the Sound Manager version number from the Feature Manager.
Declared In
SoundMgr.h
Constants
-
#define sndFtrIDVersion 0
- The feature number to supply to
FtrGet()
, along with a creator ID ofsysFileCSoundMgr
, when attempting to obtain the version of the Sound Manager. -
#define sndMgrVersionNum (100)
- The current version of the Sound Manager. Note that in Palm OS Cobalt version 6.0, this is set incorrectly to 100 (indicating version 1.00). The Sound Manager is actually version 1.01 in this release.
Stereo Pan Constants
Purpose
Define the extremes and the midpoint when altering the stream's stereo balance with SndStreamSetPan()
. SndStreamSetPan()
allows you to set the balance to one of these values, or any integral value between sndPanFullLeft
and sndPanFullRight
.
Declared In
SoundMgr.h
Constants
-
#define sndPanCenter (0)
- The stereo balance is centered.
-
#define sndPanFullLeft (-1024)
- The stereo balance is panned completely to the left.
-
#define sndPanFullRight (1024)
- The stereo balance is panned completely to the right.
Volume Constants Enum
Purpose
Use the volume constants defined in this enum with SndStreamSetVolume()
and SndPlayResource()
. The constants tell the functions to retrieve the named sound volume preference (as set by the user) and apply it as a volume setting.
Declared In
SoundMgr.h
Constants
-
sndSystemVolume = -1
- The user's system sound preference.
-
sndGameVolume = -2
- The user's game sound preference.
-
sndAlarmVolume = -3
- The user's alarm sound preference.
Sound Manager Functions and Macros
SndCreateMidiList Function
Purpose
Generates a list of MIDI records.
Declared In
SoundMgr.h
Prototype
Boolean SndCreateMidiList ( uint32_tcreator
, BooleanmultipleDBs
, uint16_t*wCountP
, MemHandle*entHP
)
Parameters
-
→ creator
- Creator ID of the database in which the function looks for MIDI records. Pass 0 to search all databases.
-
→ multipleDBs
- Pass
true
to search multiple databases for MIDI records. Passfalse
to search only in the first database that meets the search criteria. -
← wCountP
- Returns the number of MIDI records that were found.
-
← entHP
- Returns a pointer to an array of
SndMidiListItemType
structures, one structure for each record that was found.
Returns
true
if records were found, false
otherwise.
SndDoCmd Function
Purpose
Asks the Sound Manager to perform a simple sound synthesis operation.
Declared In
SoundMgr.h
Prototype
status_t SndDoCmd ( void*channelP
, SndCommandPtrcmdP
, BooleannoWait
)
Parameters
-
→ channelP
- Pointer to the sound channel on which you want to perform the operation. Pass
NULL
for the "shared" sound channel.
IMPORTANT: The Sound Manager only supports one channel of sound synthesis: You must pass
NULL
as the value of channelP
.
-
→ cmdP
- Pointer to a
SndCommandType
structure that describes the operation and contains any associated parameters. See the Comments section below for the set of sound commands and their associated parameters. -
→ noWait
- Sets the function to be asynchronous (
true
) or synchronous (false
) with respect to the caller.
Returns
errNone
if the operation completed successfully, or one of the following if an error occurs:
-
sndErrBadParam
- Invalid parameter.
-
sndErrBadChannel
- Invalid channel pointer.
-
sndErrQFull
- The sound queue is full.
Comments
The sound operations that are performed by SndDoCmd()
are encapsulated in the SndCommandType
structure. The cmd
field represents the operation, while the param
fields are data that's passed to the operation. The operations and data that SndDoCmd()
supports are described in the following table.
Table 2.1 SndDoCmd() commands and parameters
See Also
SndGetDefaultVolume Function
Purpose
Returns volume levels cached by the Sound Manager. This function is deprecated and should not be used.
Declared In
SoundMgr.h
Prototype
void SndGetDefaultVolume ( uint16_t*alarmAmpP
, uint16_t*sysAmpP
, uint16_t*masterAmpP
)
Parameters
-
← alarmAmpP
- Pointer to the alarm amplitude.
-
← sysAmpP
- Pointer to the system sound amplitude.
-
← masterAmpP
- Pointer to the master amplitude.
Returns
Comments
Pass NULL
for those settings that you don't care about.
Never call this function. To retrieve default volume levels, you should ask for the user's preferences settings.
See Also
SndPlayResource Function
Purpose
Plays formatted sound data read from a resource or file.
Declared In
SoundMgr.h
Prototype
status_t SndPlayResource ( SndPtrsndP
, int32_tvolume
, uint32_tflags
)
Parameters
-
→ sndP
- A pointer to the beginning of the formatted sound (including the header). Currently, only WAV data is recognized (see the Comments section, below); in this case,
sndP
must point to the "RIFF" ID (byte 0 in a simple.wav
file). -
→
volume
- Amplitude scalar, in the range [0, 32k]. See
SndStreamSetVolume()
for information on how amplitude scalar values are applied. -
→
flags
- One of the "Sound Resource Playback Flags." Currently, the only setting is function synchronization: use
sndFlagSync
to have the function wait until all sound data has been fed to the DAC before returning, orsndFlagAsync
flag to have the function return immediately while playback continues in a separate thread.
Returns
errNone
if the operation completed successfully, or one of the following if an error occurs:
-
sndErrBadParam
- The specified resource or file contains no data.
-
sndErrFormat
- The data is in an unsupported format.
-
sndErrMemory
- The function couldn't allocate sufficient memory.
-
other errors
- The device couldn't allocate system resources for the sound.
Comments
The supported WAVE parameters are:
- Uncompressed (PCM) or IMA 4-bit adaptive differential (IMA ADPCM). The ADPCM type is also known as DVI ADPCM; in a WAV file, it's known as format 0x11.
- One or two-channels
- Any sampling rate
You can't interrupt or abort a resource playback once it's been initiated. The resource always plays to the end of the data.
Example
The following code excerpt shows how to use this function to play a sound resource.
SndPtr soundP; MemHandle recordH; recordH = DmGetResource(myOpenDb,sysResTSound,TestWaveSound); soundP = (SndPtr) MemHandleLock(recordH); SndPlayResource(soundP,1024,sndFlagSync); // 1024 is 0dB (unity) gain MemHandleUnlock(recordH);
The above code first gets the resource from an open database. It then locks the memory associated with the resource and converts the result to a pointer to a sound resource.
The call to the SndPlayResource()
function plays the sound. The second parameter is the sound level, which varies from 0 to 32767. A value of 1024 specifies unity gain. Higher values indicate higher gain. The third parameter specifies whether the function returns immediately or waits until after the sound has finished playing. You should avoid using sndFlagAsync
, which causes the function to return immediately without waiting for the sound to finish, if you use this code because you'll unlock the sound resource before the system finishes with it. In fact, you should always specify sndFlagSync
unless you can guarantee two things:
- Your resource memory remains locked for the duration of the sound.
- Your application does not exit for the duration of the sound.
Remember that you cannot stop a sound played with SndPlayResource()
.
SndPlaySmf Function
Purpose
Performs a Standard MIDI File, or returns the duration of the file.
Declared In
SoundMgr.h
Prototype
status_t SndPlaySmf ( void*chanP
, SndSmfCmdEnumcmd
, uint8_t*smfP
, SndSmfOptionsType*selP
, SndSmfChanRangeType*chanRangeP
, SndSmfCallbacksType*callbacksP
, BooleanbNoWait
)
Parameters
-
→
chanP
- A pointer to the sound channel on which you want to perform the MIDI file. Pass
NULL
for the "shared" sound channel.
IMPORTANT: The Sound Manager only supports one channel of sound synthesis: You must pass
NULL
as the value of channel
.
-
→
cmd
- One of the SndSmfCmdEnum values: either
SndSmfCmdPlay
(play the file) orSndSmfCmdDuration
(return the duration of the file in milliseconds). -
→
smfP
- The MIDI data; this can point to a
SndMidiRecHdrType
structure, or it can point directly to the actual MIDI data bytes in memory. -
→
selP
- A pointer to a
SndSmfOptionsType
structure that defines performance parameters, such as volume, starting offset, and interruption tolerance. For default behavior, passNULL
. For more information, including default settings, seeSndSmfOptionsType
. -
→
chanRangeP
-
A
pointer to aSndSmfChanRangeType
structure that specifies the range of MIDI channels (in the SMF data) to use during playback. To play all channels, passNULL
. -
→ callbacksP
-
A
pointer to aSndSmfCallbacksType
structure that holds your callback functions. PassNULL
if you don't want any callbacks. -
→ bNoWait
- This value is ignored. This function always finishes playing the SMF selection before returning (but see the Comments section, below).
Returns
errNone
if the operation completed successfully, or one of the following if an error occurs:
-
sndErrBadParam
- Invalid value passed to this function.
-
sndErrBadChannel
- Invalid sound channel.
-
sndErrMemory
- Insufficient memory.
-
sndErrOpen
- Tried to open channel that's already open.
-
sndErrQFull
- Can't accept more notes.
-
sndErrFormat
- Unsupported data format.
-
sndErrBadStream
- Invalid data stream.
-
sndErrInterrupted
- Play was interrupted.
Comments
Although this call is always synchronous, you can register a "blocking" function that's called periodically as the MIDI file is playing. See SndBlockingFuncType()
for more information.
Normally, playback is halted by events generated by user interaction with the screen, digitizer, or hardware-based buttons. You can override this behavior by setting the interruptible
field of the selP
parameter to false
.
This function waits until any currently-playing simple sound has finished before starting playback of the requested MIDI data.
SndPlaySmfResource Function
Purpose
Plays a MIDI track read out of an open resource database.
Declared In
SoundMgr.h
Prototype
status_t SndPlaySmfResource ( uint32_tresType
, DmOpenRefdbRef
, int16_tresID
, SystemPreferencesChoicevolumeSelector
)
Parameters
-
→
resType
- SMF resource type.
-
→ dbRef
- Pointer to an open database. You can pass 0 to search all open resource databases for the specified resource type and ID.
-
→
resID
- SMF resource ID.
-
→ volumeSelector
- Volume setting; one of
prefSysSoundVolume
,prefGameSoundVolume
, orprefAlarmSoundVolume
(all defined inPreferences.h
).
Returns
errNone
if the track was played successfully, or one of the following if an error occurs:
-
sndErrBadParam
- The
volumeSelector
parameter is invalid or the SMF resource has invalid data. -
dmErrCantFind
- The specified resource doesn't exist.
-
other values
- See
SndPlaySmf()
.
Comments
This function plays the entire MIDI file using all MIDI channels. Playback is interrupted by a key down or digitizer event. No callbacks are specified.
This function waits until any currently playing simple sound has finished before starting playback of the requested MIDI data.
SndPlaySystemSound Function
Purpose
Plays a pre-defined (simple) system sound.
Declared In
SoundMgr.h
Prototype
void SndPlaySystemSound (
SndSysBeepType beepID
)
Parameters
-
→ beepID
- One of the system beep sound constants defined in the
SndSysBeepType
enum.
Returns
Comments
If you're playing an alarm (sndAlarm
), the user's alarm volume preference setting is used. For all other system sounds, the system volume preference is used.
Alarm sounds (sndAlarm
) are played synchronously: SndPlaySystemSound()
blocks until the sound has been played. All other sounds are played asynchronously.
SndSetDefaultVolume Function
Purpose
Sets the default sound volume levels cached by the Sound Manager.
Declared In
SoundMgr.h
Prototype
void SndSetDefaultVolume ( uint16_t*alarmAmpP
, uint16_t*sysAmpP
, uint16_t*defAmpP
)
Parameters
-
→ alarmAmpP
- Pointer to the alarm amplitude.
-
→ sysAmpP
- Pointer to the system sound amplitude.
-
→ defAmpP
- Pointer to the default amplitude for other sounds.
Returns
Comments
Any of the parameters may be NULL
. In that case, the corresponding setting is not altered.
NOTE: It is usually not appropriate for an application to be setting the default sound volume levels. Accordingly, this function is rarely used by applications.
See Also
SndStreamCreate Function
Purpose
Creates a new audio data stream that can be used to record or play back uncompressed, sampled audio data.
Declared In
SoundMgr.h
Prototype
status_t SndStreamCreate ( SndStreamRef*channel
, SndStreamModemode
, uint32_tsamplerate
, SndSampleTypetype
, SndStreamWidthwidth
, SndStreamBufferCallbackfunc
, void*userdata
, uint32_tbuffsize
)
Parameters
-
←
channel
- Token that represents the newly created stream.
-
→
mode
- One of the
SndStreamMode
constants that represents the "direction" of the data stream. EithersndInput
(for recording), orsndOutput
(for playback). -
→
samplerate
- Sampling rate, in frames-per-second. Specify the native rate of the data, such as 22050, 44100, or 48000.
-
→
type
- Sample quantization and endianness (but see the section on "Data Formats," below). Supply one of the values documented under "audio_type_t."
-
→
width
- One of the constants documented under "SndStreamWidth" that represents the number of channels of data in the stream.
-
→ func
- A callback function that gets called when another buffer is needed. See
SndStreamBufferCallback()
for a description of the callback function that you must implement. -
→ userdata
- Caller-defined data that is passed to the callback function.
-
→
buffsize
- Preferred size (in frames) for the buffers that are passed to the callback function,
func
. Note that the actual buffer size (as allocated by the Sound Manager) may be different from this request.
Returns
errNone
if the operation completed successfully, or one of the following if an error occurs:
-
sndErrBadParam
-
channel
is invalid,func
isNULL
, the sampling rate is too high (greater than 96000), or the device doesn't support some other specified sound parameter value. -
sndErrMemory
- All streams are being used (there is a maximum of 16), or memory for this stream couldn't otherwise be allocated.
-
other errors
- The device couldn't allocate system resources for the stream.
Comments
This function creates a new audio stream into which you can write (playback) or from which you can read (record) buffers of uncompressed, sampled audio data. The stream's "direction"—whether it will be used for recording or playback—is described by the mode
argument.
You can create one input stream and as many as 15 output streams. The "active" end of a stream is hardwired to read from or write to the device's sound driver. This means you can't "redirect" an input stream to read from a file (for example), nor can you connect one output stream to another output stream in an attempt to create a filter chain. You can, however, collect data from the input stream, manipulate it, and then write it to an output stream.
Data Formats
The format of the data that flows through the stream is described by the sampleRate
, type
, and width
arguments. If you're using an "extended" stream (see SndStreamCreateExtended()
), you can also declare the data's encoding.
If you look at the audio_type_t constants, you'll see four flavors for each quantization type: a big-endian version, a little-endian version, a native-endian version (defined as one of the other two), and an "opposite" version, which has endianness opposite that of the native version. In general, you should use the native-endian version when choosing a value for the type
parameter.
Running the Stream
The new stream starts running when you pass the channel
token returned by this function to the SndStreamStart()
function. This initiates a series of calls to your callback function (the func
parameter), which is where the action is: Each callback invocation is passed a buffer into which you write or from which you read a chunk of audio data. The callback function is also passed the userdata
parameter that you supply here. See SndStreamBufferCallback()
for more information on the callback function.
Buffering and Latency
Currently, audio streams are double-buffered. With regard to playback, this means that while one buffer (buffer A) is being played, your callback function is placing data in the other buffer (B). When A is "empty," the Sound Manager seamlessly starts playing buffer B, and passes buffer A back to your callback; when B is empty, it starts playing A, and passes back B, and so on. It's important that your callback function fills the data buffers as quickly as possible—certainly no longer than it takes to play a buffer of data. This same double-buffer scheme is also applied to sound recording although, of course, for recording you're emptying each buffer (and doing something with the data) in your callback function.
Regarding latency, you can use the buffsize
argument to suggest a buffer size and thereby increase or decrease latency, but you can't change the number of buffers. Keep in mind that the actual buffer size that's used may not be the same as the size you suggest; hardware and memory limitations may enforce a maximum or minimum buffer size. Also keep in mind that the buffer size is measured in frames (not bytes).
See Also
SndStreamStart()
, SndStreamDelete()
, SndStreamBufferCallback()
SndStreamCreateExtended Function
Purpose
Creates a new audio data stream that can be used to record or play back audio data.
Declared In
SoundMgr.h
Prototype
status_t SndStreamCreateExtended ( SndStreamRef*channel
, SndStreamModemode
, SndFormatTypeformat
, uint32_tsamplerate
, SndSampleTypetype
, SndStreamWidthwidth
, SndStreamVariableBufferCallbackfunc
, void*userdata
, uint32_tbuffsize
)
Parameters
-
←
channel
- Token that represents the newly created stream.
-
→
mode
- One of the
SndStreamMode
constants that represents the "direction" of the data stream. EithersndInput
(for recording), orsndOutput
(for playback). -
→
format
- Constant that represents the encoding format of the data that you propose to pour through the stream. See "SndFormatType," for a list of eligible values. Currently, only
sndFormatPCM
is supported. -
→
sampleRate
- Sampling rate, in frames-per-second. Specify the native rate of the data, such as 22050, 44100, or 48000. The maximum rate is 96000.
-
→
type
- Sample quantization and endianness (see "Data Formats" for advice on choosing this value). Supply one of the values documented under "audio_type_t."
-
→
width
- One of the constants documented under "SndStreamWidth" that represents the number of channels of data in the stream.
-
→
func
- A callback function that gets called when another buffer of data is needed. As implied by the name of the data type, the function accepts variable-sized buffers. See
SndStreamVariableBufferCallback()
for a description of the callback function that you must implement. -
→ userdata
- Caller-defined data that is passed to the callback function.
-
→
buffsize
- Preferred size (in frames) for the buffers that are passed to the callback function,
func
. Note that the actual buffer size (as allocated by the Sound Manager) may be different from this request.
Returns
errNone
if the operation completed successfully, or one of the following if there an error occurs:
-
sndErrBadParam
-
channel
is invalid,func
isNULL
, the sampling rate is too high (greater than 96000), or the device doesn't support some other specified sound parameter value. -
sndErrMemory
- All streams are being used (there is a maximum of 16), or memory for this stream couldn't otherwise be allocated.
-
other errors
- The device couldn't allocate system resources for the stream.
Comments
With a few minor exceptions, this function is equivalent to SndStreamCreate()
; see that function's Comments section for a description of how the stream creation functions generally work.
One difference between standard and extended streams: If you're using an extended stream, you can also declare the data's encoding. When selecting that encoding, be aware of the following:
- The data format that you specify for an input stream must match the data that's produced by the audio hardware.
- For an output stream, you can specify any of the formats that the Sound Manager supports; the data is automatically converted to the output hardware's native audio format. Whether your stream's format setting actually affects the hardware is undefined. For example, if you set an output stream to use a 48k sampling rate, that doesn't mean that the DAC will be set to 48k.
- Currently, only
sndFormatPCM
is supported.
Extended streams also allow for variable-sized buffers, as opposed to the fixed-sized buffers used by SndStreamCreate()
.This enables support for variable-length encoded data (such as MP3). To accommodate the variable-sized buffer, the callback function's prototype changes slightly for an extended stream: see SndStreamVariableBufferCallback()
for a full description of the callback function you use with SndStreamCreateExtended()
.
SndStreamDelete Function
Purpose
Stops the stream and deletes it.
Declared In
SoundMgr.h
Prototype
status_t SndStreamDelete (
SndStreamRef channel
)
Parameters
-
→ channel
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
.
Returns
errNone
if the operation completed successfully. Returns sndErrBadParam
if the channel
argument is invalid.
Comments
SndStreamDelete()
calls SndStreamStop()
before deleting the stream. You should never call SndStreamDelete()
from within your callback function.
SndStreamGetPan Function
Purpose
Retrieves a stream's stereo balance.
Declared In
SoundMgr.h
Prototype
status_t SndStreamGetPan ( SndStreamRefchannel
, int32_t*panposition
)
Parameters
-
→ channel
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
. -
← panposition
- Pan value in the range [-1024 (extreme left), 1024 (extreme right)]. Center balance is 0.
Returns
errNone
if the operation completed successfully. Returns sndErrBadParam
if channel
is invalid or panposition
is NULL
.
See Also
SndStreamGetVolume Function
Purpose
Retrieves the amplitude scalar for a sound stream.
Declared In
SoundMgr.h
Prototype
status_t SndStreamGetVolume ( SndStreamRefchannel
, int32_t*volume
)
Parameters
-
→ channel
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
. -
←
volume
- Amplitude scalar, in the range [0, 32k]. See
SndStreamSetVolume()
for more information.
Returns
errNone
if the operation completed successfully. Returns sndErrBadParam
if channel
is invalid or volume
is NULL
.
See Also
SndStreamPause Function
Purpose
Pauses or resumes a sample stream.
Declared In
SoundMgr.h
Prototype
status_t SndStreamPause ( SndStreamRefchannel
, Booleanpause
)
Parameters
-
→ channel
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
. -
→ pause
- If
true
, the function pauses the stream; iffalse
, it resumes the stream
Returns
errNone
if the operation completed successfully (which includes the situation where the stream is already in the requested state). Returns sndErrBadParam
if channel
is invalid.
Comments
Currently, SndStreamPause()
simply calls SndStreamStop()
(if pause
is true
) or SndStreamStart()
(if pause
is false
). See those functions for details about "pausing" and "resuming" a sound stream.
You can't nest pauses; a single resume request is effective, regardless of the number of times the stream has been told to pause.
SndStreamSetPan Function
Purpose
Sets a stream's stereo balance.
Declared In
SoundMgr.h
Prototype
status_t SndStreamSetPan ( SndStreamRefchannel
, int32_tpanposition
)
Parameters
-
→ channel
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
. -
→ panposition
- Pan value in the range [-1024 (full left), 1024 (full right)]. Center balance is 0. As a convenience, you can use the values described in "Stereo Pan Constants."" Note that values outside of the valid range may yield unexpected results (but don't generate an error).
Returns
errNone
if the operation completed successfully. Returns sndErrBadParam
if channel
is invalid.
Comments
The pan value is used as a scalar on a channel's volume such that a channel increases from 0 (inaudible) to full volume as the pan value moves from an extreme to 0. Graphically, it looks like this:

See Also
SndStreamSetVolume Function
Purpose
Sets the amplitude scalar for a sound stream.
Declared In
SoundMgr.h
Prototype
status_t SndStreamSetVolume ( SndStreamRefchannel
, int32_tvolume
)
Parameters
-
→ channel
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
. -
→ volume
- Amplitude scalar in the range [0, 32k]. Values less than 0 are converted to 1024 (unity gain).
Returns
errNone
if the operation completed successfully. Returns sndErrBadParam
if channel
is invalid.
Comments
The volume
value is applied as an amplitude scalar on the samples that this stream's callback function produces. The scalar is in the range [0, 32k], where 1024 is unity gain (that is, the samples are multiplied by 1.0). The mapping of volume
to a scalar is linear; thus a volume
of 512 scales the samples by ~0.5, and 2048 scales by ~2.0, and so on.
To specify a user preference volume setting, supply one of the constants documented under "Volume Constants." These values are guaranteed to be less than unity gain.
If the stream is stereo, both channels are scaled by the same amplitude scalar. To adjust the balance between the channels, use SndStreamSetPan()
.
See Also
SndStreamStart Function
Purpose
Starts a sample stream running.
Declared In
SoundMgr.h
Prototype
status_t SndStreamStart (
SndStreamRef channel
)
Parameters
-
→ channel
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
.
Returns
errNone
if the operation completed successfully (errNone
is returned even if the stream is already running). Returns sndErrBadParam
if channel
is invalid.
Comments
If the stream is already running, SndStreamStart()
returns immediately (with errNone
). If it isn't running, the function starts the stream by initiating invocations of its callback function. If the stream is paused (through SndStreamPause()
), the stream is resumed.
You can call this function from within another stream's callback function. This allows one stream to tell another stream to start playing.
See Also
SndStreamStop Function
Purpose
Stops a sample stream from running.
Declared In
SoundMgr.h
Prototype
status_t SndStreamStop (
SndStreamRef channel
)
Parameters
-
→ channel
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
.
Returns
errNone
if the operation completed successfully (errNone
is returned even if the stream is already stopped). Returns sndErrBadParam
if channel
is invalid.
Comments
Stops a running sound stream by neglecting to call the stream's callback function. The stream remains in this suspended state until you call SndStreamStart()
.
You can call this function from the stream's own callback function. In other words, a stream can stop itself.
Application-Defined Functions
SndBlockingFuncType Function
Purpose
A callback function that is invoked periodically during SMF playback.
Declared In
SoundMgr.h
Prototype
Boolean SndBlockingFuncType ( void*chanP
, uint32_tdwUserData
, int32_tsysTicksAvailable
)
typedef SndBlockingFuncType *SndBlockingFuncPtr
Parameters
-
→
chanP
- A pointer to the sound channel on which the file is being played. Currently always
NULL
. -
→
dwUserData
- Application-defined data that's specified when the callback function is registered.
-
→ sysTicksAvailable
- The amount of time, in milliseconds, available for completion of this function.
Returns
Return true
from your callback function if playback is to continue. Return false
if playback is to be aborted.
Comments
Your application's blocking callback is called whenever the MIDI parser is "between notes." Your application can do whatever it wants during this period, as long as it doesn't take more than sysTicksAvailable
milliseconds.
Specify your blocking callback function using the blocking
field of the SndSmfCallbacksType
structure that you pass to SndPlaySmf()
. Note that the blocking
field is a SndCallbackInfoType
structure; it contains a pointer to your callback function and a 32-bit value that is passed, as-is, to your callback.
See Also
SndComplFuncType Function
Purpose
A callback function that is invoked immediately after a MIDI file (SMF) finishes playing.
Declared In
SoundMgr.h
Prototype
void SndComplFuncType ( void*chanP
, uint32_tdwUserData
)
typedef SndComplFuncType *SndComplFuncPtr
Parameters
-
→
chanP
- A pointer to the sound channel on which the file was playing. Currently always
NULL
. -
→
dwUserData
- Application-defined data that's specified when the callback function is registered.
Returns
Comments
Specify your blocking callback function using the completion
field of the SndSmfCallbacksType
structure that you pass to SndPlaySmf()
. Note that the completion
field is a SndCallbackInfoType
structure; it contains a pointer to your callback function and a 32-bit value that is passed, as-is, to your callback.
See Also
SndStreamBufferCallback Function
Purpose
In input mode, delivers a data buffer to your application. In output mode, allows your application to supply the next buffer's worth of data.
Declared In
SoundMgr.h
Prototype
status_t ( *SndStreamBufferCallback ) ( void*userdata
, SndStreamRefchannel
, void*buffer
, uint32_tnumberofframes
)
Parameters
-
→
userdata
- Caller-defined data, as provided in the
userdata
parameter toSndStreamCreate()
. -
→
channel
- Token that represents the stream to which this buffer belongs.
-
→
buffer
- The data buffer.
-
→
numberofframes
- Number of sample frames the buffer contains.
Returns
Currently, the return value is ignored.
Comments
The SndStreamBufferCallback()
function that you create is invoked in input (recording) mode when the Sound Manager wants to deliver a new buffer of sound data to your application. In output (playback) mode, it is invoked when the Sound Manager needs another buffer of sound data. You associate your callback function with a given stream when you call SndStreamCreate()
.
In input mode, your callback function should read the data from the data buffer. In output mode, your callback function should write data into the data buffer (and it must fill the entire buffer with data). In either case, you want to do this as quickly as possible to avoid data underflow.
Note that the arguments passed to your callback function tell you nothing about the format of the data. You can use the userdata
argument to pass that information into the function.
See Also
SndStreamVariableBufferCallback()
SndStreamVariableBufferCallback Function
Purpose
In input mode, delivers a variable-length data buffer to your application. In output mode, allows your application to supply the next buffer's worth of data.
Declared In
SoundMgr.h
Prototype
status_t ( *SndStreamVariableBufferCallback ) ( void*userdata
, SndStreamRefchannel
, void*buffer
, uint32_t*bufferSizeP
)
Parameters
-
→
userdata
- Caller-defined data, as provided in the
userdata
parameter toSndStreamCreateExtended()
. -
→
channel
- Token that represents the stream that this buffer belongs to.
-
→
buffer
- The data buffer.
-
↔
bufferSizeP
- Size of the buffer, in bytes.
Returns
Currently, the return value is ignored.
Comments
The SndStreamVariableBufferCallback()
function that you create is invoked in input (recording) mode when the Sound Manager wants to deliver a new buffer of sound data to your application. In output (playback) mode, it is invoked when the Sound Manager needs another buffer of sound data. You associate your callback function with a given stream when you call SndStreamCreateExtended()
.
In input mode, your callback function should read the data from the data buffer. In output mode, your callback function should write data into the data buffer and then reset the value in bufferSizeP
to the amount of data that was actually written. Unlike SndStreamBufferCallback()
, your callback function is not required to fill the entire buffer with data. Moreover, the data that it writes to the buffer doesn't have to meet any other threshold or requirement—for example, the buffer doesn't have to represent a certain amount of playback time. This flexibility is provided in order to support variable-length encoded data (such as MP3).
Whether your callback is reading from the buffer or writing to it, it should do this as quickly as possible to avoid data underflow.
Note that the arguments passed to your callback function tell you nothing about the format of the data. You can use the userdata
argument to pass this information into the function.