Release 1.14
[openal-soft.git] / hrtf.txt
Commit [+]AuthorDateLineData
842a698f
CR
Chris Robinson2012-03-11 19:27:40 -07001HRTF Support
2============
3
4Starting with OpenAL Soft 1.14, HRTFs can be used to enable enhanced
5spatialization for both 3D (mono) and multi-channel sources, when used with
6headphones/stereo output. This can be enabled using the 'hrtf' config option.
7
8For multi-channel sources this creates a virtual speaker effect, making it
9sound as if speakers provide a discrete position for each channel around the
10listener. For mono sources this provides much more versatility in the perceived
11placement of sounds, making it seem as though they are coming from all around,
12including above and below the listener, instead of just to the front, back, and
13sides.
14
15The built-in data set is based on the KEMAR HRTF diffuse data provided by MIT,
16which can be found at <http://sound.media.mit.edu/resources/KEMAR.html>. It's
17only available when using 44100hz playback.
18
19
20External HRTF Data Sets
21=======================
22
23OpenAL Soft also provides an option to use user-specified data sets, in
24addition to or in place of the built-in set. This allows users to provide their
25own data sets, which could be better suited for their heads, or to work with
26stereo speakers instead of headphones, or to support more playback sample
27rates, for example.
28
29The file format for the data sets is specified below. It uses little-endian
30byte order. Certain data fields are restricted to specific values (these
31restriction may be lifted in future versions of the lib).
32
33==
34ALchar magic[8] = "MinPHR00";
35ALuint sampleRate;
36
37ALushort hrirCount; /* Required value: 828 */
38ALushort hrirSize; /* Required value: 32 */
39ALubyte evCount; /* Required value: 19 */
40
41ALushort evOffset[evCount]; /* Required values:
42 { 0, 1, 13, 37, 73, 118, 174, 234, 306, 378, 450, 522, 594, 654, 710, 755,
43 791, 815, 827 } */
44
45ALshort coefficients[hrirCount][hrirSize];
46ALubyte delays[hrirCount]; /* Element values must not exceed 127 */
47==
48
0efbf7bc Chris Robinson2012-03-12 17:15:44 -070049The data is described as thus:
842a698f
CR
Chris Robinson2012-03-11 19:27:40 -070050
51The file first starts with the 8-byte marker, "MinPHR00", to identify it as an
52HRTF data set. This is followed by an unsigned 32-bit integer, specifying the
ebc69bc8
CR
Chris Robinson2012-03-12 00:58:14 -070053sample rate the data set is designed for (OpenAL Soft will not use it if the
54output device's playback rate doesn't match).
842a698f
CR
Chris Robinson2012-03-11 19:27:40 -070055
56Afterward, an unsigned 16-bit integer specifies the total number of HRIR sets
57(each HRIR set is a collection of impulse responses forming the coefficients
58for a convolution filter). The next unsigned 16-bit integer specifies how many
ebc69bc8 Chris Robinson2012-03-12 00:58:14 -070059samples are in each HRIR set (the number of coefficients in the filter). The
842a698f Chris Robinson2012-03-11 19:27:40 -070060following unsigned 8-bit integer specifies the number of elevations used by the
93e71f05 Chris Robinson2012-03-12 17:54:16 -070061data set. The elevations start at the bottom, and increment upwards.
842a698f
CR
Chris Robinson2012-03-11 19:27:40 -070062
63Following this is an array of unsigned 16-bit integers, one for each elevation
ebc69bc8
CR
Chris Robinson2012-03-12 00:58:14 -070064which specifies the index offset to the start of the HRIR sets for each given
65elevation (the number of HRIR sets at each elevation is infered by the offset
66to the next elevation, or by the total count for the last elevation).
842a698f
CR
Chris Robinson2012-03-11 19:27:40 -070067
68The actual coefficients follow. Each coefficient is a signed 16-bit sample,
69with each HRIR set being a consecutive number of samples. For each elevation,
93e71f05 Chris Robinson2012-03-12 17:54:16 -070070the HRIR sets first start with a neutral "in-front" set (that is, one that is
3e0cf0f2
CR
Chris Robinson2012-03-12 18:42:21 -070071applied equally to the left and right outputs). After this, the sets follow a
72clockwise pattern, constructing a full circle for the left ear only. The right
73ear uses the same sets but in reverse (ie, left = angle, right = 360-angle).
842a698f
CR
Chris Robinson2012-03-11 19:27:40 -070074
75After the coefficients is an array of unsigned 8-bit delay values, one for each
76HRIR set. This is the delay, in samples, after recieving an input sample before
77before it's added in to the convolution filter that the corresponding HRIR set
93e71f05 Chris Robinson2012-03-12 17:54:16 -070078operates on and gets heard.
3daaa078
CR
Chris Robinson2012-03-12 17:14:42 -070079
80
81Note that the HRTF data is expected to be minimum-phase reconstructed. The
82time delays are handled by OpenAL Soft according to the specified delay[]
83values, and afterward the samples are fed into the convolution filter using the
84corresponding coefficients. This allows for less processing by using a shorter
93e71f05
CR
Chris Robinson2012-03-12 17:54:16 -070085convolution filter, as it skips the first coefficients that do little more than
86cause a timed delay, as well as the tailing coefficients that are used to
87equalize the length of all the sets and contribute nothing.
3daaa078
CR
Chris Robinson2012-03-12 17:14:42 -070088
89For reference, the built-in data set uses a 32-sample convolution filter while
90even the smallest data set provided by MIT used a 128-sample filter (a 4x
91reduction by applying minimum-phase reconstruction). Theoretically, one could
92further reduce the minimum-phase version down to a 16-sample convolution filter
93with little quality loss.