macOS Installation

1. Open the releases page of the AI Detector project with the button above in Safari, Chrome or Firefox, or search Google for “CowCatcher AI GitHub” and click Releases.
2. Download exactly two files: the macOS engine (aidetector-osx) and the web version — the interface where you set everything up.

1. Go to your desktop, click with two fingers on the trackpad (or right-click) and choose New Folder. Name it Cowcatcher.
2. Open Finder, go to Downloads and drag both .zip files into the Cowcatcher folder on your desktop.
3. Double-click both .zip files. macOS unpacks them automatically with Archive Utility.
4. Delete the original .zip files to keep the folder tidy.

CowCatcher AI does not come from the App Store and has no paid Apple developer certificate, so macOS blocks it on the first launch — with a message such as “cannot be opened because the developer cannot be verified”, “is damaged and can’t be opened” or “macOS cannot check it for malicious software”. Any of the three methods below gives permission; pick the one that suits your macOS version.

Method A — via System Settings (recommended for Ventura, Sonoma and Sequoia)

1. Try to open the program once by double-clicking it, then click Cancel on the security message.
2. Click the Apple logo in the top-left corner and open System Settings → Privacy & Security.
3. Scroll all the way down in the right-hand pane to Security. You see the text: “‘Cowcatcher AI’ was blocked from use because it is not from an identified developer.”
4. Click the button Open Anyway next to that text and confirm with your Mac password or Touch ID. Click Open on the final question.

Method B — Control-click → Open

1. Open the Cowcatcher folder in Finder.
2. Hold the Control key and click the program (or right-click it), then choose Open at the top of the menu.
3. Click Open in the security dialog. macOS remembers this choice and will start the program without warnings from now on.

Method C — via Terminal (if macOS says the file is “damaged”)

macOS sometimes puts downloaded files in a so-called quarantine zone. You can remove that quarantine flag in five seconds:

1. Open Terminal (press Cmd + Space, type Terminal and press Enter).
2. Type the command below, including the space at the end, and then drag the Cowcatcher folder from your desktop straight into the Terminal window. The path is filled in for you.

   sudo xattr -rd com.apple.quarantine /Users/yourname/Desktop/Cowcatcher

3. Press Enter and type your Mac login password. You will not see any characters appear while typing — that is normal. Press Enter again.
4. All files in the folder are now permanently unblocked.

RTSP (Real Time Streaming Protocol) is the network address your IP cameras use to send their live video over the local network. CowCatcher AI reads that stream and analyses it frame by frame.

Settings per camera brand

• Reolink — RTSP is switched off at the factory, so you have to enable it once. Open the Reolink app on your computer or phone, select the camera, tap the gear icon and go to Network → Advanced → Server Settings. Tick RTSP and save. Confirm with Yes when the camera asks if you are sure.
• Hikvision & Dahua — RTSP is already enabled by default. You do not have to change anything in the camera software.
• Axis, Foscam, Ubiquiti UniFi — also allow RTSP streaming out of the box, on the standard port 554.

Find the IP address of your camera

You need the IP address of the camera to connect it. You will find it in the camera's mobile app, on the network page of your router, or in the software of the camera brand. An IP address almost always looks like 192.168.1.31 or 192.168.178.50.

Always use the substream

Nearly every IP camera sends out two video streams: a mainstream in high resolution (4K or 1080p) that costs a lot of computing power, and a substream in a lower resolution (640x480 or 720p). For the AI the substream is more than sharp enough to recognise cows, mounting behaviour and calving activity — and it saves up to 80% of the load on your processor. Always pick the substream.

1. Open the folder of the web version and start the application. Your browser opens the local user interface.
2. If your browser or firewall asks for network access, choose Allow.
3. Go to Streams and click Add.
4. Enter a clear Label, for example Heifers barn 1 or Calving pen west.
5. Paste the RTSP address of the camera in the Source field. Use the template for your brand below.
6. Click Test. If the connection succeeds you immediately see the live camera image.
7. Click Save, and repeat these steps for every camera you want to add.

Find the RTSP URL for your camera

Replace [PASS] and [IP] with the password and IP address of your own camera. Prefer the Sub stream where available — it uses far less processing power.

Telegram is the fastest and cheapest way to receive alerts on your phone, including the photo of the detection.

1. Go to Notifications and click Add → Telegram.
2. Give the channel a Label, for example My phone or Family group.
3. Fill in the Token of your bot. You get this from Telegram’s BotFather when you create your own notification bot.
4. Fill in your Chat ID: a unique ten-digit number (for example 1234567890) that tells the bot which account or group chat the photos must go to.
5. Click Test notification and check your phone. Did the test message arrive? Then click Save.

Several notification groups

You can add as many Telegram recipients or groups as you like. A practical split: one group Heat detection heifers for the farmer and the staff, and a second group Calving alerts for the whole family or the night shift.

Home Assistant webhook (optional)

Do you use Home Assistant on the farm? Then you can also enter a webhook URL. CowCatcher AI sends a JSON signal to your Home Assistant server on every detection, so you can switch on the barn lighting automatically or trigger a physical siren relay.

In the Detectors tab you create the actual AI jobs: here you link the cameras, the type of detection and the settings together.

Heat detection (Cow Catcher)

1. Click Add and choose the preset Cow Catcher (heat detection / mounting).
2. Select the streams that are aimed at the cows or heifers in heat.
3. Select the Telegram channels that must receive a message when a mount is detected.
4. Set the Confidence (see the table below) and click Save.

Calving detection (Calving Catcher)

1. Click Add and choose the preset Calving Catcher.
2. Select the camera(s) of the calving pen or the straw boxes, plus the Telegram channels for calving alerts.
3. With calving you do not want any delay, so set the alert interval to 1: every detection is sent through immediately.
4. Set Required detected frames to about 15. The AI checks roughly once per second, so 15 seconds of continuous signal (feet or water bag) sets off the alarm.

Confidence explained

The confidence decides how sure the AI has to be of its case before an alert is sent.

Advanced parameters

Behind the Advanced switch you will find extra parameters such as the detection interval, timeouts and video export. Everything you save here is written automatically to the config.json file in your program folder — you never have to edit that file by hand.

See what every setting does →

1. Open the Cowcatcher folder and start the AI detector — the engine, not the web interface.
2. A dark terminal window opens. Do not close this window! This is the engine that processes all the camera images in the background.
3. On the very first start the program downloads the latest AI model from the server. Depending on your internet speed this takes one to three minutes. It then converts the model automatically to the fastest format for your hardware.

Reading the log

Once the AI is active you see a line scroll by for every processed frame, with the detection time in milliseconds. As long as those lines keep coming, you know the AI is watching your barn live.

aidetector.detection.detector - INFO - Detection time: 38ms for 1 frame(s). Avg: 38ms
aidetector.detection.detector - INFO - Detection time: 37ms for 1 frame(s). Avg: 37ms
aidetector.detection.detector - INFO - Checking for timeouts