← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/third_party/portaudio/src/hostapi/coreaudio/notes.txt

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/third_party/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 Newer/Default AUHAL implementation:
 
17
 
 
18
by Bjorn Roche
 
19
 
 
20
Last Updated December 9, 2005
 
21
 
 
22
Principle of Operation:
 
23
 
 
24
This implementation uses AUHAL for audio I/O. To some extent, it also
 
25
operates at the "HAL" Layer, though this behavior can be limited by
 
26
platform specific flags (see pa_mac_core.h for details). The default
 
27
settings should be reasonable: they don't change the SR of the device and
 
28
don't cause interruptions if other devices are using the device.
 
29
 
 
30
Major Software Elements Used: Apple's HAL AUs provide output SR
 
31
conversion transparently, however, only on output, so this
 
32
implementation uses AudioConverters to convert the sample rate on input.
 
33
A PortAudio ring buffer is used to buffer input when sample rate
 
34
conversion is required or when separate audio units are used for duplex
 
35
IO. Finally, a PortAudio buffer processor is used to convert formats and
 
36
provide additional buffers if needed. Internally, interleaved floating
 
37
point data streams are used exclusively - the audio unit converts from
 
38
the audio hardware's native format to interleaved float PCM and
 
39
PortAudio's Buffer processor is used for conversion to user formats.
 
40
 
 
41
Simplex Input: Simplex input uses a single callback. If sample rate
 
42
conversion is required, a ring buffer and AudioConverter are used as
 
43
well.
 
44
 
 
45
Simplex output: Simplex output uses a single callback. No ring buffer or
 
46
audio converter is used because AUHAL does its own output SR conversion.
 
47
 
 
48
Duplex, one device (no SR conversion): When one device is used, a single
 
49
callback is used. This achieves very low latency.
 
50
 
 
51
Duplex, separate devices or SR conversion: When SR conversion is
 
52
required, data must be buffered before it is converted and data is not
 
53
always available at the same times on input and output, so SR conversion
 
54
requires the same treatment as separate devices. The input callback
 
55
reads data and puts it in the ring buffer. The output callback reads the
 
56
data off the ring buffer, into an audio converter and finally to the
 
57
buffer processor.
 
58
 
 
59
Platform Specific Options:
 
60
 
 
61
By using the flags in pa_mac_core.h, the user may specify several options.
 
62
For example, the user can specify the sample-rate conversion quality, and
 
63
the extent to which PA will attempt to "play nice" and to what extent it
 
64
will interrupt other apps to improve performance. For example, if 44100 Hz
 
65
sample rate is requested but the device is set at 48000 Hz, PA can either
 
66
change the device for optimal playback ("Pro" mode), which may interrupt
 
67
other programs playing back audio, or simple use a sample-rate coversion,
 
68
which allows for friendlier sharing of the device ("Play Nice" mode).
 
69
 
 
70
Additionally, the user may define a "channel mapping" by calling
 
71
paSetupMacCoreChannelMap() on their stream info structure before opening
 
72
the stream with it. See below for creating a channel map.
 
73
 
 
74
Known issues:
 
75
 
 
76
- Buffering: No buffering beyond that provided by core audio is provided
 
77
except where absolutely needed for the implementation to work. This may cause
 
78
issues with large framesPerBuffer settings and it also means that no additional
 
79
latency will be provided even if a large latency setting is selected.
 
80
 
 
81
- Latency: Latency settings are generally ignored. They may be used as a
 
82
hint for buffer size in paHostFramesPerBufferUnspecified, or the value may
 
83
be used in cases where additional buffering is needed, such as doing input and
 
84
output on seperate devices. Latency settings are always automatically bound
 
85
to "safe" values, however, so setting extreme values here should not be
 
86
an issue.
 
87
 
 
88
- Buffer Size: paHostFramesPerBufferUnspecified and specific host buffer sizes
 
89
are supported. paHostFramesPerBufferUnspecified works best in "pro" mode,
 
90
where the buffer size and sample rate of the audio device is most likely
 
91
to match the expected values. In the case of paHostFramesPerBuffer, an
 
92
appropriate framesPerBuffer value will be used that guarantees minimum
 
93
requested latency if that's possible.
 
94
 
 
95
- Timing info. It reports on stream time, but I'm probably doing something
 
96
wrong since patest_sine_time often reports negative latency numbers. Also,
 
97
there are currently issues with some devices whehn plugging/unplugging
 
98
devices.
 
99
 
 
100
- xrun detection: The only xrun detection performed is when reading
 
101
and writing the ring buffer. There is probably more that can be done.
 
102
 
 
103
- abort/stop issues: stopping a stream is always a complete operation,
 
104
but latency should be low enough to make the lack of a separate abort
 
105
unnecessary. Apple clarifies its AudioOutputUnitStop() call here:
 
106
http://lists.apple.com/archives/coreaudio-api/2005/Dec/msg00055.html
 
107
 
 
108
- blocking interface: should work fine.
 
109
 
 
110
- multichannel: It has been tested successfully on multichannel hardware
 
111
from MOTU: traveler and 896HD. Also Presonus firepod and others. It is
 
112
believed to work with all Core Audio devices, including virtual devices
 
113
such as soundflower.
 
114
 
 
115
- sample rate conversion quality: By default, SR conversion is the maximum
 
116
available. This can be tweaked using flags pa_mac_core.h. Note that the AU
 
117
render quyality property is used to set the sample rate conversion quality
 
118
as "documented" here:
 
119
http://lists.apple.com/archives/coreaudio-api/2004/Jan/msg00141.html
 
120
 
 
121
- x86/Universal Binary: Universal binaries can be build.
 
122
 
 
123
 
 
124
 
 
125
Creating a channel map:
 
126
 
 
127
How to create the map array -  Text taken From AUHAL.rtfd :
 
128
[3] Channel Maps
 
129
Clients 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:
 
130
 
 
131
For Output:
 
132
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)
 
133
Initialize each of the array's values to -1 (-1 indicates that that channel is NOT to be presented in the conversion.)
 
134
 
 
135
Next, for each channel of your app's output, set:
 
136
channelMapArray[deviceOutputChannel] = desiredAppOutputChannel.
 
137
 
 
138
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 }
 
139
 
 
140
Where the formats are:
 
141
Input Element == 0: 2 channels (- client format - settable)
 
142
Output Element == 0: 6 channels (- device format - NOT settable)
 
143
 
 
144
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!)
 
145
 
 
146
For Input:
 
147
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.
 
148
 
 
149
Next, for each channel of input you require, set:
 
150
channelMapArray[desiredAppInputChannel] = deviceOutputChannel;
 
151
 
 
152
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 }
 
153
 
 
154
Where the formats are:
 
155
Input Element == 0: 2 channels (- device format - NOT settable)
 
156
Output Element == 0: 6 channels (- client format - settable)
 
157
 
 
158
 
 
159
 
 
160
----------------------------------------
 
161
 
 
162
Notes on Original implementation:
 
163
 
 
164
by Phil Burk and Darren Gibbs
 
165
 
 
166
Last updated March 20, 2002
 
167
 
 
168
WHAT WORKS
 
169
 
 
170
Output with very low latency, <10 msec.
 
171
Half duplex input or output.
 
172
Full duplex on the same CoreAudio device.
 
173
The paFLoat32, paInt16, paInt8, paUInt8 sample formats.
 
174
Pa_GetCPULoad()
 
175
Pa_StreamTime()
 
176
 
 
177
KNOWN BUGS OR LIMITATIONS
 
178
 
 
179
We do not yet support simultaneous input and output on different 
 
180
devices. Note that some CoreAudio devices like the Roland UH30 look 
 
181
like one device but are actually two different CoreAudio devices. The 
 
182
Built-In audio is typically one CoreAudio device.
 
183
 
 
184
Mono doesn't work.
 
185
 
 
186
DEVICE MAPPING
 
187
 
 
188
CoreAudio devices can support both input and output. But the sample 
 
189
rates supported may be different. So we have map one or two PortAudio 
 
190
device to each CoreAudio device depending on whether it supports 
 
191
input, output or both.
 
192
 
 
193
When we query devices, we first get a list of CoreAudio devices. Then 
 
194
we scan the list and add a PortAudio device for each CoreAudio device 
 
195
that supports input. Then we make a scan for output devices.
 
196