README.md

---
title: Marine Soundscape Analyzer
emoji: 🌊
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.23.3
app_file: app.py
pinned: false
license: mit
short_description: Coral reef acoustic analysis
---

# 🌊 Marine Soundscape Analyzer

A comprehensive acoustic analysis tool for **marine and coral reef hydrophone recordings**.

## Features

Upload any audio file (WAV, MP3, FLAC, OGG, AIFF) and get:

| Tab | Content |
|-----|---------|
| 📊 Waveform | Time-domain signal with amplitude envelope |
| 🔊 Spectrograms | Linear, Mel-scale, and Log-frequency spectrograms |
| 📡 Frequency Analysis + MFCC | Power Spectral Density (Welch), spectral centroid over time, MFCC heatmap |
| 🧬 Acoustic Indices | ACI, BI, NDSI, ADI, RMS — all shown as time-series bars |
| 📐 Temporal Features | Spectral bandwidth, rolloff, flatness, ZCR, onset detection, MFCC delta |
| 📋 Report | Full markdown report with all statistics and index interpretations |

## Acoustic Indices

| Index | Reference | What it measures |
|-------|-----------|-----------------|
| **ACI** — Acoustic Complexity Index | Pieretti et al. 2011 | Temporal variation in spectral amplitude; higher = more complex soundscape |
| **BI** — Bioacoustic Index | Boelman et al. 2007 | Energy in the 2–8 kHz biological band |
| **NDSI** — Normalized Difference Soundscape Index | Kasten et al. 2012 | Ratio of biotic (2–11 kHz) to anthropogenic (1–2 kHz) energy |
| **ADI** — Acoustic Diversity Index | Villanueva-Rivera et al. 2011 | Shannon diversity across frequency bands above a threshold |
| **Hf** — Spectral Entropy | Sueur et al. 2008 | Uniformity of energy across frequencies; 0 = tonal, 1 = white noise |
| **Ht** — Temporal Entropy | Sueur et al. 2008 | Uniformity of energy over time; 0 = impulsive, 1 = stationary |
| **H** — Total Acoustic Entropy | Sueur et al. 2008 | Combined soundscape heterogeneity (Hf × Ht) |

## Marine Coral Reef Context

| Frequency Band | Range | Typical Sources |
|----------------|-------|-----------------|
| Low | 20 – 1,000 Hz | Fish choruses, breaking waves, vessel traffic |
| Snapping Shrimp | 1 – 5 kHz | *Alpheid* snapping shrimp — key reef health indicator |
| High Biotic | 5 – 20 kHz | Small crustaceans, urchins, high-frequency fish sounds |

Snapping shrimp produce a characteristic broadband crackling that can be heard throughout the 1–20 kHz range. Healthy reefs typically show **high ACI, positive NDSI, and elevated energy in the snapping-shrimp band**. Degraded reefs tend to be quieter, with lower ACI and flatter spectra.

## Example Recordings

The app ships with example recordings from the project data folder:

- 🦐 Snapping Shrimp
- 🦀 Ghost Crab: Gastric Mill Stridulation
- 🐋 Humpback Whale Song
- 🐟 Red Grouper Vocalization

## Running Locally

```bash
pip install -r requirements.txt
python app.py
```

## Deploying to Hugging Face Spaces

1. Create a new **Gradio** Space on [huggingface.co/spaces](https://huggingface.co/spaces).
2. Upload `app.py` and `requirements.txt` to the Space repository.
3. (Optional) Add audio example files under `data/` in the Space repo — the app will auto-detect them.

## References

- Pieretti N., Farina A., Morri D. (2011). A new methodology to infer the singing activity of an avian community: The Acoustic Complexity Index (ACI). *Ecological Indicators*.
- Boelman N.T., et al. (2007). Multi-trophic invasion resistance in Hawaii: bioacoustics, field surveys, and airborne remote sensing. *Ecological Applications*.
- Kasten E.P., et al. (2012). The remote environmental assessment laboratory's acoustic library: An archive for studying soundscape ecology. *Ecological Informatics*.
- Villanueva-Rivera L.J., et al. (2011). A primer of acoustic analysis for landscape ecologists. *Landscape Ecology*.
- Sueur J., Pavoine S., Hamerlynck O., Duvail S. (2008). Rapid acoustic survey for biodiversity appraisal. *PLOS ONE*.