fork of https://github.com/samratjha96/BirdRadio to self-host it
Listen to birds around the world
https://birdradio.s1gm4.eu/
- CSS 43.7%
- JavaScript 38.9%
- HTML 17.1%
- Dockerfile 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| bin | ||
| container | ||
| functions/api | ||
| public | ||
| .dockerignore | ||
| .gitignore | ||
| compose.yml | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
Bird Radio
A relaxing web app that plays continuous bird songs from around the world, powered by the Xeno-canto bird sound database.
Features
- Continuous playback of high-quality bird recordings
- Region selector: Worldwide, Europe, North America, South America, Africa, Asia, Australia
- Retro-style volume knob with drag/scroll control
- Sonogram visualization for each bird
- Playback controls with history navigation
- Local caching to reduce API calls
- Vintage radio aesthetic
Tech Stack
- Frontend: Vanilla JavaScript, HTML, CSS
- Hosting: Cloudflare Pages
- API Proxy: Cloudflare Pages Functions (Workers)
- Data: Xeno-canto API v3
Project Structure
wildlife-sounds/
├── index.html # Main HTML
├── app.js # Application logic
├── styles.css # Styling
├── functions/
│ └── api/
│ └── recordings.js # Cloudflare Pages Function (API proxy)
└── worker.js # Standalone Worker (alternative deployment)
How It Works
The app uses a server-side proxy to keep the Xeno-canto API key secure:
Browser → /api/recordings → Cloudflare Pages Function → Xeno-canto API
↑
(injects secret API key)
The API key is stored as a Cloudflare secret and never exposed to the browser.
Deployment
Prerequisites
- Node.js installed
- A Cloudflare account
- A Xeno-canto API key
First-time Setup
-
Install Wrangler CLI (Cloudflare's deployment tool):
npm install -g wrangler -
Login to Cloudflare:
npx wrangler login -
Create the Pages project:
npx wrangler pages project create bird-radio --production-branch main -
Deploy the site:
npx wrangler pages deploy . --project-name bird-radio --branch main -
Add your API key as a secret:
npx wrangler pages secret put XENO_CANTO_API_KEY --project-name bird-radio # Paste your Xeno-canto API key when prompted
Subsequent Deployments
After the initial setup, just run:
npx wrangler pages deploy . --project-name bird-radio --branch main
Useful Commands
| Command | Description |
|---|---|
npx wrangler pages deploy . --project-name bird-radio --branch main |
Deploy to production |
npx wrangler pages secret list --project-name bird-radio |
List configured secrets |
npx wrangler pages secret put XENO_CANTO_API_KEY --project-name bird-radio |
Update API key |
npx wrangler pages deployment list --project-name bird-radio |
List all deployments |
Local Development
For local development, you can use Wrangler's dev server:
npx wrangler pages dev .
This will start a local server with the Pages Function working. You'll need a .dev.vars file for local secrets:
# .dev.vars (DO NOT COMMIT THIS FILE)
XENO_CANTO_API_KEY=your_api_key_here
Environment Variables
| Variable | Description | Where to Set |
|---|---|---|
XENO_CANTO_API_KEY |
Your Xeno-canto API key | Cloudflare Pages Secrets |
License
MIT
Credits
- Bird recordings from Xeno-canto - sharing bird sounds from around the world
- All recordings are © their respective recordists (credited in the app)