A Chrome extension that adds a random song picker functionality to Songsterr.com, allowing users to play a random song from their favorites list with enhanced performance and user experience.
- One-click random song selection from your favorites
- Keyboard shortcut support (default: "=" key, fully customizable)
- Smart UI integration - Seamlessly adds a "Random" button to Songsterr's toolbar
- Debug mode for troubleshooting
- ⚡ Lightning-fast caching - Second click within 1 minute is instant (60-second cache)
- 🔄 Loading feedback - Visual notification while fetching favorites
- ✨ Smooth animations - Polished UI with slide-down/up transitions
- 📊 Performance boost - Up to 60x fewer API calls for active users
- 🎲 No repeats - Tracks last 10 songs to avoid playing the same song twice in a row
- ⚡ Force refresh - Press Shift+key to clear cache and history instantly
- 🧹 Manual cache control - Clear cache & history button in options panel
- 🔍 Dynamic detection - MutationObserver ensures button appears even on SPA navigation
- Dismissible notifications - Color-coded feedback (loading, success, error)
- Adaptive UI - Multiple fallback strategies for Songsterr's dynamic layout
- Settings persistence - Preferences sync across devices via Chrome sync storage
- Real-time updates - Settings changes apply immediately across all tabs
Status: ✅ Submitted on January 6, 2026 - Pending Chrome Web Store review
The extension will be available for one-click installation once approved.
- Download or clone this repository
- Run
npm installto install dependencies - Run
npm run buildto build the extension - Open Chrome and navigate to
chrome://extensions - Enable "Developer mode" (toggle in top-right)
- Click "Load unpacked" and select the
distdirectory - The extension icon should appear in your Chrome toolbar
- Navigate to Songsterr.com and log in
- Add songs to your favorites (if you haven't already)
- Click the Random button in Songsterr's toolbar, or
- Press the keyboard shortcut (default: "=" key)
- Enjoy! A random song from your favorites will load
=(or custom key): Play random song (uses cache, avoids recent repeats)Shift + =: Force refresh - clears cache & history, fetches fresh favorites
- Click the extension icon in Chrome toolbar
- Customize keyboard shortcut if desired
- Enable debug mode to see performance logs (optional)
- Cache optimization: Click Random multiple times within 1 minute to experience instant loading
- Variety: Extension automatically avoids repeating the last 10 songs
- Force refresh: Use Shift+key when you've added new favorites
- Manual control: Use "Clear Cache & History" button in options panel
- Debug mode: Enable to see cache hits/misses and performance metrics in console
- Node.js (v14+ recommended)
- npm (comes with Node.js)
- Chrome browser
- Clone the repository
git clone https://github.com/AdarBahar/Songsterr-randomPlay.git
cd Songsterr-randomPlay- Install dependencies
npm install- Build the extension
npm run buildThe built extension will be in the dist directory.
- Make changes to source files (
content.js,popup.js, etc.) - Run
npm run buildto rebuild - Go to
chrome://extensionsand click refresh icon on the extension - Reload any Songsterr tabs to see changes
See TESTING_GUIDE.md for comprehensive testing instructions.
Quick test checklist:
- Random button appears on Songsterr toolbar
- Keyboard shortcut works
- Loading notification appears
- Second click within 1 minute is instant (cache working)
- Options panel animates smoothly
- No console errors
# Build for production (minified)
npm run build
# Create distribution ZIP
npm run zip
# Full compile (build + zip)
npm run compile- Directory:
dist/ - Contents: All extension files (minified and optimized)
- Size: ~50KB total
-
Build the extension:
npm run build
-
Create the ZIP file:
cd dist zip -r ../RandomFavoritePicker.zip . -x '*.DS_Store' cd ..
-
Submit to Chrome Web Store:
- Go to Chrome Web Store Developer Dashboard
- Upload
RandomFavoritePicker.zip - Fill in store listing details
- Submit for review
See deployment.md for detailed deployment instructions.
- 🎨 Popup UI refinements - Removed guitar icon, cleaner header
- 🐛 Fixed scrollbar issues - Proper height constraints for Chrome's limits
- 📏 Restored font sizes - Better readability after over-compression
- 📜 Scrollable settings - Settings panel scrolls smoothly when expanded
- 🏪 Chrome Web Store ready - Screenshots, privacy policy, metadata finalized
- ✅ Submitted - Extension submitted to Chrome Web Store on Jan 6, 2026
- 🎯 Constants extraction - All magic numbers moved to named constants
- 🎲 Song history tracking - Avoids repeating last 10 songs for better variety
- ⚡ Modifier key support - Shift+key for force refresh (clears cache & history)
- 🧹 Cache clear button - Manual control in options panel
- 🔍 MutationObserver - Dynamic toolbar detection for SPAs
- 📦 Modular functions - Better code organization and maintainability
- ⚡ Added favorites caching (60-second TTL) for instant repeat clicks
- 🔄 Added loading notification with visual feedback
- ✨ Added smooth animations for options panel
- 📚 Added comprehensive JSDoc documentation
- 🧹 Code cleanup and refactoring
- 🐛 Fixed keyboard shortcut triggering in input fields
- 🐛 Fixed error notifications not appearing
- 🐛 Fixed tooltip not updating dynamically
- 🐛 Fixed modifier keys triggering shortcut
- 🎉 First public release
- ✅ Core functionality: random song selection
- ✅ Keyboard shortcut support
- ✅ Settings panel with customization
- Every click: ~300ms (API call)
- No visual feedback
- No caching
- Possible immediate repeats
- First click: ~300ms (API call) + loading notification
- Subsequent clicks (within 1 min): <10ms (cached) ⚡
- 60x reduction in API calls for active users
- No repeats in last 10 songs (better variety)
- Smooth animations and visual feedback
- Force refresh option (Shift+key)
- Manifest V3 Chrome Extension
- Vanilla JavaScript (no frameworks)
- Webpack for bundling and minification
- Chrome Sync Storage for settings persistence
- Content Scripts for DOM manipulation
- Service Worker for background tasks
- Chrome Extension APIs (storage, runtime, messaging)
- Songsterr API integration
- Constants-based configuration (v1.4+) - All magic numbers extracted
- Comprehensive JSDoc documentation - All functions documented
- Early return patterns for readability
- Single responsibility functions - Modular design
- Proper error handling with try-catch-finally
- MutationObserver for dynamic content (v1.4+)
See project_context.md for detailed architecture documentation.
- Check if you're on songsterr.com
- Enable debug mode and check console
- Keyboard shortcut still works as fallback
- Verify you're logged into Songsterr
- Check if you have favorites added
- Enable debug mode to see error messages
- Enable debug mode
- Check console for "Using cached favorites" message
- Verify you're clicking within 60 seconds
- Try "Clear Cache & History" button in options panel
- Extension tracks last 10 songs to avoid repeats
- If you have fewer than 10 favorites, some repeats are inevitable
- Use Shift+key to force refresh and clear history
- See TESTING_GUIDE.md for detailed testing scenarios
- Check console with debug mode enabled
- Open an issue on GitHub
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Test thoroughly (see TESTING_GUIDE.md)
- Submit a pull request
- ✅ Extract magic numbers to constants
- ✅ Add song history tracking (avoid repeats)
- ✅ Support modifier keys (Shift+key for force refresh)
- ✅ Use MutationObserver for dynamic toolbar detection
- ✅ Add cache clear button
- Migrate to TypeScript
- Add filters (artist, difficulty, instrument)
- Statistics dashboard
- Playlist mode (queue multiple random songs)
- Full test coverage
- Repository: https://github.com/AdarBahar/Songsterr-randomPlay
- Issues: https://github.com/AdarBahar/Songsterr-randomPlay/issues
- Songsterr: https://www.songsterr.com
This project is licensed under the MIT License - see the LICENSE file for details.
- Built for the Songsterr community
- Inspired by the need for spontaneous practice sessions
- Thanks to all contributors and testers
Made with ❤️ for guitarists, bassists, drummers, and musicians everywhere!