3rdparty/iaxclient/lib/portaudio/src/hostapi/coreaudio/notes.txt

   1 Notes on status of CoreAudio Implementation of PortAudio
   2
   3 Document Last Updated December 9, 2005
   4
   5 There are currently two implementations of PortAudio for Mac Core Audio.
   6
   7 The original is in pa_mac_core_old.c, and the newer, default implementation
   8 is in pa_mac_core.c.
   9 Only pa_mac_core.c is currently developed and supported as it uses apple's
  10 current core audio technology. To select use the old implementation, replace
  11 pa_mac_core.c with pa_mac_core_old.c (eg. "cp pa_mac_core_auhal.c
  12 pa_mac_core.c"), then run configure and make as usual.
  13
  14 ----------------------------------------
  15
  16 Notes on Original implementation:
  17
  18 by Phil Burk and Darren Gibbs
  19
  20 Last updated March 20, 2002
  21
  22 WHAT WORKS
  23
  24 Output with very low latency, <10 msec.
  25 Half duplex input or output.
  26 Full duplex on the same CoreAudio device.
  27 The paFLoat32, paInt16, paInt8, paUInt8 sample formats.
  28 Pa_GetCPULoad()
  29 Pa_StreamTime()
  30
  31 KNOWN BUGS OR LIMITATIONS
  32
  33 We do not yet support simultaneous input and output on different
  34 devices. Note that some CoreAudio devices like the Roland UH30 look
  35 like one device but are actually two different CoreAudio devices. The
  36 Built-In audio is typically one CoreAudio device.
  37
  38 Mono doesn't work.
  39
  40 DEVICE MAPPING
  41
  42 CoreAudio devices can support both input and output. But the sample
  43 rates supported may be different. So we have map one or two PortAudio
  44 device to each CoreAudio device depending on whether it supports
  45 input, output or both.
  46
  47 When we query devices, we first get a list of CoreAudio devices. Then
  48 we scan the list and add a PortAudio device for each CoreAudio device
  49 that supports input. Then we make a scan for output devices.
  50
  51 -------------------------------------------
  52
  53 Notes on Newer/Default AUHAL implementation:
  54
  55 by Bjorn Roche
  56
  57 Last Updated December 9, 2005
  58
  59 Principle of Operation:
  60
  61 This implementation uses AUHAL for audio I/O. To some extent, it also
  62 operates at the "HAL" Layer, though this behavior can be limited by
  63 platform specific flags (see pa_mac_core.h for details). The default
  64 settings should be reasonable: they don't change the SR of the device and
  65 don't cause interruptions if other devices are using the device.
  66
  67 Major Software Elements Used: Apple's HAL AUs provide output SR
  68 conversion transparently, however, only on output, so this
  69 implementation uses AudioConverters to convert the sample rate on input.
  70 A PortAudio ring buffer is used to buffer input when sample rate
  71 conversion is required or when separate audio units are used for duplex
  72 IO. Finally, a PortAudio buffer processor is used to convert formats and
  73 provide additional buffers if needed. Internally, interleaved floating
  74 point data streams are used exclusively - the audio unit converts from
  75 the audio hardware's native format to interleaved float PCM and
  76 PortAudio's Buffer processor is used for conversion to user formats.
  77
  78 Simplex Input: Simplex input uses a single callback. If sample rate
  79 conversion is required, a ring buffer and AudioConverter are used as
  80 well.
  81
  82 Simplex output: Simplex output uses a single callback. No ring buffer or
  83 audio converter is used because AUHAL does its own output SR conversion.
  84
  85 Duplex, one device (no SR conversion): When one device is used, a single
  86 callback is used. This achieves very low latency.
  87
  88 Duplex, separate devices or SR conversion: When SR conversion is
  89 required, data must be buffered before it is converted and data is not
  90 always available at the same times on input and output, so SR conversion
  91 requires the same treatment as separate devices. The input callback
  92 reads data and puts it in the ring buffer. The output callback reads the
  93 data off the ring buffer, into an audio converter and finally to the
  94 buffer processor.
  95
  96 Platform Specific Options:
  97
  98 By using the flags in pa_mac_core.h, the user may specify several options.
  99 For example, the user can specify the sample-rate conversion quality, and
 100 the extent to which PA will attempt to "play nice" and to what extent it
 101 will interrupt other apps to improve performance. For example, if 44100 Hz
 102 sample rate is requested but the device is set at 48000 Hz, PA can either
 103 change the device for optimal playback ("Pro" mode), which may interrupt
 104 other programs playing back audio, or simple use a sample-rate coversion,
 105 which allows for friendlier sharing of the device ("Play Nice" mode).
 106
 107
 108 Known issues:
 109
 110 - Latency: Latency settings are ignored in most cases. Exceptions are when
 111 doing I/O between different devices and as a hint for selecting a realtively
 112 low or relatively high latency in conjunction with
 113 paHostFramesPerBufferUnspecified. Latency settings are always automatically
 114 bound to "safe" values, however, so setting extreme values here should not be
 115 an issue.
 116
 117 - Buffer Size: paHostFramesPerBufferUnspecified and specific host buffer sizes
 118 are supported. paHostFramesPerBufferUnspecified works best in "pro" mode,
 119 where the buffer size and sample rate of the audio device is most likely
 120 to match the expected values.
 121
 122 - Timing info. It reports on stream time, but I'm probably doing something
 123 wrong since patest_sine_time often reports negative latency numbers.
 124
 125 - xrun detection: The only xrun detection performed is when reading
 126 and writing the ring buffer. There is probably more that can be done.
 127
 128 - abort/stop issues: stopping a stream is always a complete operation,
 129 but latency should be low enough to make the lack of a separate abort
 130 unnecessary. Apple clarifies its AudioOutputUnitStop() call here:
 131 http://lists.apple.com/archives/coreaudio-api/2005/Dec/msg00055.html
 132
 133 - blocking interface: Not implemented.
 134
 135 - multichannel: It has been tested successfully on multichannel hardware
 136 from MOTU: traveler and 896HD.
 137
 138 - sample rate conversion quality: By default, SR conversion is the maximum
 139 available. This can be tweaked using flags pa_mac_core.h. Note that the AU
 140 render quyality property is used to set the sample rat conversion quality
 141 as "documented" here:
 142 http://lists.apple.com/archives/coreaudio-api/2004/Jan/msg00141.html
 143
 144 - x86: I haven't tested it on an x86 Mac myself, but users have reported
 145 being able to comiple and run it.