Sansan/MusicServer
1
0 Fork 0
Code Issues 9 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Prefer UUIDs in the API (Phase 3 of the UUID migration)
CI / docker (push) Successful in 46s
Details
CI / integration (push) Successful in 23s
Details
CI / test (push) Successful in 30s
Details
CI / publish (push) Skipped
Details

Browse Source 
- 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 2026-10-06 15:54:41 +02:00
1 parent 8c974a49cc
commit 2c3e97190d
25 files changed
+1521 -117
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

cmd/docs/docs.go
+242
View File
@@ -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"
}
}
},