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.
- 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.
- Node.js 20+ (uses global
fetch). - A reachable BirdNET-Go instance with the v2 HTTP API enabled.
1. Clone and install
git clone https://github.com/beaktech/beakwatch
cd beakwatch
npm install2. 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/.envOpen 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:8080Everything 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 + APIThen open http://localhost:2325 in a browser.
Just want to develop/tweak the UI? Skip the build and run
npm run devinstead — see Development.
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 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.
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 fromcache/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).
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).
| 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 |
BeakWatch is designed for a trusted LAN and has no authentication. Specifically:
- The
/api/serverPOST route lets any client on the network switch the active BirdNET-Go instance. - The
/birds/*.jpgroute lets any client trigger Wikimedia downloads and disk writes tocache/. 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.
GET /api/healthis 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 buildafter 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 NEEDEDorOFFLINEstate is actionable and no longer masquerades as an empty bird feed.
Issues and PRs are welcome. See CONTRIBUTING.md for setup, reporting, and pull-request guidance. Before opening a PR, run npm run check.
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.
MIT — see LICENSE.




