About - Stop Sign Nanny
Stop Sign Nanny

Making our neighborhood safer, one stop at a time

Understanding the data
  • Compliance rate — percentage of vehicles that stop for at least 2 seconds in the stop zone (based on the last 100 passes).
  • Speed value — relative motion score from the AI tracker. Lower numbers mean the vehicle slowed down more. Not miles per hour.
  • Time in zone — how many seconds the vehicle spent inside the stop zone. Longer is better.
  • "Best" passes — vehicles that stopped the longest or moved the slowest.
  • "Worst" passes — vehicles that blew through fastest or spent the least time stopped.
15 FPS
real-time inference budget from capture to stream
SSFM timestamps
capture-time metadata preserved across every queue
4 dedicated services
ingest, analyze, render, and serve the experience

Pipeline

Frames take a deterministic path from curb to browser. Each boundary is backed by Redis queues, health checks, and Prometheus metrics.

Main Pipeline
Capture
RTSP Camera
Network camera or sample MP4 feed streaming into the site via RTSP.
Frame ingestion
rtsp_to_redis
Encodes frames as JPEG, wraps them in the SSFM header, and LPUSHes into Redis with FIFO semantics.
Buffer
Redis - RAW
Deterministic queueing keeps capture order intact while smoothing network jitter.
Detection & scoring
video_analyzer
YOLO inference, Kalman-smoothed tracking, and stop-zone scoring feed Postgres + MinIO evidence.
Frame bus
Redis - PROCESSED
Annotated frames with timestamps stay ready for streaming without blocking the analyzer.
Streaming
ffmpeg_service
FFmpeg (NVENC or libx264) assembles HLS playlists, guarded by watchdog and readiness probes.
Experience layer
web_server
FastAPI + Jinja2 + htmx deliver the live player, dashboards, and developer tooling.
Interface
Operators
Browsers consume HLS, review recent passes, and adjust zones without redeploying.
Support Services
Structured history
PostgreSQL
Stores vehicle pass records, compliance scoring, and trend queries for insights.
Evidence store
MinIO
Holds annotated JPEG clips and exposes them through signed URLs in the UI.
Observability
Grafana + Prometheus
Dashboards visualize FPS, inference latency, queue depth, and HLS freshness.

Services

rtsp_to_redis
Frame ingestion & SSFM packaging
  • LPUSHes JPEG frames with SSFM headers so capture timestamps survive downstream hops.
  • Bounded queues (FRAME_BUFFER_SIZE) smooth out bursty networks without going stale.
  • Exports Prometheus counters/timers plus runtime status mixins for health probes.
video_analyzer
Computer vision core
  • Runs YOLO via ONNX Runtime with GPU acceleration (configured via YOLO_MODEL_NAME/YOLO_DEVICE).
  • CarTracker + Kalman filter blend trajectories for reliable stop detection.
  • Persists scores to Postgres, ships annotated evidence to MinIO, and surfaces live insights.
ffmpeg_service
HLS edge
  • Consumes processed frames from Redis and renders annotated video at 15 FPS.
  • Configurable FFmpeg encoders (NVENC, libx264) with presets tuned for low latency.
  • Watchdog + /ready + /health endpoints restart the stream if freshness drifts.
web_server
Experience + APIs
  • FastAPI + Jinja2 pages powered by htmx for live updates without heavy JS.
  • Interactive records view, live HLS.js player, and /debug zone editor for calibration.
  • Caches insights, proxies media from MinIO, and exposes /health/stream for monitors.

Operational Guardrails

Observability
  • Prometheus exporters on every service feed Grafana boards shipped in `static/`.
  • Health surface: `/healthz` for liveness, `/ready` for freshness, `/health/stream` for external probes.
  • ServiceStatus mixins report queue depth, Redis/DB connectivity, and error counters for triage.
  • Insights cache highlights live trends (peak hour, average stop time, fastest vehicle).
Resilience
  • Analyzer catch-up trims Redis backlogs when frames age past ANALYZER_CATCHUP_SEC.
  • FFmpeg watchdog exits when HLS segments age beyond playlist thresholds so orchestrators restart cleanly.
  • Single-source config (`config/config.yaml`) hot-reloads across services and persists via volumes.
  • Debug UI + CLI tools (`tools/set_stop_zone.py`) let operators retune stop zones without downtime.

Build & Extend

The repository doubles as a reference implementation for real-time computer vision pipelines.

  • `docker/local/docker-compose.yml` spins up the full stack with Redis, Postgres, and MinIO dependencies.
  • `Makefile` automates setup (`make setup`), streaming (`make stream-local`), and linting.
  • `sample_data/` video lets you replay the pipeline offline; `uv` manages Python deps reproducibly.
  • Documentation lives under `docs/` covering architecture, health modeling, and deployment strategy.
View on GitHub