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
This commit is contained in:
Sansan committed
1 parent
8c974a49cc
commit
2c3e97190d
25 files changed
+1521
-117
No files matched your search
@@ -23,6 +23,164 @@ const docTemplate = `{
|
||||
"host": "{{.Host}}",
|
||||
"basePath": "{{.BasePath}}",
|
||||
"paths": {
|
||||
"/api/v1/songs/{uuid}": {
|
||||
"get": {
|
||||
"description": "Returns information about a song",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"library"
|
||||
],
|
||||
"summary": "Get song",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Song UUID",
|
||||
"name": "uuid",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/backend.Song"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "invalid uuid",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "not found",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/songs/{uuid}/file": {
|
||||
"get": {
|
||||
"description": "Returns the audio file of a song. Supports Range requests.",
|
||||
"produces": [
|
||||
"audio/mpeg"
|
||||
],
|
||||
"tags": [
|
||||
"library"
|
||||
],
|
||||
"summary": "Stream song",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Song UUID",
|
||||
"name": "uuid",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/soundtracks": {
|
||||
"get": {
|
||||
"description": "Returns all soundtracks with their UUIDs, sorted by name",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"library"
|
||||
],
|
||||
"summary": "List soundtracks",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/backend.Soundtrack"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/soundtracks/{uuid}": {
|
||||
"get": {
|
||||
"description": "Returns a soundtrack with its songs",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"library"
|
||||
],
|
||||
"summary": "Get soundtrack",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Soundtrack UUID",
|
||||
"name": "uuid",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/backend.SoundtrackWithSongList"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "invalid uuid",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "not found",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/statistics/songs/least-played": {
|
||||
"get": {
|
||||
"description": "Returns the top N least played songs with their soundtrack info",
|
||||
@@ -1331,6 +1489,29 @@ const docTemplate = `{
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"backend.Song": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"file_name": {
|
||||
"type": "string"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"soundtrack_name": {
|
||||
"type": "string"
|
||||
},
|
||||
"soundtrack_uuid": {
|
||||
"type": "string"
|
||||
},
|
||||
"times_played": {
|
||||
"type": "integer"
|
||||
},
|
||||
"uuid": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"backend.SongInfo": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -1346,11 +1527,17 @@ const docTemplate = `{
|
||||
"SongPlayed": {
|
||||
"type": "integer"
|
||||
},
|
||||
"SongUuid": {
|
||||
"type": "string"
|
||||
},
|
||||
"Soundtrack": {
|
||||
"type": "string"
|
||||
},
|
||||
"SoundtrackPlayed": {
|
||||
"type": "integer"
|
||||
},
|
||||
"SoundtrackUuid": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -1366,17 +1553,69 @@ const docTemplate = `{
|
||||
"song_name": {
|
||||
"type": "string"
|
||||
},
|
||||
"song_uuid": {
|
||||
"type": "string"
|
||||
},
|
||||
"soundtrack_id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"soundtrack_name": {
|
||||
"type": "string"
|
||||
},
|
||||
"soundtrack_uuid": {
|
||||
"type": "string"
|
||||
},
|
||||
"times_played": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"backend.Soundtrack": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"added": {
|
||||
"type": "string"
|
||||
},
|
||||
"last_played": {
|
||||
"type": "string"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"times_played": {
|
||||
"type": "integer"
|
||||
},
|
||||
"uuid": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"backend.SoundtrackWithSongList": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"added": {
|
||||
"type": "string"
|
||||
},
|
||||
"last_played": {
|
||||
"type": "string"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"songs": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/backend.Song"
|
||||
}
|
||||
},
|
||||
"times_played": {
|
||||
"type": "integer"
|
||||
},
|
||||
"uuid": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"backend.SoundtrackWithSongs": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -1397,6 +1636,9 @@ const docTemplate = `{
|
||||
},
|
||||
"soundtrack_played": {
|
||||
"type": "integer"
|
||||
},
|
||||
"soundtrack_uuid": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
@@ -16,6 +16,164 @@
|
||||
},
|
||||
"basePath": "/",
|
||||
"paths": {
|
||||
"/api/v1/songs/{uuid}": {
|
||||
"get": {
|
||||
"description": "Returns information about a song",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"library"
|
||||
],
|
||||
"summary": "Get song",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Song UUID",
|
||||
"name": "uuid",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/backend.Song"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "invalid uuid",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "not found",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/songs/{uuid}/file": {
|
||||
"get": {
|
||||
"description": "Returns the audio file of a song. Supports Range requests.",
|
||||
"produces": [
|
||||
"audio/mpeg"
|
||||
],
|
||||
"tags": [
|
||||
"library"
|
||||
],
|
||||
"summary": "Stream song",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Song UUID",
|
||||
"name": "uuid",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/soundtracks": {
|
||||
"get": {
|
||||
"description": "Returns all soundtracks with their UUIDs, sorted by name",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"library"
|
||||
],
|
||||
"summary": "List soundtracks",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/backend.Soundtrack"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/soundtracks/{uuid}": {
|
||||
"get": {
|
||||
"description": "Returns a soundtrack with its songs",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"library"
|
||||
],
|
||||
"summary": "Get soundtrack",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Soundtrack UUID",
|
||||
"name": "uuid",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/backend.SoundtrackWithSongList"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "invalid uuid",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "not found",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/statistics/songs/least-played": {
|
||||
"get": {
|
||||
"description": "Returns the top N least played songs with their soundtrack info",
|
||||
@@ -1324,6 +1482,29 @@
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"backend.Song": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"file_name": {
|
||||
"type": "string"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"soundtrack_name": {
|
||||
"type": "string"
|
||||
},
|
||||
"soundtrack_uuid": {
|
||||
"type": "string"
|
||||
},
|
||||
"times_played": {
|
||||
"type": "integer"
|
||||
},
|
||||
"uuid": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"backend.SongInfo": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -1339,11 +1520,17 @@
|
||||
"SongPlayed": {
|
||||
"type": "integer"
|
||||
},
|
||||
"SongUuid": {
|
||||
"type": "string"
|
||||
},
|
||||
"Soundtrack": {
|
||||
"type": "string"
|
||||
},
|
||||
"SoundtrackPlayed": {
|
||||
"type": "integer"
|
||||
},
|
||||
"SoundtrackUuid": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -1359,17 +1546,69 @@
|
||||
"song_name": {
|
||||
"type": "string"
|
||||
},
|
||||
"song_uuid": {
|
||||
"type": "string"
|
||||
},
|
||||
"soundtrack_id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"soundtrack_name": {
|
||||
"type": "string"
|
||||
},
|
||||
"soundtrack_uuid": {
|
||||
"type": "string"
|
||||
},
|
||||
"times_played": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"backend.Soundtrack": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"added": {
|
||||
"type": "string"
|
||||
},
|
||||
"last_played": {
|
||||
"type": "string"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"times_played": {
|
||||
"type": "integer"
|
||||
},
|
||||
"uuid": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"backend.SoundtrackWithSongList": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"added": {
|
||||
"type": "string"
|
||||
},
|
||||
"last_played": {
|
||||
"type": "string"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"songs": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/backend.Song"
|
||||
}
|
||||
},
|
||||
"times_played": {
|
||||
"type": "integer"
|
||||
},
|
||||
"uuid": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"backend.SoundtrackWithSongs": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -1390,6 +1629,9 @@
|
||||
},
|
||||
"soundtrack_played": {
|
||||
"type": "integer"
|
||||
},
|
||||
"soundtrack_uuid": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user