steeplestack/zonal-controller repository overview

⁠SteepleStack Zonal Controller

⁠Real-Time SPL Monitoring & Automated Gain Control for Church Venues

Zonal Controller is a professional-grade sound pressure level (SPL) monitoring and automated gain management system designed for houses of worship. It provides live SPL tracking across multiple zones, integrated Q-SYS gain control, and a single-pane-of-glass dashboard for both volunteer operators and AV professionals.

⁠What It Does

• Real-time SPL monitoring — Captures dBA readings from USB microphones on Raspberry Pi monitors
• Automated gain control — Maintains volume within operator-defined thresholds via Q-SYS integration
• Multi-zone support — Monitor and control separate audio zones independently
• Event-driven architecture — MQTT-based communication between monitors, controller, and dashboard
• Unified dashboard — Web-based interface for live monitoring, zone configuration, override controls, and event logging

⁠Key Features

✓ Live SPL dashboard with unambiguous status indicators (safe / approaching / over limit)
✓ Per-zone threshold & gain configuration with override schedules
✓ Two-tier interface — simple readout for volunteers, deep controls for AV integrators
✓ Settings import/export — Backup and clone zone configurations as JSON
✓ User management & role-based access — Create custom roles with granular permissions
✓ Event logging — Audit trail of all threshold breaches and manual overrides
✓ OS-aware setup — Automated guide for monitor deployment on Mac, Windows, or Linux
✓ WCAG AA+ accessibility — High-contrast design optimized for dim sanctuary environments

⁠Architecture

• Controller (Node.js) — Central service orchestrating MQTT traffic and Q-SYS API calls
• Dashboard (Next.js) — Real-time web interface for monitoring and administration
• Monitor (Node.js) — Runs on Raspberry Pi; captures SPL and publishes to MQTT
• License Server — Validates product licenses
• MQTT broker — Real-time message backbone

⁠Use Cases

• Live worship services — Maintain consistent volume and prevent feedback
• Multi-venue networks — Monitor and manage audio across campus locations
• Compliance reporting — Audit log for sound level management policies
• Training & setup — Intuitive interface for non-technical AV volunteers

⁠Quick Start

docker run -d \
  --name zonal-controller \
  -p 8080:8080 \
  -e NODE_ENV=production \
  -e MQTT_HOST=<your-mqtt-host> \
  -e MQTT_PORT=1883 \
  steeplestack/zonal-controller:latest

Visit http://localhost:8080⁠ to access the dashboard.

⁠Documentation

Build Guide⁠

Production Deployment⁠

Release Notes⁠

License

See LICENSE file in repository.