|
|
--- |
|
|
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 |
|
|
|
|
|
To use the model, clone the repository and install the dependencies: |
|
|
|
|
|
```bash |
|
|
git clone https://huggingface.co/tlmk22/QuefrencyGuardian |
|
|
cd QuefrencyGuardian |
|
|
pip install -r requirements.txt |
|
|
``` |
|
|
|
|
|
## 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 along the whole 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 |
|
|
|
|
|
### Load the Model and Parameters |
|
|
|
|
|
```python |
|
|
import json |
|
|
from fast_model import FastModel |
|
|
|
|
|
# Load parameters |
|
|
with open("model/features.json", "r") as f: |
|
|
features = json.load(f) |
|
|
|
|
|
with open("model/lgbm_params.json", "r") as f: |
|
|
lgbm_params = json.load(f) |
|
|
|
|
|
# Initialize the model |
|
|
model = FastModel( |
|
|
feature_params=features, |
|
|
lgbm_params=lgbm_params, |
|
|
model_file="model/model.txt", # Path to the serialized model file |
|
|
device="cuda", |
|
|
) |
|
|
|
|
|
# Predict on a Dataset |
|
|
from datasets import load_dataset |
|
|
dataset = load_dataset("rfcx/frugalai") |
|
|
predictions = model.predict(dataset["test"]) |
|
|
print(predictions) |
|
|
``` |
|
|
|
|
|
### Performance |
|
|
|
|
|
- **Accuracy**: 95% on the test set with a 4.5% FPR at the default threshold. |
|
|
- **Low-Energy Mode**: Using only 1 second of audio inference reduces energy consumption by 50%, at the cost of ~1% accuracy. |
|
|
- **Environmental Impact**: Inference energy consumption is **0.21 Wh**, tracked using CodeCarbon. |
|
|
|
|
|
### 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 machinery similar to chainsaws is present. |
|
|
|
|
|
--- |
|
|
|
|
|
This README serves as the primary documentation for Hugging Face and provides an overview of the model's purpose, data requirements, and usage. |
