feat(api): expose the MPRIS tracklist endpoints

GET /players/{player}/tracklist serves the cached list (404 when the
player lacks the interface). GoTo and RemoveTrack take a track reference
in the path: the last segment of the track's object path (or the
%2F-encoded full path). Track IDs are player-chosen object paths with no
common prefix, so the backend resolves the reference against the cached
tracklist — which also rejects tracks not in the list. AddTrack keeps a
JSON body (uri/after_track/set_as_current), after_track resolved the
same way with a NoTrack prepend sentinel.

AddTrack validates the uri per spec — absolute URI, scheme within the
player's SupportedUriSchemes (now loaded from the root interface) — so
a bad uri gets a 400 instead of a 202 the player silently drops.

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

Author: b0bbywan

api/handlers_mpris_test.go

@@ -178,6 +178,14 @@ func TestHandleMPRISError(t *testing.T) {
 			wantStatusCode: http.StatusForbidden,
 			wantBodyMatch:  "action not allowed",
 		},
+		{
+			name: "TracklistUnsupportedError returns 404 Not Found",
+			err: &mpris.TracklistUnsupportedError{
+				BusName: "org.mpris.MediaPlayer2.firefox",
+			},
+			wantStatusCode: http.StatusNotFound,
+			wantBodyMatch:  "tracklist not supported",
+		},
 		{
 			name:           "generic error returns 500 Internal Server Error",
 			err:            http.ErrServerClosed,
@@ -205,6 +213,114 @@ func TestHandleMPRISError(t *testing.T) {
 	}
 }
 
+func TestTracklistHandler(t *testing.T) {
+	tests := []struct {
+		name           string
+		getTracklist   func(string) (*mpris.TracklistResponse, error)
+		wantStatusCode int
+		wantBodyMatch  string
+	}{
+		{
+			name: "success returns 200 with tracks",
+			getTracklist: func(string) (*mpris.TracklistResponse, error) {
+				return &mpris.TracklistResponse{
+					CanEditTracks: true,
+					Tracks:        []mpris.Track{{TrackID: "/org/mpris/MediaPlayer2/Track/1"}},
+				}, nil
+			},
+			wantStatusCode: http.StatusOK,
+			wantBodyMatch:  `"/org/mpris/MediaPlayer2/Track/1"`,
+		},
+		{
+			name: "empty tracklist returns 200 with empty array",
+			getTracklist: func(string) (*mpris.TracklistResponse, error) {
+				return &mpris.TracklistResponse{Tracks: []mpris.Track{}}, nil
+			},
+			wantStatusCode: http.StatusOK,
+			wantBodyMatch:  `"tracks":[]`,
+		},
+		{
+			name: "unsupported returns 404",
+			getTracklist: func(busName string) (*mpris.TracklistResponse, error) {
+				return nil, &mpris.TracklistUnsupportedError{BusName: busName}
+			},
+			wantStatusCode: http.StatusNotFound,
+			wantBodyMatch:  "tracklist not supported",
+		},
+		{
+			name: "player not found returns 404",
+			getTracklist: func(busName string) (*mpris.TracklistResponse, error) {
+				return nil, &mpris.PlayerNotFoundError{BusName: busName}
+			},
+			wantStatusCode: http.StatusNotFound,
+			wantBodyMatch:  "player not found",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			handler := TracklistHandler(tt.getTracklist)
+
+			req := httptest.NewRequest("GET", "/players/org.mpris.MediaPlayer2.mpd/tracklist", nil)
+			req.SetPathValue("player", "org.mpris.MediaPlayer2.mpd")
+			w := httptest.NewRecorder()
+
+			handler(w, req)
+
+			if w.Code != tt.wantStatusCode {
+				t.Errorf("status = %d, want %d", w.Code, tt.wantStatusCode)
+			}
+			if !strings.Contains(w.Body.String(), tt.wantBodyMatch) {
+				t.Errorf("body = %q, want to contain %q", w.Body.String(), tt.wantBodyMatch)
+			}
+		})
+	}
+}
+
+func TestWithTrackRoutePattern(t *testing.T) {
+	newMux := func(gotBus, gotTrack *string) *http.ServeMux {
+		mux := http.NewServeMux()
+		mux.HandleFunc("POST /players/{player}/tracklist/goto/{trackid}",
+			withTrack(func(w http.ResponseWriter, r *http.Request, busName, trackRef string) {
+				*gotBus, *gotTrack = busName, trackRef
+				w.WriteHeader(http.StatusAccepted)
+			}))
+		return mux
+	}
+
+	t.Run("last segment", func(t *testing.T) {
+		var gotBus, gotTrack string
+		req := httptest.NewRequest("POST", "/players/org.mpris.MediaPlayer2.mpd/tracklist/goto/7", nil)
+		w := httptest.NewRecorder()
+		newMux(&gotBus, &gotTrack).ServeHTTP(w, req)
+
+		if w.Code != http.StatusAccepted {
+			t.Fatalf("status = %d, want %d", w.Code, http.StatusAccepted)
+		}
+		if gotBus != "org.mpris.MediaPlayer2.mpd" {
+			t.Errorf("busName = %q, want %q", gotBus, "org.mpris.MediaPlayer2.mpd")
+		}
+		if gotTrack != "7" {
+			t.Errorf("trackRef = %q, want %q", gotTrack, "7")
+		}
+	})
+
+	t.Run("percent-encoded full object path", func(t *testing.T) {
+		var gotBus, gotTrack string
+		req := httptest.NewRequest("POST",
+			"/players/org.mpris.MediaPlayer2.mpd/tracklist/goto/%2Forg%2Fmpris%2FMediaPlayer2%2FTrack%2F7", nil)
+		w := httptest.NewRecorder()
+		newMux(&gotBus, &gotTrack).ServeHTTP(w, req)
+
+		if w.Code != http.StatusAccepted {
+			t.Fatalf("status = %d, want %d", w.Code, http.StatusAccepted)
+		}
+		if gotTrack != "/org/mpris/MediaPlayer2/Track/7" {
+			t.Errorf("trackRef = %q, want %q", gotTrack, "/org/mpris/MediaPlayer2/Track/7")
+		}
+	})
+}
+
 // TestWithPlayer tests the middleware for extracting busName
 func TestWithPlayer(t *testing.T) {
 	tests := []struct {

api/players.go

@@ -1,6 +1,7 @@
 package api
 
 import (
+	"encoding/json"
 	"errors"
 	"net/http"
 	"net/url"
@@ -47,6 +48,13 @@ func handleMPRISError(w http.ResponseWriter, err error) {
 		return
 	}
 
+	// Tracklist unsupported: the resource doesn't exist for this player
+	var unsupportedErr *mpris.TracklistUnsupportedError
+	if errors.As(err, &unsupportedErr) {
+		http.Error(w, err.Error(), http.StatusNotFound)
+		return
+	}
+
 	// Handle capability errors
 	var capErr *mpris.CapabilityError
 	if errors.As(err, &capErr) {
@@ -135,6 +143,52 @@ func SetShuffleHandler(m *mpris.MPRISBackend) http.HandlerFunc {
 	})
 }
 
+// withTrack extracts the {trackid} parameter: the last segment of a track's
+// object path (or the %2F-encoded full path), resolved against the cached
+// tracklist by the backend.
+func withTrack(
+	next func(w http.ResponseWriter, r *http.Request, busName, trackRef string),
+) http.HandlerFunc {
+	return withPlayer(func(w http.ResponseWriter, r *http.Request, busName string) {
+		next(w, r, busName, r.PathValue("trackid"))
+	})
+}
+
+func TracklistHandler(getTracklist func(string) (*mpris.TracklistResponse, error)) http.HandlerFunc {
+	return withPlayer(func(w http.ResponseWriter, r *http.Request, busName string) {
+		resp, err := getTracklist(busName)
+		if err != nil {
+			handleMPRISError(w, err)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		if err := json.NewEncoder(w).Encode(resp); err != nil {
+			http.Error(w, err.Error(), http.StatusInternalServerError)
+		}
+	})
+}
+
+func GoToHandler(m *mpris.MPRISBackend) http.HandlerFunc {
+	return withTrack(func(w http.ResponseWriter, r *http.Request, busName, trackID string) {
+		handleMPRISError(w, m.GoTo(busName, trackID))
+	})
+}
+
+func RemoveTrackHandler(m *mpris.MPRISBackend) http.HandlerFunc {
+	return withTrack(func(w http.ResponseWriter, r *http.Request, busName, trackID string) {
+		handleMPRISError(w, m.RemoveTrack(busName, trackID))
+	})
+}
+
+func AddTrackHandler(m *mpris.MPRISBackend) http.HandlerFunc {
+	return withPlayer(func(w http.ResponseWriter, r *http.Request, busName string) {
+		withBody(nil, func(w http.ResponseWriter, r *http.Request, req *mpris.AddTrackRequest) {
+			handleMPRISError(w, m.AddTrack(busName, req.Uri, req.AfterTrack, req.SetAsCurrent))
+		})(w, r)
+	})
+}
+
 func CoverHandler(getPlayer func(string) (*mpris.Player, error)) http.HandlerFunc {
 	return withPlayer(func(w http.ResponseWriter, r *http.Request, busName string) {
 		player, err := getPlayer(busName)

api/routes.go

@@ -230,4 +230,20 @@ func (s *Server) registerMPRISRoutes(b *mpris.MPRISBackend) {
 		"POST /players/{player}/shuffle",
 		SetShuffleHandler(b),
 	)
+	s.mux.HandleFunc(
+		"GET /players/{player}/tracklist",
+		TracklistHandler(b.GetTracklist),
+	)
+	s.mux.HandleFunc(
+		"POST /players/{player}/tracklist/goto/{trackid}",
+		GoToHandler(b),
+	)
+	s.mux.HandleFunc(
+		"POST /players/{player}/tracklist/add",
+		AddTrackHandler(b),
+	)
+	s.mux.HandleFunc(
+		"POST /players/{player}/tracklist/remove/{trackid}",
+		RemoveTrackHandler(b),
+	)
 }

backend/mpris/dbus.go

@@ -162,6 +162,12 @@ func extractFloat64(v dbus.Variant) (float64, bool) {
 	return val, ok
 }
 
+// extractStringSlice extracts a []string from a dbus.Variant
+func extractStringSlice(v dbus.Variant) ([]string, bool) {
+	val, ok := v.Value().([]string)
+	return val, ok
+}
+
 // extractMetadataMap extracts a metadata map from a dbus.Variant
 func extractMetadataMap(v dbus.Variant) (map[string]dbus.Variant, bool) {
 	val, ok := v.Value().(map[string]dbus.Variant)

backend/mpris/mpris_test.go

@@ -965,14 +965,15 @@ func TestPlayerStructTags(t *testing.T) {
 		dbusTag  string
 		ifaceTag string
 	}{
-		"Identity":       {dbusTag: "Identity", ifaceTag: "org.mpris.MediaPlayer2"},
-		"PlaybackStatus": {dbusTag: "PlaybackStatus", ifaceTag: "org.mpris.MediaPlayer2.Player"},
-		"LoopStatus":     {dbusTag: "LoopStatus", ifaceTag: "org.mpris.MediaPlayer2.Player"},
-		"Shuffle":        {dbusTag: "Shuffle", ifaceTag: "org.mpris.MediaPlayer2.Player"},
-		"Volume":         {dbusTag: "Volume", ifaceTag: "org.mpris.MediaPlayer2.Player"},
-		"Position":       {dbusTag: "Position", ifaceTag: "org.mpris.MediaPlayer2.Player"},
-		"Rate":           {dbusTag: "Rate", ifaceTag: "org.mpris.MediaPlayer2.Player"},
-		"Metadata":       {dbusTag: "Metadata", ifaceTag: "org.mpris.MediaPlayer2.Player"},
+		"Identity":            {dbusTag: "Identity", ifaceTag: "org.mpris.MediaPlayer2"},
+		"SupportedUriSchemes": {dbusTag: "SupportedUriSchemes", ifaceTag: "org.mpris.MediaPlayer2"},
+		"PlaybackStatus":      {dbusTag: "PlaybackStatus", ifaceTag: "org.mpris.MediaPlayer2.Player"},
+		"LoopStatus":          {dbusTag: "LoopStatus", ifaceTag: "org.mpris.MediaPlayer2.Player"},
+		"Shuffle":             {dbusTag: "Shuffle", ifaceTag: "org.mpris.MediaPlayer2.Player"},
+		"Volume":              {dbusTag: "Volume", ifaceTag: "org.mpris.MediaPlayer2.Player"},
+		"Position":            {dbusTag: "Position", ifaceTag: "org.mpris.MediaPlayer2.Player"},
+		"Rate":                {dbusTag: "Rate", ifaceTag: "org.mpris.MediaPlayer2.Player"},
+		"Metadata":            {dbusTag: "Metadata", ifaceTag: "org.mpris.MediaPlayer2.Player"},
 	}
 
 	for i := 0; i < playerType.NumField(); i++ {

backend/mpris/player.go

@@ -140,6 +140,13 @@ func (p *Player) loadFromDBus() error {
 				field.SetInt(val)
 			}
 
+		case reflect.Slice:
+			if field.Type().Elem().Kind() == reflect.String {
+				if val, ok := extractStringSlice(variant); ok {
+					field.Set(reflect.ValueOf(val))
+				}
+			}
+
 		case reflect.Map:
 			// Special case for Metadata
 			if dbusTag == "Metadata" {

backend/mpris/tracklist.go

@@ -1,6 +1,9 @@
 package mpris
 
 import (
+	"net/url"
+	"path"
+	"slices"
 	"time"
 
 	"github.com/godbus/dbus/v5"
@@ -9,6 +12,19 @@ import (
 	"github.com/b0bbywan/go-odio-api/logger"
 )
 
+// resolveTrackRef resolves an API-supplied track reference — a full object
+// path or just its last segment — against the cached tracklist. Track IDs are
+// player-chosen object paths with no common prefix, so the cache is the only
+// way to rebuild the full path from a bare ID.
+func resolveTrackRef(tracks []Track, ref string) (string, bool) {
+	for i := range tracks {
+		if tracks[i].TrackID == ref || path.Base(tracks[i].TrackID) == ref {
+			return tracks[i].TrackID, true
+		}
+	}
+	return "", false
+}
+
 // mutateTracklist applies fn to the cached player and broadcasts the resulting
 // tracklist snapshot. fn returns false for no-op mutations (nothing stored,
 // nothing broadcast). fn must respect updatePlayers' copy-on-write contract:
@@ -206,14 +222,16 @@ func (m *MPRISBackend) GetTracklist(busName string) (*TracklistResponse, error)
 	return &TracklistResponse{CanEditTracks: player.CanEditTracks, Tracks: tracks}, nil
 }
 
-// GoTo skips to the given track. Not gated on CanEditTracks: the spec doesn't
-// class GoTo as an edit operation.
-func (m *MPRISBackend) GoTo(busName, trackID string) error {
-	if _, err := m.tracklistPlayer(busName); err != nil {
+// GoTo skips to the referenced track. Not gated on CanEditTracks: the spec
+// doesn't class GoTo as an edit operation.
+func (m *MPRISBackend) GoTo(busName, trackRef string) error {
+	player, err := m.tracklistPlayer(busName)
+	if err != nil {
 		return err
 	}
-	if !dbus.ObjectPath(trackID).IsValid() {
-		return &ValidationError{Field: "track_id", Message: "must be a valid D-Bus object path"}
+	trackID, ok := resolveTrackRef(player.Tracklist, trackRef)
+	if !ok {
+		return &ValidationError{Field: "track_id", Message: "unknown track: " + trackRef}
 	}
 
 	logger.Debug("[mpris] going to track %s for %s", trackID, busName)
@@ -227,32 +245,46 @@ func (m *MPRISBackend) AddTrack(busName, uri, afterTrack string, setAsCurrent bo
 	if err != nil {
 		return err
 	}
-	if uri == "" {
-		return &ValidationError{Field: "uri", Message: "must not be empty"}
+	// The spec requires an absolute URI whose scheme the player declared in
+	// SupportedUriSchemes; a bare path would be silently dropped player-side.
+	u, err := url.Parse(uri)
+	if err != nil || u.Scheme == "" {
+		return &ValidationError{Field: "uri", Message: "must be an absolute URI (e.g. file:///path or http://...)"}
+	}
+	if len(player.SupportedUriSchemes) > 0 && !slices.Contains(player.SupportedUriSchemes, u.Scheme) {
+		return &ValidationError{Field: "uri", Message: "scheme " + u.Scheme + " not supported by player"}
 	}
 
-	if afterTrack == "" {
+	switch afterTrack {
+	case "":
 		if n := len(player.Tracklist); n > 0 {
 			afterTrack = player.Tracklist[n-1].TrackID
 		} else {
 			afterTrack = MPRIS_NO_TRACK
 		}
-	}
-	if !dbus.ObjectPath(afterTrack).IsValid() {
-		return &ValidationError{Field: "after_track", Message: "must be a valid D-Bus object path"}
+	case MPRIS_NO_TRACK, "NoTrack": // explicit prepend
+		afterTrack = MPRIS_NO_TRACK
+	default:
+		resolved, ok := resolveTrackRef(player.Tracklist, afterTrack)
+		if !ok {
+			return &ValidationError{Field: "after_track", Message: "unknown track: " + afterTrack}
+		}
+		afterTrack = resolved
 	}
 
 	logger.Debug("[mpris] adding track %s after %s for %s", uri, afterTrack, busName)
 	return m.callMethod(busName, MPRIS_METHOD_ADD_TRACK, uri, dbus.ObjectPath(afterTrack), setAsCurrent)
 }
 
-// RemoveTrack asks the player to remove a track from its tracklist.
-func (m *MPRISBackend) RemoveTrack(busName, trackID string) error {
-	if _, err := m.editableTracklistPlayer(busName); err != nil {
+// RemoveTrack asks the player to remove the referenced track from its tracklist.
+func (m *MPRISBackend) RemoveTrack(busName, trackRef string) error {
+	player, err := m.editableTracklistPlayer(busName)
+	if err != nil {
 		return err
 	}
-	if !dbus.ObjectPath(trackID).IsValid() {
-		return &ValidationError{Field: "track_id", Message: "must be a valid D-Bus object path"}
+	trackID, ok := resolveTrackRef(player.Tracklist, trackRef)
+	if !ok {
+		return &ValidationError{Field: "track_id", Message: "unknown track: " + trackRef}
 	}
 
 	logger.Debug("[mpris] removing track %s for %s", trackID, busName)