Usage

This instruction guides you in detail on how to use the Binaural simulator, for a brief guide have a look at the tutorial Setting up an acoustic scene. For instructions on how to use the whole Two!Ears Auditory Model have a look at the provided Examples.

In the following it is assumed that you have started the Two!Ears Auditory Model already via the startTwoEars() command, see also the Installation guide.

Configuration

There are basically two ways for controlling and configuring the Binaural simulator. In both cases you will need audio files to create your acoustic scenes with it. You could of course use your own audio files, but you can also use files from the large Database. In that case you only have to specify the path of the desired files in the database and the Binaural simulator will download them during processing. For further information on that have a look at the Working with the database.

Configuration using a Matlab script

The Binaural simulator uses the object-oriented programming architecture of Matlab. In order to initialise the simulation tool, an Object of the SimulatorConvexRoom()-class has to be instantiated by:

>> sim = simulator.SimulatorConvexRoom();

Note that the constructor returns a handle, which is the pendant to a reference of an object in other programming language. Assigning sim to a another variable does not copy the object. The simulation framework is depending on a simulation kernel written in C++/MEX. It is not recommended to instantiate more than one object of the SimulatorConvexRoom()-class by calling the constructor multiple times, since all objects would access the same simulation kernel. To see all configurable parameters of the simulator call the object’s name in Matlab:

>> sim

sim =

  SimulatorConvexRoom with properties:

                BlockSize: 4096
               SampleRate: 44100
          NumberOfThreads: 1
                 Renderer: @ssr_binaural
              HRIRDataset: [1x1 simulator.DirectionalIR]
             MaximumDelay: 0.0500
                 PreDelay: 0
       LengthOfSimulation: 5
                  Sources: {[1x1 simulator.source.Point]  [1x1 simulator.source.Point]}
                    Sinks: [1x1 simulator.AudioSink]
                    Walls: []
    ReverberationRoomType: 'shoebox'
    ReverberationMaxOrder: 0

For a more detailed description of each parameter refer to the documentation in the source code. In order to change various processing parameters of the simulator the build-in set/get functionality of Matlab should be used, e.g.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
% some processing parameters
set(sim, ...
  'BlockSize', 4096, ...
  'SampleRate', 44100, ...
  'MaximumDelay', 0.05, ...
  'PreDelay', 0.0, ...
  'LengthOfSimulation', 5.0, ...
  'Renderer', @ssr_binaural, ...
  'HRIRDataset', simulator.DirectionalIR( ...
    'impulse_responses/qu_kemar_anechoic/QU_KEMAR_anechoic_3m.sofa') ...
  );

Line 3 and 4 set the sample rate of the simulator to 44.1 kHz and defines a block size of 4096 samples. To define the acoustic scene, add the sound sources and the listener.

1
2
3
4
5
% acoustic scene
set(sim, ...
  'Sources', {simulator.source.Point(), simulator.source.Point()}, ...
  'Sinks', simulator.AudioSink(2) ...
  );

Sound sources are stored in a cell array. Line 3 defines two point sources, are created by calling the constructor of the simulator.source.Point-class. For the binaural simulation the parameter Sinks must contain only one object of the simulator.AudioSink-class describing the listener (Line 4). The argument 2 in the constructor’s call defines the number of input channel of the sink, which is 2 for binaural signals. Since sources and sinks are also handles, they can be accessed using the same set/get procedure as for the simulator object, e.g.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
% set parameters of audio sources
set(sim.Sources{1}, ...
  'AudioBuffer', simulator.buffer.FIFO(1), ...
  'Position', [1; 2; 1.75], ...
  'Name', 'Cello', ...
  'Volume', 0.4 ...
  );

set(sim.Sources{2}, ...
  'AudioBuffer', simulator.buffer.FIFO(1), ...
  'Position', [1; -2; 1.75], ...
  'Name', 'Castanets' ...
  );

% set parameters of head
set(sim.Sinks, ...
  'Position' , [0; 0; 1.75], ...
  'UnitX', [1; 0; 0], ...
  'UnitZ', [0; 0; 1], ...
  'Name', 'Head' ...
  );

Name defines an unique identifier for the scene object, which should not be re-used for any other scene object. Position defines the position of the scene object in 3D Cartesian coordinates (measured in meter). In order to emit sound from sound sources, audio buffers have to be respectively defined containing the sources’ audio signals. A single-channel FIFO-Buffer can be defined by simulator.buffer.FIFO(1). For more details about possible buffer types please refer to the documentation in the source code of the buffers. To load sound files into the buffers execute

1
2
3
4
5
6
% set audio input of buffers
set(sim.Sources{1}.AudioBuffer, ...
  'File', 'stimuli/anechoic/instruments/anechoic_cello.wav');

set(sim.Sources{2}.AudioBuffer, ...
  'File', 'stimuli/anechoic/instruments/anechoic_castanets.wav');

Configuration using XML Scene Description

In following the configuration as defined above using a Matlab script is done calling the constructor of the simulator object with an extra argument defining the file name of a XML scene description file.

>> sim = simulator.SimulatorConvexRoom('test_binaural.xml');

The content of test_binaural.xml is shown below.

 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
<scene
  BlockSize="4096"
  SampleRate="44100"
  MaximumDelay="0.05"
  PreDelay="0.0"
  LengthOfSimulation="5.0"
  NumberOfThreads="1"
  Renderer="ssr_binaural"
  HRIRs="impulse_responses/qu_kemar_anechoic/QU_KEMAR_anechoic_3m.sofa">
  <source Position="1 2 1.75"
          Type="point"
          Name="Cello"
          Volume="0.4">
    <buffer ChannelMapping="1"
            Type="fifo"
            File="stimuli/anechoic/instruments/anechoic_cello.wav"/>
  </source>
  <source Position="1 -2 1.75"
          Type="point"
          Name="Castanets">
    <buffer ChannelMapping="1"
            Type="fifo"
            File="stimuli/anechoic/instruments/anechoic_castanets.wav"/>
  </source>
  <sink Position="0 0 1.75"
        UnitX="1 0 0"
        UnitZ="0 0 1"
        Name="Head"/>
</scene>

Simulate Ear-Signals

After setting up all parameters the simulator object is ready to simulate ear signals according to the defined acoustic scene. In order to load all parameters into the simulation kernel execute

>> sim.set('Init',true);

Note, that all the processing parameters and objects’ initial positions have to be defined before initialisation in order to initialise the simulation properly. After the simulator has been initialised it is not possible to re-assign any property of the simulator object. Hence the number of acoustic sources cannot be changed within one simulation run. However, modifying e.g. the position of a scene object is possible. The following loop calculates the ear signals until the acoustic scene is finished.

1
2
3
4
while ~sim.isFinished()
  sim.set('Refresh',true);  % refresh all objects
  sim.set('Process',true);
end

The function sim.isFinished() yields true if the buffers of all sound sources are empty or if sim.LengthOfSimulation has been reached. Note, that the simulator is a block-wise processor: Each call of line 3 generates a block of ear signals whose length is defined by sim.BlockSize. Between two processing steps, the properties of scene objects may be manipulated, e.g. the position of a scene object is changed. If necessary, call line 2 once before processing a new block in order to send any modification to the simulation kernel. The ear signals are stored in the FIFO buffer of the sim.Sinks object.

1
2
3
4
% read whole data from buffer
data = sim.Sinks.getData();
% save date into file
sim.Sinks.saveFile('out_binaural.wav',sim.SampleRate);

In order to access or store the data line 2 or 4 may be used respectively. To finish the simulation shut down and clean up the simulator by calling:

>> sim.set('ShutDown',true);

The simulator reverts to an uninitialised state, where the manipulation of every parameter is possible, again. This is necessary, if you want to start a new simulation with complete different parameters like e.g. different number of sound sources. If you want to start a new simulation with same parameters as before a kind of a weak shut down should do the job:

>> sim.set('ReInit',true);

Again, objects’ initial positions have to be defined before re-initialisation in order to initialise the simulation properly. The simulator however remains in an initialised state.

To get more hands on the Binaural simulator have a look at its Examples page.