Getting Started

Prerequisites

• Python 3.12
• ffmpeg (decoding MP3/M4A and stress tests)
• espeak-ng (only to build the synthetic dev dataset)

sudo apt-get install -y ffmpeg espeak-ng
pip install -r requirements.txt

Common tasks

Command	What it does
make dataset	Builds ./dataset (63 items, about 70 MB, deterministic)
make test	Runs 9 tests: determinism, localisation, error handling, API
make evaluate	Writes results/evaluation.md and .json
make stress	Writes results/stress.md and .json (takes several minutes)
make serve	Starts the API on http://127.0.0.1:8000

Analyze one recording

python -m arachne analyze my_speech.wav --transcript-file transcript.txt --reference gettysburg --out result.json

• The reference id is a folder dataset/references/<id>/ with reference.wav and reference.json.
• The transcript must contain the same words as the reference text; otherwise you get a transcript_mismatch error.
• Exit code is 0 for ok, 2 otherwise.

Add your own reference

1. Create dataset/references/<id>/reference.wav.
2. Create reference.json with id, title, transcript, audio, provenance, license. An optional reviewed alignment list (text, start, end per word) overrides automatic alignment.
3. Check the recording's reuse terms, not just the text's.

Configuration

All thresholds live in arachne/config.py. Every result stores the full config and a config_hash, so any result can be traced to the exact settings that produced it. Alignment backend: align.backend = proportional (default) or whisperx (untested).

Troubleshooting

Symptom	Cause / fix
transcript_mismatch	Transcript words differ from the reference text
alignment_failed / transcript_audio_mismatch_suspected	Audio doesn't match the text, or implausible speaking rate
insufficient_evidence	Very noisy audio or too little voiced speech; scores are withheld on purpose
Tests skipped	Run make dataset first