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%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-20 01:11:55 +01:00
bin Remove references to pages.dev, for self-hosting 2026-11-20 00:40:56 +01:00
container Remove references to pages.dev, for self-hosting 2026-11-20 00:40:56 +01:00
functions/api Remove references to pages.dev, for self-hosting 2026-11-20 00:40:56 +01:00
public Remove google font, and add recordist name 2026-11-20 01:11:55 +01:00
.dockerignore Remove references to pages.dev, for self-hosting 2026-11-20 00:40:56 +01:00
.gitignore Remove references to pages.dev, for self-hosting 2026-11-20 00:40:56 +01:00
compose.yml Remove references to pages.dev, for self-hosting 2026-11-20 00:40:56 +01:00
package-lock.json Remove references to pages.dev, for self-hosting 2026-11-20 00:40:56 +01:00
package.json Remove references to pages.dev, for self-hosting 2026-11-20 00:40:56 +01:00
README.md Initializing (but it's already done) 2025-12-18 17:31:20 -05:00

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

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)