A python api for BirdNET-Analyzer and BirdNET-Lite
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 birdnetlibbirdnetlib provides a common interface for BirdNET-Analyzer and BirdNET-Lite.
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}]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)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.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 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 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 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}, ...]- 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.
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:
birdnetlib is not associated with BirdNET-Lite, BirdNET-Analyzer or the K. Lisa Yang Center for Conservation Bioacoustics.
birdnetlib is maintained by Joe Weiss. Contributions are welcome.
- 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