HomeCamCheck
Local macOS surveillance — person detection, alerts and smart home integration.
Documentation
HomeCamCheck — Help
Version: 1.1
Platform: macOS 26.4 or later
Publisher: Precellence
HomeCamCheck is a macOS app that turns a connected camera into a local surveillance tool. It detects people on your Mac using Apple’s Vision framework, shows a live preview, and can send alerts or integrate with your smart home.
Getting started
- Install and launch HomeCamCheck on the Mac that will run the camera.
- Grant camera access when macOS asks for permission. Without it, the app cannot show video or run detection.
- The camera starts automatically when the app opens. Use Stop camera / Start camera (⌘K) in the toolbar to control it.
- In the sidebar, enable Detection to start looking for people in the video feed.
The status indicator shows whether a person is currently confirmed in view.
Main window
Sidebar
| Control | Description |
|---|---|
| Detection | Turns person detection on or off without stopping the camera. |
| Camera | Choose a specific camera or leave Automatic to let the app pick one. |
| Local notifications | macOS alerts when a person is detected. |
| Telegram | Sends photo and/or video alerts via your Telegram bot. |
The footer shows the status of the webhook server, live stream, and local video archive.
Preview
The main area shows the live camera feed with detection overlays when a person is found.
Appearance
Use the appearance picker in the toolbar to switch between light and dark themes.
Settings
Open Settings… from the sidebar (or HomeCamCheck → Settings, ⌘,) for advanced options.
Camera
- Refresh camera list — Updates the list of connected cameras.
- Exposure bias — Adjusts brightness when your camera supports it.
Detection
- Minimum confidence — Higher values reduce false positives but may miss distant people.
- Analysis rate (FPS cap) — How often frames are analyzed (1–30 FPS). Lower values use less CPU.
- Smoothing frames — Number of consecutive positive detections required before confirming presence (reduces flicker).
Alerts
- SMS (Free Mobile) — Sends text messages via the Free Mobile SMS API. Requires a Free Mobile account with API access enabled.
- Telegram photo / video — Sends a snapshot and/or a short clip when a person is detected.
- Cooldown — Minimum time between two alerts of the same type (SMS or Telegram).
- Telegram video duration — Length of the recorded clip (3–15 seconds).
Use the Tests section to verify notifications, SMS, and Telegram without waiting for a real detection.
Local video archive
When enabled, short video clips are saved locally on your Mac when a person is detected.
- Retention by time — Deletes clips older than the configured number of days.
- Retention by storage cap — Limits total archive size in megabytes.
- Open folder — Opens the archive directory in Finder.
- Purge now — Immediately removes clips according to your retention rules.
Remote control (webhook)
A small HTTP server on 127.0.0.1 only lets Homebridge, Home Assistant, or scripts turn the camera on or off.
| Endpoint | Method | Action |
|---|---|---|
/v1/camera/on |
GET | Start the camera |
/v1/camera/off |
GET | Stop the camera |
/v1/camera |
POST | JSON body: {"on": true} or {"on": false} |
If you set a shared token, include it as header X-HomeCamCheck-Token or query parameter ?token=.
Default port: 37647 (configurable).
Live stream
Exports a raw H.264 (Annex B) stream over TCP for tools such as homebridge-camera-ffmpeg or ffplay.
- Active only while the camera is running.
- Bind to 127.0.0.1 only — Recommended for security. When disabled, the stream is reachable on your local network.
- Default port: 47890.
Example test command:
ffplay -fflags +genpts -f h264 tcp://127.0.0.1:47890
See the bundled homebridge-http-webhooks.example.json for a full Homebridge configuration example.
Credentials
Sensitive values are stored in the macOS Keychain, not in plain text:
- Free Mobile user and API key
- Telegram bot token and chat ID
- Webhook shared token
Homebridge integration
HomeCamCheck supports two complementary Homebridge plugins:
- homebridge-http-webhooks — Camera on/off via the local webhook.
- homebridge-camera-ffmpeg — Live video via the H.264 TCP stream.
Both run on different ports and work independently. Copy the example JSON from the app bundle and replace PASTE_YOUR_TOKEN_HERE with your webhook token.
Troubleshooting
Camera does not start
- Check that another app is not using the camera exclusively.
- Confirm camera permission in System Settings → Privacy & Security → Camera.
- Try Refresh camera list and select another camera.
Too many or too few detections
- Raise Minimum confidence if you get false alarms.
- Increase Smoothing frames to require more stable detection.
- Lower the analysis rate if performance is an issue.
SMS or Telegram not working
- Verify credentials in Settings → Credentials.
- Run the corresponding Test button.
- For Telegram, ensure your bot can message the chat ID you configured.
- For Free Mobile, confirm API SMS is enabled on your account.
Webhook or stream unreachable
- Ensure the feature is enabled in Settings.
- Check that the port is not already in use.
- The webhook only listens on
127.0.0.1. Remote machines must reach your Mac through your own network setup if you expose the stream on LAN.
Archive growing too large
- Enable retention by time and/or storage cap.
- Use Purge now to clean up immediately.
Keyboard shortcuts
| Shortcut | Action |
|---|---|
| ⌘K | Start / stop camera |
| ⌘, | Open Settings |
Privacy
HomeCamCheck processes video locally on your Mac. Optional alerts send data only to services you configure (Telegram, Free Mobile). See the Privacy Policy for details.
Contact
For support or feedback: support@precellence.icu
Last updated: June 2026