Bird song journal scene (BirdWeather)

[mariusandra]

Summary

A fork of #262 that sources its birds from BirdWeather instead of iNaturalist: a sibling sample scene under repo/scenes/samples/Bird song journal, so the two can ship side by side. #262 draws birds somebody photographed nearby; this one draws birds that BirdWeather's listening stations actually heard.

Stacked on bird-field-journal-scene with main merged in, so the diff below also carries #262's commits. Once #262 merges this reduces to the new scene alone. The frameosVersion export stamping #262 added has since landed on main independently, so that conflict is resolved in main's favour.

The BirdWeather side

Their public API is GraphQL (POST /graphql, no auth for reads), so the app sends one query per poll:

• topSpecies — the species roster with detection counts over the window. Species carries imageUrl plus imageCredit/imageLicense, which is what the plate is drawn from and what the stored attribution records.
• an aliased detections — the newest local detection per species, for the "last 19:40 at PUC-23115" half of the caption, plus the totals shown while the collection is still filling.

Species.latestDetections looks like the obvious source for that second part and is not used: it is global, so a Belgian bounding box gets told about a station in the UK. Verified against the live API.

Either a latitude/longitude/radius box or explicit station IDs select what to listen to. Stations win when both are set, because BirdWeather intersects them. Species heard fewer than minDetections times in the window are skipped — BirdNET guesses at the edge of its confidence produce one-off species that aren't worth a plate.

The plate style now asks for the bird mid-song with a small hand-drawn sonogram in the margin, which is what the preview shows.

Test plan

• nim c -r src/frameos/tests/test_bird_song_journal_scene.nim — passes. Mock BirdWeather serves two well-heard species plus one below the detection floor and one with no reference photo; asserts only the usable two are logged, one plate drawn + verified per render, HTML credits stored as plain attribution, pollMinutes keeping later renders off the network, the collection cycling, and a configured station ID replacing the bounding box in the query.
• Offline render with empty state (the gallery-card case) draws the paper placeholder with no network calls and no errors.
• backend: pytest app/api/tests/test_repositories.py — 19 passed, with the new template asserted in the samples repository.
• The preview image is a real 480x800 interpreter render of the scene, its Great Tit plate generated from BirdWeather's licensed reference photo and passed through the pipeline's own verification step.

Notes

• Visual snapshots are left to CI, which regenerates and commits them for same-repo PRs.
• test_repo_scenes_esp32.nim does not compile on main right now (availableRenderBytesOverride undeclared), so the new scene could not be checked through it. Pre-existing and untouched here.
• Generating the preview surfaced something worth knowing: the Responses API image_generation tool returns HTTP 520 for the local OpenAI key across models, while plain Responses calls and /v1/images/edits both work. The shipped app still uses the Responses tool exactly as Bird field journal scene #262 does; the preview was generated through the Images API instead. Might be worth checking whether that's account-specific before either scene is relied on.

🤖 Generated with Claude Code