Aller au contenu principal

V0.1.0 — Flux RTSP simulés joignables en CLI, navigateur et testés

Publiée le 30/09/2026.

Documentation fonctionnelle

Ce que change la version pour les collaborateurs

Pourquoi​

Sans matériel réel, impossible de construire l’API Site (0.2.0) ni le Live (0.3.0 / 1.0.0) : il faut des Caméras à regarder. Cette version fournit des Caméras simulées fiables, lancées d’une commande, visibles dans un navigateur, et dont la panne est détectée automatiquement.

Ce qu'on peut faire maintenant​

  • Lancer trois Caméras simulées (cam1, cam2, cam3) avec docker compose up -d --wait — seul Docker est requis.
  • Les lire en RTSP sur rtsp://\<hôte>:8554/camN (H.264 1280×720, vidéo en boucle, sans réencodage).
  • Les regarder dans un navigateur en HLS (http://\<hôte>:8888/camN) ou en WebRTC quasi direct (http://\<hôte>:8889/camN), y compris depuis un autre appareil du réseau local (IP de la machine dans .env pour WebRTC).
  • Vérifier un Flux en CLI avec ffprobe en conteneur (commande dans le README).
  • Lancer /t : démarre la stack si besoin et échoue si une Caméra simulée n’est pas joignable, pas en H.264 1280×720, ne décode aucune image, ou si sa playlist HLS ne répond pas ; cam404 est bien refusé.
  • Lire le README racine pour démarrer depuis un clone neuf, et le glossaire (CONTEXT.md) pour Caméra, Flux, Caméra simulée.

Documentation technique

Spec versionnée : docs/specs/v0.1.0-flux-rtsp-simules.md

Issue parente : #1

V0.1.0 — Flux RTSP simulés

Problem Statement​

Avant d'avoir du matériel réel, le développeur d'ArgOS n'a aucune Caméra à regarder : impossible de construire l'API Site (0.2.0) ni le Live (0.3.0 / 1.0.0) sans Flux RTSP joignables. Il lui faut des Caméras simulées fiables, qu'il puisse lancer d'une commande, vérifier à l'œil dans un navigateur, et dont la panne soit détectée automatiquement.

Solution​

Une stack Docker Compose lance MediaMTX, qui publie 3 Caméras simulées (cam1, cam2, cam3). Chacune diffuse en boucle une vidéo de dev fournie par le développeur, déjà convertie en H.264, sans réencodage à la volée, comme une vraie caméra H.264. Les Flux sont joignables en RTSP et visibles dans un navigateur (HLS, et WebRTC), en local et sur le réseau local. Une suite de tests (/t) échoue si un Flux n'est pas joignable ou pas conforme. Le README devient celui d'un projet lançable.

User Stories​

  1. En tant que développeur, je veux lancer toutes les Caméras simulées d'une seule commande docker compose up -d, pour ne rien avoir à installer à part Docker.
  2. En tant que développeur, je veux que les Caméras simulées soient cam1, cam2, cam3 sur rtsp://\<hôte>:8554/camN, pour avoir des URLs stables à déclarer plus tard comme Caméras du Site.
  3. En tant que développeur, je veux que chaque Caméra simulée diffuse une vidéo différente, pour voir que l'image change quand on passe d'une Caméra à la suivante.
  4. En tant que développeur, je veux que les vidéos tournent en boucle sans fin, pour que le Flux ne s'arrête jamais pendant le dev.
  5. En tant que développeur, je veux que chaque Flux soit en H.264 1280×720 15 i/s sans audio, pour se comporter comme une caméra IP H.264 classique et rester lisible par les navigateurs.
  6. En tant que développeur, je veux que les Flux soient diffusés sans réencodage à la volée, pour ne pas consommer de CPU et rester fidèle au comportement d'une vraie caméra.
  7. En tant que développeur, je veux déposer mes propres vidéos (≤ 50 Mo chacune) dans un dossier dédié du dépôt, pour choisir ce que montrent les Caméras simulées.
  8. En tant que développeur, je veux que les vidéos soient versionnées dans git, pour qu'un clone neuf fonctionne et passe /t sans étape manuelle.
  9. En tant que développeur, je veux un README dans le dossier des vidéos qui explique leur rôle (Caméras simulées de dev, à remplacer par des caméras réelles) et leur format attendu, pour ne pas les confondre avec des données produit.
  10. En tant que développeur, je veux ouvrir http://\<hôte>:8888/camN dans un navigateur et voir la vidéo (HLS), pour vérifier à l'œil qu'un Flux est vivant.
  11. En tant que développeur, je veux voir le Flux depuis un autre appareil du réseau local (téléphone, tablette), pour valider l'accès hors de la machine de dev.
  12. En tant que développeur, je veux ouvrir http://localhost:8889/camN (WebRTC) et voir la vidéo quasi en direct, pour préparer le Live à faible latence.
  13. En tant que développeur, je veux pouvoir activer WebRTC sur le réseau local en renseignant l'IP de ma machine dans un .env non commité, pour ne pas figer une IP dans le dépôt.
  14. En tant que développeur, je veux vérifier un Flux en CLI (ffprobe via Docker, commande documentée), pour diagnostiquer sans navigateur.
  15. En tant que développeur, je veux que /t démarre la stack si elle ne tourne pas, pour lancer les tests d'une seule commande.
  16. En tant que développeur, je veux que /t échoue si une Caméra simulée n'est pas joignable en RTSP, pour détecter un tuyau cassé.
  17. En tant que développeur, je veux que /t échoue si un Flux n'est pas en H.264 1280×720, pour détecter une vidéo mal convertie.
  18. En tant que développeur, je veux que /t échoue si aucune image ne peut être décodée d'un Flux, pour détecter un Flux figé ou vide.
  19. En tant que développeur, je veux que /t échoue si la playlist HLS d'une Caméra simulée ne répond pas, pour garantir la preuve navigateur.
  20. En tant que développeur, je veux qu'un test prouve qu'un chemin inexistant (cam404) est bien refusé, pour être sûr que les tests savent être rouges.
  21. En tant que développeur, je veux que les tests n'exigent que Docker (ffprobe tourne dans un conteneur), pour ne pas installer ffmpeg sur ma machine.
  22. En tant que développeur, je veux que l'image MediaMTX soit épinglée à une version précise, pour que la stack ne change pas toute seule.
  23. En tant que nouveau venu, je veux un README racine qui dit quoi, prérequis, comment lancer, les URLs des Flux, comment tester et la structure du dépôt, pour démarrer sans aide.
  24. En tant qu'agent, je veux un rôle test-roots dans agents/roles.yml, pour que /t sache où tourner.
  25. En tant que développeur, je veux que le glossaire définisse Caméra, Flux et Caméra simulée, pour parler le même langage dans les versions suivantes.
  26. En tant que développeur, je veux que la feuille de route de dev mentionne les versions futures « Codecs multiples (H.265…) » et « Incrustation nom/heure sur les Caméras simulées », pour ne pas perdre ces idées.

Implementation Decisions​

  • Stack : un seul service Docker Compose (fichier compose à la racine, qui grandira avec backend et Postgres), image bluenviron/mediamtx:\<version épinglée>-ffmpeg.
  • Publication : MediaMTX démarre, pour chaque chemin camN, un ffmpeg qui lit la vidéo en temps réel, en boucle infinie, en copie de flux (-re -stream_loop -1 -c copy), et la publie en RTSP sur ce chemin. MediaMTX relance ffmpeg s'il meurt.
  • Vidéos : noms fixes cam1.mp4, cam2.mp4, cam3.mp4 dans un dossier vidéos à côté de la config MediaMTX. Le nom du fichier donne le chemin. Les fichiers commités sont déjà convertis en H.264 1280×720 15 i/s, sans audio, keyframe ~2 s, ≤ 50 Mo. La conversion est faite une fois (ffmpeg en conteneur) à partir des vidéos fournies par le développeur. La commande de conversion est documentée dans le README du dossier.
  • Ports, ouverts sur toutes les interfaces (réseau local) : RTSP 8554, HLS 8888, WebRTC 8889 (+ UDP ICE). Pas d'auth sur les Flux.
  • WebRTC réseau local : variable MTX_WEBRTCADDITIONALHOSTS lue depuis un .env non commité (un exemple commité documente la clé).
  • Glossaire (CONTEXT.md) : Caméra (source vidéo connue du Site, identifiée par une URL RTSP), Flux (la vidéo RTSP que produit une Caméra), Caméra simulée (Caméra dont le Flux est produit par MediaMTX à partir d'une vidéo de dev).
  • Rôle test-roots ajouté à agents/roles.yml, pointant la racine des tests.
  • README racine : quoi, prérequis (Docker), lancer/arrêter, URLs RTSP/HLS/WebRTC, WebRTC en réseau local, vérification CLI, /t, structure.
  • Feuille de route : ajout « Plus tard — Codecs multiples (H.265…) » après « Enregistrement sans réencodage », et « Plus tard — Incrustation nom/heure sur les Caméras simulées ».
  • Pas d'ADR : aucune décision difficile à défaire.

Testing Decisions​

  • Un seul point de contact : la sortie réseau de la stack, vue de l'extérieur. L'URL RTSP de chaque Caméra simulée et l'URL de la playlist HLS. Aucun test sur la config MediaMTX, la commande ffmpeg ou la présence des fichiers : si l'un casse, le Flux casse et le test échoue.
  • Racine de tests Python dédiée (pyproject + .venv via uv, pytest), détectée par /t (runner pytest-venv).
  • Fixture de session : démarre la stack (docker compose up -d --wait) si elle ne tourne pas, attend que les chemins soient prêts.
  • ffprobe tourne dans un conteneur Docker. Pour chaque camN : codec h264, 1280×720, et au moins une image décodée.
  • HTTP : GET /camN/index.m3u8 sur le port HLS renvoie 200, et le contenu est une playlist.
  • Test négatif : cam404 est refusé en RTSP.
  • Un bon test vérifie un comportement observable (Flux joignable et conforme), pas un détail d'implémentation.
  • Pas de prior art : ce sont les premiers tests du dépôt.

Out of Scope​

  • CI GitHub Actions ; analyse SonarCloud par Automatic Analysis (comme BBASS), pas de scanner CI.
  • Auth sur les Flux ; API Site ; UI.
  • Codecs autres que H.264, audio, main/substream.
  • Incrustation nom/heure dans l'image.
  • Vérification automatique de WebRTC.
  • Enregistrement, IA, ONVIF, PTZ.

Further Notes​

  • Le développeur dépose ses 3 vidéos avant le premier /implement du ticket qui en a besoin.
  • Sur Mac, Docker Desktop passe par une couche réseau intermédiaire : HLS fonctionne sur le réseau local sans réglage, WebRTC a besoin de l'IP de la machine.
  • Contexte : docs/specs/contexte-initial.md, feuille de route de dev (section 0.1.0).