claudecode/AvianVisitors
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updating references to old repo to new repo

Browse Source
This commit is contained in:
Patrick McGuire
2021-09-28 14:48:25 -04:00
parent 7d31737f03
commit bc2d3df898
42 changed files with 3078 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+90 -88
View File
@@ -1,110 +1,112 @@
# BirdNET-Lite
TFLite version of BirdNET. Bird sound recognition for more than 6,000 species worldwide.
# BirdNET-Lite for arm64/aarch64 (Raspberry Pi 4)
### Built on https://github.com/kahst/BirdNET -- checkout the Wiki at [BirdNETWiki.pmcgui.xyz](https://birdnetwiki.pmcgui.xyz)
Center for Conservation Bioacoustics, Cornell Lab of Ornithology, Cornell University
This project offers an installation script for BirdNET as a systemd service on arm64 (aarch64) Debian-based operating systems, namely RaspiOS. The installation script offers to walk the user through setting up the '*birdnet.conf*' main configuration file interactively, or can read from an existing '*birdnet.conf*'. A variety of configurations can be attained through this installation script.
Go to https://birdnet.cornell.edu to learn more about the project.
BirdNET-Lite can be configured with the following optional services:
- A 24/7 recording script that can be easily configured to use any available sound card
- An extraction service that extracts the audio selections identified by BirdNET by date and species
- A Caddy instance that serves the extracted files and live audio stream (icecast2) (requires dsnoop capable mic)
- A species list updating and notification script supporting mobile notifications via Pushed.co (sorry, Android users, Pushed.co doesn't seem to work for you)
- NoMachine remote desktop software (for personal use only)
Want to use BirdNET to analyze a large dataset? Don't hesitate to contact us: ccb-birdnet@cornell.edu
An installation one-liner is available [HERE](https://birdnetwiki.pmcgui.xyz/wiki/Birder%27s_Guide_to_BirdNET-Lite#Install_BirdNET-Lite) for RaspiOS-ARM64 meeting the prequisites below. It installs all services listed above.
- Prerequisites:
- An updated RaspiOS for AArch64 that has locale, WiFi, time-zone, and pi user password set. A guide is available [here](https://birdnetwiki.pmcgui.xyz/wiki/Birder%27s_Guide_to_BirdNET-Lite#Install_the_base_operating_system_.28OS.29). 64GB SD card for best performance.
- A USB microphone (dsnoop capable to enable live audio stream).
- Running the installer from within the Raspberry Pi's desktop environment (i.e., not over SSH -- for SSH installations, see installation options 2 & 3)
# Setup (Ubuntu 18.04)
TFLite for x86 platforms comes with the standard Tensorflow package. If you are on a different platform, you need to install a dedicated version of TFLite (e.g., a pre-compiled version for Raspberry Pi). See Raspberry Pi 4B installation instructions below.
## What the installation does
1. Looks for a *'birdnet.conf'* file in the *BirdNET-Lite* main directory
1. If a *'birdnet.conf'* file exists and is filled out properly, the installation is nearly
non-interactive and builds the system based off of the services configured in the *'birdnet.conf'* file
1. If the installer cannot find a *'birdnet.conf'* file, the installation is interactive and will
walk the user through creating the '*birdnet.conf'* file interactively.
1. Installs the following system dependencies:
- ffmpeg
- libblas-dev
- liblapack-dev
- caddy (for web access to extractions)
- icecast2 (live audio stream)
- alsa-utils (for recording)
- sshfs (to mount remote sound file directories)
1. Installs BirdNET-Lite scripts in */usr/local/bin*
1. Installs all selected services based on '*birdnet.conf*'
1. Installs *miniforge* for the aarch64 architecture using the current release from https://github.com/conda-forge/miniforge
1. Builds BirdNET in miniforge's *'birdnet'* virtual environment
1. Enables (but does not start) the services
## x86
We need to setup TF2.3+ for BirdNET. First, we install Python 3 and pip:
## What you should know before any installation
1. The licensing information for the software that is used (see [LICENSE](https://raw.githubusercontent.com/mcguirepr89/BirdNET-Lite/BirdNET-Lite-for-raspi4/LICENSE)).
1. The **latitude** and **longitude** where the bird recordings take place. Google maps is an easy way to find these (right-clicking the location).
1. In order for the live audio stream to work at the same time as the birdnet_recording.service, the microphone needs to be dsnoop capable. If you are wondering whether your mic supports creating the dsnoop device, you can use `aplay -L | awk -F, '/dsn/ {print $1}' | grep -ve 'vc4' -e 'Head' -e 'PCH' | uniq` to check. (No output means your microphone does not support creating a dsnoop device and therefore cannot also provide an audio stream while recording. The birdnet_recording.service, however, should not be affected by this and the installation one-liner can still be used. The live stream link simply will not work.)
```
sudo apt-get update
sudo apt-get install python3-dev python3-pip
sudo pip3 install --upgrade pip
```
## What you should know for a manual installation
1. The **local directory** where the recordings should be found on your local computer. BirdNET-Lite supports setting up a systemd.mount for automounting remote directories. So for instance, if the actual recordings live on RemoteHost's `/home/user/recordings` directory, but you would like them to be found on your device at `/home/me/BirdNET-recordings`, then `/home/me/BirdNET-recordings` will be your answer to that question.
1. If mounting the recordings directory from a remote host, you need to know the **remote hostname, username, and password** to connect to it via SSH, as well as the **absolute path of the recordings on the remote host**.
1. If you are using a special microphone or have multiple sound cards and would like to specify which to use for recording, you can edit the `~/BirdNET-Lite/birdnet.conf` file before the installation and set the **REC_CARD** variable to the sound card of your choice. Copy your desired sound card line from the output of `aplay -L | awk -F, '/^dsn:/ { print $1 }'`(prefered), or `aplay -L | awk -F, '/^hw:/ { print $1 }'`(if prefered is not available).
1. If you would like to take advantage of Caddy's automatic handling of SSL certificates to be able to host a public website where your friends can hear your bird sounds, forward ports 80 and 443 to the host you want to serve the files. You may also want to purchase a domain name.
- *Note: If you're just keeping this on your local network, **be sure to set your extraction URL to something 'http://'** (on RaspiOS, I recommend 'http://raspberrypi.local') to disable Caddy's automatic HTTPS. Alternatively, you may edit the `/etc/caddy/Caddyfile` after installation and add the `tls internal` directive to the site block to have Caddy issue a self-signed certificate for an HTTPS connection.*
1. If you would like to take advantage of BirdNET-Lite's ability to send New Species mobile notifications, you can easily setup a Pushed.co notification app (see the #TODOs at the bottom for more info). After setting up your application, make note of your **App Key** and **App Secret** -- you will need these to enable mobile notifications for new species.
- *Note for Android users: it seems that the Pushed.co Mobile App does not work for Android devices, which is a huge bummer. If anyone knows of an Android alternative, or if anyone might be able to come up with a home-spun notification system, please let me know.*
Then, we can install Tensorflow with:
## How to install
#### Option 1 (Recommended) -- Install All Services
1. In the terminal run: `curl -s https://raw.githubusercontent.com/mcguirepr89/BirdNET-Lite/BirdNET-Lite-for-raspi4/Birders_Guide_Installer.sh | bash`
```
sudo pip3 install tensorflow
```
##### Options 2 & 3 require you setup 4GB of swapping. That step is included in the directions below.
#### Option 2 -- Pre-fill birdnet.conf
1. In the terminal run `git clone https://github.com/mcguirepr89/BirdNET-Lite.git ~/BirdNET-Lite`
1. You can copy the included *'birdnet.conf-defaults'* template to create and configure the BirdNET-Lite
to your needs before running the installer. Issue `cp ~/BirdNET-Lite/birdnet.conf-defaults ~/BirdNET-Lite/birdnet.conf`.
Edit the new *'birdnet.conf'* file to suit your needs and save it.
If you choose this method, the installation will be (nearly) non-interactive.
1. Setup zRAM swapping. Run `~/BirdNET-Lite/scripts/install_zram_service.sh && sudo reboot`
1. After the reboot, run `~/BirdNET-Lite/scripts/install_birdnet.sh`
#### Option 3 -- Interactive Installation
1. In the terminal run `git clone https://github.com/mcguirepr89/BirdNET-Lite.git ~/BirdNET-Lite`
1. Setup zRAM swapping. Run `~/BirdNET-Lite/scripts/install_zram_service.sh && sudo reboot`
1. After the reboot, run `~/BirdNET-Lite/scripts/install_birdnet.sh`
1. Follow the installation prompts to configure the BirdNET-Lite to your needs.
- Note: The installation should be run as a regular user. If run on an OS other than RaspiOS, be sure the regular user is in the sudoers file or the sudo group.
TFLite on x86 platform currently only supports CPUs.
## Access your BirdNET-Lite
If you configured BirdNET-Lite with the Caddy webserver, you can access the extractions locally at
Note: Make sure to set `CUDA_VISIBLE_DEVICES=""` in your environment variables. Or set `os.environ['CUDA_VISIBLE_DEVICES'] = ''` at the top of your Python script.
- http://birdnetsystem.local
In this example, we use Librosa to open audio files. Install Librosa with:
You can also view the log output for the <code>birdnet_analysis.service</code> and <code>extraction.service</code> at
```
sudo pip3 install librosa
sudo apt-get install ffmpeg
```
- http://birdlog.local
- http://extractionlog.local
You can use any other audio lib if you like, or pass raw audio signals to the model.
and the BirdNET-Lite Statistics Report at
- http://birdstats.local
If you don't use Librosa, make sure to install NumPy:
If you opt to also install NoMachine alongside the BirdNET-Lite, you can also access BirdNET-Lite
remotely following the address information that can be found on the NoMachine's server information page.
```
sudo pip3 install numpy
```
## Examples
These are examples of my personal instance of the BirdNET-Lite on a Raspberry Pi 4B.
- https://birdsounds.pmcgui.xyz -- My BirdNET-Lite Extractions page
- https://birdlog.pmcgui.xyz -- My 'birdlog' birdnet_analysis.service log
- https://extraction.pmcgui.xyz -- My 'extractionlog' extraction.service log
- https://birdstats.pmcgui.xyz -- My 'birdstats' BirdNET-Lite Report
Note: BirdNET expects 3-second chunks of raw audio data, sampled at 48 kHz.
## How to reconfigure the system
At any time, you can completely reconfigure the system to select or remove features. To reconfigure the system, simply run the included "reconfigure_birdnet.sh" script (as the regular user) and follow the prompts to create a new birdnet.conf file and install new services: `~/BirdNET-Lite/scripts/reconfigure_birdnet.sh`
## Raspberry Pi 4B running AArch64 OS
These steps install BirdNET-Lite on a Raspberry Pi 4B running an AArch64 OS using pre-built TFLite binaries.
1. Install dependencies<br>`sudo apt install swig libjpeg-dev zlib1g-dev python3-dev unzip wget python3-pip curl git cmake make`
1. Update pip, whell, and setuptools:<br>`sudo pip3 install --upgrade pip wheel setuptools`
1. Fetch pre-built binaries:
1. `curl -sc /tmp/cookie "https://drive.google.com/uc?export=download&id=1dlEbugFDJXs-YDBCUC6WjADVtIttWxZA" > /dev/null`
1. `CODE="$(awk '/_warning_/ {print $NF}' /tmp/cookie)"`
1. `curl -Lb /tmp/cookie "https://drive.google.com/uc?export=download&confirm=${CODE}&id=1dlEbugFDJXs-YDBCUC6WjADVtIttWxZA" -o tflite_runtime-2.6.0-cp37-none-linux_aarch64.whl`
1. `sudo pip3 install --upgrade tflite_runtime-2.6.0-cp37-none-linux_aarch64.whl`
1. `sudo pip3 install librosa`
1. `sudo apt-get install ffmpeg`
1. `git clone https://github.com/kahst/BirdNET-Lite.git`
1. `cd BirdNET-Lite/`<br>and test:
1. `python3 analyze.py --i 'example/XC558716 - Soundscape.mp3' --lat 35.4244 --lon -120.7463 --week 18`
## How to uninstall BirdNET-Lite
To remove BirdNET-Lite, run the included '*uninstall.sh*' script as the regular user.
1. Issue `/usr/local/bin/uninstall.sh && cd ~ && rm -drf BirdNET-Lite`
# Usage
## Troubleshooting
**General** -- At anytime, you can run the included `~/BirdNET-Lite/dump_logs.sh` script to create a compressed tar ball of system logs that may provide a helpful overview of the system services. In addition, you can upload it in a new issue along with a description of what you are experiencing. dump_logs.sh scrubs password information, but does retain LATITUDE and LONGITUDE information. If at all concerned with privacy, you're welcome to send them to me via email at mailto:mcguirepr89@gmail.com.
You can run BirdNET via the command line. You can add a few parameters that affect the output.
**Audio** -- If you have problems with the _bridnet_recording.service_ or _livestream.service_, try setting the REC_CARD setting in the _birdnet.conf_ file to `REC_CARD=default` and the CHANNELS variable to `CHANNELS=2`. This works for two very different microphones I have, so it may work for you. If it does, please let me know, as I may change the code as a result. Also, during installation, a file is created called `~/BirdNET-Lite/soundcard_params.txt` that may provide helpful information for customized settings.
The input parameters include:
```
--i, Path to input file.
--o, Path to output file. Defaults to result.csv.
--lat, Recording location latitude. Set -1 to ignore.
--lon, Recording location longitude. Set -1 to ignore.
--week, Week of the year when the recording was made. Values in [1, 48] (4 weeks per month). Set -1 to ignore.
--overlap, Overlap in seconds between extracted spectrograms. Values in [0.0, 2.9]. Defaults tp 0.0.
--sensitivity, Detection sensitivity; Higher values result in higher sensitivity. Values in [0.5, 1.5]. Defaults to 1.0.
--min_conf, Minimum confidence threshold. Values in [0.01, 0.99]. Defaults to 0.1.
--custom_list, Path to text file containing a list of species. Not used if not provided.
```
Note: A custom species list needs to contain one species label per line. Take a look at the `model/label.txt` for the correct species label. Only labels from this text file are valid. You can find an example of a valid custom list in the 'example' folder.
Here are two example commands to run this BirdNET version:
```
python3 analyze.py --i 'example/XC558716 - Soundscape.mp3' --lat 35.4244 --lon -120.7463 --week 18
python3 analyze.py --i 'example/XC563936 - Soundscape.mp3' --lat 47.6766 --lon -122.294 --week 11 --overlap 1.5 --min_conf 0.25 --sensitivity 1.25 --custom_list 'example/custom_species_list.txt'
```
Note: Please make sure to provide lat, lon, and week. BirdNET will work without these values, but the results might be less reliable.
The results of the anlysis will be stored in a result file in CSV format. All confidence values are raw prediction scores and should be post-processed to eliminate occasional false-positive results.
# Contact us
Please don't hesitate to contact us if you have any issues with the code or if you have any other remarks or questions.
Our e-mail address: ccb-birdnet@cornell.edu
We are always open for a collaboration with you.
# Funding
This project is supported by Jake Holshuh (Cornell class of ’69). The Arthur Vining Davis Foundations also kindly support our efforts.
**Installation** -- The installer _should_ always create a compressed set of system logs whether it succeeds or fails. Its location is `~/BirdNET-Lite/logs.tar.gz`. Take a look through there or feel free to create a new issue and upload it along with a description of what you are experiencing.
### TODO & Notes:
1. I ought to add the steps to setup a Pushed.co application for the mobile notifications feature. Here is a link for now https://pushed.co/quick-start-guide