AeroRadio 🎵

AeroRadio is a premium, responsive Web-based Internet Radio client built with an Immersive Glassmorphism Dark Mode user interface. It connects to the open, public radio-browser.info API to allow users to search, browse, play, and save thousands of live radio streams from around the globe.

---

✨ Features

• Immersive Glassmorphism UI: High-fidelity frosted-glass panels, neon gradients (blue/purple/pink), smooth hover transitions, and fluid micro-animations.
• Dynamic Visuals & Tuning: Support for multiple rendering modes (Bar Graph, Pulsing Circular Ring, Oscilloscope Waveform) across four custom neon themes (Aero, Cyberpunk, Matrix, Sunset), with range tuning sliders to adjust visual response speed (smoothing) and height multiplier (sensitivity).
• 5-Band Graphic Equalizer (v1.1.0): Built on Web Audio API BiquadFilterNodes, allowing users to adjust Bass, Low-Mid, Mid, High-Mid, and Treble frequencies (+/-12dB) with pre-configured presets (Bass Boost, Vocal Boost, Electronic, Acoustic).
• Sleep Timer (v1.2.0): Fully offline Sleep timer with a digital countdown panel, fading volume down to zero smoothly over 3 seconds before pausing audio.
• Favorites Status Heartbeat (v1.2.0): Connection probe tool that checks the online/offline status of all saved stations in parallel (using no-cors headers and a 3.5s timeout) and displays glowing green or red status badges.
• Favorites Editor (v1.3.0): Hover pencil edit buttons on saved library cards that open a glassmorphic form overlay to update custom titles, logo URLs, stream URLs, and genre tags.
• Persistent User Settings (v1.3.2): Automatically preserves and restores player volume, 5-band graphic equalizer preset/slider gains, visualizer mode/theme/sensitivity/smoothing, and search limits across session restarts.
• Search Result Limit (v1.3.2): User-customizable result count filter (10 to 100) integrated into the Search & Browse bar to optimize bandwidth and load times.
• Browse & Search: Deep directory integration allowing search by keyword and filters for genres (tags), countries, and languages.
• Persistent Favorites: Save preferred stations locally using browser localStorage to access them on subsequent visits.
• Playback History: Keeps a list of recently played stations to quickly jump back in.
• Custom Stream Adder: Input custom audio stream URLs (AAC/MP3/OGG/HLS) to pin them directly into your library.
• System Logs & Diagnostics: Centralized logging panel that records initialization, stream playback, CORS redirections, and API connection details. Includes features to inspect traces, clear logs, and download log exports.
• Responsive Layout: Adapts smoothly to mobile devices, shifting the sidebar navigation to an elegant bottom tab bar.

---

🛠️ Technology Stack

• Structure: Semantic HTML5 with inline SVG icons for resolution-independent rendering.
• Styling: Vanilla CSS3 custom properties (variables), grid/flexbox layouts, backdrop-filters, and custom scrollbars.
• Logic: Modular Vanilla JavaScript (ES6 Modules). No compilation, bundlers, or external framework dependencies required.
• Data Source: Free & public Radio Browser API with automatic failover node resolution.

---

📂 Codebase Directory Structure

C:\repos\inet_radio_agy\
├── index.html          # Main HTML entry point, navigation panels, and audio player UI
├── styles.css          # Design system, CSS variables, glassmorphic styles, and keyframe animations
├── package.json        # Node configuration, scripts, and Electron builder metadata
├── main.js             # Electron main process and custom protocol controller
├── LICENSE             # MIT License terms
├── README.md           # Project documentation
├── build/
│   └── icon.png        # Custom desktop and taskbar application icon
└── js/
    ├── api.js          # API client wrapper handling server discovery and query searches
    ├── player.js       # Playback controller managing AudioContext, AnalyserNode, and CORS fallback
    ├── visualizer.js   # Canvas drawing loop for live audio analysis and fallback graphics
    ├── logger.js       # Centralized diagnostic logger utility
    └── app.js          # App orchestrator tying events, LocalStorage, and rendering together

---

🚀 How to Run & Build

Web Client (Local HTTP Server)

Since the web application uses ES6 modules, it must be run from an HTTP server rather than opening the HTML file directly.

Option 1: Python (Recommended)

Run the following command in the project directory:

python -m http.server 8080

Then visit: http://localhost:8080

Option 2: Node.js (npx)

Alternatively, if you prefer Node:

npx http-server -p 8080

Then visit: http://localhost:8080

Desktop Client (Electron App)

Make sure you run npm install first to install the desktop dependencies.

Run Desktop App Locally

Start the Electron frame for development:

npm start

Build Desktop Installer (.exe)

Package the application into a standalone Windows installer:

npm run dist

The compiled installer will be saved to dist/AeroRadio Setup 1.3.2.exe.

---

🧠 Behind the Scenes: CORS Audio Fallback

Many public internet radio streams do not send CORS (Cross-Origin Resource Sharing) headers. Setting crossOrigin = "anonymous" on an HTML audio element is required to read its bytes via the Web Audio API for visualizer analysis; however, if the stream server lacks CORS headers, the browser will refuse to play the audio.

To solve this, AeroRadio uses a dual-element playback graph in js/player.js:

1. Visualized Element (audioVisualized): Runs with crossOrigin = "anonymous" and is connected to the Web Audio graph.
2. Direct Playback Element (audioDirect): Runs without crossOrigin and bypasses the Web Audio graph entirely.

Playback flow:

• When a station is selected, the app attempts to play via audioVisualized.
• If a CORS error blocks loading, it seamlessly hands playback to audioDirect, guaranteeing the music plays successfully.
• If playback succeeds but the analyzer returns silent frequency data (due to CORS block on reading, even if playing), the visualizer dynamically swaps from live canvas rendering to a beautiful simulated equalizer wave in js/visualizer.js so the UI remains alive.

---

🌐 Production Deployment (Windows & Linux)

Since AeroRadio is entirely static (HTML, CSS, JS), it can be deployed to any production web server.

🐧 Linux Host Deployment

Option 1: Nginx (Standard Web Server)

1. Install Nginx:

   sudo apt update
   sudo apt install nginx -y

2. Copy the project files to the web root:

   sudo mkdir -p /var/www/aeroradio
   sudo cp -r . /var/www/aeroradio/
   sudo chown -R www-data:www-data /var/www/aeroradio

3. Configure Nginx: Create /etc/nginx/sites-available/aeroradio with this configuration:

   server {
       listen 80;
       server_name your_domain.com; # Or use default server block
   
       root /var/www/aeroradio;
       index index.html;
   
       location / {
           try_files $uri $uri/ =404;
       }
   
       # Enable caching for static assets
       location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg)$ {
           expires 7d;
           add_header Cache-Control "public, no-transform";
       }
   }

4. Enable the site and restart Nginx:

   sudo ln -s /etc/nginx/sites-available/aeroradio /etc/nginx/sites-enabled/
   sudo nginx -t
   sudo systemctl restart nginx

Option 2: Caddy (Automatic HTTPS)

1. Install Caddy on your Linux host.
2. Edit /etc/caddy/Caddyfile:

   your_domain.com {
       root * /var/www/aeroradio
       file_server
       encode gzip
   }

3. Restart Caddy: sudo systemctl restart caddy.

---

🪟 Windows Host Deployment

Option 1: IIS (Internet Information Services)

1. Enable IIS via Windows Features:
   • Open Turn Windows features on or off.
   • Check Internet Information Services -> World Wide Web Services -> Common HTTP Features -> Static Content.
2. Open the IIS Manager (inetmgr).
3. Add a new Website:
   • Right-click Sites -> Add Website...
   • Site name: AeroRadio
   • Physical path: Choose the project path (e.g., C:\repos\inet_radio_agy).
   • Port: Change to 80 (or 8080 to avoid conflicts).
4. Configure MIME Types:
   • Ensure .js files are served as application/javascript. (IIS usually handles this by default, but verify under the MIME Types feature if JavaScript files fail to load).
5. Start the website. Access it at http://localhost:<port>.

Option 2: Running Node/Python as a Service (PM2 on Windows)

If you want to serve it using Node's http-server package persistently:

1. Install PM2 globally:

   npm install pm2 -g
   npm install pm2-windows-service -g

2. Start the HTTP server under PM2 process manager:

   pm2 start npx --name "aeroradio" -- http-server C:\repos\inet_radio_agy -p 8080

3. Save the PM2 process list: pm2 save.

---

🐳 Cross-Platform: Docker Deployment (Linux/Windows)

You can containerize this application to run identically on any server with Docker installed:

1. Create a Dockerfile in the root directory:

   FROM nginx:alpine
   COPY . /usr/share/nginx/html/
   EXPOSE 80

2. Build the Docker image:

   docker build -t aeroradio:latest .

3. Run the container:

   docker run -d -p 8080:80 --name aeroradio_app aeroradio:latest

4. Access the server at http://<host-ip>:8080.

---

📄 License

This project is open-source software licensed under the MIT License. Feel free to use, modify, and distribute it.