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 conforming to XDG standards.
• XDG Compliance: Installs to ~/.local/bin, logs to ~/.local/state/winamp-mpris/, and stores PID in $XDG_RUNTIME_DIR.

Prerequisites

1. Winamp / WACUP

The bridge is designed to work with both classic Winamp and WACUP (Winamp Community Update Project).

• Download WACUP: https://getwacup.org.uk/preview/
• Testing Environment: This bridge was primarily tested using WACUP installed via Bottles using the soda-9.0-1 runner.

2. Winamp Web Interface Plugin

The bridge communicates with Winamp through the Winamp Web Interface plugin (Wawi), originally written by Phil Himsworth (2001-2002).

• Download:
  • Primary: Use Wawi_7-5-13.exe included in this repository.
  • Secondary: Winamp Heritage (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).
  5. In the Users tab, ensure the user has Play permissions.

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

The project includes an XDG-compliant installer:

chmod +x install.sh
./install.sh

This will:

1. Install the script to ~/.local/bin/winamp-mpris.
2. Install and enable the systemd user service winamp-mpris.service.
3. Start the bridge immediately.

Logs and Monitoring

• Logs: tail -f ~/.local/state/winamp-mpris/bridge.log
• Systemd Logs: journalctl --user -u winamp-mpris.service -f
• PID File: $XDG_RUNTIME_DIR/winamp-mpris.pid

Testing with busctl

You can manually interact with the MPRIS interface:

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

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

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

• 401 Unauthorized: Ensure the Winamp Web Interface credentials match those in winamp-mpris and that the user has "Play" permissions in the plugin's Users tab.
• Controls not working: Ensure the Winamp Web Interface is accessible at http://localhost:5666.
• 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.

Demo