# Church Acoustic Suite

A purpose-built acoustic analysis tool for PBCC Universal Hall distributed speaker systems. Models the MS6 ceiling speaker layout, Haas window compliance, and off-axis coverage — then connects to Room EQ Wizard (REW) for live measurement analysis via a local LLM (Ollama) or Claude API.

## What it does

- **Hall geometry engine** — models the dished floor (bowl), flat ceiling, and all seating rows including corner zones; computes floor rise, ear-to-ceiling clearance, and absolute heights per row
- **Coverage analysis** — slant distance, propagation delay, Haas window status, off-axis angle, and estimated SPL at ear for every speaker ring × seating row combination
- **Flutter echo analysis** — calculates flutter fundamental frequencies and harmonics across the hall; flags speech-band risk zones
- **REW integration** — connects to REW's local API (port 4735) to fetch frequency response and measurement data
- **AI analysis** — sends geometry + coverage + REW data to Ollama (local) or Anthropic Claude for actionable acoustic recommendations tuned to this hall type

## Prerequisites

- **Room EQ Wizard** with API server enabled ([REW API docs](https://www.roomeqwizard.com/help/help_en-GB/html/api.html))
- **Ollama** (recommended) or an Anthropic API key
- **Docker** (recommended) — or Node.js ≥ 18 for local development

## Docker (recommended)

The easiest way to run the app. Docker handles the Node.js build inside the container — no local Node.js required.

```bash
# Build and start (runs tests during build)
docker compose up --build

# Open in browser
# http://localhost:3000
```

REW (port 4735) and Ollama (port 11434) are called from your browser, not the container, so they reach your local machine as normal `localhost` addresses.

To stop:

```bash
docker compose down
```

## Local development (Node.js)

```bash
npm install

# Development server with hot reload
npm run dev

# Run tests
npm test

# Run tests once (CI)
npm run test:run

# Test coverage report
npm run test:coverage

# Production build
npm run build
```

## REW setup

1. Open REW → Preferences → API and enable the API server (default port 4735)
2. Alternatively launch REW with the `-api` flag
3. The app connects to `http://127.0.0.1:4735` by default — change in Settings if needed
4. REW's API is localhost-only by design; the app and REW must run on the same machine

## Ollama setup

Ollama requires CORS to be enabled for the browser to reach it:

```bash
OLLAMA_ORIGINS=* ollama serve
```

Pull a model before starting (examples):

```bash
ollama pull llama3.2
ollama pull mistral
ollama pull qwen2.5
```

The Settings tab lets you configure the host, port, and fetch available models dynamically.

## Hall geometry

The geometry engine models the confirmed PBCC Universal Hall (8-row) dimensions:

| Parameter | Value | Source |
| --------- | ----- | ------ |
| Seating plan | 20,914 × 20,914 mm | SK-303 drawing |
| Row 1 front edge | 2,210 mm from centre | SK-303 |
| Row pitch (FFL–FFL) | 883 mm | SK-303 |
| Row 8 back face | 8,411 mm | SK-303 |
| Back aisle | 2,046 mm | Derived: 10,457 − 8,411 |
| Corner rows | 4 rows, 883 mm pitch | Site survey |
| Ceiling | **FLAT** at 4,300 mm above centre datum | Survey |
| Floor at centre | 0 mm (lowest point, communion table) | Survey |
| Floor at row 8 back | +700 mm (dish rise) | Survey: 4,300 − 3,600 = 700 |
| Floor-to-ceiling at row 8 | 3,600 mm | Confirmed survey |
| Corner zone ceiling | 2,950 mm floor-to-ceiling (structural drop) | Survey |

**Key rule:** The ceiling is a single flat horizontal plane. The floor rises (dished bowl) from 0 mm at the communion table zone outward to 700 mm at row 8. Floor-to-ceiling clearance therefore *decreases* toward the perimeter.

## Speaker layout

All speakers are flush-mounted in the 600 mm × 600 mm acoustic ceiling tile grid (no drop rods). Power settings per Dudley Wilkin's 2010 Aberdeen 8-row hall proposal:

| Ring | Count | Radius | Power | Coverage target |
| ---- | ----- | ------ | ----- | --------------- |
| Centre | 1 | 0 mm | 6 W | Rows 1–3 |
| Inner ring | 8 | 5,720 mm | 8 W | Rows 4–7 |
| Outer ring | 8 | 8,600 mm | 4 W | Row 8 + back aisle |
| Corner | 8 (2 per corner) | 10,310 mm | 4 W | Corner seating |

## MS6 speaker

The MS6 is a two-driver ceiling speaker designed by Dudley Wilkin for this hall type:

- **LF driver**: Visaton FRS8M — 8 Ω, 30 W, 88 dB/1 W/1 m, response 100 Hz–20 kHz
- **HF driver**: Visaton G20SC — 8 Ω, 20 mm soft dome, 88 dB/1 W/1 m, response 1,200 Hz–30 kHz
- **Crossover**: MIDAS MR12 active crossover — LF cut at 2,792 Hz, HF starts at 3,225 Hz
- **Gap**: 433 Hz gap centred at 3 kHz (less than 1/5 octave — inaudible)
- **Purpose of gap**: Eliminates horizontal interference lobes that conventional crossovers produce at the 2–5 kHz consonant frequencies (P, T, F, S) critical for speech intelligibility
- **Coverage**: 55° off-axis — near-perfect circular polar response at both 30° and 55°

Signal chain: `Mono mix → MIDAS MR12 Ch1 (TEQ room EQ) → Bus 1/2 → AUX1 LF amp + AUX2 HF amp → 100 V line → transformers → speakers`

## Anti-phasing

Adjacent speaker segments are wired in anti-phase. This creates acoustic null lines along aisle centrelines, so each listener receives sound from only one speaker. This is the primary intelligibility mechanism — it dramatically improves gain-before-feedback and removes inter-speaker comb filtering.

**Measurement note**: When setting EQ, select the main ring with anti-phase enabled and disconnect the centre speaker. A microphone placed under any main ring speaker will then pick up only that speaker. (Dudley Wilkin — GEQ setup method, September 2014)

## EQ setup procedure (summary)

Full method: Dudley Wilkin, September 2014

1. Only one speaker active — main ring with anti-phase, centre disconnected
2. Mic at 1,000 mm on-axis below the speaker
3. Set all tone controls and EQ to flat
4. **Coarse**: pink noise through system, TrueRTA at 1/3-octave, adjust EQ to flat
5. **Fine**: frequency scan in TrueRTA at 1/24-octave, remove peaks, fill troughs
6. Save and photograph all settings — never adjust EQ by ear
7. Adjust tone controls by voice: reduce treble to tame "S" sibilance, minimal bass for natural sound

## Measurement protocol

**Only impulse-based measurement is valid** for this speaker system. Continuous sound (pink noise, SLM readings) is invalid because:

- Each speaker covers only one zone (anti-phase nulls elsewhere)
- A standard SLM picks up all speakers simultaneously — the result is meaningless
- RT60 is only valid when measured through the live system with all speakers operating

Use REW or ARTA with an impulse window. The minimum measurement window required is **10 ms** — this requires sufficient ceiling clearance (at minimum 2,000 mm microphone distance from the speaker).

Reference: Dudley Wilkin — "Loudspeaker Positions and Continuous Sound"

## Haas window

| Status | Delay beyond primary | Meaning |
| ------ | -------------------- | ------- |
| Primary | 0 ms | Nearest speaker to this row |
| OK | 0–10 ms | Acceptable — fused with primary |
| Warn | 10–30 ms | Colouration risk |
| Danger | > 30 ms | Distinct echo — intelligibility impact |

## Project structure

```text
church-acoustic-suite/
├── src/
│   ├── main.jsx               # React entry point
│   ├── App.jsx                # All tabs and UI components
│   ├── geometry.js            # Pure acoustic geometry functions (testable)
│   ├── constants.js           # Hall defaults, speaker defaults, settings defaults
│   ├── palette.js             # Dark-theme colour constants
│   └── __tests__/
│       └── geometry.test.js   # 35+ unit and integration tests
├── documents/                 # Reference documents (Dudley Wilkin)
├── church-acoustic-suite.jsx  # Original monolithic prototype (reference)
├── index.html
├── vite.config.js
├── package.json
└── CLAUDE.md                  # Codebase reference for AI assistants
```

## Background

This tool is informed by 40+ years of acoustic engineering documentation for the PBCC Universal Hall format by Dudley Wilkin, covering:

- Speaker system evolution (1970s corner columns → 1982 ceiling ring → 1986 anti-phasing → 2010 MS6 layout)
- The MS6 crossover innovation eliminating horizontal interference lobes
- The Perth UK trial confirming the centre speaker alone covers rows 1–6
- The case against continuous-sound measurement methods for this hall type