A clean, compact, and highly responsive Progressive Web App (PWA) designed to stream global radio stations directly within the browser. Built entirely with vanilla frontend technologies, World Radio leverages a distributed network of open-source directory indices to let users discover, search, and catalog live audio feeds across continents, countries, and specific genre tags.
- Global Infrastructure Navigation: Dynamic routing that detects and fallbacks to the closest active server across the open-source Radio Browser API network.
- Geographic & Taxonomy Filtering: Seamless sorting of stations by continent mapping (ISO-3166-1 standard validation), explicitly handling live data across Africa, Asia, Europe, North America, Oceania, and South America.
- Persistent User Storage: Local caching logic via HTML5 Web Storage (
localStorage) to manage deep states for custom Favorites playlists, a structural "Exclude" filter to hide unwanted streams, and a 30-item rolling Recent History log. - Robust Audio Stream State Controls: Dedicated stream recovery framework incorporating a microsecond-based anti-caching strategy (
_nocache=TIMESTAMP) to re-sync or bypass broken server handshakes mid-stream. - PWA Compatibility Natively: Implements standard Service Worker lifecycle patterns to handle local asset caching alongside an active standalone Manifest engine to prompt instant installation on desktop or mobile environments.
- Fluid Visual Controls: Features an interactive 9-bar CSS keyframe animation visualizer bound tightly to the HTML5 Audio playback status, volume attenuation sliders, and clear connectivity feedback handlers.
├── index.html # Application interface architecture and structural layout
├── styles.css # Unified design system, grid definitions, and responsive bounds
├── app.js # API routers, state controls, event listeners, and player core
├── sw.js # Offline intercept strategy and cache management rules
└── manifest.json # Progressive Web Application runtime parameter configurations
API Routing Optimization
On initialization, the application hits the global server directory balance point to retrieve a dedicated local server name string. All secondary requests across the pipeline use this dynamically resolved baseApiUrl endpoint to minimize latencies or bypass regional network blockages.
CSS Layout Strategy
The presentation layer leverages a locked sub-component grid layout optimized for a desktop boundary size of 1200px width and 92vh height. Dynamic items (such as the primary station selection feed) adjust intelligently using repeat(auto-fill, minmax(220px, 1fr)) columns to prevent content stretching across larger workspace dimensions. Audio Stream Recovery Strategy
To address structural dropouts or changing connection environments common to streaming live audio over the internet, a recovery mechanism is wired directly into the native playback controller:
const baseSrc = currentSelectedStation.url_resolved || currentSelectedStation.url; audio.src = baseSrc + (baseSrc.includes('?') ? '&' : '?') + '_nocache=' + Date.now(); audio.load();
This forces the browser pipeline to fully drop stale network buffers and negotiate a completely fresh data layer from the endpoint.
Prerequisites
To run this application locally, you only need a modern web browser that supports HTML5 Audio and the Fetch API. No specialized build tools, runtimes, or Node modules are required.
-
Clone this repository to your local development environment:
-
Navigate directly into the directory:
cd world-radio
-
Open index.html inside your browser of choice, or run a simple local development server using Python:
python3 -m http.server 8000
-
Access the workspace at http://localhost:8000.
Core Directory Indexing: Powered seamlessly by the free Radio Browser API Community Project.
UI Graphic Components: Crisp vector symbols rendered responsively by Lucide Icons Open Source Engine.
This project is open-source and available under the MIT License.