Inside Macintosh: Sound /

Chapter 2 - Sound Manager / Sound Manager Reference

Data Structures

Compressed Sound Header Records

To describe compressed sampled-sound data, the Sound Manager uses a compressed sound header record. Compressed sound headers include all of the essential fields of extended sound headers in addition to several fields that pertain to compression. The CmpSoundHeader data type defines the compressed sound header record.

TYPE CmpSoundHeader =
PACKED RECORD
   samplePtr:        Ptr;           {if NIL, samples in sampleArea}
   numChannels:      LongInt;       {number of channels in sample}
   sampleRate:       Fixed;         {rate of original sample}
   loopStart:        LongInt;       {loop point beginning}
   loopEnd:          LongInt;       {loop point ending}
   encode:           Byte;          {sample's encoding option}
   baseFrequency:    Byte;          {base freq. of original sample}
   numFrames:        LongInt;       {length of sample in frames}
   AIFFSampleRate:   Extended80;    {rate of original sample}
   markerChunk:      Ptr;           {reserved}
   format:           OSType;        {data format type}
   futureUse2:       LongInt;       {reserved}
   stateVars:        StateBlockPtr; {pointer to StateBlock}
   leftOverSamples:  LeftOverBlockPtr;
                                    {pointer to LeftOverBlock}
   compressionID:    Integer;       {ID of compression algorithm}
   packetSize:       Integer;       {number of bits per packet}
   snthID:           Integer;       {unused}
   sampleSize:       Integer;       {bits in each sample point}
   sampleArea:       PACKED ARRAY[0..0] OF Byte;
END;

Field Description

samplePtr

The location of the compressed sound frames. If samplePtr is NIL, then the frames are located in the sampleArea field of the compressed sound header. Otherwise, samplePtr points to a buffer that contains the frames.

numChannels

The number of channels in the sample.

sampleRate

The sample rate at which the frames were sampled before compression. The approximate sample rates are shown in Table 2-1 on page 2-16. Note that the sample rate is declared as a Fixed data type, but the most significant bit is not treated as a sign bit; instead, that bit is interpreted as having the value 32,768.

loopStart

The beginning of the loop points of the sound before compression. The loop starting and ending points are 0-based.

loopEnd

The end of the loop points of the sound before compression.

encode

The method of encoding (if any) used to generate the sampled-sound data. For a compressed sound header, you should specify the constant cmpSH. Encode option values in the ranges 0 through 63 and 128 to 255 are reserved for use by Apple. You are free to use numbers in the range 64 through 127 for your own encode options.

baseFrequency

The pitch of the original sampled sound. It is not used by bufferCmd. If you wish to make use of baseFrequency with a compressed sound, you must first expand it and then play it with soundCmd and freqDurationCmd.

numFrames

The number of frames contained in the compressed sound header. When you store multiple channels of noncompressed sound, store them as interleaved sample frames (as in AIFF). When you store multiple channels of compressed sounds, store them as interleaved packet frames.

AIFFSampleRate

The sample rate at which the frames were sampled before compression, as expressed in the 80-bit extended data type representation.

markerChunk

Synchronization information. The markerChunk field is not presently used and should be set to NIL.

format

The data format type. This field contains a value of type OSType that defines the compression algorithm, if any, used to generate the audio data. For example, for data generated using MACE 3:1 compression, this field should contain the value 'MAC3'. See page 2-86 for a list of the format types defined by Apple. This field is used only if the compressionID field contains the value fixedCompression.

futureUse2

This field is reserved for use by Apple. To maintain compatibility with future releases of system software, you should always set this field to 0.

stateVars

A pointer to a state block. This field is used to store the state variables for a given algorithm across consecutive calls. See "State Blocks" on page 2-119 for a description of the state block.

leftOverSamples

A pointer to a leftover block. You can use this block to store samples that will be truncated across algorithm invocations. See "Leftover Blocks" on page 2-119 for a description of the leftover block.

compressionID

The compression algorithm used on the samples in the compressed sound header. You can use a constant to define the compression algorithm.

               CONST
                  variableCompression  
                                    = -2; {variable-ratio compr.}
                  fixedCompression  = -1; {fixed-ratio compr.}
                  notCompressed     = 0;  {noncompressed samples}
                  threeToOne        = 3;  {3:1 compressed samples}
                  sixToOne          = 4;  {6:1 compressed samples}

The constant fixedCompression is available only with Sound Manager versions 3.0 and later. If the compressionID field contains the value fixedCompression, the Sound Manager reads the format field to determine the compression algorithm used to generate the compressed data. Otherwise, the Sound Manager reads the compressionID field. Apple reserves the right to use compression IDs in the range 0 through 511. Currently the constant variableCompression is not used by the Sound Manager.

packetSize

The size, in bits, of the smallest element that a given expansion algorithm can work with. You can use a constant to define the packet size.

               CONST
                  sixToOnePacketSize   = 8;  {size for 6:1}
                  threeToOnePacketSize = 16; {size for 3:1}

Beginning with Sound Manager version 3.0, you can specify the value 0 in this field to instruct the Sound Manager to determine the packet size itself.

snthID

This field is unused. You should set it to 0.

sampleSize

The size of the sample before it was compressed. The samples passed in the compressed sound header should always be byte-aligned, and any padding done to achieve byte alignment should be done from the left with zeros.

sampleArea

The sample frames, but only when the samplePtr field is NIL. Otherwise, the sample frames are in the location indicated by samplePtr.