(C) 2022-2026 IVAS codec Public Collaboration with portions copyright Dolby International AB, Ericsson AB,
Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V., Huawei Technologies Co. LTD.,
Koninklijke Philips N.V., Nippon Telegraph and Telephone Corporation, Nokia Technologies Oy, Orange,
Panasonic Holdings Corporation, Qualcomm Technologies, Inc., VoiceAge Corporation, and other
contributors to this repository. All Rights Reserved.
This software is protected by copyright law and by international treaties.
The IVAS codec Public Collaboration consisting of Dolby International AB, Ericsson AB,
Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V., Huawei Technologies Co. LTD.,
Koninklijke Philips N.V., Nippon Telegraph and Telephone Corporation, Nokia Technologies Oy, Orange,
Panasonic Holdings Corporation, Qualcomm Technologies, Inc., VoiceAge Corporation, and other
contributors to this repository retain full ownership rights in their respective contributions in
the software. This notice grants no license of any kind, including but not limited to patent
license, nor is any license granted by implication, estoppel or otherwise.
Contributors are required to enter into the IVAS codec Public Collaboration agreement before making
contributions.
This software is provided "AS IS", without any express or implied warranties. The software is in the
development stage. It is intended exclusively for experts who have experience with such software and
solely for the purpose of inspection. All implied warranties of non-infringement, merchantability
and fitness for a particular purpose are hereby disclaimed and excluded.
Any dispute, controversy or claim arising under or in relation to providing this software shall be
submitted to and settled by the final, binding jurisdiction of the courts of Munich, Germany in
accordance with the laws of the Federal Republic of Germany excluding its conflict of law rules and
the United Nations Convention on Contracts on the International Sales of Goods.
-->
# Modeling tool for all IVAS binaural renderers
# Allows to convert SOFA file(s) to ROM tables files (*.c|h) or binaural binary file(s)
# Allows to convert SOFA file(s) to ROM tables files (\*.c|h) or binaural binary file(s)
## Requirements
- MATLAB >= R2017b
- Signal Processing Toolbox
- C/C++ compiler
- Linux (Ubuntu) :
```shell
sudo apt-get update
sudo apt-get install build-essential
```
- Windows
- Install Visual Studio Community Edition or other: https://visualstudio.microsoft.com/fr/vs/community/
- CMake version > 3.5
* MATLAB >= R2017b
* Signal Processing Toolbox
* C/C++ compiler
* Linux (Ubuntu) :
* Windows
* Install Visual Studio Community Edition or other: https://visualstudio.microsoft.com/fr/vs/community/
* CMake version > 3.5
### Build `generate_crend_ivas_tables`
- Open a command line terminal
- Execute
```shell
mkdir build
cd build
cmake ..
cmake --build.
cd ..
```
-`generate_crend_ivas_tables` executable shall be in folder [`../../scripts/binauralRenderer_interface`](../../scripts/binauralRenderer_interface)
- On Windows this executable requires DLL from MATLAB, you need to add to your path `*/matlab/version/bin/win64`
- For more details on `generate_crend_ivas_tables` see [`ivas_crend_sofa_to_rom_table_converter_readme.txt`](ivas_crend_sofa_to_rom_table_converter_readme.txt).
- On Apple Silicon Mac with Intel MATLAB, it is necessary to add `SET(CMAKE_OSX_ARCHITECTURES "x86_64")` in the `CMakeLists.txt` near the top of the file. This forces the compilation to use Intel architecture instead ofo the native one.
- if find_package do not find matlab, at the beginning of the cmakelists.txt file you can set the search path with the folowing line set(Matlab_ROOT_DIR matlab_path), for example on linux set(Matlab_ROOT_DIR ~/MATLAB/R2023b) on mac set(Matlab_ROOT_DIR /Applications/MATLAB_R2023b.app)
* Open a command line terminal
* Execute
*`generate_crend_ivas_tables` executable shall be in folder [`../../scripts/binauralRenderer_interface`](../../scripts/binauralRenderer_interface)
* On Windows this executable requires DLL from MATLAB, you need to add to your path `*/matlab/version/bin/win64`
* For more details on `generate_crend_ivas_tables` see [`ivas_crend_sofa_to_rom_table_converter_readme.txt`](ivas_crend_sofa_to_rom_table_converter_readme.txt).
* On Apple Silicon Mac with Intel MATLAB, it is necessary to add `SET(CMAKE_OSX_ARCHITECTURES "x86_64")` in the `CMakeLists.txt` near the top of the file. This forces the compilation to use Intel architecture instead ofo the native one.
* if find\_package do not find matlab, at the beginning of the cmakelists.txt file you can set the search path with the folowing line set(Matlab\_ROOT\_DIR matlab\_path), for example on linux set(Matlab\_ROOT\_DIR ~/MATLAB/R2023b) on mac set(Matlab\_ROOT\_DIR /Applications/MATLAB\_R2023b.app)
### Build `tables_format_converter`
- Open a command line terminal
- Goto folder
- Execute
```shell
cd ../../scripts/binauralRenderer_interface/Table_Format_Converter
mkdir build
cd build
cmake ..
cmake --build.--config Release
cd ..
```
-`tables_format_converter` executable shall be in the folder [`../../scripts/binauralRenderer_interface/Table_Format_Converter/`](../../scripts/binauralRenderer_interface/Table_Format_Converter)
* Open a command line terminal
* Goto folder
* Execute
*`tables_format_converter` executable shall be in the folder [`../../scripts/binauralRenderer_interface/Table_Format_Converter/`](../../scripts/binauralRenderer_interface/Table_Format_Converter)
- Generate part of ROM file [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) and/or parametric renderer binary file.
- To generate complete [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) ROM file see example in [`generate_ivas_binauralizer_tables_from_sofa.m`](generate_ivas_binauralizer_tables_from_sofa.m)
- See [`README.txt`](../../scripts/binauralRenderer_interface/fastconv/README.txt) in the folder.
- Generate part of ROM file [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) and/or FastConv renderer binary file.
- To generate complete [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) file see example in [`generate_ivas_binauralizer_tables_from_sofa.m`](generate_ivas_binauralizer_tables_from_sofa.m).
-**Warning**: The computed values for late reverberation depend on MATLAB and OS versions used. IVAS tests are still BE.
- See [`README.md`](../../scripts/td_object_renderer/modeling_tool/README.md) in the folder.
- Generate part of the ROM files [`ivas_rom_TdBinauralRenderer.h`](../../lib_rend/ivas_rom_TdBinauralRenderer.h), [`ivas_rom_TdBinauralRenderer.c`](../../lib_rend/ivas_rom_TdBinauralRenderer.c), and TD renderer binary file.
-**Warning**: The "fastconvReverberationTimes" computed values depend on MATLAB and OS versions used. Current values are computed with matlab 2017b on windows as mentioned in the rom file.
* Generate part of ROM file [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) and/or parametric renderer binary file.
* To generate complete [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) ROM file see example in [`generate_ivas_binauralizer_tables_from_sofa.m`](generate_ivas_binauralizer_tables_from_sofa.m)
* See [`README.txt`](../../scripts/binauralRenderer_interface/fastconv/README.txt) in the folder.
* Generate part of ROM file [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) and/or FastConv renderer binary file.
* To generate complete [`ivas_rom_binauralRenderer.c`](../../lib_rend/ivas_rom_binauralRenderer.c) file see example in [`generate_ivas_binauralizer_tables_from_sofa.m`](generate_ivas_binauralizer_tables_from_sofa.m).
***Warning**: The computed values for late reverberation depend on MATLAB and OS versions used. IVAS tests are still BE.
* See [`README.md`](../../scripts/td_object_renderer/modeling_tool/README.md) in the folder.
* Generate part of the ROM files [`ivas_rom_TdBinauralRenderer.h`](../../lib_rend/ivas_rom_TdBinauralRenderer.h), [`ivas_rom_TdBinauralRenderer.c`](../../lib_rend/ivas_rom_TdBinauralRenderer.c), and TD renderer binary file.
***Warning**: The "fastconvReverberationTimes" computed values depend on MATLAB and OS versions used. Current values are computed with matlab 2017b on windows as mentioned in the rom file.
### SOFA files:
- HRIRs sofa files for testing are stored in [`HRIRs_sofa`](HRIRs_sofa) folder
- BRIRs sofa files for testing are stored in [`BRIRs_sofa`](BRIRs_sofa) folder
- The current scripts have not been tested with other SOFA files. For other SOFA files some adaptations of the scripts may be required. Current scripts are provided as an example.
* HRIRs sofa files for testing are stored in [`HRIRs_sofa`](HRIRs_sofa) folder
* BRIRs sofa files for testing are stored in [`BRIRs_sofa`](BRIRs_sofa) folder
* The current scripts have not been tested with other SOFA files. For other SOFA files some adaptations of the scripts may be required. Current scripts are provided as an example.
See [`scripts/ThirdPartyLegalNotices`](../../scripts/ThirdPartyLegalNotices) for related information.
## Usage
- Run the following MATLAB script: [`generate_ivas_binauralizer_tables_from_sofa.m`](generate_ivas_binauralizer_tables_from_sofa.m)
- It will generate ROM files that can be used to compile IVAS decoder or renderer. By default, the result is BE.
- It will also generate binary files that can be used with `-hrtf` flag in IVAS decoder or renderer command line.
- Using IVAS decoder or renderer with default binary files will generate BE output compare to the same command line without `-hrtf` flag.
- To test different SOFA files input you need to modify the script in the section `%% Set input files`. Other SOFA files are available in [`HRIRs_sofa`](HRIRs_sofa) folder.
-**Warning**: The script will overwrite the tables in [`lib_rend`](../../lib_rend/)
→ Generated files are in folder [`binaural_renderers_hrtf_data`](binaural_renderers_hrtf_data)
- Generated files :
-`ivas_binaural_*kHz.bin`: file containing all tables values for all IVAS binaural renderers for one sample rate.
* Run the following MATLAB script: [`generate_ivas_binauralizer_tables_from_sofa.m`](generate_ivas_binauralizer_tables_from_sofa.m)
* It will generate ROM files that can be used to compile IVAS decoder or renderer. By default, the result is BE.
* It will also generate binary files that can be used with `-hrtf` flag in IVAS decoder or renderer command line.
* It genarates also the rom tables for the basop reposirory. Once generated they need to be copied pn an IVAS basop repo branch
* Using IVAS decoder or renderer with default binary files will generate BE output compare to the same command line without `-hrtf` flag.
* To test different SOFA files input you need to modify the script in the section `%% Set input files`. Other SOFA files are available in [`HRIRs_sofa`](HRIRs_sofa) folder.
***Warning**: The script will overwrite the tables in [`lib_rend`](../../lib_rend/)
* The overall gain of the HRIR/BRIR must be adjusted to ensure that the IVAS codec produces an output signal with the appropriate level. For example, the levels (measured using BS1770) of the same IVAS-encoded bitstream decoded to mono, stereo, or binaural should be similar (within ±2 dB). The following scripts can be used to adjust the global level of a new set of HRIRs or BRIRs. If the HRIRs are diffuse-field equalized, a gain of approximately -3 dB is usually required.
*[`compute_HRIR_BRIR_gains.m` ](compute_HRIR_BRIR_gains.m) : allows to compute binaural output levels of mono, stereo or multichannels content. Binauralisation of mono input having a levlel of -26LKFS should be around the value within +/- 1dB. Sme for mutlichannel content having decorrelated channels.
*[`check_ivas_binaural_gains.m`](check_ivas_binaural_gains.m) : Once you have determine the gain to apply. First compile IVAS\_dec on rename it IVAS\_dec\_ref. Change the gain value in the script [`generate_ivas_binauralizer_tables_from_sofa `](generate_ivas_binauralizer_tables_from_sofa.m) and run it. The compile again IVAS\_dec. Run [`check_ivas_binaural_gains.m`](check_ivas_binaural_gains.m) to check the levels againt IVAS\_dec\_ref.
→ Generated files are in folder [`binaural_renderers_hrtf_data`](binaural_renderers_hrtf_data)
* Generated files :
*`ivas_binaural_*kHz.bin`: file containing all tables values for all IVAS binaural renderers for one sample rate.
```
cd ../../scripts/binauralRenderer_interface/Table_Format_Converter
