day/night in .data
Test skill with mono images

South Island Wren       soiwre1         -

South Island Wren       soiwre1         X

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 -> 90), never downgrade it.

Review ML-classified bird call segments by visually inspecting spectrograms. Confirm or reclassify. Can only **upgrade** certainty (e.g. 70->90), never downgrade.

## When to Use

## Step 1: Scope the review

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

Get from user: **folder path**, **filter** (e.g. `opensoundscape-kiwi-1.2`), **species+calltypes** (e.g. `GSK`, `GSK+Male`, `Don't Know`).

- 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:

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)

Show filters, species, calltypes, review status. Confirm exact labels and whether to skip certainty 100 (default: yes).

The folder structure is `<common_name>/<calltype>/` containing paired `.png` and `.wav` example files.

## Step 2: Load reference spectrograms

Read 3 representative PNG images from each calltype subfolder (pick files evenly spaced through the sorted file list). Study the visual patterns:

Reference examples live in this skill's folder: `<common_name>/<calltype>/` with paired `.png`/`.wav`. 

**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

Read 3 PNGs per calltype subfolder (evenly spaced). Key patterns:

**Note on Frequency Scaling:** Spectrogram frequency ranges may vary based on recording
equipment (8kHz/16kHz/32kHz). Focus on the **relative pattern** (spacing, thickness,
regularity of vertical bars) rather than absolute frequency position. Male calls show
bold, regularly-spaced bars at lower frequencies relative to the display; female calls
are thinner and higher relatively. 

- **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

If the samaple rate is above 16kHz, audio is downsampled to 16kHz, if sample rate is below 16kHz, it is left as is fro the spectrogram. In practice images will be 8kHz (most common) or 16kHz.

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 for the folder

## Step 3: Generate clips

Generate all clips at once using the folder mode:

Use `--species GSK` (no calltype) to get all calltypes, or `--species GSK+Male` for a specific calltype.

Use `--species GSK` for all calltypes, `--species GSK+Male` for specific.

**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.

**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

### Token Efficiency Guidelines
- **<100 segments**: Review all at once
- **100-300 segments**: Review in one batch (acceptable cost)
- **>300 segments**: Consider filtering by calltype (e.g., review Duets/Females first, 
  then Males) or by date range to manage token costs

## Step 4: Examine spectrograms

### 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)

Read each generated `.png` file using the Read tool. Compare against reference images from Step 2.

**When to Skip** (leave at 70): duration <15 samples, low SNR, fragmented/incomplete, uncertain, never guess.

For each segment, determine:
- **Confirm**: classification is correct -> upgrade certainty to 90
- **Reclassify**: wrong calltype -> modify to correct species+calltype at certainty 90
- **Skip**: too faint or uncertain -> leave as-is at current certainty (never downgrade)

Parse filenames: `<prefix>_<basename>_<START>_<END>.png` -> `<basename>.wav.data`, segment `START-END`.

### When to Skip (Leave at certainty 70)
- **Duration <15 samples** (very short segments)
- **Signal-to-noise ratio too low** (fainter than reference examples)
- **Fragmented/incomplete patterns** (file boundary artifacts)
- **Uncertain classification** (pattern doesn't clearly match reference)
- **Never guess** - skip rather than misclassify
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

### Step 5: Present batch summary
Present results in a table:

Folder: tx45/202603 march (filter: opensoundscape-kiwi-1.2, species: GSK)

1  | tx45_20260304_204504 | 132-163 | GSK+Male (70)  | Confirm (90)   | Clear male pattern
2  | tx45_20260305_040003 | 352-395 | GSK+Male (70)  | -> GSK+Duet(90)| Female visible too
3  | tx45_20260304_211504 | 442-463 | GSK+Male (70)  | Skip           | Too faint to confirm

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 any modifications. User can override individual decisions.

**Ask user to approve** before executing. User can override individual decisions.

### Step 6: Execute approved changes

## Step 6: Execute changes

Confirm correct classification (bump certainty only):

./skraak calls modify --file "<folder>/<basename>.wav.data" --reviewer <Your Name> \

# Confirm (bump certainty only)
./skraak calls modify --file "<folder>/<basename>.wav.data" --reviewer <model> \

```

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 90
```

# Reclassify
./skraak calls modify ... --species GSK+Duet --certainty 90

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 90
```

# Mark as noise
./skraak calls modify ... --species Noise --certainty 90

Bookmark an outstanding example:
```bash
./skraak calls modify --file "<folder>/<basename>.wav.data" --reviewer <Your Name> \
  --filter <filter> --segment <start>-<end> --certainty 90 --bookmark
```

# Bookmark outstanding example
./skraak calls modify ... --certainty 90 --bookmark

Add a comment to preserve information:
```bash
./skraak calls modify --file "<folder>/<basename>.wav.data" --reviewer <Your Name> \
  --filter <filter> --segment <start>-<end> --certainty 90 --comment "Clear duet with visible female component"

# Add comment (max 140 chars, ASCII)
./skraak calls modify ... --certainty 90 --comment "Clear duet with visible female component"

**Bookmark**: Use `--bookmark` to mark outstanding, clear, or beautiful examples of a call. Bookmarked segments can be easily found later for training reference or demonstration purposes.
**Comment**: Use `--comment "text"` to preserve useful information about a segment. Comments are stored in the .data file and visible when classifying calls manually. Max 140 characters, ASCII only. Examples:
- "Clear duet with visible female component"
- "Unusual timing pattern, verify with audio"
- "Good training example for male vs female distinction"

**Bookmark**: mark outstanding/clear examples for training reference. 
**Comment**: preserve useful info about a segment.

### Step 7: Verify Changes (Optional)
Check that modifications were applied correctly:
```bash
# Count segments at certainty 90
grep -r '"certainty": 90' <folder>/*.data | wc -l

## Step 7: Final summary

# View a specific modified file
cat <folder>/<filename>.wav.data | grep -A5 '"segment_start":<start>'

```
Review Complete - Folder: <path>, Filter: <filter>, Species: <species>
Segments reviewed: N | Confirmed: A (%) | Reclassified: B (%) | Skipped: C (%)

## Rules

### Step 8: Final summary

- **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
- ML models ~90% accurate; **goal is upgrading certainty on correct ones**
- Use `--size 448` if more detail needed (higher token cost)
- Always report clip count before reading images

```
Review Complete
Folder: <path>
Filter: <filter>, Species: <species>
Segments reviewed: N
  Confirmed (-> 90): A (%)
  Reclassified:      B (%)
  Skipped (left as-is): C (%)
```

## GSK(Great Spotted Kiwi)/Roroa Tips

## Classification Rules

- **Male**: most common, bold vertical stripes ~1/3 to 1/2 spectrogram height
- **Female**: higher frequency, thinner, often fainter - don't mistake faintness for absence
- **Duet**: if ANY female component visible with male, it's a Duet
- **Distant calls**: fainter but still valid - only skip if pattern unclear

- **Only upgrade certainty**: confirm (70 -> 90) or reclassify (-> 90). Never downgrade. If uncertain, skip the segment and leave it as-is.
- **Certainty 90**: use for all LLM classifications (distinguishes from ML=70, human=100)
- **Reviewer**: always the actual model being used, eg haiku-4.5, kimi-k2.5, glm-5, minimax-m2.7, 
- **Never modify** segments with certainty >= 90 (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

## Gotchas

## Notes

- Develop a rough awareness of day v night 
- Recordings will be Pacific/Auckland time, from anywhere in the South Island. 
- Clocks do drift, but rarely.

- 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 never modify them
- 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.

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)

## Calltype-Specific Tips

## Day/Night Species Reference

### GSK/Roroa Specific Guidance
- **Male**: Most common, look for bold vertical stripes at ~1/3 to 1/2 of spectrogram height
- **Female**: Higher frequency, thinner bars, often fainter - don't mistake faintness for absence
- **Duet**: Both patterns present simultaneously - if you see ANY female component with male, it's a Duet
- **Distant calls**: Fainter versions of same patterns are still valid - only skip if pattern is unclear

**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

### Reference Image Strategy
1. Read 2-3 reference images from EACH calltype folder
2. Mentally note the **key distinguishing features**:
   - Male: Bar thickness, spacing regularity, relative frequency position
   - Female: Thin bars, higher position, delicate appearance  
   - Duet: Two distinct frequency bands with overlapping patterns

**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