birdnetlib 0.9.0

A python api for BirdNET-Lite and BirdNET-Analyzer

birdnetlib

A python api for BirdNET-Analyzer and BirdNET-Lite

Installation

birdnetlib requires Python 3.9+ and prior installation of Tensorflow Lite, librosa and ffmpeg. See BirdNET-Analyzer for more details on installing the Tensorflow-related dependencies.

pip install birdnetlib

Documentation

birdnetlib provides a common interface for BirdNET-Analyzer and BirdNET-Lite.

Using BirdNET-Analyzer

To use the newer BirdNET-Analyzer model, use the Analyzer class.

from birdnetlib import Recording
from birdnetlib.analyzer import Analyzer
from datetime import datetime

# Load and initialize the BirdNET-Analyzer models.
analyzer = Analyzer()

recording = Recording(
    analyzer,
    "sample.mp3",
    lat=35.4244,
    lon=-120.7463,
    date=datetime(year=2022, month=5, day=10), # use date or week_48
    min_conf=0.25,
)
recording.analyze()
print(recording.detections)

recording.detections contains a list of detected species, along with time ranges and confidence value.

[{'common_name': 'House Finch',
  'confidence': 0.5744,
  'end_time': 12.0,
  'scientific_name': 'Haemorhous mexicanus',
  'start_time': 9.0},
 {'common_name': 'House Finch',
  'confidence': 0.4496,
  'end_time': 15.0,
  'scientific_name': 'Haemorhous mexicanus',
  'start_time': 12.0}]

Using a custom classifier with BirdNET-Analyzer

To use a model trained with BirdNET-Analyzer, pass your labels and model path to the Analyzer class.

from birdnetlib import Recording
from birdnetlib.analyzer import Analyzer

# Load and initialize BirdNET-Analyzer with your own model/labels.

custom_model_path = "custom_classifiers/trogoniformes.tflite"
custom_labels_path = "custom_classifiers/trogoniformes.txt"

analyzer = Analyzer(
    classifier_labels_path=custom_labels_path, classifier_model_path=custom_model_path
)

recording = Recording(
    analyzer,
    "sample.mp3",
    min_conf=0.25,
)
recording.analyze()
print(recording.detections)

Using BirdNET-Lite

To use the legacy BirdNET-Lite model, use the LiteAnalyzer class.

Note: The BirdNET-Lite project has been deprecated. The BirdNET-Lite model is no longer included in the PyPi birdnetlib package. This model and label file will be downloaded and installed the first time the LiteAnalyzer is initialized in your Python environment.

from birdnetlib import Recording
from birdnetlib.analyzer_lite import LiteAnalyzer
from datetime import datetime

# Load and initialize the BirdNET-Lite models.
# If this is the first time using LiteAnalyzer, the model will be downloaded into your Python environment.
analyzer = LiteAnalyzer()

recording = Recording(
    analyzer,
    "sample.mp3",
    lat=35.4244,
    lon=-120.7463,
    date=datetime(year=2022, month=5, day=10), # use date or week_48
    min_conf=0.25,
)
recording.analyze()
print(recording.detections) # Returns list of detections.

Utility classes

DirectoryAnalyzer

DirectoryAnalyzer can process a directory and analyze contained files.

def on_analyze_complete(recording):
    print(recording.path)
    pprint(recording.detections)

directory = DirectoryAnalyzer(
    "/Birds/mp3_dir",
    patterns=["*.mp3", "*.wav"]
)
directory.on_analyze_complete = on_analyze_complete
directory.process()

See the full example for analyzer options and error handling callbacks.

DirectoryMultiProcessingAnalyzer

DirectoryMultiProcessingAnalyzer can process a directory and analyze contained files, using multiple processes asynchronously.

def on_analyze_directory_complete(recordings):
    for recording in recordings:
        pprint(recording.detections)

directory = "."
batch = DirectoryMultiProcessingAnalyzer(
    "/Birds/mp3_dir",
    patterns=["*.mp3", "*.wav"]
)

batch.on_analyze_directory_complete = on_analyze_directory_complete
batch.process()

See the full example for analyzer options and error handling callbacks.

DirectoryWatcher

DirectoryWatcher can watch a directory and analyze new files as they are created.

def on_analyze_complete(recording):
    print(recording.path)
    pprint(recording.detections)

watcher = DirectoryWatcher("/Birds/mp3_dir")
watcher.on_analyze_complete = on_analyze_complete
watcher.watch()

See the full example for analyzer options and error handling callbacks.

SpeciesList

SpeciesList uses BirdNET-Analyzer to predict species lists from location and date.

species = SpeciesList()
species_list = species.return_list(
    lon=-120.7463, lat=35.4244, date=datetime(year=2022, month=5, day=10)
)
print(species_list)
# [{'scientific_name': 'Haemorhous mexicanus', 'common_name': 'House Finch', 'threshold': 0.8916686}, ...]

Additional examples

• Watch a directory for new files, then analyze with both analyzer models as files are saved
• Watch a directory for new files, and apply datetimes by parsing file names (eg 2022-08-15-birdnet-21:05:52.wav) prior to analyzing This example can also be used to modify lat/lon, min_conf, etc., based on file name prior to analyzing.
• Limit detections to certain species by passing a predefined species list to the analyzer Useful when searching for a particular set of bird detections.
• Extract detections as audio file samples and/or spectrograms Supports audio extractions as .flac, .wav and .mp3. Spectrograms exported as .png, .jpg, or other matplotlib.pyplot supported formats. Can be filtered to only extract files above a separate minimum confidence value.

About BirdNET-Lite and BirdNET-Analyzer

birdnetlib uses models provided by BirdNET-Lite and BirdNET-Analyzer under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License.

BirdNET-Lite and BirdNET-Analyzer were developed by the K. Lisa Yang Center for Conservation Bioacoustics at the Cornell Lab of Ornithology.

For more information on BirdNET analyzers, please see the project repositories below:

BirdNET-Analyzer

BirdNET-Lite

birdnetlib is not associated with BirdNET-Lite, BirdNET-Analyzer or the K. Lisa Yang Center for Conservation Bioacoustics.

About birdnetlib

birdnetlib is maintained by Joe Weiss. Contributions are welcome.

Project Goals

• Establish a unified API for interacting with Tensorflow-based BirdNET analyzers
• Enable python-based test cases for BirdNET analyzers
• Make it easier to use BirdNET in python-based projects
• Make it easier to migrate to new BirdNET versions/models as they become available