README.md

---
license: cc-by-nc-4.0
datasets:
- rfcx/frugalai
language:
- en
metrics:
- accuracy
pipeline_tag: audio-classification
tags:
- acoustics
- lgbm
- frugality
- signal-processing
- climate
- chainsaw
---
# 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:

```bash
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:

```python
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](https://creativecommons.org/licenses/by-nc/4.0/).  
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](https://huggingface.co/datasets/rfcx/frugalai) 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.