RadioWave

A modern web radio application for discovering, playing, and organising radio stations from around the world.

Status: Active development — core functionality is working; new Figma-based UI is partially implemented.

Figma Design · Backend Architecture Docs

---

Table of Contents

• Features
• Tech Stack
• How to Start
• Getting Started
• Planned Features
• Screenshots

---

Features

Radio Browsing — Browse stations by genre and category. Audio Streaming — Live audio playback directly in the browser. Station Selection — Click any station card to start playback. Playback Controls — Play, pause; only one station plays at a time. Recently Played — Locally tracked listening history. Station Discovery — Stations loaded from the RadioBrowser API.

---

Tech Stack

Frontend

Tool	Purpose
React 18 + TypeScript	UI framework
Vite	Dev server & build
Tailwind CSS	Styling
Radix UI	Accessible UI primitives
Howler.js	Audio playback
Embla Carousel	Carousel component
Lucide React	Icons
Recharts	Data visualisation

Backend

Tool	Purpose
Express	HTTP server
Turso (libSQL)	Primary database
Redis	Caching layer
Jest	Testing
RadioBrowser API	Station data source

---

How to Start

1. Fork the repository by clicking the Fork button on GitHub.

2. Clone your fork:

git clone https://github.com/<your-username>/radio-app.git
cd radio-app

---

Getting Started

Prerequisites

• Node.js 18+
• Redis instance (local or hosted via Upstash) — provides REDIS_URL and REDIS_TOKEN
• Turso database — provides TURSO_DATABASE_URL and TURSO_AUTH_TOKEN

Installation

Backend:

cd backend
npm install
npm run dev

Create a .env file in the backend/ directory with the following variables:

PORT=5001
FRONTEND_URL=
REDIS_URL=
REDIS_TOKEN=
TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=

Frontend:

cd frontend
npm install
npm run dev

The frontend runs at http://localhost:5173, backend at http://localhost:5001.

Verify the backend is running:

curl http://localhost:5001/api/stations

Run Tests

cd backend
npm test

---

Planned Features

Audio Experience

• Persistent mini player on all pages
• Full-screen player on mobile
• Volume control with saved preferences
• Playback queue
• Visual equaliser
• Media controls (headphones, Bluetooth)

Station Discovery

• Search by name, country, genre
• Filters by country, genre, mood
• Trending stations
• Pagination

Personal Library

• Favourite stations
• Listening history
• Custom collections
• Cross-device sync

User Accounts

• Registration and login
• Personal profiles with stats
• Guest vs. signed-in data separation

AI Features

• Mood-based recommendations
• Natural language search
• Personalised daily mixes
• Listening insights dashboard

Social & Sharing

• Share stations via links
• Trending genres and countries

Editorial Content

• Music and radio-related articles
• Save, like, and share articles
• Browse by category or search

Design & Performance

• Desktop sidebar and mobile bottom navigation
• Smooth animations and transitions
• Accessibility support (keyboard navigation, screen readers)
• Cached data for better performance
• Graceful offline handling

---

Screenshots

New Design (in progress)

Desktop	Mobile

Current Version

Desktop	Mobile