hassio-addons/birdnet-pi/README_standalone.md

BirdNET-Pi Docker Installation Guide

I maintain this and other Home Assistant add-ons in my free time: keeping up with upstream changes, HA changes, and testing on real hardware takes a lot of time (and some money). I use around 5-10 of my >110 addons so regularly I install test machines (and purchase some test services such as vpn) that I don't use myself to troubleshoot and improve the addons

If this add-on saves you time or makes your setup easier, I would be very grateful for your support!

Addon informations

This guide provides instructions on how to install and run the BirdNET-Pi container using Docker Compose without dependency on HomeAssistant.

Note : For usage as an HomeAssistant addon, see here

Thanks to @gotschi for the initial Docker Compose

Prerequisites

Ensure you have the following installed on your system:

• Docker
• Docker Compose

Installation

1. Create a directory for BirdNET-Pi

   mkdir -p ~/birdnet-pi && cd ~/birdnet-pi
   

2. Create a docker-compose.yml file Create and open the file with:

   nano docker-compose.yml
   

   Copy and paste the following configuration:

   services:
     birdnet-pi:
       container_name: birdnet-pi
       image: ghcr.io/alexbelgium/birdnet-pi-amd64:latest # or ghcr.io/alexbelgium/birdnet-pi-aarch64:latest depending on your system
       restart: unless-stopped
       ports:
         - "8001:8081"  # Used to access WebUI
         - "80:80"  # Optional: set to 80 to use Caddy's automatic SSL. Can otherwise be set to null to avoid opening an additional port
       environment:
         - TZ=Europe/Vienna  # Optional: Set your timezone according to https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
         - BIRDSONGS_FOLDER=/config/BirdSongs  # Folder to store bird songs, be sure to use a path that is mapped to a volume (such as /config)
         - LIVESTREAM_BOOT_ENABLED=false  # Enable/disable livestream on boot
         - Use_tphakala_model_v2=false  # Switch to BirdNET-Go classifier files
         - ssl=false  # Enable/disable SSL
         - certfile=fullchain.pem  # SSL certificate file (located in /ssl/)
         - keyfile=privkey.pem  # SSL key file (located in /ssl/)
         - pi_password=  # Optional: Set web terminal password for user `pi`
         - MQTT_HOST_manual=  # Optional: Manual MQTT host
         - MQTT_PASSWORD_manual=  # Optional: Manual MQTT password
         - MQTT_PORT_manual=  # Optional: Manual MQTT port
         - MQTT_USER_manual=  # Optional: Manual MQTT user
         - PULSE_SERVER=unix:/tmp/pulseaudio.socket
         - PULSE_COOKIE=/tmp/pulseaudio.cookie
   
       volumes:
         - ./config:/config  # All your configuration files - and location of the default Birdsongs folder
         - ./ssl:/ssl  # SSL certificates
         - /dev/shm:/dev/shm  # Shared memory
         - /tmp/pulseaudio.socket:/tmp/pulseaudio.socket
         - /tmp/pulseaudio.client.conf:/etc/pulse/client.conf
   
       devices:
         - /dev/snd:/dev/snd
   
       group_add:
         - audio
   
       tmpfs:
         - /tmp # Optional
   
   

3. Start the Container Run the following command in the same directory as docker-compose.yml:

   docker compose up -d
   

   This will start the BirdNET-Pi container in detached mode.

4. Access BirdNET-Pi Web UI Open your browser and navigate to:

   http://localhost:8001 # Or whatever port you have configured
   

   Replace localhost with your server's IP address if running on another machine. When prompted for credentials in the web terminal, use the username pi and the password defined by pi_password (blank if unset).

troubleshoot

If rtsp feed doesn't work, perhaps you need to add "-rtsp-transport tcp" to your ffmpeg instruction, or allow udp on your network

Selecting the microphone

By default the container records through PulseAudio (REC_CARD=default in birdnet.conf). To record directly from a USB microphone instead, find it on the host with arecord -l, then pass its card number (or its card id) as ALSA_CARD:

    environment:
      - ALSA_CARD=1  # "card 1: Audio [KT USB Audio]" in the output of "arecord -l"

At startup this writes REC_CARD=plughw:CARD=1,DEV=0 into your birdnet.conf. A value that already is a full ALSA PCM name, as listed by arecord -L, is used as provided - for example ALSA_CARD=dsnoop:CARD=Audio,DEV=0, which allows the recording and the livestream services to read the same microphone at the same time.

Updating to the Latest Version

To check for new versions of the container and update:

1. Check for the latest version Visit the container registry: https://github.com/alexbelgium/hassio-addons/pkgs/container/birdnet-pi-amd64

   The latest version tag (e.g., 2025.02.23) will be listed.

2. Update and restart the container Run the following commands:

   docker compose pull birdnet-pi
   docker compose up -d --force-recreate
   

   This pulls the latest image and restarts the container.

3. Verify the update

   docker images | grep birdnet-pi
   

   This will show the latest downloaded image version.

Stopping and Removing the Container

To stop and remove the container, run:

docker compose down

This will stop and remove BirdNET-Pi while keeping the configuration and recorded songs intact.

---

Now you're all set to enjoy BirdNET-Pi with Docker! 🐦