feat(mpris): handle TrackList D-Bus signals in the listener

Wire TrackListReplaced/TrackAdded/TrackRemoved/TrackMetadataChanged to
the cache mutators, resolving senders via findPlayerByUniqueName (the
safety net for the broad interface+path match rule). TrackListReplaced
refetches metadata in one GetTracksMetadata call, keeping IDs only on
failure.

PropertiesChanged on the TrackList interface updates CanEditTracks and
also covers players that never deliver usable TrackList signals: VLC
emits them under a mangled interface name (MediaPlayer2.TrackList,
missing the org.mpris prefix) the match rule can't see, and reports
queue changes as a Tracks value or a bare invalidation instead. A
changed value refreshes the cache directly, an invalidation refetches
the property first; comparing IDs against the cache before refreshing
keeps players that emit proper signals (mpd2mpris) from double-updating.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sathks1sgo6iJF16zpiewx

Author: b0bbywan

backend/mpris/dbus.go

@@ -124,6 +124,16 @@ func (m *MPRISBackend) getNameOwner(busName string) (string, error) {
 	return owner, nil
 }
 
+// arg extracts sig.Body[i] as T, false if absent or mistyped.
+func arg[T any](sig *dbus.Signal, i int) (T, bool) {
+	if i >= len(sig.Body) {
+		var zero T
+		return zero, false
+	}
+	v, ok := sig.Body[i].(T)
+	return v, ok
+}
+
 // Value extraction helpers from dbus.Variant
 // These helpers are used to extract values from variants received
 // in D-Bus signals without making additional D-Bus calls.

backend/mpris/listener.go

@@ -2,6 +2,7 @@ package mpris
 
 import (
 	"context"
+	"slices"
 	"strings"
 
 	"github.com/godbus/dbus/v5"
@@ -62,6 +63,11 @@ func (l *Listener) handleSignal(sig *dbus.Signal) {
 		l.handlePropertiesChanged(sig)
 	case DBUS_NAME_OWNER_CHANGED:
 		l.handleNameOwnerChanged(sig)
+	case MPRIS_SIGNAL_TRACKLIST_REPLACED, MPRIS_SIGNAL_TRACK_ADDED,
+		MPRIS_SIGNAL_TRACK_REMOVED, MPRIS_SIGNAL_TRACK_METADATA_CHANGED:
+		if busName := l.resolveSender(sig); busName != "" {
+			l.handleTrackListSignal(busName, sig)
+		}
 	default:
 		logger.Debug("[mpris] unhandled signal: %s", sig.Name)
 	}
@@ -73,17 +79,12 @@ func (l *Listener) handlePropertiesChanged(sig *dbus.Signal) {
 	// Body[1] = changed properties (map[string]Variant)
 	// Body[2] = invalidated properties ([]string)
 
-	if len(sig.Body) < 2 {
-		return
-	}
-
-	iface, ok := sig.Body[0].(string)
-	if !ok || iface != MPRIS_PLAYER_IFACE {
-		// We only care about Player changes
+	iface, ok := arg[string](sig, 0)
+	if !ok {
 		return
 	}
 
-	changed, ok := sig.Body[1].(map[string]dbus.Variant)
+	changed, ok := arg[map[string]dbus.Variant](sig, 1)
 	if !ok {
 		return
 	}
@@ -96,6 +97,31 @@ func (l *Listener) handlePropertiesChanged(sig *dbus.Signal) {
 		return
 	}
 
+	if iface == MPRIS_TRACKLIST_IFACE {
+		if v, ok := changed["CanEditTracks"]; ok {
+			if err := l.backend.UpdateCanEditTracks(busName, v); err != nil {
+				logger.Error("[mpris] failed to update CanEditTracks for %s: %v", busName, err)
+			}
+		}
+		// Some players (VLC) never emit usable TrackList signals (VLC mangles
+		// their interface name) and only report queue changes here — as a
+		// changed value or a bare invalidation. Skipping when the IDs match
+		// the cache keeps players that emit both from doubling up.
+		if v, ok := changed["Tracks"]; ok {
+			if ids, ok := v.Value().([]dbus.ObjectPath); ok && !l.backend.tracklistMatches(busName, ids) {
+				l.refreshTracklist(busName, ids)
+			}
+			return
+		}
+		if invalidated, ok := arg[[]string](sig, 2); ok && slices.Contains(invalidated, "Tracks") {
+			l.refetchTracklist(busName)
+		}
+		return
+	}
+	if iface != MPRIS_PLAYER_IFACE {
+		return
+	}
+
 	// Check if PlaybackStatus changed for deduplication
 	if statusVar, hasStatus := changed["PlaybackStatus"]; hasStatus {
 		if status, ok := extractString(statusVar); ok {
@@ -178,6 +204,124 @@ func (l *Listener) handleNameOwnerChanged(sig *dbus.Signal) {
 	}
 }
 
+// resolveSender maps a signal's unique-name sender to a cached busName.
+// Dropping unknown senders is the safety net for the broad interface+path
+// match rule, which delivers TrackList signals from any sender.
+func (l *Listener) resolveSender(sig *dbus.Signal) string {
+	busName := l.backend.findPlayerByUniqueName(sig.Sender)
+	if busName == "" {
+		logger.Debug("[mpris] dropping %s from unknown sender %s", sig.Name, sig.Sender)
+	}
+	return busName
+}
+
+// refreshTracklist replaces a player's cached tracklist from a list of IDs,
+// fetching their metadata in one call (IDs only on failure).
+func (l *Listener) refreshTracklist(busName string, ids []dbus.ObjectPath) {
+	tracks := tracksFromIDs(ids)
+	if len(ids) > 0 {
+		if metas, err := newPlayer(l.backend, busName).getTracksMetadata(ids); err == nil {
+			tracks = tracksFromMetadata(ids, metas)
+		} else {
+			logger.Debug("[mpris] GetTracksMetadata failed for %s, keeping IDs only: %v", busName, err)
+		}
+	}
+
+	if err := l.backend.ReplaceTracklist(busName, tracks); err != nil {
+		logger.Error("[mpris] failed to replace tracklist for %s: %v", busName, err)
+	}
+}
+
+// refetchTracklist re-reads the Tracks property after an invalidation
+// (no value in the signal) and refreshes the cache if it changed.
+func (l *Listener) refetchTracklist(busName string) {
+	v, err := l.backend.getProperty(busName, MPRIS_TRACKLIST_IFACE, "Tracks")
+	if err != nil {
+		logger.Debug("[mpris] failed to fetch Tracks for %s: %v", busName, err)
+		return
+	}
+	ids, ok := v.Value().([]dbus.ObjectPath)
+	if !ok {
+		return
+	}
+	if !l.backend.tracklistMatches(busName, ids) {
+		l.refreshTracklist(busName, ids)
+	}
+}
+
+// handleTrackListSignal dispatches TrackList signals once the sender is
+// resolved to a cached player.
+func (l *Listener) handleTrackListSignal(busName string, sig *dbus.Signal) {
+	switch sig.Name {
+	case MPRIS_SIGNAL_TRACKLIST_REPLACED:
+		l.handleTrackListReplaced(busName, sig)
+	case MPRIS_SIGNAL_TRACK_ADDED:
+		l.handleTrackAdded(busName, sig)
+	case MPRIS_SIGNAL_TRACK_REMOVED:
+		l.handleTrackRemoved(busName, sig)
+	case MPRIS_SIGNAL_TRACK_METADATA_CHANGED:
+		l.handleTrackMetadataChanged(busName, sig)
+	}
+}
+
+// handleTrackListReplaced processes a wholesale tracklist replacement.
+// Body[0] = new track IDs; Body[1] = current track (unused)
+func (l *Listener) handleTrackListReplaced(busName string, sig *dbus.Signal) {
+	ids, ok := arg[[]dbus.ObjectPath](sig, 0)
+	if !ok {
+		return
+	}
+
+	l.refreshTracklist(busName, ids)
+}
+
+// handleTrackAdded processes a track insertion.
+// Body[0] = track metadata; Body[1] = the track it was inserted after
+func (l *Listener) handleTrackAdded(busName string, sig *dbus.Signal) {
+	meta, ok := arg[map[string]dbus.Variant](sig, 0)
+	if !ok {
+		return
+	}
+	afterTrack, ok := arg[dbus.ObjectPath](sig, 1)
+	if !ok {
+		return
+	}
+
+	if err := l.backend.AddTrackToCache(busName, trackFromSignalMetadata(meta), string(afterTrack)); err != nil {
+		logger.Error("[mpris] failed to add track for %s: %v", busName, err)
+	}
+}
+
+// handleTrackRemoved processes a track removal.
+// Body[0] = removed track ID
+func (l *Listener) handleTrackRemoved(busName string, sig *dbus.Signal) {
+	trackID, ok := arg[dbus.ObjectPath](sig, 0)
+	if !ok {
+		return
+	}
+
+	if err := l.backend.RemoveTrackFromCache(busName, string(trackID)); err != nil {
+		logger.Error("[mpris] failed to remove track for %s: %v", busName, err)
+	}
+}
+
+// handleTrackMetadataChanged processes per-track metadata updates.
+// Body[0] = track ID; Body[1] = new metadata
+func (l *Listener) handleTrackMetadataChanged(busName string, sig *dbus.Signal) {
+	trackID, ok := arg[dbus.ObjectPath](sig, 0)
+	if !ok {
+		return
+	}
+	meta, ok := arg[map[string]dbus.Variant](sig, 1)
+	if !ok {
+		return
+	}
+
+	if err := l.backend.UpdateTrackMetadataInCache(busName, string(trackID), trackFromSignalMetadata(meta)); err != nil {
+		logger.Error("[mpris] failed to update track metadata for %s: %v", busName, err)
+	}
+}
+
 // Stop stops the listener
 func (l *Listener) Stop() {
 	logger.Info("[mpris] stopping listener")

backend/mpris/tracklist.go

@@ -54,6 +54,21 @@ func tracklistEnvelope(p Player) map[string]any {
 	}
 }
 
+// tracklistMatches reports whether the player's cached tracklist has exactly
+// the given IDs in the same order.
+func (m *MPRISBackend) tracklistMatches(busName string, ids []dbus.ObjectPath) bool {
+	player, err := m.GetPlayerFromCache(busName)
+	if err != nil || len(player.Tracklist) != len(ids) {
+		return false
+	}
+	for i := range ids {
+		if player.Tracklist[i].TrackID != string(ids[i]) {
+			return false
+		}
+	}
+	return true
+}
+
 // ReplaceTracklist wholesale-replaces a player's tracklist (TrackListReplaced).
 func (m *MPRISBackend) ReplaceTracklist(busName string, tracks []Track) error {
 	return m.mutateTracklist(busName, func(p *Player) bool {

backend/mpris/tracklist_test.go

@@ -444,6 +444,122 @@ func TestRemoveTrackValidation(t *testing.T) {
 	})
 }
 
+func TestListenerTracklistSignals(t *testing.T) {
+	const uniqueName = ":1.42"
+
+	newListener := func() (*Listener, *MPRISBackend) {
+		b := newTracklistBackend(Player{
+			BusName:            testBus,
+			uniqueName:         uniqueName,
+			TracklistSupported: true,
+			Tracklist:          []Track{{TrackID: "/track/1"}, {TrackID: "/track/2"}},
+		})
+		return &Listener{backend: b}, b
+	}
+
+	signal := func(name string, body ...interface{}) *dbus.Signal {
+		return &dbus.Signal{Sender: uniqueName, Path: MPRIS_PATH, Name: name, Body: body}
+	}
+
+	t.Run("TrackAdded prepends via NoTrack", func(t *testing.T) {
+		l, b := newListener()
+		meta := map[string]dbus.Variant{
+			"mpris:trackid": dbus.MakeVariant(dbus.ObjectPath("/track/new")),
+		}
+		l.handleSignal(signal(MPRIS_SIGNAL_TRACK_ADDED, meta, dbus.ObjectPath(MPRIS_NO_TRACK)))
+
+		p, _ := b.GetPlayerFromCache(testBus)
+		assertTrackIDs(t, p.Tracklist, []string{"/track/new", "/track/1", "/track/2"})
+	})
+
+	t.Run("TrackRemoved", func(t *testing.T) {
+		l, b := newListener()
+		l.handleSignal(signal(MPRIS_SIGNAL_TRACK_REMOVED, dbus.ObjectPath("/track/1")))
+
+		p, _ := b.GetPlayerFromCache(testBus)
+		assertTrackIDs(t, p.Tracklist, []string{"/track/2"})
+	})
+
+	t.Run("TrackMetadataChanged", func(t *testing.T) {
+		l, b := newListener()
+		meta := map[string]dbus.Variant{
+			"mpris:trackid": dbus.MakeVariant(dbus.ObjectPath("/track/1")),
+			"xesam:title":   dbus.MakeVariant("Fresh"),
+		}
+		l.handleSignal(signal(MPRIS_SIGNAL_TRACK_METADATA_CHANGED, dbus.ObjectPath("/track/1"), meta))
+
+		p, _ := b.GetPlayerFromCache(testBus)
+		if p.Tracklist[0].Metadata["xesam:title"] != "Fresh" {
+			t.Errorf("title = %q, want %q", p.Tracklist[0].Metadata["xesam:title"], "Fresh")
+		}
+	})
+
+	t.Run("TrackListReplaced with empty list clears", func(t *testing.T) {
+		l, b := newListener()
+		l.handleSignal(signal(MPRIS_SIGNAL_TRACKLIST_REPLACED, []dbus.ObjectPath{}, dbus.ObjectPath(MPRIS_NO_TRACK)))
+
+		p, _ := b.GetPlayerFromCache(testBus)
+		assertTrackIDs(t, p.Tracklist, []string{})
+	})
+
+	t.Run("unknown sender is dropped", func(t *testing.T) {
+		l, b := newListener()
+		sig := signal(MPRIS_SIGNAL_TRACK_REMOVED, dbus.ObjectPath("/track/1"))
+		sig.Sender = ":9.99"
+		l.handleSignal(sig)
+
+		p, _ := b.GetPlayerFromCache(testBus)
+		assertTrackIDs(t, p.Tracklist, []string{"/track/1", "/track/2"})
+	})
+
+	t.Run("malformed bodies are ignored", func(t *testing.T) {
+		l, b := newListener()
+		l.handleSignal(signal(MPRIS_SIGNAL_TRACK_ADDED, "not-a-map"))
+		l.handleSignal(signal(MPRIS_SIGNAL_TRACK_REMOVED))
+		l.handleSignal(signal(MPRIS_SIGNAL_TRACKLIST_REPLACED, "not-ids", dbus.ObjectPath("/x")))
+
+		p, _ := b.GetPlayerFromCache(testBus)
+		assertTrackIDs(t, p.Tracklist, []string{"/track/1", "/track/2"})
+	})
+
+	t.Run("PropertiesChanged on TrackList iface updates CanEditTracks", func(t *testing.T) {
+		l, b := newListener()
+		// Tracks matching the cache must be skipped (dedup for players that
+		// emit both TrackListReplaced and the property change): with a nil
+		// conn, going through the refresh would panic on the metadata fetch.
+		l.handleSignal(signal(DBUS_PROP_CHANGED_SIGNAL, MPRIS_TRACKLIST_IFACE, map[string]dbus.Variant{
+			"CanEditTracks": dbus.MakeVariant(true),
+			"Tracks":        dbus.MakeVariant([]dbus.ObjectPath{"/track/1", "/track/2"}),
+		}, []string{}))
+
+		p, _ := b.GetPlayerFromCache(testBus)
+		if !p.CanEditTracks {
+			t.Error("CanEditTracks should be true")
+		}
+		assertTrackIDs(t, p.Tracklist, []string{"/track/1", "/track/2"})
+	})
+
+	t.Run("PropertiesChanged with changed Tracks refreshes the list (VLC style)", func(t *testing.T) {
+		l, b := newListener()
+		l.handleSignal(signal(DBUS_PROP_CHANGED_SIGNAL, MPRIS_TRACKLIST_IFACE, map[string]dbus.Variant{
+			"Tracks": dbus.MakeVariant([]dbus.ObjectPath{}),
+		}, []string{}))
+
+		p, _ := b.GetPlayerFromCache(testBus)
+		assertTrackIDs(t, p.Tracklist, []string{})
+	})
+
+	t.Run("unrelated invalidated property does not refetch", func(t *testing.T) {
+		l, b := newListener()
+		// With a nil conn, a refetch would panic — not reaching D-Bus is the assertion.
+		l.handleSignal(signal(DBUS_PROP_CHANGED_SIGNAL, MPRIS_TRACKLIST_IFACE,
+			map[string]dbus.Variant{}, []string{"CanEditTracks"}))
+
+		p, _ := b.GetPlayerFromCache(testBus)
+		assertTrackIDs(t, p.Tracklist, []string{"/track/1", "/track/2"})
+	})
+}
+
 func TestTracklistUnsupportedError(t *testing.T) {
 	err := &TracklistUnsupportedError{BusName: "org.mpris.MediaPlayer2.spotify"}
 	expected := "tracklist not supported: org.mpris.MediaPlayer2.spotify"