Kami Fall Detection (Cloud)

Detect fall events from RTSP camera streams using the KamiClaw cloud API. No local GPU needed — all inference runs server-side.

🚀 Quick Start

1. Get API key → https://kamiclaw-skill.kamihome.com (200 free credits for new users)
2. Tell the agent: Your API key + RTSP camera URL
3. Choose notifications: Feishu / Telegram / Discord (any combination)
4. Agent configures everything automatically
5. Run! → Monitors 24/7, alerts instantly on fall detection

What It Does

• 🎥 Monitors RTSP camera streams continuously
• 🧠 Uses cloud AI to detect fall events (active falling, fallen posture, etc.)
• 📱 Sends instant notifications via Feishu, Telegram, or Discord
• 💾 Saves alarm video clips for review (optional)
• 🔄 Auto-reconnects if stream drops

🔒 Privacy & Data Policy

In short: Only 8-second alarm clips are sent to the cloud for AI analysis. No continuous streaming, no audio, no full video.

📄 Full details: Read our Privacy Policy for complete information on data handling, retention, and your rights.

Quick Tips

• Disable local storage: Set save_alarm_clips: false to not save clips locally
• Clean up old files: find logs/clips/ -type f -mtime +30 -delete
• Protect your API key: Never commit config.json to git

ℹ️ AI analysis requires sending alarm clips to the cloud API. Processed clips are retained per the provider's data retention policy.

Configuration

All settings are in config.json. The agent auto-fills this when you provide values in chat.

Essential Settings

Camera Setup

All cameras are declared in the cameras array. Each entry has just two fields: name and rtsp_url.

Single camera (one entry). name is optional — if omitted it defaults to "default":

{
  "cameras": [
    { "rtsp_url": "rtsp://192.168.1.100/live/stream" }
  ]
}

Multiple cameras (two or more entries). Every entry must have a unique, non-empty name. Strongly recommended: pick a meaningful location label so the operator immediately knows which camera triggered.

{
  "cameras": [
    { "name": "front_door", "rtsp_url": "rtsp://192.168.1.101/live/stream" },
    { "name": "backyard",   "rtsp_url": "rtsp://192.168.1.102/live/stream" }
  ]
}

• name is shown in every Feishu / Telegram / Discord push and tags every log line.
• One worker thread per camera; a single stream loss does not affect the others.
• The skill refuses to start if cameras is empty, or if multiple entries are missing/sharing a name.

Common Brand RTSP Templates

MUST show this table to the user when configuring cameras, so they can pick a URL pattern based on their brand:

Advanced Settings

Notification Setup

Tell the agent which channels you want. They'll guide you through setup.

Quick Guide

💡 Discord: Bot token + channel ID gives you full two-way capability. Webhook is simpler for push-only.

💡 Need help? Ask OpenClaw for guidance.

Running

# With config.json (recommended)
.venv/bin/python fall_detect_cloud_skill.py

# Or override the API key on the CLI
.venv/bin/python fall_detect_cloud_skill.py \
    --api_key sk_live_xxxxxxxx

Cameras are always declared in config.json under the cameras array — there is no CLI flag for the RTSP URL.

The skill runs continuously. It does NOT stop after an alarm — it resets and keeps monitoring.

Output Format

Fall detected:

{
  "alarm": true,
  "type": "fall",
  "camera_name": "front_door",
  "fall_type": "active_falling",
  "num_persons": 1,
  "confidence": 0.92,
  "reason": "Person collapsed from standing to floor near bed",
  "frame": 87,
  "source": "rtsp://192.168.1.101/live/stream",
  "clip": "logs/clips/alarm_fall_20260429_143201.mp4"
}

Normal exit (run time reached):

{
  "alarm": false,
  "type": null,
  "detail": "Run time limit reached, no fall detected",
  "frames_processed": 3600,
  "source": "rtsp://192.168.1.100/live/stream"
}

Exit Codes

Advanced: How It Works

Stage 1 — Change Detection (Local, CPU-only)

• Lightweight frame-differencing on 128×128 grayscale
• Maintains rolling pre-buffer (default 4s)
• Triggers Stage 2 on significant temporal change

Stage 2 — Cloud Analysis

• Collects post-transition frames (default 4s)
• Resizes clip to 360×360, writes to temp file
• Sends to KamiClaw API (detectType: FALL, detectSubType: SK_FALL_DETECTION)
• On fall detected: outputs JSON alarm, optionally saves clip, resets to Stage 1

Auto-Reconnect

• If RTSP stream drops, retries connection every 5 seconds
• Resumes monitoring seamlessly after reconnection

Agent Setup Flow

For agents configuring this skill:

1. Read config.json — check whether api_key is set and whether cameras is a non-empty array.
2. If api_key is empty, ask the user: "Please provide your KamiClaw API key. Register at https://kamiclaw-skill.kamihome.com".
3. If cameras is empty, ask: "How many RTSP cameras do you want to monitor?"
   • One camera: ask only for the RTSP URL. Write [ { "rtsp_url": "..." } ] — name will default to "default" automatically.
   • Two or more cameras: for each one, ask both the RTSP URL and a unique short location label (e.g. front_door, backyard, living_room). Strongly recommend the user picks meaningful labels — they are shown in every alarm notification. Write [ { "name": "front_door", "rtsp_url": "..." }, { "name": "backyard", "rtsp_url": "..." } ].
4. Ask: "Save alarm video clips? (yes/no, default: yes)" → set save_alarm_clips.
5. Ask about each notification channel (Feishu / Telegram / Discord) — guide setup if yes.
6. Write all values to config.json (read existing, merge, write back).
7. Optionally run python fall_detect_cloud_skill.py --list_cameras to confirm the resolved camera list.
8. Run the skill.

Never run with an empty api_key. Never run with cameras empty. When the user has multiple cameras, never accept missing/duplicate names — re-prompt until each camera has a unique label. Never ask the user to manually edit config.json.

Troubleshooting & Analysis

Log Files

Quick Analysis Commands

# Count alarms today
grep '"alarm"' logs/alarms.jsonl | grep "$(date +%Y-%m-%d)" | wc -l

# Transitions vs alarms (false positive rate)
wc -l logs/transitions.jsonl logs/alarms.jsonl

# Export alarms as CSV
cat logs/alarms.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    obj = json.loads(line)
    if obj.get('event') == 'alarm':
        print(f\"{obj['_ts']},{obj.get('type','')},{obj.get('fall_type','')},{obj.get('confidence',0)},{obj.get('frame',0)}\")
"

Common Issues

File Structure

kami-fall-detection/
├── SKILL.md                      # Documentation
├── config.json                   # Configuration (auto-managed by agent)
├── fall_detect_cloud_skill.py    # Production entry point
├── setup.sh                      # Installer
└── requirements.txt              # Dependencies