acoupi

Tip

Read the latest documentation

Readme Content

• What is acoupi?
• Requirements
• Installation
• Ready to use AI Bioacoustic Classifiers
  • BatDetect2
  • BirdNET-Lite
• Acoupi software architecture
  • Framework
  • Application
• Features and Development

What is acoupi?

acoupi is an open-source Python package that streamlines bioacoustic classifier deployment on edge devices like the Raspberry Pi. It integrates and standardises the entire bioacoustic monitoring workflow, from recording to classification. With various components and templates, acoupi simplifies the creation of custom sensors, handling audio recordings, processing, classifications, detections, communication, and data management.

Figure 1: An overview of acoupi software. Input your recording settings and deep learning model of choice, and acoupi handles the rest, sending detections where you need them.

Requirements

acoupi has been designed to run on single-board computer devices like the Raspberry Pi (RPi). Users should be able to download and test acoupi software on any Linux-based machines with Python version >=3.8,<3.12 installed.

• A Linux-based single board computer such as the Raspberry Pi 4B.
• A SD Card with 64-bit Lite OS version installed.
• A USB Microphone such as an AudioMoth, a µMoth, an Ultramic 192K/250K.

Tip

Recomended Hardware

The software has been extensively developed and tested with the RPi 4B. We advise users to select the RPi 4B or a device featuring similar specifications.

Installation

To install and use the bare-bone framework of acoupi on your embedded device follow these steps:

Step 1: Install acoupi and its dependencies.

curl -sSL https://github.com/acoupi/acoupi/raw/main/scripts/setup.sh | bash

Step 2: Configure an acoupi program.

acoupi setup --program `program-name`

acoupi includes two pre-built programs; a default and a connected program. The default program only records and saves audio files based on users' settings. This program does not do any audio processing neither send any messages, being comparable to an AudioMoth. The connected program is similar to the default program but with the added capability of sending messages to a remote server.

Configure acoupi default program"

acoupi setup --program acoupi.programs.default

Configure acoupi connected program"

acoupi setup --program acoupi.programs.connected

Step 3: Start the deployment of your acoupi's configured program.

acoupi deployment start

Tip

To check what are the available commands for acoupi, enter acoupi --help.

Ready to use AI Bioacoustic Classifiers

acoupi simplifies the use and implementation of open-source AI bioacoustic models. Currently, it supports two classifiers: the BatDetect2, developed by @macodha and al., and the BirdNET-Lite, developed by @kahst and al..

Warning

Licenses and Usage

Before using a pre-trained AI bioacoustic classifier, review its license to ensure it aligns with your intended use. acoupi programs built with these models inherit the corresponding model licenses. For further licensing details, refer to the FAQ section.

Warning

Model Output Reliability

Please note that acoupi is not responsible for the accuracy or reliability of model predictions. It is crucial to understand the performance and limitations of each model before using it in your project.

Important

Please make sure you are aware of their license, if you use these models.

BatDetect2

The BatDetect2 bioacoustic DL model has been trained to detect and classify UK bats species. The acoupi_batdetect2 repository provides users with a pre-built acoupi program that can be configured and tailored to their use cases.

Step 1: Install acoupi_batdetect2 program.

pip install acoupi_batdetect2

Step 2: Setup and configure acoupi_batdetect2 program.

acoupi setup --program acoupi_batdetect2.program

BirdNET-Lite (COMING SOON!)

The BirdNET-Lite bioacoustic DL model has been trained to detect and classify a large number of bird species. The acoupi_birdnet repository provides users with a pre-build acoupi program that can be configured and tailored to their use cases of birds monitoring.

Install acoupi_birdnet program.

pip install acoupi_birdnet

Setup and configure acoupi_birdnet program.

acoupi setup --program acoupi_birdnet.program

In development 🐳🐘🐝

Tip

Interested in sharing your AI bioacoustic model with the community?

acoupi allows you to integrate your own bioacoustic classifier model. If you already have a model and would like to share it with the community, we'd love to hear from you! We are happy to offer guidance and support to help include your classifier in the acoupi list of "ready-to-use" AI bioacoustic classifiers.

acoupi Software

Acoupi software is divided into two parts; the code-based architecture and the running application. The acoupi framework is organised into layers that ensure standardisation of data while providing flexibility of configuration. The acoupi application provides a simple command line interface (CLI) allowing users to configure the acoupi framework for deployment.

acoupi Framework

The acoupi software has been designed to provide maximum flexibility and keep away the internal complexity from a user. The architecture is made of four intricate elements, which we call the data schema, components, tasks, and programs.

The figure below provides a simplified example of an acoupi program. This program illustrates some of the most important data schema, components, and tasks.

Figure 2: An example of a simplified acoupi program.This example program implements the four tasks; audio recording, model, communication and management. Each task is composed of components executing specific actions such as recording an audio file, processing it, sending results, and storing associated metadata. The components input or output data objects defined by the data schema to validate format of information flowing between components and tasks.

Tip

Refer to the Explanation of the documentation for full details on each of these elements.

acoupi Application

An acoupi application consists of the full set of code that runs at the deployment stage. This includes a set of scripts made of an acoupi program with user configurations, celery files to organise queues and workers, and bash scripts to start, stop, and reboot the application processes. An acoupi application requires the acoupi package and related dependencies to be installed before a user can configure and run it. The figure below gives an overview of key stages related to the installation, configuration and runtime of an acoupi application.

Figure 3: An visual diagram highlighting the elements of an acoupi application.Three main steps are involved in setting up and running an acoupi application: (1) installation, (2) configuration, and (3) deployment.

Features and development

acoupi builds on other Python packages. The list of the most important packages and their functions is summarised below. For more information about each of them, make sure to check their respective documentation.

• PDM to manage package dependencies.
• Pydantic for data validation.
• Pytest as a testing framework.
• Pony-ORM for databse queries.
• Celery to manage the processing of tasks.
• Jinja for text templating.