# Guide d'accès aux flux caméra — DWARF Mini

Ce document décrit comment accéder aux flux vidéo des caméras du télescope
DWARF Mini (et DWARF II/3), que ce soit pour capturer une image unique,
afficher un flux continu, ou enregistrer une vidéo.

---

## 1. Architecture du flux caméra

Le télescope possède **deux caméras** accessibles via des protocoles distincts :

| Caméra | Canal RTSP | Usage |
|--------|-----------|-------|
| **Tele** | `ch0` | Caméra principale (longue focale) |
| **Wide** | `ch1` | Caméra grand angle (repérage) |

Le flux vidéo est accessible via le protocole **RTSP** sur le port **554** :

```
rtsp://<IP_TELESCOPE>:554/ch0/stream0   # Téléobjectif (Tele)
rtsp://<IP_TELESCOPE>:554/ch1/stream0   # Grand angle (Wide)
```

### Caractéristiques techniques

- **Codec** : MJPEG (Motion JPEG)
- **Résolution** : 1920×1080 (les deux caméras)
- **Transport** : TCP (`rtsp_transport=tcp` obligatoire)
- **FPS** : Variable (généralement 15-30 FPS selon l'éclairage)

### ⚠️ Prérequis absolu : ouvrir la caméra via WebSocket

**Le flux RTSP n'est actif qu'après avoir ouvert la caméra via l'API de contrôle
WebSocket** (port 9900). Sans cette étape, le serveur RTSP accepte la connexion
TCP mais n'envoie **aucune frame vidéo**.

La procédure complète est :
1. Se connecter au WebSocket `ws://<IP>:9900/?client_id=mon_client`
2. Envoyer la commande `CMD_CAMERA_TELE_OPEN_CAMERA` (10000) ou
   `CMD_CAMERA_WIDE_OPEN_CAMERA` (12000) via le protocole `WsPacket`
3. Attendre ~2 secondes que le serveur RTSP démarre
4. Se connecter au flux RTSP avec `ffmpeg`, `mpv`, `VLC` ou tout lecteur RTSP

---

## 2. Accès avec `dwarfctl` (le plus simple)

Le CLI `dwarfctl` inclut une commande `preview grab` qui automatise toute la
séquence (ouverture caméra + capture RTSP) :

```bash
# Capturer une frame de la caméra grand angle
dwarfctl --ip 192.168.88.1 preview grab --cam wide /tmp/wide.jpg

# Capturer une frame du téléobjectif
dwarfctl --ip 192.168.88.1 preview grab --cam tele /tmp/tele.jpg
```

---

## 3. Accès avec `ffmpeg` (capture manuelle)

### Capture d'une seule image (frame)

```bash
# 1. Ouvrir la caméra via WebSocket
dwarfctl --ip 192.168.88.1 camera open --cam wide

# 2. Attendre 2 secondes
sleep 2

# 3. Capturer une frame
ffmpeg -rtsp_transport tcp \
  -i "rtsp://192.168.88.1:554/ch1/stream0" \
  -frames:v 1 -q:v 2 \
  -y wide_frame.jpg
```

### Capture de plusieurs frames (time-lapse)

```bash
# Capturer 1 frame par seconde pendant 60 secondes
ffmpeg -rtsp_transport tcp \
  -i "rtsp://192.168.88.1:554/ch1/stream0" \
  -r 1 -t 60 \
  -q:v 2 \
  wide_timelapse_%03d.jpg
```

### Enregistrement vidéo (MP4)

```bash
# Enregistrer 30 secondes de vidéo
ffmpeg -rtsp_transport tcp \
  -i "rtsp://192.168.88.1:554/ch1/stream0" \
  -t 30 -c:v libx264 -preset fast \
  wide_video.mp4
```

---

## 4. Accès avec `mpv` (flux continu)

`mpv` est idéal pour afficher le flux en direct avec faible latence :

```bash
# 1. Ovrir la caméra
dwarfctl --ip 192.168.88.1 camera open --cam wide

# 2. Afficher le flux en plein écran
mpv --rtsp-transport=tcp "rtsp://192.168.88.1:554/ch1/stream0"
```

### Options utiles pour mpv
```bash
# Faible latence
mpv --rtsp-transport=tcp --profile=low-latency \
    "rtsp://192.168.88.1:554/ch1/stream0"

# Double flux (Tele + Wide côte à côte)
dwarfctl --ip 192.168.88.1 camera open --cam tele &
dwarfctl --ip 192.168.88.1 camera open --cam wide &
sleep 2
mpv --rtsp-transport=tcp "rtsp://192.168.88.1:554/ch0/stream0" &
mpv --rtsp-transport=tcp "rtsp://192.168.88.1:554/ch1/stream0"
```

---

## 5. Accès avec VLC

```bash
# Ouvrir depuis la ligne de commande
vlc "rtsp://192.168.88.1:554/ch1/stream0" --rtsp-tcp

# Ou depuis l'interface VLC :
# Média → Ouvrir un flux réseau → rtsp://192.168.88.1:554/ch1/stream0
# (Cliquer sur "Afficher les options" → ajouter :rtsp-tcp)
```

---

## 6. Accès programmatique (Python / Go)

### Python (avec OpenCV)

```python
import cv2
import subprocess
import time

# 1. Ouvrir la caméra via dwarfctl
subprocess.run(["dwarfctl", "--ip", "192.168.88.1", "camera", "open", "--cam", "wide"])
time.sleep(2)

# 2. Ouvrir le flux RTSP avec OpenCV
cap = cv2.VideoCapture("rtsp://192.168.88.1:554/ch1/stream0")
cap.set(cv2.CAP_PROP_BUFFERSIZE, 1)

while True:
    ret, frame = cap.read()
    if not ret:
        break
    cv2.imshow("DWARF Wide", frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()
```

### Go (avec `gortsplib` ou `ffmpeg` exec)

```go
// Voir la commande `preview grab` dans:
// dwarfctl/cmd/dwarfctl/main.go → func cmdPreview()
// Elle utilise exec.Command("ffmpeg", ...) pour capturer une frame.
```

---

## 7. Comparatif des modes de preview

Le télescope supporte deux modes de preview selon les modèles :

| Mode | Protocole | Port | DWARF Mini | DWARF II/3 |
|------|-----------|------|:----------:|:----------:|
| **RTSP** | `rtsp://` | 554 | ✅ Actif | ✅ Actif |
| **MJPEG** | HTTP multipart | 8092 | ❌ Inactif | ⚠️ Non testé |

- **RTSP (streamType=1)** : flux MJPEG encapsulé en RTSP, port 554, channel
  `ch0` (tele) ou `ch1` (wide), path `/stream0`.
- **MJPEG HTTP (streamType=2)** : flux multipart/x-mixed-replace sur port 8092,
  endpoints `/mainstream` (tele) et `/secondstream` (wide).
  Le DWARF Mini n'envoie pas de frames sur ce port — le mode RTSP est utilisé.

Le choix entre RTSP et MJPEG est décidé par le télescope via la notification
`CMD_NOTIFY_STREAM_TYPE` (15234) qui transporte `StreamType{stream_type, cam_id}`.
L'app Android s'y adapte automatiquement.

---

## 8. Dépannage

### Le flux RTSP ne donne aucune image

**Cause** : la caméra n'est pas ouverte via WebSocket.

**Solution** :
```bash
dwarfctl --ip 192.168.88.1 camera open --cam wide
sleep 2
ffmpeg -rtsp_transport tcp -i "rtsp://192.168.88.1:554/ch1/stream0" -frames:v 1 test.jpg
```

### ffmpeg affiche "Connection refused" sur le port 554

**Cause** : le télescope vient de démarrer, le serveur RTSP n'est pas encore prêt.

**Solution** : attendre 10-15 secondes après l'allumage du télescope.

### L'image est noire

**Cause** : le télescope pointe vers le sol ou dans l'obscurité.

**Solution** : vérifier la position du télescope, ou augmenter le gain/exposure :
```bash
dwarfctl --ip 192.168.88.1 camera exp --cam wide 200   # exposition longue
dwarfctl --ip 192.168.88.1 camera gain --cam wide 100   # gain élevé
```

### VLC met très longtemps à afficher l'image

**Cause** : VLC utilise UDP par défaut pour RTSP.

**Solution** : forcer TCP — ajouter `:rtsp-tcp` dans les options ou utiliser
`--rtsp-transport=tcp` en ligne de commande.