Inside Macintosh: Sound /: Chapter 5 - Sound Components

Legacy Document

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.

Summary of Sound Components

This section provides a C summary for the constants, data types, and routines you can use to write a sound component. There are currently no Pascal interfaces available for writing sound components.

C Summary

Constants

/*component types*/
#define kSoundComponentType      'sift'   /*utility component*/
#define kMixerType               'mixr'   /*mixer component*/
#define kSoundHardwareType       'sdev'   /*sound output device component*/
#define kSoundCompressor         'scom'   /*compression component*/
#define kSoundDecompressor       'sdec'   /*decompression component*/
#define kNoSoundComponentType    '****'   /*no type*/

/*subtypes for kSoundComponentType component type*/
#define kRate8SubType            'ratb'   /*8-bit rate converter*/
#define kRate16SubType           'ratw'   /*16-bit rate converter*/
#define kConverterSubType        'conv'   /*sample format converter*/
#define kSndSourceSubType        'sour'   /*generic source component*/

/*subtypes for kMixerType component type*/
#define kMixer8SubType           'mixb'   /*8-bit mixer*/
#define kMixer16SubType          'mixw'   /*16-bit mixer*/

/*subtypes for kSoundHardwareType component type*/
#define kClassicSubType          'clas'   /*Classic hardware*/
#define kASCSubType              'asc '   /*ASC device*/
#define kDSPSubType              'dsp '   /*DSP device*/

/*subtypes for kSoundCompressor and kSoundDecompressor component types*/
#define kMace3SubType            'MAC3'   /*MACE 3:1*/
#define kMace6SubType            'MAC6 '  /*MACE 6:1*/
#define kCDXA4SubType            'CDX4'   /*CD/XA 4:1*/
#define kCDXA2SubType            'CDX2'   /*CD/XA 2:1*/
#define kSoundComponentCodeType  'sift'   /*sound component code type*/

/*first selector that can be delegated up the chain*/
#define kDelegatedSoundComponentSelectors       0x0100

/*Component Manager selectors for routines*/
enum {
   /*the following calls cannot be delegated*/
   kSoundComponentInitOutputDeviceSelect     = 1,
   kSoundComponentSetSourceSelect,
   kSoundComponentGetSourceSelect,
   kSoundComponentGetSourceDataSelect,
   kSoundComponentSetOutputSelect,
   /*the following calls can be delegated*/
   kSoundComponentAddSourceSelect = kDelegatedSoundComponentSelectors + 1,
   kSoundComponentRemoveSourceSelect,
   kSoundComponentGetInfoSelect,
   kSoundComponentSetInfoSelect,
   kSoundComponentStartSourceSelect,
   kSoundComponentStopSourceSelect,
   kSoundComponentPauseSourceSelect,
   kSoundComponentPlaySourceBufferSelect
};

/*sound component information selectors*/
#define siChannelAvailable       'chav'   /*number of channels available*/
#define siCompressionAvailable   'cmav'   /*compression types available*/
#define siCompressionFactor      'cmfa'   /*current compression factor*/
#define siCompressionType        'comp'   /*current compression type*/
#define siHardwareMute           'hmut'   /*current hardware mute state*/
#define siHardwareVolume         'hvol'   /*current hardware volume*/
#define siHardwareVolumeSteps    'hstp'   /*number of hardware volume steps*/
#define siHeadphoneMute          'pmut'   /*current headphone mute state*/
#define siHeadphoneVolume        'pvol'   /*current headphone volume*/
#define siHeadphoneVolumeSteps   'hdst'   /*num. of headphone volume steps*/
#define siNumberChannels         'chan'   /*current number of channels*/
#define siQuality                'qual'   /*current quality*/
#define siRateMultiplier         'rmul'   /*current rate multiplier*/
#define siSampleRate             'srat'   /*current sample rate*/
#define siSampleRateAvailable    'srav'   /*sample rates available*/
#define siSampleSize             'ssiz'   /*current sample size*/
#define siSampleSizeAvailable    'ssav'   /*sample sizes available*/
#define siSpeakerMute            'smut'   /*current speaker mute*/
#define siSpeakerVolume          'svol'   /*current speaker volume*/
#define siVolume                 'volu'   /*current volume setting*/

/*audio data format types*/
#define kOffsetBinary            'raw '
#define kTwosComplement          'twos'
#define kMACE3Compression        'MAC3'
#define kMACE6Compression        'MAC6'

/*sound component features flags*/
#define k8BitRawIn               (1 << 0)    /*data flags*/
#define k8BitTwosIn              (1 << 1)
#define k16BitIn                 (1 << 2)
#define kStereoIn                (1 << 3)
#define k8BitRawOut              (1 << 8)
#define k8BitTwosOut             (1 << 9)
#define k16BitOut                (1 << 10)
#define kStereoOut               (1 << 11)

#define kReverse                 (1 << 16)   /*action flags*/
#define kRateConvert             (1 << 17)
#define kCreateSoundSource       (1 << 18)

#define kHighQuality             (1 << 22)   /*performance flags*/
#define kRealTime                (1 << 23)

/*action flags for SoundComponentPlaySourceBuffer*/
#define kSourcePaused            (1 << 0)
#define kPassThrough             (1 << 16)
#define kNoSoundComponentChain   (1 << 17)

/*flags for OpenMixerSoundComponent*/
#define kNoMixing                (1 << 0)    /*don't mix sources*/
#define kNoSampleRateConversion  (1 << 1)    /*don't convert sample rate*/
#define kNoSampleSizeConversion  (1 << 2)    /*don't convert sample size*/
#define kNoSampleFormatConversion            \
                                 (1 << 3)    /*don't convert sample format*/
#define kNoChannelConversion     (1 << 4)    /*don't convert stereo/mono*/
#define kNoDecompression         (1 << 5)    /*don't decompress*/
#define kNoVolumeConversion      (1 << 6)    /*don't apply volume*/
#define kNoRealtimeProcessing    (1 << 7)    /*don't run at interrupt time*/

/*quality flags*/
#define kBestQuality             (1 << 0)    /*use interp. in rate conv.*/

/*volume specifications*/
#define kSilenceByte             0x80
#define kSilenceLong             0x80808080
#define kFullVolume              0x0100

Data Types

Unsigned Fixed-Point Numbers

typedef unsigned long UnsignedFixed;   /*unsigned fixed-point number*/

Sound Component Data Record

typedef struct {
   long           flags;               /*sound component flags*/
   OSType         format;              /*data format*/
   short          numChannels;         /*number of channels in data*/
   short          sampleSize;          /*size of a sample*/
   UnsignedFixed  sampleRate;          /*sample rate*/
   long           sampleCount;         /*number of samples in buffer*/
   Byte           *buffer;             /*location of data*/
   long           reserved;            /*reserved*/
} SoundComponentData, *SoundComponentDataPtr;

Sound Parameter Block

typedef pascal Boolean (*SoundParamProcPtr)(SoundParamBlockPtr *pb);
struct SoundParamBlock {
   long                 recordSize;    /*size of this record in bytes*/
   SoundComponentData   desc;          /*description of sound buffer*/
   Fixed                rateMultiplier;/*rate multiplier*/
   short                leftVolume;    /*volume on left channel*/
   short                rightVolume;   /*volume on right channel*/
   long                 quality;       /*quality*/
   ComponentInstance    filter;        /*filter*/
   SoundParamProcPtr    moreRtn;       /*routine to call to get more data*/
   SoundParamProcPtr    completionRtn; /*buffer complete routine*/
   long                 refCon;        /*user refcon*/
   short                result;        /*result*/
};
typedef struct SoundParamBlock SoundParamBlock;
typedef SoundParamBlock *SoundParamBlockPtr;

Sound Source

typedef struct privateSoundSource *SoundSource;

Sound Information List

typedef struct {
   short          count;
   Handle         handle;
} SoundInfoList, *SoundInfoListPtr;

Compression Information Record

typedef struct {
   long           recordSize;
   OSType         format;
   short          compressionID;
   short          samplesPerPacket;
   short          bytesPerPacket;
   short          bytesPerFrame;
   short          bytesPerSample;
   short          futureUse1;
} CompressionInfo, *CompressionInfoPtr, **CompressionInfoHandle;

Sound Manager Utilities

Opening and Closing the Apple Mixer Component

pascal OSErr OpenMixerSoundComponent
		(SoundComponentDataPtr outputDescription, 
		long outputFlags, 
		ComponentInstance *mixerComponent);
pascal OSErr CloseMixerSoundComponent
		(ComponentInstance ci);

Saving and Restoring Sound Component Preferences

pascal OSErr SetSoundPreference
		(OSType type, Str255 name, Handle settings);
pascal OSErr GetSoundPreference
		(OSType type, Str255 name, Handle settings);

Sound Component-Defined Routines

Managing Sound Components

pascal ComponentResult SoundComponentInitOutputDevice
		(ComponentInstance ti, long actions);
pascal ComponentResult SoundComponentSetSource
		(ComponentInstance ti, SoundSource sourceID,
		ComponentInstance source);
pascal ComponentResult SoundComponentGetSource
		(ComponentInstance ti, SoundSource sourceID,
		ComponentInstance *source);
pascal ComponentResult SoundComponentGetSourceData
		(ComponentInstance ti, 
		SoundComponentDataPtr *sourceData);
pascal ComponentResult SoundComponentSetOutput
		(ComponentInstance ti, 
		SoundComponentDataPtr requested, SoundComponentDataPtr *actual);

Creating and Removing Audio Sources

pascal ComponentResult SoundComponentAddSource
		(ComponentInstance ti, SoundSource *sourceID);
pascal ComponentResult SoundComponentRemoveSource
		(ComponentInstance ti, SoundSource sourceID);

Getting and Setting Sound Component Information

pascal ComponentResult SoundComponentGetInfo
		(ComponentInstance ti, SoundSource sourceID,
		OSType selector, void *infoPtr);
pascal ComponentResult SoundComponentSetInfo
		(ComponentInstance ti, SoundSource sourceID,
		OSType selector, void *infoPtr);

Managing Source Data

pascal ComponentResult SoundComponentStartSource
		(ComponentInstance ti, short count, 
		SoundSource *sources);
pascal ComponentResult SoundComponentStopSource
		(ComponentInstance ti, short count, 
		SoundSource *sources);
pascal ComponentResult SoundComponentPauseSource
		(ComponentInstance ti, short count, 
		SoundSource *sources);
pascal ComponentResult SoundComponentPlaySourceBuffer
		(ComponentInstance ti, SoundSource sourceID, SoundParamBlockPtr pb, long actions);

Assembly-Language Summary

Data Structures

Sound Component Data Record
0 flags long sound component flags
4 format long data format
8 numChannels word number of channels in data
10 sampleSize word size of a sample
12 sampleRate long sample rate (Fixed)
16 sampleCount long number of samples in buffer
20 buffer long location of data
24 reserved long reserved

Sound Parameter Block
0 recordSize long size of this record in bytes
4 desc 28 bytes description of sound buffer
32 rateMultiplier long rate multiplier (Fixed)
36 leftVolume word volume on left channel
38 rightVolume word volume on right channel
40 quality long quality
44 filter long filter
48 moreRtn long routine to call to get more data
52 completionRtn long buffer complete routine
56 refCon long user refcon
60 result word result

Sound Information List
0 count word number of data items in the handle
2 handle long handle to list of data items

Compression Information Record
0 recordSize long the size of this record
4 format 4 bytes compression format
8 compressionID word compression ID
10 samplesPerPacket word the number of samples per packet
12 bytesPerPacket word the number of bytes per packet
14 bytesPerFrame word the number of bytes per frame
16 bytesPerSample word the number of bytes per sample
18 futureUse1 word reserved

0	flags	long	sound component flags
4	format	long	data format
8	numChannels	word	number of channels in data
10	sampleSize	word	size of a sample
12	sampleRate	long	sample rate (Fixed)
16	sampleCount	long	number of samples in buffer
20	buffer	long	location of data
24	reserved	long	reserved

0	recordSize	long	size of this record in bytes
4	desc	28 bytes	description of sound buffer
32	rateMultiplier	long	rate multiplier (Fixed)
36	leftVolume	word	volume on left channel
38	rightVolume	word	volume on right channel
40	quality	long	quality
44	filter	long	filter
48	moreRtn	long	routine to call to get more data
52	completionRtn	long	buffer complete routine
56	refCon	long	user refcon
60	result	word	result

0	count	word	number of data items in the handle
2	handle	long	handle to list of data items

0	recordSize	long	the size of this record
4	format	4 bytes	compression format
8	compressionID	word	compression ID
10	samplesPerPacket	word	the number of samples per packet
12	bytesPerPacket	word	the number of bytes per packet
14	bytesPerFrame	word	the number of bytes per frame
16	bytesPerSample	word	the number of bytes per sample
18	futureUse1	word	reserved