birdnetlib 0.0.11

A python api for BirdNET-Lite and BirdNET-Analyzer

birdnetlib

A python api for BirdNET-Lite and BirdNET-Analyzer

Installation

birdnetlib requires Python 3.7+ 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-Lite and BirdNET-Analyzer.

Using BirdNET-Lite

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

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

# Load and initialize the BirdNET-Lite models.
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.

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 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)

Other common helper classes

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.

DirectoryWatcherMultiAnalyzer

DirectoryWatcherMultiAnalyzer can watch a directory and analyze new files as they are created, with multiple analyzer models.

def on_analyze_all_complete(recording_list):
    for recording in recording_list:
        print(recording.path, recording.analyzer.name)
        pprint(recording.detections)

analyzer_lite = LiteAnalyzer()
analyzer = Analyzer()

watcher = DirectoryWatcherMultiAnalyzer(
    "/Birds/mp3_dir",
    analyzers=[analyzer, analyzer_lite],
)
watcher.on_analyze_all_complete = on_analyze_all_complete
watcher.watch()

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

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.

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