Skip to main content

​
Installation

La Urban Radio Player is a standalone HTML5 application that doesn’t require installation or build steps. Simply clone or download the files and start customizing.
1

Download the Source

Clone the repository or download the source files to your local machine.
git clone https://github.com/yourusername/la-urban-player.git
cd la-urban-player
2

Configure Your Stream

Open js/index.js and update the configuration with your radio station details.
const CONFIG = {
    STREAM_URL: 'https://your-stream.com/listen/station/media',
    API_URL: 'https://your-azura.com/api/nowplaying/station',
    DEFAULT_TITLE: 'Your Radio Station',
    DEFAULT_COVER: 'https://your-station.com/img/default.jpg',
    UPDATE_INTERVAL: 5000,
};
3

Update Branding

Replace the logo and default images in the img/ folder with your station’s branding.
  • img/logo.png - Main station logo
  • img/default.jpg - Default album artwork
  • img/android-chrome-512x512.png - PWA icon
  • favicon.ico - Browser favicon
4

Deploy

Upload the files to your web server. The player works with any static hosting service.
# Example: Upload to your server
scp -r * [email protected]:/var/www/html/radio/

​
Local Development

For local development, you’ll need to handle CORS since browsers block cross-origin audio by default.
Running directly from file:// won’t work due to CORS restrictions. You need a local web server.
Create a proxy-server.js file in your project root: 
const express = require('express');
const cors = require('cors');
const { createProxyMiddleware } = require('http-proxy-middleware');

const app = express();

// Enable CORS for all routes
app.use(cors());

// Serve static files
app.use(express.static('.'));

// Proxy for the audio stream
app.use('/stream', createProxyMiddleware({
    target: 'https://stream.yourstation.com:8000',
    changeOrigin: true,
    pathRewrite: {
        '^/stream': '/media'
    }
}));

// Proxy for the API
app.use('/api', createProxyMiddleware({
    target: 'https://azura.yourstation.com',
    changeOrigin: true
}));

const PORT = 3000;
app.listen(PORT, () => {
    console.log(`✅ Server running at http://localhost:${PORT}`);
    console.log(`🎵 Stream: http://localhost:${PORT}/stream`);
    console.log(`📡 API: http://localhost:${PORT}/api/nowplaying/station`);
});
Update your config for development: 
// Development URLs
const CONFIG = {
    STREAM_URL: 'http://localhost:3000/stream',
    API_URL: 'http://localhost:3000/api/nowplaying/station',
    // ... other settings
};
Remember to change the URLs back to production values before deploying!

​
Option 2: Python Simple Server

For quick testing without API functionality: 
# Python 3
python -m http.server 8000

# Python 2
python -m SimpleHTTPServer 8000
Then open http://localhost:8000 in your browser.
This won’t work for the audio stream due to CORS, but you can test the UI and layout.

​
Option 3: VS Code Live Server

Install the Live Server extension and click “Go Live” in VS Code.

​
Basic Usage

Once deployed, users can interact with your radio player:

​
Starting Playback

1

Initial Load

The player shows a loading screen while initializing.
2

Play Button Overlay

Users see a play button with engaging messages encouraging them to start listening.
const PLAY_MESSAGES = [
    { text: 'Dale play y disfruta', emoji: '🎧' },
    { text: 'dale play no seas tímido', emoji: '😳' },
    // Customize these for your audience!
];
3

Streaming Begins

After clicking play, the overlay disappears and streaming starts with a smooth fade-in.

​
Player Controls

The player includes several interactive controls: Play/Pause Button 
<button id="customPlayBtn" class="control-btn play-pause">
    <i class="fas fa-play"></i>
</button>
Volume Control
  • Desktop: Horizontal slider
  • Mobile: Popup slider (tap volume icon)
  • Displays percentage overlay on cover art
Social Media Links 
<a href="https://www.instagram.com/yourstation" class="social-btn">
    <i class="fab fa-instagram"></i>
</a>

​
Customizing the Player

​
Update Station Information

Edit the HTML metadata in index.html: 
<title>Your Station · Online Radio</title>
<meta name="description" content="Your station description here.">
<meta property="og:title" content="Your Station · Online Radio">
<meta property="og:image" content="https://yourstation.com/img/share.png">

​
Customize Action Buttons

The player includes two customizable action buttons: 
// In index.js, these are configured:
elements.dynamicButton.href = CONFIG.REQUEST_IFRAME_URL;
elements.dynamicCanvas.href = CONFIG.CHAT_IFRAME_URL;

const CONFIG = {
    REQUEST_IFRAME_URL: 'https://azura.yourstation.com/public/station/embed-requests?theme=dark',
};

​
Modify Color Scheme

The player features a day/night theme system: 
// Automatic theme based on time
function setThemeByTime() {
    const hour = new Date().getHours();
    const isDaytime = hour >= 6 && hour < 18;
    
    document.body.style.background = isDaytime
        ? 'linear-gradient(135deg, #f89200, #facc22)' // Day colors
        : 'linear-gradient(to bottom, rgba(2,7,29) 0%, rgb(8, 30, 77) 100%)'; // Night colors
}
Update CSS variables in css/index.css: 
:root {
    /* Colores de acento - Por defecto NOCHE (azul/cyan) */
    --accent-primary: #00d9ff;
    --accent-secondary: #0099ff;
    --accent-glow: rgba(0, 217, 255, 0.6);
    --accent-glow-strong: rgba(0, 217, 255, 0.8);
    --accent-glow-soft: rgba(0, 217, 255, 0.4);
}

/* Modo DÍA - Colores naranja/amarillo */
body.theme-day {
    --accent-primary: #fc5e16;
    --accent-secondary: #fc9e16;
    --accent-glow: rgba(252, 94, 22, 0.6);
    --accent-glow-strong: rgba(252, 94, 22, 0.8);
    --accent-glow-soft: rgba(252, 94, 22, 0.4);
}

​
Testing Features

​
Test Lyrics Synchronization

Open the browser console (F12) and use these commands: 
// Manually search for lyrics of current song
searchCurrentSongLyrics()

​
Test Audio Visualization

The logo should react to the music in real-time:
  • Kicks/Bass: Logo scales and moves vertically
  • Mids: Logo rotates slightly
  • Highs: Background overlay brightens
Visualization requires CORS to be properly configured on your stream server. On mobile devices, a CSS fallback animation is used for better performance.

​
Monitor Performance

Check the console for performance logs: 
// In development mode, you'll see:
logger.dev('🎵 Fade-in: 0 → 1 en 2500ms');
logger.success('✅ Audio source conectado al visualizador');
logger.info('📱 Dispositivo móvil detectado');

​
Troubleshooting

​
Audio Won’t Play

1

Check CORS Headers

Verify your stream server includes CORS headers:
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
2

Verify Stream URL

Test the stream URL directly in your browser to ensure it’s accessible.
curl -I https://your-stream.com/media
3

Check Browser Console

Look for error messages in the browser console (F12).
4

Test on Mobile

Mobile devices (especially iOS) require user interaction before playing audio. The play button overlay handles this.

​
Lyrics Not Appearing

The player silently searches for lyrics. If none are found, it simply doesn’t display them - this is intentional.
To debug lyrics: 
// Check if lyrics system is active
console.log('Lyrics active:', state.lyricsManager?.isActive);

// Check current song info
console.log('Current song:', state.lastSongId);

// Manually trigger search (with detailed logs)
searchCurrentSongLyrics()

​
Visualization Not Working

The audio visualizer may not work due to CORS restrictions: 
// Check visualizer status
console.log('Visualizer active:', state.isVisualizerActive);
console.log('Audio context:', state.audioContext);
If you see CORS errors when connecting the audio source, the stream server needs proper CORS configuration. The player will fall back to CSS animations.

​
Mobile-Specific Issues

iOS Safari buffering:
  • iOS uses aggressive buffering. The lyrics system compensates with a 4.5s delay.
  • Ensure your stream supports byte-range requests.
Android Chrome:
  • Works well with standard configuration.
  • Uses 1.5s lyrics delay for optimal sync.
Volume popup not showing: 
// Check if mobile is detected
console.log('Is mobile:', isMobileDevice());
console.log('Window width:', window.innerWidth);

​
Production Deployment

​
Pre-Deployment Checklist

1

Update Configuration

Ensure all URLs point to production servers:
const CONFIG = {
    STREAM_URL: 'https://stream.yourstation.com/media',
    API_URL: 'https://azura.yourstation.com/api/nowplaying/station',
    // No localhost URLs!
};
2

Optimize Assets

Compress images and ensure fast loading:
# Optimize images
pngquant img/*.png
jpegoptim img/*.jpg
3

Test on Multiple Devices

  • Chrome Desktop
  • Safari Desktop
  • iOS Safari
  • Android Chrome
  • Firefox
4

Configure PWA (Optional)

Update site.webmanifest for Progressive Web App support:
{
  "name": "Your Radio Station",
  "short_name": "YourRadio",
  "theme_color": "#fc5e16",
  "background_color": "#000000",
  "display": "standalone"
}
5

Set Up HTTPS

Ensure your site uses HTTPS for Web Audio API and MediaSession to work properly.

​
Performance Optimization

The player includes several optimizations out of the box:
  • Smart caching reduces API calls
  • Conditional loading of iframe content
  • GPU-accelerated CSS transforms
  • Debounced updates for smooth performance

​
Next Steps

Configuration Guide

Detailed configuration options

Lyrics System

Advanced lyrics synchronization

Cache Management

Optimize API calls

Development Setup

Local development guide
Need help? The player includes extensive console logging in development mode to help you debug issues. Just open your browser’s developer tools!

Build docs developers (and LLMs) love

Get started for freeTalk to us