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

1. Install Wrangler CLI (Cloudflare's deployment tool):

   npm install -g wrangler

2. Login to Cloudflare:

   npx wrangler login

3. Create the Pages project:

   npx wrangler pages project create bird-radio --production-branch main

4. Deploy the site:

   npx wrangler pages deploy . --project-name bird-radio --branch main

5. 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)