forked from torbenwendt/razr
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
314 lines (241 loc) · 13.5 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
===========================================
RAZR SOFTWARE PACKAGE FOR MATHWORK'S MATLAB
===========================================
RAZR - Room acoustics simulator
Version 0.93
Copyright (c) 2014-2017, Torben Wendt, Steven van de Par, Stephan Ewert,
University of Oldenburg, Germany.
All rights reserved.
Author: Torben Wendt
e-mail: torben.wendt(at)uni-oldenburg.de
===============================================================================
Algorithm reference
===============================================================================
Wendt, T., van de Par, S., Ewert, S.D. (2014): A Computationally-Efficient and
Perceptually-Plausible Algorithm for Binaural Room Impulse Response Simulation.
J. Audio Eng. Soc., Vol. 62, No. 11, pp. 748-766.
Please note: The set of default options contain some optimizations compared to
the setup described in the publication above. You can however load the original
setup by using GET_DEFAULT_OPTIONS_2014.M. To see how to use options, see also
the subsection "Getting started/Data structures", below in this file.
===============================================================================
What's in the distribution?
===============================================================================
This distribution adds a toolbox for synthesizing and analyzing binaural
room impulse responses (BRIRs) to your Matlab installation. Example simulations
are included.
Included Files
--------------
./* - RAZR top-level functions, README, license, disclaimer
ANALYSIS_TOOLS/
*.M - Collection of tools to analyze BRIRs
HEADPHONE_EQ/*.mat - Equalization files for headphones
EXAMPLES/*.M - Some examples to create BRIRs
BASE/** - RAZR core files
EXTERNAL/** - Files created by other Authors, see Credits below
HRTF/** - Supplementary files for HRTF application
MEXFDN/* - Compiled FDN mainloop
TOOLS/*.M - Supplementary functions for simulation and analysis
All these files must not be changed as also not permitted by RAZR's license,
unless not stated otherwise. Changes might moreover harm proper function of
this distribution. For exceptions see the following section "License and
permissions".
===============================================================================
License and permissions
===============================================================================
Unless otherwise stated, the RAZR distribution, including all files is licensed
under Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International
(CC BY-NC-ND 4.0).
In short, this means that you are free to use and share (copy, distribute and
transmit) the RAZR distribution under the following conditions:
Attribution - You must attribute the RAZR distribution by acknowledgement of
the author if it appears or if was used in any form in your work.
The attribution must not in any way that suggests that the author
endorse you or your use of the work.
Noncommercial - You may not use RAZR for commercial purposes.
No Derivative Works - You may not alter, transform, or build upon RAZR.
Exceptions are:
- The files ./BASE/EXTERNAL/**, see their respective license.
Users are explicitly granted to modify, derive their own modifications and to
distribute their modifications for the configurations, options and examples:
- The file RAZR_CFG.M in the main folder
- All files in the folder ./EXAMPLES
For further exceptions, see the license headers in the respecive files and the
section "Credits" in this file.
===============================================================================
Installation
===============================================================================
Requirements
------------
- Windows 95/98, Windows NT/2000/XP or higher, or MAC OSX, or Linux
- Mathwork's MATLAB Version 7.4 or higher
Recommended
-----------
- Sound device
- Headphones
Installation
------------
- Unzip all included files to your preferred directory.
===============================================================================
Getting Started
===============================================================================
Demo and Example scripts
------------------------
To start the demo, type "razr demo".
Besides, in the directory "EXAMPLES", you can find some example scripts, that
demonstrate the usage of this program package. See the respective files for
details. When you have read and tried out all examples, you know the most
important features of RAZR.
To start any of the examples, type "razr addpath" to temporally add all required
folders to MATLAB's path. Then type, e.g., "example_default" or
"example_options".
A formal usage description is provided in the documentation of the top-level
function razr(). Type "razr help" to display it.
Please see also the changelog if you have already used earlier versions of RAZR.
Data structures
---------------
RAZR uses three essential data structures, that occur in the probably most
common usage of RAZR:
ir = razr(room, op);
(1) A room is defined as a Matlab structure, called "room" in most scripts and
functions. It contains information about the room size, wall absorption,
positions of source and receiver, and other specifications. For the required
fields of a room structure see the example rooms defined in
EXAMPLES/GET_ROOM_*.M. Both, required and optional fields are explained in the
help entry of RAZR.M. Depending on your taste and needs, you can
generate and store own rooms either in functions like the examples, as *.mat
files, directly within scripts, or by any other means. For example, for
automated RIR creation for many rooms in a loop, .mat files might be the most
convenient way to store rooms as they can easily be loaded by filename.
(2) Options for the BRIR synthesis are defined in a structure, called "op" in
most scripts and functions. All possible fields and their default values are
stored in BASE/GET_DEFAULT_OPTIONS.M. To display options, check out also the
function "sop".
Some of them are experimental, refer to features in development (and thus not
contained in the current version), or might read unclear. In doubt, stick to
the default or contact the author. See EXAMPLES/EXAMPLE_OPTIONS.M to see how
to use options.
(3) Room impulse responses are stored as a structure, called "ir" in most
scripts and functions. It contains the time signal itself and some metadata,
depending on your chosen options. For instance, ir can contain also the signals
for direct sound, early and late reflections in separate fields, if the option
"return_rir_parts" is set to "true".
Most of the functions in ANALYSIS_TOOLS expect a BRIR in the format of such a
structure as input parameter.
For further information, type "razr help".
Configuration
-------------
In contrast to the options structure, which specifies how a BRIR is created, in
the configuration it is mainly defined, where RAZR finds certain files on your
computer. Hence, on different computers, the same options can be used, whereas
the configuration has to be adapted.
Configuration structures are defined in RAZR_CFG_DEFAULT.M and RAZR_CFG_USER.M.
(The latter one is automatically created when you run razr for the first time.)
Internally, RAZR_CFG_USER overloads RAZR_CFG_DEFAULT. You can also create and
store several configuration files in parallel. In the file SELECT_RAZR_CFG.M,
you can specify what configuration is actually used to override
RAZR_CFG_DEFAULT. RAZR_CFG_USER is the predefined one.
===============================================================================
Using HRTFs/HRIRs
===============================================================================
This program package does not contain any HRTF data. In the default settings, a
spherical head model (SHM) is used, implemented after [2]. However, though the
SHM yields reasonably good results (and is computationally very efficient),
using HRTFs is an essential part of BRIR simulation. If you would like to use
HRTFs you need to get a database from external sources. To link an HRTF database
to RAZR, download the database to the preferred directory on your harddrive.
Then, this database must be specified in ./RAZR_CFG.M as described in the
following:
SOFA format
-----------
RAZR supports HRIRs that are stored in the SOFA format [3], using the SOFA con-
vention "SimpleFreeFieldHRIR" [3]. If you would like to use SOFA-formatted HRIRs
you need to download the SOFA API for Matlab/Octave from
https://www.sofaconventions.org/mediawiki/index.php/Software_and_APIs
Store and unzip the API in your preferred directory. In RAZR, open the file
RAZR_CFG_USER and set the field "cfg.sofa_api_path" to the path where you stored
the API.
Then, there are two ways to use a SOFA database in RAZR:
(1) Specify the name of the .sofa file directly as option, e.g.,
op.hrtf_database = path/to/database.sofa;
(2) Use a shortcut. In ./RAZR_CFG.M, a shortcut to a .sofa file can be linked
as, e.g,.:
cfg.sofa_file__<shortcut> = path/to/database.sofa;
(Note the double underscore before <shortcut>.) Then, the option to use this
Database can be set as:
op.hrtf_database = 'shortcut.sofa';
(The suffix ".sofa" is required although it is not part of the shortcut.)
Other formats
-------------
For an HRTF database that is stored in any other format, its path on your hard-
drive must be specified in ./RAZR_CFG.M:
cfg.hrtf_path__<shortcut> = path/to/database;
where <shortcut> is the unique key for the database. For already supported data-
bases, configuration fields have already been prepared there. (Note: Some of
them are not open access databases or not published, yet.)
If you would like to use an unsupported (non-SOFA) HRTF database, you need
create two Matlab functions, which will be executed internally in RAZR:
- hrtf_params_<shortcut> to set database-specific parameters.
- pick_hrir_<shortcut> to pick a set of HRIRs from the database according
to a set of desired azimuth and elevation angles.
For the syntax of these functions and required parameters please see the
examples provided in ./BASE/HRTF.
If you create these functions for an open-access database, be cordially invited
to share them with the author, such that they can be included in a future
release.
All formats (SOFA and non-SOFA)
-------------------------------
To actually use an HRTF database (SOFA or non-SOFA), the following option must
be set and passed to razr:
op.spat_mode = 'hrtf';
Note that the sampling rate of the HRIRs from a database must match the sampling
rate of the BRIR generated by RAZR (44100 Hz). If necessary, it can be adjusted
using the option op.fs, e.g.,
op.fs = 48000;
HRTF usage is also demonstrated in EXAMPLES/EXAMPLE_HRTF.M which is precon-
figured for the FABIAN database [4]. To run this example with the FABIAN data-
base, download the database from [3] and store it in a preferred directory on
your harddrive. Then replace 'path_to_database' in ./RAZR_CFG.M in the SOFA file
definition for the FABIAN database with the path to the directory where you
stored the database.
===============================================================================
References
===============================================================================
[1] Wendt, T., van de Par, S., Ewert, S.D. (2014): A Computationally-Efficient
and Perceptually-Plausible Algorithm for Binaural Room Impulse Response
Simulation. J. Audio Eng. Soc., Vol. 62, No. 11
[2] C. P. Brown and R.O. Duda (1998): "A Structural Model for Binaural Sound
Synthesis," IEEE Trans. Speech Audio Processing, vol. 6, no. 5
[3] https://www.sofaconventions.org
[4] Brinkmann, F., Lindau, A., Weinzierl, S., Geissler, G., & van de Par, S.
(2013). A high resolution head-related transfer function database including
different orientations of head above the torso. AIA-DAGA 2013.
===============================================================================
Credits
===============================================================================
This work was supported by
- DFG-FOR 1732 "Individualisierte Hoerakustik",
- Cluster of Excellence EXC 1077/1 Hearing4all.
I'd like to thank Dr. Stephan D. Ewert and Prof. Dr. Steven van de Par for
continuous support on the algorithm development and evaluation.
I'd like to thank all the people who tested earlier versions of the Software,
contributed to it, reported on bugs, or made suggestions for improvements:
Thomas Biberger, Oliver Buttler, Stephan D. Ewert, Jan-Hendrik Flessner, Nico
Goessling, Julian Grosse, Andreas Haeussler, Stefan Klockgether, Steven van de
Par, Josef Poppitz, Joachim Thiemann. (Sorry if I forgot someone here.)
All files in the directory ./BASE/EXTERNAL and all subdirectories are written
by other authors. Please see the file headers or license.txt files further
informations on licenses. In some cases I did code modifications. For details,
see the comments in the code. The authors are:
Daniyal Amir OVERWRITE_MERGE.M
Robert Baumgartner HOR2GEO.M
Piotr Majdak GEO2HORPOLAR.M
Ofek Shilon RANDORTHMAT.M (modified Version for RAZR: RANDORTHMAT3.M)
Todd Welti SMOOTHNEW3.M
Furthermore, some supplementary functions for HRTF databases, located in
respective subfolders of ./BASE/HRTF, are written by the following authors:
Hendrik Kayser (kayser-database), Gunnar Geissler (mk2-database).
The unreverberated sound samples in ./BASE/EXTERNAL/SAMPLES are
part of the Oldenburg Sentence Test for AFC Software Package by Stephan Ewert,
Daniel Berg, Hoertech gGmbH. See also
BASE/EXTERNAL/SAMPLES/OLSA_SENTENCES_README.TXT.