EVS-Embedded-Voice-System/mumble-bridge/README.md

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)

Example docker compose service

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:

      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"