# birdnet-team/birdnet architecture

> Architecture diagram of the GitHub repository birdnet-team/birdnet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/birdnet-team/birdnet
- Repository: https://github.com/birdnet-team/birdnet

## Overview

BirdNET is a Python library for acoustic bird identification, with a companion location-and-time species-presence capability. The primary workflow loads an acoustic model and backend, then predicts from audio files or arrays; users can also extract embeddings. Acoustic sessions coordinate processing and return prediction or encoding results. The README documents model-family, custom-classifier, multilingual, and export capabilities. Several implementation details are represented at subsystem level because their source was not sampled; edges are limited to README statements or relationships shown in indexed/read source.

Main entry points: [`src/birdnet/acoustic/models`](https://github.com/birdnet-team/birdnet/tree/main/src/birdnet/acoustic/models) (Acoustic models), [`src/birdnet/acoustic/inference/session.py`](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/session.py) (Acoustic session), [`src/birdnet/model_loader.py`](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/model_loader.py) (Model loader), [`src/birdnet/geo/models`](https://github.com/birdnet-team/birdnet/tree/main/src/birdnet/geo/models) (Geo models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Public API and loading"]
  node_api["Python API<br/>[__init__.py]"]
  node_loader["Model loader<br/>[model_loader.py]"]
end

subgraph group_acoustic["Acoustic analysis"]
  node_acoustic_session["Acoustic session<br/>[session.py]"]
  node_prediction["Score prediction"]
  node_embeddings["Embedding extraction<br/>[encoding_result.py]"]
  node_audio_utils["Audio utilities<br/>[audio_files.py]"]
  node_export["Result export<br/>[result_base.py]"]
end

subgraph group_compute["Inference runtime"]
  node_process_manager["Process manager<br/>[process_manager.py]"]
  node_worker["Inference workers<br/>[worker.py]"]
  node_backends["Runtime backends<br/>[backends.py]"]
end

subgraph group_models["Models and metadata"]
  node_acoustic_model["Acoustic models"]
  node_custom_model["Custom classifiers<br/>[custom_tflite.py]"]
  node_species["Species names<br/>[species_lists.py]"]
  node_downloads["Model downloads<br/>[downloads.py]"]
end

subgraph group_geo["Geographic prediction"]
  node_geo_model["Geo models"]
  node_geo_session["Geo session<br/>[session.py]"]
  node_geo_result["Presence result"]
end

node_user(("Library user"))
node_runtime["ML runtimes"]
node_audio_files["Audio files"]

node_user -->|"calls"| node_api
node_api -->|"loads models"| node_loader
node_loader -->|"selects"| node_acoustic_model
node_loader -->|"selects"| node_geo_model
node_loader -->|"loads custom"| node_custom_model
node_acoustic_model -->|"runs prediction"| node_acoustic_session
node_acoustic_model -->|"extracts embeddings"| node_acoustic_session
node_acoustic_session -->|"starts processing"| node_process_manager
node_process_manager -->|"coordinates workers"| node_worker
node_worker -->|"uses backend"| node_backends
node_backends -->|"executes model"| node_runtime
node_audio_files -->|"provides audio"| node_acoustic_model
node_acoustic_session -->|"returns scores"| node_prediction
node_acoustic_session -->|"returns embeddings"| node_embeddings
node_geo_model -->|"predicts presence"| node_geo_session
node_geo_session -->|"returns result"| node_geo_result
node_acoustic_model -->|"gets official models"| node_downloads
node_acoustic_model -->|"uses labels"| node_species
node_geo_model -->|"uses species list"| node_species
node_prediction -->|"serializes result"| node_export
node_embeddings -->|"serializes result"| node_export
node_audio_files -->|"supports formats"| node_audio_utils

click node_api "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/__init__.py"
click node_loader "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/model_loader.py"
click node_acoustic_model "https://github.com/birdnet-team/birdnet/tree/main/src/birdnet/acoustic/models"
click node_custom_model "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/models/custom_tflite.py"
click node_geo_model "https://github.com/birdnet-team/birdnet/tree/main/src/birdnet/geo/models"
click node_acoustic_session "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/session.py"
click node_prediction "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/core/prediction/prediction_result.py"
click node_embeddings "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/core/encoding/encoding_result.py"
click node_geo_session "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/geo/inference/session.py"
click node_geo_result "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/geo/inference/prediction_result.py"
click node_process_manager "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/process_manager.py"
click node_worker "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/core/worker.py"
click node_backends "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/core/backends.py"
click node_audio_utils "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/utils/audio_files.py"
click node_species "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/utils/species_lists.py"
click node_downloads "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/utils/downloads.py"
click node_export "https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/core/result_base.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_loader,node_user toneBlue
class node_acoustic_session,node_prediction,node_embeddings,node_audio_utils,node_export toneAmber
class node_process_manager,node_worker,node_backends toneMint
class node_acoustic_model,node_custom_model,node_species,node_downloads toneRose
class node_geo_model,node_geo_session,node_geo_result,node_runtime,node_audio_files toneIndigo
```

## Components

### Public API and loading

- [Python API](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/__init__.py): `src/birdnet/__init__.py`
- [Model loader](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/model_loader.py): `src/birdnet/model_loader.py`

### Acoustic analysis

- [Acoustic session](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/session.py): `src/birdnet/acoustic/inference/session.py`
- [Score prediction](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/core/prediction/prediction_result.py): `src/birdnet/acoustic/inference/core/prediction/prediction_result.py`
- [Embedding extraction](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/core/encoding/encoding_result.py): `src/birdnet/acoustic/inference/core/encoding/encoding_result.py`
- [Audio utilities](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/utils/audio_files.py): `src/birdnet/utils/audio_files.py`
- [Result export](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/core/result_base.py): `src/birdnet/acoustic/inference/core/result_base.py`

### Inference runtime

- [Process manager](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/process_manager.py): `src/birdnet/acoustic/inference/process_manager.py`
- [Inference workers](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/inference/core/worker.py): `src/birdnet/acoustic/inference/core/worker.py`
- [Runtime backends](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/core/backends.py): `src/birdnet/core/backends.py`

### Models and metadata

- [Acoustic models](https://github.com/birdnet-team/birdnet/tree/main/src/birdnet/acoustic/models): `src/birdnet/acoustic/models`
- [Custom classifiers](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/acoustic/models/custom_tflite.py): `src/birdnet/acoustic/models/custom_tflite.py`
- [Species names](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/utils/species_lists.py): `src/birdnet/utils/species_lists.py`
- [Model downloads](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/utils/downloads.py): `src/birdnet/utils/downloads.py`

### Geographic prediction

- [Geo models](https://github.com/birdnet-team/birdnet/tree/main/src/birdnet/geo/models): `src/birdnet/geo/models`
- [Geo session](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/geo/inference/session.py): `src/birdnet/geo/inference/session.py`
- [Presence result](https://github.com/birdnet-team/birdnet/blob/main/src/birdnet/geo/inference/prediction_result.py): `src/birdnet/geo/inference/prediction_result.py`

### Other components

- **Library user**
- **ML runtimes**
- **Audio files**

## Connections

- Library user → Python API: calls (evidence: `README.md`)
- Python API → Model loader: loads models (evidence: `src/birdnet_benchmark/cli.py`)
- Model loader → Acoustic models: selects (evidence: `src/birdnet/model_loader.py`)
- Model loader → Geo models: selects (evidence: `src/birdnet/model_loader.py`)
- Model loader → Custom classifiers: loads custom (evidence: `src/birdnet/model_loader.py`)
- Acoustic models → Acoustic session: runs prediction (evidence: `src/birdnet/acoustic/models/v3_0/model.py`)
- Acoustic models → Acoustic session: extracts embeddings (evidence: `src/birdnet/acoustic/models/v3_0/model.py`)
- Acoustic session → Process manager: starts processing (evidence: `src/birdnet/acoustic/inference/session.py`)
- Process manager → Inference workers: coordinates workers (evidence: `src/birdnet/acoustic/inference/process_manager.py`)
- Inference workers → Runtime backends: uses backend (evidence: `src/birdnet/acoustic/inference/core/worker.py`)
- Runtime backends → ML runtimes: executes model (evidence: `src/birdnet/core/backends.py`)
- Audio files → Acoustic models: provides audio (evidence: `README.md`)
- Acoustic session → Score prediction: returns scores (evidence: `src/birdnet/acoustic/inference/session.py`)
- Acoustic session → Embedding extraction: returns embeddings (evidence: `src/birdnet/acoustic/inference/session.py`)
- Geo models → Geo session: predicts presence (evidence: `src/birdnet/geo/models/base.py`)
- Geo session → Presence result: returns result (evidence: `src/birdnet/geo/inference/session.py`)
- Acoustic models → Model downloads: gets official models (evidence: `src/birdnet/acoustic/models/v3_0/model.py`)
- Acoustic models → Species names: uses labels (evidence: `src/birdnet/acoustic/models/v3_0/model.py`)
- Geo models → Species names: uses species list (evidence: `src/birdnet/geo/models/base.py`)
- Score prediction → Result export: serializes result (evidence: `src/birdnet/acoustic/inference/core/prediction/prediction_result.py`)
- Embedding extraction → Result export: serializes result (evidence: `src/birdnet/acoustic/inference/core/encoding/encoding_result.py`)
- Audio files → Audio utilities: supports formats (evidence: `README.md`)
