Join GitHub today
RAZR – Room acoustics simulator for Mathwork’s MATLAB
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
=========================================== 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 . 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 , using the SOFA con- vention "SimpleFreeFieldHRIR" . 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 . To run this example with the FABIAN data- base, download the database from  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 ===============================================================================  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  C. P. Brown and R.O. Duda (1998): "A Structural Model for Binaural Sound Synthesis," IEEE Trans. Speech Audio Processing, vol. 6, no. 5  https://www.sofaconventions.org  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.