A java program for running behavioural studies of music perception.

It allows you to examine a listener's perception of particular notes at particular points in a melody without stopping playback of the music. It uses MIDI files and can, optionally, present a clock whose hand counts down to indicate which note the participant should respond to.

It was designed to gather behavioural data (ratings and response times) on melodic expectation but the program has various options that make it quite flexible.




java Experiment <show clock?> <multiple> <n> <midi device> <scale length> <low anchor> <high anchor> <midi file directory> <instructions file> <results directory> <familiarity> <pleasantness> <questionnaire> <fullscreen> <debug>


<show clock?> specifies whether to show the clock (0 = no; 1 = yes).

<multiple> and <n> are integers: the clock runs for <n> time units before a probed event where the time unit is a multiple of the tatum as specified by <multiple>.

<midi device> is an integer specifying the midi device to use or a boolean String ("true" or "false") where "true" specifies that the program should use the default midi device and "false" specifies that the program should not use the default midi device, and should list the available midi devices on start up.

<scale length> is the number of levels of the rating scale and <low anchor> and <high anchor> are its high and low anchors respectively (e.g., "highly unexpected", "highly expected" with a scale length of 7).

<midi file directory> is the directory where the midi files are stored.

<instructions file> is an html file containing the instructions for the participant which will be displayed at the beginning of the experiment.

<results directory> is the directory where the results will be written.

If <familiarity> is 1 the participant is asked to rate the familiarity of each stimulus, if it is 0 the question is omitted.

If <pleasantness> is 1 the participant is asked to rate the pleasantness of each stimulus, if it is 0 the question is omitted.

if <questionnaire> is 1, experiment ends with a compulsory questionnaire on age, sex, musical training etc.; if it is 0 the questionnaire is optional.

If <fullscreen> is 1, the program will produce a fixed full screen GUI which can't be resized if the device allows this; if it is 0 then the program will produce a resizable full screen GUI.

if <debug> is 1, debugging information is printed to Standard Output, otherwise no debugging information is printed.


See https://code.soundsoftware.ac.uk/projects/mep/repository/entry/runExperiment.bat for an example.

To use in a study:

  1. put the relevant midi files in the directory specified by <midi file directory>. When playing the clock, the program can be a little fussy about the onsets and durations of the notes in the midi files being exact integer multiples of each other.
  2. edit pfilelist.txt and filelist.txt (also in <midi file directory>) to contain the midi files played in the practice and main blocks respectively: put one file on each line followed by a list of note numbers to probe with the visual clock (e.g., 1 = the first note).
  3. run the program, entering a participant ID. The results are written to files in the specified directory which must exist.
  4. responses can be given either using the mouse or using the numeric keys (except in the case of a scalelength of 2 where the keys 'q' and 'p' are used).
  5. create a set of instructions for the study in an html file.

Nota Bene: some guidelines for creating the files filelist.txt and pfilelist.txt:

  • the filenames may contain letters and numbers but must not start with a number;
  • only use a single space between filenames and note numbers and end each line directly after the last probe point - i.e with no trailing white space;
  • don't include any blank lines;
  • the last line containing a filename and probe points must terminate with a single newline at the end of the file.


The code is organised according to a MVC structure:

Model: Experiment.java
- FileList.java
- ProbeID.java
- MidiPlayer.java
- MelodyResults.java
- SubjectResults.java
- Block.java

View: ExperimentGui.java
- Clock.java
- InstructionsPanel.java
- StimulusPanel.java
- SubjectDataPanel.java
- InterBlockPanel.java

Controller: ExperimentController.java

- contains icons used for the GUI

Related publications

M. Pearce, M. H. Ruiz, J. Bhattacharya, G. Wiggins, and S. Kapasi, “Unsupervised statistical learning underpins computational, behavioural and neural manifestations of musical expectation,” NeuroImage, vol. 50, pp. 302–313, 2010.
[More Details] [BIBTEX] [URL (ext.)]