Classes

Recording Classes

Recording

Use the Recording class to open and analyze a file from disk.

from birdnetlib import Recording
from birdnetlib.analyzer import Analyzer

analyzer = Analyzer()

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

All recording classes can accept an optional lat, lon and date arguments, which will limit the detections to species to those predicted to be included.

from birdnetlib import Recording
from birdnetlib.analyzer import Analyzer

analyzer = Analyzer()

recording = Recording(
    analyzer,
    "sample.mp3",
    min_conf=0.25,
    lat=35.6,
    lon=-77.3,
    date=datetime(year=2023, month=6, day=27),
)
recording.analyze()
print(recording.detections)

It is also possible to return all detections, but annotate the detection if the species is on the predicted list for that location and date.

from birdnetlib import Recording
from birdnetlib.analyzer import Analyzer

analyzer = Analyzer()

recording = Recording(
    analyzer,
    "sample.mp3",
    min_conf=0.25,
    lat=35.6,
    lon=-77.3,
    date=datetime(year=2023, month=6, day=27),
    is_predicted_for_location_and_date=True,
)
recording.analyze()
print(recording.detections)

Embeddings

To extract feature embeddings instead of class predictions, use the extract_embeddings method.

from birdnetlib import Recording
from birdnetlib.analyzer import Analyzer

analyzer = Analyzer()
recording = Recording(
    analyzer,
    "sample.mp3",
)
recording.extract_embeddings()
print(recording.embeddings)

RecordingFileObject

Use the RecordingFileObject class to analyze an in-memory file object.

with io.BytesIO(r.content) as fileObj:
    recording = RecordingFileObject(
        analyzer,
        fileObj,
        lat=35.6,
        lon=-77.3,
        date=datetime(year=2023, month=6, day=27),  # use date or week_48
        min_conf=0.25,
    )
    recording.analyze()
    pprint(recording.detections)

See Download and analyzer an audio file from a URL for a working implementation of RecordingFileObject.

RecordingBuffer

Use the RecordingBuffer class to analyze an in-memory array buffer.

See the example Analyze an audio stream in realtime using RecordingBuffer class for more information.

Analyzer classes

Analyzer

Using specific versions of BirdNET-Analyzer

To use a specific version of BirdNET-Analyzer model, pass the version to the Analyzer class.

# Load and initialize the BirdNET-Analyzer 2.3 model.
analyzer = Analyzer(version="2.3")

Note: birdnetlib is compatible with BirdNET-Analyzer model versions 2.1 and higher. For more information on specific versions of BirdNET-Analyzer, see their model version history.

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)

LiteAnalyzer - 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.