Satellite: Android

Use an Android phone as a BirdNET-NG satellite for portable bird audio capture.

Platform: Android — a Capacitor-based mobile app with native AudioRecord plugin, background recording, and in-app registration.

Device Requirements

• Android 8.0 (Oreo) or newer
• Working microphone
• GPS (for location-aware species filtering)
• Network connectivity (Wi-Fi or mobile data)

Getting the APK

Easiest path is to grab the latest release from your hub. After vhub-0.32.7+:

1. Log in to the web UI as any tenant member.
2. Open the Satellites page.
3. Click Get mobile app vX.Y.Z in the page header. The browser downloads the APK; transfer it to the phone via USB, cloud drive, or any sideload path that works for you.

Platform admins can also pick a specific historical version from Platform Settings → Mobile (each row has a Download button).

Building locally

If you need a custom build (signed with your own keystore, different hub URL baked in at build time, etc.):

cd packages/mobile
./build-apk.sh

The script reads .env from the repo root (auto-derives HUB_URL from BNG_APP_FQDN and HUB_API_KEY from HUB_INTERNAL_API_KEY), builds the APK inside Docker, and uploads it to the running hub as a new release. The debug keystore in the repo is persistent across builds so the same APK keeps updating without an uninstall.

Android Permissions

The app requests these permissions at startup:

If permissions are denied, the app shows an "Open Settings" button to navigate to Android's app permission screen.

Setup Flow

1. Sign In

Enter your hub URL (e.g. https://birdnet.example.com) and log in with your credentials.

If your account has MFA enabled (TOTP / passkeys), the app prompts for a 6-digit code after the password. Toggle to "Use backup code" if your authenticator is unavailable. Hub-side this calls /api/auth/login/mfa/{totp,backup}?returnToken=true (vhub-0.32.6+); pre-vapk-1.4.1 the mobile flow couldn't complete MFA at all.

After registration the app stores a satellite-scoped API key (vapk-1.4.0+) instead of the session JWT. The key is long-lived and survives password changes or session expiry, so the satellite keeps working without re-login. Existing installs auto-exchange their stored JWT for an API key on first launch after upgrade.

2. Register Satellite

Choose a name for this satellite and select the tenant it belongs to. GPS location is acquired automatically after registration -- no need to enter coordinates during registration.

3. GPS Requirement

Before recording starts, the app requires a GPS fix or manually entered coordinates. This is needed because BirdNET uses location + date to filter its species list for regionally plausible species.

If GPS is unavailable:

• A yellow "GPS Location Required" prompt appears
• Retry GPS: attempt auto-acquisition again
• Open Settings: enter latitude/longitude manually

4. Record

Once GPS is set, the app connects to the hub via MQTT (WebSocket over TLS). The app starts in a paused state -- tap the recording status bar to begin capturing 3-second audio chunks. Audio is filtered on-device with an RMS silence gate followed by a YAMNet VAD (native Capacitor plugin via org.tensorflow:tensorflow-lite); filter thresholds and per-category drop settings are received from the hub.

Recording Screen

The recording screen features a tap-to-record status bar -- the large recording rectangle is the toggle for starting and stopping capture. The app starts in a paused state by default.

Below the chunk audit, two collapsible cards:

• Chunks (N): per-chunk pipeline audit, last 16 statuses as colored dots (sent / live / silence / low-bird / category-excluded). Expand for the full list with timestamps + RMS / bird-prob values.
• Détections (N) (vapk-1.3.0+): live feed of detections from chunks this phone uploaded. REST backfill from /api/detections?satelliteId=<self>&limit=50 on mount, then live MQTT prepend via the new /detection topic. Each row shows species (common + scientific), confidence %, timestamp, and badges for rare / first-of-day / first-of-season.

Settings Page

Settings is a full page (not a popup), accessible from the recording screen.

Satellite Name

Editable field that syncs to the hub. Visible on the Satellites page in the web UI.

Location

Clear toggle between GPS and manual location modes:

::: tip Battery Savings For a stationary phone, turn off GPS auto-update and set coordinates manually. GPS polling is the largest battery drain after screen-on. :::

Keep Screen On

Toggle to prevent the phone from locking. Uses the Capacitor keep-awake plugin.

Verbose Chunk Logging

Toggle to enable detailed per-chunk log entries for diagnostics (filter decisions, RMS values, SNR).

Recording Profile

Read-only display of the hub-assigned profile, with resolved sunrise/sunset times and active recording windows. Profiles are changed from the hub (Satellites page), not in-app.

Audio Filter Settings

All filter settings are received from the hub via MQTT and applied locally. The on-device pipeline is RMS silence gate + YAMNet VAD (per-category bird-likelihood scoring via the bundled tensorflow-lite AAR). Tenant-wide defaults and per-satellite overrides for yamnet_min_bird_prob and the five drop_*_at_satellite toggles are configured in the hub.

Satellite Info

• Satellite ID -- UUID (read-only)
• Hub -- hub URL (read-only)

Unregister

Type UNREGISTER to confirm. This:

• Stops recording
• Disconnects from the hub
• Clears the saved configuration
• Does not delete the satellite record on the hub

To re-register: sign in again and register with the same name -- the device ID matching will reconnect to the existing satellite record.

Background Mode

The app uses the Capacitor background mode plugin to continue recording when minimized. A persistent notification shows "BirdNET Satellite -- Recording bird sounds..."

::: warning Battery Background recording with screen off is the most battery-efficient mode. Keep-screen-on with background mode will drain battery faster. :::

Heartbeat

The app sends a heartbeat at a configurable interval (default 30 seconds) via MQTT QoS 1. The interval is set from hub tenant settings. This keeps the satellite showing as "online" on the hub even when all audio chunks are filtered. The heartbeat reports the current state:

• recording -- actively capturing
• paused -- user pressed Pause

Telemetry

Reported every 60 seconds:

CPU temperature is not available on mobile -- shown as "--" on the hub.

Log Viewer

Collapsible panel at the bottom of the recording screen. Captures:

• Audio capture events (chunk sent, filtered)
• MQTT connection changes
• GPS updates
• Errors and warnings

Logs are in-memory only (max 200 entries). Use "Copy All" to export, "Clear" to reset.

Updating

The mobile app shows an "Update available" banner when the hub is running a newer version. To update:

1. Pull the latest code on your development machine
2. Rebuild the APK: cd packages/mobile && npx cap sync android
3. Build and install via Android Studio or adb install

The app cannot self-update — APK installation requires a manual step. The banner is dismissible and reappears on next connection if the version mismatch persists.

Troubleshooting