Spotify Queue Widget for KDE Plasma 6

A beautiful and feature-rich Plasma widget that displays your Spotify queue with enhanced auto-authentication and extended session persistence.

Features

✨ Enhanced Authentication

• 🔗 Automatic code extraction from redirect URLs
• 💾 Extended session persistence
• 🔄 Proactive token refresh to maintain longer sessions
• 🛡️ State parameter verification for enhanced security

🎵 Queue Management

• 📋 View your entire Spotify queue (up to 50 tracks)
• 🔄 Auto-refresh every 15 seconds
• ⚡ Real-time queue updates
• 🎨 Modern, beautiful UI with Spotify's signature green color

🔒 Security & Privacy

• Tokens stored securely in KDE's configuration system
• OAuth 2.0 authentication with CSRF protection
• No third-party services or data collection

Screenshots

Requirements

• KDE Plasma 6 (or Plasma 5.27+)
• Spotify account (Premium required for queue access)
• Spotify Developer App credentials (Client ID and Secret)

Installation

Automatic Installation (Recommended)

1. Clone or download this repository:

   git clone https://github.com/Raindancer118/plasma-spotify-queue.git
   cd plasma-spotify-queue

2. Run the installation script:

   ./install.sh

The script will:

• Detect your Linux distribution automatically
• Install required dependencies (optional)
• Install the widget to your user directory
• Restart Plasma Shell (optional)

Supported Distributions

The install script supports all major Linux distributions:

• Debian/Ubuntu (Ubuntu, Linux Mint, Pop!_OS, Elementary OS, etc.)
• Fedora/RHEL (Fedora, CentOS, RHEL, etc.)
• Arch Linux (Arch, Manjaro, EndeavourOS, Garuda, etc.)
• openSUSE (openSUSE Leap, Tumbleweed, etc.)
• Other distributions with KDE Plasma 6

Manual Installation

If you prefer to install manually:

1. Copy the widget files to your local plasmoids directory:

   mkdir -p ~/.local/share/plasma/plasmoids/com.spotify.queue-working
   cp -r contents ~/.local/share/plasma/plasmoids/com.spotify.queue-working/
   cp metadata.json ~/.local/share/plasma/plasmoids/com.spotify.queue-working/

2. Restart Plasma Shell:

   plasmashell --replace

Setup

1. Create Spotify Developer App

1. Go to Spotify Developer Dashboard
2. Log in with your Spotify account
3. Click "Create an App"
4. Fill in the app details:
   • App Name: Any name you like (e.g., "Plasma Queue Widget")
   • App Description: Any description
   • Redirect URI: https://example.com/callback (important!)
5. Save the app and note your Client ID and Client Secret

2. Configure the Widget

1. Right-click on your desktop or panel
2. Select Add Widgets...
3. Search for "Spotify Queue"
4. Drag and drop it to your desktop or panel
5. Right-click the widget and select Configure Spotify Queue...
6. Enter your Client ID and Client Secret
7. Click Apply or OK

3. Authenticate with Spotify

1. Click the Get Code button in the widget
2. Your browser will open to Spotify's authorization page
3. Log in and authorize the app
4. After authorization, you'll be redirected to a page that shows an error (this is expected!)
5. Copy the entire URL from your browser's address bar
6. Paste the URL into the widget's text field
7. The widget will automatically extract the authorization code
8. Click Submit or press Enter

The widget will now display your Spotify queue! 🎉

Usage

Viewing Your Queue

Once authenticated, the widget will automatically:

• Display your current Spotify queue
• Show track names, artists, albums, and durations
• Auto-refresh every 15 seconds
• Maintain your session across restarts

Manual Refresh

Click the Refresh button at the top of the widget to manually update the queue.

Disconnect

Click the Disconnect button to clear your authentication and start over.

Troubleshooting

"module "QtGraphicalEffects" is not installed" Error

This error occurred in older versions of the widget. This has been fixed in version 6.2 and later. If you still see this error:

1. Update to the latest version
2. Run the install script again
3. Restart Plasma Shell

"Spotify Premium Required" Error

Queue access requires a Spotify Premium subscription. Free accounts cannot access the queue API.

Session Expires Too Quickly

The widget now includes proactive token refresh to maintain longer sessions. If you still experience issues:

1. Ensure you're using version 6.2 or later
2. Check that your Client ID and Secret are correct
3. Try disconnecting and reconnecting

Widget Not Appearing

1. Make sure you restarted Plasma Shell after installation
2. Try running: plasmashell --replace
3. Check the widget is installed: ls ~/.local/share/plasma/plasmoids/

Authorization Code Extraction Not Working

If automatic code extraction fails:

1. You can manually copy just the code part from the URL
2. Look for code= in the URL and copy everything after it (until the next &)
3. Paste just the code into the widget

Uninstallation

To remove the widget:

rm -rf ~/.local/share/plasma/plasmoids/com.spotify.queue-working
plasmashell --replace

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built for KDE Plasma 6
• Uses Spotify Web API
• Inspired by the need for a native Spotify queue viewer on Linux

Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check the Spotify API Documentation

Changelog

Version 6.2

• ✅ Fixed QtGraphicalEffects compatibility issue with Plasma 6
• 🎨 Removed decorative shadow effects for better compatibility
• 📦 Added automatic installation script
• 📖 Added comprehensive README

Version 6.1

• 🔗 Auto-extraction of authorization codes from URLs
• 🔄 Proactive token refresh for extended sessions
• 💾 Enhanced session persistence
• 🛡️ State parameter verification
• ⚡ Reduced re-authentication needs

---

Made with ❤️ for the KDE Community