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:

Install the script to ~/.local/bin/winamp-mpris.
Install and enable the systemd user service winamp-mpris.service.
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.

4.4 KiB Raw Blame History Unescape Escape