Prefer UUIDs in the API (Phase 3 of the UUID migration)

- New /api/v1 endpoints: GET /soundtracks, /soundtracks/{uuid},
  /songs/{uuid} and /songs/{uuid}/file (streams the song, Range support,
  locked during sync)
- UUIDs added to every response with soundtracks or songs: queue info and
  list (SoundtrackUuid, SongUuid) and statistics (soundtrack_uuid,
  song_uuid). Existing fields stay for backward compatibility
- Play counts and broken-song removal use song UUIDs instead of
  soundtrack ID + song name, so songs with the same name are counted
  separately
- Statistics return an empty song list for soundtracks without songs
  instead of a single empty entry
- The legacy .id file cleanup stays until Phase 4 (#31)

Closes #29

cmd/docs/swagger.yaml

@@ -1,5 +1,20 @@
 basePath: /
 definitions:
+  backend.Song:
+    properties:
+      file_name:
+        type: string
+      name:
+        type: string
+      soundtrack_name:
+        type: string
+      soundtrack_uuid:
+        type: string
+      times_played:
+        type: integer
+      uuid:
+        type: string
+    type: object
   backend.SongInfo:
     properties:
       CurrentlyPlaying:
@@ -10,10 +25,14 @@ definitions:
         type: integer
       SongPlayed:
         type: integer
+      SongUuid:
+        type: string
       Soundtrack:
         type: string
       SoundtrackPlayed:
         type: integer
+      SoundtrackUuid:
+        type: string
     type: object
   backend.SongInfoForStats:
     properties:
@@ -23,13 +42,47 @@ definitions:
         type: string
       song_name:
         type: string
+      song_uuid:
+        type: string
       soundtrack_id:
         type: integer
       soundtrack_name:
         type: string
+      soundtrack_uuid:
+        type: string
       times_played:
         type: integer
     type: object
+  backend.Soundtrack:
+    properties:
+      added:
+        type: string
+      last_played:
+        type: string
+      name:
+        type: string
+      times_played:
+        type: integer
+      uuid:
+        type: string
+    type: object
+  backend.SoundtrackWithSongList:
+    properties:
+      added:
+        type: string
+      last_played:
+        type: string
+      name:
+        type: string
+      songs:
+        items:
+          $ref: '#/definitions/backend.Song'
+        type: array
+      times_played:
+        type: integer
+      uuid:
+        type: string
+    type: object
   backend.SoundtrackWithSongs:
     properties:
       songs:
@@ -44,6 +97,8 @@ definitions:
         type: string
       soundtrack_played:
         type: integer
+      soundtrack_uuid:
+        type: string
     type: object
   backend.StatisticsSummary:
     properties:
@@ -134,6 +189,110 @@ info:
   title: MusicServer API
   version: "1.0"
 paths:
+  /api/v1/songs/{uuid}:
+    get:
+      description: Returns information about a song
+      parameters:
+      - description: Song UUID
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/backend.Song'
+        "400":
+          description: invalid uuid
+          schema:
+            type: string
+        "404":
+          description: not found
+          schema:
+            type: string
+      summary: Get song
+      tags:
+      - library
+  /api/v1/songs/{uuid}/file:
+    get:
+      description: Returns the audio file of a song. Supports Range requests.
+      parameters:
+      - description: Song UUID
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - audio/mpeg
+      responses:
+        "200":
+          description: OK
+          schema:
+            type: file
+        "206":
+          description: Partial Content
+          schema:
+            type: file
+        "400":
+          description: invalid uuid
+          schema:
+            type: string
+        "404":
+          description: not found
+          schema:
+            type: string
+        "423":
+          description: Syncing is in progress
+          schema:
+            type: string
+      summary: Stream song
+      tags:
+      - library
+  /api/v1/soundtracks:
+    get:
+      description: Returns all soundtracks with their UUIDs, sorted by name
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            items:
+              $ref: '#/definitions/backend.Soundtrack'
+            type: array
+      summary: List soundtracks
+      tags:
+      - library
+  /api/v1/soundtracks/{uuid}:
+    get:
+      description: Returns a soundtrack with its songs
+      parameters:
+      - description: Soundtrack UUID
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/backend.SoundtrackWithSongList'
+        "400":
+          description: invalid uuid
+          schema:
+            type: string
+        "404":
+          description: not found
+          schema:
+            type: string
+      summary: Get soundtrack
+      tags:
+      - library
   /api/v1/statistics/songs/least-played:
     get:
       description: Returns the top N least played songs with their soundtrack info