Documentation

Installation APK

Kass 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>:8181/api/system/status

{
  "is_recording": false,
  "cameras_connected": 1,
  "storage_free_gb": 184,
  "mqtt_connected": false,
  "rtsp_active": false
}

curl -X POST http://<IP_ANDROID>:8181/api/record/start \
  -H "Content-Type: application/json" \
  -d '{"camera": 0, "mode": "continuous"}'

Paramètres généraux

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

Port API HTTP

Le port par défaut de l'API HTTP est 8181. Vous pouvez le modifier dans les paramètres de l'application :

POST /api/system/config
{
  "api_port": 9090
}

Paramètres disponibles

Notifications

Kass Recorder peut envoyer des notifications Android et des alertes MQTT sur différents événements.

kass/recorder/cam0/motion

{
  "detected": true,
  "camera": 0,
  "timestamp": "2024-01-01T12:00:00Z"
}

Caméras UVC

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

Caméras testées

Hub OTG

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

GET /api/system/status

// Réponse
{
  "cameras_connected": 3,
  "camera_list": [
    {"index": 0, "name": "Logitech C920", "active": true},
    {"index": 1, "name": "ELP-USB", "active": true},
    {"index": 2, "name": "Generic UVC", "active": true}
  ]
}

Réglages UVC

Les caméras UVC exposent des contrôles matériels accessibles via l'API. Les paramètres disponibles varient selon le modèle de caméra.

GET /api/uvc/capabilities?camera=0

{
  "supports_zoom": true,
  "supports_focus": false,
  "brightness_range": [-64, 64],
  "contrast_range": [0, 100],
  "kelvin_range": [2800, 6500]
}

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

L'API Kass Recorder repose sur un dictionnaire de commandes unifié — la même action peut être déclenchée via HTTP REST, MQTT ou Android Intent.

Format des requêtes HTTP

Toutes les requêtes acceptent et retournent du JSON. L'authentification est optionnelle (token Bearer).

POST http://<IP_ANDROID>:8181/api/record/start
Content-Type: application/json

{
  "camera": 0,
  "mode": "continuous"
}

{
  "success": true,
  "is_recording": true,
  "camera": 0
}

Codes de statut HTTP

RTSP / MediaMTX

Kass Recorder intègre MediaMTX pour publier les flux RTSP consommables par VLC, Home Assistant, NVR, ou tout client RTSP standard.

POST /api/stream/rtsp/start
{
  "camera": 0,
  "path": "cam0"
}

// Réponse
{
  "success": true,
  "rtsp_url": "rtsp://192.168.1.50:8554/cam0"
}

Lire dans VLC

vlc rtsp://192.168.1.50:8554/cam0

HTTP MJPEG

Le serveur MJPEG local permet d'afficher le flux vidéo directement dans un navigateur ou une image Home Assistant sans configuration supplémentaire.

POST /api/stream/mjpeg/start
{
  "camera": 0,
  "port": 8080
}

// URL du flux
http://192.168.1.50:8080/stream

Intégration Home Assistant

camera:
  - platform: mjpeg
    name: Kass Cam 0
    mjpeg_url: http://192.168.1.50:8080/stream

MQTT

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

POST /api/mqtt/broker
{
  "host": "192.168.1.10",
  "port": 1883,
  "username": "kass",
  "password": "secret"
}

Topics publiés (état)

Topics de commande (souscription)

// Topic : kass/recorder/command
// Payload :
{
  "action": "start_recording",
  "camera": 0,
  "mode": "motion"
}

Warden Engine

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

Triggers disponibles

POST /api/warden/rules
{
  "trigger": "motion",
  "rule_action": "start_recording",
  "condition": {
    "camera": 0,
    "sensitivity_min": 5
  }
}

// Réponse
{
  "success": true,
  "rule_id": "rule_abc123"
}

Tasker / MacroDroid

Kass Recorder expose des Android Intentsque Tasker ou MacroDroid peuvent déclencher. Vous pouvez aussi appeler l'API HTTP directement depuis ces apps.

Intents supportés

POST /api/automation/intent
{
  "intent_action": "com.kass.recorder.START",
  "extras": {
    "camera": "0",
    "mode": "motion"
  }
}

Home Assistant

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

automation:
  - alias: "Kass - Enregistrer sur sonnette"
    trigger:
      platform: state
      entity_id: binary_sensor.doorbell
      to: "on"
    action:
      service: mqtt.publish
      data:
        topic: kass/recorder/command
        payload: '{"action": "start_recording", "camera": 0}'

camera:
  - platform: mjpeg
    name: Kass Cam Entrée
    mjpeg_url: http://192.168.1.50:8080/stream
    still_image_url: http://192.168.1.50:8080/snapshot

S3 / MinIO

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

POST /api/automation/s3/config
{
  "endpoint": "https://minio.local:9000",
  "bucket": "surveillance",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1"
}

Options d'upload

POST /api/automation/upload
{
  "wifi_only": true
}

// Réponse
{
  "success": true,
  "files_queued": 12
}

Stockage local

Kass Recorder gère 3 niveaux de stockage avec fallback automatique silencieux: l'enregistrement continue sans interruption même si un support est plein.

GET /api/system/storage

{
  "usb_free_gb": 184,
  "sd_free_gb": 32,
  "internal_free_gb": 8,
  "active_storage": "usb",
  "priority": ["usb", "sd", "internal"]
}

Dépannage

Solutions aux problèmes les plus fréquents.

Problèmes connus

Limitations connues et comportements attendus.