WebcamServer

Ein schlanker, selbst gehosteter Kamera-Server für USB-Webcams. Nimmt eine oder mehrere UVC-Kameras auf, encodiert sie per ffmpeg zu H.264 und liefert die Streams über MediaMTX als RTSP, HLS und WebRTC aus – inklusive einer kleinen Web-Oberfläche, mit der sich Kameras, Auflösung und Bildrate per Dropdown verwalten lassen.

Haupteinsatzzweck: Livebild der Kamera in Mainsail (ein 3D-Drucker-Interface) einbinden, aber auch VLC oder jeder RTSP/HLS-fähige Player funktioniert.

Features

• Web-Oberfläche unter Port 8088: Live-Ansicht aller Kameras + URLs zum Einbinden.
• Settings: Kameras per Dropdown hinzufügen/entfernen, Auflösung und FPS wählen. Die angebotenen Modi werden automatisch aus v4l2-ctl ermittelt – es werden nur die Modi angezeigt, die die jeweilige Kamera wirklich kann.
• Mehrere Kameras: beliebig erweiterbar, jede bekommt ihren eigenen Stream.
• Drei Protokolle gleichzeitig:
  • RTSP (geringe Latenz, für VLC & Co.)
  • HLS (Low-Latency, für Browser/Mainsail)
  • WebRTC (sehr geringe Latenz, für Mainsail/Browser)
• Konfiguration wird in config.json gespeichert und überlebt Reboots.

Architektur

USB-Kamera  -->  ffmpeg (H.264, x264)  -->  MediaMTX  -->  RTSP :8554
                                                          HLS  :8888
                                                          WebRTC :8889
                            ^
                Flask-App (verwaltet ffmpeg-Prozesse,
                dient UI + API auf Port 8088)

• app.py (Flask + waitress) enumeriert Kameras, startet/stoppt die ffmpeg-Prozesse und dient UI + REST-API.
• MediaMTX nimmt die ffmpeg-Streams per RTSP entgegen und re-publiziert sie als HLS/WebRTC/RTSP.

Voraussetzungen

• Linux (getestet auf Raspberry Pi 5 / Debian 12 Bookworm, arm64)
• Eine UVC-Webcam (USB)
• Für das Encoding ist kein Hardware-Encoder nötig (Software-x264). Als grobe Richtlinie: 1080p30 ≈ 1,5 Kerne eines Pi 5.
• ffmpeg, v4l2-utils, python3 (wird vom Installer automatisch installiert)

---

Installation (nativ, per install.sh)

1. Repository klonen bzw. Dateien auf den Rechner legen:

   git clone <repo-url> WebcamServer
   cd WebcamServer
   

2. Installer als root ausführen:

   sudo ./install.sh
   

   Der Installer macht Folgendes:

   • installiert ffmpeg, v4l2-utils, python3-venv, curl
   • lädt das MediaMTX-Binary (passend zur Architektur) nach /usr/local/bin/
   • kopiert die App nach /opt/webcam-ui und legt ein Python-venv an
   • installiert zwei systemd-Services: mediamtx.service und webcam-ui.service
   • startet beide Services

3. Im Browser öffnen:

   http://<IP-des-Rechners>:8088/
   

   Über Einstellungen → + Kamera hinzufügen die Kamera auswählen, Auflösung/FPS wählen und Speichern & anwenden.

Installation (Docker)

Voraussetzung: Docker mit Compose-Plugin (docker compose).

cd WebcamServer
mkdir -p data
docker compose up -d --build

Die Web-Oberfläche ist danach unter http://<IP>:8088/ erreichbar. Die Kamera-Konfiguration wird in ./data/config.json gespeichert und bleibt beim Neustart erhalten.

Hinweis zu den Geräten: In docker-compose.yml sind /dev/video0 und /dev/video1 durchgereicht. Für eine zweite Kamera dort zusätzlich /dev/video2 und /dev/video3 eintragen (siehe Kommentare in der Datei), danach docker compose up -d erneut ausführen.

---

Bedienung

Kamera hinzufügen / ändern

1. In der Web-Oberfläche oben rechts auf Einstellungen klicken.
2. + Kamera hinzufügen.
3. Gerät wählen (zeigt nur UVC-Webcams mit ihren Kartenamen).
4. Auflösung / FPS wählen – die Dropdown-Liste enthält nur Modi, die die gewählte Kamera tatsächlich unterstützt.
5. Speichern & anwenden – die Streams werden sofort neu gestartet.

Jede Kamera bekommt einen Namen (Standard: Gerätename wie video0). Dieser Name ist der Pfad im Stream.

Zweite Kamera

• Nativ: zweite Webcam einstecken, im UI „+ Kamera hinzufügen" – sie erscheint automatisch im Geräte-Dropdown (z. B. /dev/video2).
• Docker: zusätzlich das Gerät in docker-compose.yml freigeben.

In Mainsail einbinden

In Mainsail unter Interface Settings → Webcams → Add Webcam:

Empfohlene Option	Service	URL
Sehr geringe Latenz	WebRTC (MediaMTX)	http://<IP>:8889/<kamera>
Kompatibel (Browser)	HLS Stream	http://<IP>:8888/<kamera>/index.m3u8

In VLC öffnen

WebRTC unterstützt VLC nicht. Für VLC RTSP oder HLS verwenden:

rtsp://<IP>:8554/<kamera>
http://<IP>:8888/<kamera>/index.m3u8

---

Ports

Port	Protokoll	Dienst
8088	HTTP	Web-Oberfläche + API
8554	RTSP	MediaMTX
8888	HTTP	HLS
8889	HTTP + UDP 8189	WebRTC

Konfiguration

config.json

{
  "cameras": [
    {
      "name": "video0",
      "device": "/dev/video0",
      "pixfmt": "MJPG",
      "width": 1920,
      "height": 1080,
      "fps": 30
    }
  ]
}

• pixfmt ist das V4L2-Format (z. B. MJPG oder YUYV) – wird von der UI automatisch gesetzt.

Umgebungsvariablen (für app.py)

Variable	Standard	Bedeutung
MEDIAMTX_HOST	127.0.0.1	Host von MediaMTX (Docker: mediamtx)
MEDIAMTX_PORT	8554	RTSP-Port von MediaMTX
PORT	8088	Port der Web-Oberfläche
CONFIG_PATH	./config.json	Pfad zur Konfigurationsdatei
FFMPEG	/usr/bin/ffmpeg	Pfad zum ffmpeg-Binary
V4L2_CTL	/usr/bin/v4l2-ctl	Pfad zu v4l2-ctl

---

Fehlersuche

• Kamera erscheint nicht im Dropdown: prüfen mit v4l2-ctl --list-devices. Es werden nur uvcvideo-Geräte angezeigt.
• Stream zeigt „offline": ffmpeg-Log ansehen: journalctl -u webcam-ui -f bzw. tail -f /opt/webcam-ui/logs/<kamera>.log.
• WebRTC im VLC: wird nicht unterstützt – RTSP oder HLS nutzen.
• Latenz: RTSP/WebRTC ≈ <1 s, HLS ≈ 1–2 s (Low-Latency HLS).

Lizenzen

• MediaMTX: MIT
• ffmpeg, Flask, waitress: jeweilige Lizenzen (GPL/BSD)
• Der eigene Code in diesem Repo steht ohne explizite Lizenz – bitte vor öffentlicher Weitergabe eine Lizenz ergänzen.