README.md

metadata

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

pip install -r requirements.txt
python app.py

Deploying to Hugging Face Spaces

1. Create a new Gradio Space on 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.