aveX Files

aveX project
============

aveX is a free software for running and monitoring ABX listening tests. It works as a Jack (Jack Audio Connection Kit) client and is able to send test-status messages over a network for monitoring purposes. 'A' and 'B' audio files are read in pairs from a list and played in randomized order, the 'X' audio file is also randomized and is either 'A' or 'B' (double-blind test). The listening test results are written after every choice in a text file.

The program's configuration is read from a XML file at start-up.
A working dummy-example is provided. 
Current version was only developed for linux.

Dependencies:
you should have liblo, libsndfile, libxml++-2.6, gtk+-2.0, gmodule-2.0 and jack development packages

Installation:
unpack the downloaded sources in a folder of your choice and open a terminal in the path of this folder, to install just run: 
>scons
a executable binary is created along with other object files.

Note.- if you see error messages check if this are related to missing libraries, if so install the -dev packages of those libraries. Otherwise write me an email with the terminal's output.

Configuration:
before starting the software you should already know the caracteristics of the test you want to run. These, as well as some other parameters are read from a configuration file written in XML format, in the 'config' folder you can find an example (ABX_config.xml) that you can edit.

The parameters to specify are:

jack_name => the name to use in the jack server. Default: aveX 

audio_file => the path to the folder containig the audio files. Default: ./audios/example/

audio_list => here you should set the path of the text file that contains the names of the audio files that are going to be used in the listening test. They should have following format:
someaudioA.wav;someaudioB
someotheraudioA.wav;someotheraudioB.wav
An example of this file can also be found in ./audios/example folder. Default: ./audios/example/audiofiles.txt

results_filename => the path of the folder where the test resuts should be stored. Default: ./results/example_project/ . The results are named after the subject. Note make sure the folder exists!

OSC_listening_port => OSC port to send monitoring messages to. Default: 59100 
The monitoring software listens also by default to port 59100 unless you specify something else at start-up. 

OSC_host => the IP address of the host (the monitoring computer).

userID => here comes the name of the subject, but will be deprecated soon since it should be written at runtime. Don't bother editing this too, all users participating in the same test use the same configuration file.

mode => in a future release there will be more operation modes. For now leave it with 'O'.

num_trials => here comes the number of decisions in a run, so it is usually the same as the number of audio-file pairs (A B pairs). 

num_runs => this parameter gives the number of times that a set of decisions should run. minimum is 1.

project => here comes the name of the project that appears in the header of the results .txt file.

Note.- The parameters should not contain any blank spaces since that could lead to miss-interpretation at parsing time.

Example.- if you have num_trials = 6 (group of 6 pairs of audio files A and B) and number of runs = 3 the user will have to make 18 choices.  Note that the runs are also randomized, so it may occur that the user become consecutively the same A-B pairs. As said before X is always randomized.

Starting aveX:
>./avex -c myconfigfile.xml
where myconfigfile.xml is your configuration file.
 
To start the provided example just type in the console (in the path where binary was created):
>./avex
you may also type:
>./avex -c ./config/ABX_config.xml
it's the same.

 if you also use -v (--verbose) you become information on what's going on in test, so it is useful only for understanding the program, the subject should not see this output.

if you use or -h (--help) you become information about how to start the program.

When aveX runs:
A GUI with the ABX listening test opens. 
Note.- you have to write a user ID (without blank spaces) to enable the decision buttons. When the test finishes you see a message and the GUI closes. You can find the results in the file specified in the configuration file. 

The first column contains the results, 1 stands for correct, 0 for wrong.
The second column displays the number of audio file pair involved in the decision. 0 for the first, 1 for the second, etc.
The third column shows the number of choice.


Releases:
=========
aveX_v0.2 21.09.2011 first release has been tested to run under linux Kernel: 2.6.38-11-generic
aveX_v0.3 01.10.2011 solved bugs regarding OSC monitoring. Sources for the monitoring software were included.  

TODO list (quite incomplete)
=========
- make the maximal length of the audio samples configurable.
- make the length of the crossfades also configurable. 
- add error/warning when audio files have a different samplerate as the jack server.

for questions write to jorgos.estrella@gmail.com