Name Last Update
dynamic_annotations Loading commit data...
matlabfiles Loading commit data...
prepare_clips Loading commit data...
LICENSE Loading commit data...
README.md Loading commit data...

Dynamic annotation web-tool

A simple web-based interface to dynamically annotate or "rate" audio/visual material.

Originally used in:

PNAS 2012

Code released under MIT License (see LICENSE file).


This is a series of php scripts for a webserver with linux+apache2+php5. The purpose of this tool is to have a web-interface to collect dynamic annotations during audio/video stimuli. The annotation is performed by moving the mouse to change the position of a slider (no need to click on the slider, moving the mouse is enough). The annotation interface is currently built in Adobe Flash and the source code of the player is available only on request. To test how it works, see: http://bml.becs.aalto.fi/dynamic_annotations/ Presentation of each video is randomized. After annotating one video, the interface automatically moves to the next video. If you have more than one dimension (e.g. we had valence and arousal), you need to have two separate experiments on two different URLs. Output files are stored as CSV files and saved directly on disk since often users do not have access to mysql. To increase security, an encrypted session key is generated and it expires after predefined lifetime (see below how to edit write.php).


1) The subfolder dynamic_annotations contains the php and flash code and is the one used for this web experiment: http://bml.becs.aalto.fi/dynamic_annotations/

2) The subfolder prepare_clips contains a small "how to" encode clips for the dynamic annotator using ffmpeg on linux.

3) The subfolder matlabfiles contains a simple script to read the ratings (needed to fix possible lags and missing samples; usually it happens when client's computer is lacking resources).


1) git clone https://git.becs.aalto.fi/eglerean/dynamicannotations.git

2) move the folder dynamic_annotations to your webserver (usually under /var/www/). Give it a meaningful name since it will be the name of the final URL e.g. http://yourserver.com/a_meaningful_name/

3) you need to edit the following files

  • settings.php
    • $type will stay to 1, other types are available but not documented for now
    • $path = the full directory path to the folder
    • $wwwlocation = the URL where your experiment will be under "case 1" you need to edit
    • $title Title of the experiment
    • $Nstimuli = number of stimuli
  • index.php
    • Edit the bit from class "introtext": a generic blurb about your study.
  • register.php
    • Edit the text for the explanation of what you will do, what data you collect and other privacy disclaimers, ethical permissions etc. Anything the user should know before actually registering for the experiment. Registration is anonymous. There is no way to track a user, unless you generate a code for her and send her the code.
  • welcome.txt
    • Edit description of the task and experiment. This appears after registration
    • Make your own demo image if you think it is useful (current image is in Finnish).
  • videoheader.php
    • Edit the task sentence: "Please annotate the amount of Valence in time by using the mouse + positive valence - negative valence". Replace it with your current task.
  • videoannotate.php
    • Change the encription key, now set to "njWInCoZ3ErGptKX8oR7g44mXSF61lXi". You can generate a new key at: http://randomkeygen.com/ (CodeIgniter Encryption Key)
  • write.php
    • Edit the decription key with the same key you have set in videoannotate.php
    • Expiry time is set to 30 minutes (line 31). If you have a video longer than 30 minutes, you need to increase the session expiry time.

4) edit the permissions of the subfolder subjects so that it is writable by the www user

  • chmod 777 subjects

5) make sure that the subfolder temp is also writable

  • chmod 777 subjects/temp
  • Temp keeps some information about the sessions.

6) Admin interface is under the URL of your experiment /admin/

  • To set the admin password edit file admin/admin.php line 5. Current password is "replacepassword".
  • Admin interface allows you to download the data. To allow that, you need to make sure admin/data folder is also disk writable
  • chmod 777 admin/data

15/07/2015 TODO

  • remove redundant code
  • test other options different than videorater
  • get rid of flash and convert tool to HTML5
  • add mysql support to avoid writing on disk


If you use this code, please cite:

Nummenmaa, L., Glerean, E., Viinikainen, M., Jääskeläinen, I.P., Hari, R., & Sams, M. (2012) Emotions promote social interaction by synchronizing brain activity across individuals. OA Proceedings of the National Academy of Sciences of United States of America doi: 10.1073/pnas.1206095109