Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

2    Sound Manager Reference

Multimedia

Exploring Palm OS®

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 ^TOP^

SndCallbackInfoType Struct ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

Purpose

Used to cast a pointer to the sound data used by SndPlayResource().

Declared In

SoundMgr.h

Prototype

typedef void *SndPtr

SndSampleType Typedef ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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, if dwStartMilliSec 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]. The default is 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. If false, 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 ^TOP^

Purpose

Represents a sampled stream. You create an SndStreamRef with SndStreamCreate().

Declared In

SoundMgr.h

Prototype

typedef uint32_t SndStreamRef

Sound Manager Constants ^TOP^

audio_type_t Enum ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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

#define sndMidiNameLength 32

sndMidiRecHdrSize ^TOP^

Purpose

Defines the header size of a MIDI record.

Declared In

SoundMgr.h

Constants

#define sndMidiRecHdrSize 6

sndMidiRecSignature ^TOP^

Purpose

Tags a MIDI record. It is used as the value of the signature field of the SndMidiRecHdrType structure.

Declared In

SoundMgr.h

Constants

#define sndMidiRecSignature 'PMrc'

sndSmfPlayAllMilliSec ^TOP^

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

#define sndSmfPlayAllMilliSec 0xFFFFFFFFUL

SndSmfCmdEnum Enum ^TOP^

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 ^TOP^

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

sndInput
Input stream used for recording.
sndOutput
Output stream used for playback.

SndStreamWidth Enum ^TOP^

Purpose

Defines constants that represent mono and stereo sampled data streams. Use these constants with the SndStreamCreate() function.

Declared In

SoundMgr.h

Constants

sndMono
Mono (one channel) stream.
sndStereo
Stereo (two channel) stream.

SndSysBeepType Enum ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 of sysFileCSoundMgr, 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 ^TOP^

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 ^TOP^

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 ^TOP^

SndCreateMidiList Function ^TOP^

Purpose

Generates a list of MIDI records.

Declared In

SoundMgr.h

Prototype

Boolean SndCreateMidiList (
   uint32_t creator,
   Boolean multipleDBs,
   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. Pass false 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 ^TOP^

Purpose

Asks the Sound Manager to perform a simple sound synthesis operation.

Declared In

SoundMgr.h

Prototype

status_t SndDoCmd (
   void *channelP,
   SndCommandPtr cmdP,
   Boolean noWait
)

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.

IMPORTANT: SndDoCmd() is always synchronous: The noWait value is currently ignored.

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 

Command

Function

Parameters

sndCmdFreqDurationAmp

Plays a tone. SndDoCmd() blocks until the tone has finished.

param1 is the tone's frequency in Hertz.

param2 is its duration in milliseconds.

param3 is its amplitude in the range [0, sndMaxAmp]. If the amplitude is 0, the sound isn't played and the function returns immediately.

sndCmdFrqOn

Initiates a tone. SndDoCmd() returns immediately while the tone plays in the background. Subsequent sound playback requests interrupt the tone.

param1 is the tone's frequency in Hertz.

param2 is its duration in milliseconds.

param3 is its amplitude in the range [0, sndMaxAmp]. If the amplitude is 0, the sound isn't played and the function returns immediately.

sndCmdNoteOn

Initiates a MIDI-defined tone. SndDoCmd() returns immediately while the tone plays in the background. Subsequent sound playback requests interrupt the tone.

param1 is the tone's pitch given as a MIDI key number in the range [0, 127].

param2 is the tone's duration in milliseconds.

param3 is its amplitude given as MIDI velocity [0, 127].

sndCmdQuiet

Stops the playback of the currently generated tone.

All parameter values are ignored.

See Also

SndPlaySmf()

SndGetDefaultVolume Function ^TOP^

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

Nothing.

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

SndSetDefaultVolume()

SndPlayResource Function ^TOP^

Purpose

Plays formatted sound data read from a resource or file.

Declared In

SoundMgr.h

Prototype

status_t SndPlayResource (
   SndPtr sndP,
   int32_t volume,
   uint32_t flags
)

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, or sndFlagAsync 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:

  1. Your resource memory remains locked for the duration of the sound.
  2. Your application does not exit for the duration of the sound.

Remember that you cannot stop a sound played with SndPlayResource().

SndPlaySmf Function ^TOP^

Purpose

Performs a Standard MIDI File, or returns the duration of the file.

Declared In

SoundMgr.h

Prototype

status_t SndPlaySmf (
   void *chanP,
   SndSmfCmdEnum cmd,
   uint8_t *smfP,
   SndSmfOptionsType *selP,
   SndSmfChanRangeType *chanRangeP,
   SndSmfCallbacksType *callbacksP,
   Boolean bNoWait
)

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) or SndSmfCmdDuration (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, pass NULL. For more information, including default settings, see SndSmfOptionsType.
chanRangeP
A pointer to a SndSmfChanRangeType structure that specifies the range of MIDI channels (in the SMF data) to use during playback. To play all channels, pass NULL.
callbacksP
A pointer to a SndSmfCallbacksType structure that holds your callback functions. Pass NULL 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 ^TOP^

Purpose

Plays a MIDI track read out of an open resource database.

Declared In

SoundMgr.h

Prototype

status_t SndPlaySmfResource (
   uint32_t resType,
   DmOpenRef dbRef,
   int16_t resID,
   SystemPreferencesChoice volumeSelector
)

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, or prefAlarmSoundVolume (all defined in Preferences.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 ^TOP^

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

Nothing.

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 ^TOP^

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

Nothing.

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

SndGetDefaultVolume()

SndStreamCreate Function ^TOP^

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,
   SndStreamMode mode,
   uint32_t samplerate,
   SndSampleType type,
   SndStreamWidth width,
   SndStreamBufferCallback func,
   void *userdata,
   uint32_t buffsize
)

Parameters

channel
Token that represents the newly created stream.
mode
One of the SndStreamMode constants that represents the "direction" of the data stream. Either sndInput (for recording), or sndOutput (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 is NULL, 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 ^TOP^

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,
   SndStreamMode mode,
   SndFormatType format,
   uint32_t samplerate,
   SndSampleType type,
   SndStreamWidth width,
   SndStreamVariableBufferCallback func,
   void *userdata,
   uint32_t buffsize
)

Parameters

channel
Token that represents the newly created stream.
mode
One of the SndStreamMode constants that represents the "direction" of the data stream. Either sndInput (for recording), or sndOutput (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 is NULL, 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 ^TOP^

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() or SndStreamCreateExtended().

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 ^TOP^

Purpose

Retrieves a stream's stereo balance.

Declared In

SoundMgr.h

Prototype

status_t SndStreamGetPan (
   SndStreamRef channel,
   int32_t *panposition
)

Parameters

channel
Stream token, as returned from SndStreamCreate() or SndStreamCreateExtended().
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

SndStreamSetPan()

SndStreamGetVolume Function ^TOP^

Purpose

Retrieves the amplitude scalar for a sound stream.

Declared In

SoundMgr.h

Prototype

status_t SndStreamGetVolume (
   SndStreamRef channel,
   int32_t *volume
)

Parameters

channel
Stream token, as returned from SndStreamCreate() or SndStreamCreateExtended().
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

SndStreamSetVolume()

SndStreamPause Function ^TOP^

Purpose

Pauses or resumes a sample stream.

Declared In

SoundMgr.h

Prototype

status_t SndStreamPause (
   SndStreamRef channel,
   Boolean pause
)

Parameters

channel
Stream token, as returned from SndStreamCreate() or SndStreamCreateExtended().
pause
If true, the function pauses the stream; if false, 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 ^TOP^

Purpose

Sets a stream's stereo balance.

Declared In

SoundMgr.h

Prototype

status_t SndStreamSetPan (
   SndStreamRef channel,
   int32_t panposition
)

Parameters

channel
Stream token, as returned from SndStreamCreate() or SndStreamCreateExtended().
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

SndStreamGetPan()

SndStreamSetVolume Function ^TOP^

Purpose

Sets the amplitude scalar for a sound stream.

Declared In

SoundMgr.h

Prototype

status_t SndStreamSetVolume (
   SndStreamRef channel,
   int32_t volume
)

Parameters

channel
Stream token, as returned from SndStreamCreate() or SndStreamCreateExtended().
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

SndStreamGetVolume()

SndStreamStart Function ^TOP^

Purpose

Starts a sample stream running.

Declared In

SoundMgr.h

Prototype

status_t SndStreamStart (
   SndStreamRef channel
)

Parameters

channel
Stream token, as returned from SndStreamCreate() or SndStreamCreateExtended().

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()

SndStreamStop Function ^TOP^

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() or SndStreamCreateExtended().

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 ^TOP^

SndBlockingFuncType Function ^TOP^

Purpose

A callback function that is invoked periodically during SMF playback.

Declared In

SoundMgr.h

Prototype

Boolean SndBlockingFuncType (
   void *chanP,
   uint32_t dwUserData,
   int32_t sysTicksAvailable
)
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()

SndComplFuncType Function ^TOP^

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_t dwUserData
)
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

Return nothing.

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

SndBlockingFuncType()

SndStreamBufferCallback Function ^TOP^

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,
   SndStreamRef channel,
   void *buffer,
   uint32_t numberofframes
)

Parameters

userdata
Caller-defined data, as provided in the userdata parameter to SndStreamCreate().
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 ^TOP^

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,
   SndStreamRef channel,
   void *buffer,
   uint32_t *bufferSizeP
)

Parameters

userdata
Caller-defined data, as provided in the userdata parameter to SndStreamCreateExtended().
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.