dwarf-go/analysis/CAMERA_STREAMING.md

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) :

# 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)

# 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)

# 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)

# 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 :

# 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

# 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

# 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)

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)

// 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 :

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 :

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.