Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update readme to give more context and trim less relevant info #260

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update readme to give more context and trim less relevant info #260

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 47 additions & 112 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
<h1 align="center"><a href="https://github.com/mcguirepr89/BirdNET-Pi/blob/main/LICENSE">Review the license!!</a></h1>
<h1 align="center">You may not use BirdNET-Pi to develop a commercial product!!!!</h1>
<h1 align="center">
BirdNET-Pi
</h1>
<h1 align="center">BirdNET-Pi</h1>
<p align="center">
A realtime acoustic bird classification system for the Raspberry Pi 5, 4B, 400, 3B+, and 0W2
</p>
Expand All @@ -14,114 +12,82 @@ Icon made by <a href="https://www.freepik.com" title="Freepik">Freepik</a> from
</p>

## About this fork:
I've been building on [mcguirepr89's](https://github.com/mcguirepr89/BirdNET-Pi) most excellent work to further update and improve BirdNET-Pi. Maybe someone will find it useful.

Changes include:
In 2024, [Nachtzuster](https://github.com/Nachtzuster/BirdNET-Pi) forked and began building on [mcguirepr89's](https://github.com/mcguirepr89/BirdNET-Pi) most excellent earlier work to further update and improve BirdNET-Pi. We hope you find it useful.

- Backup & Restore
- Web ui is much more responsive
Changes include:
- Raspberry Pi 5 support
- Support for 'Species range model V2.4 - V2'
- Bump tflite_runtime to 2.11.0, it is faster
- Debian Bookworm support
- Backup & Restore Tools
- More responsive Web ui
- Daily charts now include all species, not just top/bottom 10
- Bump apprise version, so more notification type are possible
- Swipe events on Daily Charts (by @croisez)
- Support for 'Species range model V2.4 - V2'
- Bookworm support
- Experimental support for writing transient files to tmpfs
- Rework analysis to consolidate analysis/server/extraction. Should make analysis more robust and slightly more efficient, especially on installations with a large number of recordings
- Bump tflite_runtime to 2.11.0, it is faster
- Rework daily_plot.py (chart_viewer) to run as a daemon to avoid the very expensive startup
- Lots of fixes & cleanups

!! note: see 'Migrating' on how to migrate from mcguirepr89

## Introduction
BirdNET-Pi is built on the [BirdNET framework](https://github.com/kahst/BirdNET-Analyzer) by [**@kahst**](https://github.com/kahst) <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/"><img src="https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg"></a> using [pre-built TFLite binaries](https://github.com/PINTO0309/TensorflowLite-bin) by [**@PINTO0309**](https://github.com/PINTO0309) . It is able to recognize bird sounds from a USB microphone or sound card in realtime and share its data with the rest of the world.
BirdNET-Pi is built on the [BirdNET framework](https://github.com/kahst/BirdNET-Analyzer) by [**@kahst**](https://github.com/kahst) <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/"><img src="https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg"></a> using [pre-built TFLite binaries](https://github.com/PINTO0309/TensorflowLite-bin) by [**@PINTO0309**](https://github.com/PINTO0309) . It is able to recognize bird sounds from a microphone in near realtime and share its data with the rest of the world.

Check out birds from around the world
- [BirdWeather](https://app.birdweather.com)<br>

Currently listening in these countries . . . that I know of . . .
- The United States
- Germany
- South Africa
- France
- Austria
- Sweden
- Scotland
- Norway
- England
- Italy
- Finland
- Australia
- Canada
- Switzerland
- Romania
- Spain
- New Zealand
- Russia
- Croatia
- Belgium
- Israel
- Ireland
- Denmark
- Costa Rica
- The Philippines
- Hungary
- South Sudan
- Argentina
- Brazil
- Thailand
- Colombia
- Estonia
- Tasmania
- Luxembourg
- Crete
- Rwanda
- Oman
- Belarus
- Czech Republic
- Japan
Since at least 2021, listening in countries all around the world:

Argentina, Australia, Austria, Belarus, Belgium, Brazil, Canada, Colombia, Costa Rica, Crete, Croatia, Czech Republic, Denmark, England, Estonia, Finland, France, Germany, Hungary, Ireland, Israel, Italy, Japan, Luxembourg, New Zealand, Norway, Oman, Romania, Russia, Rwanda, Scotland, South Africa, South Sudan, Spain, Sweden, Switzerland, Tasmania, Thailand, The Philippines, The United States

## Features
* **24/7 recording and automatic identification** of bird songs, chirps, and peeps using BirdNET machine learning
* **Automatic extraction and cataloguing** of bird clips from full-length recordings
* **Tools to visualize your recorded bird data** and analyze trends
* **Live audio stream and spectrogram**
* **Automatic disk space management** that periodically purges old audio files
* [BirdWeather](https://app.birdweather.com) integration -- you can request a BirdWeather ID from BirdNET-Pi's "Tools" > "Settings" page
* Web interface access to all data and logs provided by [Caddy](https://caddyserver.com)
* [GoTTY](https://github.com/yudai/gotty) and [GoTTY x86](https://github.com/sorenisanerd/gotty) Web Terminal
* [Tiny File Manager](https://tinyfilemanager.github.io/)
* **Disk space management** to periodically delete/purge old audio files
* [BirdWeather](https://app.birdweather.com) API integration -- request a BirdWeather ID from BirdNET-Pi's "Tools" > "Settings" page
* Web HTTP interface access to data and logs provided by [Caddy](https://caddyserver.com)
* Web Terminal - [GoTTY](https://github.com/yudai/gotty)/[GoTTY x86](https://github.com/sorenisanerd/gotty)
* File Browsing - [Tiny File Manager](https://tinyfilemanager.github.io/)
* FTP server included
* SQLite3 Database
* [Adminer](https://www.adminer.org/) database maintenance
* [phpSysInfo](https://github.com/phpsysinfo/phpsysinfo)
* Database Store - SQLite3
* Database Tool - [Adminer](https://www.adminer.org/)
* System Info using [phpSysInfo](https://github.com/phpsysinfo/phpsysinfo)
* [Apprise Notifications](https://github.com/caronc/apprise) supporting 90+ notification platforms
* Localization supported
* International Localization supported

## Requirements
* A Raspberry Pi 5, Raspberry 4B, Raspberry Pi 400, Raspberry Pi 3B+, or Raspberry Pi 0W2 (The 3B+ and 0W2 must run on RaspiOS-ARM64-**Lite**)
* An SD Card with the **_64-bit version of RaspiOS_** installed (please use Bookworm) -- Lite is recommended, but the installation works on RaspiOS-ARM64-Full as well. Downloads available within the [Raspberry Pi Imager](https://www.raspberrypi.com/software/).
* A USB Microphone or Sound Card
* Raspberry Pi: 5, 4B, 400, 3B+, 0W2 (3B+ and 0W2 must run on RaspiOS-ARM64-**Lite**)
* SD Card with the **_64-bit version of RaspiOS_** installed (please use Debian Bookworm) -- Lite is recommended, but the installation works on RaspiOS-ARM64-Full as well. Downloads available within the [Raspberry Pi Imager](https://www.raspberrypi.com/software/).
* A USB Microphone or Audio Interface and Microphone

## Installation
[A comprehensive installation guide is available here](https://github.com/mcguirepr89/BirdNET-Pi/wiki/Installation-Guide). This guide is slightly out-dated: make sure to pick Bookworm, also the curl command is still pointing to mcguirepr89's repo.
[A historical installation guide is available here](https://github.com/mcguirepr89/BirdNET-Pi/wiki/Installation-Guide).
NOTE: This guide is slightly out-dated: make sure to pick Bookworm, also the curl command is still pointing to mcguirepr89's repo.

Please note that installing BirdNET-Pi on top of other servers is not supported. If this is something that you require, please open a discussion for your idea and inquire about how to contribute to development.
Please note that installing BirdNET-Pi on other server systems is not supported. If this is something that you require, please open a GitHub discussion for your idea and inquire about how to contribute to development.

[Raspberry Pi 3B[+] and 0W2 installation guide available here](https://github.com/mcguirepr89/BirdNET-Pi/wiki/RPi0W2-Installation-Guide)

The system can be installed with:
The system can be installed with: (Note this points to Nachtzuster's fork)
```
curl -s https://raw.githubusercontent.com/Nachtzuster/BirdNET-Pi/main/newinstaller.sh | bash
```
The installer takes care of any and all necessary updates, so you can run that as the very first command upon the first boot, if you'd like.
The installer takes care of any and all necessary OS and BirdNet-Pi updates, so you can run that as the very first command upon the first boot, if you'd like.

The installation creates a log in `$HOME/installation-$(date "+%F").txt`.

## Access
The BirdNET-Pi can be accessed from any web browser on the same network:
The BirdNET-Pi can be accessed from any web browser using HTTP (Port 80) on the same network:
- http://birdnetpi.local OR your Pi's IP address
- Default Basic Authentication Username: birdnet
- Password is empty by default. Set this in "Tools" > "Settings" > "Advanced Settings"
- Default Username: birdnet
- Default Password is empty. Change this in "Tools" > "Settings" > "Advanced Settings"


## Resources

Please take a look at the [wiki](https://github.com/mcguirepr89/BirdNET-Pi/wiki) and [discussions](https://github.com/mcguirepr89/BirdNET-Pi/discussions) for information on
- [BirdNET-Pi's Deep Convolutional Neural Network(s)](https://github.com/mcguirepr89/BirdNET-Pi/wiki/BirdNET-Pi:-some-theory-on-classification-&-some-practical-hints)
Expand Down Expand Up @@ -153,12 +119,13 @@ To restore:
./scripts/backup_data.sh -a restore -f /mnt/birds/backup-2024-07-09.tar
```

## x86_64 support*
***x86_64 is not supported.** Not officially anyway. It is mainly there for developers or otherwise more Linux savvy people.
## x86_64 support
**x86_64 is not supported.** Not officially anyway. It is mainly there for developers or otherwise more Linux savvy people.

That being said, some pointers:
- Use Debian 12
- The user needs passwordless sudo
- We use a custom TFLite build that needs AVX2 support. So Intel Haswell or newer, not sure what that means for AMD cpu's, let me know if you do.
- TFLite build needs AVX2 support. So Intel Haswell or newer, not sure what that means for AMD cpu's, let me know if you do.
- Some people get around the previous point by uninstalling `tflite_runtime` and replacing with `tensorflow` in the `./birdnet` venv. But beware: analysis will be slower, and the older v1 model won't work.

For Proxmox, a user has reported adding this in their `cpu-models.conf`, in order for the custom TFLite build to work.
Expand All @@ -168,10 +135,11 @@ cpu-model: BirdNet
reported-model host
```

## Uninstallation
## Uninstalling
```
/usr/local/bin/uninstall.sh && cd ~ && rm -drf BirdNET-Pi
```

## Migrating
Before switching, make sure your installation is fully up-to-date. Also make sure to have a backup, that is also the only way to get back to the original BirdNET-Pi.
Please note that upgrading your underlying OS to Bookworm is not going to work. Please stick to Bullseye. If you do want Bookworm, you need to start from a fresh install and copy back your data. (remember the backup!)
Expand All @@ -183,7 +151,9 @@ git remote add origin https://github.com/Nachtzuster/BirdNET-Pi.git
./scripts/update_birdnet.sh
```
## Troubleshooting and Ideas

*Hint: A lot of weird problems can be solved by simply restarting the core services. Do this from the web interface "Tools" > "Services" > "Restart Core Services"

Having trouble or have an idea? *Submit an issue for trouble* and a *discussion for ideas*. Please do *not* submit an issue as a discussion -- the issue tracker solicits information that is needed for anyone to help -- discussions are *not for issues*.

PLEASE search the repo for your issue before creating a new one. This repo has nothing to do with the validity of the detection results, so please do not start any issues around "False positives."
Expand All @@ -194,10 +164,10 @@ I hope that if you find BirdNET-Pi has been worth your time, you will share your

## Homeassistant addon

BirdNET-Pi can also be run as a [Homeassistant](https://www.home-assistant.io/) addon through docker.
BirdNET-Pi can also be added to [Homeassistant](https://www.home-assistant.io/) addon through docker.
For more information : https://github.com/alexbelgium/hassio-addons/blob/master/birdnet-pi/README.md

## Cool Links
## Cool WriteUps and Extensions

- [Marie Lelouche's <i>Out of Spaces</i>](https://www.lestanneries.fr/exposition/marie-lelouche-out-of-spaces/) using BirdNET-Pi in post-sculpture VR! [Press Kit](https://github.com/mcguirepr89/BirdNET-Pi-assets/blob/main/dp_out_of_spaces_marie_lelouche_digital_05_01_22.pdf)
- [Research on noded BirdNET-Pi networks for farming](https://github.com/mcguirepr89/BirdNET-Pi-assets/blob/main/G23_Report_ModelBasedSysEngineering_FarmMarkBirdDetector_V1__Copy_.pdf)
Expand All @@ -210,42 +180,7 @@ For more information : https://github.com/alexbelgium/hassio-addons/blob/master/
### Internationalization:
The bird names are in English by default, but other localized versions are available thanks to the wonderful efforts of [@patlevin](https://github.com/patlevin). Use the web interface's "Tools" > "Settings" and select your "Database Language" to have the detections in your language.

Current database languages include the list below:
| Language | Missing Species out of 6,362 | Missing labels (%) |
| -------- | ------- | ------ |
| Afrikaans | 5774 | 90.76% |
| Catalan | 544 | 8.55% |
| Chinese | 264 | 4.15% |
| Croatian | 370 | 5.82% |
| Czech | 683 | 10.74% |
| Danish | 460 | 7.23% |
| Dutch | 264 | 4.15% |
| Estonian | 3171 | 49.84% |
| Finnish | 518 | 8.14% |
| French | 264 | 4.15% |
| German | 264 | 4.15% |
| Hungarian | 2688 | 42.25% |
| Icelandic | 5588 | 87.83% |
| Indonesian | 5550 | 87.24% |
| Italian | 524 | 8.24% |
| Japanese | 640 | 10.06% |
| Latvian | 4821 | 75.78% |
| Lithuanian | 597 | 9.38% |
| Norwegian | 325 | 5.11% |
| Polish | 265 | 4.17% |
| Portuguese | 2742 | 43.10% |
| Russian | 808 | 12.70% |
| Slovak | 264 | 4.15% |
| Slovenian | 5532 | 86.95% |
| Spanish | 348 | 5.47% |
| Swedish | 264 | 4.15% |
| Thai | 5580 | 87.71% |
| Ukrainian | 646 | 10.15% |

## Screenshots
![Overview](docs/overview.png)
![chrome_HNMJKSPwV0](https://user-images.githubusercontent.com/103586016/217896322-aee3ecc4-e40e-40df-ade1-79f05ded21f2.png)


## :thinking:
Are you a lucky ducky with a spare Raspberry Pi? [Try Folding@home!](https://foldingathome.org/)