Aller au contenu principal

V0.4.1 — Ajout d’une Caméra depuis un Candidat (Aperçu et identifiants)

Publiée le 04/10/2026.

Documentation fonctionnelle

Ce que change la version pour les collaborateurs

Pourquoi​

Depuis la 0.4.0, l’Administrateur voyait les Candidats trouvés par la Détection, mais ne pouvait rien en faire : pour ajouter une Caméra, il devait encore connaître et coller son URL RTSP complète (chemin propre à la marque, identifiants compris), et ne voyait l’image qu’une fois la Caméra créée. Une caméra protégée par mot de passe restait offline sans explication.

Ce qu'on peut faire maintenant​

  • Ajouter sur un Candidat : ArgOS cherche seul le Flux en essayant les chemins courants des caméras (Hikvision, Dahua, Reolink, Uniview, Axis, génériques), flux principal en priorité.
  • Caméra protégée : « Cette caméra demande un mot de passe », identifiant admin prérempli. Un seul essai par clic, jamais de mots de passe par défaut, pour ne pas faire verrouiller la caméra.
  • Caméra exotique : « Flux introuvable », puis saisie du chemin RTSP, essayé avec les identifiants déjà donnés.
  • Aperçu du Flux dans l’Administration avant l’ajout (jamais dans le Live), puis nom, emplacement et « Ajouter la Caméra ». Le mot de passe ne revient jamais au navigateur.
  • Codec que le navigateur ne lit pas (H.265) : nommé, l’ajout reste permis.
  • Ajouter par adresse IP pour un appareil que la Détection n’a pas trouvé, par le même parcours. L’Administration n’offre plus d’ajout par URL (la modification reste).
  • Garde-fous : essai réservé à une session, un seul à la fois, réseau local seulement, jamais vers ArgOS ; un seul Aperçu, retiré à l’ajout, à l’annulation ou après 2 min sans renouvellement.
  • Les Caméras simulées servent des chemins de vraies caméras (style Hikvision, Dahua avec identifiants, chemin exotique).
  • Doc : Ajouter une Caméra.

Documentation technique

Spec versionnée : docs/specs/v0.4.1-ajout-camera-depuis-candidat.md

Issue parente : #25

V0.4.1 — Ajout d'une Caméra depuis un Candidat (Aperçu et identifiants)

Problem Statement​

Depuis la 0.4.0, l'Administrateur voit les Candidats trouvés par la Détection (IP et port), mais ne peut rien en faire : pour ajouter une Caméra, il doit encore connaître et coller son URL RTSP complète, chemin et identifiants compris. Il ne connaît ni le chemin (propre à chaque marque), ni la forme de l'URL, et ne voit l'image qu'une fois la Caméra créée, dans le Live. Une caméra protégée par un mot de passe reste simplement offline sans qu'il comprenne pourquoi. Et quand un appareil n'est pas détecté, il n'a pas d'autre recours que l'URL.

Solution​

Dans l'Administration, l'Administrateur clique sur un Candidat (ou saisit l'IP d'un appareil non détecté). ArgOS cherche seul le Flux en essayant les chemins courants des caméras. Si la caméra demande un mot de passe, l'Administrateur le lit à l'écran et saisit identifiant et mot de passe ; si aucun chemin courant ne répond, il peut indiquer le chemin. Dès que le Flux est trouvé, son Aperçu s'affiche dans l'Administration (jamais dans le Live), avec en dessous le nom et l'emplacement à remplir, puis « Ajouter la Caméra ». L'Administrateur n'écrit plus jamais d'URL RTSP pour ajouter une Caméra ; la modification d'une Caméra par son URL reste possible.

User Stories​

Parcours d'ajout​

  1. En tant qu'Administrateur, je veux un bouton « Ajouter » sur chaque nouveau Candidat, pour transformer un appareil détecté en Caméra.
  2. En tant qu'Administrateur, je veux qu'un clic sur « Ajouter » ouvre un panneau sous la ligne du Candidat (pas une fenêtre modale), pour garder la liste sous les yeux.
  3. En tant qu'Administrateur, je veux qu'ArgOS trouve seul le chemin du Flux en essayant les chemins courants des caméras, pour ne pas avoir à connaître la marque ni l'URL.
  4. En tant qu'Administrateur, je veux voir « Recherche du Flux… » pendant l'essai, pour savoir qu'il faut attendre.
  5. En tant qu'Administrateur, je veux que le Flux principal (meilleure qualité) soit préféré au flux secondaire quand la caméra offre les deux, pour surveiller avec la meilleure image.
  6. En tant qu'Administrateur, je veux, dès que le Flux est trouvé, voir son Aperçu dans l'Administration, pour vérifier que c'est la bonne caméra avant de l'ajouter.
  7. En tant qu'Administrateur, je veux sous l'Aperçu les champs nom (obligatoire) et emplacement, puis « Ajouter la Caméra », pour la nommer et la situer en la regardant.
  8. En tant qu'Administrateur, je veux pouvoir « Annuler » à chaque étape, pour abandonner sans rien créer.
  9. En tant qu'Administrateur, je veux qu'après l'ajout la Caméra soit active, apparaisse dans la liste des Caméras et dans le Live, et que le Candidat passe dans « Déjà configurées », sans relancer de Détection.
  10. En tant qu'Administrateur, je veux qu'un nom déjà pris soit refusé avec le message habituel, l'Aperçu restant ouvert, pour corriger sans tout recommencer.
  11. En tant qu'Administrateur, je veux que l'Aperçu ne soit jamais montré dans le Live, pour que le Live ne montre que des Caméras.

Identifiants​

  1. En tant qu'Administrateur, je veux, quand la caméra refuse le Flux faute d'identifiants, lire « Cette caméra demande un mot de passe » et voir les champs identifiant et mot de passe, pour savoir quoi faire.
  2. En tant qu'Administrateur, je veux que l'identifiant soit prérempli avec admin mais modifiable, pour aller vite sans être bloqué sur une caméra qui en utilise un autre.
  3. En tant qu'Administrateur, je veux qu'après validation des identifiants ArgOS réessaie les chemins courants avec eux, pour arriver à l'Aperçu.
  4. En tant qu'Administrateur, je veux lire « Identifiant ou mot de passe refusé par la caméra » quand ils sont faux, et pouvoir les ressaisir, pour corriger une faute de frappe.
  5. En tant qu'Administrateur, je veux qu'ArgOS ne fasse qu'un essai d'identifiants par clic, sans réessai automatique ni test de mots de passe par défaut, pour ne pas faire verrouiller la caméra.
  6. En tant qu'Administrateur, je veux que les identifiants soient enregistrés avec la Caméra, pour qu'elle soit relayée et surveillée sans les ressaisir.
  7. En tant qu'Administrateur, je veux que le mot de passe ne revienne jamais dans le navigateur une fois envoyé (masqué partout, ajout fait depuis l'essai côté serveur), pour qu'il ne traîne pas dans l'UI.

Chemin en repli​

  1. En tant qu'Administrateur, je veux, quand aucun chemin courant ne répond, lire « Flux introuvable » et voir un champ « chemin RTSP », pour ajouter une caméra exotique en indiquant son chemin (trouvé dans sa notice).
  2. En tant qu'Administrateur, je veux que le chemin saisi soit essayé avec les identifiants déjà donnés, pour ne pas les ressaisir.

Codec non lisible​

  1. En tant qu'Administrateur, je veux, quand la caméra émet dans un codec que le navigateur ne sait pas lire (H.265), lire le nom du codec et que la Caméra peut quand même être ajoutée, pour ne pas croire qu'elle est en panne.
  2. En tant qu'Administrateur, je veux pouvoir ajouter cette Caméra malgré l'Aperçu illisible, puisque son Flux répond bien.

Appareil non détecté​

  1. En tant qu'Administrateur, je veux « Ajouter par adresse IP » (IP, port 554 par défaut modifiable) dans la section Détection, pour ajouter un appareil que la Détection n'a pas trouvé (sous-réseau mal configuré, port exotique).
  2. En tant qu'Administrateur, je veux que l'IP saisie suive exactement le même parcours qu'un Candidat détecté, pour n'apprendre qu'une façon de faire.
  3. En tant qu'Administrateur, je veux, si l'IP saisie correspond déjà à une Caméra, lire « Déjà configurée : <nom> » sans ouvrir le parcours.
  4. En tant qu'Administrateur, je veux lire « Aucune caméra ne répond à cette adresse » quand l'IP ne répond pas en RTSP.
  5. En tant qu'Administrateur, je veux qu'une IP non privée ou appartenant à ArgOS soit refusée avec un message, pour qu'ArgOS ne serve pas à joindre internet ou lui-même.
  6. En tant qu'Administrateur, je veux que l'Administration n'offre plus d'ajout de Caméra par URL RTSP, mais garde la modification d'une Caméra (URL comprise).

Aperçu et garde-fous​

  1. En tant qu'Administrateur, je veux un seul Aperçu à la fois : ouvrir un autre Candidat ferme le précédent.
  2. En tant qu'Administrateur, je veux que l'Aperçu soit retiré à l'ajout, à l'annulation, et de lui-même après 2 minutes sans renouvellement (onglet fermé), pour qu'aucun relais ne reste ouvert vers une caméra non configurée.
  3. En tant qu'Administrateur, je veux que l'Aperçu reste affiché tant que le panneau est ouvert (renouvelé par l'UI), pour prendre mon temps pour le nommer.
  4. En tant qu'Administrateur, je veux que l'essai d'un Flux soit réservé à une session connectée, et un seul à la fois, pour qu'un inconnu du réseau ne puisse pas s'en servir pour deviner des mots de passe.
  5. En tant que développeur, je veux que les identifiants ne soient jamais écrits dans les journaux de l'API, et que chaque essai y écrive une ligne (IP, port, issue, chemin retenu), pour diagnostiquer sans fuite.

Caméras simulées​

  1. En tant que développeur, je veux que camera-simulee-1 serve son Flux sur un chemin de style Hikvision (/Streaming/Channels/101), pour vérifier qu'ArgOS le trouve seul.
  2. En tant que développeur, je veux que camera-simulee-2 serve son Flux sur un chemin de style Dahua (/cam/realmonitor?channel=1&subtype=0) avec identifiants, pour vérifier le parcours avec mot de passe.
  3. En tant que développeur, je veux que camera-simulee-3 garde un chemin exotique (/flux), pour vérifier le repli par chemin saisi.
  4. En tant que développeur, je veux que la liste des chemins courants ne contienne aucune trace de la simulation.
  5. En tant que développeur, je veux que tests et docs utilisant camera-simulee-N/flux migrent vers les nouveaux chemins.

Documentation​

  1. En tant qu'Administrateur, je veux une doc « Ajouter une Caméra » qui explique le déroulé (chemins courants, mot de passe, repli par chemin, codec non lisible, ajout par IP), pour comprendre ce que fait ArgOS et quoi faire quand ça bloque.
  2. En tant que développeur, je veux que le glossaire définisse Aperçu et élargisse Candidat à l'IP saisie à la main.
  3. En tant que développeur, je veux que docs/securite.md décrive l'ajout d'une Caméra (garde-fous de l'essai, mot de passe en clair sur le réseau tant qu'il n'y a pas HTTPS, Aperçu lisible sans authentification comme les autres Flux).
  4. En tant que développeur, je veux que la feuille de route note l'ajout manuel par adresse MAC en 0.4.2, et que « Codecs multiples » évoque le réencodage ou un autre transport que WebRTC.

Implementation Decisions​

  • Glossaire :
  • Pas d'ADR : l'Aperçu complète l'ADR 0001 (pont MediaMTX) sans la contredire.
  • Identifiants : toujours portés par l'URL RTSP stockée, masquée à la lecture, en clair en base (chiffrement et HTTPS : version sécurité plus tard). L'API compose rtsp://identifiant:motdepasse@ip:port/chemin en encodant les caractères spéciaux. Pas de migration.
  • Module d'essai (interface étroite, s'appuie sur la sonde RTSP existante) : entrée IP, port, identifiants facultatifs, chemin facultatif ; sortie une issue parmi flux_trouve, identifiants_requis, identifiants_refuses, flux_introuvable, injoignable, plus le chemin retenu et le codec vidéo lu dans le SDP du DESCRIBE.
    • Sans chemin saisi : liste ordonnée de chemins courants (flux principal avant secondaire), réordonnée selon l'en-tête Server quand une marque est reconnue ; DESCRIBE sur chacun jusqu'au premier 200.
    • Un 401 sans identifiants → identifiants_requis (on s'arrête : la caméra répond souvent 401 avant de vérifier le chemin). Un 401 avec identifiants → identifiants_refuses, sans essayer d'autre chemin (un seul essai d'identifiants par demande).
    • Aucun 200 sur la liste (ou sur le chemin saisi) → flux_introuvable. Pas de réponse RTSP → injoignable.
    • Le Flux trouvé est confirmé par la sonde (au moins un paquet vidéo) avant d'ouvrir l'Aperçu.
  • Contrat de l'API (session requise, 401 sinon) :
    • POST /api/essai \{ip, port (554 par défaut), identifiant?, mot_de_passe?, chemin?\} → \{issue, chemin, codec, apercu\} où apercu est le chemin MediaMTX à lire en WebRTC, présent seulement si flux_trouve. Remplace l'essai précédent (et son Aperçu).
      • IP non privée (hors RFC 1918) ou appartenant à ArgOS → 422 avec la raison.
      • IP:port déjà configurée (même rapprochement que la Détection) → 409 avec la Caméra correspondante \{id, nom\}.
      • Un essai déjà en cours → 409 avec un message distinct.
    • POST /api/essai/renouveler → 204 ; 404 si aucun essai ou expiré.
    • DELETE /api/essai → 204 (retire l'Aperçu ; idempotent).
    • POST /api/essai/camera \{nom, emplacement?\} → 201 avec la Caméra (forme habituelle, URL masquée), créée active à partir de l'URL de l'essai côté serveur ; l'Aperçu est retiré. 404 sans essai flux_trouve en cours ; 409 doublon (message habituel), l'essai restant ouvert.
    • POST /api/cameras (par URL) reste dans l'API ; seul l'UI cesse de l'offrir.
  • Aperçu : chemin MediaMTX éphémère apercu-\<jeton aléatoire> ajouté par l'API de contrôle, à côté des chemins camera-\<id> ; la réconciliation du pont ne touche pas aux chemins apercu-*. Un seul à la fois pour le Site. Retiré à l'ajout, à l'annulation, au remplacement par un autre essai, ou 2 minutes sans renouvellement (nettoyage côté API, y compris des apercu-* orphelins au démarrage).
  • Journaux : une ligne par essai (IP, port, issue, chemin retenu, codec) ; jamais d'identifiant ni d'URL complète.
  • UI (Administration) :
    • Section Détection : bouton « Ajouter » par nouveau Candidat ; panneau sous la ligne ; étapes « Recherche du Flux… » → (identifiants) → (chemin en repli) → Aperçu + nom/emplacement + « Ajouter la Caméra » ; « Annuler » partout.
    • Champs identifiants : identifiant prérempli admin modifiable, mot de passe ; messages « Cette caméra demande un mot de passe », « Identifiant ou mot de passe refusé par la caméra ».
    • Repli : « Flux introuvable » + champ chemin RTSP.
    • Codec : si l'Aperçu n'est pas lisible ou que le codec n'est pas H.264, message nommant le codec ; « Ajouter la Caméra » reste permis.
    • « Ajouter par adresse IP » (IP, port 554) dans la section Détection, utilisable même si la Détection n'est pas configurée ; même panneau.
    • Renouvellement de l'essai tant que le panneau est ouvert ; fermeture du panneau → DELETE.
    • Après l'ajout : liste des Caméras rafraîchie, Candidat déplacé dans « Déjà configurées ».
    • Le formulaire d'ajout par URL disparaît ; le formulaire de modification reste.
  • Caméras simulées : chemins /Streaming/Channels/101 (1), /cam/realmonitor?channel=1&subtype=0 avec identifiants (2), /flux (3). README de simulation, healthchecks, tests et docs mis à jour.
  • Docs : nouveau document « Ajouter une Caméra » dans le dossier de docs caméras, lié depuis le README et la doc de Détection ; paragraphe « Ajout d'une Caméra » dans docs/securite.md ; une ligne Aperçu dans le schéma des Flux ; feuille de route (0.4.2 : ajout manuel par MAC ; Codecs multiples : réencodage ou autre transport que WebRTC).

Testing Decisions​

  • Un bon test vérifie un comportement observable (réponse HTTP, chemins présents dans MediaMTX, écran), jamais la liste interne de chemins ni les requêtes RTSP envoyées.
  • tests/api/ (HTTP contre la stack avec simulation), prior art : tests Détection 0.4.0 et pont 0.3.0. Sans mock :
    • camera-simulee-1 → flux_trouve, chemin Hikvision, codec H.264, Aperçu présent dans MediaMTX ;
    • camera-simulee-2 → identifiants_requis, puis mauvais mot de passe → identifiants_refuses, puis bons → flux_trouve ;
    • camera-simulee-3 → flux_introuvable, puis chemin /flux → flux_trouve ;
    • IP privée sans caméra → injoignable ; IP publique ou d'ArgOS → 422 ; IP déjà configurée → 409 avec la Caméra ;
    • Aperçu retiré par DELETE, par un nouvel essai, par l'ajout, et après expiration (délai réglable pour les tests) ;
    • POST /api/essai/camera crée une Caméra active (URL masquée, identifiants conservés : elle passe online) ; doublon → 409, essai toujours ouvert ;
    • sans session → 401 ; essai simultané → 409 ; aucun identifiant dans les journaux.
  • tests/web/ (pytest-playwright), prior art : test_detection.py, test_administration.py. Parcours complets sur les trois Caméras simulées (Aperçu visible, mot de passe, chemin en repli), ajout par IP, absence du formulaire d'ajout par URL, modification toujours possible.
  • tests/flux/ : migration vers les nouveaux chemins des Caméras simulées.
  • Mêmes règles qu'avant : jamais d'effacement de la base, noms uniques par test puis nettoyage.

Out of Scope​

  • Adresse MAC (détection, saisie manuelle, identité stable) : 0.4.2.
  • ONVIF (GetStreamUri, profils), PTZ.
  • Chiffrement des identifiants en base, HTTPS, authentification des Flux MediaMTX (Aperçu compris).
  • Lecture du H.265 dans le navigateur (réencodage ou autre transport) : « Codecs multiples ».
  • Test de mots de passe par défaut, réessai automatique.
  • Choix entre flux principal et secondaire par l'Administrateur.

Further Notes​

  • La plupart des caméras répondent 401 à un DESCRIBE avant de vérifier le chemin : c'est pourquoi les identifiants sont demandés avant le repli par chemin.
  • Contexte : feuille de route de dev (section 0.4.1), spec 0.4.0 (#18), ADR 0001 et 0002, docs/securite.md, docs/cameras/reseau-et-detection.md, media/simulated/README.md.