# AppRobotWebcam

Webcam-Service für den AppRobot. Liefert Live-MJPEG-Streams und HD-Standbilder
über einen einzelnen HTTP-Port — als Docker-Container, ohne externe Streaming-Server.

## Was es tut

| | |
|---|---|
| **Live-Stream** | MJPEG multipart im Browser `<img>`, ~139 ms Latenz |
| **HD-Snapshot** | Ein JPEG pro Kamera auf Knopfdruck oder per HTTP GET |
| **Snapshot alle** | Alle Kameras parallel in einem Schritt |
| **REST-API** | Kameraliste, Snapshots, Streams — für andere Container nutzbar |

## Kameras (aktuell)

| ID | Modell | Live | HD-Grab |
|---|---|---|---|
| cam0 | Logitech C270 | 640×480 | 1280×960 |
| cam1 | Logitech C270 | 640×480 | 1280×960 |
| cam2 | Logitech C920 | 640×480 | 1920×1080 |

Konfiguration ausschliesslich über `cameras.json` — kein Redeploy bei Kamera-Änderungen.

## Zugriff

```
http://<host>:8444/                          Viewer
http://<host>:8444/api/stream/cam0           Live-MJPEG
http://<host>:8444/api/snapshot/cam0         640er JPEG
http://<host>:8444/api/snapshot/cam0/hires   HD-JPEG
http://<host>:8444/api/cameras               Kamera-Metadaten (JSON)
http://<host>:8444/health                    Status
```

## API-Referenz

Basis-URL: `http://<host>:8444`

---

### `GET /api/cameras`

Vollständige Kamera-Metadaten. Primärer Einstiegspunkt für andere Container.

```json
{
  "cameras": [
    {
      "id":             "cam0",
      "name":           "Kamera 0",
      "position":       "front",
      "stream":         true,
      "hires":          true,
      "encode":         "copybsf",
      "mseCodec":       null,
      "note":           "usb-046d_0825_3BB3FE20-video-index0",
      "calibrationUrl": "/api/cameras/cam0/calibration"
    }
  ]
}
```

`calibrationUrl` fehlt, solange noch keine `.npz` für diese Kamera vorhanden ist.  
`encode`: `"copybsf"` (MJPEG-Copy, Default) | `"mjpeg"` (Re-Encode) | `"h264"` (GPU, MSE).  
`mseCodec`: nur bei `encode="h264"` gesetzt, z.B. `"avc1.4D001F"`.

---

### `GET /api/cameras/{id}/calibration`

Liefert die `.npz`-Kalibrierungsdatei (Kameramatrix + Verzerrungskoeffizienten) als Binary.

```
Content-Type:        application/octet-stream
Content-Disposition: attachment; filename="cam0_calibration.npz"
Cache-Control:       public, max-age=86400
```

404 wenn keine Kalibrierung vorhanden. Einlesen in Python:

```python
import numpy as np, requests
d = np.load(requests.get(".../api/cameras/cam0/calibration", stream=True).raw)
K, D = d["camera_matrix"], d["dist_coeffs"]
```

---

### `PUT /api/cameras/{id}/calibration`

Nimmt eine neue `.npz`-Datei entgegen (Homing-Prozess → Webcam-Service).  
Schreibt zwei Dateien nach `data/calibration/{id}/`:

| Datei | Zweck |
|---|---|
| `calibration_YYYYMMDD_HHMMSS.npz` | Archiv (bleibt erhalten) |
| `calibration.npz` | Aktuell — wird bei jedem PUT überschrieben |

Existiert beim ersten Aufruf nur `calibration.npz` (noch kein Archiv), wird sie
anhand ihres `mtime` automatisch in `calibration_<ts>.npz` umbenannt, bevor die
neue Datei abgelegt wird.

```
Content-Type: application/octet-stream
Body:         rohe .npz-Bytes
```

```json
// Response 200
{ "id": "cam0", "saved": "calibration_20260610_143022.npz", "size": 1284, "calibrationUrl": "/api/cameras/cam0/calibration" }
```

Der In-Memory-Buffer wird sofort aktualisiert — `GET /api/cameras/cam0/calibration`
liefert ab diesem Moment die neue Datei, ohne Server-Neustart.

400 bei leerem Body, 404 bei unbekannter Kamera-ID.

Aufruf aus Python (Homing):

```python
import requests
with open("cam0_calibration.npz", "rb") as f:
    r = requests.put(
        "http://thinkcentre.local:8444/api/cameras/cam0/calibration",
        data=f,
        headers={"Content-Type": "application/octet-stream"},
    )
r.raise_for_status()
print(r.json())  # {'id': 'cam0', 'saved': 'calibration_20260610_143022.npz', ...}
```

---

### `GET /api/snapshot/{id}`

Letztes Live-JPEG (Live-Auflösung, z.B. 640×480) aus dem RAM-Puffer.  
Bei `stream: false`: one-shot — öffnet Gerät kurz, schließt es wieder.

```
Content-Type:    image/jpeg
X-Camera-Id:     cam0
X-Frame-Width:   640
X-Timestamp:     2026-06-10T07:30:00.000Z
Cache-Control:   no-store
```

503 wenn kein Frame verfügbar (Kamera nicht erreichbar).

---

### `GET /api/snapshot/{id}/hires`

HD-JPEG (volle Auflösung, z.B. 1280×960 oder 1920×1080).  
Pausiert den Live-Stream kurz, nimmt ein Einzelbild auf, startet Live neu.  
Gleiche Response-Headers wie `/api/snapshot/{id}`.

---

### `GET /api/stream/{id}`

Live-Stream. Format hängt vom `encode`-Modus ab:

| encode | Content-Type | Player |
|---|---|---|
| `copybsf` / `mjpeg` | `multipart/x-mixed-replace; boundary=frame` | `<img src="...">` |
| `h264` | `video/mp4` (fragmentiertes MP4) | `<video>` via MSE |

Verbindung läuft bis der Client trennt. Langsame Clients droppen Frames (MJPEG)
bzw. werden getrennt (H.264, um Decode-Lücken zu vermeiden).

---

### `GET /api/config`

Laufzeit-Konfiguration aller Kameras.

```json
{
  "liveSizes": ["320x240", "640x480", "1280x960"],
  "encodes":   ["copybsf", "mjpeg", "h264"],
  "cameras": [
    {
      "id":       "cam0",
      "name":     "Kamera 0",
      "liveSize": "640x480",
      "stream":   true,
      "encode":   "copybsf"
    }
  ]
}
```

---

### `POST /api/config`

Ändert Auflösung, Stream-Zustand oder Encoder einer oder mehrerer Kameras.  
Änderungen werden in `cameras.json` gespeichert und sofort aktiv (Hot-Reload).

```json
// Request Body
{ "cameras": [{ "id": "cam0", "liveSize": "320x240", "stream": true, "encode": "copybsf" }] }
```

Alle Felder ausser `id` sind optional. Antwort: wie `GET /api/config`.  
400 bei ungültiger Auflösung, unbekannter Kamera-ID oder falschem Typ.

---

### `GET /health`

```json
{
  "status": "ok",
  "cameras": [
    { "id": "cam0", "name": "Kamera 0", "device": "/dev/video0", "state": "running", "hasFrame": true }
  ]
}
```

`state`: `"running"` | `"idle"` | `"stopping"` — Zustand des FFmpeg-Prozesses.

---

## Deploy (Portainer)

1. Portainer → Stacks → Web editor → `docker-compose.yaml` einfügen
2. `APP_PATH` auf den absoluten Pfad des Projektverzeichnisses setzen
3. Deploy — der Container baut sich selbst (Node + FFmpeg)

```yaml
# Minimal-Konfiguration:
APP_PATH=/home/user/appRobotWebcam
```

## Architektur

```
cameras.json → server.js → CameraSwitch (/dev/videoN)
                                ├── Live: ffmpeg → MJPEG → Browser
                                └── Grab: Live stoppen → hires → zurück
```

Ein FFmpeg pro Kamera, nie zwei gleichzeitig. Das `close`-Event ist der harte Beweis
„Gerät frei" — kein Race, kein 106%-CPU-Bug (der mit go2rtc aufgetreten war).

## Dokumentation

| Datei | Inhalt |
|---|---|
| `doc/01_WebcamRoadmap.md` | Ziel, Architektur, Entwicklungsgeschichte |
| `doc/05_screenShot_roadmap.md` | HD-Grab, Encode-Qualität, Kamera-Eigenheiten |
| `doc/07_multipleCam_roadmap.md` | cameras.json-Referenz, Multi-Kamera-Setup |
| `doc/09_Bug_reports.md` | Bug-Dokumentation |