# AURA LIVE — Voice Provider Setup (LiveKit)

Aura Live uses **LiveKit** (WebRTC SFU) for real voice chat. The server mints short-lived
room tokens after checking authentication + room membership; the client (web/mobile) connects
to LiveKit directly. No provider credentials ever reach the client bundle.

## Option A — LiveKit Cloud (fastest)
1. Sign up at https://cloud.livekit.io and create a project.
2. Copy the WSS URL, API Key and Secret.
3. Fill `.env` in the project root (or `server/.env`):
```ini
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxx
LIVEKIT_API_SECRET=your-secret
LIVEKIT_PUBLIC_URL=wss://your-project.livekit.cloud
```
4. Restart the server. The party-room banner disappears and the mic works.

## Option B — Self-hosted LiveKit
```bash
docker run -d --name livekit \
  -p 7880:7880 -p 7881:7881/udp -p 7882:7882/udp \
  -e LIVEKIT_KEYS="aurakey: aurasecret-change-me" \
  livekit/livekit-server --dev
```
Then:
```ini
LIVEKIT_URL=ws://YOUR_SERVER_IP:7880
LIVEKIT_API_KEY=aurakey
LIVEKIT_API_SECRET=aurasecret-change-me
LIVEKIT_PUBLIC_URL=ws://YOUR_SERVER_IP:7880
```
(Use WSS behind TLS in production — put LiveKit behind Caddy/Nginx with a cert.)

## How the flow works
1. `POST /api/v1/rooms/:id/voice-token` → server checks: active user, room live, membership, seat/speaker permission.
2. Server returns `{ token, wsUrl, roomName, canPublish }` — token TTL 2h, publish allowed only for seated speakers/host/mods.
3. Web client (`livekit-client`) / Android (`@livekit/react-native`) connects, publishes mic (after permission), subscribes to all audio tracks.
4. Active-speaker events drive the glowing seat rings; mute state is local; reconnection is handled by the SDK.

## Without credentials (graceful degradation)
- The endpoint returns **503 `VOICE_NOT_CONFIGURED`** with a clear message.
- Clients show an amber "voice server not configured" banner; chat, gifts, games and presence keep working.
- The server never fakes a "live" voice room — honesty over demo effects, as required.

## Diagnostics
- Admin → System Health shows the LiveKit configuration status.
- Server log prints the voice provider status at boot.