# Farsi Uvular Production

A speech production task where participants listen to Farsi uvular consonant
sounds and record their own pronunciation attempts. Each of the 6 trials has
three steps: listening to the target Farsi sound, recording a pronunciation
attempt via microphone, and reviewing the recording. The task begins with a
microphone check that includes device selection and a real-time volume meter.
Trial data can be exported as CSV and all recordings downloaded as a single
ZIP archive for offline analysis. Part of the NCCR Evolving Language task
library (NEBULA101) at the University of Geneva.

## Requirements

- A modern browser with support for the MediaRecorder API and
  `getUserMedia()` (tested on current Chrome, Firefox, Edge and Safari).
- A working **microphone**. The task requires microphone permission — grant
  access when the browser prompts.
- Microphone access is only granted on `https://` origins or on
  `http://localhost`. Opening `index.html` via `file://` will fail.
- Python 3 (only for the bundled dev server script) or any other static
  file server.
- The task pulls JSZip from a CDN at runtime
  (`cdnjs.cloudflare.com/ajax/libs/jszip/3.10.1`) for the ZIP download, so
  an internet connection is needed to save recordings.

## Install

```bash
git clone <repo-url> farsi-uvular-production
cd farsi-uvular-production
```

There are no build steps and no npm dependencies — the task is plain
HTML/JS with four local scripts under `js/` and audio stimuli under
`stimuli/`.

## Run

Serve the folder over HTTP from `localhost` (required for mic access):

```bash
./serve.sh
# → http://localhost:8080
```

`serve.sh` simply runs `python3 -m http.server 8080` from the repo root.
Any equivalent static server works, e.g. `npx http-server .` or
`php -S localhost:8080`.

In production the bundle is served from
`library.nccr-ttf-ddg.ch/static/tasks/farsi-uvular/index.html` (see
`run-site` in `task.json`); GitLab CI builds `dist/` and `task.zip`
from all tracked files except `task.json` and `.gitlab-ci.yml`
(see `.gitlab-ci.yml`).

## Controls

The task is fully mouse-driven via on-screen buttons:

- **Continue to Mic Check** — advance from the instructions.
- **Select Microphone** — dropdown of available input devices.
- **Record Test** / **Stop** — capture a short test clip and play it back
  to verify the microphone.
- **Microphone Ready — Start Task** — enabled once a test recording is made.
- **Play Target Sound** — plays the trial stimulus; recording starts
  automatically in parallel.
- **Stop Recording** — ends the trial recording and enables playback.
- **Next Trial** — moves to the next trial (enabled only after recording).
- **Download Trial Data (CSV)** / **Download All Recordings (ZIP)** — on
  the results screen.

A language switcher on the instructions screen toggles UI between
English, French and German (see `js/lang-switcher.js`).

## Outputs

Local data export only (`localDataExport: true` in `task.json`). No data
is sent to a server.

- **CSV** of per-trial metadata with columns:
  - `trial_number` — trial index (1-6)
  - `stimulus_file` — WAV file played as target
  - `recording_filename` — filename of the participant's recording
  - `recording_duration_ms` — length of the recording, in milliseconds
  - `lang` — UI language at the time of the trial
- **ZIP archive** of WebM recordings, one per trial (named
  `farsi-uvular-recordings.zip`).

Design: 6 trials, each presenting one of the stimuli in `stimuli/`
(`1_ghaza_gaza.wav` … `6_ghAli_gali.wav`). Derived measures — expert
ratings of pronunciation accuracy and acoustic analysis of uvular
articulation — are produced offline from the downloaded recordings.

## Files

- `index.html` — full UI, inline CSS, task logic, translations and the
  `TRIALS` list.
- `js/audio-recorder.js` — `AudioRecorder` class wrapping `getUserMedia`,
  `MediaRecorder`, volume metering and ZIP export.
- `js/data-collector.js` — `DataCollector` class for in-memory rows and
  CSV download.
- `js/lang-switcher.js` — language picker (EN/FR/DE), `t()` and `tpl()`
  helpers, `langchange` event.
- `js/timer.js` — timer utility (loaded but not used by the main flow).
- `stimuli/*.wav` — six Farsi uvular stimulus recordings.
- `serve.sh` — launches a local static server on port 8080.
- `task.json` — library metadata (id 23, engine `html`, contact, domains,
  variables, outputs).
- `.gitlab-ci.yml` — CI that zips the folder into `task.zip` on tag or
  default-branch push.

## Contact

- Contact person: **Narly Golestani** — narly.golestani@unige.ch
- Lab: Brain and Language Lab — http://brainandlanguagelab.org/
- Contributor: Narly Golestani (conceptualization, supervision),
  University of Geneva, ORCID `0000-0001-7388-4714`.
