*.png
*.jpg

---
name: check-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 spectrogram images. Confirm correct classifications or reclassify incorrect ones. This skill can only **upgrade** certainty (e.g. 70 -> 80), never downgrade it.
## When to Use
When the user wants to review/check ML calltype classifications on bird call segments. Typical use cases:
- Check all GSK (Great Spotted Kiwi / Roroa) calltypes in a folder
- Review a specific calltype (e.g. just GSK+Male)
- Check "Don't Know" segments for any missed kiwi calls
- Review segments from a specific ML filter
## Prerequisites
- Folder with `.data` files
- Corresponding `.wav` files present (needed for clip generation)
- `./skraak` binary built and available
## Workflow
### Step 1: Scope the review
Ask the user for:
- **Folder path** containing `.data` files
- **Which filter** to check (e.g. `opensoundscape-kiwi-1.2`)
- **Which species+calltypes** to review (e.g. `GSK`, `GSK+Male`, `Don't Know`)
Run summarise to show what's available:
```bash
./skraak calls summarise --folder "<folder_path>" --brief > /tmp/summarise.json 2>&1
```
Show the user the filters, species, calltypes, and review status. Confirm:
- The exact species labels to use for modifications (e.g. `GSK+Male`, `GSK+Female`, `GSK+Duet`, `Noise`, `Don't Know`)
- Whether to skip certainty 100 segments (default: yes, these are human-reviewed)
### Step 2: Load reference spectrograms
Look for reference examples in this skill's folder. Map species to reference folder:
- GSK / Great Spotted Kiwi -> `Roroa/`
- (Future species get their own folders)
The folder structure is `<common_name>/<calltype>/` containing paired `.png` and `.wav` example files.
Read 3 representative PNG images from each calltype subfolder (pick files evenly spaced through the sorted file list). Study the visual patterns:
**GSK/Roroa calltypes:**
- **Male Solo**: bold, regularly spaced vertical bars at lower frequency, strong signal
- **Female Solo**: thinner, higher-frequency bars, often fainter/more delicate
- **Duet**: overlapping male + female patterns visible simultaneously, two distinct frequency bands
**Noise/False positive**: no clear repeated bar pattern, random speckle or broadband noise
### Step 3: Generate clips for the folder
Generate all clips at once using the folder mode:
```bash
./skraak calls clip --folder "<folder_path>" --prefix <prefix> --output /tmp/<prefix>/ \
  --filter <filter> --species <species> --size 224 --color
```
Use `--species GSK` (no calltype) to get all calltypes, or `--species GSK+Male` for a specific calltype.
**Before reading any images**, report the number of spectrograms generated and ask the user to confirm they are OK with the token cost. Each 224px PNG is one image token. Give the user the option to proceed, reduce scope (e.g. filter to a specific calltype), or abort.
### Step 4: Examine spectrograms
Read each generated `.png` file using the Read tool. Compare against reference images from Step 2.
For each segment, determine:
- **Confirm**: classification is correct -> upgrade certainty to 80
- **Reclassify**: wrong calltype -> modify to correct species+calltype at certainty 80
- **Skip**: too faint or uncertain -> leave as-is at current certainty (never downgrade)
Parse segment start-end times from the clip filename: `<prefix>_<basename>_<START>_<END>.png`
Map back to the source .data file using the basename (e.g. `check_tx45_20260304_203005_310_345.png` -> `tx45_20260304_203005.wav.data`, segment `310-345`).
### Step 5: Present batch summary
Present results in a table:
```
Folder: tx45/202603 march (filter: opensoundscape-kiwi-1.2, species: GSK)
#  | File                  | Segment | Current Label   | Action         | Notes
---|----------------------|---------|----------------|----------------|------
1  | tx45_20260304_204504 | 132-163 | GSK+Male (70)  | Confirm (80)   | Clear male pattern
2  | tx45_20260305_040003 | 352-395 | GSK+Male (70)  | -> GSK+Duet(80)| Female visible too
3  | tx45_20260304_211504 | 442-463 | GSK+Male (70)  | Skip           | Too faint to confirm
```
**Ask user to approve** before executing any modifications. User can override individual decisions.
### Step 6: Execute approved changes
Confirm correct classification (bump certainty only):
```bash
./skraak calls modify --file "<folder>/<basename>.wav.data" --reviewer <Your Name> \
  --filter <filter> --segment <start>-<end> --certainty 80
```
Reclassify to different calltype:
```bash
./skraak calls modify --file "<folder>/<basename>.wav.data" --reviewer <Your Name> \
  --filter <filter> --segment <start>-<end> --species GSK+Duet --certainty 80
```
Mark as noise (only if clearly not a bird call):
```bash
./skraak calls modify --file "<folder>/<basename>.wav.data" --reviewer <Your Name> \
  --filter <filter> --segment <start>-<end> --species Noise --certainty 80
```
### Step 7: Final summary
```
Review Complete
Folder: <path>
Filter: <filter>, Species: <species>
Segments reviewed: N
  Confirmed (-> 80): A (%)
  Reclassified:      B (%)
  Skipped (left as-is): C (%)
```
## Classification Rules
- **Only upgrade certainty**: confirm (70 -> 80) or reclassify (-> 80). Never downgrade. If uncertain, skip the segment and leave it as-is.
- **Certainty 80**: use for all Claude classifications (distinguishes from ML=70, human=100)
- **Reviewer**: always "Claude"
- **Never modify** segments with certainty >= 80 (already reviewed by LLM or human)
- **Always ask** the user for labels if you see something identifiable that isn't in the expected species list
- Use `calls summarise --brief` to check existing labels in the folder
## Notes
- Image size defaults to 224px with `--color`. Use `--size 448` if more detail needed (higher token cost)
- Always report clip count and ask user before reading images (token cost awareness)
- Distant/faint calls are common - skip rather than guess
- The `.data.bak` files serve as backups but always get user approval before modifying
- The ML models can be ~97% accurate, so most classifications will often be correct. The goal is to increase certainty on correct ones, not to second-guess the model.