🎵 Ultimate Local Music Player

A powerful, feature-rich offline music player with AI-powered playlists, intelligent EQ, crossfading, DJ mode, and advanced analysis

🌟 Complete Features Overview

🎼 Core Playback

Multi-Format Support: MP3, WAV, OGG, M4A, FLAC, AAC, WMA
Advanced Playlist Management: Load, shuffle, loop (all/one), search, smart filtering
Smart Folder Loading: One-click folder selection with auto-reload on startup
Folder Persistence: Remembers your music folder across sessions via IndexedDB
Hardware Media Controls: Works with keyboard shortcuts, media keys, headphone buttons, lock screen controls
Persistent Storage: Remembers your playlist, settings, folder location, and custom metadata across sessions
Background Playback: Continues playing when tab/app is minimized (PWA mode)
Seamless Crossfade: Intelligent crossfading with BPM-aware start points and smooth transitions
Jump to Current: Quickly scroll to the currently playing track in your playlist
Playlist Search: Fast search through 10+ tracks with real-time filtering

🎨 Visual Experience

4 Professional Visualizer Modes:
- 🎚️ Bars - Classic frequency spectrum bars with smooth gradients
- ⭕ Circular - Radial spectrum analyzer with pulsing center
- 🌊 Waveform - Dual mirrored wave display
- ✨ Particles - Interactive particle system that reacts to music
Mood-Based Visualizer Colors: Real-time color adaptation based on track analysis (energetic=red/orange, calm=blue, bright=yellow, dark=purple)
BPM-Synced Visual Effects: Visualizer pulses and animations sync with detected BPM
Energy-Modulated Animations: Animation intensity scales with track energy levels
Fullscreen Visualizer: Immersive full-window visualization with auto-hide controls
Fullscreen Lyrics Mode: Dedicated lyrics view with edge visualizer effects
Dynamic Backgrounds: Album art colors automatically influence UI theme
Custom Backgrounds: Upload your own background images or use URLs
Album Art Extraction: Automatic extraction and display from ID3 tags with color analysis

🎤 Lyrics System

WebVTT Support: Time-synced lyrics with precise millisecond timing
Auto-Scroll: Automatically follows current playback position
Click-to-Jump: Tap any lyric line to seek to that position
Export Options: Download lyrics as text file or copy to clipboard
Fullscreen Lyrics View: Dedicated immersive lyrics mode with edge-based visualizer
🆕 Automatic Lyrics Fetcher: Standalone tool to bulk-download synced lyrics from LRCLIB API
Lyrics Validation: Automatic VTT file validation with error reporting

🎛️ Audio Controls

10 Professional EQ Presets:
- Flat (Reference)
- Bass Boost (Modern genres)
- Treble Boost (Dull recordings)
- Rock (Aggressive midrange)
- Jazz (Warmth + air)
- Electronic (V-curve)
- Classical (Minimal, natural)
- Acoustic (Midrange focus)
- Podcast/Speech (Intelligibility)
- Vocal Clarity (Smile curve)
3-Band Manual EQ: Bass (200Hz), Mid (1kHz), Treble (3kHz) with ±12dB range
🆕 Auto-EQ System: Intelligent preset selection based on analysis
- Genre-based selection with audio analysis override
- Context-aware scoring (35+ confidence threshold)
- Vintage recording detection and handling
- Speech/podcast detection
- BPM and key compatibility checking
Volume Control: Slider, keyboard shortcuts, mouse wheel scroll support
Mute Toggle: Quick mute/unmute with volume memory

🧠 Advanced Analysis & Intelligence

🆕 Deep Music Analysis Tool: Standalone HTML tool for comprehensive track analysis
- Analyzes ENTIRE track duration (not just samples)
- BPM detection (40-200 BPM range)
- Energy calculation (LUFS-based, EBU R128 inspired)
- Spectral centroid analysis
- Dynamic range measurement (crest factor in dB)
- 6-band frequency analysis (sub-bass to brilliance)
- Vocal prominence detection
- Vintage recording detection
- Mood classification (energetic, calm, bright, dark, neutral)
- Tempo classification (slow, moderate, fast, very-fast)
- Exports analysis as .txt files
- Batch processing with progress tracking
- ZIP download for all analysis files
Analysis Text Parser: Loads pre-generated .txt analysis files
Background Analysis: Automatically analyzes tracks loaded without deep analysis
Analysis Caching: Saves results to memory for instant playlist generation

✏️ Metadata System

Custom Metadata Editor: Edit title, artist, album, year, genre, composer, comments
Persistent Custom Tags: Survives browser restarts using localStorage
Custom Metadata Storage: File-based storage system (name + size keys)
ID3 Tag Reading: Automatic extraction from audio files (via jsmediatags)
Multi-Format Support: MP3, M4A, FLAC, OGG, WAV, AAC, WMA metadata parsing
Playlist Integration: Updates display instantly across all views
Album Art Extraction: Automatic extraction and display from ID3 tags
Metadata Preview: Live preview in editor modal

🧠 Smart Playlist Generator

AI-Powered Analysis: Analyzes BPM, energy, mood, key, danceability, loudness
Enhanced Mood Detection: Considers tempo (BPM) alongside energy and spectral brightness
8 Intelligent Templates:
- 💪 High Energy Workout - Energetic tracks to power through workouts
- 📚 Focus & Study - Calm, consistent tracks for concentration
- 🎧 Seamless DJ Mix - BPM and key-matched for smooth transitions
- ☀️ Gentle Wake Up - Gradually increasing energy
- 🎉 Party Mix - High energy, danceable tracks
- 😌 Chill Vibes - Relaxed, mellow atmosphere
- 🏃 Running Pace - Consistent tempo for running (150-180 BPM)
- 😴 Sleep & Relaxation - Descending energy for winding down
Analysis Caching: Save analysis results to memory for instant playlist generation
Enhanced Visualizer Integration: Mood analysis influences visualizer colors and effects
Detailed Stats: Track count, duration, average BPM, energy levels, mood distribution
Playlist Preview: Review generated playlist before loading
One-Click Loading: Load smart playlist directly to player

🎚️ Advanced Mixing Features

🆕 Crossfade Manager: Intelligent track transitions
- Configurable fade duration (1-10 seconds)
- BPM-aware crossfade timing
- Smart intro detection and skipping
- Key compatibility checking
- Dual audio system with preloading
- Smooth volume ramping
🆕 DJ Mode: Automatic playlist reordering
- BPM and key matching for seamless transitions
- Harmonic mixing using Camelot wheel
- Mood compatibility checking
- Energy flow optimization
- Danceability consistency
- Automatic mix generation
- Original playlist restoration

📱 Mobile Optimizations

Touch Gestures:
- Swipe right/left on cover art for previous/next track
- Pull-to-refresh on playlist to reload folder
- Long-press on tracks for context menu
Haptic Feedback: Physical button feel on all interactions (light, medium, heavy, success, error)
Responsive UI: Adapts perfectly to any screen size
PWA Support: Install as native app on iOS/Android
Status Bar Auto-Hide: Fullscreen experience on Android
Mobile Context Menu: Long-press for track options
Gesture Indicators: Visual hints for swipe gestures
Optimized Button Sizes: 48px minimum touch targets

🖥️ Chrome OS Features

Extension Mode: Runs as Chrome extension with dedicated window
PWA Mode: Installable web app with offline support
Folder Persistence: Remembers last used folder with auto-reload
Optimized Keyboard Shortcuts: Chrome OS-specific shortcuts
Hybrid Input Support: Optimized for touchscreen + keyboard usage
Platform Detection: Automatic Chrome OS feature detection

🎯 Advanced Features

Picture-in-Picture: Floating mini-player always on top (Chrome/Edge)
- Multi-strategy fallback system for maximum compatibility
- Main video, custom stream, and audio-only modes
- Automatic video cleanup and resource management
Sticky Mini Player: Keeps controls visible while scrolling
3 View Modes: Full, Compact, Mini for different workflows
Debug Console: Real-time logging for troubleshooting
Performance Manager: Adaptive frame rates based on visibility and mode
Color Extraction: Dominant color extraction from album art with caching (50-item LRU cache)
Drag & Drop: Drop audio/VTT files anywhere to load instantly
Error Recovery System: Automatic retry with exponential backoff
Custom Progress Bar: Click anywhere to seek, smooth scrubbing
Playlist Status: Real-time track count, loop mode, shuffle status
Volume Scroll: Mouse wheel control over volume slider
Keyboard Shortcuts: 15+ shortcuts for efficient control

🔧 System Features

Modular Architecture: Cleanly separated components for audio processing, UI management, and file handling.
UI Manager: Centralized UI interaction system with non-intrusive toast notifications.
Error Recovery System: Circuit breaker pattern and automatic retries with global error reporting.
Service Worker: Offline functionality with cache-first strategy.
GitHub Pages Support: Automatic base path detection and configuration.
Folder Handle Persistence: IndexedDB storage with permission verification.
Custom Metadata Storage: localStorage-based with size/name keys.
Analysis Cache: In-memory caching with localStorage backup.
Color Cache: LRU cache (50 items) for album art colors.
Playlist Persistence: localStorage with timestamp tracking.
Auto-Reload Preference: Remember folder auto-load setting.

🚀 Quick Start

🌐 Web Browser (Any Device)

Open index.html in any modern browser
Click "📂 Load Music & Lyrics"
Select your music files (+ optional .vtt lyric files)
Enjoy! 🎉

📁 Folder Mode (Desktop/Chrome OS)

Click "📁 Select Music Folder"
Grant permission when prompted
Auto-loads all music in folder
Next time: Automatically reloads last folder on startup

🔍 Deep Analysis Workflow

Open deep-music-analysis.html in browser
Select your music folder
Click "Analyze All Songs" (analyzes entire tracks)
Wait for processing (30-60s per song)
Download analysis files as ZIP
Extract .txt files to music folder
Load in main player - enhanced features activate!

📲 Progressive Web App (Mobile)

Android:

Chrome → Menu (⋮) → "Add to Home Screen"
Tap icon to launch fullscreen app

iOS:

Safari → Share → "Add to Home Screen"
Tap icon to launch

🔌 Chrome Extension (Chrome OS)

Chrome → chrome://extensions
Enable "Developer mode"
Click "Load unpacked"
Select project folder
Click extension icon to open

⌨️ Complete Keyboard Shortcuts

Key	Action
Space	Play/Pause
N	Next track
P	Previous track
M	Mute/Unmute
→	Skip forward 5s
←	Rewind 5s
C	Cycle view mode (Full → Compact → Mini)
S	Toggle sticky player
F	Picture-in-Picture
V	Fullscreen visualizer
D	Debug panel
O	Open folder picker
ESC	Close fullscreen modes

Chrome OS Exclusive:

Alt+M: Toggle mini player
Ctrl+Shift+L: Open folder picker

📖 Complete Usage Guide

🎵 Loading Music

Method 1: File Picker

Click "📂 Load Music & Lyrics"
→ Select files (Ctrl+Click for multiple)
→ Include .vtt files for lyrics
→ Include .txt analysis files for enhanced features
→ Player loads automatically

Method 2: Folder Picker (Desktop/Chrome OS only)

Click "📁 Select Music Folder"
→ Grant permission
→ All music auto-loads
→ Enable auto-reload to remember folder
→ Click "🗑️ Forget Folder" to reset

Method 3: Drag & Drop

Drag music files onto page
→ Drop anywhere
→ Instant load

🔍 Deep Analysis Workflow

Using the Analysis Tool:

Open deep-music-analysis.html
Select your music folder (MP3, M4A, FLAC, WAV, OGG)
Click "Analyze All Songs"
Wait for comprehensive analysis (entire track duration)
Download generated .txt files as ZIP
Extract ZIP to your music folder
Load music in main player

What Gets Analyzed:

Duration: Total track length
BPM: Tempo detection (40-200 BPM)
Key: Musical key detection
Tempo: Classification (slow/moderate/fast/very-fast)
Mood: Enhanced detection (energetic/calm/bright/dark/neutral)
Energy (LUFS): Professional loudness measurement
Danceability: Beat consistency and groove
Loudness: Perceptual loudness
Spectral Centroid: Brightness measurement
Vocal Prominence: Voice detection ratio
Dynamic Range: Crest factor in dB
Frequency Bands: 6-band analysis (sub-bass to brilliance)
Vintage Detection: Identifies old recordings

Benefits of Deep Analysis:

Enhanced visualizer with mood-based colors
BPM-synced visual effects
Accurate Auto-EQ preset selection
Better smart playlist generation
Mood indicators in playlist
DJ mode compatibility

🎤 Adding Lyrics

Manual Method:

Name your VTT file to match audio:

Song.mp3
Song.vtt  ← Must match exactly!

VTT Format:

WEBVTT

00:00:00.000 --> 00:00:05.000
First line of lyrics

00:00:05.000 --> 00:00:10.000
Second line of lyrics

Load together with music files

🆕 Automatic Method (Lyrics Fetcher):

Open lyrics-fetcher.html in your browser
Click "📁 Select Music Folder"
Choose your music folder
Click "🎤 Fetch Lyrics for All Songs"
Wait for automatic processing (uses LRCLIB API)
Download generated VTT files as ZIP
Extract ZIP and place VTT files in your music folder
Reload music player - lyrics appear automatically!

🎛️ Using the Equalizer

Quick Presets:

Click dropdown → Select preset
Instant apply (saved automatically)

Manual Adjustment:

Drag vertical sliders
Bass: Low frequencies (drums, bass)
Mid: Vocals, guitars
Treble: High frequencies (cymbals, hi-hats)
Reset: Click "Reset" button

🆕 Auto-EQ Mode:

Click "🎛️ Auto-EQ" button to enable
Player automatically selects optimal preset per track
Based on genre tags and audio analysis
Respects vintage recordings (uses flat or gentle presets)
Adapts to speech content (uses podcast preset)
35% confidence threshold for activation

✏️ Editing Metadata

Hover over track in playlist
Click ✏️ (edit button)
Modify title, artist, album, year, genre, composer, comments
Preview changes in real-time
Click "💾 Save Changes"
Changes persist across sessions via localStorage
Custom metadata stored by filename + size

🧠 Smart Playlists

Click "🧠 Smart Playlists" button
Analyze your music library (one-time process)
Wait for enhanced mood detection with tempo analysis
Choose a playlist template:
- Workout, Study, DJ Mix, Wake Up, Party, Chill, Running, Sleep
Review generated playlist with detailed stats
Load to main player with one click
Enhanced: Visualizer adapts to playlist mood

🆕 Benefits of Smart Playlists:

Mood-based visualizer colors
BPM-synced effects
Energy-modulated animations
Perfect for different activities
Saves analysis cache for future use

🎚️ Crossfade & DJ Mode

Crossfade:

Click "🎚️ Crossfade" to enable
Tracks blend smoothly (2-5 seconds)
BPM-aware start points
Skips quiet intros on high-energy tracks
Adjustable duration (1-10 seconds)

DJ Mode:

Click "🎧 DJ Mode" to enable
Playlist automatically reordered for seamless mixing
BPM and key matching
Harmonic mixing (Camelot wheel)
Mood compatibility
Click again to restore original order

🖼️ Custom Background

Click "🎨 Background"
Choose:
- "📤 Upload Image" → Select file (under 5MB)
- "🌐 Use Image URL" → Paste link
Preview before applying
Reset anytime to default gradient

🌌 Fullscreen Visualizer

Click "🌌 Fullscreen Visualizer" (or press V)
🆕 Enhanced Features:
- Mood-based color schemes (red=energetic, blue=calm, etc.)
- BPM-synced pulses
- Energy-modulated animation speed
Switch modes: Bars / Circular / Waveform / Particles
Controls:
- Auto-hide after 3 seconds
- Move mouse to reveal
- 👁️ button to force hide/show
Navigate: Previous/Next/Play/Pause
Close: ✕ button or press ESC

🎤 Fullscreen Lyrics

Click "🎤 Fullscreen Lyrics"
Features:
- Edge-based visualizer effects
- Auto-scroll to current line
- Click any line to jump
Navigate: Previous/Next buttons at bottom
Close: ✕ button or press ESC

🎨 View Modes

Full View (Default)

All features visible
Visualizer, EQ, lyrics, playlist
Best for desktop

Compact Mode

Hides visualizer, EQ, lyrics
Shows player essentials + playlist
Good for multitasking

Mini Mode

Minimal: Now playing + progress bar only
Maximum space savings
Perfect for background music

Toggle: Click "📐 Full View" button or press C

📌 Sticky Player

Enable sticky mode:

Click "📌 Sticky Off"
Player sticks to bottom of window
Stays visible while scrolling
Perfect with mini mode
Press S to toggle

Use case: Browse playlist while controlling playback

🔧 Advanced Features

Picture-in-Picture (Desktop)

Click "📺 Float"
Creates draggable mini window
Always on top of other windows
Shows track info and visualizer
Multi-strategy fallback system for maximum compatibility:
- Primary: Uses main video element
- Fallback 1: Creates custom video stream
- Fallback 2: Minimal audio-only approach
Automatic resource cleanup
Works on Chrome, Edge, and Chrome OS

Debug Mode

Press D or click "🛠 Debug"
Shows real-time console logs
Displays metadata extraction info
Analysis status and errors
Helpful for troubleshooting

Performance Optimization

Adaptive Frame Rates: Adjusts based on visibility
Tab Hidden: Reduces CPU usage when tab not visible
Compact/Mini Mode: Disables visualizer to save resources
Smart Caching: Color extraction, analysis results, metadata
Canvas Performance: Optimized drawing algorithms

🎨 Enhanced Visualizer Integration

New: Mood-based visual effects!

Energetic tracks: Red/orange color scheme with strong pulses
Calm tracks: Blue color scheme with gentle waves
Bright tracks: Yellow/gold colors with sparkles
Dark tracks: Purple/indigo colors with deep effects
Neutral: Default red scheme

How it works:

Track is analyzed for mood (energy + BPM + brightness)
Mood classification influences visualizer colors
BPM affects pulse speed and animation intensity
Energy level controls visualizer sensitivity
Real-time synchronization with music analysis

📱 Complete Mobile Gestures

Gesture	Action
Swipe Right on cover art	Previous track
Swipe Left on cover art	Next track
Pull Down on playlist	Refresh folder
Long Press on track	Context menu (Play Now / Add to Queue / Show Info)
Tap lyric line	Jump to that time

Haptic Feedback Types:

Light: Play/pause, volume changes
Medium: Track changes
Heavy: Long press detection
Success: Playlist loaded
Error: Operation failed

🎯 Tips & Tricks

🎵 Best Audio Quality

Use FLAC or high-bitrate MP3 (320kbps)
Enable Auto-EQ for intelligent preset selection
Use Bass Boost preset for EDM/Electronic
Use Vocal preset for podcasts
Use Classical preset for orchestral music

🎤 Perfect Lyrics

Use the Lyrics Fetcher tool for bulk downloads
Manual VTT files: Match filename exactly with audio
Create VTT files with proper timestamps (HH:MM:SS.mmm)
Example: Song.mp3 needs Song.vtt (exact match)
Any filename difference prevents VTT matching

🔍 Deep Analysis Benefits

Always run deep analysis for best experience
Enhanced visualizer with mood colors
BPM-synced effects
Accurate Auto-EQ
Better smart playlists
Clear analysis cache (musicAnalysisCache in localStorage) after updates

🧠 Smart Playlists

Improved Mood Detection: Uses tempo + energy + brightness
Analyze your library once, reuse forever
Save analysis cache for instant generation
Try different templates for same music
DJ Mode works best with analyzed tracks

🎚️ Crossfade & DJ Mode

Enable both for ultimate DJ experience
DJ Mode auto-disables shuffle (incompatible)
Crossfade respects track intros and BPM
Works best with similar genres
DJ Mode uses Camelot wheel for harmonic mixing

⚡ Performance

Use Compact or Mini mode if visualizer lags
Close unused browser tabs
Disable visualizer in settings for maximum battery life
Smart Playlists: Analyze in batches if you have 100+ tracks
Deep analysis: Process overnight for large libraries

💾 Storage

Browser cache: ~50 tracks (color cache)
Folder mode: Unlimited (direct file access)
Playlists persist in localStorage
Custom metadata stored separately by file
Analysis cache in memory + localStorage backup
IndexedDB for folder handles

🔒 Privacy

All processing happens locally on your device
No data sent to servers (except LRCLIB for lyrics)
Music files never leave your device
No tracking, no analytics, no ads
Analysis files stay local

🌐 Browser Support

Browser	Desktop	Mobile	Features
Chrome	✅ Full	✅ Full	All features including PiP, folder access
Edge	✅ Full	✅ Full	All features including PiP, folder access
Firefox	✅ Most	✅ Most	No folder picker, PiP support varies
Safari	⚠️ Limited	⚠️ Limited	No folder picker, no PiP, basic features only

Recommended: Chrome 86+ or Edge 86+ for best experience

Minimum Requirements:

ES6+ JavaScript support
Web Audio API
Canvas API
FileReader API
LocalStorage API
Media Session API (for background playback)

📂 Complete Project Structure

├── index.html                          # Main app HTML
├── style.css                           # All styling
├── script.js                           # Main app logic (2000+ lines)
│
├── Core Audio:
├── audio-presets-manager.js            # 10 EQ presets with professional curves
├── visualizer-manager.js               # 4-mode visualizer (enhanced with mood)
├── performance-manager.js              # Adaptive frame rates
│
├── Metadata & Parsing:
├── metadata-parser.js                  # Multi-format ID3 reader (MP3/M4A/FLAC/OGG/WAV/AAC/WMA)
├── vtt-parser.js                       # Lyrics parsing with validation
├── metadata-editor.js                  # Custom metadata editing UI
├── analysis-text-parser.js             # Deep analysis .txt file parser
│
├── Smart Features:
├── music-analyzer.js                   # BPM, energy, mood, key detection
├── smart-playlist-generator.js         # 8 AI playlist templates
├── auto-eq-manager.js                  # Intelligent EQ preset selection
├── crossfade-manager.js                # Seamless track transitions
├── dj-mode-manager.js                  # Automatic playlist reordering
│
├── UI & UX:
├── custom-background.js                # Background image manager
├── mobile.js                           # Touch gestures + haptics
├── error-recovery.js                   # Exponential backoff retry
├── config-constants.js                 # App configuration
│
├── Platform Support:
├── chromeOS-detector.js                # Platform detection
├── background.js                       # Chrome extension service worker
├── background-audio-handler.js         # Media Session API + wake locks
├── gh-pages-config.js                  # GitHub Pages base path
├── sw-init.js                          # Service worker initialization
├── service-worker.js                   # PWA offline support
│
├── Standalone Tools:
├── lyrics-fetcher.html                 # Bulk lyrics downloader (LRCLIB API)
├── deep-music-analysis.html            # Comprehensive track analyzer
├── smart-playlist-ui.html              # Smart playlist demo/tester
│
├── PWA Assets:
├── manifest.webmanifest                # PWA manifest
├── icon-192.png                        # App icon (192x192)
├── icon-512.png                        # App icon (512x512)
│
└── Widget Support (Android 12+):
    ├── widget-minimal.html             # Minimal widget
    ├── widget-full.html                # Full widget with album art
    ├── widget-data-*.json              # Widget data templates
    └── widget-adaptive-cards.json      # Adaptive card templates

Total Lines of Code: ~15,000+ JavaScript Files: 25+ Features: 100+

🆕 What's New in Latest Version

Enhanced Mood Detection & Visualizer Integration

🎨 Enhanced Mood Detection: Analyzes tempo (BPM) + energy + spectral brightness
🎨 5 Accurate Mood Classifications: Energetic, Calm, Bright, Dark, Neutral
🎨 Mood-Based Visualizer Colors: Real-time color adaptation
🎨 BPM-Synced Visual Effects: Pulses sync with detected BPM
🎨 Energy-Modulated Animations: Intensity scales with track energy
🎨 Album Art Color Integration: Uses dominant colors when available

Deep Analysis Tool

🔍 Comprehensive Track Analysis: Analyzes entire track duration
🔍 Professional Metrics: LUFS energy, crest factor, frequency bands
🔍 Batch Processing: Analyze entire music library
🔍 Export System: Download all analysis as .txt files (ZIP)
🔍 Integration: Load .txt files for enhanced player features

Auto-EQ System

🎛️ Intelligent Preset Selection: Context-aware scoring system
🎛️ Genre Recognition: Automatic genre-based presets
🎛️ Vintage Detection: Special handling for old recordings
🎛️ Speech Detection: Podcast preset for speech content
🎛️ 35% Confidence Threshold: Only applies when confident

Crossfade & DJ Mode

🎚️ Seamless Transitions: BPM-aware crossfading
🎚️ Smart Intro Skipping: Detects and skips quiet intros
🎧 Harmonic Mixing: Camelot wheel key matching
🎧 Automatic Reordering: Intelligent playlist sequencing
🎧 Mood Compatibility: Smooth emotional transitions

Enhanced Mobile Experience

📱 Pull-to-Refresh: Reload folder with gesture
📱 Haptic Feedback: 6 types (light, medium, heavy, success, error, warning)
📱 Context Menu: Long-press for track options
📱 Gesture Indicators: Visual swipe hints

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create feature branch (git checkout -b feature/AmazingFeature)
Test thoroughly across browsers
Commit changes (git commit -m 'Add AmazingFeature')
Push to branch (git push origin feature/AmazingFeature)
Submit pull request

Areas for Contribution:

Additional visualizer modes
More EQ presets and Auto-EQ improvements
Smart playlist templates
Mobile gesture improvements
Browser compatibility fixes
Performance optimizations
Translation/localization
Better analysis algorithms
Machine learning integration

📄 License

MIT License - See LICENSE file

This means you can:

✅ Use commercially
✅ Modify freely
✅ Distribute
✅ Use privately

🙏 Credits

Libraries Used:

jsmediatags - Metadata tag reading
JSZip - ZIP file generation (lyrics fetcher)

APIs Used:

LRCLIB - Synced lyrics database (free, no API key required)

Inspiration: Built with ❤️ for music lovers who want complete control over their listening experience without cloud dependencies or subscriptions.

📞 Support

Found a bug? Have a feature request?

📧 Email: pieredino@gmail.com

Common Issues:

No sound: Check browser audio permissions
Folder not loading: Grant filesystem permissions
Lyrics not showing: Ensure VTT filename matches audio exactly
PiP not working: Use Chrome/Edge, try refreshing page
Slow performance: Try Compact/Mini mode
🆕 Mood detection issues: Clear analysis cache (musicAnalysisCache in localStorage) after updates

🔮 Roadmap

Planned Features:

Playlist import/export (M3U, PLS)
Audio effects (reverb, echo, etc.)
Podcast support with chapters
Radio streaming support
Wrapped-Like Listening Reports
More smart playlist templates
Advanced mood detection with machine learning
Custom visualizer color themes
Crossfade between tracks

⭐ Show Your Support

If you like this project:

⭐ Star this repository
🍴 Fork and customize
📢 Share with friends
💖 Contribute improvements

"Impossible is a social construct. Anything is possible if you don't know it shouldn't be."

Enjoy your music! 🎵🎧🎶

Built for offline freedom. Enhanced with intelligence. Powered by the web.

Name		Name	Last commit message	Last commit date
Latest commit History 83 Commits
LICENSE		LICENSE
README.md		README.md
STEP_2_CHANGELOG.md		STEP_2_CHANGELOG.md
analysis-text-parser.js		analysis-text-parser.js
audio-buffer-manager.js		audio-buffer-manager.js
audio-pipeline.js		audio-pipeline.js
audio-presets-manager.js		audio-presets-manager.js
auto-eq-manager.js		auto-eq-manager.js
background-audio-handler.js		background-audio-handler.js
background.js		background.js
background_audio_handler.js		background_audio_handler.js
chromeOS-detector.js		chromeOS-detector.js
config-constants.js		config-constants.js
crossfade-manager.js		crossfade-manager.js
custom-background.js		custom-background.js
custom-metadata-store.js		custom-metadata-store.js
deep-music-analysis.html		deep-music-analysis.html
error-recovery.js		error-recovery.js
file-loading-manager.js		file-loading-manager.js
folder-persistence.js		folder-persistence.js
fullscreen-helper.js		fullscreen-helper.js
gh-pages-config.js		gh-pages-config.js
icon-192.png		icon-192.png
icon-512.png		icon-512.png
image-optimizer.js		image-optimizer.js
index.html		index.html
lyrics-fetcher.html		lyrics-fetcher.html
lyrics-manager.js		lyrics-manager.js
lyrics-worker.js		lyrics-worker.js
manifest.json		manifest.json
manifest.webmanifest		manifest.webmanifest
metadata-editor.js		metadata-editor.js
metadata-parser.js		metadata-parser.js
mobile.js		mobile.js
music-analyzer.js		music-analyzer.js
optimization_plan.md		optimization_plan.md
performance-manager.js		performance-manager.js
playlist-renderer.js		playlist-renderer.js
script.js		script.js
service-worker.js		service-worker.js
style.css		style.css
sw-init.js		sw-init.js
true-metadata-editor.html		true-metadata-editor.html
ui-manager.js		ui-manager.js
visualizer-manager.js		visualizer-manager.js
visualizer-ui-controller.js		visualizer-ui-controller.js
volume-control.js		volume-control.js
vtt-parser.js		vtt-parser.js
web-audio-data-bridge.html		web-audio-data-bridge.html
widget-adaptive-cards.json		widget-adaptive-cards.json
widget-config.json		widget-config.json
widget-data-full.json		widget-data-full.json
widget-full.html		widget-full.html
widget-minimal-data.json		widget-minimal-data.json
widget-minimal.html		widget-minimal.html
widget-now-playing.html		widget-now-playing.html
worker-manager.js		worker-manager.js

Folders and files

Latest commit

History

Repository files navigation

🎵 Ultimate Local Music Player

🌟 Complete Features Overview

🎼 Core Playback

🎨 Visual Experience

🎤 Lyrics System

🎛️ Audio Controls

🧠 Advanced Analysis & Intelligence

✏️ Metadata System

🧠 Smart Playlist Generator

🎚️ Advanced Mixing Features

📱 Mobile Optimizations

🖥️ Chrome OS Features

🎯 Advanced Features

🔧 System Features

🚀 Quick Start

🌐 Web Browser (Any Device)

📁 Folder Mode (Desktop/Chrome OS)

🔍 Deep Analysis Workflow

📲 Progressive Web App (Mobile)

🔌 Chrome Extension (Chrome OS)

⌨️ Complete Keyboard Shortcuts

📖 Complete Usage Guide

🎵 Loading Music

🔍 Deep Analysis Workflow

🎤 Adding Lyrics

Manual Method:

🆕 Automatic Method (Lyrics Fetcher):

🎛️ Using the Equalizer

✏️ Editing Metadata

🧠 Smart Playlists

🎚️ Crossfade & DJ Mode

🖼️ Custom Background

🌌 Fullscreen Visualizer

🎤 Fullscreen Lyrics

🎨 View Modes

Full View (Default)

Compact Mode

Mini Mode

📌 Sticky Player

🔧 Advanced Features

Picture-in-Picture (Desktop)

Debug Mode

Performance Optimization

🎨 Enhanced Visualizer Integration

📱 Complete Mobile Gestures

🎯 Tips & Tricks

🎵 Best Audio Quality

🎤 Perfect Lyrics

🔍 Deep Analysis Benefits

🧠 Smart Playlists

🎚️ Crossfade & DJ Mode

⚡ Performance

💾 Storage

🔒 Privacy

🌐 Browser Support

📂 Complete Project Structure

🆕 What's New in Latest Version

Enhanced Mood Detection & Visualizer Integration

Deep Analysis Tool

Auto-EQ System

Crossfade & DJ Mode

Enhanced Mobile Experience

🤝 Contributing

📄 License

🙏 Credits

📞 Support

🔮 Roadmap

⭐ Show Your Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Packages