Installation of the development version

Getting the code

The development of the Two!Ears Auditory Model happens independently for its different modules. All of them are hosted as git repositories on github. For an overview go to https://github.com/TWOEARS.

Note

Internally the Two!Ears development happens at https://dev.qu.tu-berlin.de. The repositories on github are mirrors of our internal ones, excluding code or data that cannot be made public.

In order to get started you should familarize yourself with git and then start to clone the repository you would like to change the code. First you have to start with getting the main repository as all other modules need this as a basis:

$ git clone https://github.com/TWOEARS/main.git

Working on the whole Two!Ears model

Let us now assume you want to take part in the development of the complete Two!Ears Auditory Model. What you have to do then is the following. In the main repository you will find the file TwoEars.xml which defines all modules that are part of the Two!Ears Auditory Model:

<?xml version="1.0" encoding="utf-8"?>
<!-- Configure which parts of the Two!Ears model should be started -->

<requirements>
    <TwoEarsPart sub="src"    startup="startBinauralSimulator">binaural-simulator</TwoEarsPart>
    <TwoEarsPart sub="API_MO" startup="SOFAstart">sofa</TwoEarsPart>
    <TwoEarsPart              startup="startAuditoryFrontEnd">auditory-front-end</TwoEarsPart>
    <TwoEarsPart              startup="startBlackboardSystem">blackboard-system</TwoEarsPart>
</requirements>

So first clone of off the necessary repositories:

$ mkdir git
$ mkdir git/twoears/
$ cd git/twoears
$ git clone https://github.com/TWOEARS/main.git
$ git clone https://github.com/TWOEARS/binaural-simulator.git
$ git clone https://github.com/TWOEARS/SOFA.git
$ git clone https://github.com/TWOEARS/auditory-front-end.git
$ git clone https://github.com/TWOEARS/blackboard-system.git

Then you have to define the paths of the single modules. In the main repository copy the file TwoEarsPaths_Example.xml to TwoEarsPaths.xml and adjust it to the used paths, in our case the default settings, which is:

<?xml version="1.0" encoding="utf-8"?>
<!-- Configuration file for the Two!Ears auditory model -->

<repoPaths>
    <!-- https://github.com/TWOEARS/binaural-simulator -->
    <binaural-simulator>~/git/twoears/binaural-simulator</binaural-simulator>
    <!-- https://github.com/TWOEARS/auditory-front-end -->
    <auditory-front-end>~/git/twoears/auditory-front-end</auditory-front-end>
    <!-- https://github.com/TWOEARS/blackboard-system -->
    <blackboard-system>~/git/twoears/blackboard-system</blackboard-system>
    <!-- https://github.com/TWOEARS/SOFA -->
    <sofa>~/git/twoears/SOFA</sofa>
</repoPaths>

After that you can simply run the following command in the folder of the main repository in order to work with the model:

>> startTwoEars;

Working on a single module

If you would like to work only on a single module you need only to get its repository as well as all its dependencies. If you not sure what are the dependencies, you can have a look at its XML configuration file. For example, in the case of the Binaural simulator it is stored in the file BinauralSimulator.xml in its main directory of the binaural-simulator repository:

<?xml version="1.0" encoding="utf-8"?>
<!-- Configure dependency of Two!Ears modules for the Binaural Simulator -->

<!-- Start the Two!Ears Binaural Simulator with
     startTwoEars('BinauralSimulator.xml'); -->

<requirements>
  <TwoEarsPart  sub="src"
                startup="startBinauralSimulator">binaural-simulator</TwoEarsPart>
  <TwoEarsPart  sub="API_MO"
                startup="SOFAstart">sofa</TwoEarsPart>
</requirements>

This means in this case you have to clone the sofa repository in order to use the Binaural simulator:

$ mkdir git
$ mkdir git/twoears
$ cd git/twoears
$ git clone https://github.com/TWOEARS/main.git
$ git clone https://github.com/TWOEARS/SOFA.git

After that you can start the Binaural simulator in Matlab with the following command in order to test it:

>> startTwoEars('BinauralSimulator.xml');

Setting up dependencies on particular branches

Git allows to ease software development by using branches. During the development of the whole model it could happen that you have dependencies to particular branches of other modules. You can specify those dependencies also in the XML configuration files, for example:

<?xml version="1.0" encoding="utf-8"?>
<!-- Configure which parts of the Two!Ears model should be started -->

<requirements>
    <TwoEarsPart branch="master"
                 sub="src"
                 startup="startBinauralSimulator">binaural-simulator</TwoEarsPart>
    <TwoEarsPart branch="feature1"
                 sub="API_MO"
                 startup="SOFAstart">sofa</TwoEarsPart>
    <TwoEarsPart branch="feature1"
                 startup="startAuditoryFrontEnd">auditory-front-end</TwoEarsPart>
    <TwoEarsPart branch="master"
                 startup="startBlackboardSystem">blackboard-system</TwoEarsPart>
</requirements>

The startTwoEars function will then check if you have all the modules checked out at the correct branches. Of course you have to have git installed in order to use this feature. Even if you are using only the master branches you are encouraged to use the branch setting as it ensures that other people testing your code are also using the master branch and not another one.

Note

Under Windows it is most likely that Matlab complains that git cannot be found in the system path, when executing startTwoEars. To fix this you have to add git to your system paths, see for example this tutorial.

Another feature of the startTwoEars script is the setting sub-all instead of sub which will include the specified path, as sub will do, but also all of its sub-folders.