{"id":18035848,"url":"https://github.com/echo-devim/pyalarmguard","last_synced_at":"2026-04-28T01:32:02.143Z","repository":{"id":173000575,"uuid":"646457780","full_name":"echo-devim/pyalarmguard","owner":"echo-devim","description":"Python project for home security","archived":false,"fork":false,"pushed_at":"2023-11-16T08:17:36.000Z","size":21941,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-22T16:55:10.884Z","etag":null,"topics":["alarm-detection","artificial-intelligence","home-security","human-detection","python","raspberry-pi","signal-processing","single-shot-detection"],"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/echo-devim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-05-28T13:16:57.000Z","updated_at":"2024-07-21T13:05:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"ae479da4-b08b-4925-b0a7-7cf7abef6be0","html_url":"https://github.com/echo-devim/pyalarmguard","commit_stats":null,"previous_names":["echo-devim/pyalarmguard"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/echo-devim/pyalarmguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/echo-devim%2Fpyalarmguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/echo-devim%2Fpyalarmguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/echo-devim%2Fpyalarmguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/echo-devim%2Fpyalarmguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/echo-devim","download_url":"https://codeload.github.com/echo-devim/pyalarmguard/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/echo-devim%2Fpyalarmguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32362781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"ssl_error","status_checked_at":"2026-04-27T20:07:00.910Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["alarm-detection","artificial-intelligence","home-security","human-detection","python","raspberry-pi","signal-processing","single-shot-detection"],"created_at":"2024-10-30T12:10:29.397Z","updated_at":"2026-04-28T01:32:02.129Z","avatar_url":"https://github.com/echo-devim.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pyAlarmGuard\n\nPython project for Raspberry PI (or other similar boards) to enforce your home security.\n\nThe current implementation can be summarized by the following image:\n![system overview](system_overview.png)\n\nImagine to have an audio alarm system (e.g. fire detection system, anti-theft system, etc.). This project has the goal to use a microphone to hear for alarm sounds. When an alarm sound is detected, the system will send to your smartphone a notification with eventually attached evidences (e.g. recorded audio).\npyAlarmGuard can support also a camera featuring object/human detection powered by MobileNetSSD (really fast even on raspberry pi).\n\nThe project has the `carriers` directory that contains all available notification methods. Currently only Telegram messages are supported, but future implementations could include emails or other IM apps. Carriers can also perform actions, even if their goal is to notify the user, they can eventually receive commands to execute.\n\nThe `sensors` directory contains all the available sensors. Audio recording through microphone and photos from camera are supported. Future implementations could include videos from camera, motion-detection systems, etc.\n\nThe `detectors` directory contains tools and algorithms to perform several analysis, currently only alarm detection and human detection are implemented.\n\nThe project aims to provide a general structure easy to customize, in order to implement your home security system.\n\n\n# Installation\n\nInstall on the system the package `sox` and optionally `vlc`\nThen run `pip install -r requirements.txt`\n\nCopy the bash file `setup/startup.sh` into `/opt` directory. The bash script contains some workarounds to init the user session for pulse audio server and then starts the project.\nThe project will run as non-root user, you must enable ssh-key authentication between root and pi local users.\nCopy the service `setup/alarmguard.service` in `/etc/systemd/system`, then run `systemctl daemon-reload` and `systemctl --now enable alarmguard`.\n\nBefore to run the project you need to rename `config_example.py` into `config.py` in the root project directory adding the configuration for Telegram (api key and chat id).\n\n\n## Technical Details\n\n### Alarm detection\nThe `detectors` are wrapped by `Detector` class (in `detectory.py` file).\nAlarm detection is performed first applying a sinc filter and then measuring db level of wav file.\nFinally is applied a custom audio correlation algorithm to exclude false positives (i.e. matches for environmental sounds).\n\nThe audio correlation is performed translating the amplitude values into positive values. Thus, the minimum value of the signal (negative number) is summed to all the amplitudes.\nThen the time information is discarded by re-ordering all amplitudes in descending order. In this way the same sound recorded at different moment can be recognized.\nThe resulting curve is then compared to other curves representing the sounds in the dataset calculating the differences with some tollerance.\nThe final result is a percentage of similarity between two sounds.\n\n### Alarm Correlation with Dejavu3 (archivied)\nPreviously the project was based on dejavu3 algorithm, but after some tests it showed little effectiveness with short audios.\n\nActually the repo still includes Dejavu3 audio correlator, but it's not used by the project anymore.\n\nDejavu3 is derived from [dejavu](https://github.com/worldveil/dejavu), but modified to use a local sqlite database `audio.db`.\n\nEach time, recorded audio is compared to sounds already known (saved in the database) using Dejavu3 algorithm. It is possible to add new sounds putting `wav` files inside the `detectors/dejavu3/samples/` directory. The name of the `wav` file represents its label.\n\nIf the audio recorded from mic results to have a correlation to a known sound (found in `audio.db`) its label is retrieved. If the label (i.e. the filename) starts with the `exclude` keyword, the current recording is considered as a sound to ignore (e.g. noise). Otherwise if the label starts with the `include` keyword, the current recording is considered as an alarm.\n\nWhen the dejavu3 algorhitm fails to classify the recorded audio, then it's applied a sinc filter and measured RMS dB level. If the dB level is greather then a defined threshold, the alarm notification will be triggered.\n\n### Object detection\nFor object detection is used the MobileNetSSD model for the Single Shot Detector (SSD) that can infer very fast objects in a image.\nObject that can be detected: background,aeroplane,bicycle,bird,boat,bottle,bus,car,cat,chair,cow,diningtable,dog,horse,motorbike,person,pottedplant,sheep,sofa,train,tvmonitor\n\nWhen human is detected with a confidence greather than 60% the user is notified and a sequence of 120 images per second (by default) is acquired from camera.\n\n## Supported Commands\nTelegram carrire implements several commands that are described below:\n\n*  `/stop` stop all detectors\n*  `/stoph` stop only human detection\n*  `/start` start all detectors\n*  `/status` get system status\n*  `/poweroff` shutdown the system\n*  `/play` play a song/sound (if the raspberry has a speaker)\n*  `/getphoto` get a photo from camera\n*  `/getaudio n` get an audio of n seconds (recording is done with a background thread)\n*  `/setdblevel n` set the db level threshold for alarm detection\n\nLogs are saved in `pyalarmguard.log` file in the project directory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecho-devim%2Fpyalarmguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecho-devim%2Fpyalarmguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecho-devim%2Fpyalarmguard/lists"}