Chirp — Automated Bird Call Detection System

Chirp is an end-to-end, edge AI–powered system for automated bird call detection, identification, and archival. It runs entirely on your own hardware — no cloud subscriptions, no data sharing.

Author: Joshua Salvi — josh.salvi@gmail.com
Version: 0.5.15.b
Status: Active development · ourchirp.com/about

🧠 How It Works

Getting started: build a station from chirp-device/README.md, then either run your own server (setup guide, chirp-server-instances/docker-compose.simple.yml) or request a hosted site on ourchirp.com. Self-hosted servers can request a push relay token there so the iPhone app gets notifications.

Chirp splits into two pieces: a lightweight edge sensor node (the physical device with microphones attached, typically a Raspberry Pi) that listens continuously and decides what's worth recording, and a server subsystem (this Docker container) that stores everything, enriches detected species with data from several public sources, and serves the web dashboard.

Detection itself runs as a two-stage pipeline on the edge device: a cheap, fast energy filter screens out the overwhelming majority of incoming audio (silence, wind, unrelated noise) before the expensive neural network classifier ever runs — this is what makes continuous, always-on detection practical on modest hardware instead of needing a full-scale classifier running on every moment of audio all day.

For the full technical breakdown — real configuration values, the species enrichment sequence, API reference, and troubleshooting — see the full technical documentation guide (built with MkDocs; cd techdocs && mkdocs serve to view locally).

📱 Screenshots

Mobile (iOS app / installed PWA) — a sample across the app. All screenshots below have identifying information (account details, exact home address, device network info) removed or blacked out.

Dashboard	Recordings	Life List
Field Guide	Bat activity	Statistics
Yard diversity	Notes	Settings & themes

Desktop (web browser) — the same real app, same real data, at desktop width.

Dashboard	Recordings
Life List	Statistics
Field Guide	Devices

The full set (20 screenshots, including Devices, Logs, admin Activity, Weekly Summary, Life List growth, confidence distributions, and more) is in docs/screenshots/mobile/.

Desktop screenshots aren't included yet — the web app is fully responsive and works the same way in a desktop browser, but no desktop captures have been taken for this README so far. If you'd like to contribute some, a PR adding docs/screenshots/desktop/ in the same style would be very welcome.

📂 Documentation

🗂️ Components

🔢 Versioning

Chirp uses a four-part version number: 0.X.Y.Z

  0 . 1 . 3 . d
  │   │   │   └─ Patch letter  (a b c d …)
  │   │   └───── Minor version (0, 1, 2, 3 …)
  │   └───────── Major version (0, 1, 2 …)
  └───────────── Epoch         (always 0 until public commercial launch)

What each position means

Epoch 0 — The leading zero means Chirp is in pre-commercial development. It becomes 1 at the first stable public/commercial release. Think of it as "Chapter 0: still building."

Major X — Increments when something breaks backwards compatibility or requires a significant manual step from you: a database migration you have to run yourself, a renamed config key, a hardware requirement change, or a fundamental architectural rewrite. You will always see a clear note in the changelog when X changes.

Minor Y — Increments when a new user-visible feature is added. New pages, new integrations (e.g. iNaturalist submission, SSH terminal, eBird export), new hardware support. The system still works the same way, just has more capabilities.

Patch Z — A letter (a, b, c, d …) that resets to a whenever Y increments. Patch releases contain only fixes and small improvements within the same feature set:

Reading examples

Where to find the version

• In the app: Bottom of the sidebar — "v0.5.0.p · What's New"
• In the app: Settings → About, or click "What's New" for full changelog
• In the code: chirp-server/frontend/package.json → "version"
• In the API: GET /api/v1/health → {"version": "0.5.0.p"}
• In the changelog: CHANGELOG.md

How to update the version

When making a release, update these three files consistently:

# 1. chirp-server/frontend/package.json
"version": "0.X.Y.Z"

# 2. chirp-server/app/main.py
version="0.X.Y.Z"

# 3. CHANGELOG.md — add a new ## 0.X.Y.Z section at the top

⚡ Quick Setup

1. Server (Unraid / any Docker host)

cd chirp-server
cp .env.example .env
# Edit .env: set CHIRP_SECRET_KEY, CHIRP_DEVICE_API_KEY
docker-compose up -d --build
# WebGUI: http://YOUR_SERVER_IP:8765

See chirp-server/README.md for full environment variable reference and volume paths.

2. Device (Raspberry Pi 5)

cd chirp-device
./install.sh              # CPU-only
# ./install-coral.sh      # With Google Coral EdgeTPU (~8x faster)
# Edit config.yaml: set upload.server_url and upload.api_key
python main.py --test-detection
python main.py            # Start detecting!

See chirp-device/README.md for full installation instructions, configuration options, and Coral setup.

3. Configure in the WebGUI

Open http://YOUR_SERVER_IP:8765 → Settings:

• Set your location (enables eBird regional data)
• Add your eBird API key (free at ebird.org/api/keygen)
• Configure SMTP if you want email notifications

🔑 API Keys Needed

🤖 AI Features (Optional) — Anthropic / OpenAI / Gemini / Ollama

Three optional features run on an LLM, each independently assignable to a provider in Settings → AI Features, off by default:

Important architectural note before picking a model: unlike the hosted providers, Ollama has one shared base_url + model setting, not a separate model per feature — you pick a provider per feature, but every feature assigned to "ollama" uses that same single model. Since Call Re-analysis needs a vision-capable model and the other two are text-only, this leaves two real strategies:

• A. One model does everything — pick a vision-capable model (they handle plain text fine too) and assign all three features to Ollama.
• B. Split it — assign Daily Journal + Bird Profile Summaries to Ollama with a fast text-only model, and leave Call Re-analysis on a hosted provider (Anthropic/OpenAI/Gemini). Local vision models are noticeably behind frontier hosted models on fine-grained visual judgment calls like "does this spectrogram support this species guess" — Strategy B trades a few cents per re-analysis for meaningfully better judgment on the one feature where a wrong answer is most misleading.

There's no wrong choice here — B is the more accuracy-conscious pick, A is the fully self-hosted/zero-cost pick.

Audio cleanup — not LLM features, but AI-adjacent

Every recording's audio player also has two or three toggles that clean up the audio itself, separate from the three LLM features above (no provider or API key involved for either):

Enhanced and Rumble Removed can be combined; AI Enhance always replaces both when it's on.

Setting up Ollama

1. Install (bare-metal or Docker — if you're running the rest of Chirp on Unraid, Docker is the natural fit):

# Bare-metal (Linux):
curl -fsSL https://ollama.ai/install.sh | sh

# Or Docker:
docker run -d --gpus=all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

2. Give the container your GPU. Docker doesn't expose a GPU to a container by default, even with working host drivers — this is the single most common reason Ollama silently runs on CPU with no error. On Unraid: install the Nvidia-Driver plugin (Community Applications) first, then make sure the container actually requests the GPU. In docker-compose:

services:
  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
volumes:
  ollama:

3. Pull a model (see the table below), then confirm it's actually on the GPU:

ollama pull <model>
ollama ps          # PROCESSOR column should show 100% GPU, not CPU
nvidia-smi         # confirm an ollama process is using VRAM while generating

4. Configure in Chirp — Settings → AI Features → set Ollama's base URL (e.g. http://192.168.1.X:11434 — use the host's LAN IP, not localhost, if Ollama runs in a separate container from chirp-server) and model name, then assign whichever features you want to it.

Which Ollama model should you use?

Model names, sizes, and exact VRAM figures shift often — always double-check current tags with ollama pull <name> (it'll error clearly if the tag doesn't exist) or at ollama.com/library before committing. Figures below are Q4 quantization estimates, treat as a floor rather than exact:

Our recommendation: given you already have GPU passthrough working, gemma4:e4b (Strategy A, one model for everything) is the best starting point — genuinely multimodal, fast, and modest on VRAM. If Call Re-analysis's judgment calls matter to you and you have the VRAM to spare, gemma4:26b is a meaningful step up for that feature specifically. If you'd rather keep Call Re-analysis on a hosted provider and just want Ollama for the two text features (Strategy B), llama3.3:8b is the better dedicated pick — it won't be doing double duty as a vision model it doesn't need to be.

🏗️ Architecture

Raspberry Pi 5 (chirp-device)
  ├── USB/M.2 Coral TPU (optional, ~8x faster)
  ├── ReSpeaker USB microphone (primary — detection path)
  ├── Additional USB mics (optional — SNR-weighted recording path)
  ├── BirdNET TFLite — 2-stage detection (energy filter → neural classifier)
  └── → uploads WAV + JSON metadata → chirp-server

Unraid Docker (chirp-server, port 8765)
  ├── FastAPI backend  /app/app/api/
  │   ├── recordings.py    — upload, analysis, statistics
  │   ├── birds.py         — profiles, life list, eBird export
  │   ├── devices.py       — Pi pairing, config push, SSH terminal
  │   └── app_settings.py  — settings, backup / restore
  ├── Services
  │   ├── bird_enricher.py  — Wikipedia, iNat, eBird, Xeno-canto, BirdLife
  │   ├── geomodel_service  — iNat GeoPackage range map rendering
  │   ├── email_service.py  — SMTP notifications
  │   └── inat_service.py   — iNaturalist observation submission
  └── React/Vite PWA  (served at /)

🎙️ Microphone Options — Full Comparison

The ReSpeaker XVF3800 (Chirp's default mic) publishes a 64 dBA SNR spec, not a self-noise figure — it's a digital MEMS array with on-chip DSP (AEC/AGC/ beamforming/noise suppression), so its numbers aren't measured the same way as a plain analog capsule's. Several fields below aren't published by the manufacturer in a directly comparable form (marked accordingly) rather than guessed at, and "effective range" genuinely isn't a standardized spec across this category — it depends on the sound source's own loudness/directivity and whether a reflector is involved.

Bottom line: for the birds pipeline, the EM272Z1-based mics are the standout value — a fraction of the MKH 8020's price for self-noise within striking distance of it. For the bats pipeline, the Dodotronic Ultramic is the most direct upgrade over the stock AudioMoth. If you want a completely separate, no-Pi-required deployment instead, the Song Meter SM4 is the industry-standard standalone option.

🐦 Key Features

👤 User Roles

📜 License

Copyright © 2026 Joshua Salvi. Licensed under the PolyForm Noncommercial License 1.0.0: free to use, modify and run for any noncommercial purpose, including your own station and server. Commercial use needs written permission: josh.salvi@gmail.com