# EVS Mumble Bridge

Single-device UDP-to-Mumble bridge.

## Purpose

This service receives PCM16LE mono audio over UDP from one EVS client and forwards it as a dedicated Mumble user.

Deploy one container per EVS client so every device appears as its own Mumble user.

## Required ENV

- `MUMBLE_HOST`: Mumble server host/IP
- `MUMBLE_PORT`: default `64738`
- `MUMBLE_USERNAME`: username for this EVS client (example: `EVS-esp32-evs-1`)
- `MUMBLE_PASSWORD`: optional
- `UDP_LISTEN_PORT`: UDP port this client will stream to
- `MUMBLE_CERTFILE`: optional path to client certificate file for registration/auth
- `MUMBLE_KEYFILE`: optional path to private key file (if not bundled in cert)
- `MUMBLE_AUTO_CERT`: auto-generate self-signed cert/key when missing (default `true`)
- `MUMBLE_CERT_DIR`: target dir for auto-generated certs (default `/data/certs`)
- `MUMBLE_CERT_DAYS`: validity days for auto-generated cert (default `3650`)
- `MUMBLE_CERT_SUBJECT`: optional openssl subject, default `/CN=<MUMBLE_USERNAME>`
- `MUMBLE_CERT_AUTO_RENEW`: renew cert automatically at startup when close to expiry (default `false`)
- `MUMBLE_CERT_RENEW_BEFORE_DAYS`: renewal threshold in days (default `30`)

## Optional ENV

- `DEVICE_ID`: label for logs (default `esp32-evs-1`)
- `MUMBLE_CHANNEL`: move bot to channel name after connect
  - nested path is supported: `KHNM/EVS`
- `MUMBLE_CHANNEL_ID`: move bot by numeric channel ID (takes precedence over `MUMBLE_CHANNEL`)
- `MUMBLE_CONNECT_TIMEOUT_SEC`: wait time for ready state (default `30`)
- `MUMBLE_CONNECT_STRICT`: `true|false` (default `false`)
  - `false`: continue even if `is_ready()` does not become true in time
  - `true`: fail and reconnect on timeout
- `INPUT_SAMPLE_RATE`: default `16000`
- `MUMBLE_SAMPLE_RATE`: default `48000`
- `MUMBLE_FRAME_MS`: default `20`
- `MUMBLE_AUDIO_GAIN`: default `1.0`
- `BRIDGE_STATS_INTERVAL_SEC`: periodic runtime stats in logs, default `5` (`0` disables)
- `VAD_ENABLED`: enable speech gating before sending to Mumble (`true|false`, default `false`)
- `VAD_RMS_THRESHOLD`: RMS gate threshold on incoming PCM16 (default `700`)
- `VAD_OPEN_FRAMES`: consecutive voice frames to open gate (default `2`)
- `VAD_CLOSE_FRAMES`: consecutive silence frames to close gate (default `20`)
- `HPF_ENABLED`: enable high-pass/DC blocker to reduce low-frequency rumble (default `true`)
- `HPF_CUTOFF_HZ`: high-pass cutoff frequency (default `120.0`)
- `TX_BUFFER_MAX_MS`: maximum bridge TX buffer before dropping old audio to stop latency growth (default `800`)
- `TX_BUFFER_TARGET_MS`: buffer target after drop (default `300`)

## Example docker compose service

```yaml
services:
  evs-mumble-esp32-1:
    image: git.khnm-zimmerling.de/kai/evs-mumble-bridge:latest
    container_name: evs-mumble-esp32-1
    restart: unless-stopped
    ports:
      - "5004:5004/udp"
    environment:
      DEVICE_ID: "esp32-evs-1"
      UDP_LISTEN_HOST: "0.0.0.0"
      UDP_LISTEN_PORT: "5004"
      INPUT_SAMPLE_RATE: "16000"
      MUMBLE_HOST: "10.100.3.50"
      MUMBLE_PORT: "64738"
      MUMBLE_USERNAME: "EVS-esp32-evs-1"
      MUMBLE_PASSWORD: ""
      MUMBLE_CERTFILE: "/run/secrets/mumble_client.crt"
      MUMBLE_KEYFILE: "/run/secrets/mumble_client.key"
      MUMBLE_AUTO_CERT: "false"
      MUMBLE_CHANNEL: "Bots"
```

For automatic self-signed cert generation when files are missing:

```yaml
      MUMBLE_AUTO_CERT: "true"
      MUMBLE_CERT_DIR: "/data/certs"
      MUMBLE_CERT_DAYS: "3650"
      MUMBLE_CERT_AUTO_RENEW: "true"
      MUMBLE_CERT_RENEW_BEFORE_DAYS: "30"
      # optional:
      # MUMBLE_CERT_SUBJECT: "/CN=EVS-esp32-evs-1"
```

## Persistent cert volume (recommended)

If `MUMBLE_AUTO_CERT=true`, mount `/data` as a persistent volume.
Otherwise a new cert may be generated after redeploy and Mumble can reject login for an already-registered username.

Example:

```yaml
services:
  evs-mumble-esp32-1:
    image: git.khnm-zimmerling.de/kai/evs-mumble-bridge:latest
    restart: unless-stopped
    ports:
      - "5004:5004/udp"
    environment:
      DEVICE_ID: "esp32-evs-1"
      MUMBLE_HOST: "10.100.3.50"
      MUMBLE_PORT: "64738"
      MUMBLE_USERNAME: "EVSClient1"
      MUMBLE_AUTO_CERT: "true"
      MUMBLE_CERT_DIR: "/data/certs"
      MUMBLE_CERT_AUTO_RENEW: "true"
      MUMBLE_CERT_RENEW_BEFORE_DAYS: "30"
      UDP_LISTEN_HOST: "0.0.0.0"
      UDP_LISTEN_PORT: "5004"
      INPUT_SAMPLE_RATE: "16000"
    volumes:
      - evs_mumble_esp32_1_data:/data

volumes:
  evs_mumble_esp32_1_data:
```

If the user is already registered with another cert, either:
- provide the original `MUMBLE_CERTFILE`/`MUMBLE_KEYFILE`, or
- use a new `MUMBLE_USERNAME`, or
- re-register that username on the Mumble server.