--------------------------------------------------
---------       The A/ST Software        ---------
---------    Version 5.1, March 2020     ---------
--------------------------------------------------
- Fraunhofer IIS and Audio Laboratories Erlangen -
--------------------------------------------------
--------------------------------------------------
* INTRODUCTION

The Adjustment/Satisfaction Test (A/ST) is a perceptual test where subjects interact with a user-adjustable system and their adjustment preferences and the resulting satisfaction levels are studied. 

The details are presented in:
Matteo Torcoli, Juergen Herre, et al., "The Adjustment/Satisfaction Test (A/ST) for the Evaluation of Personalization in Broadcast Services and Its Application to Dialogue Enhancement," IEEE Transaction on Broadcasting, 64(2): 524-538, 2018.

This package contains a demo implementation for the A/ST software. This is implemented in Max/MSP.
Please read carefully the license agreement text: LICENSE.text.

If you find the A/ST Software useful please cite the mentioned publication.

--------------------------------------------------
* REQUIREMENT

** Max 7 (https://cycling74.com/downloads). Also Max 8 seems to work fine.
** Audio files in subfolder ./data. Audio files containing up to 6 channels (e.g., 5.1) are supported.

--------------------------------------------------
* IMPLEMENTATION PRINCIPLES

Launching ASTv5_1_main.maxpat starts the test procedure. The user is first asked to input an ID or a nickname that will be used for creating the file storing the results. 
After pressing Enter, a new result file is created, which will be updated throughout the test. Hence, a new screen suggests to regulate the overall volume.
After this the phases Adjustment (tools_UserInterface_adjust.maxpat) and Satisfaction (tools_UserInterface_satisf.maxpat) will appear in turn for each test item.

It is required that the experimenter chooses some discrete personalization levels and that the corresponding set of audio files is created and copied in the data folder (see the section about /data). 
For each test item, this software loads the set of audio files (i.e. the conditions) in parallel and gives the user the possibility to browse through them. In this way, a real-time interaction with the system under test is simulated. 
Also, the user can switch between a default setting and the several personalization levels and can select a preferred setting (adjustment phase). The selection is saved in a .txt file (see the section about /RESULTS) together with the answer to the question about the level of satisfaction (satisfaction phase).

We ran this test by providing the user with a rotating knob. This knob is depicted in the graphical user interface of the adjustment phase (which reads graphics_minus.png, graphics_plus.png, and graphics_select.png). 
The rotation of the knob was mapped to the left and right arrow on the keyboard and the selection is mapped to "Enter" on the keyboard. 
Hence, a keyboard is enough to run the A/ST software (if you want to simply use the keyboard, then we recommend to delete graphics_minus.png, graphics_plus.png, and graphics_select.png and to remove '_alternative' from the file names of the remaining png files). 
However, in order to reduce the risk of a bias, we suggest the usage of a controller that makes the personalization steps not clearly perceivable.
The spacebar is used to pause the audio, while the keys 1 and 2 are used to switch between the default (or reference) signal and the current personalization level.

We distribute the source code for the Max patches (.maxpat) so that a new experimenter can easily modify the software according to the needs of the new experiment. We appreciate any feedback and contribution (see CONTACTS). Please read carefully LICENSE.text.

--------------------------------------------------
** ASTv5_1_main.maxpat

This is the main patch and the entry point for running the A/ST. Open this with Max 7 or 8 and the A/ST will start.
Please note that the position and the dimension of the windows can be suboptimal depending on the dimension and resolution of your screen. However, this should be easy to adjust for your screen.

** /data

This folder has to contain the test material. Please create subfolders containing WAVE files. 
Each subfolder corresponds to a test item (the name of the subfolder is considered as the item name). 
In the test, the subfolders (i.e., the items) are presented in the same order as their alphabetical order. The contained WAVE files are considered as the outputs of the same system on the same input signal with different adjustment settings. The alphabetical order of the contained files (i.e., the conditions) is also important. The audio files are interpreted as alphabetically ordered samples of the personalization range. Please check that the alphabetical order of these is right. E.g., 22MyItem.wav comes before 3MyItem.wav alphabetically, but this is probably not intended. 03MyItem.wav is a better file name here.

Inside the item folders, a default.txt file is expected alongside with the audio files. This txt files contains only a number, indicating which audio file (in alphabetical order) should be considered as the default setting. This file has to contain plain text. If you are using a text editor that uses other formats as default (e.g. rtf), please convert it to plain text. E.g., in TextEdit on Mac this can be done by selecting Format -> convert to plain text.

An example data set is present, where the user can personalize the cutoff frequency of a low-pass filter on white noise. Hence, "./data/01_WhiteNoise/" contains WhiteNoisecutoff01.wav, WhiteNoisecutoff02.wav and so on.
The file default.txt contains "4" indicating that WhiteNoisecutoff04.wav has to be considered as the file corresponding to the default setting.

Please note that a maximum of 41 files in each folder is supported. If more is needed, you can modify the patchers "openTracks", "mixerL", "mixerR", and the 'selector~' objects in ASTv5_1_main.maxpat.

** /RESULTS

The A/ST software stores the selections of the users in the folder "/RESULTS".
For each user, a .txt file is created. The name of the user and the current date and time are used to create the file name. The content of the .txt file is structured as follows:

Name of the item (i.e., folder name)
Preferred setting (i.e., WAVE file name)
Selected satisfaction (from 0 to 30)

The levels of the selected satisfaction follow this mapping:
30 Much better
25 Better
20 Slightly better
15 The same as
10 Slightly worse
5 Worse
0 Much worse

The first item is used also during the initial phase, where the overall volume is adjusted. So this file name is printed once more to store also this piece of information.

** How to modify the messages describing the task for the participant?

The messages describing the task for the test participant are hard-coded inside the Max patches, but they can be easily modified. 
For example, the default message for the adjustment phase is: "Find the audio setting that allows you to follow the speech easily but also enjoy the rest of the content, e.g., background music."
If a different task has to be carried out by the participant, the message has to be changed. If you are familiar with Max, this should be trivial, but you can do this also without opening Max. By opening tools_UserInterface_adjust.maxpat with a text editor, you can change line 53, where the message is hard coded.
Similarly, the message for the satisfaction phase can be changed inside tools_UserInterface_satisf.maxpat (line 1052).
Also the message in tools_adjustOverallVolume (line 219) is quite specific (it mentions 'watching TV'), please consider changing it.

--------------------------------------------------
* CONTACTS

matteo.torcoli@iis.fraunhofer.de

info@audiolabs-erlangen.de

https://www.iis.fraunhofer.de/en/ff/amm.html

http://www.audiolabs-erlangen.de/fraunhofer 
