The Problem

Most IP cameras record blindly. Turning an RTSP feed into something that detects people, tracks them across frames, clips events, and notifies a phone normally means stitching together Frigate, a notification service, and a search index. This repo packages that whole pipeline — detection, tracking, clip search, mobile apps — into one Python server with iOS and Android clients.

What This Does

clearcam.py is the NVR and inference server. It ingests RTSP streams, runs YOLOv9 detection via detection/yolov9.py, tracks objects with the OC-SORT tracker in ocsort_tracker/, stores clips and events through utils/db.py, and serves a browser UI from mainview.html. clip.py and clip_search.py provide semantic search over recorded footage. The ios/ and android/ directories are native apps that connect to the server for live view, event clips, and push notifications.

The Python side runs from source with requirements.txt; the mobile apps are self-contained (the iOS README claims zero dependencies beyond iOS 15).

How It Is Wired

Execution starts at clearcam.py — the entry point and the module hub. Static analysis shows it imports 5 internal modules (Ca 1, Ce 5, instability 0.83), making it the widest blast radius in the repo: a change there ripples to everything. It routes into three leaf modules that nothing else imports: detection/yolov9 (Ca 2, Ce 0), clip (Ca 2, Ce 0), and utils/db (Ca 2, Ce 0). ocsort_tracker/ocsort is fully unstable (Ce 3, instability 1) — it only consumes. No circular dependencies exist.

The flow is short: clearcam.py → yolov9 for detection, → ocsort for tracking, → utils/db for persistence, → clip/clip_search for search. utils/db.py carries 60 branch points over 161 lines — the densest decision logic outside the main file. The wiring for the mobile apps' server communication is not mapped by the analysis; only the Python graph was resolved.

How To Use It

From the README, verbatim:

pip install -r requirements.txt
python3 clearcam.py
# optional: enter your Clearcam premium userID to receive streams/notifications
# open localhost:8080 in your browser
# BEAM=2 python3 clearcam.py for extra performance (wait time on first run)

ffmpeg must be installed on the host. Premium features (remote viewing, notifications) require a userID from the iOS app. No environment variables or config file are documented.

Real-World Use

Point the server at a parking-lot RTSP feed. clearcam.py detects a person, ocsort keeps the same ID across frames, an event clip is written via utils/db.py, and the iOS app pushes a notification. Later, search "red van" and clip_search.py retrieves the matching segment without watching the footage.

Code Health & Issues

Static analysis found 20 issues (8 high, 12 medium) across 6 kinds:

  • High - deep nesting x11, max depth 13 in HomeScreen.kt, MainActivity.kt, SettingsScreen.kt. Flatten with early returns.
  • High - duplicated code x17 repeated 6-line blocks across clearcam.py, detection/yolov9.py, cocotest.py. Extract shared helpers.
  • High - oversized files x2: clearcam.py at 1544 lines and HomeScreen.kt. Split by responsibility.
  • Medium - broad exception handling x3 in utils/db.py, clearcam.py, utils/clip_tokenizer.py. Catch specific exceptions.
  • Medium - file opened without context manager x2 in utils/clip_tokenizer.py, cocotest.py. Use with open(...).
  • Medium - high branching density in utils/db.py: 60 branches / 161 lines.

SDLC observations from the file structure: no CI configuration exists (24 source files, no build gate), no lockfile for reproducible installs, and three blobs over 5MB are committed (clearcamviewer.apk 18.1MB, MOT16-03.mp4 10.7MB, yolov9t 10.6MB) — move those to LFS or object storage. clearcam.py also makes 2 outbound calls with no timeout, which can hang a worker indefinitely.

The Bottom Line

The core idea is sound and the Python pipeline is compact — three leaf modules doing detection, tracking, and storage with no cycles. The risk is concentration: one 1500-line entry file, no CI, and no lockfile mean the project works today but is fragile to change. Use it if you want a self-hosted camera NVR with search and mobile clients; add CI and split clearcam.py before extending it.