📋 Overview

This is a modern, feature-rich HTML5 audio player built with vanilla JavaScript, featuring a unique circular canvas-based visualizer, comprehensive playlist management, and advanced audio processing capabilities. The application is designed to be lightweight, dependency-free, and fully responsive across all devices.

Key Highlights

• Zero Dependencies: Pure vanilla JavaScript, HTML5, and CSS3
• Circular Visualizer: Real-time audio visualization using HTML5 Canvas
• Advanced Playlist: IndexedDB-powered persistent storage with drag-and-drop reordering
• 10-Band Equalizer: Professional-grade audio equalization with presets
• Playback Speed Control: Adjustable speed from 0.5x to 2x with modal selection
• Shuffle & Repeat: Multiple playback modes (off, one, all)
• Custom Background: Upload or URL-based background images with glassy effect
• Theme System: System-aware light/dark theme switching
• Fully Responsive: Optimized for desktop, tablet, and mobile
• Accessibility: WCAG-compliant with keyboard navigation and ARIA labels

✨ Features

📖 User Guide

This section provides step-by-step instructions on how to use each feature of the audio player.

🎵 Basic Playback

Playing Music

1. Open the playlist by clicking the playlist icon (📋) in the top-left corner
2. Click on any track in the playlist to start playback
3. Use the play/pause button in the center of the player to control playback
4. Click the previous (◀) or next (▶) buttons to navigate between tracks

Seeking Through a Track

• Mouse/Touch: Click or tap anywhere on the circular visualizer to jump to that position
• Keyboard: Press ← (left arrow) to seek backward 10 seconds, or → (right arrow) to seek forward 10 seconds

Volume Control

1. Hover over the volume icon (🔊) at the bottom of the player
2. A volume slider will appear
3. Drag the slider up to increase volume or down to decrease
4. Click the volume icon to mute/unmute
5. Keyboard: Press ↑ to increase volume, ↓ to decrease, or M to mute/unmute

🎚️ Using the Equalizer

1. Click the equalizer button (🎚️) in the player controls (top-right area)
2. The equalizer panel will appear below the player
3. Adjust any of the 10 frequency bands by dragging the sliders:
   • Move sliders up to boost frequencies (+12dB max)
   • Move sliders down to reduce frequencies (-12dB max)
4. Use preset buttons for quick configurations:
   • Flat: All bands at 0dB (neutral)
   • Bass Boost: Enhances low frequencies
   • Treble Boost: Enhances high frequencies
   • Vocal: Optimizes for vocal clarity
5. Click the equalizer button again to close the panel

🔀 Shuffle Mode

1. Click the shuffle button (🔀) in the player controls
2. The button will highlight when shuffle is active
3. Tracks will play in random order
4. Click again to disable shuffle
5. Keyboard: Press S to toggle shuffle

🔁 Repeat Modes

1. Click the repeat button (🔁) in the player controls
2. Cycle through three modes:
   • Off: Normal playback, stops at end of playlist
   • One: Repeats the current track indefinitely
   • All: Repeats the entire playlist
3. The button icon changes to indicate the current mode
4. Keyboard: Press R to cycle through repeat modes

⚡ Playback Speed Control

1. Click the speedometer button (⚡) in the player controls
2. A speed panel will appear
3. Select your desired speed:
   • 0.5x (slowest)
   • 0.75x
   • 1x (normal)
   • 1.25x
   • 1.5x
   • 1.75x
   • 2x (fastest)
4. The speed setting persists across sessions
5. Click the × button or press T to close the speed panel
6. Keyboard: Press T to open/close the speed panel

📋 Playlist Management

Opening the Playlist

1. Click the playlist icon (📋) in the top-left corner
2. The playlist panel will slide in from the left
3. Click outside the panel or press Escape to close

Adding Tracks

1. Open the playlist panel
2. Click the "Add Track" button (usually at the top)
3. Choose one of two methods:
   • From URL: Enter the track URL, song name, and artist name
   • From File: Click "Choose File" and select an audio file from your device
4. Click "Add" to add the track to your playlist

Reordering Tracks (Drag and Drop)

1. Open the playlist panel
2. Desktop: Click and hold the drag handle (⋮⋮) on the left of a track, drag it to the desired position, and release
3. Mobile: Touch and hold the drag handle, drag to the desired position, and release
4. The new order is automatically saved

Searching/Filtering Tracks

1. Open the playlist panel
2. Click in the search box at the top of the playlist
3. Type to filter tracks by:
   • Song name
   • Artist name
   • URL
4. Results update in real-time as you type
5. Click the × button to clear the search
6. Keyboard: Press Ctrl+F or / to focus the search box

Deleting Tracks

1. Open the playlist panel
2. Hover over a track to reveal the delete button (🗑️)
3. Click the delete button
4. Confirm deletion if prompted

Downloading Tracks

1. Open the playlist panel
2. Hover over a track to reveal the download button (⬇️)
3. Click the download button
4. The track will download to your device

Sharing Tracks

1. Open the playlist panel
2. Click the share button (🔗) on any track
3. The track URL will be copied to your clipboard
4. Share the URL with others - they can open it to play that specific track

🎤 Recording Audio

1. Click the record button (🎤) in the player controls
2. The recording panel will appear
3. Click "Start" to begin recording
4. Speak or play audio into your microphone
5. While recording, you can:
   • Click "Pause" to pause recording (click "Resume" to continue)
   • Click "Finish" when done recording
   • Click "Cancel" to discard the recording
6. After finishing, a save dialog will appear
7. Enter a song name and artist name
8. Click "Save" to add the recording to your playlist
9. The recording will appear in your playlist automatically

📻 Listening to Radio/Streams

1. Add a streaming URL to your playlist (same as adding a regular track)
2. Click on the stream in your playlist
3. The player will automatically detect it's a live stream
4. A "LIVE" indicator will appear instead of the time display
5. Seeking controls are automatically disabled for live streams
6. Use play/pause and volume controls normally

🌓 Changing Theme

1. Look for the theme buttons in the top-right corner
2. Click one of three options:
   • System: Follows your operating system's theme preference
   • Light: Always use light theme
   • Dark: Always use dark theme
3. Your preference is saved automatically

🖼️ Custom Background Image

1. Open the playlist panel
2. Click the settings/gear icon (⚙️) to open settings
3. Find the "Background Image" section
4. Choose one of two methods:
   • From URL: Switch to "URL" tab, enter an image URL, and click "Apply Background"
   • Upload File: Switch to "Upload" tab, click "Choose File", select an image, and click "Apply Background"
5. A preview will appear - adjust if needed
6. Click "Apply Background" to set the background
7. The background will appear with a glassy blur effect
8. Click "Clear" to remove the background image

🖼️ Picture-in-Picture Mode

Picture-in-Picture (PiP) mode allows you to have a floating mini player window that stays visible while you browse other tabs or work in other applications.

Opening PiP Mode

1. Click the Picture-in-Picture button (🖼️) in the player controls (bottom of the player)
2. A floating window will appear with track information and controls
3. The window can be dragged around the screen by clicking and dragging the header

Using PiP Controls

• Previous Button (◀): Go to the previous track
• Play/Pause Button (▶/⏸): Control playback
• Next Button (▶): Go to the next track
• Close Button (×): Close the PiP window

PiP Features

• Native Browser PiP: On supported browsers, uses native Picture-in-Picture API for cross-tab support
• Custom Floating Window: Fallback mode with fully clickable buttons
• Position Memory: Remembers window position between sessions
• Real-time Updates: Track info, time, and play state update automatically
• Draggable: Click and drag the header to move the window

Closing PiP Mode

1. Click the close button (×) in the top-right corner of the PiP window, or
2. Click the Picture-in-Picture button again in the player controls

⚙️ Settings

Accessing Settings

1. Open the playlist panel
2. Click the settings/gear icon (⚙️)
3. The settings panel will appear

Available Settings

• Playback: Auto advance on end, loop current track, auto play on track select
• Player control buttons: Show or hide each control (Shuffle, Repeat, Equalizer, Speed, Record, Picture-in-Picture) individually; changes apply and persist immediately
• Theme: System, Light, or Dark
• Volume: Default volume level
• Background Image: Set a custom background via URL or file upload (see above)
• Data Management: Clear Database to remove all stored data (playlists, settings, recordings)

Save Settings

The Save Settings button appears in a dedicated footer at the bottom of the settings form, separated by a border from the sections above. It applies to all settings (playback, player buttons, theme, volume, background image). Use it after changing any options to persist them.

Background Image section (From URL tab)

In the Background Image section, the From URL tab shows a text input for the image URL and a Load from URL button. The input is styled as a text field (lighter background, normal text), and the button is styled as a primary action (accent color, prominent) so the two are clearly distinct.

🎹 Keyboard Shortcuts

Use these keyboard shortcuts for quick access to features:

💡 Tips & Tricks

• Quick Track Selection: Click directly on a track in the playlist to start playing it
• Visual Feedback: The circular visualizer shows real-time audio frequency data - watch it react to the music!
• Persistent Settings: Your equalizer settings, playback speed, and theme preference are saved automatically
• Mobile Optimization: On mobile devices, use touch gestures for drag-and-drop reordering
• Offline Playback: Tracks stored in IndexedDB can be played offline
• Large Playlists: Use the search feature to quickly find tracks in large playlists
• Recording Quality: Recordings are saved in WebM/Opus format for good quality and file size
• Background Images: Images are automatically compressed when uploaded to save storage space

❓ Troubleshooting

Audio Not Playing

• Check your browser's console for errors (F12 → Console tab)
• Ensure the audio file URL is accessible and not blocked by CORS
• Try a different audio format (MP3, OGG, WAV)
• Check your browser's autoplay policies - some browsers require user interaction first

Recording Not Working

• Grant microphone permissions when prompted
• Check your browser's privacy settings for microphone access
• Ensure you're using HTTPS (required for MediaRecorder API in most browsers)

Playlist Not Saving

• Check if IndexedDB is supported in your browser
• Check browser storage quota - clear some space if needed
• Try clearing browser cache and reloading

Visualizer Not Showing

• Ensure audio is actually playing
• Check if Web Audio API is supported in your browser
• Try refreshing the page

🏗️ Architecture

System Architecture

┌─────────────────────────────────────────────────────────┐
│                    HTML5 Audio Element                  │
│                    (Media Source)                       │
└────────────────────┬──────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│              Web Audio API Graph                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ Equalizer│→ │   Gain   │→ │ Analyser │→ │   Out  │ │
│  │ Filters  │  │   Node    │  │   Node   │  │        │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
└─────────────────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│              Canvas Visualizer                          │
│         (Circular Frequency Display)                    │
└─────────────────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│              Playlist System                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
│  │ IndexedDB│  │   JSON    │  │ Controls │            │
│  │ Storage  │  │  Fallback │  │   & UI   │            │
│  └──────────┘  └──────────┘  └──────────┘            │
└─────────────────────────────────────────────────────────┘
                

Core Components

1. Player Engine (player.js)

The main audio playback engine that handles:

• HTML5 Audio element management
• Web Audio API graph construction
• Equalizer filter chain
• Volume control via GainNode
• Audio analysis via AnalyserNode
• Playback state management
• Playback speed control (0.5x - 2x)
• Live stream detection and handling
• Audio recording via MediaRecorder API
• Shuffle and repeat logic

2. Visualizer (player.js - Framer, Tracker, Scene)

Canvas-based visualization system:

• Scene: Canvas setup and coordinate system
• Framer: Circular tick marks and loading indicator
• Tracker: Frequency bars visualization
• Controls: Play/pause button visualization

3. Playlist System (playlist.js)

Comprehensive playlist management:

• Track loading from JSON or IndexedDB
• Drag-and-drop reordering
• Track addition/removal
• Real-time search and filtering
• Thumbnail management
• Share functionality
• UI rendering and interaction

4. Storage Layer (idb.js)

IndexedDB wrapper for persistent storage:

• Track metadata storage
• Playlist order management
• Blob storage for uploaded files
• State persistence
• Automatic migration and fallback

5. Theme System (theme.js)

Dynamic theme management:

• System preference detection
• Light/dark theme switching
• CSS variable management
• Preference persistence

6. Recording System (recording.js)

Audio recording functionality:

• MediaRecorder API integration
• Microphone access and permissions
• Recording state management (start, pause, resume, stop)
• Real-time recording timer
• WebM/Opus format encoding
• Recording save dialog and metadata input
• Automatic playlist integration

7. UI Components (script.js)

User interface utilities:

• Toast notifications
• Modal dialogs
• Responsive scaling
• Event handling

8. Picture-in-Picture System (pip.js)

Floating mini player window:

• Native browser Picture-in-Picture API integration
• Custom floating window fallback
• Canvas-based visual display with track info and visualizer
• Drag-and-drop window positioning
• Position persistence in localStorage
• Real-time synchronization with main player
• Clickable controls (play/pause, previous, next)

📁 File Structure

The project follows a clean, organized structure with clear separation of concerns:

Core Files Overview

Directory Structure

⚙️ Configuration

Playlist Configuration (playlist.json)

Track entries can be single audio files or M3U playlists (one playlist = one row; the player plays through its entries in order). Use "url" ending in .m3u/.m3u8 or add "isM3u": true for M3U.

{
    "version": 1,
    "autoplayOnSelect": true,
    "tracks": [
        {
            "artist": "Playlist",
            "song": "Demo playlist (M3U)",
            "url": "assets/tracks/demo-playlist.m3u",
            "thumbnail": "optional-image-url.jpg"
        },
        {
            "artist": "Artist Name",
            "song": "Song Title",
            "url": "path/to/track.mp3",
            "thumbnail": "optional-image-url.jpg"
        }
    ]
}

📑 M3U Playlist Support

The player supports M3U / M3U8 playlists as a single playlist entry. When you load or select an M3U track, the player fetches the file, parses the list of entries, and plays them in order (next/previous move through the M3U entries, then the main playlist).

M3U from URL (e.g. playlist.json)

• Use a track with url ending in .m3u or .m3u8, or set isM3u: true.
• Relative paths in the M3U file are resolved against the M3U URL. Keep entry paths (e.g. filenames only) in the same folder as the M3U for correct resolution.
• M3U URLs are prefetched when the playlist is applied so that selecting an M3U can start playback immediately (same user gesture).

Uploaded M3U (with audio files)

• Upload the M3U file and all its audio files together (same selection). The app matches M3U entries to uploaded files by filename and creates one playlist entry for the M3U.
• Resolved entries are stored in IndexedDB as Blobs (m3uResolvedEntries), so the uploaded M3U playlist works after page refresh and when switching to another track and back.
• If you upload only the M3U (no audio files), you’ll see a message to upload the M3U together with its audio files. M3U entries that are absolute URLs (http/https) are still used when present.

Auto-play on select

When “Auto play on track” is enabled in Settings, selecting a track (including an M3U) starts playback. For M3U from URL, prefetch ensures the list is ready so playback can start on first select. If the browser blocks autoplay, the next click or key press will start playback.

Player Settings

Settings are stored in localStorage and can be modified programmatically:

Player.settings = {
    autoPlay: false,        // Auto-play on load
    autoAdvance: false,     // Auto-advance to next track
    repeatMode: 'off',      // 'off' | 'one' | 'all'
    shuffle: false          // Enable shuffle mode
}

Theme Configuration

Themes are managed via CSS variables in style.css:

:root {
    --accent: #FE4365;           // Primary accent color
    --neutral: #F5F5F5;          // Neutral color
    --accent-rgb: 254, 67, 101;  // RGB values for rgba()
    
    // Theme-specific variables are set dynamically
    // via JavaScript based on user preference
}

Equalizer Configuration

Equalizer bands are configured in player.js:

var frequencies = [
    60,      // 60Hz - Sub-bass
    170,     // 170Hz - Bass
    310,     // 310Hz - Low-mid
    600,     // 600Hz - Mid
    1000,    // 1kHz - Upper-mid
    3000,    // 3kHz - Presence
    6000,    // 6kHz - Brilliance
    12000,   // 12kHz - High
    14000,   // 14kHz - Very high
    16000    // 16kHz - Ultra high
];

Background Image Configuration

Custom background images can be set through the Settings panel. The Save Settings button is in a separate footer below all sections (including Background Image), so it is clear that it saves all settings. In the Background Image From URL tab, the URL input is styled as a text field and the Load from URL button as a primary action for clarity. The feature supports:

• Image URLs: Enter any publicly accessible image URL
• File Upload: Upload image files directly from your device
• Glassy Effect: Automatic frosted glass effect with adjustable blur and opacity
• Responsive Scaling: Background scales with the player UI
• Persistence: Background image is saved to IndexedDB (or localStorage fallback)

Background images are stored in IndexedDB under the key 'backgroundImage'. You can programmatically set or clear the background:

// Set background image from URL
Playlist.setBackgroundImage('https://example.com/image.jpg');

// Set background image from data URL (file upload)
Playlist.setBackgroundImage('data:image/jpeg;base64,...');

// Clear background image
Playlist.clearBackgroundImage();

// Load current background image
Playlist.loadBackgroundImage().then(function(url) {
    console.log('Current background:', url);
});

🔌 API Reference

Player API

Playback Control

Equalizer API

Shuffle & Repeat API

Playback Speed API

Playlist API

Background Image API

The background image feature allows users to customize the player's background with a glassy/frosted glass effect:

• Image Sources: Supports both image URLs and uploaded files (converted to data URLs)
• Storage: Background image URL is stored in IndexedDB under key 'backgroundImage'
• Visual Effect: Automatic glassy effect with blur, brightness, and saturation filters
• Responsive: Background scales with player UI using CSS custom properties
• Theme Aware: Overlay adjusts for light/dark themes

Example usage:

// Set background from URL
Playlist.setBackgroundImage('https://example.com/background.jpg');

// Set background from uploaded file (data URL)
var fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', function(e) {
    var file = e.target.files[0];
    var reader = new FileReader();
    reader.onload = function(e) {
        Playlist.setBackgroundImage(e.target.result);
    };
    reader.readAsDataURL(file);
});

// Clear background
Playlist.clearBackgroundImage();

// Load existing background
Playlist.loadBackgroundImage().then(function(url) {
    if (url) {
        console.log('Background loaded:', url);
    }
});

Search Functionality

The search feature automatically filters tracks as you type in the search input. It searches across:

• Song/track names
• Artist names
• Track URLs

The search is case-insensitive and updates in real-time. Use Ctrl+F or / to focus the search input when the playlist is open.

Streaming Support

The player automatically detects and handles live radio streams:

• Live Stream Detection: Detects streams with infinite or unknown duration
• UI Indicators: Shows "LIVE" text with pulsing animation instead of time
• Seeking Disabled: Automatically disables seeking controls for live streams
• Supported Formats: MP3 streams, Icecast, Shoutcast, and other HTTP/HTTPS audio streams
• CORS Support: Handles cross-origin streams with proper CORS headers

To add a radio stream, simply add it to your playlist with a streaming URL:

{
  "artist": "Radio Station",
  "song": "Live Stream",
  "url": "https://stream.example.com/radio.mp3"
}

Storage API (PlaylistStore)

💾 Database System

IndexedDB Overview

This application uses IndexedDB (Indexed Database API) as its primary storage mechanism. IndexedDB is a low-level API for client-side storage of significant amounts of structured data, including files/blobs.

Database Schema

The application uses a single IndexedDB database named 'circular-player-db' with the following structure:

Database: 'circular-player-db'
Version: 1

Object Stores:
1. 'tracks'
   - Key: id (auto-increment)
   - Index: url (unique)
   - Fields: artist, song, url, blob, mime, thumbnail, thumbnailBlob, isLiveStream

2. 'state'
   - Key: key (string)
   - Fields: value (any type)
   - Common keys: 'playlistOrder', 'lastTrackId', 'autoplayOnSelect', 'backgroundImage'

3. 'files'
   - Key: id (auto-increment)
   - Fields: blob (Blob object), mime (string), size (number)
   - Used for: Storing uploaded audio files and recordings

Safety & Security Considerations

Data Storage Details

What Gets Stored:

• Playlist Tracks: Track metadata (artist, song, URL), audio file blobs, thumbnails
• Playlist Order: Custom track ordering from drag-and-drop
• User Preferences: Theme preference, autoplay settings, background image URLs
• Recordings: Audio recordings saved by users (stored as Blob objects)
• State Data: Last played track, playlist order, various settings

Storage Size Considerations:

• Audio Files: Uploaded audio files are stored as Blob objects. Large files will consume significant storage space.
• M3U Resolved Entries: For uploaded M3U playlists (M3U + audio files added together), the resolved list of audio Blobs is stored in the track as m3uResolvedEntries so playback persists after refresh.
• Recordings: Audio recordings are stored in WebM/Opus format. Recording length directly affects storage size.
• Thumbnails: Image thumbnails are compressed to ~500KB maximum before storage.
• Background Images: Background images are stored as data URLs, which can be large for high-resolution images.

Best Practices & Cautions

Error Handling

The application includes error handling for common IndexedDB scenarios:

• Database Initialization Failures: Falls back to JSON-based playlist loading
• Storage Quota Exceeded: Shows error notifications to users
• Transaction Failures: Includes try-catch blocks and error callbacks
• Browser Support Detection: Checks for IndexedDB support before attempting operations

Data Migration & Compatibility

The application handles database versioning and migration:

• Version Management: Uses IndexedDB versioning system for schema updates
• Backward Compatibility: Maintains compatibility with existing data structures
• Fallback Mechanisms: Falls back to localStorage and JSON files if IndexedDB is unavailable

Privacy Considerations

Clearing Database

Users can clear all stored data through:

1. Application Settings: Use the "Clear Database" button in the Settings panel
2. Browser Developer Tools: Application → Storage → IndexedDB → Delete database
3. Browser Settings: Clear browsing data → Select "IndexedDB" → Clear

🔧 Technical Details

Web Audio API Graph

The audio processing pipeline:

MediaElementAudioSourceNode (HTML5 Audio)
    ↓
BiquadFilterNode (Equalizer Band 1)
    ↓
BiquadFilterNode (Equalizer Band 2)
    ↓
... (8 more bands)
    ↓
GainNode (Volume Control)
    ↓
AnalyserNode (Frequency Analysis)
    ↓
AudioDestinationNode (Output)

Visualizer Algorithm

The circular visualizer uses:

• AnalyserNode.getByteFrequencyData(): Gets frequency data (0-255 values)
• Circular Coordinate System: Converts frequency data to radial positions
• Gradient Rendering: Uses Canvas gradients for visual appeal
• RequestAnimationFrame: Smooth 60fps animation loop
• Dynamic Scaling: Adapts to screen size and DPI

Shuffle Algorithm

Uses Fisher-Yates shuffle for true randomization:

function generateShuffleOrder() {
    var order = [];
    for (var i = 0; i < tracks.length; i++) {
        order.push(i);
    }
    // Fisher-Yates shuffle
    for (var i = order.length - 1; i > 0; i--) {
        var j = Math.floor(Math.random() * (i + 1));
        var temp = order[i];
        order[i] = order[j];
        order[j] = temp;
    }
    return order;
}

Drag-and-Drop Implementation

Cross-platform drag-and-drop with robust mobile support:

• Desktop: Mouse events (mousedown, mousemove, mouseup) with visual drag indicators
• Mobile: Touch events (touchstart, touchmove, touchend) with improved drop detection
• Visual Feedback: translateY transform for smooth movement with drag indicators (dragOverBefore/dragOverAfter)
• Drop Detection: Multiple fallback strategies using elementFromPoint() API and position-based detection for reliable mobile reordering
• Persistence: Updates IndexedDB playlistOrder array with proper error handling
• Mobile Optimization: Enhanced touch handling with improved threshold detection (3x item height) and multiple fallback mechanisms to ensure reordering persists

IndexedDB Schema

Database: 'circular-player-db'
Version: 1

Object Stores:
1. 'tracks'
   - Key: id (auto-increment)
   - Index: url (unique)
   - Fields: artist, song, url, blob, mime, thumbnail, thumbnailBlob,
             isM3u (boolean, optional),
             m3uResolvedEntries (array, optional)
   - m3uResolvedEntries: for uploaded M3U, array of { artist, song, blob };
     Blobs are stored so the M3U playlist works after refresh and when
     switching tracks. Playlist creates blob URLs from these when applying.

2. 'state'
   - Key: key (string)
   - Fields: value (any)
   - Keys: 'playlistOrder', 'lastTrackId', 'autoplayOnSelect'

Responsive Scaling

The player uses CSS transforms for responsive scaling:

function updatePlayerScale() {
    var container = document.querySelector('.player');
    var baseWidth = 982; // Design width
    var scale = Math.min(
        window.innerWidth / baseWidth,
        window.innerHeight / baseWidth,
        1.0 // Max scale
    );
    container.style.transform = 'scale(' + scale + ')';
}

🎨 Customization

Changing Colors

Edit CSS variables in style.css:

:root {
    --accent: #FE4365;        /* Change to your brand color */
    --accent-rgb: 254, 67, 101; /* RGB values for rgba() */
    --neutral: #F5F5F5;       /* Neutral/background color */
}

Customizing Fonts

Replace font files in assets/fonts/ and update @font-face declarations.

Modifying Visualizer

Adjust visualizer parameters in player.js:

• Framer.countTicks: Number of tick marks (default: 360)
• Framer.tickSize: Tick size multiplier
• Tracker.barCount: Number of frequency bars
• Scene.padding: Canvas padding

Adding Custom Presets

Add equalizer presets in player.js:

applyEqualizerPreset: function (preset) {
    var presets = {
        'flat': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        'bass': [6, 4, 2, 0, 0, 0, 0, 0, 0, 0],
        'treble': [0, 0, 0, 0, 0, 2, 4, 6, 6, 6],
        'vocal': [-2, -1, 2, 4, 3, 1, -1, -2, -2, -2],
        'your-preset': [/* your values */]
    };
    // ... apply preset
}

🌐 Browser Support

Supported Browsers

Required APIs

• HTML5 Audio: Core playback
• Web Audio API: Visualization and equalizer
• Canvas API: Visualizer rendering
• IndexedDB: Persistent storage (with localStorage fallback)
• CSS Variables: Theme system
• Fetch/XHR: Playlist loading
• File API: File uploads
• Blob URL: Local file playback

⚡ Performance

Optimization Techniques

1. Canvas Optimization

• Uses requestAnimationFrame for smooth 60fps rendering
• Efficient gradient caching
• Minimal redraws (only updates changed areas)
• High-DPI display support with proper scaling

2. Memory Management

• Automatic cleanup of blob URLs to prevent memory leaks
• Thumbnail blob URL management
• Efficient IndexedDB usage with proper transaction handling

3. Audio Processing

• Efficient Web Audio API graph (single chain)
• Minimal CPU usage for equalizer (BiquadFilterNode is hardware-accelerated)
• Optimized frequency analysis (only reads necessary data)

4. Code Optimization

• Vanilla JavaScript (no framework overhead)
• Minimal DOM manipulation
• Event delegation where possible
• Debounced resize handlers

Performance Metrics

♿ Accessibility

WCAG 2.1 AA Compliance

The application follows WCAG 2.1 Level AA guidelines:

Keyboard Navigation

ARIA Labels

• All interactive elements have aria-label attributes
• Buttons include descriptive labels
• Form inputs have associated labels
• Modal dialogs use aria-modal and role="dialog"

Screen Reader Support

• Semantic HTML5 elements
• Proper heading hierarchy
• Live regions for dynamic content updates
• Focus management for modals

Visual Accessibility

• High contrast color schemes
• Focus indicators on all interactive elements
• Sufficient touch target sizes (44x44px minimum)
• Scalable text and UI elements

📊 Code Quality Analysis

Code Structure

• Modular Design: Separated into logical modules (player, playlist, theme, storage)
• IIFE Pattern: All modules use Immediately Invoked Function Expressions to avoid global pollution
• Strict Mode: All files use 'use strict' for better error handling
• Consistent Naming: Clear, descriptive variable and function names

Best Practices

• ✅ Error handling with try-catch blocks
• ✅ Defensive programming (null checks, type validation)
• ✅ Event listener cleanup
• ✅ Memory leak prevention (blob URL cleanup)
• ✅ Cross-browser compatibility
• ✅ Progressive enhancement
• ✅ Graceful degradation

Security Considerations

• Input sanitization for user-provided data
• Safe URL handling (no eval or innerHTML with user data)
• CORS-aware file loading
• XSS prevention through proper escaping

🚀 Deployment

Local Development

1. Clone or download the project
2. Serve files via HTTP server (required for Web Audio API)
3. Open index.html in browser

Production Deployment

1. Upload all files to web server
2. Ensure proper MIME types are configured
3. Enable HTTPS for secure contexts (required for some APIs)
4. Configure CORS headers if loading tracks from different domains
5. Optimize audio files (consider compression)

Recommended Server Configuration

# Nginx example
location / {
    try_files $uri $uri/ /index.html;
}

# MIME types
audio/mpeg mp3;
audio/ogg ogg;
audio/wav wav;
application/json json;

🔍 Troubleshooting

Common Issues

Audio Not Playing

• Check browser console for CORS errors
• Ensure files are served over HTTP/HTTPS
• Verify audio file format is supported (MP3, OGG, WAV)
• Check browser autoplay policies

Visualizer Not Working

• Verify Web Audio API is supported
• Check browser console for errors
• Ensure audio is actually playing

IndexedDB Not Working

• Check browser support
• Verify storage permissions
• Check for quota exceeded errors
• Application will fallback to localStorage automatically

Drag-and-Drop Not Working

• Ensure IndexedDB is available (required for reordering)
• Check that tracks have valid IDs
• Verify touch/mouse events are not blocked
• Mobile: Ensure you drag far enough (threshold is 10px) before releasing
• Mobile: Try dragging to a position near the center of another track for better detection
• Check browser console for any IndexedDB errors

Picture-in-Picture Not Working

• Native PiP: Check if your browser supports Picture-in-Picture API (Chrome 70+, Edge 79+, Safari 13+)
• Native PiP: Ensure the page has user interaction before requesting PiP
• Custom Window: If native PiP fails, the custom floating window should appear automatically
• Buttons Not Clickable: Ensure the window is not behind other elements (check z-index)
• Position Not Saved: Check browser localStorage permissions
• Cross-Tab Support: Native PiP works across tabs; custom window works within the current tab only
• Check browser console for any errors related to PiP

🔮 Future Enhancements

Potential Features

• 📊 Playback statistics and analytics
• 📱 Progressive Web App (PWA) support
• ☁️ Cloud storage integration
• 🎨 Custom visualizer themes
• 🎙️ Advanced recording features (pause/resume, multiple tracks)
• 🌍 Internationalization (i18n)
• 📈 Advanced analytics and reporting
• 📡 HLS/DASH streaming protocol support (via libraries)