---
name: oceansong
description: Query the Ocean Song cetacean monitoring platform — real-time whale detection across 7 live hydrophone streams. Check system status, list detections, download audio clips.
context: fork
---

# Ocean Song API — Cetacean Acoustic Monitoring

**API Base**: https://api.oceansong.live
**Dashboard**: https://oceansong.live
**OpenAPI**: https://api.oceansong.live/openapi.json
**No authentication required.**

## Quick Start

Check system status:
```bash
curl -s https://api.oceansong.live/status | python3 -m json.tool
```

List recent detections:
```bash
curl -s "https://api.oceansong.live/events?limit=5"
```

## Endpoints

### GET /status
All 7 streams with connection state, ML detection scores, last detection time, detection counts (1h/24h/7d), top species.

### GET /events
Detection events, newest first.
- `?species=humpback` — filter by species (humpback, orca, blue_whale, sperm_whale)
- `?stream=mbari-mars` — filter by stream
- `?since=2026-04-01T00:00:00Z` — events after timestamp
- `?before=...` — events before timestamp (pagination)
- `?limit=10` — max results (default 10, max 1000)

### GET /clips/{event_id}
Download original FLAC audio clip.

### GET /clips/{event_id}/mp3
Stream MP3 for browser playback.

### GET /clips/{event_id}/denoised
Download denoised FLAC (Earth Species Project biodenoising).

### GET /clips/{event_id}/denoised/mp3
Stream denoised MP3.

### GET /spectrograms/{event_id}
Download spectrogram PNG.

### WSS wss://api.oceansong.live/ws
Real-time WebSocket. Sends:
- `{"type":"status","data":{...}}` every 5s
- `{"type":"new_events","data":[...]}` on new detections

## Streams
| ID | Location | Active Models |
|----|----------|--------------|
| orcasound-pt | Port Townsend, WA | humpback, orca |
| orcasound-sunset | Sunset Bay, WA | humpback, orca |
| orcasound-nsjc | North San Juan Channel, WA | humpback, orca |
| orcasound-mast | MaST Center, WA | humpback, orca |
| orcasound-andrews | Andrews Bay, WA | humpback, orca |
| mbari-mars | Monterey Bay, CA (900m) | humpback, blue_whale, sperm_whale |
| simres | Saturna Island, BC | humpback, orca |

## Examples
```bash
# Recent humpback detections at MBARI
curl -s "https://api.oceansong.live/events?species=humpback&stream=mbari-mars&limit=5"

# Download a denoised clip
curl -sL "https://api.oceansong.live/clips/722/denoised/mp3" -o orca.mp3

# Check which streams are online
curl -s https://api.oceansong.live/status | python3 -c "
import json,sys
for s in json.load(sys.stdin)['streams']:
    print(f'{s[\"stream_id\"]:20s} {\"ONLINE\" if s[\"connected\"] else \"OFFLINE\"}')"
```