initial commit

README.md

@@ -0,0 +1,171 @@
+# audioserver — Docker Compose stack
+
+Runs on the **Audio Server (Pi 5)**.  
+Combines Snapserver, Mopidy, and the audiocontrol web frontend in one stack.
+
+```
+internet / LAN
+    │
+    ▼
+┌───────────────────────────────────────┐  Docker network
+│  frontend (Nginx :80)                 │
+│    /api/hifiberry/ ──────────────────────────→ BeoCreate Pi :5005
+│    /api/mopidy/rpc → mopidy:6680     │
+│    /ws/mopidy      → mopidy:6680     │
+│    /ws/snapcast    → snapserver:1705 │
+├───────────────────────────────────────┤
+│  mopidy (:6680, :6600 MPD)           │──→ /audio/mopidy.fifo ─┐
+├───────────────────────────────────────┤                         │
+│  snapserver (:1704, :1705, :1780)    │←── /audio/mopidy.fifo ─┘
+│                                       │←── /audio/turntable.fifo ← host service
+└───────────────────────────────────────┘
+```
+
+---
+
+## Prerequisites
+
+```bash
+sudo apt install docker.io docker-compose-plugin
+sudo usermod -aG docker $USER   # logout & back in
+```
+
+---
+
+## One-time setup
+
+### 1. Clone / copy this directory to the Pi 5
+
+```bash
+scp -r audioserver/ pi@audioserver.local:/opt/audiocontrol/stack
+cd /opt/audiocontrol/stack
+```
+
+### 2. Copy the React source
+
+The `audiocontrol/` directory (from `audiocontrol.tar.gz`) must sit next to `docker-compose.yml`:
+
+```bash
+tar -xzf audiocontrol.tar.gz -C /opt/audiocontrol/stack/
+```
+
+### 3. Configure
+
+```bash
+cp .env.example .env
+nano .env    # set BEOCREATE_HOST, TZ, HIFIBERRY_CARD, etc.
+```
+
+### 4. Create audio FIFOs
+
+```bash
+sudo bash scripts/init-pipes.sh
+```
+
+### 5. Install the turntable capture service
+
+```bash
+sudo cp scripts/turntable-capture.sh /opt/audiocontrol/scripts/
+sudo chmod +x /opt/audiocontrol/scripts/turntable-capture.sh
+sudo cp scripts/turntable-capture.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now turntable-capture
+```
+
+---
+
+## Start the stack
+
+```bash
+docker compose up -d --build
+docker compose logs -f          # watch startup
+```
+
+---
+
+## Service ports
+
+| Service     | Port  | Purpose                        |
+|-------------|-------|-------------------------------|
+| Frontend    | 80    | Web UI + API proxy             |
+| Snapserver  | 1704  | Snapcast audio streaming       |
+| Snapserver  | 1705  | JSON-RPC WebSocket             |
+| Snapserver  | 1780  | Snapcast HTTP API              |
+| Mopidy      | 6600  | MPD (optional, host access)    |
+
+Mopidy's HTTP port (6680) is **not** exposed on the host — accessed only via the frontend Nginx proxy.
+
+---
+
+## Updating
+
+```bash
+# Pull latest changes, rebuild, restart
+docker compose down
+docker compose up -d --build
+```
+
+## Mopidy local library scan
+
+```bash
+docker compose exec mopidy mopidy local scan
+```
+
+## Useful commands
+
+```bash
+docker compose ps                          # service status
+docker compose logs snapserver            # snapserver logs
+docker compose exec mopidy bash           # shell into mopidy
+docker compose restart snapserver         # restart one service
+```
+
+---
+
+## Audio routing
+
+```
+Turntable
+  → HiFiBerry HAT (ALSA hw:0)
+  → turntable-capture.sh (host)
+  → /opt/audiocontrol/pipes/turntable.fifo
+  → Snapserver (Turntable stream)
+  → BeoCreate Pi (Snapclient)
+
+Mopidy
+  → GStreamer filesink
+  → /opt/audiocontrol/pipes/mopidy.fifo
+  → Snapserver (Mopidy stream)
+  → BeoCreate Pi (Snapclient)
+```
+
+Both are 48 kHz / 16-bit / stereo to match the BeoCreate DSP profile.
+
+---
+
+## Troubleshooting
+
+**Frontend shows "unreachable" for BeoCreate DSP**  
+Check that `BEOCREATE_HOST` in `.env` resolves from the Pi 5. Test:
+```bash
+curl http://beocreate.local:5005/api/volume
+```
+
+**No audio from turntable**  
+Check the ALSA card name in `.env`:
+```bash
+arecord -l   # lists available capture devices
+```
+
+**Mopidy FIFO blocks on startup**  
+Snapserver must open the FIFO before Mopidy can write to it.  
+The `depends_on: snapserver` in docker-compose.yml handles this, but if Snapserver is slow, restart Mopidy:
+```bash
+docker compose restart mopidy
+```
+
+**Snapclient on BeoCreate can't connect**  
+Port 1704 must be reachable from the BeoCreate Pi. Check firewall:
+```bash
+sudo ufw allow 1704/tcp   # if ufw is active
+```