Documentation

Installation APK

K7 Recorder s'installe directement depuis le fichier APK — aucun store requis.

Première connexion

Connectez votre première caméra UVC et vérifiez que l'API répond correctement.

curl http://<IP_ANDROID>:8080/api/cameras

{
  "cameras": [
    {
      "id": 1003,
      "cameraId": 1003,
      "name": "USB Camera",
      "resolution": "1920x1080",
      "fps": 24,
      "isRecording": false,
      "recordingMode": "CONTINUOUS",
      "streamUrl": "/camera/1003/stream",
      "snapshotUrl": "/camera/1003/snapshot"
    }
  ],
  "count": 1
}

curl -X POST \
  http://<IP_ANDROID>:8080/camera/1003/api/recording/start

Paramètres généraux

Configurez les paramètres globaux de K7 Recorder via l'interface ou l'API.

Serveur HTTP local

Le serveur HTTP local est désactivé par défaut et écoute sur le port 8080 une fois démarré. Il n'a pas de couche d'authentification : l'isolation vient du tunnel VPN, il ne doit pas être exposé hors de ce périmètre.

{
  "action": "start_http_server",
  "params": { "port": 8080 },
  "request_id": "a1b2c3d4"
}

Paramètres disponibles

Événements publiés

K7 Recorder publie son état et ses événements sur MQTT, sans qu'on ait à l'interroger. Les alertes applicatives arrivent sur le topic d'alerte de la caméra concernée.

camera/1003/motion

{
  "device_id": "<ANDROID_ID>",
  "cameraId": 1003,
  "event": "motion_started",
  "motionPercent": 4.2,
  "timestamp": 1756108800000
}

Caméras UVC

K7 Recorder supporte toutes les caméras conformes au standard USB Video Class (UVC). La plupart des webcams modernes sont UVC compatibles.

Hub OTG

Pour connecter plusieurs caméras, utilisez un hub USB OTG alimenté (recommandé : alimentation externe 5V/3A minimum).

{
  "action": "refresh_cameras",
  "request_id": "a1b2c3d4"
}

// Les caméras découvertes sont republiées sur
// device/{phoneId}/cameras/list

Réglages UVC

Les caméras UVC exposent des contrôles matériels pilotables à distance. Les paramètres réellement disponibles varient d'un modèle à l'autre : interrogez la caméra plutôt que de supposer.

{
  "action": "get_capabilities",
  "params": { "camera": 1003 },
  "request_id": "a1b2c3d4"
}

// Réponse sur camera/1003/response, puis état
// complet retenu sur camera/1003/capabilities

La balance des blancs automatique (Auto Kelvin) utilise le capteur de luminosité Lux pour adapter la température de couleur en temps réel selon les conditions d'éclairage.

Concepts API

K7 Recorder repose sur un dictionnaire de commandes unique. La même action se déclenche par MQTT ou par broadcast Android — les deux voies passent par le même routeur de commandes. Le serveur HTTP local est un canal distinct, avec ses propres routes.

Enveloppe des commandes MQTT

Une commande est un message JSON : l'action, ses paramètres, et un request_id qui corrèle la réponse. Sans request_id, la réponse ne peut pas être rattachée à la commande.

// topic : device/{phoneId}/cameras/1003/command
{
  "action": "start_recording",
  "params": {
    "camera": 1003,
    "mode": "continuous"
  },
  "request_id": "a1b2c3d4"
}

// topic : camera/1003/response
{
  "action": "start_recording",
  "success": true,
  "deviceId": 1003,
  "device_id": "<ANDROID_ID>",
  "request_id": "a1b2c3d4",
  "timestamp": 1756108800000
}

Codes d'erreur des réponses

Diffusion SRT / RTSP

Le téléphone pousse son flux vers un serveur MediaMTX — qui tourne sur votre infrastructure, pas sur le téléphone. MediaMTX le republie ensuite en RTSP, WebRTC ou HLS pour VLC, Home Assistant, un NVR ou un navigateur. Le transport par défaut est SRT ; RTSP reste disponible.

// topic : device/{phoneId}/cameras/1003/command
{
  "action": "start_rtsp_streaming",
  "params": {
    "camera": 1003,
    "transport": "SRT"
  },
  "request_id": "a1b2c3d4"
}

Lire dans VLC

vlc rtsp://<IP_MEDIAMTX>:8554/<chemin_publie>

HTTP MJPEG

Le serveur HTTP local sert un flux MJPEG et des snapshots, affichables directement dans un navigateur ou une entité caméra Home Assistant. Il est désactivé par défaut et écoute sur le port 8080 une fois démarré.

// 1. démarrer le serveur HTTP local (MQTT)
{
  "action": "start_http_server",
  "params": { "port": 8080 },
  "request_id": "a1b2c3d4"
}

// 2. flux et image fixe, par caméra
http://<IP_ANDROID>:8080/camera/1003/stream
http://<IP_ANDROID>:8080/camera/1003/snapshot

Intégration Home Assistant

camera:
  - platform: mjpeg
    name: K7 Cam
    mjpeg_url: http://<IP_ANDROID>:8080/camera/1003/stream
    still_image_url: http://<IP_ANDROID>:8080/camera/1003/snapshot

MQTT

L'intégration MQTT est bi-directionnelle : K7 Recorder publie des événements et reçoit des commandes sur le même broker.

// Le broker est provisionné avec l'appareil.
// Les identifiants se changent à distance :
{
  "action": "set_mqtt_credentials",
  "params": {
    "username": "kass",
    "password": "…"
  },
  "request_id": "a1b2c3d4"
}

Topics publiés (état et événements)

Topics de commande (souscrits par le téléphone)

// topic : device/{phoneId}/cameras/{cameraId}/command
{
  "action": "start_recording",
  "params": {
    "camera": 1003,
    "mode": "motion"
  },
  "request_id": "a1b2c3d4"
}

Warden Engine

Le Warden Engine est le moteur d'automatisation intégré à K7 Recorder. Il permet de créer des règles trigger → action sans dépendance externe.

Triggers disponibles

// topic : device/{phoneId}/cameras/0/command
{
  "action": "warden_create_profile",
  "params": { "name": "Garde de nuit" },
  "request_id": "a1b2c3d4"
}

// puis lier le profil à une caméra
{
  "action": "warden_assign_camera",
  "params": { "profile_id": "12", "camera": 1003 },
  "request_id": "b2c3d4e5"
}

Tasker / MacroDroid

K7 Recorder écoute des broadcasts Android que Tasker ou MacroDroid peuvent émettre. La voie principale est un broadcast unique, com.kass.recorder.ACTION_CONTROL, dont l'extra command porte le nom de l'action — le même dictionnaire qu'en MQTT. Quelques actions ont aussi leur broadcast dédié.

Broadcasts supportés

Les extras sont transmis en chaînes de caractères — c'est ce que Tasker sait produire. Sur un montage multi-caméras, camera_id est obligatoire : sans lui, une action liée à une caméra est rejetée plutôt que routée au hasard.

am broadcast -p com.kass.recorder \
  -a com.kass.recorder.ACTION_CONTROL \
  --es command start_recording \
  --es camera_id 1003 \
  --es mode motion

Home Assistant

Intégrez K7 Recorder dans Home Assistant via MQTT et MJPEG. Créez des automatisations depuis les événements de surveillance.

automation:
  - alias: "K7 - Record on doorbell"
    trigger:
      platform: state
      entity_id: binary_sensor.doorbell
      to: "on"
    action:
      service: mqtt.publish
      data:
        topic: device/{phoneId}/cameras/1003/command
        payload: >-
          {"action": "start_recording",
           "params": {"camera": 1003},
           "request_id": "{{ now().timestamp() }}"}

camera:
  - platform: mjpeg
    name: K7 Cam Entrance
    mjpeg_url: http://<IP_ANDROID>:8080/camera/1003/stream
    still_image_url: http://<IP_ANDROID>:8080/camera/1003/snapshot

S3 / MinIO

K7 Recorder peut exporter automatiquement les enregistrements vers un bucket S3 (AWS) ou une instance MinIO auto-hébergée. L'upload supporte la reprise sur interruption (chunked upload).

{
  "action": "configure_s3",
  "params": {
    "endpoint": "https://minio.local:9000",
    "bucket": "surveillance",
    "access_key": "…",
    "secret_key": "…",
    "region": "us-east-1",
    "wifi_only": true
  },
  "request_id": "a1b2c3d4"
}

Options d'upload

{
  "action": "upload_last_video",
  "request_id": "a1b2c3d4"
}

// état de la file et de la configuration
{
  "action": "get_s3_status",
  "request_id": "b2c3d4e5"
}

Stockage local

K7 Recorder gère trois supports d'écriture avec bascule automatique silencieuse : l'enregistrement continue sans interruption même si un support est plein. L'ordre de priorité est configurable ; par défaut, le stockage interne passe en premier.

{
  "action": "get_storage_stats",
  "request_id": "a1b2c3d4"
}

// L'espace libre est aussi publié en continu sur
// device/{phoneId}/storage

Dépannage

Solutions aux problèmes les plus fréquents.

Problèmes connus

Limitations connues et comportements attendus.