feat: list the play order in GET /player/queue, and step back without rewinding

API.md

@@ -72,3 +72,4 @@ The websocket endpoint is available at `/events`. The following events are emitt
     - `value`: Whether repeating context is enabled
 - `repeat_track`: The player repeating track setting changed
     - `value`: Whether repeating track is enabled
+- `queue`: The `GET /player/queue` response changed, or the session ended and the endpoint now answers 204

README.md

@@ -233,10 +233,10 @@ cache:
 
 Optionally, the daemon can cache track metadata (name, artists, cover art) in memory and fetch it — via the same
 internal API playback uses, not the rate-limited public Web API — for the tracks around the playback position. This
-enables a `next_track` field in `GET /status` and a `GET /context/tracks?uri=...` endpoint that lists any playable
-context (playlist, album, artist) in order with metadata, so a client can render a browsable song list and start any
-entry via `POST /player/play` with `skip_to_uri`. Everything is opt-in and disabled by default: a headless speaker has
-no use for metadata beyond the playing track and should not pay network requests for it.
+enables a `next_track` field in `GET /status`, track metadata in `GET /player/queue` and a `GET /context/tracks?uri=...`
+endpoint that lists any playable context (playlist, album, artist) in order with metadata, so a client can render a
+browsable song list and start any entry via `POST /player/play` with `skip_to_uri`. Everything is opt-in and disabled by
+default: a headless speaker has no use for metadata beyond the playing track and should not pay network requests for it.
 
 ```yaml
 metadata:

api-spec.yml

@@ -233,6 +233,61 @@ components:
           allOf:
             - $ref: '#/components/schemas/track'
           nullable: true
+    queueEntry:
+      x-go-name: ApiQueueEntry
+      description: One entry of the play order
+      type: object
+      required: [ uri, uid, provider, track ]
+      properties:
+        uri:
+          description: The entry URI, usually a track or an episode
+          type: string
+        uid:
+          description: >-
+            The entry's uid in the play order, which tells two copies of a
+            track apart; null when it has none, as for album tracks
+          type: string
+          nullable: true
+        provider:
+          description: >-
+            Where the entry comes from: the user's queue, the context, or
+            autoplay once the context has ended
+          type: string
+          enum: [ queue, context, autoplay ]
+        track:
+          description: >-
+            Track metadata (metadata.enabled), null until cached or for entries
+            without any, such as local files. Its position is the playback
+            position for the current entry and 0 for the others
+          allOf:
+            - $ref: '#/components/schemas/track'
+          nullable: true
+    queue:
+      x-go-name: ApiQueue
+      description: The play order around the current track
+      type: object
+      required: [ prev_tracks, track, next_tracks ]
+      properties:
+        prev_tracks:
+          description: >-
+            Entries before the current one in the play order, farthest first,
+            up to 32. Not a play history: a context started from one of its
+            tracks lists the tracks before it
+          type: array
+          items:
+            $ref: '#/components/schemas/queueEntry'
+        track:
+          description: The current entry, null when nothing is loaded
+          allOf:
+            - $ref: '#/components/schemas/queueEntry'
+          nullable: true
+        next_tracks:
+          description: >-
+            Entries after the current one, nearest first, the user's queue
+            before the rest, up to 32
+          type: array
+          items:
+            $ref: '#/components/schemas/queueEntry'
     contextTracks:
       x-go-name: ApiContextTracks
       description: A context's track listing
@@ -701,6 +756,17 @@ components:
             The track URI to skip to. When omitted the next track in the
             context is played.
           type: string
+    prev:
+      x-go-name: ApiPrev
+      description: A skip to previous payload
+      type: object
+      properties:
+        allow_seeking:
+          description: >-
+            Whether to rewind a track played past three seconds instead of
+            skipping to the previous one
+          type: boolean
+          default: true
     seek:
       x-go-name: ApiSeek
       description: A seek payload
@@ -1258,7 +1324,16 @@ paths:
   /player/prev:
     post:
       operationId: playerPrev
-      description: Skip to previous track (or rewind current track)
+      description: >-
+        Skip to previous track (or rewind current track); with none before it,
+        the current track restarts. From a queued track it returns to the
+        context, to the track before the one the queue was entered from (or
+        that one if it is the context's first); the queued track stays queued
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/prev'
       responses:
         200:
           description: Successful response
@@ -1348,6 +1423,25 @@ paths:
       responses:
         200:
           description: Successful response
+  /player/queue:
+    get:
+      operationId: playerGetQueue
+      description: >-
+        List the play order around the current track, as Spotify Connect holds
+        it. With metadata.enabled, missing metadata is fetched in the background
+        and the response never waits for it. The queue event is raised whenever
+        the response changes, the current entry's position aside; a context
+        start can report the cleared order before the resolved one. A 204 means
+        the same as an empty order
+      responses:
+        200:
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/queue'
+        204:
+          description: No active session
   /player/add_to_queue:
     post:
       operationId: playerAddToQueue

config_schema.json

@@ -369,11 +369,11 @@
         },
         "metadata": {
           "type": "object",
-          "description": "Opt-in in-memory track metadata cache behind the next_track status field and the GET /context/tracks listing",
+          "description": "Opt-in in-memory track metadata cache behind the next_track status field, the tracks of GET /player/queue and the GET /context/tracks listing",
           "properties": {
             "enabled": {
               "type": "boolean",
-              "description": "Whether to cache track metadata and batch-fetch it for the tracks around the playback position, enabling the next_track status field and the /context/tracks endpoint. Disabled, the daemon performs no metadata request playback does not need",
+              "description": "Whether to cache track metadata and batch-fetch it for the tracks around the playback position, enabling the next_track status field, the tracks of GET /player/queue and the /context/tracks endpoint. Disabled, the daemon performs no metadata request playback does not need",
               "default": false
             },
             "context_sweep": {