Something went wrong. Try again.
A modern, network-enabled music player platform built on Rockbox technology. rockboxd.tsiry-sandratraina.com
rust deno navidrome airplay libadwaita zig mpris snapcast mpd rockbox audio subsonic
Something went wrong. Try again.
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255{ "openapi": "3.1.0", "info": { "title": "Rockbox HTTP API", "version": "1.0.0", "summary": "HTTP REST API for rockboxd — playback, library, playlists, devices, settings.", "description": "Rockbox Daemon exposes its full feature surface over HTTP REST on port 6063 (configurable via `ROCKBOX_TCP_PORT`). It complements the GraphQL API on :6062 and the gRPC API on :6061 — all three speak to the same in-process state.\n\nAll handlers are defined in `crates/server/src/handlers/` and registered in `crates/server/src/lib.rs:run_http_server()`.", "contact": { "name": "Rockbox Daemon", "url": "https://github.com/tsirysndr/rockboxd" }, "license": { "name": "GPL-2.0", "url": "https://www.gnu.org/licenses/old-licenses/gpl-2.0.html" } }, "servers": [ { "url": "http://localhost:6063", "description": "Default local rockboxd" } ], "tags": [ { "name": "Albums" }, { "name": "Artists" }, { "name": "Tracks" }, { "name": "Search" }, { "name": "Browse" }, { "name": "Player" }, { "name": "Playlist (queue)" }, { "name": "Saved playlists" }, { "name": "Smart playlists" }, { "name": "Track stats" }, { "name": "Devices" }, { "name": "Settings" }, { "name": "System" }, { "name": "Bluetooth" } ], "paths": { "/albums": { "get": { "operationId": "getAlbums", "tags": ["Albums"], "summary": "List all albums", "responses": { "200": { "description": "Array of albums", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Album" } } } } } } } }, "/albums/{id}": { "get": { "operationId": "getAlbum", "tags": ["Albums"], "summary": "Get an album by id", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Album", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Album" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/albums/{id}/tracks": { "get": { "operationId": "getAlbumTracks", "tags": ["Albums"], "summary": "List tracks in an album", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Tracks belonging to the album", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Track" } } } } } } } }, "/artists": { "get": { "operationId": "getArtists", "tags": ["Artists"], "summary": "List all artists", "responses": { "200": { "description": "Array of artists", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Artist" } } } } } } } }, "/artists/{id}": { "get": { "operationId": "getArtist", "tags": ["Artists"], "summary": "Get an artist by id", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Artist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artist" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/artists/{id}/albums": { "get": { "operationId": "getArtistAlbums", "tags": ["Artists"], "summary": "List albums by an artist", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Albums by the artist", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Album" } } } } } } } }, "/artists/{id}/tracks": { "get": { "operationId": "getArtistTracks", "tags": ["Artists"], "summary": "List tracks by an artist", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Tracks by the artist", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Track" } } } } } } } }, "/tracks": { "get": { "operationId": "getTracks", "tags": ["Tracks"], "summary": "List all tracks in the library", "responses": { "200": { "description": "All tracks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Track" } } } } } } } }, "/tracks/{id}": { "get": { "operationId": "getTrack", "tags": ["Tracks"], "summary": "Get a track by id", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Track", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Track" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tracks/stream-metadata": { "put": { "operationId": "saveStreamTrackMetadata", "tags": ["Tracks"], "summary": "Persist metadata for an HTTP stream URL", "description": "Used by the player when a remote URL is loaded — saves title/artist/album/duration so the URL can be resolved from the DB later.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url", "title", "artist", "album", "duration_ms"], "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "artist": { "type": "string" }, "album": { "type": "string" }, "duration_ms": { "type": "integer", "format": "int32", "minimum": 0 } } } } } }, "responses": { "204": { "description": "Stored" } } } }, "/search": { "get": { "operationId": "search", "tags": ["Search"], "summary": "Full-text search powered by Typesense", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search term" } ], "responses": { "200": { "description": "Matching tracks, albums and artists", "content": { "application/json": { "schema": { "type": "object", "properties": { "tracks": { "type": "array", "items": { "$ref": "#/components/schemas/Track" } }, "albums": { "type": "array", "items": { "$ref": "#/components/schemas/Album" } }, "artists": { "type": "array", "items": { "$ref": "#/components/schemas/Artist" } } } } } } } } } }, "/browse/tree-entries": { "get": { "operationId": "getTreeEntries", "tags": ["Browse"], "summary": "Browse the filesystem under music_dir", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Path to list (absolute). Defaults to $ROCKBOX_LIBRARY or $HOME/Music." }, { "name": "show_hidden", "in": "query", "schema": { "type": "string", "enum": ["true", "false"] }, "description": "Show dotfiles (default false)" } ], "responses": { "200": { "description": "Directory entries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TreeEntry" } } } } }, "500": { "description": "Path is not a directory or other I/O error" } } } }, "/player": { "get": { "operationId": "getCurrentPlayer", "tags": ["Player"], "summary": "Get the current output device", "responses": { "200": { "description": "Current device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Device" } } } } } } }, "/player/load": { "put": { "operationId": "loadTracks", "tags": ["Player"], "summary": "Load tracks into an external player (Cast/AirPlay)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadTracks" } } } }, "responses": { "200": { "description": "Loaded" }, "404": { "description": "No external player connected or no playable tracks" } } } }, "/player/play": { "put": { "operationId": "play", "tags": ["Player"], "summary": "Start playback at an offset", "parameters": [ { "name": "elapsed", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Playback started" } } } }, "/player/pause": { "put": { "operationId": "pause", "tags": ["Player"], "summary": "Pause playback", "responses": { "200": { "description": "Paused" } } } }, "/player/resume": { "put": { "operationId": "resume", "tags": ["Player"], "summary": "Resume playback", "responses": { "200": { "description": "Resumed" } } } }, "/player/ff-rewind": { "put": { "operationId": "ffRewind", "tags": ["Player"], "summary": "Seek to an absolute position (ms)", "parameters": [{ "name": "newtime", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" } }], "responses": { "200": { "description": "Seeked" } } } }, "/player/status": { "get": { "operationId": "getStatus", "tags": ["Player"], "summary": "Get the playback status", "responses": { "200": { "description": "Audio status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioStatus" } } } } } } }, "/player/current-track": { "get": { "operationId": "getCurrentTrack", "tags": ["Player"], "summary": "Get the currently playing track", "responses": { "200": { "description": "Currently playing Mp3Entry, or null if nothing is playing", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Mp3Entry" }, { "type": "null" } ] } } } } } } }, "/player/next-track": { "get": { "operationId": "getNextTrack", "tags": ["Player"], "summary": "Get the next queued track", "responses": { "200": { "description": "Next Mp3Entry, or null if at end of queue", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Mp3Entry" }, { "type": "null" } ] } } } } } } }, "/player/flush-and-reload-tracks": { "put": { "operationId": "flushAndReloadTracks", "tags": ["Player"], "summary": "Flush PCM buffers and reload the current queue", "responses": { "200": { "description": "Reloaded" } } } }, "/player/next": { "put": { "operationId": "next", "tags": ["Player"], "summary": "Skip to the next track", "responses": { "200": { "description": "Skipped" } } } }, "/player/previous": { "put": { "operationId": "previous", "tags": ["Player"], "summary": "Skip to the previous track", "responses": { "200": { "description": "Skipped" } } } }, "/player/stop": { "put": { "operationId": "stop", "tags": ["Player"], "summary": "Hard-stop playback", "responses": { "200": { "description": "Stopped" } } } }, "/player/file-position": { "get": { "operationId": "getFilePosition", "tags": ["Player"], "summary": "Get the current byte offset in the playing file", "responses": { "200": { "description": "Byte offset", "content": { "application/json": { "schema": { "type": "integer", "format": "int64" } } } } } } }, "/player/volume": { "get": { "operationId": "getVolume", "tags": ["Player"], "summary": "Get current volume range and value", "responses": { "200": { "description": "Volume info", "content": { "application/json": { "schema": { "type": "object", "properties": { "volume": { "type": "integer", "format": "int32" }, "min": { "type": "integer", "format": "int32" }, "max": { "type": "integer", "format": "int32" } } } } } } } }, "put": { "operationId": "adjustVolume", "tags": ["Player"], "summary": "Adjust volume by N firmware-defined steps", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVolume" } } } }, "responses": { "200": { "description": "Adjusted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVolume" } } } } } } }, "/playlists": { "post": { "operationId": "createPlaylist", "tags": ["Playlist (queue)"], "summary": "Replace the live queue with a new playlist", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPlaylist" } } } }, "responses": { "200": { "description": "Start index of the new playlist (as plain text)", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/playlists/start": { "put": { "operationId": "startPlaylist", "tags": ["Playlist (queue)"], "summary": "Start playback at a queue index", "parameters": [ { "name": "start_index", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "elapsed", "in": "query", "schema": { "type": "integer", "format": "int64", "default": 0 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "format": "int64", "default": 0 } } ], "responses": { "200": { "description": "Started" } } } }, "/playlists/shuffle": { "put": { "operationId": "shufflePlaylist", "tags": ["Playlist (queue)"], "summary": "Shuffle the live queue", "parameters": [ { "name": "start_index", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 0 } } ], "responses": { "200": { "description": "Shuffle return code (text)", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/playlists/amount": { "get": { "operationId": "getPlaylistAmount", "tags": ["Playlist (queue)"], "summary": "Number of tracks in the live queue", "responses": { "200": { "description": "Amount", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "format": "int32" } } } } } } } } }, "/playlists/resume": { "put": { "operationId": "resumePlaylist", "tags": ["Playlist (queue)"], "summary": "Resume the saved control file playlist", "responses": { "200": { "description": "Status code", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" } } } } } } } } }, "/playlists/resume-track": { "put": { "operationId": "resumeTrack", "tags": ["Playlist (queue)"], "summary": "Resume the saved track at its previous offset", "responses": { "200": { "description": "Resumed" } } } }, "/playlists/{id}/tracks": { "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "get": { "operationId": "getPlaylistTracks", "tags": ["Playlist (queue)"], "summary": "List tracks currently in the queue", "responses": { "200": { "description": "Mp3Entry list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Mp3Entry" } } } } } } }, "post": { "operationId": "insertTracks", "tags": ["Playlist (queue)"], "summary": "Insert tracks into the live queue", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertTracks" } } } }, "responses": { "200": { "description": "Insertion position or 0 (text)", "content": { "text/plain": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "removeTracks", "tags": ["Playlist (queue)"], "summary": "Remove tracks from the live queue", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTracks" } } } }, "responses": { "200": { "description": "Result code (text)", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/playlists/{id}": { "get": { "operationId": "getPlaylist", "tags": ["Playlist (queue)"], "summary": "Get the live queue and its metadata", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "PlaylistInfo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistInfo" } } } } } } }, "/saved-playlists": { "get": { "operationId": "listSavedPlaylists", "tags": ["Saved playlists"], "summary": "List saved playlists, optionally filtered by folder", "parameters": [ { "name": "folder_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saved playlists", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SavedPlaylist" } } } } } } }, "post": { "operationId": "createSavedPlaylist", "tags": ["Saved playlists"], "summary": "Create a saved playlist", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "folder_id": { "type": "string" }, "track_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedPlaylist" } } } }, "400": { "description": "Missing required fields" } } } }, "/saved-playlists/{id}": { "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "get": { "operationId": "getSavedPlaylist", "tags": ["Saved playlists"], "summary": "Get a saved playlist", "responses": { "200": { "description": "Saved playlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedPlaylist" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateSavedPlaylist", "tags": ["Saved playlists"], "summary": "Update a saved playlist's metadata", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "folder_id": { "type": "string" } } } } } }, "responses": { "204": { "description": "Updated" } } }, "delete": { "operationId": "deleteSavedPlaylist", "tags": ["Saved playlists"], "summary": "Delete a saved playlist", "responses": { "204": { "description": "Deleted" } } } }, "/saved-playlists/{id}/tracks": { "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "get": { "operationId": "getSavedPlaylistTracks", "tags": ["Saved playlists"], "summary": "List tracks in a saved playlist", "responses": { "200": { "description": "Tracks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Track" } } } } } } }, "post": { "operationId": "addTracksToSavedPlaylist", "tags": ["Saved playlists"], "summary": "Add tracks to a saved playlist", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["track_ids"], "properties": { "track_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "204": { "description": "Added" } } } }, "/saved-playlists/{id}/track-ids": { "get": { "operationId": "getSavedPlaylistTrackIds", "tags": ["Saved playlists"], "summary": "List track ids in a saved playlist", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Track ids", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } } } } }, "/saved-playlists/{id}/tracks/{track_id}": { "delete": { "operationId": "removeTrackFromSavedPlaylist", "tags": ["Saved playlists"], "summary": "Remove a track from a saved playlist", "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed" } } } }, "/saved-playlists/{id}/play": { "post": { "operationId": "playSavedPlaylist", "tags": ["Saved playlists"], "summary": "Load a saved playlist into the queue and start playing", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "204": { "description": "Started" }, "422": { "description": "Empty playlist or unresolved tracks" } } } }, "/saved-playlists/folders": { "get": { "operationId": "listPlaylistFolders", "tags": ["Saved playlists"], "summary": "List playlist folders", "responses": { "200": { "description": "Folders", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlaylistFolder" } } } } } } }, "post": { "operationId": "createPlaylistFolder", "tags": ["Saved playlists"], "summary": "Create a playlist folder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistFolder" } } } } } } }, "/saved-playlists/folders/{id}": { "delete": { "operationId": "deletePlaylistFolder", "tags": ["Saved playlists"], "summary": "Delete a playlist folder", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "204": { "description": "Deleted" } } } }, "/smart-playlists": { "get": { "operationId": "listSmartPlaylists", "tags": ["Smart playlists"], "summary": "List smart playlists", "responses": { "200": { "description": "Smart playlists", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SmartPlaylist" } } } } } } }, "post": { "operationId": "createSmartPlaylist", "tags": ["Smart playlists"], "summary": "Create a smart playlist with a rule criteria", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "rules"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "folder_id": { "type": "string" }, "rules": { "$ref": "#/components/schemas/RuleCriteria" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartPlaylist" } } } }, "400": { "description": "Missing required fields" } } } }, "/smart-playlists/{id}": { "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "get": { "operationId": "getSmartPlaylist", "tags": ["Smart playlists"], "summary": "Get a smart playlist", "responses": { "200": { "description": "Smart playlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartPlaylist" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateSmartPlaylist", "tags": ["Smart playlists"], "summary": "Update a smart playlist", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "rules"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "folder_id": { "type": "string" }, "rules": { "$ref": "#/components/schemas/RuleCriteria" } } } } } }, "responses": { "204": { "description": "Updated" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteSmartPlaylist", "tags": ["Smart playlists"], "summary": "Delete a smart playlist", "responses": { "204": { "description": "Deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/smart-playlists/{id}/tracks": { "get": { "operationId": "getSmartPlaylistTracks", "tags": ["Smart playlists"], "summary": "Resolve a smart playlist to its current matching tracks", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Resolved tracks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Track" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/smart-playlists/{id}/play": { "post": { "operationId": "playSmartPlaylist", "tags": ["Smart playlists"], "summary": "Resolve a smart playlist and start playing its tracks", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "204": { "description": "Started" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Resolves to zero tracks" } } } }, "/track-stats/{id}": { "get": { "operationId": "getTrackStats", "tags": ["Track stats"], "summary": "Get listening stats for a track", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Track stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackStats" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/track-stats/{id}/played": { "post": { "operationId": "recordTrackPlayed", "tags": ["Track stats"], "summary": "Record a 'played' event for a track", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "204": { "description": "Recorded" } } } }, "/track-stats/{id}/skipped": { "post": { "operationId": "recordTrackSkipped", "tags": ["Track stats"], "summary": "Record a 'skipped' event for a track", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "204": { "description": "Recorded" } } } }, "/devices": { "get": { "operationId": "getDevices", "tags": ["Devices"], "summary": "List all known output devices (discovered + virtual)", "responses": { "200": { "description": "Devices", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } } } } } } } }, "/devices/{id}": { "get": { "operationId": "getDevice", "tags": ["Devices"], "summary": "Get a device by id (use 'current' for the active sink)", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Device" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/devices/{id}/connect": { "put": { "operationId": "connectDevice", "tags": ["Devices"], "summary": "Switch the active sink to this device", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Connected" }, "400": { "description": "Unknown device service" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/devices/{id}/disconnect": { "put": { "operationId": "disconnectDevice", "tags": ["Devices"], "summary": "Disconnect the active device and revert to builtin", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "responses": { "200": { "description": "Disconnected" } } } }, "/settings": { "get": { "operationId": "getSettings", "tags": ["Settings"], "summary": "Get the global settings (in-memory snapshot)", "responses": { "200": { "description": "Settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalSettings" } } } } } }, "put": { "operationId": "updateSettings", "tags": ["Settings"], "summary": "Apply a partial settings update and persist to settings.toml", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewGlobalSettings" } } } }, "responses": { "204": { "description": "Saved" } } } }, "/version": { "get": { "operationId": "getVersion", "tags": ["System"], "summary": "Get the running rockboxd version", "responses": { "200": { "description": "Version", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/status": { "get": { "operationId": "getGlobalStatus", "tags": ["System"], "summary": "Get global runtime status", "responses": { "200": { "description": "Global status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalStatus" } } } } } } }, "/scan-library": { "put": { "operationId": "scanLibrary", "tags": ["System"], "summary": "Trigger a library scan and (optionally) rebuild the search index", "parameters": [ { "name": "path", "in": "query", "schema": { "type": "string" }, "description": "Path to scan; defaults to $HOME/Music" }, { "name": "rebuild_index", "in": "query", "schema": { "type": "string", "enum": ["true", "false", "1", "0"] }, "description": "Re-build the Typesense collections" } ], "responses": { "200": { "description": "Scan started/complete (returns '0' on success)", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "tags": ["System"], "summary": "Get this OpenAPI document", "responses": { "200": { "description": "OpenAPI spec", "content": { "application/json": {} } } } } }, "/bluetooth/scan": { "post": { "operationId": "scanBluetooth", "tags": ["Bluetooth"], "summary": "Scan for Bluetooth devices (Linux only)", "parameters": [ { "name": "timeout_secs", "in": "query", "schema": { "type": "integer", "format": "int64", "default": 10 } } ], "responses": { "200": { "description": "Discovered devices", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BluetoothDevice" } } } } } } } }, "/bluetooth/devices": { "get": { "operationId": "getBluetoothDevices", "tags": ["Bluetooth"], "summary": "List paired Bluetooth devices (Linux only)", "responses": { "200": { "description": "Devices", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BluetoothDevice" } } } } } } } }, "/bluetooth/devices/{addr}/connect": { "put": { "operationId": "connectBluetoothDevice", "tags": ["Bluetooth"], "summary": "Connect to a paired Bluetooth device (Linux only)", "parameters": [{ "name": "addr", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Connected" }, "500": { "description": "Bluez error" } } } }, "/bluetooth/devices/{addr}/disconnect": { "put": { "operationId": "disconnectBluetoothDevice", "tags": ["Bluetooth"], "summary": "Disconnect a Bluetooth device (Linux only)", "parameters": [{ "name": "addr", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Disconnected" }, "500": { "description": "Bluez error" } } } } }, "components": { "parameters": { "IdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } }, "responses": { "NotFound": { "description": "Not found" } }, "schemas": { "Album": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "artist": { "type": "string" }, "year": { "type": "integer", "format": "int32", "nullable": true }, "year_string": { "type": "string", "nullable": true }, "artist_id": { "type": "string" }, "md5": { "type": "string" }, "album_art": { "type": "string", "nullable": true } } }, "Artist": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "image":{ "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true } } }, "Track": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "title": { "type": "string" }, "artist": { "type": "string" }, "album": { "type": "string" }, "album_artist": { "type": "string" }, "composer": { "type": "string" }, "genre": { "type": "string", "nullable": true }, "year": { "type": "integer", "format": "int64", "nullable": true }, "year_string": { "type": "string", "nullable": true }, "track_number": { "type": "integer", "format": "int64", "nullable": true }, "disc_number": { "type": "integer", "format": "int64" }, "length": { "type": "integer", "format": "int64", "description": "Duration in milliseconds" }, "filesize": { "type": "integer", "format": "int64" }, "bitrate": { "type": "integer", "format": "int64" }, "frequency": { "type": "integer", "format": "int64" }, "album_id": { "type": "string" }, "artist_id": { "type": "string" }, "genre_id": { "type": "string" }, "album_art": { "type": "string", "nullable": true }, "md5": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TreeEntry": { "type": "object", "properties": { "name": { "type": "string", "description": "Absolute path" }, "time_write": { "type": "integer", "format": "int64", "description": "Unix timestamp of last modification" }, "attr": { "type": "integer", "format": "int32", "description": "0x10 = directory" } } }, "Mp3Entry": { "type": "object", "description": "Rockbox firmware-side representation of a playing or queued track", "properties": { "path": { "type": "string" }, "title": { "type": "string" }, "artist": { "type": "string" }, "album": { "type": "string" }, "albumartist": { "type": "string" }, "composer": { "type": "string" }, "genre_string": { "type": "string" }, "tracknum": { "type": "integer", "format": "int32" }, "discnum": { "type": "integer", "format": "int32" }, "year": { "type": "integer", "format": "int32" }, "year_string": { "type": "string" }, "length": { "type": "integer", "format": "int64", "description": "Duration in milliseconds" }, "elapsed": { "type": "integer", "format": "int64", "description": "Current position in milliseconds" }, "filesize": { "type": "integer", "format": "int64" }, "bitrate": { "type": "integer", "format": "int64" }, "frequency": { "type": "integer", "format": "int64" }, "id": { "type": "string", "nullable": true }, "album_id": { "type": "string", "nullable": true }, "artist_id": { "type": "string", "nullable": true }, "genre_id": { "type": "string", "nullable": true }, "album_art": { "type": "string", "nullable": true } } }, "AudioStatus": { "type": "object", "properties": { "status": { "type": "integer", "format": "int32", "description": "0 = stopped, 1 = playing, 2 = paused (bitfield)" } } }, "Device": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "host": { "type": "string" }, "ip": { "type": "string" }, "port": { "type": "integer", "format": "int32" }, "service": { "type": "string", "description": "builtin | fifo | airplay | squeezelite | upnp | chromecast | snapcast" }, "app": { "type": "string" }, "is_connected": { "type": "boolean" }, "is_cast_device": { "type": "boolean" }, "is_source_device": { "type": "boolean" }, "is_current_device": { "type": "boolean" }, "base_url": { "type": "string", "nullable": true } } }, "LoadTracks": { "type": "object", "required": ["tracks"], "properties": { "tracks": { "type": "array", "items": { "type": "string" }, "description": "Track paths or HTTP URLs" }, "shuffle": { "type": "boolean" } } }, "InsertTracks": { "type": "object", "required": ["tracks", "position"], "properties": { "tracks": { "type": "array", "items": { "type": "string" } }, "directory": { "type": "string", "description": "Insert all audio files under this directory instead of an explicit list" }, "position": { "type": "integer", "format": "int32", "description": "0=Next, 1=After current, 2=Last, 3=First/replace, 7=LastShuffled" } } }, "DeleteTracks": { "type": "object", "required": ["positions"], "properties": { "positions": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Empty array clears the entire queue" } } }, "NewPlaylist": { "type": "object", "required": ["tracks"], "properties": { "name": { "type": "string" }, "tracks": { "type": "array", "items": { "type": "string" } } } }, "PlaylistInfo": { "type": "object", "properties": { "amount": { "type": "integer", "format": "int32" }, "index": { "type": "integer", "format": "int32" }, "max_playlist_size": { "type": "integer", "format": "int32" }, "first_index": { "type": "integer", "format": "int32" }, "last_insert_pos": { "type": "integer", "format": "int32" }, "seed": { "type": "integer", "format": "int32" }, "last_shuffled_start": { "type": "integer", "format": "int32" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Mp3Entry" } } } }, "NewVolume": { "type": "object", "required": ["steps"], "properties": { "steps": { "type": "integer", "format": "int32", "description": "Positive = louder, negative = quieter" } } }, "SavedPlaylist": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "image": { "type": "string", "nullable": true }, "folder_id": { "type": "string", "nullable": true }, "track_count": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PlaylistFolder": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "SmartPlaylist": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "image": { "type": "string", "nullable": true }, "folder_id": { "type": "string", "nullable": true }, "rules": { "$ref": "#/components/schemas/RuleCriteria" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RuleCriteria": { "type": "object", "description": "Smart-playlist rule set. See `crates/playlists/src/rules.rs` for the canonical definition.", "properties": { "operator": { "type": "string", "enum": ["AND", "OR"], "default": "AND" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "play_count | skip_count | last_played | year | duration_ms | genre | artist | …" }, "op": { "type": "string", "description": "eq | ne | gt | gte | lt | lte | contains | within | not_within" }, "value": {} } } }, "sort": { "type": "object", "nullable": true, "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": ["asc", "desc"] } } }, "limit": { "type": "integer", "format": "int32", "nullable": true } } }, "TrackStats": { "type": "object", "properties": { "track_id": { "type": "string" }, "play_count": { "type": "integer", "format": "int64" }, "skip_count": { "type": "integer", "format": "int64" }, "last_played": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix timestamp" }, "last_skipped": { "type": "integer", "format": "int64", "nullable": true } } }, "GlobalSettings": { "type": "object", "description": "Live `global_settings` snapshot. Fields mirror `apps/settings.h`.", "additionalProperties": true, "properties": { "music_dir": { "type": "string" }, "audio_output": { "type": "string", "enum": ["builtin", "fifo", "airplay", "squeezelite", "chromecast", "snapcast_tcp", "upnp"] }, "volume": { "type": "integer", "format": "int32" }, "volume_limit": { "type": "integer", "format": "int32" }, "balance": { "type": "integer", "format": "int32" }, "channel_config": { "type": "integer", "format": "int32" }, "stereo_width": { "type": "integer", "format": "int32" }, "playlist_shuffle": { "type": "boolean" }, "repeat_mode": { "type": "integer", "format": "int32" }, "crossfade": { "type": "integer", "format": "int32" }, "eq_enabled": { "type": "boolean" }, "eq_precut": { "type": "integer", "format": "int32" }, "eq_band_settings": { "type": "array", "items": { "$ref": "#/components/schemas/EqBandSetting" } }, "replaygain_settings": { "$ref": "#/components/schemas/ReplaygainSettings" }, "compressor_settings": { "$ref": "#/components/schemas/CompressorSettings" } } }, "NewGlobalSettings": { "type": "object", "description": "Partial settings update — only the fields you set are written.", "additionalProperties": true }, "EqBandSetting": { "type": "object", "properties": { "cutoff": { "type": "integer", "format": "int32", "description": "Centre / cutoff frequency in Hz" }, "q": { "type": "integer", "format": "int32", "description": "Q × 10 (fixed-point)" }, "gain": { "type": "integer", "format": "int32", "description": "Gain × 10 in dB (fixed-point)" } } }, "ReplaygainSettings": { "type": "object", "properties": { "noclip": { "type": "boolean" }, "type": { "type": "integer", "format": "int32", "description": "0=Track 1=Album 2=Track-shuffle 3=Off" }, "preamp": { "type": "integer", "format": "int32", "description": "dB × 10" } } }, "CompressorSettings": { "type": "object", "properties": { "threshold": { "type": "integer", "format": "int32", "description": "dB" }, "makeup_gain": { "type": "integer", "format": "int32" }, "ratio": { "type": "integer", "format": "int32" }, "knee": { "type": "integer", "format": "int32" }, "release_time": { "type": "integer", "format": "int32", "description": "ms" }, "attack_time": { "type": "integer", "format": "int32", "description": "ms" } } }, "GlobalStatus": { "type": "object", "additionalProperties": true, "properties": { "resume_index": { "type": "integer", "format": "int32" }, "resume_offset": { "type": "integer", "format": "int64" }, "resume_elapsed": { "type": "integer", "format": "int64" }, "resume_crc32": { "type": "integer", "format": "int64" }, "resume_pitch": { "type": "integer", "format": "int32" }, "resume_speed": { "type": "integer", "format": "int32" }, "runtime": { "type": "integer", "format": "int64" }, "topruntime": { "type": "integer", "format": "int64" }, "volume": { "type": "integer", "format": "int32" } } }, "BluetoothDevice": { "type": "object", "properties": { "address": { "type": "string" }, "name": { "type": "string" }, "rssi": { "type": "integer", "format": "int32", "nullable": true }, "is_paired": { "type": "boolean" }, "is_connected": { "type": "boolean" } } } } }}