Notes on status of CoreAudio Implementation of PortAudioDocument Last Updated December 9, 2005There are currently two implementations of PortAudio for Mac Core Audio.The original is in pa_mac_core_old.c, and the newer, default implementationis in pa_mac_core.c.Only pa_mac_core.c is currently developed and supported as it uses apple'scurrent core audio technology. To select use the old implementation, replacepa_mac_core.c with pa_mac_core_old.c (eg. "cp pa_mac_core_auhal.cpa_mac_core.c"), then run configure and make as usual.-------------------------------------------Notes on Newer/Default AUHAL implementation:by Bjorn RocheLast Updated December 9, 2005Principle of Operation:This implementation uses AUHAL for audio I/O. To some extent, it alsooperates at the "HAL" Layer, though this behavior can be limited byplatform specific flags (see pa_mac_core.h for details). The defaultsettings should be reasonable: they don't change the SR of the device anddon't cause interruptions if other devices are using the device.Major Software Elements Used: Apple's HAL AUs provide output SRconversion transparently, however, only on output, so thisimplementation uses AudioConverters to convert the sample rate on input.A PortAudio ring buffer is used to buffer input when sample rateconversion is required or when separate audio units are used for duplexIO. Finally, a PortAudio buffer processor is used to convert formats andprovide additional buffers if needed. Internally, interleaved floatingpoint data streams are used exclusively - the audio unit converts fromthe audio hardware's native format to interleaved float PCM andPortAudio's Buffer processor is used for conversion to user formats.Simplex Input: Simplex input uses a single callback. If sample rateconversion is required, a ring buffer and AudioConverter are used aswell.Simplex output: Simplex output uses a single callback. No ring buffer oraudio converter is used because AUHAL does its own output SR conversion.Duplex, one device (no SR conversion): When one device is used, a singlecallback is used. This achieves very low latency.Duplex, separate devices or SR conversion: When SR conversion isrequired, data must be buffered before it is converted and data is notalways available at the same times on input and output, so SR conversionrequires the same treatment as separate devices. The input callbackreads data and puts it in the ring buffer. The output callback reads thedata off the ring buffer, into an audio converter and finally to thebuffer processor.Platform Specific Options:By using the flags in pa_mac_core.h, the user may specify several options.For example, the user can specify the sample-rate conversion quality, andthe extent to which PA will attempt to "play nice" and to what extent itwill interrupt other apps to improve performance. For example, if 44100 Hzsample rate is requested but the device is set at 48000 Hz, PA can eitherchange the device for optimal playback ("Pro" mode), which may interruptother programs playing back audio, or simple use a sample-rate coversion,which allows for friendlier sharing of the device ("Play Nice" mode).Additionally, the user may define a "channel mapping" by callingpaSetupMacCoreChannelMap() on their stream info structure before openingthe stream with it. See below for creating a channel map.Known issues:- Latency: Latency settings are ignored in most cases. Exceptions are whendoing I/O between different devices and as a hint for selecting a realtivelylow or relatively high latency in conjunction withpaHostFramesPerBufferUnspecified. Latency settings are always automaticallybound to "safe" values, however, so setting extreme values here should not bean issue.- Buffer Size: paHostFramesPerBufferUnspecified and specific host buffer sizesare supported. paHostFramesPerBufferUnspecified works best in "pro" mode,where the buffer size and sample rate of the audio device is most likelyto match the expected values.- Timing info. It reports on stream time, but I'm probably doing somethingwrong since patest_sine_time often reports negative latency numbers. Also,there are currently issues with some devices whehn plugging/unpluggingdevices.- xrun detection: The only xrun detection performed is when readingand writing the ring buffer. There is probably more that can be done.- abort/stop issues: stopping a stream is always a complete operation,but latency should be low enough to make the lack of a separate abortunnecessary. Apple clarifies its AudioOutputUnitStop() call here:http://lists.apple.com/archives/coreaudio-api/2005/Dec/msg00055.html- blocking interface: should work fine.- multichannel: It has been tested successfully on multichannel hardwarefrom MOTU: traveler and 896HD. Also Presonus firepod and others. It isbelieved to work with all Core Audio devices, including virtual devicessuch as soundflower.- sample rate conversion quality: By default, SR conversion is the maximumavailable. This can be tweaked using flags pa_mac_core.h. Note that the AUrender quyality property is used to set the sample rate conversion qualityas "documented" here:http://lists.apple.com/archives/coreaudio-api/2004/Jan/msg00141.html- x86/Universal Binary: to build a universal binary, be sure to usethe darwin makefile and not the usual configure && make combo.Creating a channel map:How to create the map array -  Text taken From AUHAL.rtfd :[3] Channel MapsClients can tell the AUHAL units which channels of the device they are interested in.  For example, the client may be processing stereo data, but outputting to a six-channel device.  This is done by using the kAudioOutputUnitProperty_ChannelMap property.  To use this property:For Output:Create an array of SInt32 that is the size of the number of channels of the device (Get the Format of the AUHAL's output Element == 0)Initialize each of the array's values to -1 (-1 indicates that that channel is NOT to be presented in the conversion.)Next, for each channel of your app's output, set:channelMapArray[deviceOutputChannel] = desiredAppOutputChannel.For example: we have a 6 channel output device and our application has a stereo source it wants to provide to the device.  Suppose we want that stereo source to go to the 3rd and 4th channels of the device. The channel map would look like this: { -1, -1, 0, 1, -1, -1 }Where the formats are:Input Element == 0: 2 channels (- client format - settable)Output Element == 0: 6 channels (- device format - NOT settable)So channel 2 (zero-based) of the device will take the first channel of output and channel 3 will take the second channel of output. (This translates to the 3rd and 4th plugs of the 6 output plugs of the device of course!)For Input:Create an array of SInt32 that is the size of the number of channels of the format you require for input.  Get (or Set in this case as needed) the AUHAL's output Element == 1.Next, for each channel of input you require, set:channelMapArray[desiredAppInputChannel] = deviceOutputChannel;For example: we have a 6 channel input device from which we wish to receive stereo input from the 3rd and 4th channels. The channel map looks like this: { 2, 3 }Where the formats are:Input Element == 0: 2 channels (- device format - NOT settable)Output Element == 0: 6 channels (- client format - settable)----------------------------------------Notes on Original implementation:by Phil Burk and Darren GibbsLast updated March 20, 2002WHAT WORKSOutput with very low latency, <10 msec.Half duplex input or output.Full duplex on the same CoreAudio device.The paFLoat32, paInt16, paInt8, paUInt8 sample formats.Pa_GetCPULoad()Pa_StreamTime()KNOWN BUGS OR LIMITATIONSWe do not yet support simultaneous input and output on different devices. Note that some CoreAudio devices like the Roland UH30 look like one device but are actually two different CoreAudio devices. The Built-In audio is typically one CoreAudio device.Mono doesn't work.DEVICE MAPPINGCoreAudio devices can support both input and output. But the sample rates supported may be different. So we have map one or two PortAudio device to each CoreAudio device depending on whether it supports input, output or both.When we query devices, we first get a list of CoreAudio devices. Then we scan the list and add a PortAudio device for each CoreAudio device that supports input. Then we make a scan for output devices.