AI-powered bird species classification API

Transform your bird feeder into a smart detection system. Identify 707 European species with ~90% accuracy. Built for Home Assistant and privacy-conscious bird enthusiasts.

707 European Species
~90% Accuracy
24/7 Monitoring

Get Started

Run with Docker Compose

git clone https://github.com/birdsense/birdsense.git cd birdsense docker compose up -d

Once running, access the dashboard and API documentation locally.

Features

AI-Powered Classification

State-of-the-art ConvNeXt V2 model trained on thousands of bird images for accurate species identification.

Home Assistant Ready

Seamless integration with your smart home via REST API or MQTT. Get notifications when birds are detected.

Beautiful Dashboard

View real-time statistics, historical data, and detection charts. Dark mode included for round-the-clock viewing.

Smart Notifications

Configure alerts for specific species or rarity levels. Never miss a rare visitor at your feeder.

Privacy First

All processing happens locally on your device. Your bird data never leaves your home network.

Docker Deployment

One-command setup with Docker Compose. Runs on Raspberry Pi, NAS, or any Linux server.

API Usage

File Upload

# Classify a bird image (file upload)
curl -X POST http://localhost:5001/api/classify \
  -F "image=@bird.jpg"

From URL (e.g., BirdBuddy)

# Classify a bird image from URL
curl -X POST http://localhost:5001/api/classify \
  -d "image_url=https://example.com/bird.jpg" \
  -d "camera=birdbuddy"

Response

{
  "species_en": "European Robin",
  "species_nl": "Roodborst",
  "confidence": 92
}

MQTT

BirdSense publishes bird detections to your MQTT broker. Connect to Home Assistant's Mosquitto or any other broker.

📡 Topics

birdsense/detections - Published when a bird is detected

🔔 Real-time

Instant notifications and automation triggers on bird detection

🖼️ Images

Payload includes image_path for integration with cameras

Topic

birdsense/detections

Payload

{
  "species_en": "Great Tit",
  "species_nl": "Koolmees",
  "species": "Koolmees (85%)",
  "confidence": 85,
  "camera": "garden",
  "timestamp": 1706000000,
  "image_path": "/data/images/great_tit_1737550000.jpg",
  "top_predictions": [
    {"species_en": "Great Tit", "confidence": 85},
    {"species_en": "Blue Tit", "confidence": 12}
  ]
}

Home Assistant

Integrate BirdSense with your smart home using MQTT sensors or REST commands.

MQTT Sensors

# configuration.yaml
mqtt:
  sensor:
    - name: "Last Bird Detected"
      state_topic: "birdsense/detections"
      value_template: "{{ value_json.species_en }}"
      json_attributes_topic: "birdsense/detections"
      
    - name: "Bird Confidence"
      state_topic: "birdsense/detections"
      value_template: "{{ value_json.confidence }}%"
      json_attributes_topic: "birdsense/detections"

Automation

# automations.yaml
automation:
  - alias: "Bird notification"
    trigger:
      platform: mqtt
      topic: "birdsense/detections"
    condition:
      - condition: template
        value_template: "{{ trigger.payload_json.confidence | int >= 80 }}"
    action:
      - service: notify.mobile_app
        data:
          title: "🐦 Bird detected!"
          message: "{{ trigger.payload_json.species_nl }} ({{ trigger.payload_json.confidence }}%)"

REST Command (for image URLs)

# configuration.yaml - classify images from URL (e.g., BirdBuddy)
rest_command:
  classify_bird:
    url: "http://birdsense:5001/api/classify"
    method: POST
    content_type: "application/x-www-form-urlencoded"
    payload: "image_url={{ image_url }}&camera={{ camera }}&lang=nl"

Shell Command (for local files)

# configuration.yaml - classify local images
shell_command:
  classify_bird: 'curl -s -X POST http://birdsense:5001/api/classify -F "image=@/config/www/snapshot.jpg"'

Configuration

Set environment variables in .env:

Variable Description Default
MQTT_BROKER MQTT broker hostname -
MQTT_PORT MQTT broker port 1883
MQTT_USERNAME MQTT username -
MQTT_PASSWORD MQTT password -
MIN_CONFIDENCE Minimum confidence % 60
SAVE_IMAGES Save classified images true
IMAGE_DIR Directory for saved images /data/images
MAX_IMAGE_SIZE Max image size in bytes 10485760
View on GitHub