Previous Book Contents Book Index Next

Inside Macintosh: Sound /
Chapter 3 - Sound Input Manager / Sound Input Manager Reference
Sound Input Manager Routines / Constructing Sound Resource and File Headers


Legacy Documentclose button

Important: Inside Macintosh: Sound is deprecated as of Mac OS X v10.5. For new audio development in Mac OS X, use Core Audio. See the Audio page in the ADC Reference Library.

SetupSndHeader

You can use the SetupSndHeader function to construct a sound resource containing sampled sound that can be passed to the SndPlay function.

FUNCTION SetupSndHeader (sndHandle: Handle;
                           numChannels: Integer;
                           sampleRate: Fixed;
                           sampleSize: Integer; 
                           compressionType: OSType; 
                           baseFrequency: Integer; 
                           numBytes: LongInt; 
                           VAR headerLen: Integer): OSErr;
sndHandle
A handle to a block of memory that is at least large enough to store the sound resource header information. The handle is not resized in any way upon successful completion of SetupSndHeader. The SetupSndHeader function simply fills the relocatable block specified by this parameter with the header information needed for a format 1 'snd ' resource, including the sound resource header, the list of sound commands, and a sampled sound header. It is your application's responsibility to append the desired sampled-sound data.
numChannels
The number of channels for the sound; one channel is equivalent to monaural sound and two channels are equivalent to stereo sound.
sampleRate
The rate at which the sound was recorded. The sample rate is declared as a Fixed data type. In order to accommodate sample rates greater than 32 kHz, the most significant bit is not treated as a sign bit; instead, that bit is interpreted as having the value 32,768.
sampleSize
The sample size for the original sound (that is, bits per sample).
compressionType
The compression type for the sound ('NONE', 'MAC3', 'MAC6', or other third-party types).
baseFrequency
The base frequency for the sound, expressed as a MIDI note value.
numBytes
The number of bytes of audio data that are to be stored in the handle. (This value is not necessarily the same as the number of samples in the sound.)
headerLen
On exit, the size (in bytes) of the 'snd ' resource header that is created. In no case will this length exceed 100 bytes. This field allows you to put the audio data right after the header in the relocatable block specified by the sndHandle parameter. The value returned depends on the type of sound header created.
DESCRIPTION
The SetupSndHeader function creates a format 1 'snd ' resource for a sampled sound. The resource contains a sound resource header that links the sound to the sampled synthesizer, a single sound command (a bufferCmd command to play the accompanying data), and a sampled sound header. You can use SetupSndHeader to construct a sampled sound header that can be passed to the Sound Manager's SndPlay function or stored as an 'snd ' resource. After calling the SetupSndHeader function, your application should place the sampled-sound data directly after the sampled sound header so that, in essence, the sampled sound header's final field contains the sound data.

The sampled sound is in one of three formats depending on several of the parameters passed. Table 3-1 shows how SetupSndHeader determines what kind of sound header to create.

The sampled sound header format used by SetupSndHeader
compressionTypenumChannelssampleSizeSampled sound header format
'NONE'18SoundHeader
'NONE'116ExtSoundHeader
'NONE'2anyExtSoundHeader
not 'NONE'anyanyCmpSoundHeader

A good way to use this function is to create a handle in which you want to store a sampled sound, then call SetupSndHeader with the numBytes parameter set to 0 to see how much room the header for that sound will occupy and hence where to append the audio data. Then record the data into the handle and call SetupSndHeader again with numBytes set to the correct amount of sound data recorded. The handle filled out in this way can be passed to SndPlay to play the sound.

SPECIAL CONSIDERATIONS
You cannot call the SetupSndHeader function at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION
The trap macro and routine selector for the SetupSndHeader function are
Trap macroSelector
_SoundDispatch$0D480014

RESULT CODES
noErr0No error
siInvalidCompression-223Invalid compression type
SEE ALSO
For an example that uses the SetupSndHeader function to set up a sound header before recording, see Listing 3-1 on page 3-7.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
2 JUL 1996