clearcam: object detection and mobile alerts for an RTSP camera you already own

What clearcam adds to a camera that already speaks RTSP

A plain RTSP camera gives you a stream and, if it has a card slot, a folder of files nobody watches. clearcam sits in front of that stream and turns it into events. The README describes the project as adding "object detection, tracking, mobile notifications, AI summaries, and search to any security camera", and the repository layout backs that up: detection/, ocsort_tracker/, llm/, models/, plus android/ and ios/ clients. The intended user is someone who already owns an RTSP camera and is willing to run a Python process on a Mac or Linux machine. It is not a camera vendor and it does not sell hardware. If you have no camera, the README points at a public test feed at https://webcam.elcat.kg/Too-Ashu_Tunnel_North/index.m3u8 so you can see the pipeline work before buying anything. The topics list on the repository (cctv, nvr, rtsp, selfhosted, object-detection, tinygrad, yolov9) is a fair summary of the scope.

The pipeline: ffmpeg in, detections out, clips on disk

The architecture visible in the repository is a single Python process that pulls frames, runs inference, tracks objects across frames, and writes event clips. clearcam.py is the entry point and also serves the web UI on port 8080. Inference is built on tinygrad, pinned in requirements.txt to a specific commit (efd256b2a3ccd53a797c0b8ced62ea40e75d2a8b), with numpy 2.0.0 and opencv-python-headless 4.10.0.84 as the only other dependencies. Tracking lives in ocsort_tracker/, which is the OC-SORT family of trackers, and detection/ holds the model glue. ffmpeg is listed as a requirement rather than a Python package, which tells you decoding is handed to the system binary. The llm/ directory and the README's note about "AI Notification Summaries with Qwen3 VL" indicate a second, optional stage that turns a detection into a written sentence for the notification. Zones appear in the screenshots, so detections can be scoped to part of the frame. The dependency list is unusually short for a project with a mobile app and a web UI, and that is a deliberate consequence of the tinygrad choice: no CUDA toolkit, no PyTorch wheel, just a pinned git dependency.

Installing clearcam from source and seeing your first detection

The README gives a four-step source install. You need ffmpeg on the PATH and Python 3.11 or later. Clone the repository, install the pinned requirements, then start the server:

git clone https://github.com/roryclear/clearcam.git
cd clearcam
pip install -r requirements.txt
python3 clearcam.py

The process starts the NVR and the inference loop together. The README then says to open localhost:8080 in your browser, where the web UI appears. That is where you add a camera, draw a zone, and watch detections land as events. If the log shows the CPU doing the work instead of a GPU, the README gives two environment switches:

DEV=AMD python3 clearcam.py
DEV=NV python3 clearcam.py
BEAM=2 python3 clearcam.py

The DEV variable selects the AMD or NVIDIA backend, and BEAM=2 trades a longer first run for extra performance, because the first launch pays a compilation cost. Notifications are not locked to the vendor app. The README says the notification URL can be changed in settings, and names Home Assistant, Pushover and N8N as targets, with a sample Pushover server in utils/sample_server.py. If you want remote viewing and push notifications through the official apps, the README says to enter a Clearcam Premium userID, visible in the iOS app settings page, in the web UI settings. The iOS app can also be built from source by opening ios/clearcam.xcodeproj, and the README claims no third-party dependencies for it.

Where clearcam stops being the right tool

Windows is the clearest boundary. The requirements list reads "Mac, Linux, ~~Windows~~ *ffmpeg fix needed", so the Windows path is struck out and unfinished. If your only always-on machine runs Windows, this project is not for you today. The second limit is the dependency pinning. requirements.txt points tinygrad at a git commit rather than a released version, which means pip resolves a moving target you cannot easily audit or substitute. The third is operational maturity. The releases listed are 0.2.6 through 0.2.8, the newest on 2026-08-31, and the README does not document rollback, migration between versions, or what happens to recorded clips and event history when you upgrade. There is no stated retention policy, no documented backup procedure, and no description of what happens when the process dies mid-recording. The repository also contains a test/ directory but the README says nothing about how to run it, so you cannot tell from the documentation alone how much of the pipeline is covered. Finally, the README does not describe multi-camera scaling limits, so if you plan to attach eight streams to one host, that is an experiment you run yourself, not a documented configuration.

Compared with a conventional NVR stack

The usual self-hosted alternative is a general-purpose NVR such as Frigate or ZoneMinder, which record continuously and treat detection as an add-on service, often a separate container talking to the recorder over MQTT. clearcam inverts that. Detection is the core loop, and the recording is the byproduct: the process decodes, infers, tracks, and writes event clips. The practical difference shows up in what you install. A container-based NVR expects Docker, a broker, and a config file with camera definitions. clearcam expects ffmpeg, Python 3.11 or later, and three pinned packages, and you configure cameras through a browser at localhost:8080. The trade-off is the opposite direction too. A mature NVR has documented storage layouts, retention rules and upgrade notes; clearcam's README covers the happy path and little else. If your priority is a stable recorder with detection bolted on, clearcam is the wrong shape. If your priority is a small Python process that only keeps the interesting seconds and pings your phone, the shape fits.

Licence, releases and what an upgrade actually costs you

clearcam is GPL-3.0. For anyone running it at home that changes nothing. For anyone embedding it in a product, the copyleft terms apply to distributed derivatives, and the project also has a separate hosted tier, Clearcam Premium, sold through clearcam.org and the iOS app. The README does not state how the premium service interacts with the GPL code, and that is a question to settle with the project before building a commercial offering on top of it; this is a description of the licence text, not legal advice. Upgrade cost is dominated by the tinygrad pin. Because requirements.txt references a commit, moving to a newer clearcam release may move the inference backend at the same time, and the BEAM=2 first-run compilation means every upgrade has a slow first start. With releases roughly six to eight weeks apart in the list (0.2.6 on 2026-05-29, 0.2.7 on 2026-07-13, 0.2.8 on 2026-08-31), you are choosing a cadence, not a one-time install. The last push to the repository was on 2026-09-15.

Editorial conclusion

Adopt clearcam if you already own an RTSP camera, can run Python 3.11 or later on a Mac or Linux box, and want detections and clips kept on your own hardware rather than in a vendor cloud. Skip it if you are on Windows, if you need a supported rollback path between releases, or if you want a project with a long public track record: the first release in the list is 0.2.6 from 2026-05-29. Before committing, confirm that ffmpeg and Python 3.11 or later are present on the host, run the source install and watch the log while a real camera connects, and decide whether remote viewing is worth a Clearcam Premium userID, since the README ties remote streams and notifications to that account.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. roryclear/clearcam on GitHub