Binaural Rendering Toolbox

https://grupodiana.github.io/BRT-Documentation/
Admin
The Binaural Rendering Toolbox (BRT) is an open, extensible C++ library and set of applications for...
Tokens:266,404
Snippets:1,682
Trust Score:9.7
Update:20 hours ago
Show doc for...
Tokens:
Raw
### Begin Setup

Source: https://grupodiana.github.io/BRT-Documentation/library/service-modules/service-hrtf/

Prepares the HRTF object for initialization and starts the configuration process.

```APIDOC
## Begin Setup

### Description
Prepares the HRTF object for initialization and starts the configuration process.

### Method
Begin Setup

### Parameters
None

### Response
None
```

--------------------------------

### Begin Setup

Source: https://grupodiana.github.io/BRT-Documentation/library/service-modules/service-ambisonic-bir/

Initializes the setup process with the specified ambisonic order and normalization scheme.

```APIDOC
## Begin Setup

### Description
Initializes the setup process with the specified ambisonic order and normalization scheme.

### Method
Begin Setup

### Parameters
- **ambisonicOrder** (type not specified) - Required - The ambisonic order.
- **normalizationScheme** (type not specified) - Required - The normalization scheme.

### Response
No response details provided.
```

--------------------------------

### End Setup

Source: https://grupodiana.github.io/BRT-Documentation/library/service-modules/service-ambisonic-bir/

Completes the setup process and confirms the system is ready.

```APIDOC
## End Setup

### Description
Completes the setup process and confirms the system is ready.

### Method
End Setup

### Parameters
None specified.

### Response
No response details provided.
```

--------------------------------

### End Setup

Source: https://grupodiana.github.io/BRT-Documentation/library/service-modules/service-hrtf/

Finalizes the setup process and stores the configured HRTF data.

```APIDOC
## End Setup

### Description
Finalizes the setup process and stores the configured HRTF data.

### Method
End Setup

### Parameters
None

### Response
None
```

--------------------------------

### Instantiation and Connection Example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example code showing how to instantiate the CSOSBilateralFilterModel and connect it to a listener and a listener model.

```APIDOC
## Instantiation and Connection Example

### Description
This example demonstrates how to create a `CSOSBilateralFilterModel` using the BRT manager and connect it to a listener and a listener model.

### Code Example
```cpp
brtManager.BeginSetup();
std::shared_ptr<BRTBilateralFilter::CSOSBilateralFilterModel> binauralFilter =
    brtManager.CreateBinauralFilter<BRTBilateralFilter::CSOSBilateralFilterModel>(_binauralFilterID);
brtManager.EndSetup();
if (binauralFilter == nullptr) {
    // ERROR
}

std::shared_ptr<BRTBase::CListener> listener = brtManager.GetListener(_listenerID);
if (listener != nullptr) {
    brtManager.BeginSetup();
    bool control = listener->ConnectBinauralFilter(_binauralFilterID);
    brtManager.EndSetup();
}

std::shared_ptr<BRTBilateralFilter::CBilateralFilterModelBase> binauralFilter =
    brtManager.GetBinauralFilter<BRTBilateralFilter::CBilateralFilterModelBase>(_binauralFilterID);
if (binauralFilter != nullptr) {
    brtManager.BeginSetup();
    bool control = binauralFilter->ConnectListenerModel(_listenerModelID);
    brtManager.EndSetup();
}
```
```

--------------------------------

### soundLevelAlert Example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of the /control/soundLevelAlert command sent by BeRTA.

```plaintext
/control/soundLevelAlert 60 62
```

--------------------------------

### /listener/orientation example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of the /listener/orientation command. BeRTA receives and echoes back to all subscribers except the sender.

```plaintext
/listener/orientation defaultListener 0.1 0 0
```

--------------------------------

### /recordIR Example Command

Source: https://grupodiana.github.io/BRT-Documentation/osc/overall/

Example of the /recordIR command as received and echoed by BeRTA, with a wav file, 2-second duration, and directivity enabled.

```text
/recordIR "record/sytem_conf_IR.wav" "wav" 2 0 0 1 0 0 Directivity1 true
```

--------------------------------

### /playAndRecord example command and results

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of /playAndRecord with a 10-second recording, showing the echo and both success and failure result messages.

```plaintext
/playAndRecord c:/tmp/file.mat mat 10
```

```plaintext
/control/actionResult /playAndRecord c:/tmp/file.mat true Recording completed. File saved : c:/tmp/file.mat
```

```plaintext
/control/actionResult /playAndRecord c:/tmp/file.mat false ERROR:Recording failed. File could not be created.
```

--------------------------------

### /record example command and results

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of /record with a 10-second processing time, showing the echo and both success and failure result messages.

```plaintext
/record c:/tmp/file.mat mat 10
```

```plaintext
/control/actionResult /record c:/tmp/file.mat true Recording completed. File saved : c:/tmp/file.mat
```

```plaintext
/control/actionResult /record c:/tmp/file.mat false ERROR:Recording failed. File could not be created.
```

--------------------------------

### OSC command: /environment/setReflectionOrder example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of BeRTA receiving and echoing the command, and sending back the action result.

```plaintext
/environment/setReflectionOrder ISM 3
```

```plaintext
/control/actionResult /environment/setReflectionOrder ISM true "Reflection Order updated in the model (ISM) to 3.
```

--------------------------------

### Instantiation and Connection Example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example code showing how to instantiate an omnidirectional source model and connect it to listener and environment models using the BRT manager.

```APIDOC
## Instantiation and Connection Example

### Description
Example code showing how to instantiate an omnidirectional source model and connect it to listener and environment models using the BRT manager.

### Code Example
```cpp
// Assuming that the ID of this environment model is contained in _environmentID.
brtManager.BeginSetup();
std::shared_ptr<BRTSourceModel::CSourceOmnidirectionalModel> soundSource = brtManager->CreateSoundSource<BRTSourceModel::CSourceOmnidirectionalModel>(soundSourceID);
brtManager.EndSetup();
if (soundSource == nullptr) {
    // error
}

// Assuming that the soundSource could be a ID(string) or a std::shared_ptr<BRTSourceModel::CSourceModelBase>;
std::shared_ptr<BRTListenerModel::CListenerModelBase> listenerModel = brtManager->GetListenerModel<BRTListenerModel::CListenerModelBase>(_listenerModelID);
if (listenerModel != nullptr) {
    bool control = listenerModel->ConnectSoundSource(soundSource);
}

// Assuming that the ID of this source model is contained in _sourceID and that the ID of this environment is contained in _environmentModelID.
std::shared_ptr<BRTEnvironmentModel::CEnviromentModelBase> environmentModel = brtManager->GetEnvironmentModel<BRTEnvironmentModel::CEnviromentModelBase>(_environmentModelID);
if (environmentModel != nullptr) {
    bool control = environmentModel->ConnectSoundSource(_sourceID);
}
```

```

--------------------------------

### OSC command: /environment/setRoom example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of BeRTA receiving and echoing the command, and sending back the action result. Shows an error when room is not found.

```plaintext
/environment/setRoom SDN room1
```

```plaintext
/control/actionResult /environment/setRoom SDN false "ERROR setting Room to the environment room1 not found in the Room list'].
```

--------------------------------

### /resources/loadHRTF example and echo

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of BeRTA receiving and echoing back the /resources/loadHRTF command, and the return message sent to the sender.

```plaintext
/resources/loadHRTF HRTF1 c:/tmp/hrtf.sofa 5
```

```plaintext
/control/actionResult /resources/loadHRTF HRTF1 true HRTF HRTF1 loaded successfully, with a spatial resolution of 5, from the file: c:/tmp/hrtf.sofa
```

```plaintext
/control/actionResult /resources/loadHRTF HRTF1 false HRTF sofa file couldn't be loaded from HRTF1 .
```

--------------------------------

### getListenerSoundLeveldBFS Unknown Listener Example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of the /control/getListenerSoundLeveldBFS command when the requested listener does not exist, returning valid=false and an error description.

```plaintext
/control/getListenerSoundLeveldBFS Unknown
```

```plaintext
/control/getListenerSoundLeveldBFS Unknown false -inf -inf "Listener Unknown does not exist."
```

--------------------------------

### Get filter info example - request and response

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of /resources/getFilterInfo: BeRTA receives a request and sends back the SOFA file name.

```plaintext
/resources/getFilterInfo NFCF1
```

```plaintext
/resources/getFilterInfo NFCF1 NFCFilters.sofa
```

--------------------------------

### Connect SphericalSOSTable to a listener model

Source: https://grupodiana.github.io/BRT-Documentation/library/service-modules/service-spherical-sos-table/

C++ example showing how to get a listener by ID and set near-field compensation filters. Assumes the listener ID is in _listenerID and the HRTF is already successfully loaded into hrtf.

```cpp
// Assuming that the ID of this listener is contained in _listenerID and 
// that the HRTF is already lsuccessfuly loaded into hrtf.
std::shared_ptr<BRTBase::CListener> listener = brtManager->GetListener(listenerID);
listener->SetNearFieldCompensationFilters(hrtf);
```

--------------------------------

### Play reference signal with /control/playCalibration

Source: https://grupodiana.github.io/BRT-Documentation/applications/calibration/

Starts the reference signal at the specified digital RMS level on the given output pair. The example plays at -40 dBFS on channels 0-1. BeRTA plays the file resources/Calibration/CalibrationPinkNoise.wav in a loop, sending identical samples to both channels. The request is rejected if sample rate mismatch, gain calculation fails, or clipping would occur.

```OSC
/control/playCalibration -40 0
```

--------------------------------

### BeginSetup

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Initializes the FIR table setup with the given HRIR length and extrapolation method.

```APIDOC
## BeginSetup

### Description
Initializes the FIR table setup with the given HRIR length and extrapolation method.

### Method
bool BeginSetup(const int32_t & _HRIRLength, const BRTServices::TEXTRAPOLATION_METHOD & _extrapolationMethod) override

### Parameters
- `_HRIRLength` (int32_t) - Length of the HRIR.
- `_extrapolationMethod` (BRTServices::TEXTRAPOLATION_METHOD) - Extrapolation method.

### Returns
bool - True if setup began successfully.
```

--------------------------------

### BeginSetup(...)

Source: https://grupodiana.github.io/BRT-Documentation/library/service-modules/service-spherical-fir-table/

Initializes the table configuration before inserting impulse responses.

```APIDOC
## BeginSetup(...)

### Description
Initializes the table configuration before inserting impulse responses.

### Method
BeginSetup

### Parameters
- **...** (unspecified) - Required - Configuration parameters for the setup.

### Returns
Void.
```

--------------------------------

### Resources JSON configuration example

Source: https://grupodiana.github.io/BRT-Documentation/applications/settingsFile/

Example JSON for the 'Resources' section. Lists HRTFs, BRIRs, filters, directivities, and rooms to load at startup. Each entry includes an ID and a fileName, with optional parameters like spatialResolution and fadeInWindowThreshold. Rooms can be defined by dimensions or by loading an OBJ file.

```json
"Resources" : {
        "HRTFs": [{"ID": "HRTF1", "fileName": "resources//HRTF//3DTI_HRTF_SADIE_II_D2_256s_48000Hz_resampled5.sofa", "spatialResolution": 5}],      
        "BRIRs": [{"ID": "BRIR1", "fileName": "resources//BRIR//3DTI_BRIR_Trapezoid_48000Hz_3D.sofa", "spatialResolution": 15, "fadeInWindowThreshold" : 0, "fadeInWindowRiseTime": 0, "fadeOutWindowThreshold" : 0, "fadeOutWindowRiseTime": 0}],      
        "Filters": [
            {"ID": "DefaultNFFilters", "fileName": "resources//SOSFilters//NearFieldCompensation_ILD_1.2m_48Khz.sofa"},
            {"ID": "JBLCompensation", "fileName": "resources//Filters//Phone_Compensation_JBLQuantum100_48000.sofa"}
            ],
        "Directivities": [
            {"ID": "Directivity1", "fileName": "resources//Directivity//Cardioid_LP_30dB_512s_resampled10_normalized_fir_512.sofa"}
        ],
        Rooms":[
            {"ID": "Room1", "length": 3, "width":5.5, "height": 3},
            {"ID": "Room2", "fileName": "resources//OBJ//A108_room.obj"}
        ]
    },
```

--------------------------------

### /listener/location example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of the /listener/location command. BeRTA receives and echoes back to all subscribers except the sender.

```plaintext
/listener/location defaultListener 0 0 0
```

--------------------------------

### BeRTA /source/orientation example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example command that BeRTA receives and echoes back to all subscribers except the sender.

```plaintext
/source/orientation source1 0 0 0
```

--------------------------------

### Instantiate CListenerAmbisonicReverberantVirtualLoudspeakersModel

Source: https://grupodiana.github.io/BRT-Documentation/library/listener-models/rir-models/listener-acoustic-environment-model-ambisonic-brir/

Shows how to create the listener model using brtManager.BeginSetup(), CreateListenerModel, and EndSetup(). Checks for nullptr to handle errors.

```cpp
// Assuming that the ID of this listener model is contained in _listenerModelID.
brtManager.BeginSetup();
std::shared_ptr<BRTListenerModel::CListenerAmbisonicReverberantVirtualLoudspeakersModel>listenerModel = brtManager.CreateListenerModel<BRTListenerModel::CListenerAmbisonicReverberantVirtualLoudspeakersModel>(_listenerModelID);
brtManager.EndSetup();
if (listenerModel == nullptr) {
    // ERROR
}
```

--------------------------------

### OSC command: /environment/setMaxDistanceSourcesToListener example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of BeRTA receiving and echoing the command, and sending back the action result.

```plaintext
/environment/setMaxDistanceSourcesToListener ISM 10.5
```

```plaintext
/control/actionResult /environment/setMaxDistanceSourcesToListener ISM true "Max Distance Sources to Listener updated in the model (ISM) to 10.5m.
```

--------------------------------

### Remove filter example - echo and response

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of /resources/removeFilter: BeRTA echoes to subscribers and sends an actionResult to the sender.

```plaintext
/resources/removeFilter EarMuffFilter
```

```plaintext
/control/actionResult /resources/removeFilter EarMuffFilter true Filter coefs. (EarMuffFilter) removed from the resource list.
```

```plaintext
/control/actionResult /resources/removeFilter EarMuffFilter false ERROR deleting coefs. (EarMuffFilter) not found in the list.
```

--------------------------------

### SetupShoeBox()

Source: https://grupodiana.github.io/BRT-Documentation/library/service-modules/service-room/

Creates a rectangular (shoebox) room defined by length (X), width (Y), and height (Z). Generates six walls with proper geometry, inward-facing normals, editable absorption coefficients, and optional activation/deactivation. Walls cannot be reshaped but absorption and active status can be modified.

```APIDOC
## SetupShoeBox()

### Description
Creates a rectangular (shoebox) room defined by length (X), width (Y), and height (Z). Generates six walls with proper geometry, inward-facing normals, editable absorption coefficients, and optional activation/deactivation. Walls cannot be reshaped but absorption and active status can be modified.

### Method
SetupShoeBox

### Parameters
- **length** (float) - Required - Length along X axis
- **width** (float) - Required - Width along Y axis
- **height** (float) - Required - Height along Z axis

### Response
Returns a room object with six walls, each having editable absorption coefficients and active status.
```

--------------------------------

### Enable Reverb Path Command Example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of the /environment/enableReverbPath command. BeRTA receives the command and echoes it back to all subscribers except the sender, then sends an action result to the sender.

```plaintext
/environment/enableReverbPath SDN false
```

```plaintext
/control/actionResult /environment/enableReverbPath SDN true "Environment model SDN Reverb path enabled"
```

--------------------------------

### getListenerSoundLeveldBFS Silent Listener Example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of the /control/getListenerSoundLeveldBFS command for a valid silent listener, returning -inf for both channels.

```plaintext
/control/getListenerSoundLeveldBFS B true -inf -inf ""
```

--------------------------------

### Example exchange for stopCalibrationTest

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of BeRTA receiving a stopCalibrationTest command and sending back an actionResult with success=true and a description.

```plaintext
/control/stopCalibrationTest 0
```

```plaintext
/control/actionResult /control/stopCalibrationTest calibrationTest true "Calibration test stopped."
```

--------------------------------

### bool BeginSetup(const int32_t & _HRIRLength, const BRTServices::TEXTRAPOLATION_METHOD & _extrapolationMethod) override

Source: https://grupodiana.github.io/BRT-Documentation/library/service-modules/service-spherical-interpolated-fir-table/

Initializes the table configuration before inserting impulse responses.

```APIDOC
## bool BeginSetup(const int32_t & _HRIRLength, const BRTServices::TEXTRAPOLATION_METHOD & _extrapolationMethod) override

### Description
Initializes the table configuration before inserting impulse responses.

### Method
Override

### Signature
`bool BeginSetup(const int32_t & _HRIRLength, const BRTServices::TEXTRAPOLATION_METHOD & _extrapolationMethod) override`

### Parameters
- **_HRIRLength** (const int32_t &) - Required - The length of the HRIRs.
- **_extrapolationMethod** (const BRTServices::TEXTRAPOLATION_METHOD &) - Required - The extrapolation method to use.

### Returns
- **bool** - True if setup was successful, false otherwise.
```

--------------------------------

### Load SOS filters example - echo and response

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of /resources/loadSOSFilters: BeRTA echoes to subscribers and sends an actionResult to the sender.

```plaintext
/resources/loadSOSFilters SOSF1 c:/tmp/SOSilters.sofa
```

```plaintext
/control/actionResult /resources/loadSOSFilters NFCF1 true SOS filter SOSF1 loaded successfully, from the file: c:/tmp/SOSilters.sofa
```

```plaintext
/resources/loadSOSFilters SOSF1 false ERROR deleting SOS filter. SOSF1 not found in the list.
```

--------------------------------

### Enable Direct Path Command Example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of the /environment/enableDirectPath command. BeRTA receives the command and echoes it back to all subscribers except the sender, then sends an action result to the sender.

```plaintext
/environment/enableDirectPath SDN false
```

```plaintext
/control/actionResult /environment/enableDirectPath SDN true "Environment model SDN Direct path enabled"
```

--------------------------------

### BeRTA /resources/getHRTFHeadRadius example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of requesting the head radius of an HRTF. BeRTA sends back the head radius value.

```plaintext
/resources/getHRTFHeadRadius HRTF1
```

```plaintext
/resources/getHRTFHeadRadius HRTF1 0.09
```

--------------------------------

### /source/play command example

Source: https://grupodiana.github.io/BRT-Documentation/assets/brt-documentation.pdf

Example of the /source/play command. BeRTA receives the command and echoes it back to all subscribers except the sender, then sends a /control/actionResult confirmation to the sender.

```plaintext
/source/play source1
```

```plaintext
/control/actionResult /source/play source1 true Audio source source1 played back
```

--------------------------------

### GeneralSettings JSON configuration example

Source: https://grupodiana.github.io/BRT-Documentation/applications/settingsFile/

Example of the GeneralSettings section in the JSON configuration file. It sets sample rate, buffer size, buffer frames, OSC listen port, extrapolation method, default audio interfaces, and log file options. The DefaultInputAudioInterface and DefaultOutputAudioInterface are set to -1 to use the operating system defaults if not found.

```json
"GeneralSettings": {
  "SampleRate": 48000,
  "BufferSize": 512,
  "BufferFrames": 4,
  "OSCListenPort": 10017,
  "ExtrapolationMethod": "NearestPoint",
  "DefaultInputAudioInterface": -1,
  "DefaultOutputAudioInterface": -1,
  "LogFile": true,
  "LogFilePath" : "",
}
```
Tokens:
Raw