Snowmobile analyzer ❄️

A model to detect whether snowmobiles are present in an acoustic dataset.

Introduction

This repository is made to run the snowmobile detector on your audio files.

Moreover, in this repository we provide guidance on setting up a pipeline for real-time analysis of audio files on Google Cloud. For more information see the README in the subfolder cloud_analysis.

Setup

Install uv, then run:

uv sync --dev

Copy the GitHub repository and get the model from Zenodo.

cd audioclip
wget "https://zenodo.org/record/7969521/files/assets.zip?download=1"
unzip "./assets.zip?download=1"
cd ..

Place the model files inside audioclip/assets/ (adjust the paths in CONFIG.yaml if needed).

Use of the repository

Below are the instructions on installing and using the snowmobile detector with both Docker and without. The output of the script is a subfolder SNOWMOBILE_RESULTS containing the .csv file of the analyzed file. Note that the folder SNOWMOBILE_RESULTS will be located in the same folder as the input file.

Use with Docker

Create the Docker image:

docker build -t snowmobile -f Dockerfile .

Run the program using the analyze.sh script which is a wrapper around the Docker command:

./analyze.sh ./example/example_audio.mp3

Note that if you want to have more control over the arguments you can use Docker:

docker run \
    --rm \
    --gpus all \
    -v ./logs:/app/logs \ # Important to write the log files
    -v "$FOLDER_TO_EXPOSE":/data \
    snowmobile \
    /data/"$FILENAME"

Note that you can change ./example/example_audio.mp3 to the path of your own file.

Use without Docker

Run the script:

uv run python src/predict.py example/example_audio.mp3

Output

The program creates a folder SNOWMOBILE_RESULTS containing a .csv file with the following columns:

start_detection	end_detection	label	confidence	hr
0	3	1	0.97691464	0.19687336119166438
3	6	1	0.9611957	0.16774687365839228

• start_detection and end_detection are in seconds
• label is always equal to 1 (i.e. snowmobile detected)
• confidence is the model confidence
• hr is the harmonic ratio value

By default the program selects detections for which confidence > 0.95 and hr > 0.1.

Update from template

To update this project with the latest changes from the template, run:

uvx --with copier-template-extensions copier update --trust

You can keep your previous answers by using:

uvx --with copier-template-extensions copier update --trust --defaults

Development

Run the prek git hooks to keep code quality:

prek install
prek run --all-files

Acknowledgment and contact

For bug reports please use the issues section.

For other inquiries please contact Benjamin Cretois or Femke Gelderblom.

Cite this work

Cretois, B., Bick, I. A., Balantic, C., Gelderblom, F., Pavon-Jordan, D., Wiel, J., ... & Reinen, T. A. (2023). Snowmobile noise alters bird vocalization patterns during winter and pre-breeding season. bioRxiv, 2023-07.