# experiment_listening

Bilateral neuroscience listening experiment designed to measure brain responses to naturalistic speech. Subjects listen to audio stimuli while fixating a cross, with timing synchronized via photodiode triggers and serial port markers (for EEG/fMRI).

## Experiment sessions

### Day 1 — Le Petit Prince (`exp_listening_lpp_fr.py`)

Subjects listen to <15 chapters of the French audiobook *Le Petit Prince* (read by Xavier Perez), presented sequentially. Each chapter is followed by an ITI and a rest period.

### Day 2 — Optimized stories (`exp_listening_stories_fitted.py`)

Subjects listen to 32-34 short optimized narratives, split into 3 groups (1-12, 13-24, 25-32) and shuffled independently within each group. Audio files are pre-loaded into memory and normalized to 24 kHz before playback. A rest period is offered every 2 stories.

## Experiment flow

1. Welcome screen with instructions (press Space to advance)
2. Baseline fixation period (default 30 s)
3. Start screen
4. For each audio stimulus:
   - Serial trigger sent (if port available)
   - Audio plays while subject fixates the cross (photodiode active)
   - Inter-trial interval (default 2 s)
   - Rest screen (every chapter for Day 1, every 2 stories for Day 2)
5. Final baseline fixation
6. End screen

## Controls

- **Space** — advance through instruction screens
- **c** — skip the current screen/audio
- **Escape** — abort the experiment

## Requirements

- Python ≥ 3.9
- PsychoPy **2024.2.5** (pinned — see `requirements.txt`)
- psychtoolbox — precise audio timing
- numpy
- pyserial — serial port triggers
- pydub — audio conversion (Day 2 only); `wave` is in the standard library

All versions are pinned in `requirements.txt`.

## Install

```bash
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

On Linux, you may also need system libraries for PsychoPy and pydub
(`libportaudio2`, `libasound2-dev`, `libgl1-mesa-glx`, `libsdl2-2.0-0`, `ffmpeg`).

## Hardware configuration

Hardware defaults (resolution, frame rate, serial port, photodiode position, monitor name) are defined in `HARDWARE_DEFAULTS` in `exp_common.py`. Each experiment script creates a `config` dict that overrides only the values that differ (e.g. the serial port name). To adapt to a new setup, edit the `config` line at the top of the experiment script or change the defaults in `exp_common.py`.

Current defaults:
- 1920x1080 display at ~60 Hz
- Serial port for trigger output (COM5 for Day 1 / COM3 for Day 2)
- Monitor configured as `DellExperiment` in PsychoPy Monitor Center (20 cm viewing distance)
- Photodiode square at position [910, 490] (bottom-right for 1920x1080)

## Directory structure

```
experiment_listening/
  exp_common.py                   # Shared utilities (display, audio, setup)
  exp_listening_lpp_fr.py         # Day 1 experiment script
  exp_listening_stories_fitted.py # Day 2 experiment script
  lpp_fr/                         # MP3 audiobook chapters (reference copies)
../data_experiments/
  audio/
    lpp_fr/                       # WAV chapters for Day 1
    optimized_stories_pat_6684/   # WAV stories for Day 2
../logs/                          # Timestamped log files
```
