Radio 🎵

A live streaming radio application that plays music from Google Drive with real-time features including synchronized playback, chat, and listener tracking.

Features

• Synchronized Streaming: All listeners hear the same music at the same time
• Real-time Updates: Live "now playing" info, listener count, and chat
• Google Drive Integration: Stream music directly from your Google Drive
• Admin Panel: Manage playlists, skip songs, and view statistics
• Play History: Track what's been played
• Lightweight: HTML + HTMX + Tailwind frontend

Tech Stack

• Runtime: Bun
• Server: Hono
• Database: Convex (reactive/real-time)
• Frontend: HTML, HTMX, Tailwind CSS
• Storage: Google Drive API

Quick Start

Prerequisites

• Bun installed (see bun.sh)
• Google Cloud project with Drive API enabled
• OAuth 2.0 credentials from Google Cloud Console

Installation

1. Clone and install dependencies:

   cd radio
   bun install

2. Set up Google Drive:

   See docs/GOOGLE_DRIVE_SETUP.md for detailed instructions.

   Quick setup:

   bun setup:gdrive

   Follow the interactive prompts to authenticate with Google Drive and get your credentials.

   Then add the credentials to .env:

   cp .env.example .env
   # Edit .env and add your Google Drive credentials

3. Set up Convex:

   npx convex dev

   This will:

   • Create a Convex account (if needed)
   • Initialize your backend
   • Generate .env.local with your deployment URL

4. Set up admin account:

   a. Add your email to .env:

   ADMIN_EMAIL=[email protected]

   b. Start the dev server:

   bun dev

   c. Create account at http://localhost:3000/admin-auth.html

   d. Grant admin privileges:

   bun admin:grant

   e. Sign in at http://localhost:3000/admin-auth.html

5. Configure frontend:

   Open public/app.js, public/admin.html, and public/admin-auth.html and replace:

   const convexUrl = "REPLACE_WITH_YOUR_CONVEX_URL";

   with your actual Convex deployment URL from .env.local.

6. Access the app:

   • Radio player: http://localhost:3000
   • Admin panel: http://localhost:3000/admin.html
   • Admin login: http://localhost:3000/admin-auth.html

Usage

Adding Music

1. Upload music files to a Google Drive folder
2. Get the folder ID from the URL: https://drive.google.com/drive/folders/FOLDER_ID_HERE
3. Go to /admin.html
4. Paste the folder ID and click "Sync Folder"
5. Your songs will be imported to the library

Playing Music

From the admin panel:

• Click "Play" on any song to start streaming
• All listeners will automatically start hearing the stream
• Use "Skip Current Song" to move to the next track

Listening

1. Go to http://localhost:3000
2. Enter a username
3. You'll see:
   • Now playing info
   • Live listener count
   • Chat with other listeners
   • Play history

Project Structure

radio/
├── convex/              # Convex backend
│   ├── schema.ts        # Database schema
│   ├── radio.ts         # Radio functions
│   ├── chat.ts          # Chat functions
│   └── listeners.ts     # Listener tracking
├── server/              # Hono streaming server
│   ├── index.ts         # Main server
│   ├── stream.ts        # Audio streaming
│   └── drive.ts         # Google Drive API
├── public/              # Frontend
│   ├── index.html       # Main player
│   ├── admin.html       # Admin panel
│   └── app.js           # Convex client
└── scripts/             # Utilities
    └── setup-google-drive.ts

Architecture

The app uses a hybrid architecture:

• Convex handles all real-time state (now playing, chat, listeners, history)
• Hono/Bun server streams audio from Google Drive
• HTML frontend connects to Convex for reactive updates

All listeners stay synchronized because:

• Server stores a startedAt timestamp in Convex
• Clients calculate their position: (Date.now() - startedAt) / 1000
• Everyone plays from the same position in the same song

Configuration

Environment Variables

Create a .env file (see .env.example):

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
GOOGLE_CREDENTIALS={"access_token":"...","refresh_token":"..."}
PORT=3000

Convex auto-generates .env.local:

CONVEX_DEPLOYMENT=https://your-deployment.convex.cloud

Development

bun dev              # Start dev servers
bun setup:gdrive     # Configure Google Drive
bun admin:grant      # Grant admin privileges
npx convex dev       # Convex dev mode
bun start            # Production server
npx convex deploy    # Deploy Convex backend

Deployment

1. Deploy Convex backend:

   npx convex deploy

2. Deploy Hono server to your hosting provider (Vercel, Fly.io, etc.)

3. Update environment variables in production

4. Update Convex URLs in public/app.js and public/admin.html

Future Enhancements

• Auto-play algorithm (shuffle, playlists, moods)
• Song metadata extraction from ID3 tags
• Playlist management
• Voting/skip requests
• Multiple radio channels
• Audio visualization
• DJ mode with manual control

Documentation

• CLAUDE.md - Complete technical reference for developers and Claude Code
• docs/GOOGLE_DRIVE_SETUP.md - Google Drive API setup guide
• docs/ - Additional documentation

License

ISC

Contributing

Feel free to submit issues and enhancement requests!