---
name: call-classification
description: Check ML-classified bird call spectrograms by visual inspection, confirming or correcting calltype labels in .data files
---
# Check Call Classification
Review ML-classified bird call segments by visually inspecting spectrograms. Confirm or reclassify. Can only **upgrade** certainty (e.g. 70->90), never downgrade.
## Step 1: Scope the review
Get from user: **folder path**, **filter** (e.g. `opensoundscape-kiwi-1.2`), **species+calltypes** (e.g. `GSK`, `GSK+Male`, `Don't Know`).
```bash
./skraak calls summarise --folder "<folder_path>" --brief > /tmp/summarise.json 2>&1
```
Show filters, species, calltypes, review status. Confirm exact labels and whether to skip certainty 100 (default: yes).
If the target species is strictly diurnal or nocturnal (see Day/Night Species Reference below), ask which site: **Takaka**, **Milford Sound**, **Pomona Island**, or **Indian Island**. Use `--night` for nocturnal species, `--day` for diurnal. Otherwise skip day/night filtering.
## Step 2: Load reference spectrograms
Reference examples live in this skill's folder: `<common_name>/<calltype>/` with paired `.png`/`.wav`.
Read 3 PNGs per calltype subfolder (evenly spaced). Key patterns:
- **Male Solo**: bold, regularly spaced vertical bars, lower frequency, strong signal
- **Female Solo**: thinner, higher-frequency bars, fainter/more delicate
- **Duet**: overlapping male+female, two distinct frequency bands
- **Noise**: no clear repeated bar pattern, random speckle or broadband
Frequency ranges vary by equipment (8/16/32kHz). Focus on **relative pattern** not absolute position. Audio is downsampled to 16kHz if above; images will be 8kHz (most common) or 16kHz.
## Step 3: Generate clips
```bash
./skraak calls clip --folder "<folder_path>" --prefix <prefix> --output /tmp/<subfolder>/ \
--filter <filter> --species <species> --size 448 --color [--night|--day --lat <float> --lng <float> [--timezone Pacific/Auckland]] #timezone required for DOC AR4 recorders
```
Use `--species Kiwi` for all calltypes, `--species Kiwi+Male` for specific.
**Before reading images**, report count and ask user to confirm token cost. Batching:
- **<100**: review all at once
- **100-300**: one batch (acceptable)
- **>300**: filter by calltype or date range
Fallback Locations:
| Takaka | -40.85 | 172.81 |
| Milford Sound | -44.67 | 167.93 |
| Pomona Island (Lake Manapouri) | -45.55 | 167.47 |
| Indian Island (Dusky Sound) | -45.75 | 166.55 |
## Step 4: Examine spectrograms
Read each `.png` with Read tool. Compare against references. For each segment:
- **Confirm**: definately correct -> certainty 90
- **Confirm**: probably correct -> certainty 80
- **Reclassify**: wrong calltype -> correct species+calltype at 90
- **Skip**: too faint/uncertain -> leave as-is (never downgrade)
**When to Skip** (leave at 70): duration <15 samples, low SNR, fragmented/incomplete, uncertain, never guess.
Parse filenames: `<prefix>_<basename>_<START>_<END>.png` -> `<basename>.wav.data`, segment `START-END`.
## Step 5: Present batch summary
```
# | File | Segment | Current Label | Action | Notes
---|----------------------|---------|----------------|----------------|------
1 | tx45_20260304_204504 | 132-163 | GSK+Male (70) | Confirm (90) | Clear male
2 | tx45_20260305_040003 | 352-395 | GSK+Male (70) | -> GSK+Duet(90)| Female visible
3 | tx45_20260304_211504 | 442-463 | GSK+Male (70) | Skip | Too faint
```
**Ask user to approve** before executing. User can override individual decisions.
## Step 6: Execute changes
```bash
# Confirm (bump certainty only)
./skraak calls modify --file "<folder>/<basename>.wav.data" --reviewer <model> \
--filter <filter> --segment <start>-<end> --certainty 90
# Reclassify
./skraak calls modify ... --species GSK+Duet --certainty 90
# Bookmark outstanding example
./skraak calls modify ... --certainty 90 --bookmark
# Add comment (max 140 chars, ASCII)
./skraak calls modify ... --certainty 90 --comment "Clear duet with visible female component"
```
**Bookmark**: mark outstanding/clear examples for training reference.
**Comment**: preserve useful info about a segment.
## Step 7: Final summary
```
Review Complete - Folder: <path>, Filter: <filter>, Species: <species>
Segments reviewed: N | Confirmed: A (%) | Reclassified: B (%) | Skipped: C (%)
```
## Rules
- **REVIEW EVERY PNG FILE**
- **Only upgrade certainty**: confirm (70->80 or 90) or reclassify (->80 or 90). Never downgrade. If uncertain, skip.
- **Certainty 80 or 90** for all LLM classifications (ML=70, human=100)
- **Reviewer**: actual model name (e.g. kimi-k2.5, glm-5, minimax-m2.7, haiku-4.5 )
- **Never modify** segments with certainty >= 90
- **Ask user** if you see identifiable species not in expected list
- `.data.bak` files are backups, never modify them
- **goal is upgrading certainty on correct ones**
- **REVIEW EVERY PNG FILE**
## Gotchas
- Use `--size 448` if more detail needed (higher token cost)
- Recordings will likely be timezone Pacific/Auckland.
- Clocks do drift, but rarely.
All of theese are Kiwi, usually only 1 species will be present:
- Fiordland Tokoeka (SI Brown Kiwi)
- Haast Tokoeka (SI Brown Kiwi)
- Kiwi-nui (NI Brown Kiwi)
- Kiwi pukupuku (Little Spotted Kiwi)
- Roroa (Great Spotted Kiwi)
- Rowi (Okarito Brown Kiwi)
## Day/Night Species Reference
**Night** (nocturnal callers): Fiordland Tokoeka, Haast Tokoeka, Kaka, Kea, Kiwi pukupuku, Kiwi-nui, Morepork, Roroa, Rowi, Bittern, Spotless Crake, Weka, Korero Gecko, Weta, Long-tailed Cuckoo
**Day** (diurnal): Bellbird, Blackbird, Chaffinch, Dunnock, Fantail, Fernbird, Grey Warbler, Kaka, Kakariki, Kakaruai, Kea, Kereru, Long-tailed Cuckoo, Pied Oystercatcher, Pipipi, Redpoll, Rifleman, Rock Wren, Shining Cuckoo, Silvereye, Starling, Thrush, Tieke, Tomtit, Tui, Variable Oystercatcher, Whio, Yellowhammer