Skip to content
beaktechPublic

About

A kiosk display for BirdNET-Go. Shows live bird detections, species spotlights, rare visitors, daily top birds, and local weather on a rotating full-screen hero panel.

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

BeakWatch

test MIT licence

A kiosk display for BirdNET-Go. Shows live bird detections, species spotlights, rare visitors, daily top birds, and local weather on a rotating full-screen hero panel. Designed for a wall-mounted screen/iPad to show your live detections and statistics in a beautiful way, without any interaction necessary.

This may just be so you can have a nice display at home for your family. But works particularly well in public places. Maybe you want to promote awareness of birds to those in the area and you could even place a screen in your front window to show the neighbours the wildlife they are living with!

Display support: BeakWatch is a fixed-layout kiosk for screens at least 900px wide and iPads in landscape. Smaller and portrait displays get a clear rotation notice instead of a broken layout; the dashboard itself is intentionally not a mobile app.

Screenshots

Last identified Species profile Activity patterns Most popular species Rare visitors

Features

  • Live detections sidebar — newest detection per species, deduplicated.
  • Rotating hero — last identified, species spotlight, top 10 over 30 days, 6 rarest visitors, today's species hourly chart.
  • On-demand bird images — fetched from Wikimedia Commons the first time a species appears, then cached on disk. The repo ships zero images.
  • Optional local weather — current conditions from Open-Meteo, enabled only when you configure coordinates.
  • Multi-server support — point at one or several BirdNET-Go instances and switch between them from the UI.
  • Unattended recovery — honest connecting/offline/setup states, automatic retries, stale-data fallback, and upstream timeouts.

Prerequisites

  • Node.js 20+ (uses global fetch).
  • A reachable BirdNET-Go instance with the v2 HTTP API enabled.

Quick start

1. Clone and install

git clone https://github.com/beaktech/beakwatch
cd beakwatch
npm install

2. Create your config

Copy the example file to server/.env (note the server/ subfolder — that's where the app reads it from):

cp .env.example server/.env

Open server/.env in an editor and set at least BIRDNET_GO_URL to your BirdNET-Go instance, including the http:// prefix and port:

BIRDNET_GO_URL=http://192.168.1.10:8080

Everything else is optional — see Configuration below. To show weather, set both LAT and LON to the display location. (Running more than one BirdNET-Go? Use BIRDNET_GO_URLS instead.)

3. Build and run

npm run build   # compile the frontend into dist/
npm start       # serve the app + API

Then open http://localhost:2325 in a browser.

Just want to develop/tweak the UI? Skip the build and run npm run dev instead — see Development.

Configuration

All config lives in server/.env (see .env.example).

Variable Default Description
BIRDNET_GO_URL (unset) URL of your BirdNET-Go instance, e.g. http://192.168.1.10:8080. Required.
BIRDNET_GO_URLS (unset) Comma-separated URLs for multiple instances. Overrides BIRDNET_GO_URL.
BIRDNET_GO_NAMES hostname Comma-separated display names matching BIRDNET_GO_URLS (e.g. Garden,Office).
LAT (unset) Latitude for the weather widget. Set together with LON; weather is hidden when omitted.
LON (unset) Longitude for the weather widget. Set together with LAT; weather is hidden when omitted.
OPEN_METEO_API_KEY (unset) Commercial Open-Meteo key; automatically selects their customer endpoint.
OPEN_METEO_API_URL automatic Complete forecast endpoint override, useful for a self-hosted Open-Meteo API.
PORT 2325 Port the kiosk server listens on. Dev mode proxies to this too.
UPSTREAM_TIMEOUT_MS 10000 Timeout for BirdNET-Go and weather requests (minimum 1000ms).
BEAKWATCH_CONTACT repo URL Contact URL/email sent in BeakWatch's Wikimedia User-Agent.
BEAKWATCH_CACHE_DIR cache/birds Bird-image cache directory; use an absolute persistent path in containers.

Weather usage

Weather is opt-in so a fresh installation never displays London's weather by mistake. The public Open-Meteo API is for non-commercial use and its CC BY 4.0 licence requires a nearby link; BeakWatch keeps that attribution visible in the footer. For commercial displays, configure OPEN_METEO_API_KEY, point OPEN_METEO_API_URL at a suitably licensed/self-hosted endpoint, or leave LAT and LON unset. See Open-Meteo's licence and current terms.

Architecture

Browser  ──/api/*─▶  Express (server/index.js)  ──▶  BirdNET-Go (REST)
                          │
                          ├──/birds/*─▶  cache/birds/  (disk)
                          │                    │ miss
                          │                    ▼
                          │        Wikipedia API / Wikimedia Commons
                          │
                          └──static────▶  dist/  (built React app)
  • Express (server/): proxies BirdNET-Go, serves the built frontend, and runs the on-demand image cache.
  • React + Vite (src/): the kiosk UI. Tailwind for styling, Vitest for tests.
  • Image cache (server/birdImages.js): on a request for /birds/<slug>.jpg?name=<commonName>&w=<width>, serves the closest standard Wikimedia size from cache/birds/ if present; otherwise it looks up the species, accepts only Wikimedia Commons media, validates and atomically caches the response. Concurrent requests for the same image are deduped; outbound traffic is capped at 2 concurrent requests with backoff on HTTP 429.

The cache/ directory is gitignored and grows organically as new species are detected (~50–200 KB per species).

Development

npm install
cp .env.example server/.env
npm run dev    # vite (5173, or next free port) + nodemon-watched express (2325)

Vite proxies /api and /birds/*.jpg to Express, so you don't need a separate build. Open the URL Vite prints on startup (usually http://localhost:5173).

Scripts

Command What it does
npm run dev Vite + Express in watch mode
npm run build Build the React app to dist/
npm start Serve dist/ and the API from Express
npm run check Run lint, tests, and a production build
npm test Run the Vitest suite once
npm run test:watch Vitest in watch mode
npm run test:coverage Run the suite with a coverage report
npm run lint Run ESLint

Trust model

BeakWatch is designed for a trusted LAN and has no authentication. Specifically:

  • The /api/server POST route lets any client on the network switch the active BirdNET-Go instance.
  • The /birds/*.jpg route lets any client trigger Wikimedia downloads and disk writes to cache/. Names must match their safe slug and only Commons-hosted media are accepted, but a client could still fill the disk with many valid requests.

If you expose BeakWatch beyond a network you trust, put it behind an authenticated HTTPS reverse proxy and restrict the routes. See SECURITY.md.

Operations

  • GET /api/health is a lightweight liveness endpoint for service managers and container probes. Its response also says whether BirdNET-Go and weather are configured.
  • Keep cache/ on persistent storage if you do not want images re-downloaded after deployments.
  • Run npm run build after upgrades, then restart the Node process. Use a service manager appropriate to your OS so BeakWatch starts after reboot.
  • The UI retries failed data sources automatically. A persistent SETUP NEEDED or OFFLINE state is actionable and no longer masquerades as an empty bird feed.

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md for setup, reporting, and pull-request guidance. Before opening a PR, run npm run check.

Attribution

Bird summaries come from Wikipedia and include a source link; photos are accepted only from Wikimedia Commons. Hero photos show a linked photographer/licence credit, while thumbnails have a visible information badge and linked source. Keep this attribution available — individual Commons files have their own reuse requirements.

Weather data from Open-Meteo under its current licence and terms, with attribution beside the displayed conditions.

License

MIT — see LICENSE.

About

A kiosk display for BirdNET-Go. Shows live bird detections, species spotlights, rare visitors, daily top birds, and local weather on a rotating full-screen hero panel.

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages