# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**psychosnd** is a Python CLI tool for analyzing sound latencies in PsychoPy experiments. It wraps the `prespy` library to extract and compare port trigger timings with sound recordings.

CLI entry point: `psych-scla <soundfile> <logfile>`

## Development Setup

Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then:

```bash
uv sync --group dev
```

## Common Commands

```bash
# Run the CLI
uv run psych-scla <soundfile> <logfile>
uv run psych-scla --help

# Update the lockfile after editing pyproject.toml
uv lock

# Build distribution artifacts
uv build

# Publish to PyPI
uv publish
```

## Architecture

The package lives under `src/psychosnd/` (src-layout):

- **`scla.py`** — Core analysis logic. The `scla()` function loads the PsychoPy log, calls `prespy.sndan.extract_sound_events()` on the audio file, validates that event counts match across log/port/sound, then computes latencies (Port_to_Snd = snd - code) and timing stats. The `datasets` dict defines the output structure.
- **`psychcsv.py`** — Thin wrapper around `csv.DictReader` for loading PsychoPy CSV log files. `load()` returns a `PsychoPyCSV` instance with an `events` list.
- **`__main__.py`** — Argparse CLI wiring. Calls `scla()` and formats the statistics report (mean/min/max/stddev). Handles `ExtractError` with exit code 65.
- **`__about__.py`** — Single source of truth for version and package metadata.

The primary external dependency is `prespy` (>=0.0.11), which provides the actual sound analysis algorithms (`sndan.extract_sound_events`, `sndan.timing`, `sndan.stdStats`).

## Notes

- The `test/` directory exists but contains no tests — the project has no test suite.
- Dependencies and build metadata are defined in `pyproject.toml` (hatchling backend). Use `uv lock` to regenerate `uv.lock`.
