Quefrency Guardian: Chainsaw Noise Detector

An efficient model to detect chainsaw activity in forest soundscapes using spectral and cepstral audio features. The model is designed for environmental conservation and is based on a LightGBM classifier, capable of low-energy inference on both CPU and GPU devices. This repository provides the complete code and configuration for feature extraction, model implementation, and deployment.

Installation

You can install and use the model in two different ways:

Option 1: Clone the repository

To download the entire repository containing the code, model, and associated files, follow these steps:

git clone https://huggingface.co/tlmk22/QuefrencyGuardian
cd QuefrencyGuardian
pip install -r requirements.txt

Once installed, you can directly import the files into your existing project and use the model.

Option 2: Dynamically load from the Hub

If you only want to download the required files to use the model (without cloning the full repository), you can use the hf_hub_download function provided by Hugging Face. This method downloads only what is necessary directly from the Hub.

Here's an example:

import os
import sys

from huggingface_hub import hf_hub_download
import importlib.util

# Specify the repository
repo_id = "tlmk22/QuefrencyGuardian"

# Download the Python file containing the model class and add it to your path
model_path = hf_hub_download(repo_id=repo_id, filename="model.py")
model_dir = os.path.dirname(model_path)  
if model_dir not in sys.path:
    sys.path.append(model_dir)

# Dynamically load the class from the downloaded file
spec = importlib.util.spec_from_file_location("model", model_path)
model_module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(model_module)

# Import the FastModelHuggingFace class
FastModelHuggingFace = model_module.FastModelHuggingFace

# Load the pre-trained model
fast_model = FastModelHuggingFace.from_pretrained(repo_id)

# Perform predictions
result = fast_model.predict("path/to/audio.wav", device="cpu")
map_labels = {0: "chainsaw", 1: "environment"}
print(f"Prediction Result: {map_labels[result[0]]}")

Depending on your needs, you can either clone the repository for a full installation or use Hugging Face's dynamic download functionalities for lightweight and direct usage.

Model Overview

Features

The model uses:

Spectrogram Features
Cepstral Features: Calculated as the FFT of the log spectrogram between [f_min-f_max] in a filtered quefrency range [fc_min-fc_max].
Time Averaging: Both feature sets are averaged across the entire audio clip for robustness in noisy settings (Welch methodology).

LightGBM Model

The model is a binary classifier (chainsaw vs environment) trained on the rfcx/frugalai dataset.
Key model parameters are included in model/lgbm_params.json.

Usage

Two example scripts demonstrating how to use the repository or the model downloaded from Hugging Face are available in the examples directory.

Performance

Accuracy: Achieved 95% on the test set with a 4.5% FPR at the default threshold during the challenge.
Environmental Impact: Inference energy consumption was measured at 0.21 Wh, tracked using CodeCarbon. This metric is dependent on the challenge's infrastructure, as the code was executed within a Docker container provided by the platform.

License

This project is licensed under the Creative Commons Attribution Non-Commercial 4.0 International.
You are free to share and adapt the work for non-commercial purposes, provided attribution is given.

Dataset

The model was trained and evaluated on the Rainforest Connection (RFCx) Frugal AI dataset.

Labels:

0: Chainsaw
1: Environment

Limitations

Audio Length: The classifier is designed for 1 to 3 seconds of audio sampled at either 12 kHz or 24 kHz.
Environmental Noise: The model might misclassify if recordings are noisy or if machinery similar to chainsaws is present.

tlmk22
/

QuefrencyGuardian