homesec 1.2.0__py3-none-any.whl → 1.2.2__py3-none-any.whl

homesec/sources/rtsp/recorder.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import logging
+import subprocess
+from pathlib import Path
+from typing import Protocol
+
+from homesec.sources.rtsp.clock import Clock
+from homesec.sources.rtsp.utils import _format_cmd, _is_timeout_option_error, _redact_rtsp_url
+
+logger = logging.getLogger(__name__)
+
+
+class Recorder(Protocol):
+    def start(self, output_file: Path, stderr_log: Path) -> subprocess.Popen[bytes] | None: ...
+
+    def stop(self, proc: subprocess.Popen[bytes], output_file: Path | None) -> None: ...
+
+    def is_alive(self, proc: subprocess.Popen[bytes]) -> bool: ...
+
+
+class FfmpegRecorder:
+    def __init__(
+        self,
+        *,
+        rtsp_url: str,
+        ffmpeg_flags: list[str],
+        rtsp_connect_timeout_s: float,
+        rtsp_io_timeout_s: float,
+        clock: Clock,
+    ) -> None:
+        self._rtsp_url = rtsp_url
+        self._ffmpeg_flags = ffmpeg_flags
+        self._rtsp_connect_timeout_s = rtsp_connect_timeout_s
+        self._rtsp_io_timeout_s = rtsp_io_timeout_s
+        self._clock = clock
+
+    def start(self, output_file: Path, stderr_log: Path) -> subprocess.Popen[bytes] | None:
+        def _read_tail(path: Path, max_bytes: int = 4000) -> str:
+            try:
+                data = path.read_bytes()
+            except Exception as exc:
+                logger.warning("Failed to read recording stderr tail: %s", exc, exc_info=True)
+                return ""
+            if len(data) <= max_bytes:
+                return data.decode(errors="replace")
+            return data[-max_bytes:].decode(errors="replace")
+
+        cmd_base = [
+            "ffmpeg",
+            "-rtsp_transport",
+            "tcp",
+            "-rtsp_flags",
+            "prefer_tcp",
+            "-user_agent",
+            "Lavf",
+        ]
+
+        user_flags = self._ffmpeg_flags
+        has_stimeout = any(x == "-stimeout" for x in user_flags)
+        has_rw_timeout = any(x == "-rw_timeout" for x in user_flags)
+        timeout_us_connect = str(int(max(0.1, self._rtsp_connect_timeout_s) * 1_000_000))
+        timeout_us_io = str(int(max(0.1, self._rtsp_io_timeout_s) * 1_000_000))
+
+        timeout_args: list[str] = []
+        if not has_stimeout and self._rtsp_connect_timeout_s > 0:
+            timeout_args.extend(["-stimeout", timeout_us_connect])
+        if not has_rw_timeout and self._rtsp_io_timeout_s > 0:
+            timeout_args.extend(["-rw_timeout", timeout_us_io])
+
+        cmd_tail = ["-i", self._rtsp_url, "-c", "copy", "-f", "mp4", "-y"]
+
+        # Naive check to see if user overrode defaults
+        # If user supplies ANY -loglevel, we don't add ours.
+        # If user supplies ANY -fflags, we don't add ours (to avoid concatenation complexity).
+        # This allows full user control.
+        has_loglevel = any(x == "-loglevel" for x in user_flags)
+        if not has_loglevel:
+            cmd_tail.extend(["-loglevel", "warning"])
+
+        has_fflags = any(x == "-fflags" for x in user_flags)
+        if not has_fflags:
+            cmd_tail.extend(["-fflags", "+genpts+igndts"])
+
+        has_fps_mode = any(x == "-fps_mode" or x == "-vsync" for x in user_flags)
+        if not has_fps_mode:
+            cmd_tail.extend(["-vsync", "0"])
+
+        # Add user flags last so they can potentially override or add to the above
+        cmd_tail.extend(user_flags)
+        cmd_tail.extend([str(output_file)])
+
+        attempts: list[tuple[str, list[str]]] = []
+        if timeout_args:
+            attempts.append(("timeouts", timeout_args))
+        attempts.append(("no_timeouts" if timeout_args else "default", []))
+
+        for label, extra_args in attempts:
+            cmd = list(cmd_base) + list(extra_args) + cmd_tail
+
+            safe_cmd = list(cmd)
+            try:
+                idx = safe_cmd.index("-i")
+                safe_cmd[idx + 1] = _redact_rtsp_url(str(safe_cmd[idx + 1]))
+            except Exception as exc:
+                logger.warning("Failed to redact recording RTSP URL: %s", exc, exc_info=True)
+            logger.debug("Recording ffmpeg (%s): %s", label, _format_cmd(safe_cmd))
+
+            try:
+                with open(stderr_log, "w") as stderr_file:
+                    proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=stderr_file)
+
+                self._clock.sleep(0.5)
+                if proc.poll() is None:
+                    return proc
+
+                stderr_tail = _read_tail(stderr_log)
+                timeout_option_error = (
+                    label == "timeouts"
+                    and bool(stderr_tail)
+                    and _is_timeout_option_error(stderr_tail)
+                )
+
+                if timeout_option_error:
+                    logger.warning(
+                        "Recording process died immediately (%s, exit code: %s); timeout options unsupported",
+                        label,
+                        proc.returncode,
+                    )
+                    logger.warning("Check logs at: %s", stderr_log)
+                else:
+                    logger.error(
+                        "Recording process died immediately (%s, exit code: %s)",
+                        label,
+                        proc.returncode,
+                    )
+                    logger.error("Check logs at: %s", stderr_log)
+
+                if stderr_tail:
+                    redacted_tail = stderr_tail.replace(
+                        self._rtsp_url, _redact_rtsp_url(self._rtsp_url)
+                    )
+                    if timeout_option_error:
+                        logger.warning("Recording stderr tail (%s):\n%s", label, redacted_tail)
+                        logger.warning(
+                            "Recording ffmpeg missing timeout options; retrying without timeouts"
+                        )
+                        continue
+                    logger.error("Recording stderr tail (%s):\n%s", label, redacted_tail)
+                if label == "timeouts":
+                    return None
+            except Exception:
+                logger.exception("Failed to start recording")
+                return None
+
+        return None
+
+    def stop(self, proc: subprocess.Popen[bytes], output_file: Path | None) -> None:
+        try:
+            if proc.poll() is None:
+                proc.terminate()
+                proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            logger.warning("Recording process did not terminate, killing (PID: %s)", proc.pid)
+            try:
+                proc.kill()
+                proc.wait(timeout=2)
+            except Exception:
+                logger.exception("Failed to kill recording process (PID: %s)", proc.pid)
+        except Exception:
+            logger.exception("Failed while stopping recording process (PID: %s)", proc.pid)
+
+        logger.debug(
+            "Stopped recording: %s",
+            output_file,
+            extra={"recording_id": output_file.name if output_file else None},
+        )
+
+    def is_alive(self, proc: subprocess.Popen[bytes]) -> bool:
+        return proc.poll() is None

homesec/sources/rtsp/utils.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import logging
+import shlex
+
+logger = logging.getLogger(__name__)
+
+
+def _redact_rtsp_url(url: str) -> str:
+    if "://" not in url:
+        return url
+    scheme, rest = url.split("://", 1)
+    if "@" not in rest:
+        return url
+    _creds, host = rest.split("@", 1)
+    return f"{scheme}://***:***@{host}"
+
+
+def _format_cmd(cmd: list[str]) -> str:
+    try:
+        return shlex.join([str(x) for x in cmd])
+    except Exception as exc:
+        logger.warning("Failed to format command with shlex.join: %s", exc, exc_info=True)
+        return " ".join([str(x) for x in cmd])
+
+
+def _is_timeout_option_error(stderr_text: str) -> bool:
+    text = stderr_text.lower()
+    return ("rw_timeout" in text and ("not found" in text or "unrecognized option" in text)) or (
+        "stimeout" in text and ("not found" in text or "unrecognized option" in text)
+    )
+
+
+def _next_backoff(backoff_s: float, cap_s: float, *, factor: float = 1.6) -> float:
+    return min(backoff_s * factor, cap_s)

{homesec-1.2.0.dist-info → homesec-1.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: homesec
-Version: 1.2.0
+Version: 1.2.2
 Summary: Pluggable async home security camera pipeline with detection, VLM analysis, and alerts.
 Project-URL: Homepage, https://github.com/lan17/homesec
 Project-URL: Source, https://github.com/lan17/homesec
@@ -243,25 +243,70 @@ Description-Content-Type: text/markdown
 
 # HomeSec
 
+[![PyPI](https://img.shields.io/pypi/v/homesec)](https://pypi.org/project/homesec/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Python: 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
 [![Typing: Typed](https://img.shields.io/badge/typing-typed-2b825b)](https://peps.python.org/pep-0561/)
 [![codecov](https://codecov.io/gh/lan17/HomeSec/branch/main/graph/badge.svg)](https://codecov.io/gh/lan17/HomeSec)
 
-HomeSec is a self-hosted, extensible network video recorder that puts you in control. Store clips wherever you want, analyze them with AI, and get smart notifications—all while keeping your footage private and off third-party clouds.
+HomeSec is a self-hosted, extensible video pipeline for home security cameras. You can connect cameras directly via RTSP, receive clips over FTP, or implement your own ClipSource. From there, the pipeline filters events with AI and sends smart notifications. Your footage stays private and off third-party clouds.
+
+## Design Principles
+
+- **Local-Only Data Processing**: Video footage remains on the local network by default. Cloud usage (Storage, VLM/OpenAI) is strictly opt-in.
+- **Modular Architecture**: All major components (sources, filters, analyzers, notifiers) are decoupled plugins defined by strict interfaces. If you want to use a different AI model or storage backend, you can swap it out with a few lines of Python.
+- **Resilience**: The primary resilience feature is backing up clips to storage. The pipeline handles intermittent stream failures and network instability without crashing or stalling.
+
+## Pipeline at a glance
+
+
+
+```mermaid
+graph TD
+    %% Layout Wrapper for horizontal alignment
+    subgraph Wrapper [" "]
+        direction LR
+        style Wrapper fill:none,stroke:none
+        
+        S[Clip Source]
+        
+        subgraph Pipeline [Media Processing Pipeline]
+            direction TB
+            C(Clip File) --> U([Upload to Storage])
+            C --> F([Detect objects: YOLO])
+            F -->|Detected objects| AI{Trigger classes filter}
+            AI -->|Yes| V([VLM Analysis])
+            AI -->|No| D([Discard])
+            V -->|Risk level, detected objects| P{Alert Policy filter}
+            P -->|No| D
+            P -->|YES| N[Notifiers]
+        end
+        
+        S -->|New Clip File| Pipeline
+        
+        PG[(Postgres)]
+        Pipeline -.->|State & Events| PG
+    end
+```
+
+- **Parallel Processing**: Upload and filter run in parallel.
+- **Resilience**: Upload failures do not block alerts; filter failures stop expensive VLM calls.
+- **State**: Metadata is stored in Postgres (`clip_states` + `clip_events`) for full observability.
 
-Under the hood, it's a pluggable async pipeline for home security cameras. It records short clips, runs object detection, optionally calls a vision-language model ([VLM](https://en.wikipedia.org/wiki/Vision%E2%80%93language_model)) for a structured summary, and sends alerts via [MQTT](https://en.wikipedia.org/wiki/MQTT) or email. The design prioritizes reliability and extensibility.
 
 ## Table of Contents
 
 - [Highlights](#highlights)
 - [Pipeline at a glance](#pipeline-at-a-glance)
 - [Quickstart](#quickstart)
+  - [30-Second Start (Docker)](#30-second-start-docker)
+  - [Manual Setup](#manual-setup)
 - [Configuration](#configuration)
-- [Extensible by design](#extensible-by-design)
-- [CLI](#cli)
-- [Built-in plugins](#built-in-plugins)
-- [Writing a plugin](#writing-a-plugin)
+  - [Commands](#commands)
+- [Plugins](#plugins)
+  - [Built-in plugins](#built-in-plugins)
+  - [Plugin interfaces](#plugin-interfaces)
+  - [Writing a custom plugin](#writing-a-custom-plugin)
 - [Observability](#observability)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -270,227 +315,231 @@ Under the hood, it's a pluggable async pipeline for home security cameras. It re
 ## Highlights
 
 - Multiple pluggable video clip sources: [RTSP](https://en.wikipedia.org/wiki/Real-Time_Streaming_Protocol) motion detection, [FTP](https://en.wikipedia.org/wiki/File_Transfer_Protocol) uploads, or a watched folder
-- Parallel upload + filter ([YOLOv8](https://en.wikipedia.org/wiki/You_Only_Look_Once)) with frame sampling and early exit
+- Parallel upload + filter ([YOLO](https://en.wikipedia.org/wiki/You_Only_Look_Once)) with frame sampling and early exit
 - OpenAI-compatible VLM analysis with structured output
 - Policy-driven alerts with per-camera overrides
 - Fan-out notifiers (MQTT for Home Assistant, SendGrid email)
 - Postgres-backed state + events with graceful degradation
-- Built around small, stable interfaces so new plugins drop in cleanly
 - Health endpoint plus optional Postgres telemetry logging
 
-## Pipeline at a glance
 
-```
-ClipSource -> (Upload + Filter) -> VLM (optional) -> Alert Policy -> Notifier(s)
-```
-
-- Upload and filter run in parallel; VLM runs only when trigger classes are detected.
-- Upload failures do not block alerts; filter failures stop processing.
-- State is stored in Postgres (`clip_states` + `clip_events`) when available.
 
 ## Quickstart
 
-### Requirements
+### 30-Second Start (Docker)
+The fastest way to see it in action. Includes a pre-configured Postgres and a dummy local source.
+
+```bash
+git clone https://github.com/lan17/homesec.git
+cd homesec
+make up
+```
+*Modify `config/config.yaml` to add your real cameras, then restart.*
 
-- Raspberry Pi 4 (or equivalent) or higher; any x86_64 system works as well
-- Docker and Docker Compose
-- Optional: MQTT broker, Dropbox credentials, OpenAI-compatible API key
+### Manual Setup
+For standard production usage without Docker Compose:
 
-### Setup
+1. **Prerequisites**:
+   - Python 3.10+
+   - ffmpeg
+   - PostgreSQL (running and accessible)
 
-1. Create a config file:
+2. **Install**
    ```bash
-   cp config/example.yaml config/config.yaml
-   # Edit config/config.yaml with your settings
+   pip install homesec
    ```
-2. Set environment variables:
+
+3. **Configure**
    ```bash
-   cp .env.example .env
-   # Edit .env with your credentials
+   # Download example config & env
+   curl -O https://raw.githubusercontent.com/lan17/homesec/main/config/example.yaml
+   mv example.yaml config.yaml
+   
+   curl -O https://raw.githubusercontent.com/lan17/homesec/main/.env.example
+   mv .env.example .env
+
+   # Setup environment (DB_DSN is required)
+   # Edit .env to set your secrets!
+   export DB_DSN="postgresql://user:pass@localhost/homesec"
    ```
-3. Start HomeSec + Postgres:
+
+4. **Run**
    ```bash
-   make up
+   homesec run --config config.yaml
    ```
-4. Stop:
+
+### Developer Setup
+If you are contributing or running from source:
+
+1. **Install dependencies**
    ```bash
-   make down
+   uv sync
    ```
 
-### Running without Docker
+2. **Start Infrastructure**
+   ```bash
+   make db  # Starts just Postgres in Docker
+   ```
 
-If you prefer to run locally:
+3. **Run**
+   ```bash
+   uv run python -m homesec.cli run --config config/config.yaml
+   ```
 
-1. Install Python 3.10+ and ffmpeg
-2. `uv sync`
-3. `make db` (starts Postgres)
-4. `make run`
 
 ## Configuration
 
-Configs are YAML and validated with Pydantic. See `config/example.yaml` for all options.
+Configuration is YAML-based and strictly validated. Secrets (API keys, passwords) should always be loaded from environment variables (`_env` suffix).
 
-Minimal example (RTSP + Dropbox + MQTT):
+### Configuration Examples
 
-```yaml
-version: 1
+#### 1. The "Power User" (Robust RTSP)
+Best for real-world setups with flaky cameras.
 
+```yaml
 cameras:
-  - name: front_door
+  - name: driveway
     source:
       type: rtsp
       config:
-        rtsp_url_env: FRONT_DOOR_RTSP_URL
+        rtsp_url_env: DRIVEWAY_RTSP_URL
         output_dir: "./recordings"
+        stream:
+          # Critical for camera compatibility:
+          ffmpeg_flags: ["-rtsp_transport", "tcp", "-vsync", "0"]
+        reconnect:
+          backoff_s: 5
 
+filter:
+  plugin: yolo
+  config:
+    classes: ["person", "car"]
+    min_confidence: 0.6
+```
+
+In your `.env`:
+```bash
+DRIVEWAY_RTSP_URL="rtsp://user:pass@192.168.1.100:554/stream"
+```
+
+#### 2. The "Cloud Storage" (Dropbox)
+Uploads to Cloud but keeps analysis local.
+
+```yaml
 storage:
   backend: dropbox
   dropbox:
-    root: "/homecam"
     token_env: DROPBOX_TOKEN
-    app_key_env: DROPBOX_APP_KEY
-    app_secret_env: DROPBOX_APP_SECRET
-    refresh_token_env: DROPBOX_REFRESH_TOKEN
-
-state_store:
-  dsn_env: DB_DSN
+    root: "/SecurityCam"
 
 notifiers:
-  - backend: mqtt
-    config:
-      host: "localhost"
-      port: 1883
+    - backend: sendgrid_email
+      config:
+        api_key_env: SENDGRID_API_KEY
+        to_emails: ["me@example.com"]
+```
 
-filter:
-  plugin: yolo
-  config:
-    classes: ["person"]
-    min_confidence: 0.5
-
-vlm:
-  backend: openai
-  llm:
-    api_key_env: OPENAI_API_KEY
-    model: gpt-4o
-
-alert_policy:
-  backend: default
-  enabled: true
-  config:
-    min_risk_level: medium
+In your `.env`:
+```bash
+DROPBOX_TOKEN="sl.Al..."
+SENDGRID_API_KEY="SG.xyz..."
+```
+
+See [`config/example.yaml`](config/example.yaml) for a complete reference of all options.
+
+### Tips
+
+- **Secrets**: Never put secrets in YAML. Use env vars (`*_env`) and set them in your shell or `.env`.
+- **Notifiers**: At least one notifier (mqtt/email) must be enabled unless `alert_policy.enabled` is false.
+- **YOLO Classes**: Built-in classes include `person`, `car`, `truck`, `motorcycle`, `bicycle`, `dog`, `cat`, `bird`, `backpack`, `handbag`, `suitcase`.
 
-per_camera_alert:
-  front_door:
-    min_risk_level: low
-    notify_on_activity_types: ["person_at_door", "delivery"]
+After installation, the `homesec` command is available:
+
+```bash
+homesec --help
 ```
 
-A few things worth knowing:
-- Secrets never go in YAML. Use env var names (`*_env`) and set values in your shell or `.env`.
-- At least one notifier must be enabled (`mqtt` or `sendgrid_email`).
-- Built-in YOLO classes: `person`, `car`, `truck`, `motorcycle`, `bicycle`,
-  `dog`, `cat`, `bird`, `backpack`, `handbag`, `suitcase`.
-- Local storage for development:
+### Commands
 
-```yaml
-storage:
-  backend: local
-  local:
-    root: "./storage"
+**Run the pipeline:**
+```bash
+homesec run --config config.yaml
 ```
 
-- Set `alert_policy.enabled: false` to disable notifications (a noop policy is used).
-- For a quick local run, pair `local_folder` with `local` storage and drop a clip
-  into `recordings/`.
-
-## Extensible by design
-
-HomeSec is intentionally modular. Each major capability is an interface
-(`ClipSource`, `StorageBackend`, `ObjectFilter`, `VLMAnalyzer`, `AlertPolicy`,
-`Notifier`) defined in `src/homesec/interfaces.py`, and plugins are discovered at
-runtime via entry points. This keeps the core pipeline small while making it
-easy to add new backends without editing core code.
-
-What this means in practice:
-- Swap storage or notifications by changing config, not code.
-- Add a new plugin type as a separate package and register it.
-- Keep config validation strict by pairing each plugin with a Pydantic model.
-
-Extension points (all pluggable):
-- Sources: RTSP motion detection, FTP uploads, local folders
-- Storage backends: Dropbox, local disk, or your own
-- Filters: object detection (YOLO or custom models)
-- VLM analyzers: OpenAI-compatible APIs or local models
-- Alert policies: per-camera rules and thresholds
-- Notifiers: MQTT, email, or anything else you can send from Python
-
-## CLI
-
-- Run the pipeline:
-  `uv run python -m homesec.cli run --config config/config.yaml --log_level INFO`
-- Validate config:
-  `uv run python -m homesec.cli validate --config config/config.yaml`
-- Cleanup (reanalyze and optionally delete empty clips):
-  `uv run python -m homesec.cli cleanup --config config/config.yaml --older_than_days 7 --dry_run True`
-
-## Built-in plugins
-
-- Filters: `yolo`
-- VLM analyzers: `openai` (OpenAI-compatible API)
-- Storage: `dropbox`, `local`
-- Notifiers: `mqtt`, `sendgrid_email`
-- Alert policies: `default`, `noop`
-
-## Writing a plugin
-
-HomeSec discovers plugins via entry points in the `homesec.plugins` group. A plugin
-module just needs to import and register itself.
-
-Each plugin provides:
-- A unique name (used in config)
-- A Pydantic config model for validation
-- A factory that builds the concrete implementation
-
-```python
-# my_package/filters/custom.py
-from pydantic import BaseModel
-from homesec.interfaces import ObjectFilter
-from homesec.plugins.filters import FilterPlugin, filter_plugin
-
-class CustomConfig(BaseModel):
-    threshold: float = 0.5
-
-class CustomFilter(ObjectFilter):
-    ...
-
-@filter_plugin(name="custom")
-def register() -> FilterPlugin:
-    return FilterPlugin(
-        name="custom",
-        config_model=CustomConfig,
-        factory=lambda cfg: CustomFilter(cfg),
-    )
+**Validate config:**
+```bash
+homesec validate --config config.yaml
 ```
 
-```toml
-# pyproject.toml
-[project.entry-points."homesec.plugins"]
-my_filters = "my_package.filters.custom"
+**Cleanup old clips** (reanalyze and optionally delete empty clips):
+```bash
+homesec cleanup --config config.yaml --older_than_days 7 --dry_run=False
 ```
 
+Use `homesec <command> --help` for detailed options on each command.
+
+## Plugins
+
+### Extensible by design
+
+We designed HomeSec to be modular. Each major capability is an interface (`ClipSource`, `StorageBackend`, `ObjectFilter`, `VLMAnalyzer`, `AlertPolicy`, `Notifier`) defined in `src/homesec/interfaces.py`. This means you can swap out components (like replacing YOLO with a different detector) without changing the core pipeline.
+  
+HomeSec uses a plugin architecture where every component is discovered at runtime via entry points.
+
+### Built-in plugins
+
+| Type | Plugins |
+|------|---------|
+| Sources | [`rtsp`](src/homesec/sources/rtsp/core.py), [`ftp`](src/homesec/sources/ftp.py), [`local_folder`](src/homesec/sources/local_folder.py) |
+| Filters | [`yolo`](src/homesec/plugins/filters/yolo.py) |
+| Storage | [`dropbox`](src/homesec/plugins/storage/dropbox.py), [`local`](src/homesec/plugins/storage/local.py) |
+| VLM analyzers | [`openai`](src/homesec/plugins/analyzers/openai.py) |
+| Notifiers | [`mqtt`](src/homesec/plugins/notifiers/mqtt.py), [`sendgrid_email`](src/homesec/plugins/notifiers/sendgrid_email.py) |
+| Alert policies | [`default`](src/homesec/plugins/alert_policies/default.py), [`noop`](src/homesec/plugins/alert_policies/noop.py) |
+
+### Plugin interfaces
+
+All interfaces are defined in [`src/homesec/interfaces.py`](src/homesec/interfaces.py).
+
+| Type | Interface | Decorator |
+|------|-----------|-----------|
+| Sources | `ClipSource` | `@source_plugin` |
+| Filters | `ObjectFilter` | `@filter_plugin` |
+| Storage | `StorageBackend` | `@storage_plugin` |
+| VLM analyzers | `VLMAnalyzer` | `@vlm_plugin` |
+| Notifiers | `Notifier` | `@notifier_plugin` |
+| Alert policies | `AlertPolicy` | `@alert_policy_plugin` |
+
+### Writing a custom plugin
+
+Extending HomeSec is designed to be easy. You can write custom sources, filters, storage backends, and more.
+
+👉 **See [PLUGIN_DEVELOPMENT.md](PLUGIN_DEVELOPMENT.md) for a complete guide.**
+
 ## Observability
 
-- Health endpoint: `GET /health` (configurable in `health.host`/`health.port`)
-- Optional telemetry logs to Postgres when `DB_DSN` is set:
-  - Start local DB: `make db`
-  - Run migrations: `make db-migrate`
+- Health endpoint: `GET /health` (configurable via `health.host`/`health.port` in config)
+- Telemetry logs to Postgres when `DB_DSN` is set
 
 ## Development
 
+### Setup
+
+1. Clone the repository
+2. Install [uv](https://docs.astral.sh/uv/) for dependency management
+3. `uv sync` to install dependencies
+4. `make db` to start Postgres locally
+
+### Commands
+
 - Run tests: `make test`
 - Run type checking (strict): `make typecheck`
 - Run both: `make check`
-- Tests must include Given/When/Then comments.
+- Run the pipeline: `make run`
+
+### Notes
+
+- Tests must include Given/When/Then comments
 - Architecture notes: `DESIGN.md`
 
 ## Contributing