A fast, lightweight music player that creates instant random playlists from your music library. Built in Rust for maximum performance and reliability.
- 🎲 Instant Random Playlists - Generate 50 random songs in seconds
- ⚡ Lightning Fast - Optimized for huge music libraries (100GB+)
- 🔄 Smart Caching - First scan takes time, every launch after is instant
- 🎵 Multi-Format Support - MP3, FLAC, OGG, WAV, M4A, AAC
- 🖼️ Album Art Display - Beautiful album artwork when available
- 📊 Real-time Progress - Live progress bars and time tracking
- 💾 Remembers Everything - Your directory, preferences, and metadata
- 🎯 Zero Configuration - Just select your music folder and go
- Download the latest release
- Extract
music-shuffler-windows.zip - Run
music-shuffler.exe - Select your music directory
- Click "Generate Playlist"
- Enjoy your music! 🎶
┌─────────────────────────────────────────────────────────────┐
│ 🎵 Music Shuffler │
├────────────────────────────────────────────────────────────┤
│ Select a music directory to get started │
│ │
│ [Select Directory] [Generate Playlist] │
├────────────────────────────────────────────────────────────┤
│ Playlist │ Now Playing │
│ │ │
│ ♪ Bohemian Rhapsody │ [Album Art] │
│ Hotel California │ │
│ Stairway to Heaven │ Bohemian Rhapsody │
│ Sweet Child O' Mine │ Queen │
│ Free Bird │ A Night at the Opera │
│ ... (45 more songs) │ │
│ │ ████████░░░░ 2:34 / 5:55 │
│ │ ⏮ ⏸ ⏭ │
└─────────────────────────────────────────────────────────────┘
- OS: Windows 10 or later (64-bit)
- RAM: 100MB (scales with library size)
- Storage: 25MB + cache space
- Audio: Any Windows-compatible audio device
| Library Size | First Scan | Subsequent Launches | Playlist Generation |
|---|---|---|---|
| 1GB (500 songs) | 5-10 seconds | 0.1 seconds | 0.1 seconds |
| 10GB (5,000 songs) | 15-30 seconds | 0.2 seconds | 0.2 seconds |
| 100GB (50,000 songs) | 30-60 seconds | 0.5 seconds | 0.3 seconds |
Performance scales beautifully thanks to intelligent caching and parallel processing.
| Format | Metadata | Album Art | Playback Quality |
|---|---|---|---|
| MP3 | ✅ Full | ✅ Yes | High |
| FLAC | ✅ Full | ✅ Yes | Lossless |
| OGG | ✅ Full | ✅ Yes | High |
| WAV | ❌ No | Lossless | |
| M4A | ✅ Full | ✅ Yes | High |
| AAC | ✅ Full | High |
- Parallel Discovery - Uses all CPU cores to find music files
- Smart Filtering - Only processes actual music files
- Metadata Extraction - Reads title, artist, album, and duration
- Cache Building - Saves everything for instant future access
- File List Cache - Remembers all discovered music files
- Metadata Cache - Stores extracted song information
- Change Detection - Only re-processes modified files
- Cross-Session - Cache persists between app launches
- Rust-Native - Built with the Rodio audio library
- Low Latency - Minimal delay between track changes
- Robust Decoding - Handles various encoding qualities
- Error Recovery - Gracefully skips corrupted files
No sound when playing:
- Install Visual C++ Redistributables
- Check Windows audio drivers
- Try different audio formats
- Restart Windows Audio service
"Device not available" error:
- Close other audio applications
- Check default audio device in Windows
- Try running as Administrator (once)
"Invalid main_data offset" error:
Error playing track 'Song Name': mpa: invalid main_data offset
This file may be corrupted. Try re-encoding or replacing it.
Solutions:
- Re-encode with modern tools (VLC, Audacity, FFmpeg)
- Download from reputable sources
- Check file integrity
Slow first scan:
- Normal for large libraries (builds cache for future speed)
- Monitor console output for progress
- Close other applications during first scan
High memory usage:
- Expected with very large libraries (50GB+)
- Memory usage scales with library size
- Consider splitting huge libraries
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Clone repository
git clone https://github.com/W5DEV/music-shuffler.git
cd music-shuffler# Build for current platform
cargo build --release
# Run locally
cargo run# One-time setup
./scripts/build-windows.sh- Automatic builds on every push
- Windows executables available in Actions artifacts
- Release builds triggered by tags
We welcome contributions! Here's how to help:
- 🐛 Bug Reports - Open an issue with details
- 💡 Feature Requests - Suggest improvements
- 🔧 Code Contributions - Submit pull requests
- 📖 Documentation - Improve guides and docs
- 🧪 Testing - Test on different systems
git clone https://github.com/W5DEV/music-shuffler.git
cd music-shuffler
cargo run┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ GUI (eGUI) │ │ Audio (Rodio) │ │ Files (WalkDir) │
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
│ • Playlist UI │ │ • MP3/FLAC/OGG │ │ • Parallel Scan │
│ • Progress Bar │ │ • Real-time │ │ • Smart Filter │
│ • Controls │ │ • Low Latency │ │ • Recursive │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ Metadata Cache │
├─────────────────┤
│ • JSON Storage │
│ • Change Track │
│ • Fast Lookup │
└─────────────────┘
- Winamp/VLC: More features, but complex setup
- Spotify: Streaming, but requires internet/subscription
- Windows Media Player: Built-in, but slow and dated
- Music Shuffler: Simple, fast, offline, just works
- 🏠 Local Music Libraries - Your own MP3/FLAC collection
- 🎲 Discovery - Rediscover forgotten songs in huge libraries
- ⚡ Speed - When you want music NOW, not after setup
- 🔒 Privacy - No tracking, no internet required
- 💻 Low Resource - Minimal impact on system performance
This project is licensed under the MIT License - see the LICENSE file for details.
- Rust Community - For amazing crates and ecosystem
- eGUI - For the beautiful, immediate-mode GUI framework
- Rodio - For reliable cross-platform audio
- Contributors - Everyone who helped improve this project
Made with ❤️ and Rust
Music Shuffler: Because sometimes you just want to press play and discover great music. 🎵