Winamp MPRIS Bridge

A Python-based bridge that provides an MPRIS2 interface for Winamp/WACUP on Linux (running via Wine/Proton). This allows Linux desktop environments (like KDE Plasma, GNOME, or any MPRIS-compatible media widget) to control playback and display track metadata.

Features

• Metadata Extraction: Primarily uses the Winamp window title for high-fidelity metadata (Artist, Album, Title).
• Playback Controls: Supports Play, Pause, Next, Previous, and Stop via the Winamp Web Interface.
• Live Position Tracking: Extrapolates playback position for smooth progress bars in your desktop's media widget.
• Robustness: Gracefully handles Winamp being offline and automatically reconnects when it starts.
• Systemd Integration: Can be run as a background user service.

Prerequisites

1. Winamp Web Interface Plugin

The bridge communicates with Winamp through the Winamp Web Interface plugin.

• Download: Winamp Web Interface v7.5.10
• Installation: Install the plugin in Winamp/WACUP.
• Configuration:
  1. Open Winamp Preferences -> Plug-ins -> General Purpose.
  2. Configure "Winamp Web Interface".
  3. Set a Username (default: winamp) and Password (default: llama).
  4. Ensure the server is running (default port: 5666).

2. Winamp/WACUP Title Formatting

To ensure the bridge can extract correct metadata, you must configure Winamp to show specific information in its window title.

• Open Winamp Preferences -> Titles.
• Set the Taskbar/Window title format to:

  %artist%–%album%–%title% | %playback_time%/%length% - Winamp
  

  (Note: The separator between Artist, Album, and Title should be an en-dash – or a simple dash -).

3. Linux Dependencies

Install the required Python libraries, wmctrl, and libnotify (for notifications):

# Python dependencies
pip install requests pydbus beautifulsoup4 pygobject

# System tools
sudo dnf install wmctrl libnotify  # or sudo apt install wmctrl libnotify

Installation & Setup

1. Clone or copy the script to a local directory (e.g., ~/Scripts/winamp-mpris/).
2. Configure Credentials: If you changed the default username/password in the plugin, update the AUTH variable in winamp_mpris.py.

Running Manually

python3 winamp_mpris.py

Testing and Debugging

You can use busctl to interact with the MPRIS interface:

# Get playback status
busctl --user get-property org.mpris.MediaPlayer2.winamp /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player PlaybackStatus

# Get current position (in microseconds)
busctl --user get-property org.mpris.MediaPlayer2.winamp /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player Position

# Send commands
busctl --user call org.mpris.MediaPlayer2.winamp /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player PlayPause

Running as a systemd User Service

1. Install the service file:

   mkdir -p ~/.config/systemd/user/
   cp winamp-mpris.service ~/.config/systemd/user/
   

2. Reload and Enable:

   systemctl --user daemon-reload
   systemctl --user enable --now winamp-mpris.service
   

3. Monitor Logs:

   journalctl --user -u winamp-mpris.service -f
   

Technical Details

• D-Bus Bus: org.mpris.MediaPlayer2.winamp
• Object Path: /org/mpris/MediaPlayer2
• Polling Rate: 1 second (updates metadata from window title and checks Web UI for status).

Troubleshooting

• Controls not working: Ensure the Winamp Web Interface is accessible at http://localhost:5666 and the credentials in the script match your plugin settings.
• No Metadata: Ensure wmctrl -l can see the Winamp window and the title matches the expected format.
• KDE Plasma 6: If using Plasma 6 on Wayland, you may need to grant "Remote Control" permissions when prompted to allow wmctrl to read window titles accurately.