Initial: Standalone mixer app with MixerPage, scene management, WS proxy

2026-06-21 00:03:42 -04:00
commit b8a9f06734
7146 changed files with 1684613 additions and 0 deletions
@@ -0,0 +1,127 @@
+# OPLabs Mixer App
+
+A standalone mixer application that connects to PiPedal (at `192.168.0.245:8080`) via WebSocket to discover and display OPLabsBandChannel and OPLabsBandBus LV2 plugin instances loaded on the pedalboard.
+
+## Architecture
+
+```
+Browser (React SPA)  ←→  FastAPI Backend (localhost:8081)  ←→  PiPedal (192.168.0.245:8080)
+        │                        │
+        └── WS /ws/pipedal       └── WS /pipedal (upstream)
+        └── REST /api/discover   └── REST proxied via WS
+```
+
+- **Backend:** FastAPI on port 8081 — serves the SPA, proxies WebSocket connections to PiPedal, and provides a REST API for plugin discovery.
+- **Frontend:** Vite + React + TypeScript — connects to the local WS proxy and shows discovered OPLabs plugin instances with their parameter values.
+
+## Prerequisites
+
+- Python 3.10+
+- Node.js 18+
+- PiPedal running at `192.168.0.245:8080` with OPLabs plugin instances loaded on the pedalboard
+
+## Setup
+
+### Backend
+
+```bash
+cd backend
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### Frontend
+
+```bash
+cd frontend
+npm install
+```
+
+## Running
+
+### Development Mode
+
+Start both backend and frontend:
+
+```bash
+# Terminal 1: Backend
+cd backend
+source venv/bin/activate
+python app.py          # runs on port 8081
+
+# Terminal 2: Frontend (with hot-reload)
+cd frontend
+npm run dev            # runs on port 5173, proxies API/WS to 8081
+```
+
+Then open http://localhost:5173 in your browser.
+
+### Production Mode
+
+Build the frontend and serve from the backend:
+
+```bash
+cd frontend
+npm run build
+
+# Then start the backend (it will serve the built SPA):
+cd ../backend
+source venv/bin/activate
+python app.py
+
+# Open http://localhost:8081
+```
+
+Or use the convenience script:
+
+```bash
+./start.sh
+```
+
+## WebSocket Protocol
+
+The app uses PiPedal's native WebSocket protocol:
+
+- Messages are JSON arrays: `[{"message": "msgName", "replyTo": N}, optionalBody]`
+- Replies: `[{"reply": N, "message": "msgName"}, optionalBody]`
+- The browser connects to `ws://localhost:8081/ws/pipedal`, which proxies to PiPedal's `ws://192.168.0.245:8080/pipedal`
+
+## REST API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/ping` | GET | Health check + connection status |
+| `/api/discover` | GET | Discover OPLabs plugin instances from current pedalboard |
+| `/api/plugins` | GET | List all available plugins from PiPedal |
+
+## OPLabs Plugin URIs
+
+- OPLabsBandChannel: `http://ourpad.casa/plugins/oplabs-band-channel`
+- OPLabsBandBus: `http://ourpad.casa/plugins/oplabs-band-bus#`
+
+## Project Structure
+
+```
+~/projects/oplabs-mixer-app/
+├── backend/
+│   ├── app.py              # FastAPI app (routes, SPA serving, WS proxy)
+│   ├── ws_proxy.py         # PiPedal WebSocket proxy client
+│   └── requirements.txt
+├── frontend/
+│   ├── package.json
+│   ├── vite.config.ts
+│   ├── tsconfig.json
+│   ├── index.html
+│   └── src/
+│       ├── main.tsx
+│       ├── App.tsx
+│       ├── App.css
+│       ├── hooks/
+│       │   └── usePiPedalWS.ts
+│       └── components/
+│           ├── ConnectionStatus.tsx
+│           └── PluginList.tsx
+├── README.md
+└── start.sh
+```