acoupi#

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: Overview of where the acoupi software package fits in the toolbox of bioacoustic research — **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 USB Microphone or an Ultramic 192K/250K.

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

CLI Command: acoupi installation

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

Step 2: Configure an acoupi program.

CLI Command: acoupi configuration

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.

CLI Command: configure acoupi default program

acoupi setup --program acoupi.programs.default

CLI Command: configure acoupi connected program

acoupi setup --program acoupi.programs.connected

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

CLI Command: acoupi deployment

acoupi deployment start

Using acoupi from the command line

To check what are the available commands for acoupi, enter acoupi --help. Also look at the CLI documentation for further info.

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

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.

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.

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.

CLI Command: Install acoupi_batdetect2 program.

pip install acoupi_batdetect2

CLI Command: 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.

CLI Command: Install acoupi_birdnet program.

pip install acoupi_birdnet

CLI Command: Setup and configure acoupi_birdnet program.

acoupi setup --program acoupi_birdnet.program

In development 🐳🐘🐝#

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.

Navigate the docs 📖#

Get to know acoupi better by exploring the following sections of the documentation.

Tutorials Step-by-step information on how to install, configure and deploy acoupi for new users.	How-To Guides Guides to learn how to customise and built key elements of acoupi.
Explanation Overview of the key elements of acoupi: what they are and how they work.	Reference Technical information refering to acoupi code.

Important

We would love to hear your feedback about the documentation. We are always looking to hearing suggestions to improve readability and user's ease of navigation. Don't hesitate to reach out if you have comments!