@article{kahl2021birdnet,
  title={BirdNET: A deep learning solution for avian diversity monitoring},
  author={Kahl, Stefan and Wood, Connor M and Eibl, Maximilian and Klinck, Holger},
  journal={Ecological Informatics},
  volume={61},
  pages={101236},
  year={2021},
  publisher={Elsevier}
}

If you want to analyze audio files without any additional coding or package install, you can now use Raven Pro software to run BirdNET models. After download, BirdNET is available through the new "Learning detector" feature in Raven Pro. For more information on how to use this feature, please visit the Raven Pro Knowledge Base.

The easiest way to setup BirdNET on your machine is to install birdnetlib through pip with:

Make sure to install Tensorflow Lite, librosa and ffmpeg like mentioned below. You can run BirdNET with:

For more examples and documentation, make sure to visit pypi.org/project/birdnetlib/. For any feature request or questions regarding birdnetlib, please contact Joe Weiss or add an issue or PR at github.com/joeweiss/birdnetlib.

Install Python 3:

Install TFLite runtime (recommended) or Tensorflow (has to be 2.5 or later):

Install Librosa to handle audio files:

Clone the repository

Before you attempt to setup BirdNET-Analyzer on your Windows machine, please consider downloading our fully-packaged version that does not require you to install any additional packages and can be run "as-is".

You can download this version here: BirdNET-Analyzer Windows

1. Download the zip file

2. Before unpacking, make sure to right-click the zip-file, select "Properties" and check the box "Unblock" under "Security" at the bottom of the "General" tab.

   • If Windows does not display this option, the file can be unblocked with the PowerShell 7 command Unblock-File -Path .\BirdNET-Analyzer.zip

3. Unpack the zip-file

4. Navigate to the extracted folder named "BirdNET-Analyzer"

5. You can start the analysis through the command prompt with BirdNET-Analyzer.exe --i "path\to\folder" ... (see Usage (CLI) section for more details), or you can launch BirdNET-Analyzer-GUI.exe to start the analysis through a basic GUI.

For more advanced use cases (e.g., hosting your own API server), follow these steps to set up BirdNET-Analyzer on your Windows machine:

Install Python 3.9 or higher (has to be 64bit version)

• Download and run installer: Download Python installer

Install Tensorflow (has to be 2.5 or later), Librosa and NumPy

• Open command prompt with Win + S type "command" and click on "Command Prompt"

• Type pip install --upgrade pip

• Type pip install librosa resampy numpy==1.20

• Install Tensorflow by typing pip install tensorflow

Install Visual Studio Code (optional)

• Download and install VS Code: Download VS Code installer

• Select all available options during install

Install BirdNET using Git (for simple download see below)

• Download and install Git Bash: Download Git Bash installer

• Select Visual Studio Code as default editor (optional)

• Keep all other settings as recommended

• Create folder in personal directory called "Code" (or similar)

• Change to folder and right click, launch "Git bash here"

• Type git clone https://github.com/kahst/BirdNET-Analyzer.git

• Keep BirdNET updated by running git pull for BirdNET-Analyzer folder occasionally

Install BirdNET from zip

• Download BirdNET: Download BirdNET Zip-file

• Unpack zip file (e.g., in personal directory)

• Keep BirdNET updated by re-downloading the zip file occasionally and overwrite existing files

Run BirdNET from command line

• Open command prompt with Win + S type "command" and click on "Command Prompt"

• Navigate to the folder where you installed BirdNET (cd path\to\BirdNET-Analyzer)

• See Usage (CLI) section for command line arguments

Requirements

xcode-select --install

curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ~/Downloads/Miniconda3-latest-MacOSX-arm64.sh
bash ~/Downloads/Miniconda3-latest-MacOSX-arm64.sh -b -p $HOME/miniconda

curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -o ~/Downloads/Miniconda3-latest-MacOSX-x86_64.sh
bash ~/Downloads/Miniconda3-latest-MacOSX-x86_64.sh -b -p $HOME/miniconda

conda config --add channels conda-forge

Create Conda Environment

conda create -n birdnet-analyzer python=3.10 -c conda-forge -y
conda activate birdnet-analyzer

Install dependencies

conda install -c apple tensorflow-deps

python -m pip install tensorflow-macos tensorflow-metal

conda install -c conda-forge librosa resampy -y

Verify

git clone https://github.com/kahst/BirdNET-Analyzer.git
cd BirdNET-Analyzer

python analyze.py

1. Inspect config file for options and settings, especially inference settings. Specify a custom species list if needed and adjust the number of threads TFLite can use to run the inference.

2. Run analyzer.py to analyze an audio file. You need to set paths for the audio file and selection table output. Here is an example:

   python3 analyze.py --i /path/to/audio/folder --o /path/to/output/folder

   ℹ️

   Your custom species list has to be named 'species_list.txt' and the folder containing the list needs to be specified with --slist /path/to/folder. You can also specify the number of CPU threads that should be used for the analysis with --threads <Integer> (e.g., --threads 16). If you provide GPS coordinates with --lat and --lon, the custom species list argument will be ignored.

   Here’s a complete list of all command line arguments:

   --i, Path to input file or folder. If this is a file, --o needs to be a file too.
   --o, Path to output file or folder. If this is a file, --i needs to be a file too.
   --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 for year-round species list.
   --slist, Path to species list file or folder. If folder is provided, species list needs to be named "species_list.txt". If lat and lon are provided, this list will be ignored.
   --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.
   --overlap, Overlap of prediction segments. Values in [0.0, 2.9]. Defaults to 0.0.
   --rtype, Specifies output format. Values in ['table', 'audacity', 'r', 'kaleidoscope', 'csv']. Defaults to 'table' (Raven selection table).
   --threads, Number of CPU threads.
   --batchsize, Number of samples to process at the same time. Defaults to 1.
   --locale, Locale for translated species common names. Values in ['af', 'de', 'it', ...] Defaults to 'en'.
   --sf_thresh, Minimum species occurrence frequency threshold for location filter. Values in [0.01, 0.99]. Defaults to 0.03.
   --classifier, Path to custom trained classifier. Defaults to None. If set, --lat, --lon and --locale are ignored.

   Here are two example commands to run this BirdNET version:

   python3 analyze.py --i example/ --o example/ --slist example/ --min_conf 0.5 --threads 4
   
   python3 analyze.py --i example/ --o example/ --lat 42.5 --lon -76.45 --week 4 --sensitivity 1.0

3. Run embeddings.py to extract feature embeddings instead of class predictions. Result file will contain timestamps and lists of float values representing the embedding for a particular 3-second segment. Embeddings can be used for clustering or similarity analysis. Here is an example:

   python3 embeddings.py --i example/ --o example/ --threads 4 --batchsize 16

   Here’s a complete list of all command line arguments:

   --i, Path to input file or folder. If this is a file, --o needs to be a file too.
   --o, Path to output file or folder. If this is a file, --i needs to be a file too.
   --overlap, Overlap of prediction segments. Values in [0.0, 2.9]. Defaults to 0.0.
   --threads, Number of CPU threads.
   --batchsize, Number of samples to process at the same time. Defaults to 1.

4. After the analysis, run segments.py to extract short audio segments for species detections to verify results. This way, it might be easier to review results instead of loading hundreds of result files manually.

   Here’s a complete list of all command line arguments:

   --audio, Path to folder containing audio files.
   --results, Path to folder containing result files.
   --o, Output folder path for extracted segments.
   --min_conf, Minimum confidence threshold. Values in [0.01, 0.99]. Defaults to 0.1.
   --max_segments, Number of randomly extracted segments per species.
   --seg_length, Length of extracted segments in seconds. Defaults to 3.0.
   --threads, Number of CPU threads.

5. When editing your own species_list.txt file, make sure to copy species names from the labels file of each model.

   You can find label files in the checkpoints folder, e.g., checkpoints/V2.3/BirdNET_GLOBAL_3K_V2.3_Labels.txt.

   Species names need to consist of scientific name_common name to be valid.

6. You can generate a species list for a given location using species.py in case you need it for reference. Here is an example:

   python3 species.py --o example/species_list.txt --lat 42.5 --lon -76.45 --week 4

   Here’s a complete list of all command line arguments:

   --o, Path to output file or folder. If this is a folder, file will be named 'species_list.txt'.
   --lat, Recording location latitude.
   --lon, Recording location longitude.
   --week, Week of the year when the recording was made. Values in [1, 48] (4 weeks per month). Set -1 for year-round species list.
   --threshold, Occurrence frequency threshold. Defaults to 0.05.
   --sortby, Sort species by occurrence frequency or alphabetically. Values in ['freq', 'alpha']. Defaults to 'freq'.

7. This is a very basic version of the analysis workflow, you might need to adjust it to your own needs.

8. Please open an issue to ask for new features or to document unexpected behavior.

9. I will keep models up to date and upload new checkpoints whenever there is an improvement in performance. I will also provide quantized and pruned model files for distribution.

Install docker for Ubuntu:

Build Docker container:

In order to pass a directory that contains your audio files to the docker file, you need to mount it inside the docker container with -v /my/path:/mount/path before you can run the container.

You can run the container for the provided example soundscapes with:

You can adjust the directory that contains your recordings by providing an absolute path:

You can also mount more than one drive, e.g., if input and output folder should be different:

See Usage (CLI) section above for more command line arguments, all of them will work with Docker version.

You can host your own analysis service and API by launching the server.py script. This will allow you to send files to this server, store submitted files, analyze them and send detection results back to a client. This could be a local service, running on a desktop PC, or a remote server. The API can be accessed locally or remotely through a browser or Python client (or any other client implementation).

1. Install one additional package with pip3 install bottle.

2. Start the server with python3 server.py. You can also specify a host name or IP and port number, e.g., python3 server.py --host localhost --port 8080.

   Here’s a complete list of all command line arguments:

   --host, Host name or IP address of API endpoint server. Defaults to '0.0.0.0'.
   --port, Port of API endpoint server. Defaults to 8080.
   --spath, Path to folder where uploaded files should be stored. Defaults to '/uploads'.
   --threads, Number of CPU threads for analysis. Defaults to 4.
   --locale, Locale for translated species common names. Values in ['af', 'de', 'it', ...] Defaults to 'en'.

   ℹ️	The server is single-threaded, so you’ll need to start multiple instances for higher throughput. This service is intented for short audio files (e.g., 1-10 seconds).

3. Query the API with a client. You can use the provided Python client or any other client implementation. Request payload needs to be multipart/form-data with the following fields: audio for raw audio data as byte code, and meta for additional information on the audio file. Take a look at our example client implementation in the client.py script.

   This script will read an audio file, generate metadata from command line arguments and send it to the server. The server will then analyze the audio file and send back the detection results which will be stored as a JSON file.

   Here’s a complete list of all command line arguments:

   --host, Host name or IP address of API endpoint server.
   --port, Port of API endpoint server.
   --i, Path to file that should be analyzed.
   --o, Path to result file. Leave blank to store with audio file.
   --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 for year-round species list.
   --overlap, Overlap of prediction segments. Values in [0.0, 2.9]. Defaults to 0.0.
   --sensitivity, Detection sensitivity; Higher values result in higher sensitivity. Values in [0.5, 1.5]. Defaults to 1.0.
   --pmode, Score pooling mode. Values in ['avg', 'max']. Defaults to 'avg'.
   --num_results, Number of results per request.
   --sf_thresh, Minimum species occurrence frequency threshold for location filter. Values in [0.01, 0.99]. Defaults to 0.03.
   --save, Define if files should be stored on server. Values in [True, False]. Defaults to False.

4. Parse results from the server. The server will send back a JSON response with the detection results. The response also contains a msg field, indicating success or error. Results consist of a sorted list of (species, score) tuples.

   This is an example response:

   {"msg": "success", "results": [["Poecile atricapillus_Black-capped Chickadee", 0.7889], ["Spinus tristis_American Goldfinch", 0.5028], ["Junco hyemalis_Dark-eyed Junco", 0.4943], ["Baeolophus bicolor_Tufted Titmouse", 0.4345], ["Haemorhous mexicanus_House Finch", 0.2301]]}

   ℹ️	Let us know if you have any questions, suggestions, or feature requests. Also let us know when hosting an analysis service - we would love to give it a try.

We provide a very basic GUI which lets you launch the analysis through a web interface.

1. You need to install two additional packages in order to use the GUI with pip3 install pywebview gradio

2. Launch the GUI with python3 gui.py.

3. Set all folders and parameters, after that, click 'Analyze'.