expe3000

A multimedia stimulus delivery system designed for experimental psychology and neuroscience tasks requiring millisecond-accurate timing and low-latency audio.

Stimuli are presented according to a fixed, predefined, schedule. Althought keypress events are saved, with a timestamp, the behavior of the program cannot be modified in real-time, e.g. you cannot provide immediate feedback. There is no notion of “trial”. This approach is suitable for fMRI/MEG/EEG experiments with rigid stimulus presentation schedules.

Features

The software is built with C and SDL3, providing

• Precise Timing: High-resolution timing loop with VSYNC synchronization and predictive onset look-ahead (pre-rendering).
• Low-Latency Audio: Uses a manual mixing callback to keep the audio hardware “warm” and minimize startup delay.
• Text Stimuli: Support for rendering text via TTF fonts.
• Unified Event Log: Records stimulus onsets, offsets, and user responses in a single CSV file with a comprehensive metadata header.
• Splashscreens: Optional start and end screens that wait for user input.
• Advanced Display Options: Supports multiple monitors, custom resolutions, logical scaling, and magnification factors.
• Auto-exit: Automatically concludes the experiment after the last stimulus or a specified total duration.

Note: This project is a work in progress, yet is already functionnal.

Quick Start with Examples

If you downloaded the expe3000 app, you can quickly test it:

• GUI Mode: Just double-click the expe3000 executable. A setup window will appear allowing you to select your experiment file (e.g. experiment.csv) and settings.
• Command Line mode:: See the example scripts:
  • Windows: run_example.bat
  • Linux/macOS: ./run_example.sh

  These scripts run the expe3000 executable with the included experiment.csv and assets folder.

Note: you can press Escape any time to interrupt the experiment and exit.

Usage

Interactive GUI Mode

If you run expe3000 without any command-line arguments, or if you use the --gui option, an Interactive Setup Window will open.

This window allows you to:

• Select Files: Use the “…” buttons to browse for your Experiment CSV, Stimuli Directory, and Output Results file.
• Set Resolution: Choose between standard experimental resolutions (800x600, 1024x768, 1366x1024).
• Toggle Features: Enable or disable the fixation cross and Fullscreen mode.
• Launch: Click START to begin the experiment once the CSV path is set.

Command Line

./expe3000 <experiment_csv> [options]

Options

• -h, --help: Show help message.
• -g, --gui: Force starting with the interactive GUI setup.
• --output [file]: Specify the output log file (default: results.csv).
• --stimuli-dir [dir]: folder containing stimuli files (absolute or relative to the current working directory).
• --no-fixation: remove the white center fixation cross.
• --fullscreen: Run in fullscreen mode on the selected display.
• --display [index]: Select monitor index (default: 0).
• --res [WxH]: Set resolution (default: 1920x1080).
• --scale [factor]: Apply a magnifying factor to images (default: 1.0).
• --start-splash [file]: Display a PNG splashscreen at the start and wait for a keypress.
• --end-splash [file]: Display a PNG splashscreen at the end and wait for a keypress.
• --total-duration [ms]: Minimum duration for the experiment loop to run.
• --dlp [path]: Path to the DLP-IO8-G device for triggers (e.g., /dev/ttyUSB0 or COM3).
• --font [file]: Specify the TTF font file for text stimuli (optional, defaults to searching fonts/ folder then system Arial/Liberation).
• --font-size [pt]: Set the font size in points (default: 24).
• --no-vsync: Disable VSYNC synchronization (not recommended for precise timing).

Example Command

./expe3000 experiment.csv --stimuli-dir assets --fullscreen

The input csv file must have four columns: timestamp_ms,duration_ms,type,content

Example (experiment.csv):

# timestamp, duration, type, content
1000,500,IMAGE,target.png
2000,0,SOUND,beep.wav
3000,1500,TEXT,Bye

Possible values for the type column: IMAGE, SOUND, TEXT

Note: Use 0 duration for sounds.

Output

Upon exiting, the program generates a log file (default: results.csv) containing:

• Metadata Header: Detailed session info (date, user, host, command, OS, driver, renderer, resolution).
• Event Log:
  • timestamp_ms: The time of the event relative to the start of the experiment.
  • event_type: IMAGE_ONSET, IMAGE_OFFSET, SOUND_ONSET, TEXT_ONSET, TEXT_OFFSET, or RESPONSE.
  • label: The stimulus content/file path or the name of the key pressed.

---

Installation

Precompiled Binaries

Pre-compiled binaries for Linux, macOS, and Windows are available in the Releases section of the GitHub project.

The pre-compiled binaries for Windows are self-contained and include all necessary DLLs.

For Linux and macOS, you need to have the SDL3 libraries installed on your system to run the program:

• MacOS. Install via Homebrew:

   brew install sdl3 sdl3_image sdl3_ttf
  

• Linux. Install via your package manager (if available): - Ubuntu 24.10+ / Debian Trixie+: sudo apt install libsdl3-0 libsdl3-image-0 libsdl3-ttf-0 - Fedora 41+: sudo dnf install sdl3 sdl3_image sdl3_ttf - Arch Linux: sudo pacman -S sdl3 sdl3_image sdl3_ttf

  Note: If your distribution does not yet provide SDL3 packages, you may need to compile them from source(INSTALL_Linux.md#3-option-b-compiling-sdl3-from-source-universal).

Compiling from scratch

For detailed installation and compilation instructions, please refer to the guide for your operating system:

• Linux
• macOS
• Windows

License

This code was developed by Christophe Pallier

The code is distributed under the GNU LICENSE GPLv3.

The files in the assets folder are NOT public domain. The images were created by Minye Zhan (https://www.linkedin.com/in/minye-zhan-3b414626/) who retains all rights to them. Do not reuse without permission from her.