{ "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" } }, "example": [ { "id": "cmodxew8w0053pdmdmro8vx0w", "title": "2014 Forest Hills Drive", "artist": "J. Cole", "year": 2014, "year_string": "2014-12-09", "album_art": "216ccc791352fbbffc11268b984db19a.jpg", "md5": "7efed3c16a2ea54a2c090e40f03107d4", "artist_id": "cmodw19po0005pdmd6k9mwauv", "label": null, "copyright_message": "℗ 2014 Cole World/Interscope Records" }, { "id": "cmjodpk0r00j8pdoc5r5eko46", "title": "21 Reasons (feat. Ella Henderson)", "artist": "Nathan Dawe", "year": 2019, "year_string": "2019-05-31", "album_art": "53682046896b8c9c6118c169cfd03ff8.jpg", "md5": "3997d22d81a895c867827ef6f4f83477", "artist_id": "cmjodpk0r00j7pdocuh1vu2vx", "label": null, "copyright_message": "under exclusive licence to Warner Music UK Limited, ℗ 2020 Nathan Dawe" } ] } } } } } }, "/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" }, "example": { "album_art": "fd2f91b0204eb7d7bb57573c86d9511d.jpg", "artist": "Charli xcx", "artist_id": "cmfcfqx3w002dwg08lrasptzo", "copyright_message": null, "id": "cmffj228r0009wgc76zjd7rtr", "label": null, "md5": "2896ca6b64216f891514d2d746754ea1", "title": "how i'm feeling now", "year": 2020, "year_string": "2020-05-15" } } } }, "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" } }, "example": [ { "id": "cmodxew97005epdmdvt8ar73r", "path": "/Users/tsirysandratraina/Music/J. Cole - 2014 Forest Hills Drive (Explicit)/01. J. Cole - Intro (Explicit).m4a", "title": "Intro", "artist": "J. Cole", "album": "2014 Forest Hills Drive", "album_artist": "J. Cole", "bitrate": 320, "composer": "", "disc_number": 1, "filesize": 5168762, "frequency": 44100, "length": 129199, "track_number": 1, "year": 2014, "year_string": "2014-12-09", "md5": "07576ce8ea7906aa36bf05ae93cb1643", "album_art": "216ccc791352fbbffc11268b984db19a.jpg", "artist_id": "cmodw19po0005pdmd6k9mwauv", "album_id": "cmodxew8w0053pdmdmro8vx0w", "genre_id": "", "is_remote": false, "created_at": 1777096568, "updated_at": 1777096568 }, { "id": "cmodxew9a005opdmddc5l9y63", "path": "/Users/tsirysandratraina/Music/J. Cole - 2014 Forest Hills Drive (Explicit)/02. J. Cole - January 28th (Explicit).m4a", "title": "January 28th", "artist": "J. Cole", "album": "2014 Forest Hills Drive", "album_artist": "J. Cole", "bitrate": 320, "composer": "", "disc_number": 1, "filesize": 9710586, "frequency": 44100, "length": 242744, "track_number": 2, "year": 2014, "year_string": "2014-12-09", "md5": "e6914133fcbcf8771fbf156c485b8459", "album_art": "216ccc791352fbbffc11268b984db19a.jpg", "artist_id": "cmodw19po0005pdmd6k9mwauv", "album_id": "cmodxew8w0053pdmdmro8vx0w", "genre_id": "", "is_remote": false, "created_at": 1777096568, "updated_at": 1777096568 } ] } } } } } }, "/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" } }, "example": [ { "id": "cmjftbrug03ipsl3jo6fggigk", "name": "A Perfect Circle", "image": "https://i.scdn.co/image/ab6761610000e5eb41472573351dfea479a4ffba", "genres": "alternative metal" }, { "id": "cmo7132f7006epdouye8onwe7", "name": "Ab-Soul, Anderson .Paak, James Blake" } ] } } } } } }, "/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" }, "example": { "genres": "", "id": "cm5zvhb1h000owg6dqxnn66bp", "image": "https://i.scdn.co/image/ab6761610000e5eb9e528993a2820267b97f6aae", "name": "The Weeknd" } } } }, "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" } }, "example": [ { "id": "cmodxew8w0053pdmdmro8vx0w", "title": "2014 Forest Hills Drive", "artist": "J. Cole", "year": 2014, "year_string": "2014-12-09", "album_art": "216ccc791352fbbffc11268b984db19a.jpg", "md5": "7efed3c16a2ea54a2c090e40f03107d4", "artist_id": "cmodw19po0005pdmd6k9mwauv", "label": null, "copyright_message": "℗ 2014 Cole World/Interscope Records" }, { "id": "cmodw1a5l003dpdmd39obvgay", "title": "Might Delete Later", "artist": "J. Cole", "year": 2024, "year_string": "2024-04-05", "album_art": "85b108fff8d0cabd396a2e79885f2752.jpg", "md5": "ddbdd86c1fc7e7f1b5b901d83c83aaf2", "artist_id": "cmodw19po0005pdmd6k9mwauv", "label": null, "copyright_message": "℗ 2024 Cole World, Inc., under exclusive license to Interscope Records" } ] } } } } } }, "/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" } }, "example": [ { "id": "cmodxew9o006spdmdnhqjh8ab", "path": "/Users/tsirysandratraina/Music/J. Cole - 2014 Forest Hills Drive (Explicit)/04. J. Cole - 03’ Adolescence (Explicit).m4a", "title": "03’ Adolescence", "artist": "J. Cole", "album": "2014 Forest Hills Drive", "album_artist": "J. Cole", "bitrate": 320, "composer": "", "disc_number": 1, "filesize": 10570653, "frequency": 44100, "length": 264259, "track_number": 4, "year": 2014, "year_string": "2014-12-09", "md5": "0edf984c5a9cb95e6d9003b47f10e991", "album_art": "216ccc791352fbbffc11268b984db19a.jpg", "artist_id": "cmodw19po0005pdmd6k9mwauv", "album_id": "cmodxew8w0053pdmdmro8vx0w", "genre_id": "", "is_remote": false, "created_at": 1777096568, "updated_at": 1777096568 }, { "id": "cmodw19qb002apdmd476zdpfv", "path": "/Users/tsirysandratraina/Music/J. Cole - The Fall-Off (Explicit)/101. J. Cole - 29 Intro (Explicit).m4a", "title": "29 Intro", "artist": "J. Cole", "album": "The Fall-Off", "album_artist": "J. Cole", "bitrate": 320, "composer": "", "disc_number": 1, "filesize": 2311779, "frequency": 44100, "length": 57779, "track_number": 1, "year": 2026, "year_string": "2026-02-06", "md5": "72ee494cab9aba116e2fe724e347dc59", "album_art": "20a95234ea29a20884f5c6a1ef5ad592.jpg", "artist_id": "cmodw19po0005pdmd6k9mwauv", "album_id": "cmodw19pi0001pdmdv76spfpp", "genre_id": "", "is_remote": false, "created_at": 1777094253, "updated_at": 1777094253 } ] } } } } } }, "/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" } }, "example": [ { "id": "cmnvrqv4k002zpdwax7lrsbhh", "path": "/Users/tsirysandratraina/Music/Juicy J - The Trippy Tapes Vol. 1 (Explicit)/26. Juicy J, DJ Scream, Babyfxce E - Scotty (feat. Babyfxce E ) (Explicit).m4a", "title": " Scotty (feat. Babyfxce E )", "artist": "Juicy J, DJ Scream, Babyfxce E", "album": "The Trippy Tapes Vol. 1", "album_artist": "Juicy J, DJ Scream", "bitrate": 320, "composer": "", "disc_number": 1, "filesize": 6746791, "frequency": 44100, "length": 168664, "track_number": 26, "year": 2026, "year_string": "2026-04-03", "md5": "b418a0d44e61ef179005ff9a13d5c8bd", "album_art": "8c8b3a145776af32d29ea293691ecaa8.jpg", "artist_id": "cmnvrqv3b0000pdwaux8uj1d2", "album_id": "cmnvrqv3b0001pdwatmcq1aqt", "genre_id": "", "is_remote": false, "created_at": 1775998658, "updated_at": 1775998658 } ] } } } } } }, "/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" }, "example": { "album": "Birds In The Trap Sing McKnight", "album_art": "89cb92505e4bbe0560bbcda6280a202a.jpg", "album_artist": "Travis Scott", "album_id": "cm5zvhb22009lwg6dnvablpbc", "artist": "Travis Scott", "artist_id": "cm5zvhb21008ewg6dvgqsa9rx", "bitrate": 320, "composer": "Mike Dean, Matthew Samuels, Tyler Williams, Jacques Webster, Abel \"The Weeknd\" Tesfaye", "created_at": 1737064715, "disc_number": 1, "filesize": 8680548, "frequency": 44100, "genre_id": "", "id": "cm5zvhcnd02olwg6dxlapwu92", "is_remote": false, "length": 216991, "md5": "961b2782d0910101aa5d6c90b49f077e", "path": "/home/tsiry/Music/Travis Scott/[E] Birds In The Trap Sing McKnight [64819399] [2016]/14 - Travis Scott - wonderful(Explicit).m4a", "title": "wonderful", "track_number": 14, "updated_at": 1737064715, "year": 2016, "year_string": "2016-09-03" } } } }, "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" } } } }, "example": { "albums": [ { "album_art": "5e35f1a2c80de5a6cb3f27132f3f81ea.jpg", "artist": "Charli xcx", "artist_id": "cmfcfqx3w002dwg08lrasptzo", "id": "cmffj228r0007wgc70wuvimfc", "label": null, "md5": "d15421a438be924a9d24969e3b3b3fbc", "title": "Charli", "year": 2019, "year_string": "2019-09-13" }, { "album_art": "0cba3a84d1c43731303a54dc03e3e852.jpg", "artist": "Charli xcx", "artist_id": "cmfcfqx3w002dwg08lrasptzo", "id": "cmfpe1csg0008wguw7f4v18j2", "label": null, "md5": "e46ac9be6763f80e7bcf4328db202e50", "title": "SUCKER", "year": 2014, "year_string": "2014-12-16" } ], "artists": [], "tracks": [] } } } } } } }, "/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" } }, "example": [ { "name": "/Users/tsirysandratraina/Music/Union Of Sound - Acoustic - A Quiet Night In (Explicit)", "attr": 16, "time_write": 1768805953, "customaction": 0 }, { "name": "/Users/tsirysandratraina/Music/Media.localized", "attr": 16, "time_write": 1766757435, "customaction": 0 }, { "name": "/Users/tsirysandratraina/Music/Cannons - Up All Night EP", "attr": 16, "time_write": 1766430051, "customaction": 0 } ] } } }, "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" }, "example": { "app": "Snapcast", "base_url": null, "host": "192.168.1.220", "id": "snapcast-192.168.1.220", "ip": "192.168.1.220", "is_cast_device": true, "is_connected": false, "is_current_device": true, "is_source_device": false, "name": "Snapcast (192.168.1.220)", "port": 4953, "service": "snapcast" } } } } } } }, "/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" } }, "example": [ { "path": "/Users/tsirysandratraina/Music/Cannons - All I Need/1. Cannons - All I Need.m4a", "title": "All I Need", "artist": "Cannons", "album": "All I Need", "albumartist": "Cannons", "composer": "", "genre_string": "", "tracknum": 1, "discnum": 1, "year": 2025, "year_string": "2025-10-17", "length": 227073, "elapsed": 0, "filesize": 9083647, "bitrate": 320, "frequency": 44100, "id": null, "album_id": null, "artist_id": null, "genre_id": null, "album_art": null } ] } } } } }, "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" }, "example": { "amount": 1, "index": 0, "first_index": 0, "last_insert_pos": 0, "max_playlist_size": 10000, "seed": 0, "last_shuffled_start": 0, "entries": [ { "path": "/Users/tsirysandratraina/Music/Cannons - All I Need/1. Cannons - All I Need.m4a", "title": "All I Need", "artist": "Cannons", "album": "All I Need", "albumartist": "Cannons", "composer": "", "genre_string": "", "tracknum": 1, "discnum": 1, "year": 2025, "year_string": "2025-10-17", "length": 227073, "elapsed": 0, "filesize": 9083647, "bitrate": 320, "frequency": 44100, "id": "cmjhiwtrq002vslny83sh3cpc", "album_id": "cmjhiwtr6002fslnyzl17c1rn", "artist_id": "cmjhiwtqz0003slnyk5x8akqo", "genre_id": "", "album_art": "b0cf2a54ef92afc1796c506f641f8b68.jpg" } ] } } } } } } }, "/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" } }, "example": [ { "id": "68920507-2d77-4a89-afae-79626f570ad0", "name": "rap", "description": null, "image": null, "folder_id": null, "track_count": 1, "created_at": 1777133688, "updated_at": 1777135103 } ] } } } } }, "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" } }, "example": [ { "id": "cmodxew9c005tpdmde8b4v7jn", "path": "/Users/tsirysandratraina/Music/J. Cole - 2014 Forest Hills Drive (Explicit)/06. J. Cole - Fire Squad (Explicit).m4a", "title": "Fire Squad", "artist": "J. Cole", "album": "2014 Forest Hills Drive", "album_artist": "J. Cole", "bitrate": 320, "composer": "", "disc_number": 1, "filesize": 11527315, "frequency": 44100, "length": 288169, "track_number": 6, "year": 2014, "year_string": "2014-12-09", "md5": "cffdfee6f1cccb4f25581f9f4f4820d3", "album_art": "216ccc791352fbbffc11268b984db19a.jpg", "artist_id": "cmodw19po0005pdmd6k9mwauv", "album_id": "cmodxew8w0053pdmdmro8vx0w", "genre_id": "", "is_remote": false, "created_at": 1777096568, "updated_at": 1777096568 } ] } } } } }, "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" } }, "example": [ { "created_at": 1777348193, "description": "A shuffle of your 90s music.", "folder_id": null, "id": "sys_90s_mix", "image": null, "is_system": true, "name": "90s Mix", "rules": { "conditions": [ { "field": "year", "operator": "greater_than_or_equal", "unit": null, "value": 1990, "value2": null }, { "field": "year", "operator": "less_than_or_equal", "unit": null, "value": 1999, "value2": null } ], "limit": 50, "match_type": "all", "sort_by": "random", "sort_order": "DESC" }, "updated_at": 1777348193 } ] } } } } }, "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" } }, "example": [ { "id": "builtin", "name": "Rockbox (Built-in)", "host": "localhost", "ip": "127.0.0.1", "port": 0, "service": "builtin", "app": "builtin", "is_connected": false, "base_url": null, "is_cast_device": false, "is_source_device": false, "is_current_device": true }, { "id": "fifo", "name": "Snapcast (FIFO)", "host": "localhost", "ip": "127.0.0.1", "port": 0, "service": "fifo", "app": "fifo", "is_connected": false, "base_url": null, "is_cast_device": false, "is_source_device": false, "is_current_device": false }, { "id": "squeezelite", "name": "Squeezelite", "host": "localhost", "ip": "127.0.0.1", "port": 3483, "service": "squeezelite", "app": "squeezelite", "is_connected": false, "base_url": null, "is_cast_device": false, "is_source_device": false, "is_current_device": false }, { "id": "158759fe25f1a23ac2e12721b038e860", "name": "Salon TV", "host": "158759fe-25f1-a23a-c2e1-2721b038e860.local", "ip": "192.168.1.60", "port": 8009, "service": "chromecast", "app": "chromecast", "is_connected": false, "base_url": null, "is_cast_device": true, "is_source_device": false, "is_current_device": false }, { "id": "snapcast-192.168.1.220", "name": "Snapcast", "host": "pi4-2.local", "ip": "192.168.1.220", "port": 4953, "service": "snapcast", "app": "Snapcast", "is_connected": false, "base_url": null, "is_cast_device": true, "is_source_device": false, "is_current_device": false }, { "id": "92736CF1CD65@Pi4._raop._tcp.local.", "name": "Pi4", "host": "pi4-2.local", "ip": "192.168.1.220", "port": 5000, "service": "airplay", "app": "AirPlay", "is_connected": false, "base_url": null, "is_cast_device": true, "is_source_device": false, "is_current_device": false } ] } } } } } }, "/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" }, "example": { "id": "builtin", "name": "Rockbox (Built-in)", "host": "localhost", "ip": "127.0.0.1", "port": 0, "service": "builtin", "app": "builtin", "is_connected": false, "base_url": null, "is_cast_device": false, "is_source_device": false, "is_current_device": true } } } }, "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" }, "example": { "music_dir": "/Users/tsirysandratraina/Music", "volume_limit": 320, "balance": 0, "bass": 1, "treble": 0, "channel_config": 0, "stereo_width": 100, "crossfade": 5, "crossfade_fade_in_delay": 7, "crossfade_fade_out_delay": 7, "crossfade_fade_in_duration": 1, "crossfade_fade_out_duration": 1, "playlist_shuffle": false, "repeat_mode": 846620009, "eq_enabled": true, "eq_precut": 7, "eq_band_settings": [ { "cutoff": -16, "q": 64, "gain": 10 }, { "cutoff": 9, "q": 125, "gain": 10 }, { "cutoff": 21, "q": 250, "gain": 10 }, { "cutoff": 9, "q": 500, "gain": 10 }, { "cutoff": -35, "q": 1000, "gain": 10 }, { "cutoff": -81, "q": 2000, "gain": 10 }, { "cutoff": -41, "q": 4000, "gain": 10 }, { "cutoff": 1, "q": 8000, "gain": 10 }, { "cutoff": 15, "q": 16000, "gain": 7 }, { "cutoff": 24, "q": 0, "gain": 0 } ], "replaygain_settings": { "noclip": true, "type": 0, "preamp": 0 }, "compressor_settings": { "threshold": -24, "makeup_gain": 0, "ratio": 4, "knee": 1, "release_time": 300, "attack_time": 5 }, "dithering_enabled": true, "timestretch_enabled": false, "play_frequency": 3400, "surround_enabled": 0, "surround_balance": -25 } } } } } }, "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" }, "example": { "volume": 0, "resume_index": 0, "resume_crc32": 3654789000, "resume_elapsed": 0, "resume_offset": 0, "runtime": 10000, "topruntime": 10000, "dircache_size": 1016, "last_screen": -8, "viewer_icon_count": -1, "last_volume_change": 0 } } } } } } }, "/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" } }, "example": [ { "address": "56:64:C4:EE:EE:7B", "connected": false, "name": "Beats Studio Pro", "paired": true, "rssi": null, "trusted": true }, { "address": "D8:E0:E1:13:96:DD", "connected": false, "name": "[AV] Samsung Soundbar K450 K-Series", "paired": true, "rssi": null, "trusted": true } ] } } } } } }, "/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" }, "customaction": { "type": "integer", "format": "int32" } } }, "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 }, "paired": { "type": "boolean" }, "connected": { "type": "boolean" }, "trusted": { "type": "boolean" } } } } } }