{"id":15567990,"url":"https://github.com/circa10a/cv-notifier","last_synced_at":"2025-09-08T13:37:37.989Z","repository":{"id":170063824,"uuid":"646018094","full_name":"circa10a/cv-notifier","owner":"circa10a","description":"Easily detect objects using computer vision and call configurable webhooks","archived":false,"fork":false,"pushed_at":"2025-01-14T02:57:25.000Z","size":14,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-02T05:14:03.795Z","etag":null,"topics":["ai","artificial-intelligence","nocode","opencv","opencv-python","raspberry-pi","raspberrypi","webhooks","yaml","yolo"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/circa10a.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-27T03:10:30.000Z","updated_at":"2025-01-14T02:57:10.000Z","dependencies_parsed_at":"2024-02-06T07:31:17.122Z","dependency_job_id":"0fb064d5-f3e0-453d-8bd0-86c55cddc361","html_url":"https://github.com/circa10a/cv-notifier","commit_stats":{"total_commits":10,"total_committers":2,"mean_commits":5.0,"dds":0.09999999999999998,"last_synced_commit":"b6aaa2b9a4ea56d71704579b370d4471760e27fc"},"previous_names":["circa10a/cv-notifier"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/circa10a/cv-notifier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fcv-notifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fcv-notifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fcv-notifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fcv-notifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/circa10a","download_url":"https://codeload.github.com/circa10a/cv-notifier/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fcv-notifier/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274194958,"owners_count":25239146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","artificial-intelligence","nocode","opencv","opencv-python","raspberry-pi","raspberrypi","webhooks","yaml","yolo"],"created_at":"2024-10-02T17:14:04.232Z","updated_at":"2025-09-08T13:37:37.965Z","avatar_url":"https://github.com/circa10a.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cv-notifier \u003cimg src=\"https://cdn-icons-png.flaticon.com/512/1527/1527254.png\" height=\"5%\" width=\"5%\" align=\"left\"/\u003e\n\n![Build Status](https://github.com/circa10a/cv-notifier/workflows/deploy/badge.svg)\n![GitHub tag (latest semver)](https://img.shields.io/github/v/tag/circa10a/cv-notifier?style=plastic)\n\nEasily detect objects using computer vision ([YOLOv8](https://github.com/ultralytics/ultralytics)) and call configurable webhooks. Built for easy object detection on x86/arm64 machines.\n\n![alt text](https://media.tenor.com/rEfUBOuVFZcAAAAC/stalker-peeping-tom.gif)\n\n* [About](#about)\n* [Usage](#usage)\n  * [System requirements](#system-requirements)\n  * [Local](#local)\n  * [Docker](#docker)\n* [Configuration](#configuration)\n  * [Variable substituiton](#variable-substituiton)\n\n## About\n\nI primarily built this because I wanted to be able to notify my cat that there are birds/squirrels on my patio since he often yells at me to summon said birds/squirrels all of the time. I thought an application such as this existed already. All I wanted was to be able to call webhooks when a certain object is detected on a video stream, but yet, here we are because it didn't exist.\n\nI'm using this with an RTSP stream via [this cheap ip camera](https://www.amazon.com/Tapo-security-indoor-pet-camera/dp/B0866S3D82) along with [home assistant](https://www.home-assistant.io/) to play sounds on my Google Home speakers. Everything is hosted on a Raspberry Pi 4 via docker containers.\n\n## Usage\n\n`cv-notifier` is very configurable, thus requires a YAML or JSON configuration file at runtime. See [configuration](#configuration) for more details.\n\nHere's what an example configuration file looks like:\n\n```yaml\nconfig:\n  source: 'rtsp://$STREAM_USER:$STREAM_PASSWORD@192.168.1.101/stream1'\n  schedule:\n    startTime: '07:00'\n    endTime: '18:00'\n  webhooks:\n    - url: http://localhost:8080?object_name=$object_name\u0026object_confidence=$object_confidence\n      notifyInterval: 900\n      objects:\n        - bird\n        - cat\n        - dog\n      method: 'POST'\n      headers:\n        Content-Type: application/json\n        Authorization: Bearer $API_TOKEN\n      body: \u003e\n        {\n          \"someKey\": \"$object_name detected with confidence score of $object_confidence\"\n        }\n```\n\n### System requirements\n\n* x86\n  * 2 CPU's\n  * 500M available RAM\n* ARM (Raspberry Pi 4+ recommended)\n  * 4 CPU's\n  * 500M available RAM\n\n### Local\n\n```console\npython main.py --config ./sample.config.yaml\n```\n\n### Docker\n\nDocker run:\n\n\u003e Variable substitution in the configuration is optional. This is to demonstrate capabilities.\n\n```console\ndocker run --name cv-notifier \\\n    -e STREAM_USER=$USER \\\n    -e STREAM_PASSWORD=password \\\n    -e API_TOKEN='token' \\\n    -v $PWD/sample.config.yaml:/opt/cv-notifier/config.yaml \\\n    -v /etc/localtime:/etc/localtime:ro \\\n    circa10a/cv-notifier\n```\n\nDocker Compose:\n\n```yaml\nversion: '3'\n\nservices:\n  cv-notifier:\n    container_name: cv-notifier\n    restart: always\n    image: circa10a/cv-notifier\n    env_file: .env\n    volumes:\n      - ./sample.config.yaml:/opt/cv-notifier/config.yaml\n      - /etc/localtime:/etc/localtime:ro\n```\n\n## Configuration\n\n`cv-notifier` supports many different configuration options. See [usage](#usage)\n\n|                                     |                                                                      |           |                    |                                |\n|-------------------------------------|----------------------------------------------------------------------|-----------|--------------------|--------------------------------|\n| Key                                 | Description                                                          | Required  | Default            | Supports environment variables |\n| `config.source`                     | Source of video stream such as `RTSP`, `RTMP`, `HTTP`                | `True`    | `None`             |  ✅                            |\n| `config.model`                      | What pre-trained model to use                                        | `False`   | `yolov8s.pt`       |  ❌                            |\n| `config.confidence`                 | Score filter to only show detected objects with confidence above this| `False`   | `0.50` (50%)       |  ❌                            |\n| `config.loglevel`                   | Level of logging. `info`, `debug`, `warning`                         | `False`   | `info`             |  ❌                            |\n| `config.schedule.startTime`         | Time to start detecting objects/send notifications in 24 hour format | `False`   | `None`             |  ❌                            |\n| `config.schedule.endTime`           | Time to stop detecting objects/send notifications in 24 hour format  | `False`   | `None`             |  ❌                            |\n| `config.webhooks`                   | List of webhook configurations to be notified                        | `False`   | `None`             |  N/A                           |\n| `config.webhooks[0].url`            | HTTP endpoint to send request to when object is detected             | `True`    | `None`             |  ✅                            |\n| `config.webhooks[0].notifyInterval` | In seconds, frequency at which to send notifications                 | `False`   | `0`                |  ❌                            |\n| `config.webhooks[0].objects`        | [List][COCO list] of things to detect and notify if seen             | `True`    | `[]`               |  ❌                            |\n| `config.webhooks[0].method`         | HTTP method to send in request                                       | `False`   | `POST`             |  ❌                            |\n| `config.webhooks[0].headers`        | Map of HTTP headers to send in request                               | `False`   | `None`             |  ✅                            |\n| `config.webhooks[0].body`           | HTTP body to send in request                                         | `False`   | `None`             |  ✅                            |\n| `config.webhooks[0].timeout`        | HTTP request timeout in seconds                                      | `False`   | `5`                |  ❌                            |\n\n### Variable substituiton\n\nConfiguration fields that often require sensitive data do support environment variable subtsition in the form of `$variable` within the configuration values. The `url`, `body`, and `headers within a webhook configuration supports some additional data around the object detected. This information can be used to customize request payloads like the example mentioned above in [configuration](#configuration).\n\n* `object_name` - The name of the object detected that was specified in the `objects` list\n* `object_confidence` - The confidence score from the model of the object detected\n\n\u003c!-- References --\u003e\n[COCO list]: https://gist.github.com/AruniRC/7b3dadd004da04c80198557db5da4bda\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirca10a%2Fcv-notifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcirca10a%2Fcv-notifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirca10a%2Fcv-notifier/lists"}