1 /*
2 * Copyright (C) 2010, Google Inc. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 *
13 * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS'' AND ANY
14 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
15 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
16 * DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY
17 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
18 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
19 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
21 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
22 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 */
24
25 #include "config.h"
26
27 #if ENABLE(WEB_AUDIO)
28
29 #include "platform/audio/HRTFPanner.h"
30
31 #include <algorithm>
32 #include "platform/audio/AudioBus.h"
33 #include "platform/audio/HRTFDatabase.h"
34 #include "wtf/MathExtras.h"
35 #include "wtf/RefPtr.h"
36
37 using namespace std;
38
39 namespace WebCore {
40
41 // The value of 2 milliseconds is larger than the largest delay which exists in any HRTFKernel from the default HRTFDatabase (0.0136 seconds).
42 // We ASSERT the delay values used in process() with this value.
43 const double MaxDelayTimeSeconds = 0.002;
44
45 const int UninitializedAzimuth = -1;
46 const unsigned RenderingQuantum = 128;
47
HRTFPanner(float sampleRate,HRTFDatabaseLoader * databaseLoader)48 HRTFPanner::HRTFPanner(float sampleRate, HRTFDatabaseLoader* databaseLoader)
49 : Panner(PanningModelHRTF)
50 , m_databaseLoader(databaseLoader)
51 , m_sampleRate(sampleRate)
52 , m_crossfadeSelection(CrossfadeSelection1)
53 , m_azimuthIndex1(UninitializedAzimuth)
54 , m_elevation1(0)
55 , m_azimuthIndex2(UninitializedAzimuth)
56 , m_elevation2(0)
57 , m_crossfadeX(0)
58 , m_crossfadeIncr(0)
59 , m_convolverL1(fftSizeForSampleRate(sampleRate))
60 , m_convolverR1(fftSizeForSampleRate(sampleRate))
61 , m_convolverL2(fftSizeForSampleRate(sampleRate))
62 , m_convolverR2(fftSizeForSampleRate(sampleRate))
63 , m_delayLineL(MaxDelayTimeSeconds, sampleRate)
64 , m_delayLineR(MaxDelayTimeSeconds, sampleRate)
65 , m_tempL1(RenderingQuantum)
66 , m_tempR1(RenderingQuantum)
67 , m_tempL2(RenderingQuantum)
68 , m_tempR2(RenderingQuantum)
69 {
70 ASSERT(databaseLoader);
71 }
72
~HRTFPanner()73 HRTFPanner::~HRTFPanner()
74 {
75 }
76
fftSizeForSampleRate(float sampleRate)77 size_t HRTFPanner::fftSizeForSampleRate(float sampleRate)
78 {
79 // The HRTF impulse responses (loaded as audio resources) are 512 sample-frames @44.1KHz.
80 // Currently, we truncate the impulse responses to half this size, but an FFT-size of twice impulse response size is needed (for convolution).
81 // So for sample rates around 44.1KHz an FFT size of 512 is good. We double the FFT-size only for sample rates at least double this.
82 ASSERT(sampleRate >= 44100 && sampleRate <= 96000.0);
83 return (sampleRate < 88200.0) ? 512 : 1024;
84 }
85
reset()86 void HRTFPanner::reset()
87 {
88 m_convolverL1.reset();
89 m_convolverR1.reset();
90 m_convolverL2.reset();
91 m_convolverR2.reset();
92 m_delayLineL.reset();
93 m_delayLineR.reset();
94 }
95
calculateDesiredAzimuthIndexAndBlend(double azimuth,double & azimuthBlend)96 int HRTFPanner::calculateDesiredAzimuthIndexAndBlend(double azimuth, double& azimuthBlend)
97 {
98 // Convert the azimuth angle from the range -180 -> +180 into the range 0 -> 360.
99 // The azimuth index may then be calculated from this positive value.
100 if (azimuth < 0)
101 azimuth += 360.0;
102
103 HRTFDatabase* database = m_databaseLoader->database();
104 ASSERT(database);
105
106 int numberOfAzimuths = database->numberOfAzimuths();
107 const double angleBetweenAzimuths = 360.0 / numberOfAzimuths;
108
109 // Calculate the azimuth index and the blend (0 -> 1) for interpolation.
110 double desiredAzimuthIndexFloat = azimuth / angleBetweenAzimuths;
111 int desiredAzimuthIndex = static_cast<int>(desiredAzimuthIndexFloat);
112 azimuthBlend = desiredAzimuthIndexFloat - static_cast<double>(desiredAzimuthIndex);
113
114 // We don't immediately start using this azimuth index, but instead approach this index from the last index we rendered at.
115 // This minimizes the clicks and graininess for moving sources which occur otherwise.
116 desiredAzimuthIndex = max(0, desiredAzimuthIndex);
117 desiredAzimuthIndex = min(numberOfAzimuths - 1, desiredAzimuthIndex);
118 return desiredAzimuthIndex;
119 }
120
pan(double desiredAzimuth,double elevation,const AudioBus * inputBus,AudioBus * outputBus,size_t framesToProcess)121 void HRTFPanner::pan(double desiredAzimuth, double elevation, const AudioBus* inputBus, AudioBus* outputBus, size_t framesToProcess)
122 {
123 unsigned numInputChannels = inputBus ? inputBus->numberOfChannels() : 0;
124
125 bool isInputGood = inputBus && numInputChannels >= 1 && numInputChannels <= 2;
126 ASSERT(isInputGood);
127
128 bool isOutputGood = outputBus && outputBus->numberOfChannels() == 2 && framesToProcess <= outputBus->length();
129 ASSERT(isOutputGood);
130
131 if (!isInputGood || !isOutputGood) {
132 if (outputBus)
133 outputBus->zero();
134 return;
135 }
136
137 HRTFDatabase* database = m_databaseLoader->database();
138 ASSERT(database);
139 if (!database) {
140 outputBus->zero();
141 return;
142 }
143
144 // IRCAM HRTF azimuths values from the loaded database is reversed from the panner's notion of azimuth.
145 double azimuth = -desiredAzimuth;
146
147 bool isAzimuthGood = azimuth >= -180.0 && azimuth <= 180.0;
148 ASSERT(isAzimuthGood);
149 if (!isAzimuthGood) {
150 outputBus->zero();
151 return;
152 }
153
154 // Normally, we'll just be dealing with mono sources.
155 // If we have a stereo input, implement stereo panning with left source processed by left HRTF, and right source by right HRTF.
156 const AudioChannel* inputChannelL = inputBus->channelByType(AudioBus::ChannelLeft);
157 const AudioChannel* inputChannelR = numInputChannels > 1 ? inputBus->channelByType(AudioBus::ChannelRight) : 0;
158
159 // Get source and destination pointers.
160 const float* sourceL = inputChannelL->data();
161 const float* sourceR = numInputChannels > 1 ? inputChannelR->data() : sourceL;
162 float* destinationL = outputBus->channelByType(AudioBus::ChannelLeft)->mutableData();
163 float* destinationR = outputBus->channelByType(AudioBus::ChannelRight)->mutableData();
164
165 double azimuthBlend;
166 int desiredAzimuthIndex = calculateDesiredAzimuthIndexAndBlend(azimuth, azimuthBlend);
167
168 // Initially snap azimuth and elevation values to first values encountered.
169 if (m_azimuthIndex1 == UninitializedAzimuth) {
170 m_azimuthIndex1 = desiredAzimuthIndex;
171 m_elevation1 = elevation;
172 }
173 if (m_azimuthIndex2 == UninitializedAzimuth) {
174 m_azimuthIndex2 = desiredAzimuthIndex;
175 m_elevation2 = elevation;
176 }
177
178 // Cross-fade / transition over a period of around 45 milliseconds.
179 // This is an empirical value tuned to be a reasonable trade-off between
180 // smoothness and speed.
181 const double fadeFrames = sampleRate() <= 48000 ? 2048 : 4096;
182
183 // Check for azimuth and elevation changes, initiating a cross-fade if needed.
184 if (!m_crossfadeX && m_crossfadeSelection == CrossfadeSelection1) {
185 if (desiredAzimuthIndex != m_azimuthIndex1 || elevation != m_elevation1) {
186 // Cross-fade from 1 -> 2
187 m_crossfadeIncr = 1 / fadeFrames;
188 m_azimuthIndex2 = desiredAzimuthIndex;
189 m_elevation2 = elevation;
190 }
191 }
192 if (m_crossfadeX == 1 && m_crossfadeSelection == CrossfadeSelection2) {
193 if (desiredAzimuthIndex != m_azimuthIndex2 || elevation != m_elevation2) {
194 // Cross-fade from 2 -> 1
195 m_crossfadeIncr = -1 / fadeFrames;
196 m_azimuthIndex1 = desiredAzimuthIndex;
197 m_elevation1 = elevation;
198 }
199 }
200
201 // This algorithm currently requires that we process in power-of-two size chunks at least RenderingQuantum.
202 ASSERT(1UL << static_cast<int>(log2(framesToProcess)) == framesToProcess);
203 ASSERT(framesToProcess >= RenderingQuantum);
204
205 const unsigned framesPerSegment = RenderingQuantum;
206 const unsigned numberOfSegments = framesToProcess / framesPerSegment;
207
208 for (unsigned segment = 0; segment < numberOfSegments; ++segment) {
209 // Get the HRTFKernels and interpolated delays.
210 HRTFKernel* kernelL1;
211 HRTFKernel* kernelR1;
212 HRTFKernel* kernelL2;
213 HRTFKernel* kernelR2;
214 double frameDelayL1;
215 double frameDelayR1;
216 double frameDelayL2;
217 double frameDelayR2;
218 database->getKernelsFromAzimuthElevation(azimuthBlend, m_azimuthIndex1, m_elevation1, kernelL1, kernelR1, frameDelayL1, frameDelayR1);
219 database->getKernelsFromAzimuthElevation(azimuthBlend, m_azimuthIndex2, m_elevation2, kernelL2, kernelR2, frameDelayL2, frameDelayR2);
220
221 bool areKernelsGood = kernelL1 && kernelR1 && kernelL2 && kernelR2;
222 ASSERT(areKernelsGood);
223 if (!areKernelsGood) {
224 outputBus->zero();
225 return;
226 }
227
228 ASSERT(frameDelayL1 / sampleRate() < MaxDelayTimeSeconds && frameDelayR1 / sampleRate() < MaxDelayTimeSeconds);
229 ASSERT(frameDelayL2 / sampleRate() < MaxDelayTimeSeconds && frameDelayR2 / sampleRate() < MaxDelayTimeSeconds);
230
231 // Crossfade inter-aural delays based on transitions.
232 double frameDelayL = (1 - m_crossfadeX) * frameDelayL1 + m_crossfadeX * frameDelayL2;
233 double frameDelayR = (1 - m_crossfadeX) * frameDelayR1 + m_crossfadeX * frameDelayR2;
234
235 // Calculate the source and destination pointers for the current segment.
236 unsigned offset = segment * framesPerSegment;
237 const float* segmentSourceL = sourceL + offset;
238 const float* segmentSourceR = sourceR + offset;
239 float* segmentDestinationL = destinationL + offset;
240 float* segmentDestinationR = destinationR + offset;
241
242 // First run through delay lines for inter-aural time difference.
243 m_delayLineL.setDelayFrames(frameDelayL);
244 m_delayLineR.setDelayFrames(frameDelayR);
245 m_delayLineL.process(segmentSourceL, segmentDestinationL, framesPerSegment);
246 m_delayLineR.process(segmentSourceR, segmentDestinationR, framesPerSegment);
247
248 bool needsCrossfading = m_crossfadeIncr;
249
250 // Have the convolvers render directly to the final destination if we're not cross-fading.
251 float* convolutionDestinationL1 = needsCrossfading ? m_tempL1.data() : segmentDestinationL;
252 float* convolutionDestinationR1 = needsCrossfading ? m_tempR1.data() : segmentDestinationR;
253 float* convolutionDestinationL2 = needsCrossfading ? m_tempL2.data() : segmentDestinationL;
254 float* convolutionDestinationR2 = needsCrossfading ? m_tempR2.data() : segmentDestinationR;
255
256 // Now do the convolutions.
257 // Note that we avoid doing convolutions on both sets of convolvers if we're not currently cross-fading.
258
259 if (m_crossfadeSelection == CrossfadeSelection1 || needsCrossfading) {
260 m_convolverL1.process(kernelL1->fftFrame(), segmentDestinationL, convolutionDestinationL1, framesPerSegment);
261 m_convolverR1.process(kernelR1->fftFrame(), segmentDestinationR, convolutionDestinationR1, framesPerSegment);
262 }
263
264 if (m_crossfadeSelection == CrossfadeSelection2 || needsCrossfading) {
265 m_convolverL2.process(kernelL2->fftFrame(), segmentDestinationL, convolutionDestinationL2, framesPerSegment);
266 m_convolverR2.process(kernelR2->fftFrame(), segmentDestinationR, convolutionDestinationR2, framesPerSegment);
267 }
268
269 if (needsCrossfading) {
270 // Apply linear cross-fade.
271 float x = m_crossfadeX;
272 float incr = m_crossfadeIncr;
273 for (unsigned i = 0; i < framesPerSegment; ++i) {
274 segmentDestinationL[i] = (1 - x) * convolutionDestinationL1[i] + x * convolutionDestinationL2[i];
275 segmentDestinationR[i] = (1 - x) * convolutionDestinationR1[i] + x * convolutionDestinationR2[i];
276 x += incr;
277 }
278 // Update cross-fade value from local.
279 m_crossfadeX = x;
280
281 if (m_crossfadeIncr > 0 && fabs(m_crossfadeX - 1) < m_crossfadeIncr) {
282 // We've fully made the crossfade transition from 1 -> 2.
283 m_crossfadeSelection = CrossfadeSelection2;
284 m_crossfadeX = 1;
285 m_crossfadeIncr = 0;
286 } else if (m_crossfadeIncr < 0 && fabs(m_crossfadeX) < -m_crossfadeIncr) {
287 // We've fully made the crossfade transition from 2 -> 1.
288 m_crossfadeSelection = CrossfadeSelection1;
289 m_crossfadeX = 0;
290 m_crossfadeIncr = 0;
291 }
292 }
293 }
294 }
295
tailTime() const296 double HRTFPanner::tailTime() const
297 {
298 // Because HRTFPanner is implemented with a DelayKernel and a FFTConvolver, the tailTime of the HRTFPanner
299 // is the sum of the tailTime of the DelayKernel and the tailTime of the FFTConvolver, which is MaxDelayTimeSeconds
300 // and fftSize() / 2, respectively.
301 return MaxDelayTimeSeconds + (fftSize() / 2) / static_cast<double>(sampleRate());
302 }
303
latencyTime() const304 double HRTFPanner::latencyTime() const
305 {
306 // The latency of a FFTConvolver is also fftSize() / 2, and is in addition to its tailTime of the
307 // same value.
308 return (fftSize() / 2) / static_cast<double>(sampleRate());
309 }
310
311 } // namespace WebCore
312
313 #endif // ENABLE(WEB_AUDIO)
314