Update README.md

README.md

@@ -1,14 +1,81 @@
 ---
-title: Sound2Spectrogram
-emoji: 🏃
-colorFrom: indigo
-colorTo: purple
+title: Marine Soundscape Analyzer
+emoji: 🌊
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.22.0
-python_version: '3.12'
+sdk_version: 5.23.3
 app_file: app.py
 pinned: false
 license: mit
+short_description: Coral reef acoustic analysis
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🌊 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*.