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

50    Sound Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter describes the API that's defined by the Sound Manager. You use this API to make and record sounds.

The Sound Manager controls two independent sound facilities:

  • "Simple" sound: single voice, monophonic, square-wave sound synthesis, useful for system beeps. This is the traditional (pre-Palm OS® Garnet) sound.
  • "Sampled" sound: stereo, multi-format, sampled data recording and playback (new in Palm OS Garnet).

The organization of this chapter reflects this division:

All elements described here are declared in SoundMgr.h.

For more information on the Sound Manager, see the section "Sound" in the Palm OS Programmer's Companion, vol. I.

Simple Sound Data Structures ^TOP^

SndCallbackInfoType Struct ^TOP^

Purpose

The SndCallbackInfoType structure 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.

Prototype

typedef struct SndCallbackInfoType {
MemPtr funcP;
UInt32 dwUserData;
} SndCallbackInfoType;

Fields

funcP
A pointer to the callback function.
dwUserData
Data that's passed as an argument to the function.

SndCommandType Struct ^TOP^

Purpose

The SndCommandType structure encapsulates a sound synthesis operation and its associated parameters. It is used by the SndDoCmd() function.

Prototype

typedef struct SndCommandType {
SndCmdIDType cmd;
UInt8 reserved;
Int32 param1;
UInt16 param2;
UInt16 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.
param1, param2, param3
Operation-specific parameters. The parameters' meanings are described in SndDoCmd().

Compatibility

The reserved field was introduced in the Palm OS 3.5 SDK. Consequently, when using a later SDK the compiler will complain when it encounters code that depends upon the presence or absence of this field. Code like this, for instance:


static SndCommandType onCmd = {sndCmdNoteOn,60,2200,127}; 

Instead of doing the above, set each of the structure's fields explicitly, like this:


SndCommandType onCmd; 
[...] 
onCmd.cmd = sndCmdNoteOn; 
onCmd.param1 = 60; 
onCmd.param2 = 2200; 
onCmd.param3 = 127; 

SndCmdIDType Typedef ^TOP^

Purpose

Type used to specify a sound operation to SndDoCmd() The constants that can be assigned to this type are documented under "SndCmdIDTag."

Prototype

typedef UInt8 SndCmdIDType;

SndMidiListItemType Struct ^TOP^

Purpose

A structure that locates a MIDI file. This structure is used by the SndCreateMidiList() function.

Prototype

typedef struct SndMidiListItemType{
Char name[sndMidiNameLength];
UInt32 uniqueRecID;
LocalID dbID;
UInt16 cardNo;
} SndMidiListItemType;

Fields

name
The null-terminated name of the MIDI file.
uniqueRecID
The ID of the record that holds the MIDI file.
dbID
Database ID of the database that holds the record.
cardNo
Card number on which the database that holds the record resides.

SndMidiRecHdrType Struct ^TOP^

Purpose

A structure that encapsulates the header of a MIDI record.

Prototype

typedef struct SndMidiRecHdrType {
UInt32 signature;
UInt8 bDataOffset;
UInt8 reserved;
} 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.

SndMidiRecType Struct ^TOP^

Purpose

The SndMidiRecType structure encapsulates the MIDI record header and the beginning of the human-readable name of the MIDI data.

Prototype

typedef struct SndMidiRecType {
SndMidiRecHdrType header;
Char name[2];
} SndMidiRecType

Fields

header
The MIDI record header.
name
The human-readable name of the MIDI data. The MIDI track name is a null-terminated string, even if it's empty. Contrary to the declaration, its length (including the null-terminator) varies; it's at least one byte and at most sndMidiNameLength bytes long.

SndSmfCallbacksType Struct ^TOP^

Purpose

A structure that contains a set of application-defined functions that are called during MIDI playback. To register your callback functions, call SndPlaySmf().

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

A structure that defines the range of enabled MIDI channels. Events on MIDI channels outside the enabled range are ignored. By default, no channels are enabled.

Prototype

typedef struct SndSmfChanRangeType {
UInt8 bFirstChan;
UInt8 bLastChan;
} SndSmfChanRangeType;

Fields

bFirstChan
The first enabled channel in the range [0, 15].
bLastChan
The last enabled channel in the range [0, 15].

WARNING! 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.

SndSmfCmdEnum Typedef ^TOP^

Purpose

Type used to specify a command to SndPlaySmf(). See "SndPlaySmf Commands" for the set of values that this type can contain.

Prototype

typedef UInt8 SndSmfCmdEnum;

SndSmfOptionsType Struct ^TOP^

Purpose

The SndSmfOptionsType structure establishes MIDI performance parameters. 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.

Prototype

typedef struct SndSmfOptionsType {
UInt32 dwStartMilliSec;
UInt32 dwEndMilliSec;
UInt16 amplitude;
Boolean interruptible;
UInt8 reserved1;
UInt32 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.

SndSysBeepType Typedef ^TOP^

Purpose

Type that specifies a system beep sound. This type is used by SndPlaySystemSound(). See "System Beeps" for the set of values that this type can contain.

Prototype

typedef UInt8 SndSysBeepType;

Simple Sound Constants ^TOP^

SndCmdIDTag Enum ^TOP^

Purpose

The SndCmdIDTag enumeration contains constants that represent specific sound operations used in simple sound playback with SndDoCmd().

Prototype

typedef enum SndCmdIDTag {
sndCmdFreqDurationAmp = 1,
sndCmdNoteOn,
sndCmdFrqOn,
sndCmdQuiet
}

Constants

sndCmdFreqDurationAmp
Play a tone. SndDoCmd blocks until the tone has finished.
sndCmdFrqOn
Initiate a tone. SndDoCmd returns immediately while the tone plays in the background. Subsequent sound playback requests interrupt the tone.
sndCmdNoteOn
Initiate a MIDI-defined 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.

Simple Sound Amplitudes ^TOP^

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.

Constant

Value

Description

sndMaxAmp

64

The maximum amplitude (full volume).

sndDefaultAmp

sndMaxAmp

The default amplitude.

sndMidiNameLength ^TOP^

Constant that defines the maximum string length, including the null terminator, for the name of a MIDI file or MIDI track.

#define sndMidiNameLength 32

sndMidiRecSignature ^TOP^

Constant that's used to tag a MIDI record. It is used as the value of the signature field of the SndMidiRecHdrType structure.

#define sndMidiRecSignature 'PMrc'

SndPlaySmf Commands Enum ^TOP^

Purpose

This enumeration defines a set of commands that tell SndPlaySmf() whether it should play the file or simply return the duration of the file in milliseconds.

Prototype

enum SndSmfCmdEnumTag {
sndSmfCmdPlay = 1,
sndSmfCmdDuration,
}

Constants

sndSmfCmdPlay
Play the specified Standard MIDI File.
sndSmfCmdDuration
Return the duration, in milliseconds, of the specified Standard MIDI File.

sndSmfPlayAllMilliSec ^TOP^

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.

#define sndSmfPlayAllMilliSec 0xFFFFFFFFUL

System Beeps Enum ^TOP^

Purpose

This enumeration declares a set of constants that represent pre-defined system beeps. In order to play one of these sounds, pass the corresponding value to SndPlaySystemSound().

Prototype

typedef enum SndSysBeepTag {
sndInfo = 1,
sndWarning,
sndError,
sndStartUp,
sndAlarm,
sndConfirmation,
sndClick
}

Constants

sndInfo
Heralds 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.

Simple Sound Functions ^TOP^

SndCreateMidiList Function ^TOP^

Purpose

Generate a list of MIDI records.

Declared In

SoundMgr.h

Prototype

Boolean SndCreateMidiList (
   UInt32creator,
   BooleanmultipleDBs,
   UInt16*recordCount,
   MemHandle*recordList
)

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.
recordCount
Returns the number of MIDI records that were found.
recordList
Returns a pointer to an array of SndMidiListItemType structures, one structure for each record that was found.

Returns

Returns true if records were found, false otherwise.

Compatibility

Implemented in Palm OS 3.0 and later.

SndDoCmd Function ^TOP^

Purpose

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

Declared In

SoundMgr.h

Prototype

Err SndDoCmd (
   void*channelP,
   SndCommandPtrcommandP,
   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.
commandP
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

Returns errNone if the operation completed successfully, or one of the following if an error occurred:

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 50.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.

Compatibility

Commands other than sndCmdFreqDurationAmp are implemented in Palm OS 3.0 and later. In OS versions earlier than 3.0, SndDoCmd will crash with a fatal error if you pass a command other than sndCmdFreqDurationAmp.

See Also

SndPlaySmf()

SndGetDefaultVolume Function ^TOP^

Purpose

Return volume levels cached by the Sound Manager.

Declared In

SoundMgr.h

Prototype

void SndGetDefaultVolume (
   UInt16*alarmAmpP,
   UInt16*sysAmpP,
   UInt16*masterAmpP
)

Parameters

alarmAmpP
Pointer to the alarm amplitude.
sysAmpP
Pointer to the system sound amplitude.
masterAmpP
Pointer to the master amplitude.

Comments

Pass NULL for those settings that you don't care about.

Compatibility

Never call this function in Palm OS Garnet. To retrieve default volume levels, you should ask for the user's preferences settings.

See Also

SndSetDefaultVolume()

SndInterruptSmfIrregardless Function ^TOP^

Purpose

Stop the currently playing MIDI file, even if the performance was declared to be intolerant of interruptions.

Declared In

SoundMgr.h

Prototype

Err SndInterruptSmfIrregardless (
   void
)

Returns

Always returns errNone.

Compatibility

Implemented only if 4.0 New Feature Set is present. However, if Palm OS Cobalt Feature Set is present this function is unimplemented.

See Also

SndPlaySmf(), SndPlaySmfResourceIrregardless()

SndPlaySmf Function ^TOP^

Purpose

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

Declared In

SoundMgr.h

Prototype

Err SndPlaySmf (
   void*channelP,
   SndSmfCmdEnumcommand,
   UInt8*midiDataP,
   SndSmfOptionsType*optionsP,
   SndSmfChanRangeType*channelRangeP,
   SndSmfCallbacksType*callbacksP,
   BooleannoWait
)

Parameters

channelP
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.
command
One of the SndPlaySmf Commands: either SndSmfCmdPlay (play the file) or SndSmfCmdDuration (return the duration of the file in milliseconds).
midiDataP
The MIDI data; this can point to an SndMidiRecHdrType structure, or it can point directly to the actual MIDI data bytes in memory.
optionsP
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.
channelRangeP
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.
noWait
This value is ignored. This function always finishes playing the SMF selection before returning (but see the Comments section, below).

Returns

Returns errNone if the operation completed successfully, or one of the following if there was an error:

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 optionsP argument to false.

This function waits until any currently-playing simple sound has finished before starting playback of the requested MIDI data. A similar function, SndPlaySmfIrregardless(), doesn't wait: it interrupts the current performance and immediately begins playback of the requested data.

Compatibility

Implemented in Palm OS 3.0 and later.

SndPlaySmfIrregardless Function ^TOP^

Purpose

Like SndPlaySmf(), but interrupts any currently playing simple sound, regardless of that sound's declared interruption tolerance.

Declared In

SoundMgr.h

Prototype

Err SndPlaySmfIrregardless (
   void*channelP,
   SndSmfCmdEnumcommand,
   UInt8*midiDataP,
   SndSmfOptionsType*optionsP,
   SndSmfChanRangeType*channelRangeP,
   SndSmfCallbacksType*callbacksP,
   BooleannoWait
)

Parameters

channelP
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.
command
One of the SndPlaySmf Commands: either SndSmfCmdPlay (play the file) or SndSmfCmdDuration (return the duration of the file in milliseconds).
midiDataP
The MIDI data; this can point to an SndMidiRecHdrType structure, or it can point directly to the actual MIDI data bytes in memory.
optionsP
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.
channelRangeP
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.
noWait
This value is ignored. This function always finishes playing the SMF selection before returning.

Returns

Returns errNone if the operation completed successfully, or one of the following if there was an error:

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 optionsP argument to false.

This function doesn't wait for any currently-playing simple sound to finish before starting playback of the requested MIDI data: it interrupts the current performance and immediately begins playback of the requested data. A similar function, SndPlaySmf(), waits for any currently-playing simple sound to finish before starting playback of the requested MIDI data.

Compatibility

Implemented only if 4.0 New Feature Set is present. However, if Palm OS Cobalt Feature Set is present this function is unimplemented.

SndPlaySmfResource Function ^TOP^

Purpose

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

Declared In

SoundMgr.h

Prototype

Err SndPlaySmfResource (
   UInt32resType,
   Int16resID,
   SystemPreferencesChoicevolume
)

Parameters

resType
SMF resource type.
resID
SMF resource ID.
volume
Volume setting; one of prefSysSoundVolume, prefGameSoundVolume, or prefAlarmSoundVolume (all defined in Preferences.h).

Returns

Returns errNone if the track was played successfully, or one of the following if an error occurred:

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. A similar function, SndPlaySmfResourceIrregardless(), doesn't wait: It interrupts the current performance and immediately begins playback of the requested data.

Compatibility

Implemented in Palm OS 3.2 and later.

SndPlaySmfResourceIrregardless Function ^TOP^

Purpose

Like SndPlaySmfResource(), but interrupts any currently playing simple sound, regardless of that sound's declared tolerance for interruption.

Declared In

SoundMgr.h

Prototype

Err SndPlaySmfResourceIrregardless (
    UInt32resType,
   Int16resID,
   SystemPreferencesChoicevolumeSelector
)

Parameters

resType
SMF resource type.
resID
SMF resource ID.
volume
Volume setting; one of prefSysSoundVolume, prefGameSoundVolume, or prefAlarmSoundVolume.

Returns

Returns errNone if the track was played successfully, or one of the following if an error occurred:

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 doesn't wait for any currently playing simple sound to finish before starting playback of the requested MIDI data: it interrupts the current performance and immediately begins playback of the requested data. A similar function, SndPlaySmfResource(), does wait.

Compatibility

Implemented only if 4.0 New Feature Set is present. However, if Palm OS Cobalt Feature Set is present this function is unimplemented.

SndPlaySystemSound Function ^TOP^

Purpose

Play a pre-defined (simple) system sound.

Declared In

SoundMgr.h

Prototype

void SndPlaySystemSound (
   SndSysBeepTypebeepID
)

Parameters

beepID
One of the system beep sound constants defined in the System Beeps enum.

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

Set the default sound volume levels cached by the Sound Manager.

Declared In

SoundMgr.h

Prototype

void SndSetDefaultVolume (
   UInt16*alarmAmpP,
   UInt16*sysAmpP,
   UInt16*masterAmpP
)

Parameters

alarmAmpP
Pointer to the alarm amplitude.
sysAmpP
Pointer to the system sound amplitude.
masterAmpP
Pointer to the master amplitude.

Returns

Returns nothing.

Comments

Any of the arguments 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()

Simple Sound Application-Defined Functions ^TOP^

SndBlockingFuncType Function ^TOP^

Purpose

A callback funtion that is invoked periodically during SMF playback.

Declared In

SoundMgr.h

Prototype

Boolean SndBlockingFuncType (
   void*channelP,
   UInt32userData,
   Int32time
)

Parameters

channelP
A pointer to the sound channel on which the file is being played. Currently always NULL.
userData
Application-defined data that's specified when the callback function is registered.
time
The amount of time, in milliseconds, available for completion of this function.

Returns

Return true from your callback 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 time 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*channelP,
   UInt32userData
)

Parameters

channelP
A pointer to the sound channel on which the file was played; currently always NULL.
userData
Application-defined data that's specified when the callback function is registered.

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.

Sampled Sound Data Structures ^TOP^

SndFormatType Typedef ^TOP^

Purpose

Data type used to contain the encoding format of the data that you propose to pour through the stream with SndStreamCreateExtended(). See "Sound Data Encoding Formats" for the set of values that this type can contain.

Prototype

typedef UInt32 SndFormatType;

SndPtr Typedef ^TOP^

Purpose

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

Prototype

typedef void *SndPtr;

Compatibility

Implemented if Sound Stream Feature Set is present.

SndSampleType Typedef ^TOP^

Purpose

Data type used to specify the sample format (size, data type, endianness) of a sampled sound stream. Used by SndStreamCreate(). See "SndSampleTag" for the set of values that this type can contain.

Prototype

typedef Enum16 SndSampleType;

Compatibility

Implemented if Sound Stream Feature Set is present.

SndStreamMode Typedef ^TOP^

Purpose

Data type used to specify the "direction" (input or output) of a sampled sound stream. Used by the SndStreamCreate() function. See "SndStreamModeTag" for the set of values that this type can contain.

Prototype

typedef Enum8 SndStreamMode;

Compatibility

Implemented if Sound Stream Feature Set is present.

SndStreamRef Typedef ^TOP^

Purpose

Data type that represents a sampled stream. You create an SndStreamRef with SndStreamCreate().

Prototype

typedef UInt32 SndStreamRef;

Compatibility

Implemented if Sound Stream Feature Set is present.

SndStreamWidth Typedef ^TOP^

Purpose

Data type that specifies whether a sampled data stream is in stereo or mono. This data type is used by the SndStreamCreate() function. See "SndStreamWidthTag" for the set of values that this type can contain.

Prototype

typedef Enum8 SndStreamWidth;

Compatibility

Implemented if Sound Stream Feature Set is present.

Sampled Sound Constants ^TOP^

Sound Stream Feature Constants ^TOP^

To detect the presence of the Sound Stream Feature Set you check for the Sound Manager's version number feature. If the Sound Manager's version feature is defined, the Sound Stream feature set is supported.

Constant

Value

Description

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.

sndMgrVersionNum

(100)

The current version of the Sound Manager.

Sound Data Encoding Formats Enum ^TOP^

Purpose

The SndFormatTag enum defines a set of constants that represent various sound data encoding formats. Pass one of these constants as the encodingFormat argument to SndStreamCreateExtended().

Prototype

enum SndFormatTag  {
sndFormatPCM = 0,
sndFormatIMA_ADPCM = 'APCM',
sndFormatDVI_ADPCM = 'DPCM',
sndFormatMP3 = 'MPG3',
sndFormatAAC = 'DAAC',
sndFormatOGG = 'OGGV'
} 

Constants

sndFormatPCM
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
The Interactive Multimedia Association's implementation of "adaptive delta" encoding. The sampling rate is constant, but the quantization is non-linear.
sndFormatDVI_ADPCM
Microsoft's adaptive delta implementation. This is the same as IMA ADPCM.
sndFormatMP3
Motion Picture Group Audio Layer III.
sndFormatAAC
Dolby Advanced Audio Coding.
sndFormatOGG
OGG Vorbis encoding.

Compatibility

Implemented if Sound Stream Feature Set is present. The Palm OS Garnet implementation of SndStreamCreateExtended() supports sndFormatPCM data only. To play ADPCM data, use SndPlayResource().

SndSampleTag Enum ^TOP^

Purpose

The SndSampleTag enum 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().

The lower four bits of these constants gives the size (in bytes) of a single sample, as shown here:


UInt8 byteSize = formatConstant & 0x0f 

Prototype

enum SndSampleTag {
sndInt8 = 0x01,
sndUInt8 = 0x11,
sndInt16Big = 0x02,
sndInt16Little = 0x12,
sndInt32Big = 0x04,
sndInt32Little = 0x14,
sndFloatBig = 0x24,
sndFloatLittle = 0x34,
#if CPU_ENDIAN == CPU_ENDIAN_BIG
sndInt16 = sndInt16Big,
sndInt16Opposite = sndInt16Little,
sndInt32 = sndInt32Big,
sndInt32Opposite = sndInt32Little,
sndFloat = sndFloatBig,
sndFloatOpposite= sndFloatLittle
#else
sndInt16 = sndInt16Little,
sndInt16Opposite = sndInt16Big,
sndInt32 = sndInt32Little,
sndInt32Opposite= sndInt32Big,
sndFloat = sndFloatLittle,
sndFloatOpposite= sndFloatBig
#endif
}

Constants

sndFloat
Signed floating-point data in the device's native endianness.
sndFloatBig
Signed floating-point data in big-endian format.
sndFloatLittle
Signed floating-point data in little-endian format.
sndFloatOpposite
Signed floating-point data in the endianness opposite to that of the device.
sndInt16
Signed 16-bit integer data in the device's native endianness.
sndInt16Big
Signed 16-bit integer data in big-endian format.
sndInt16Little
Signed 16-bit integer data in little-endian format.
sndInt16Opposite
Signed 16-bit integer data in the endianness opposite to that of the device.
sndInt32
Signed 32-bit integer data in the device's native endianness.
sndInt32Big
Signed 32-bit integer data in big-endian format.
sndInt32Little
Signed 32-bit integer data in little-endian format.
sndInt32Opposite
Signed 32-bit integer data in the endianness opposite to that of the device.
sndInt8
Signed 8-bit data.
sndUInt8
Unsigned 8-bit data.

Compatibility

Implemented if Sound Stream Feature Set is present. In Palm OS Garnet, the 32-bit and floating point formats aren't supported.

SndStreamModeTag Enum ^TOP^

Purpose

The SndStreamModeTag enum defines constants that represent the "direction" (input or output) of a sampled sound stream. Use these constants with the SndStreamCreate() function.

Prototype

enum SndStreamModeTag {
sndInput,
sndOutput
}

Constants

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

Compatibility

Implemented if Sound Stream Feature Set is present.

SndStreamWidthTag Enum ^TOP^

Purpose

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

Prototype

enum SndStreamWidthTag {
sndMono,
sndStereo
}

Constants

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

Compatibility

Implemented if Sound Stream Feature Set is present.

Sound Resource Playback Flags ^TOP^

Use these flags when calling SndPlayResource() to specify various settings. Currently, the only setting is function synchronization.

Constant

Value

Description

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

sndFlagAsync

0x00000001

Tells SndPlayResource to return immediately while playback continues in a separate thread.

sndFlagNormal

sndFlagSync

A shorthand for the set of "normal" flag settings.

Compatibility

Implemented if Sound Stream Feature Set is present.

Stereo Pan Constants ^TOP^

These constants 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.

Constant

Value

Description

sndPanCenter

(0)

The stereo balance is centered.

sndPanFullLeft

(-1024)

The stereo balance is panned completely to the left.

sndPanFullRight

(1024)

The stereo balance is panned completely to the right.

Compatibility

Implemented if Sound Stream Feature Set is present.

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.

Prototype

enum {
sndSystemVolume = -1,
sndGameVolume = -2,
sndAlarmVolume = -3
}

Constants

sndSystemVolume
The user's system sound preference.
sndGameVolume
The user's game sound preference.
sndAlarmVolume
The uer's alarm sound preference.

Compatibility

Implemented if Sound Stream Feature Set is present.

Sampled Sound Functions ^TOP^

SndPlayResource Function ^TOP^

Purpose

Play formatted sound data read from a resource or file.

Declared In

SoundMgr.h

Prototype

Err SndPlayResource (
   SndPtrsoundP,
   Int32volume,
   UInt32flags
)

Parameters

soundP
A pointer to the beginning of the formatted sound (including the header). Currently, only WAVE data is recognized (see the Comments section, below); in this case, soundP 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

Returns errNone if the operation completed successfully, or one of the following if there was an error:

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 WAVE file, it's known as format 0x11.
  • One or two-channels
  • All normal sampling rates (8k, 11k, 22.05k, 44.1k, 48, 96k).

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 = DmGet1Resource(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 the last opened database. (You can use DmGetResource() instead if you have more than one database open.) It then locks the memory associated with the resource and converts the result to a pointer to a sournd 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().

Compatibility

Implemented if Sound Stream Feature Set is present.

SndStreamCreate Function ^TOP^

Purpose

Create a new audio data stream that can be used to record or play back uncompressed, sampled audio data.

Declared In

SoundMgr.h

Prototype

Err SndStreamCreate (
   SndStreamRef*streamP,
   SndStreamModemode,
   UInt32sampleRate,
   SndSampleTypetype,
   SndStreamWidthwidth,
   SndStreamBufferCallbackcallback,
   void*callbackArgP,
   UInt32bufferSize,
   BooleancallbackIsARM
)

Parameters

streamP
Token that represents the newly created stream.
mode
One of the SndStreamModeTag 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. The maximum rate is 96000.
type
Sample quantization and endianness (but see the section on "Data Formats," below). Supply one of the values documented under "SndSampleTag."
width
One of the constants documented under "SndStreamWidthTag" that represents the number of channels of data in the stream.
callback
A callback function that gets called when another buffer is needed. See SndStreamBufferCallback() for a description of the callback function that you must implement.
callbackArgP
Caller-defined data that gets passed to callback.
bufferSize
Preferred size (in frames) for the buffers that are passed to callback. Note that the actual buffer size (as allocated by the Sound Manager) may be different from this request.
callbackIsARM
Pass true if the callback function is written in ARM-native code, or false if it is written in 68k code.

Returns

Returns errNone if the operation completed successfully, or one of the following if there was an error:

sndErrBadParam
streamP is invalid, callback is NULL, the sampling rate is too high (greater than 96000), or the device doesn't like some other sound parameter value.
sndErrorMemory
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 SndSampleTag 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. The one exception to this (in Palm OS Garnet) is if your application is written for 68k, but uses an ARM callback function (that is, callbackIsARM == true). In this case you should use one of the little-endian formats as the type value when you create your stream.

Running the Stream

The new stream starts running when you pass the stream token returned by this function to the SndStreamStart() function. This initiates a series of calls to your callback function, 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 callbackArg 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 bufferSize 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 bufferSize is measures in frames (not bytes).

See Also

SndStreamStart(), SndStreamDelete(), SndStreamBufferCallback()

Compatibility

Implemented if Sound Stream Feature Set is present.

SndStreamCreateExtended Function ^TOP^

Purpose

Create a new audio data stream that can be used to record or play back audio data.

Declared In

SoundMgr.h

Prototype

Err SndStreamCreate (
   SndStreamRef*streamP,
   SndStreamModemode,
   SndFormatTypeencodingFormat,
   UInt32sampleRate,
   SndSampleTypetype,
   SndStreamWidthwidth,
   SndStreamVariableBufferCallbackcallback,
   void*callbackArgP,
   UInt32bufferSize,
   BooleancallbackIsARM
)

Parameters

streamP
Token that represents the newly created stream.
mode
One of the SndStreamModeTag constants that represents the "direction" of the data stream. Either sndInput (for recording), or sndOutput (for playback).
encodingFormat
Constant that represents the encoding format of the data that you propose to pour through the stream. See SndFormatType for a list of elligible 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 "SndSampleTag."
width
One of the constants documented under "SndStreamWidthTag" that represents the number of channels of data in the stream.
callback
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.
callbackArgP
Caller-defined data that gets passed to callback.
bufferSize
Preferred size (in frames) for the buffers that are passed to callback. Note that the actual buffer size (as allocated by the Sound Manager) may be different from this request.
callbackIsARM
Pass true if the callback function is written in ARM-native code, or false if it is written in 68k code.

Returns

Returns errNone if the operation completed successfully, or one of the following if there was an error:

sndErrBadParam
streamP is invalid, callback is NULL, the sampling rate is too high (greater than 96000), or the device doesn't like some other sound parameter value.
sndErrorMemory
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

Stop the stream and destroy it.

Declared In

SoundMgr.h

Prototype

Err SndStreamDelete (
   SndStreamRefstream
)

Parameters

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

Returns

Returns errNone if the operation completed successfully. Returns sndErrBadParam if the stream argument is invalid.

Comments

SndStreamDelete calls SndStreamStop() before destroying the stream. You should never call SndStreamDelete from within your callback function.

Compatibility

Implemented if Sound Stream Feature Set is present.

SndStreamGetPan Function ^TOP^

Purpose

Retrieve a stream's stereo balance.

Declared In

SoundMgr.h

Prototype

Err SndStreamGetPan (
   SndStreamRefstream,
   Int32*panP
)

Parameters

stream
Stream token, as returned from SndStreamCreate() or SndStreamCreateExtended().
panP
Pan value in the range [-1024 (hard left), 1024 (hard right)]. Center balance is 0.

Returns

Returns errNone if the operation completed successfully. Returns sndErrBadParam if stream is invalid or panP is NULL.

Compatibility

Implemented if Sound Stream Feature Set is present.

See Also

SndStreamSetPan()

SndStreamGetVolume Function ^TOP^

Purpose

Retrieve the amplitude scalar for a sound stream.

Declared In

SoundMgr.h

Prototype

Err SndStreamGetVolume (
   SndStreamRefstream,
   Int32*volumeP
)

Parameters

stream
Stream token, as returned from SndStreamCreate() or SndStreamCreateExtended().
volumeP
Amplitude scalar, in the range [0, 32k]. See SndStreamSetVolume() for more information.

Returns

Returns errNone if the operation completed successfully. Returns sndErrBadParam if stream is invalid or volumeP is NULL.

See Also

SndStreamSetVolume()

Compatibility

Implemented if Sound Stream Feature Set is present.

SndStreamPause Function ^TOP^

Purpose

Pause or resume a sample stream.

Declared In

SoundMgr.h

Prototype

Err SndStreamPause (
   SndStreamRefstream,
   Booleanpause
)

Parameters

stream
Stream token, as returned from SndStreamCreate() or SndStreamCreateExtended().
pause
If true, the function pauses the stream; if false, it resumes the stream

Returns

Returns errNone if the operation completed successfully (which includes the situation where the stream is already in the requested state). Returns sndErrBadParam if stream 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.

Compatibility

Implemented if Sound Stream Feature Set is present.

SndStreamSetPan Function ^TOP^

Purpose

Sets a stream's stereo balance.

Declared In

SoundMgr.h

Prototype

Err SndStreamSetPan (
   SndStreamRefstream,
   Int32pan
)

Parameters

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

Returns errNone if the operation completed successfully. Returns sndErrBadParam if stream 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:

Compatibility

Implemented if Sound Stream Feature Set is present.

See Also

SndStreamGetPan()

SndStreamSetVolume Function ^TOP^

Purpose

Sets the amplitude scalar for a sound stream.

Declared In

SoundMgr.h

Prototype

Err SndStreamSetVolume (
   SndStreamRefstream,
   Int32volume
)

Parameters

stream
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

Returns errNone if the operation completed successfully. Returns sndErrBadParam if stream 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 (i.e. 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 ~.5, 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().

Compatibility

Implemented if Sound Stream Feature Set is present.

SndStreamStart Function ^TOP^

Purpose

Start a sample stream running.

Declared In

SoundMgr.h

Prototype

Err SndStreamStart (
   SndStreamRef stream
)

Parameters

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

Returns

Returns errNone if the operation completed successfully (errNone is returned even if the stream is already running). Returns sndErrBadParam if stream 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.

Compatibility

Implemented if Sound Stream Feature Set is present.

SndStreamStop Function ^TOP^

Purpose

Stop a sample stream from running.

Declared In

SoundMgr.h

Prototype

Err SndStreamStop (
   SndStreamRef stream
)

Parameters

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

Returns

Returns errNone if the operation completed successfully (errNone is returned even if the stream is already stopped). Returns sndErrBadParam if stream 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.

Compatibility

Implemented if Sound Stream Feature Set is present.

Sampled Sound Application-Defined Functions ^TOP^

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

Err (
   *SndStreamBufferCallback
) (
   void*userDataP,
   SndStreamRefstream,
   void*bufferP,
   UInt32frameCount
)

Parameters

userDataP
Caller-defined data, as provided in the callbackArg parameter to SndStreamCreate().
stream
Token that represents the stream to which this buffer belongs.
bufferP
The data buffer.
frameCount
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 userDataP argument to pass this information into the function.

The callback function is executed in a task that's created and managed by the Sound Manager. Because of this, the function doesn't have access to the symbols that you create in your application. Again, use the userDataP argument if you need to pass pointers to your symbols.

Compatibility

Implemented if Sound Stream Feature Set is present.

See Also

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

Err (
   *SndStreamVariableBufferCallback
) (
    void*userDataP,
   SndStreamRefstream,
   void*bufferP,
   UInt32*bufferSizeP
)

Parameters

userDataP
Caller-defined data, as provided by the callbackArg parameter to SndStreamCreateExtended().
stream
Token that represents the stream that this buffer belongs to.
bufferP
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 *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 userDataP argument to pass this information into the function.

The callback function is executed in a task that's created and managed by the Sound Manager. Because of this, the function doesn't have access to the symbols that you create in your application. Again, use the userDataP argument if you need to pass pointers to your symbols.

Compatibility

Implemented if Sound Stream Feature Set is present.

See Also

SndStreamCreateExtended(), SndStreamBufferCallback()