openapi: 3.0.3 info: title: Sonda API version: 0.1.0 description: | Sonda is a privacy-first, self-hosted music server. This is its first-party REST API. **Authentication.** Log in with `POST /auth/login` and send the access token as `Authorization: Bearer `. Access tokens are short-lived; renew the session with `POST /auth/refresh`. Each refresh token works once. **Roles.** Operations marked *admin* need an account with the admin role. The first user who registers is the admin. **Errors.** Every error has the same shape: `{"error": {"code": "...", "message": "..."}}`. The `code` is stable and meant for programs; the `message` is for people. **Paging.** Lists take `limit` (default 50, at most 200; a larger value is lowered to 200) and `offset`, and answer with `items`, `total`, `limit` and `offset`. servers: - url: /api/v1 tags: - name: System - name: Auth description: Accounts and sessions. - name: Users description: User management (admin). - name: Libraries description: Named folders of music (admin). - name: Scan description: Indexing the libraries. - name: Catalog description: Browsing and searching what can be played. - name: Playback description: Streaming and listening history. - name: Taste description: What Sonda has learned from your listening, and the settings that are yours. - name: Playlists description: Ordered lists of tracks that belong to one user. - name: Mixes description: Playlists made for you, from what you listen to and from the genres of your music. - name: Smart playlists description: Playlists that are a set of rules, worked out again every time they are opened. - name: Discovery description: Music outside the library, from external providers an admin switched on, and suggestions scored for you. - name: Providers description: External services Sonda can ask about artists, set up by an admin. paths: /health: get: tags: [System] operationId: getHealth summary: Liveness check responses: '200': description: The server is up. content: application/json: schema: type: object additionalProperties: false required: [status] properties: status: {type: string, enum: [ok]} /openapi.yaml: get: tags: [System] operationId: getOpenAPI summary: This document responses: '200': description: The OpenAPI description of the API. content: application/yaml: schema: {type: string} /auth/register: post: tags: [Auth] operationId: register summary: Create the first user description: | Only works while no user exists. The new user is the admin. Afterwards registration is closed and admins create accounts with `POST /users`. requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/Credentials'} responses: '201': description: The admin account. content: application/json: schema: {$ref: '#/components/schemas/User'} '400': {$ref: '#/components/responses/InvalidInput'} '403': description: A user already exists (`registration_closed`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '409': description: The email is already registered (`email_taken`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /auth/login: post: tags: [Auth] operationId: login summary: Open a session requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/LoginRequest'} responses: '200': description: A new session. content: application/json: schema: {$ref: '#/components/schemas/Session'} '400': {$ref: '#/components/responses/InvalidInput'} '401': description: Wrong email or password (`invalid_credentials`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /auth/refresh: post: tags: [Auth] operationId: refresh summary: Renew a session description: | Exchanges a refresh token for a new access token and a new refresh token. The old refresh token stops working. Presenting a spent one again, more than ten seconds after it was used, ends every session of that user; inside those ten seconds it only fails, so two tabs refreshing together do not log each other out. This holds for any spent token, including one revoked by logout or by a password change. requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/RefreshRequest'} responses: '200': description: A new session. content: application/json: schema: {$ref: '#/components/schemas/Session'} '400': {$ref: '#/components/responses/InvalidInput'} '401': description: The refresh token is unknown, expired or already used (`invalid_refresh_token`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /auth/logout: post: tags: [Auth] operationId: logout summary: End a session description: Revokes one refresh token. Always answers 204, so it never reveals whether the token existed. requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/RefreshRequest'} responses: '204': {description: Done.} '400': {$ref: '#/components/responses/InvalidInput'} /auth/me: get: tags: [Auth] operationId: getMe summary: The signed-in account security: [{bearerAuth: []}] responses: '200': description: Your account. content: application/json: schema: {$ref: '#/components/schemas/User'} '401': {$ref: '#/components/responses/Unauthorized'} /auth/password: post: tags: [Auth] operationId: changePassword summary: Change your password description: | Revokes every refresh token of the account, so no session can be renewed. An access token that was already issued keeps working until it expires (15 minutes by default). security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/PasswordChange'} responses: '204': {description: Password changed.} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': description: The current password is wrong (`invalid_credentials`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /users: get: tags: [Users] operationId: listUsers summary: List users description: Admin only. security: [{bearerAuth: []}] responses: '200': description: Every account, oldest first. content: application/json: schema: type: object additionalProperties: false required: [users] properties: users: type: array items: {$ref: '#/components/schemas/User'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} post: tags: [Users] operationId: createUser summary: Create a user description: Admin only. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/CreateUser'} responses: '201': description: The new account. content: application/json: schema: {$ref: '#/components/schemas/User'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '409': description: The email is already registered (`email_taken`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /users/{id}: parameters: - {$ref: '#/components/parameters/Id'} patch: tags: [Users] operationId: updateUser summary: Grant or remove the admin role description: Admin only. The last admin cannot be demoted. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: type: object required: [is_admin] properties: is_admin: {type: boolean} responses: '200': description: The updated account. content: application/json: schema: {$ref: '#/components/schemas/User'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '404': description: No such user (`user_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '409': description: This is the last admin (`last_admin`). content: application/json: schema: {$ref: '#/components/schemas/Error'} delete: tags: [Users] operationId: deleteUser summary: Delete a user description: | Admin only. Removes the account and its refresh tokens. Access tokens already issued stop working at once on admin routes, `/auth/me`, `/auth/password` and `/listens`; other routes accept them until they expire (15 minutes by default). The last admin cannot be deleted. security: [{bearerAuth: []}] responses: '204': {description: Deleted.} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '404': description: No such user (`user_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '409': description: This is the last admin (`last_admin`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /users/{id}/password: parameters: - {$ref: '#/components/parameters/Id'} put: tags: [Users] operationId: resetUserPassword summary: Reset a user's password description: | Admin only. Revokes every refresh token of that user, so no session can be renewed. Access tokens already issued keep working until they expire (15 minutes by default). security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: type: object required: [password] properties: password: type: string format: password description: 8 to 256 bytes (UTF-8). responses: '204': {description: Password reset.} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '404': description: No such user (`user_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /libraries: get: tags: [Libraries] operationId: listLibraries summary: List libraries description: Admin only. security: [{bearerAuth: []}] responses: '200': description: Every library, oldest first. content: application/json: schema: type: object additionalProperties: false required: [libraries] properties: libraries: type: array items: {$ref: '#/components/schemas/Library'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} post: tags: [Libraries] operationId: createLibrary summary: Add a library description: | Admin only. The path must be an absolute, existing directory, never the filesystem root, and never inside or around another library (a bad path or an overlap is `400 invalid_input`). A name or path that another library already uses is `409 library_exists`. Names are unique ignoring case. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/NewLibrary'} responses: '201': description: The new library. content: application/json: schema: {$ref: '#/components/schemas/Library'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '409': description: Another library has this name or path (`library_exists`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /libraries/{id}: parameters: - {$ref: '#/components/parameters/Id'} patch: tags: [Libraries] operationId: updateLibrary summary: Rename or move a library description: | Admin only. Send `name`, `path` or both. Files keep their identity when the path changes. Changing the path is refused while a scan runs. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/LibraryUpdate'} responses: '200': description: The updated library. content: application/json: schema: {$ref: '#/components/schemas/Library'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '404': {$ref: '#/components/responses/LibraryNotFound'} '409': description: The name or path is used by another library (`library_exists`), or a scan is running (`scan_running`). content: application/json: schema: {$ref: '#/components/schemas/Error'} delete: tags: [Libraries] operationId: deleteLibrary summary: Remove a library description: | Admin only. Removes the library and its index entries. Tracks and listening history stay; the music on disk is never touched. Refused while a scan runs. security: [{bearerAuth: []}] responses: '204': {description: Removed.} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '404': {$ref: '#/components/responses/LibraryNotFound'} '409': description: A scan is running (`scan_running`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /libraries/{id}/scan: parameters: - {$ref: '#/components/parameters/Id'} post: tags: [Scan] operationId: scanLibrary summary: Scan one library description: | Admin only. Starts a scan in the background; follow it with `GET /library/scan`. With `full=true` every file is read again, not only the new or changed ones. security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/Full'} responses: '202': {$ref: '#/components/responses/ScanStarted'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '404': {$ref: '#/components/responses/LibraryNotFound'} '409': description: A scan is already running (`scan_running`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /library/covers: get: tags: [Scan] operationId: getCoversJob summary: Progress of the job that builds the covers description: | Whether the job is running, how far it is (`progress`, only while it runs), and how the last one ended. The job is described at `POST /library/covers`. security: [{bearerAuth: []}] responses: '200': description: The job. content: application/json: schema: {$ref: '#/components/schemas/CoversJobStatus'} '401': {$ref: '#/components/responses/Unauthorized'} post: tags: [Scan] operationId: startCoversJob summary: Build all the covers in the background description: | Admin only. Starts, in the background and one at a time like a scan, a job that builds the cover of every album that has something to play and no cover that is still good, instead of waiting for each album to be opened; follow it with `GET /library/covers`. For each album it does what `GET /albums/{id}/cover` does: the pictures in the user's own files first and, only if the album has none and an admin switched the `coverartarchive` provider on, the Cover Art Archive by the release group id of the album's tags. An album whose cover is still good (a found one for a week, "no cover" for a day) is skipped; send `refresh=true` to search every album again. **This goes through the whole library.** With the archive on, it sends the release group id of every album that has no picture in its files, one after the other and spaced out. It gives up, and says why in `last_error`, when the provider fails for five albums in a row, and also when the files cannot be read (an unmounted disk): it never turns that into "no cover" and never replaces a cover that was built. A cover that came from the archive is kept when the provider was switched off since, even with `refresh=true`; only taking its data back (`DELETE /providers/coverartarchive/data`) removes those. `DELETE /library/covers` stops it. security: [{bearerAuth: []}] parameters: - name: refresh in: query description: "`true` searches every album again, also those that have a good cover. `false` when absent." schema: {type: boolean, default: false} responses: '202': description: The job was started in the background. content: application/json: schema: type: object additionalProperties: false required: [status] properties: status: {type: string, enum: [started]} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '409': description: The job is already running (`covers_job_running`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '500': description: The albums could not be counted (`internal`). content: application/json: schema: {$ref: '#/components/schemas/Error'} delete: tags: [Scan] operationId: stopCoversJob summary: Stop the job that builds the covers description: | Admin only. Asks a running job to end after the album it is on (its requests to the provider may still finish); the covers already built stay. It answers the same when no job is running. security: [{bearerAuth: []}] responses: '204': {description: "Done, also when no job was running."} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} /library/artist-images: get: tags: [Scan] operationId: getArtistImagesJob summary: Progress of the job that looks for the artist pictures description: | Whether the job is running, how far it is (`progress`, only while it runs), and how the last one ended. The job is described at `POST /library/artist-images`. security: [{bearerAuth: []}] responses: '200': description: The job. content: application/json: schema: {$ref: '#/components/schemas/ArtistJobStatus'} '401': {$ref: '#/components/responses/Unauthorized'} post: tags: [Scan] operationId: startArtistImagesJob summary: Look for all the artist pictures in the background description: | Admin only. Starts, in the background and one at a time like a scan, a job that looks for the picture of every artist of the library that has a MusicBrainz id and no answer about its picture that is still good, instead of waiting for each artist to be opened; follow it with `GET /library/artist-images`. For each artist it does what `GET /artists/{id}/image` does, by the artist's MusicBrainz id and never by name: MusicBrainz, Wikidata, then a free picture on Wikimedia Commons. It needs an admin to have switched both the `commons` and the `musicbrainz` providers on; with either off the job ends at once and says so in `last_error`. Artists with no id are not touched. A picture is good for 30 days and "no picture" for a week; send `refresh=true` to search every artist again. A refresh never replaces a stored picture by a failure. **This goes through the whole library.** It sends the MusicBrainz id of every artist, one after the other and spaced out, to MusicBrainz, Wikidata and Commons. It gives up, and says why in `last_error`, when the providers fail for five artists in a row. `DELETE /library/artist-images` stops it. security: [{bearerAuth: []}] parameters: - name: refresh in: query description: "`true` searches every artist again, also those with a good answer. `false` when absent." schema: {type: boolean, default: false} responses: '202': description: The job was started in the background. content: application/json: schema: type: object additionalProperties: false required: [status] properties: status: {type: string, enum: [started]} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '409': description: The job is already running (`artist_images_job_running`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '500': description: The artists could not be counted (`internal`). content: application/json: schema: {$ref: '#/components/schemas/Error'} delete: tags: [Scan] operationId: stopArtistImagesJob summary: Stop the job that looks for the artist pictures description: | Admin only. Asks a running job to end after the artist it is on (its requests to the providers may still finish); the pictures already found stay. It answers the same when no job is running. security: [{bearerAuth: []}] responses: '204': {description: "Done, also when no job was running."} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} /library/descriptions: get: tags: [Scan] operationId: getDescriptionsJob summary: Progress of the job that looks for the artist descriptions description: | Whether the job is running, how far it is (`progress`, only while it runs), and how the last one ended. The job is described at `POST /library/descriptions`. security: [{bearerAuth: []}] responses: '200': description: The job. content: application/json: schema: {$ref: '#/components/schemas/ArtistJobStatus'} '401': {$ref: '#/components/responses/Unauthorized'} post: tags: [Scan] operationId: startDescriptionsJob summary: Look for all the artist descriptions in the background description: | Admin only. Starts, in the background and one at a time like a scan, a job that looks for the description of every artist of the library that has a MusicBrainz id and no answer about its description that is still good; follow it with `GET /library/descriptions`. For each artist it does what `GET /artists/{id}/description` does, by the artist's MusicBrainz id and never by name: MusicBrainz, Wikidata, then Wikipedia. It needs an admin to have switched both the `wikipedia` and the `musicbrainz` providers on; with either off the job ends at once and says so in `last_error`. Artists with no id are not touched. A description is good for 30 days and "no description" for a day; send `refresh=true` to read every artist again. A refresh never replaces a stored description by a failure. **This goes through the whole library.** It sends the MusicBrainz id of every artist, one after the other and spaced out, to MusicBrainz, Wikidata and Wikipedia. It gives up, and says why in `last_error`, when the providers fail for five artists in a row. `DELETE /library/descriptions` stops it. security: [{bearerAuth: []}] parameters: - name: refresh in: query description: "`true` reads every artist again, also those with a good answer. `false` when absent." schema: {type: boolean, default: false} responses: '202': description: The job was started in the background. content: application/json: schema: type: object additionalProperties: false required: [status] properties: status: {type: string, enum: [started]} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '409': description: The job is already running (`descriptions_job_running`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '500': description: The artists could not be counted (`internal`). content: application/json: schema: {$ref: '#/components/schemas/Error'} delete: tags: [Scan] operationId: stopDescriptionsJob summary: Stop the job that looks for the artist descriptions description: | Admin only. Asks a running job to end after the artist it is on (its requests to the providers may still finish); the descriptions already found stay. It answers the same when no job is running. security: [{bearerAuth: []}] responses: '204': {description: "Done, also when no job was running."} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} /library/duplicates: get: tags: [Scan] operationId: listDuplicates summary: The songs that are in more than one file description: | Admin only. Groups of files that are the same song by the same artists, worked out from the index and never from the disk, so it is quick and touches no file. Two files are the same song when they have the same set of main artists, the same title (the key Sonda matches titles by) and durations no more than 3 seconds apart, every pair in a group within that. A file with no duration or no artist never matches, a file flagged as missing does not count, and a copy may be on a different album: `files` says which. Each group says which copy Sonda would keep (`suggested_keep_track_id`): the one without loss (FLAC) before one with loss, then the higher bitrate, then the bigger file, then the oldest. `hashed` is true when every file of the group has been read by the check (`POST /library/duplicates/check`) and `identical` when, besides, they are byte for byte the same. No file path is ever returned. `deletion_allowed` says whether `POST /library/duplicates/clean` can work: with `library.allow_delete` off (the default) the groups can still be seen. security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/Limit'} - {$ref: '#/components/parameters/Offset'} responses: '200': description: A page of groups, in a fixed order (by title). content: application/json: schema: {$ref: '#/components/schemas/DuplicatesPage'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} /library/duplicates/check: get: tags: [Scan] operationId: getDuplicatesCheck summary: Progress of the check that reads the files of the duplicates description: | Whether the check is running, how far it is (`progress`, only while it runs), and how the last one ended. The check is described at `POST /library/duplicates/check`. security: [{bearerAuth: []}] responses: '200': description: The job. content: application/json: schema: {$ref: '#/components/schemas/DuplicatesCheckStatus'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} post: tags: [Scan] operationId: startDuplicatesCheck summary: Read the files of the duplicates, to tell which are identical description: | Admin only. Starts, in the background and one at a time like a scan, a job that reads every file that is in a group of copies and keeps its SHA-256, so that a group of files that are byte for byte the same can be called `identical`. It only reads: nothing is removed or sent anywhere. **It reads whole files**, which on a network drive takes a while, so it is started on purpose. A file that has a fingerprint is skipped, and the fingerprint of a file is forgotten when a scan finds the file changed; send `refresh=true` to read every file again. A file that changed since the scan is skipped. It gives up, and says why in `last_error`, when files cannot be read five times in a row (a disk that is not mounted). `DELETE /library/duplicates/check` stops it. security: [{bearerAuth: []}] parameters: - name: refresh in: query description: "`true` reads every file again, also those that have a fingerprint. `false` when absent." schema: {type: boolean, default: false} responses: '202': description: The check was started in the background. content: application/json: schema: type: object additionalProperties: false required: [status] properties: status: {type: string, enum: [started]} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '409': description: The check is already running (`duplicates_check_running`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '500': description: The groups could not be worked out (`internal`). content: application/json: schema: {$ref: '#/components/schemas/Error'} delete: tags: [Scan] operationId: stopDuplicatesCheck summary: Stop the check of the duplicates description: | Admin only. Asks a running check to end after the file it is on; the fingerprints already kept stay. It answers the same when no check is running. security: [{bearerAuth: []}] responses: '204': {description: "Done, also when no check was running."} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} /library/duplicates/clean: post: tags: [Scan] operationId: cleanDuplicates summary: Delete the extra copies of one song description: | Admin only. **Deletes files from the music folder.** It is the one thing Sonda does that writes there, so it is off until the operator turns on `library.allow_delete` (answer `deletion_disabled` otherwise), the folder has to be writable (`library_read_only`), and it is never done by itself: one request removes the copies `remove_track_ids` of one song and keeps `keep_track_id`. The server decides again, whatever the client saw, and removes nothing unless every check passes: no scan is running (`scan_running`); the tracks exist (`track_not_found`); they are copies of one song by the rule of `GET /library/duplicates` (`invalid_input` otherwise, and also when the copy to keep is among those to remove, a copy is named twice or there are none or more than 100); and the copy to keep and every copy to remove are still the file the last scan saw, a regular file with the same size and date (`duplicate_changed` for a file that changed, is gone, became a link or is outside the library: scan again). So the last copy of a song is never removed. Every file is checked before the first is removed. Each copy is removed from the disk through the library folder (a path cannot leave it, not even through a link) and its track leaves the index; **the listens of the removed track become listens of the track that stays**, so the taste is not lost. Folders are never removed, not even empty ones. If it fails part way (for example the folder turns out to be read-only for the second file), what was removed stays removed. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/CleanDuplicates'} responses: '200': description: The extra copies were removed. content: application/json: schema: {$ref: '#/components/schemas/DuplicatesCleaned'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '404': description: A track that was named does not exist (`track_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '409': description: | Deleting is not turned on (`deletion_disabled`), a scan is running (`scan_running`), a file is not what the last scan saw (`duplicate_changed`), or the music folder cannot be written to (`library_read_only`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /library/scan: get: tags: [Scan] operationId: getScanStatus summary: Scan status description: Whether a scan is running and how the last one ended. security: [{bearerAuth: []}] responses: '200': description: The current state. content: application/json: schema: {$ref: '#/components/schemas/ScanStatus'} '401': {$ref: '#/components/responses/Unauthorized'} post: tags: [Scan] operationId: scanAll summary: Scan every library description: | Admin only. Starts a scan in the background. Only MP3 and FLAC files are read; other audio formats are counted as `unsupported`. Housekeeping folders of NAS boxes (`@Recycle`, `#recycle`, `@eaDir`, `.@__thumb`, `$RECYCLE.BIN`) are skipped. A scan reads the tags of files that are new or changed. Send `full=true` to read every file again: that is how MusicBrainz ids and genres reach music that was indexed before they were read. Files keep their identity, so listening history is kept. security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/Full'} responses: '202': {$ref: '#/components/responses/ScanStarted'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '409': description: A scan is already running (`scan_running`), or there is no library yet (`no_libraries`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /artists: get: tags: [Catalog] operationId: listArtists summary: List artists description: | Artists credited on a playable track, or that are the album artist of an album with one. Sorted by name. security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/Q'} - {$ref: '#/components/parameters/Limit'} - {$ref: '#/components/parameters/Offset'} - {$ref: '#/components/parameters/LibraryId'} responses: '200': description: A page of artists. content: application/json: schema: {$ref: '#/components/schemas/ArtistPage'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} /artists/{id}: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Catalog] operationId: getArtist summary: One artist security: [{bearerAuth: []}] responses: '200': description: The artist. content: application/json: schema: {$ref: '#/components/schemas/Artist'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: | No such artist (`artist_not_found`). An artist with nothing to play is not found either, unless a provider named it as similar to another artist: those can be shown, with `track_count` and `album_count` of 0, but they are never part of the lists. content: application/json: schema: {$ref: '#/components/schemas/Error'} /artists/{id}/similar: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Discovery] operationId: getSimilarArtists summary: Artists similar to one description: | Artists an external provider (Last.fm) finds similar to this one, best first. Each says whether it is in the library, and `id` works with `GET /artists/{id}`; one that is not in the library has no files. The provider is only asked when an admin switched it on and the stored answer is missing or old (7 days; a "no such artist" answer is kept 1 day). What is sent is the artist's name or MusicBrainz id and nothing about any user. Several requests for the same artist at once make one call. A provider that is off or failing is not an error: the answer is `200` and `provider_status` says why. Then `items` holds whatever was stored before, if anything, and `stale` is true when it is older than it should be. `score` is the provider's own number between 0 and 1. It is relative to the list it came in (the best one is usually 1), so it only compares artists inside one answer. `rank` is the position. Show `attribution` where you show the data. security: [{bearerAuth: []}] parameters: - name: limit in: query description: How many to return. 20 when absent or 0; values above 50 are lowered to 50, the most that is kept. schema: {type: integer, minimum: 0, default: 20} responses: '200': description: The similar artists. content: application/json: schema: {$ref: '#/components/schemas/SimilarArtists'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such artist (`artist_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /artists/{id}/tags: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Discovery] operationId: getArtistTags summary: Tags of an artist, from each provider description: | What each provider says kind of music this artist plays: Last.fm's top tags and MusicBrainz's tags and genres, and last the genres of the artist's own music files (`provider` is `files`: the genre tags the scan read, each weighted by how many of the playable tracks the artist is credited on have it; it asks nobody, is always `ok` and has a null `retrieved_at`). There is always one entry for each, Last.fm first. The weights are the providers' own numbers, kept as they came and never mixed: Last.fm's is relative to the artist (1 to 100, the top tag is usually 100; a tag with no votes is dropped), MusicBrainz's is a count of votes. `genre` is true for a MusicBrainz tag that it also lists among its curated genres, and for every tag of the `files` entry, which are genres by definition. A provider is only asked when an admin switched it on and its stored answer is missing or old (7 days; a "no such artist" answer is kept 1 day), with the same rules as `GET /artists/{id}/similar`. What is sent is the artist's name or MusicBrainz id to Last.fm (its id when known), and only the MusicBrainz id to MusicBrainz: Sonda never looks an id up by name. An artist's id comes from the tags in the music files, or from Last.fm for an artist it named that is not in the library; for any other artist the MusicBrainz entry says `no_id`. Show each `attribution` where you show the tags. security: [{bearerAuth: []}] responses: '200': description: One entry per provider. content: application/json: schema: {$ref: '#/components/schemas/ArtistTags'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such artist (`artist_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /discover: get: tags: [Discovery] operationId: discover summary: Artists you may like description: | Suggests artists, in your library or not, each with a `score` from 0 to 1 and the parts it is made of, so every number can be explained. **Where it starts.** From the artists you name with `seed` (one to five, repeat the parameter), or, when you named none and turned on `discover_from_listening` in `PATCH /me/settings`, from the up to 20 artists you play most. With neither the request is refused (`seed_required`) and nothing is sent to anyone. For each seed, the similar artists are the stored ones, or are asked from Last.fm when they are missing or old and an admin switched Last.fm on (see `GET /artists/{id}/similar`). **What is sent**: the name or MusicBrainz id of each seed, and, for the best candidates that have no tags yet, the name of the candidate (tags are asked from Last.fm only, never from MusicBrainz). The seeds from your listening are therefore sent only when you allowed it. A seed is never suggested to itself, and nobody else's listening is read. **The score** is `S = wA·A + wG·G + wP·P + wD·D` with the weights of the server's `[scoring]` config (default 0.40, 0.25, 0.25, 0.10; only their proportions matter). `a` is the affinity: 1 − Π(1 − weight·match) over the seeds that point at the artist, where `match` is Last.fm's similarity (relative to each seed's own list) and `weight` is 1 for a seed you named or your `preference` for one taken from your listening (see `GET /me/taste`). `g` is how close the artist's tags are to the tags of the artists you like (cosine of the tag vectors); it is `null` when there is nothing to compare, and then the score is worked out without it, the other weights rescaled, so a missing part never counts as a bad one. `p` is what your listening says about the artist, from `preference` mapped to 0 to 1, and 0.5 for an artist you never played. `d` is a bonus for what you have not played: `1 / (1 + listens)`. Only the best candidates by affinity (at least 20) are scored, then the best `limit` by score are returned; ties go to the higher affinity, then to the lower id. `because` names up to three seeds that count most for the suggestion. The first request after a seed's data gets old can take several seconds, because the provider is asked politely, a few at a time; later ones are served from the database. `provider_status` is `disabled` when something had to be asked from Last.fm (a seed's similar artists are missing or old) and Last.fm is off or has no key; anything stored earlier is still used, so the list can be empty. With every seed's data stored and fresh the status is `ok` whether Last.fm is on or not. It is `error` when Last.fm failed for some seed (the rest is still returned) and `ok` otherwise. Show `attribution` where you show the data. **How many at once.** One Discover at a time for each listener (a second one answers 429 `discover_busy`), and at most three at the same time on the server: a request that finds them busy waits for its turn (at most 30 seconds, then it answers 429 as well), and leaves without doing any work if the client gives up. A request that waits for its turn counts as running. security: [{bearerAuth: []}] parameters: - name: seed in: query description: An artist id to start from. Repeat up to 5 times. Without it, your listening is used if you allowed that. schema: {type: array, items: {type: integer, format: int64}, maxItems: 5} style: form explode: true - name: limit in: query description: How many suggestions to return. 20 when absent or 0; values above 30 are lowered to 30. schema: {type: integer, minimum: 0, default: 20} - name: in_library in: query description: "`true` keeps only artists you have, `false` only artists you do not. Absent keeps both." schema: {type: boolean} responses: '200': description: The suggestions, best first. content: application/json: schema: {$ref: '#/components/schemas/Discover'} '400': description: A seed that is not an artist, too many seeds, a bad `limit` or `in_library` (`invalid_input`), or no seed and no permission to use your listening (`seed_required`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '401': {$ref: '#/components/responses/Unauthorized'} '429': description: "You already have a Discover running or waiting for its turn, or the server was too busy to give it one in 30 seconds (`discover_busy`). Ask again after `Retry-After` seconds." headers: Retry-After: description: Seconds to wait before asking again. schema: {type: integer} content: application/json: schema: {$ref: '#/components/schemas/Error'} /discover/dismissed: get: tags: [Discovery] operationId: listDismissed summary: Artists you are not interested in description: | The artists you told Discover you are not interested in (`POST /discover/{id}/dismiss`), newest first. Only yours; nobody else's choices are visible or affect your Discover. security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/Limit'} - {$ref: '#/components/parameters/Offset'} responses: '200': description: A page of artists. content: application/json: schema: {$ref: '#/components/schemas/MarkedPage'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} /discover/{id}/dismiss: parameters: - {$ref: '#/components/parameters/Id'} post: tags: [Discovery] operationId: dismissArtist summary: Not interested in this artist description: | Hides the artist from your Discover: it is never suggested again, and an artist taken from your listening that you dismissed no longer seeds your suggestions. An artist is dismissed or on your wishlist, never both: dismissing one that is on the wishlist takes it off. Doing it twice is the same as once. Nothing is sent to anyone. The artist can be one of yours or one a provider named. An artist that a provider named and nobody else does is kept for as long as it is dismissed, so the choice survives a new list from the provider; such an artist is listed for you, but other users cannot see that it exists. When an admin takes a provider's data back (`DELETE /providers/{name}/data`), what only that provider's lists named goes, your choice with it. security: [{bearerAuth: []}] responses: '204': {description: "Done, also when it was already dismissed."} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such artist (`artist_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} delete: tags: [Discovery] operationId: undismissArtist summary: Interested again description: Lets Discover suggest the artist again. A wish on the wishlist is not touched. security: [{bearerAuth: []}] responses: '204': {description: "Done, also when it was not dismissed."} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such artist (`artist_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /mixes: get: tags: [Mixes] operationId: listMixes summary: Your mixes description: | Playlists that Sonda makes for you, from what you listen to and from the genres of your music. First the ones made for you (`favourites`, `rediscover`: they need some listening history, so they are missing without it; `unheard`, the songs you never played), then one `genre` mix for each genre of the library that has at least 30 songs by at least 4 artists, the genres you play most first (and the biggest after them). Spellings of a genre that differ only by case or punctuation are one genre, and `other` and `unknown` are not genres. `title` is in English; a client may say it in its own words from `kind` and `genre`. Nothing is stored and nothing is sent to a provider: a mix is worked out from your own history and the genre tags of your files, for you alone. security: [{bearerAuth: []}] responses: '200': description: The mixes. content: application/json: schema: {$ref: '#/components/schemas/MixList'} '401': {$ref: '#/components/responses/Unauthorized'} /mixes/{id}: parameters: - {$ref: '#/components/parameters/MixId'} get: tags: [Mixes] operationId: getMix summary: A mix and its songs description: | Up to 50 songs, at most 3 by one artist and never two by the same artist in a row. They are picked by weighted chance: the artists you play weigh more, songs you never played a bit more, songs played in the last days less, and songs you skipped in the last two weeks and artists you avoid do not come at all. The same mix comes back all day: it changes the next day, or when you ask for another `variant`. The id of a genre mix has the genre in it (`genre:hard rock`), so it must be percent-encoded in the path. A mix you do not have (a genre that is too small, `favourites` with no history) is `mix_not_found`. security: [{bearerAuth: []}] parameters: - name: variant in: query description: Another mix of the same kind, from 0 (the mix of the day) up. schema: {type: integer, minimum: 0, maximum: 1000000, default: 0} responses: '200': description: The mix. content: application/json: schema: {$ref: '#/components/schemas/MixWithTracks'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/MixNotFound'} /mixes/{id}/playlist: parameters: - {$ref: '#/components/parameters/MixId'} post: tags: [Mixes] operationId: saveMix summary: Keep a mix as a playlist description: | Makes a playlist of your own with the songs that `variant` of the mix has now, in the same order. The playlist is a copy: it does not change afterwards, and is yours to edit. The body is optional. security: [{bearerAuth: []}] requestBody: required: false content: application/json: schema: {$ref: '#/components/schemas/SaveMix'} responses: '201': description: The playlist. content: application/json: schema: {$ref: '#/components/schemas/Playlist'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/MixNotFound'} '409': {$ref: '#/components/responses/PlaylistLimit'} '422': description: The mix has no songs to save (`mix_empty`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /genres: get: tags: [Smart playlists] operationId: listGenres summary: The genres of the library description: | The genres of the playable songs, to choose from in the rules of a smart playlist: each with the number of songs, the biggest first, and by name among equals. The spellings that the files have are one genre (`jazz+funk` and `jazz-funk` are `jazz funk`), written the way the rules compare them; tags such as `other` or `unknown` are left out. security: [{bearerAuth: []}] responses: '200': description: The genres. content: application/json: schema: {$ref: '#/components/schemas/GenreList'} '401': {$ref: '#/components/responses/Unauthorized'} /smart-playlists: get: tags: [Smart playlists] operationId: listSmartPlaylists summary: Your smart playlists description: | The smart playlists you made, the one changed last first. Only yours. A smart playlist is a set of rules: its songs come from `GET /smart-playlists/{id}/tracks`. security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/Limit'} - {$ref: '#/components/parameters/Offset'} responses: '200': description: A page of smart playlists. content: application/json: schema: {$ref: '#/components/schemas/SmartPlaylistPage'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} post: tags: [Smart playlists] operationId: createSmartPlaylist summary: Make a smart playlist description: | Keeps a set of rules, an order and a limit under a name. Only that is stored: the songs are worked out again every time. A user can have 200. Names can repeat. Use `POST /smart-playlists/preview` to try the rules first. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/CreateSmartPlaylist'} responses: '201': description: The smart playlist. content: application/json: schema: {$ref: '#/components/schemas/SmartPlaylist'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '409': description: A user can have 200 smart playlists (`limit_reached`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /smart-playlists/preview: post: tags: [Smart playlists] operationId: previewSmartPlaylist summary: Try rules without keeping them description: | Works the songs out for rules that are not kept, the way `GET /smart-playlists/{id}/tracks` would, so they can be tried while they are written. Nothing is stored. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/PreviewSmartPlaylist'} responses: '200': description: The songs. content: application/json: schema: {$ref: '#/components/schemas/SmartTracks'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} /smart-playlists/suggested: get: tags: [Smart playlists] operationId: listSuggestedSmartPlaylists summary: The smart playlists Sonda makes for you description: | A fixed set that is there without anybody making it, the same rules for everyone and worked out on your own library and history: `recently-added`, `on-rotation` (the songs you played most in the last 30 days, at least twice), `top-year` (the same over 365 days), `most-played` (over all time), `never-played`, `forgotten` (played once, but not in the last 90 days), `high-quality` (bitrate of 900 kbps or more) and `long-tracks` (6 minutes or more). Nothing is stored for them. A client says their names in its own language from the `key`. To change one, make a smart playlist of your own from its rules with `POST /smart-playlists`. security: [{bearerAuth: []}] responses: '200': description: The suggested smart playlists. content: application/json: schema: {$ref: '#/components/schemas/SuggestedSmartPlaylistList'} '401': {$ref: '#/components/responses/Unauthorized'} /smart-playlists/suggested/{key}/tracks: parameters: - {$ref: '#/components/parameters/SuggestedKey'} get: tags: [Smart playlists] operationId: getSuggestedSmartPlaylistTracks summary: The songs of a suggested smart playlist, now description: | Works the rules out for you, as `GET /smart-playlists/{id}/tracks` does for yours. With the random order the songs stay the same all day, and another `variant` gives other ones. security: [{bearerAuth: []}] parameters: - name: variant in: query description: Other songs for the random order, from 0 (the songs of the day) up. schema: {type: integer, minimum: 0, maximum: 1000000, default: 0} responses: '200': description: The songs. content: application/json: schema: {$ref: '#/components/schemas/SmartTracks'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/SuggestedNotFound'} /smart-playlists/suggested/{key}/playlist: parameters: - {$ref: '#/components/parameters/SuggestedKey'} post: tags: [Smart playlists] operationId: saveSuggestedSmartPlaylist summary: Keep a suggested smart playlist as a playlist description: | Makes a playlist of your own with the songs that `variant` gives now, in the same order. It is a copy, and is yours to edit. The body is optional; without a name the playlist is called by the `key`. security: [{bearerAuth: []}] requestBody: required: false content: application/json: schema: {$ref: '#/components/schemas/SaveSmartPlaylist'} responses: '201': description: The playlist. content: application/json: schema: {$ref: '#/components/schemas/Playlist'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/SuggestedNotFound'} '409': {$ref: '#/components/responses/PlaylistLimit'} '422': description: The rules give no songs to save (`smart_playlist_empty`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /smart-playlists/{id}: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Smart playlists] operationId: getSmartPlaylist summary: A smart playlist description: | Its name, rules, order and limit, without the songs. One of somebody else answers `smart_playlist_not_found`. security: [{bearerAuth: []}] responses: '200': description: The smart playlist. content: application/json: schema: {$ref: '#/components/schemas/SmartPlaylist'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/SmartPlaylistNotFound'} patch: tags: [Smart playlists] operationId: updateSmartPlaylist summary: Change a smart playlist description: | Changes what is given. The rules, when given, replace the old ones whole. An empty description clears it; a name cannot be empty. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/UpdateSmartPlaylist'} responses: '200': description: The smart playlist as it is now. content: application/json: schema: {$ref: '#/components/schemas/SmartPlaylist'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/SmartPlaylistNotFound'} delete: tags: [Smart playlists] operationId: deleteSmartPlaylist summary: Delete a smart playlist description: Deletes the rules. Playlists that were made from it with `POST /smart-playlists/{id}/playlist` stay. security: [{bearerAuth: []}] responses: '204': {description: Deleted.} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/SmartPlaylistNotFound'} /smart-playlists/{id}/tracks: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Smart playlists] operationId: getSmartPlaylistTracks summary: The songs of a smart playlist, now description: | Works the rules out on the playable songs of the library, with your own listening history and taste for the rules that use them, puts them in the order and cuts the end at the limit. A song whose files are gone is never offered. Nothing is stored, and nothing is asked of a provider. With the random order the songs stay the same all day, and another `variant` gives other ones. security: [{bearerAuth: []}] parameters: - name: variant in: query description: Other songs for the random order, from 0 (the songs of the day) up. schema: {type: integer, minimum: 0, maximum: 1000000, default: 0} responses: '200': description: The songs. content: application/json: schema: {$ref: '#/components/schemas/SmartTracks'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/SmartPlaylistNotFound'} /smart-playlists/{id}/playlist: parameters: - {$ref: '#/components/parameters/Id'} post: tags: [Smart playlists] operationId: saveSmartPlaylist summary: Keep a smart playlist as a playlist description: | Makes a playlist of your own with the songs that `variant` gives now, in the same order. The playlist is a copy: it does not change afterwards, and is yours to edit. The body is optional. security: [{bearerAuth: []}] requestBody: required: false content: application/json: schema: {$ref: '#/components/schemas/SaveSmartPlaylist'} responses: '201': description: The playlist. content: application/json: schema: {$ref: '#/components/schemas/Playlist'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/SmartPlaylistNotFound'} '409': {$ref: '#/components/responses/PlaylistLimit'} '422': description: The rules give no songs to save (`smart_playlist_empty`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /playlists: get: tags: [Playlists] operationId: listPlaylists summary: Your playlists description: | The playlists you made, the one changed last first. Only yours: nobody else's are ever listed. security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/Limit'} - {$ref: '#/components/parameters/Offset'} responses: '200': description: A page of playlists. content: application/json: schema: {$ref: '#/components/schemas/PlaylistPage'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} post: tags: [Playlists] operationId: createPlaylist summary: Make a playlist description: | Makes an empty playlist. A user can have 1000. Names can repeat. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/CreatePlaylist'} responses: '201': description: The playlist. content: application/json: schema: {$ref: '#/components/schemas/Playlist'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '409': {$ref: '#/components/responses/PlaylistLimit'} /playlists/{id}: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Playlists] operationId: getPlaylist summary: A playlist description: | Its name, description, how many tracks it has and how long they are. The tracks come from `GET /playlists/{id}/tracks`. A playlist of somebody else answers `playlist_not_found`. security: [{bearerAuth: []}] responses: '200': description: The playlist. content: application/json: schema: {$ref: '#/components/schemas/Playlist'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/PlaylistNotFound'} patch: tags: [Playlists] operationId: updatePlaylist summary: Rename a playlist or change its description description: | Changes what is given. An empty description clears it; a name cannot be empty. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/UpdatePlaylist'} responses: '200': description: The playlist as it is now. content: application/json: schema: {$ref: '#/components/schemas/Playlist'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/PlaylistNotFound'} delete: tags: [Playlists] operationId: deletePlaylist summary: Delete a playlist description: Deletes the playlist and its list of tracks. The tracks themselves stay in the library. security: [{bearerAuth: []}] responses: '204': {description: Deleted.} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/PlaylistNotFound'} /naming: get: tags: [Smart playlists] operationId: getNamingStatus summary: Whether names are made by themselves description: | `auto` is true when the `anthropic` provider is on with its key: a playlist that is kept from a mix or a smart playlist with `auto_name`, and a smart playlist made with no name, are then named by Claude. A page asks this so that it does not ask for a name that Claude will make. security: [{bearerAuth: []}] responses: '200': description: The status. content: application/json: schema: type: object additionalProperties: false required: [auto] properties: auto: {type: boolean} '401': {$ref: '#/components/responses/Unauthorized'} /playlists/{id}/suggest-name: parameters: - {$ref: '#/components/parameters/Id'} post: tags: [Playlists] operationId: suggestPlaylistName summary: Suggest a name for a playlist description: | Makes a suggestion and changes nothing: the client decides what to do with it. When an admin turned the `anthropic` provider on with an API key, Claude is asked for the name, with only a few facts: up to 5 genres, up to 8 artist names, how many songs there are, for a smart playlist a few words about its rules, and the language. Never the user, a listen, a track title or a file path. What Claude answers is kept, so the same facts are not asked twice. With the provider off, or when it fails or declines, a name is made on this server from the genres and the artists and nothing leaves it: `source` says which it was. The body is optional. The facts come from the first 200 songs of the playlist that can be played. security: [{bearerAuth: []}] requestBody: required: false content: application/json: schema: {$ref: '#/components/schemas/SuggestName'} responses: '200': description: A name and a line of description. content: application/json: schema: {$ref: '#/components/schemas/NameSuggestion'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/PlaylistNotFound'} /mixes/{id}/suggest-name: parameters: - {$ref: '#/components/parameters/MixId'} post: tags: [Mixes] operationId: suggestMixName summary: Suggest a name for a mix description: | Makes a suggestion and changes nothing: the client decides what to do with it. When an admin turned the `anthropic` provider on with an API key, Claude is asked for the name, with only a few facts: up to 5 genres, up to 8 artist names, how many songs there are, for a smart playlist a few words about its rules, and the language. Never the user, a listen, a track title or a file path. What Claude answers is kept, so the same facts are not asked twice. With the provider off, or when it fails or declines, a name is made on this server from the genres and the artists and nothing leaves it: `source` says which it was. The body is optional. The facts come from the songs that `variant` of the mix has. security: [{bearerAuth: []}] requestBody: required: false content: application/json: schema: {$ref: '#/components/schemas/SuggestName'} responses: '200': description: A name and a line of description. content: application/json: schema: {$ref: '#/components/schemas/NameSuggestion'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/MixNotFound'} /smart-playlists/{id}/suggest-name: parameters: - {$ref: '#/components/parameters/Id'} post: tags: [Smart playlists] operationId: suggestSmartPlaylistName summary: Suggest a name for a smart playlist description: | Makes a suggestion and changes nothing: the client decides what to do with it. When an admin turned the `anthropic` provider on with an API key, Claude is asked for the name, with only a few facts: up to 5 genres, up to 8 artist names, how many songs there are, for a smart playlist a few words about its rules, and the language. Never the user, a listen, a track title or a file path. What Claude answers is kept, so the same facts are not asked twice. With the provider off, or when it fails or declines, a name is made on this server from the genres and the artists and nothing leaves it: `source` says which it was. The body is optional. The facts come from the rules and from the songs that `variant` of it gives now. security: [{bearerAuth: []}] requestBody: required: false content: application/json: schema: {$ref: '#/components/schemas/SuggestName'} responses: '200': description: A name and a line of description. content: application/json: schema: {$ref: '#/components/schemas/NameSuggestion'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/SmartPlaylistNotFound'} /playlists/{id}/tracks: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Playlists] operationId: listPlaylistTracks summary: The tracks of a playlist description: | The items in order, each with its own `id` (a track can be in a playlist more than once), its `position` (counted from 0, without gaps) and the track. A track whose files were deleted or moved away stays in the playlist with `available` false: it is not lost, and it plays again when the files are back and a scan has found them. security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/Limit'} - {$ref: '#/components/parameters/Offset'} responses: '200': description: A page of items. content: application/json: schema: {$ref: '#/components/schemas/PlaylistItemPage'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/PlaylistNotFound'} post: tags: [Playlists] operationId: addPlaylistTracks summary: Add tracks to a playlist description: | Puts 1 to 500 tracks, in the order given, at `position` (the tracks from there on move down) or at the end when it is absent. A track can be added again. If one id is not a track nothing is added. A playlist holds up to 10000 tracks. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/AddPlaylistTracks'} responses: '200': description: The playlist as it is now. content: application/json: schema: {$ref: '#/components/schemas/Playlist'} '400': description: The request is malformed, or `position` is beyond the end (`invalid_position`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {$ref: '#/components/responses/PlaylistNotFound'} '409': {$ref: '#/components/responses/PlaylistLimit'} '422': description: One of the tracks does not exist (`track_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /playlists/{id}/tracks/{item}: parameters: - {$ref: '#/components/parameters/Id'} - name: item in: path required: true description: The `id` of the item, not of the track. schema: {type: integer, format: int64, minimum: 1} patch: tags: [Playlists] operationId: movePlaylistItem summary: Move a track inside a playlist description: | Puts the item at `position`, from 0 to the number of items less one; the ones in between shift by one. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/MovePlaylistItem'} responses: '204': {description: Moved.} '400': description: The request is malformed, or `position` is beyond the end (`invalid_position`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such playlist (`playlist_not_found`) or no such item in it (`item_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} delete: tags: [Playlists] operationId: removePlaylistItem summary: Take a track out of a playlist description: Removes that one item; the ones after it move up by one. security: [{bearerAuth: []}] responses: '204': {description: Removed.} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such playlist (`playlist_not_found`) or no such item in it (`item_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /wishlist: get: tags: [Discovery] operationId: listWishlist summary: Your wishlist description: | The artists you want, newest first. It is a list for you: nothing is downloaded or sent anywhere. `in_library` says whether there is music of the artist to play now, so a client can hide the ones you already got. Only yours. security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/Limit'} - {$ref: '#/components/parameters/Offset'} responses: '200': description: A page of artists. content: application/json: schema: {$ref: '#/components/schemas/MarkedPage'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} /wishlist/{id}: parameters: - {$ref: '#/components/parameters/Id'} put: tags: [Discovery] operationId: addToWishlist summary: Put an artist on your wishlist description: | Adds the artist. An artist is on the wishlist or dismissed, never both: adding one you dismissed lifts the dismissal. Doing it twice keeps the first date. The artist can be one of yours or one a provider named; the latter is kept while it is on a wishlist (see `POST /discover/{id}/dismiss` for what a purge does). Discover marks it `wishlisted`. security: [{bearerAuth: []}] responses: '204': {description: "Done, also when it was already there."} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such artist (`artist_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} delete: tags: [Discovery] operationId: removeFromWishlist summary: Take an artist off your wishlist description: A dismissal of the artist is not touched. security: [{bearerAuth: []}] responses: '204': {description: "Done, also when it was not there."} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such artist (`artist_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /me/taste: get: tags: [Taste] operationId: getMyTaste summary: What Sonda has learned about your taste description: | Your taste, worked out from your own listening history every time you ask. It uses local data only: nothing is sent to any provider, and nobody else's history is read. Each event has a value: a `complete` listen +1, any other listen that counts +0.5 (see `POST /listens`), a `skip` before that -1, and a play too short to mean anything 0. An event weighs half as much for every 90 days (`taste.half_life_days`) that has passed, and one dated after the moment of the request weighs as if it happened then. Only the last ten half-lives are read (900 days by default); older events weigh less than a thousandth and are left out, also from `listens`. For each artist the values add up, and `preference` is `tanh(sum / 3)`: from -1 to 1, approaching both (a large sum rounds to exactly 1), so one skip does not sink an artist and listening makes one loved at most. A track with several artists credits each of them. `artists` are the ones you like (a `preference` above 0), the most played first. They are ordered by the sum itself, so artists whose `preference` rounds to 1 keep their order; ties go to the lower id. `tags` are the kinds of music you like, at most 50: the tags of those artists (the genres of your files that still exist, and what Last.fm and MusicBrainz said earlier, if they were ever asked) added up, each artist weighing as much as its `preference`, and scaled so the best tag is 1, best first. Tags are read from what is already stored; this request never asks a provider. The tag profile is built from your 200 most liked artists. security: [{bearerAuth: []}] parameters: - name: limit in: query description: How many artists to return. 20 when absent or 0; values above 50 are lowered to 50. It does not limit `tags`. schema: {type: integer, minimum: 0, default: 20} responses: '200': description: Your taste. Both lists are empty until you have listened to something. content: application/json: schema: {$ref: '#/components/schemas/Taste'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} /me/settings: get: tags: [Taste] operationId: getMySettings summary: Your own settings description: | Settings that belong to you, not to the server. Everyone starts with the private defaults: anything that would send something about your taste to a provider is off. security: [{bearerAuth: []}] responses: '200': description: Your settings. content: application/json: schema: {$ref: '#/components/schemas/UserSettings'} '401': {$ref: '#/components/responses/Unauthorized'} patch: tags: [Taste] operationId: updateMySettings summary: Change your own settings description: | Changes the settings named in the body and leaves the others alone. An empty object changes nothing. `null` is the same as leaving a field out. The body must be one JSON object, with nothing after it, and the names must be spelt exactly: a setting that does not exist is refused rather than ignored. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/UpdateUserSettings'} responses: '200': description: Your settings as they are now. content: application/json: schema: {$ref: '#/components/schemas/UserSettings'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} /artists/{id}/lidarr: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Discovery] operationId: getArtistInLidarr summary: Whether Lidarr has an artist description: | Asks your own Lidarr, by the artist's MusicBrainz id and never by name, whether it has the artist and whether it monitors it. Like the descriptions, whatever stops the answer is a status and not an error: `disabled` when the `lidarr` provider is off (nobody is asked), `no_id` when the artist has no MusicBrainz id, `not_configured` when Lidarr has no address or key, `error` when it could not be asked now. Only the id and the API key go out, to the address an admin set. security: [{bearerAuth: []}] responses: '200': description: Whether Lidarr has the artist. content: application/json: schema: {$ref: '#/components/schemas/ArtistInLidarr'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such artist (`artist_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} post: tags: [Discovery] operationId: sendArtistToLidarr summary: Send an artist to Lidarr description: | Admin only. Adds the artist to your own Lidarr, which then looks for and downloads the music by itself: Sonda downloads nothing, and does this only when an admin asks, for one artist, never by itself. It works for any artist that has a MusicBrainz id, also one that Sonda only learned of from a list of similar artists, which is the point: asking for music you do not have. It never looks an id up by name. It uses what an admin set in `PUT /providers/lidarr`: the quality profile, the metadata profile, the root folder, which of the albums to monitor and whether Lidarr starts searching at once. It needs the provider switched on and those chosen. An artist that Lidarr already has is not an error (`already_added`, nothing changes), so the call can be repeated. If Lidarr does not answer in time, the artist may have been added all the same: read it with `GET /artists/{id}/lidarr`. Only the MusicBrainz id and the API key go out, to the address an admin set. security: [{bearerAuth: []}] responses: '200': description: The artist is in Lidarr. content: application/json: schema: type: object additionalProperties: false required: [status] properties: status: type: string enum: [added, already_added] description: "`added` now, or `already_added` when Lidarr had it." '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/AdminRequired'} '404': description: No such artist (`artist_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '409': description: The provider is switched off (`lidarr_disabled`), or has no address or key, or the profiles and the folder were not chosen (`lidarr_not_configured`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '422': description: The artist has no MusicBrainz id (`no_musicbrainz_id`), Lidarr does not know the id (`lidarr_unknown_artist`), or it refused the artist (`lidarr_rejected`, with its reason). content: application/json: schema: {$ref: '#/components/schemas/Error'} '502': description: Lidarr refused the key (`lidarr_key_refused`), or could not be asked or did not answer in time (`lidarr_unavailable`; the artist may have been added). content: application/json: schema: {$ref: '#/components/schemas/Error'} /artists/{id}/description: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Discovery] operationId: getArtistDescription summary: What Wikipedia says about an artist description: | A short text about the artist from Wikipedia, with the page it comes from. The way to it is a chain of identifiers, never a search by name: the artist's MusicBrainz id, then the Wikidata item that MusicBrainz links to it, then the Wikipedia page that Wikidata names in the first of the server's languages (`[wikipedia] languages`, the code of the Wikipedia: `it`, `en`, `no` for Norwegian; a language with no Wikipedia finds nothing) that has one. A page is used only if it is an article about that same item (not a page of disambiguation). An artist with no MusicBrainz id answers `no_id`: Sonda does not look an id up by name. It needs the `wikipedia` provider and also the `musicbrainz` one, because the link to Wikidata comes from MusicBrainz; an admin switches them on, and nothing is sent while either is off (`disabled`, also when an answer is stored). What is sent: the MusicBrainz id to MusicBrainz (with the contact set for MusicBrainz), the Wikidata item to Wikidata and the title of the page to Wikipedia (with the contact set for Wikipedia), and your server's IP address with them. The answer is stored: 30 days, or a day when there was nothing to find, and an old one is returned as `stale` if Wikipedia fails. When there is nothing to show, `description` is `null` and `provider_status` is `ok`. The text is CC BY-SA 4.0. Where you show it, name the page (`title`), link to it (`url`) and give the licence (`license`, `license_url`), and say if you changed it. security: [{bearerAuth: []}] responses: '200': description: The description, or `null` with the status that says why. content: application/json: schema: {$ref: '#/components/schemas/ArtistDescription'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such artist (`artist_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /artists/{id}/image: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Discovery] operationId: getArtistImage summary: A free picture of an artist description: | A JPEG made from a picture of the artist on Wikimedia Commons, only when its licence is free: public domain, CC0, CC BY or CC BY-SA. Non-commercial, no-derivatives, fair use and unknown licences are refused, because Sonda keeps a copy. **Where you show it, show its credit** (`GET /artists/{id}/image/credit`): the author, the licence and the page of the file. The way to it is a chain of identifiers, never a search by name: the artist's MusicBrainz id, the Wikidata item MusicBrainz links to it, the picture Wikidata names for it, and Commons for its licence and a copy. It needs the `commons` provider and the `musicbrainz` one, which an admin switches on. It is built the first time it is asked for (that request can take a few seconds), scaled to fit, saved in the data folder, and served from there afterwards: for 30 days, or a week when there is no free picture; an older copy is served when Commons cannot be reached. What is sent: the MusicBrainz id to MusicBrainz, the Wikidata item to Wikidata, the name of the file to Commons, and the address of a copy to Wikimedia, with your server's IP address and a `User-Agent` with a contact. An `` element cannot send headers, so, like the stream and the covers, this accepts the access token as the `access_token` query parameter. A header, when present, always wins. security: - bearerAuth: [] - streamQueryToken: [] parameters: - name: size in: query description: "`small` (300 pixels at most on the longest side) or `large` (1000). Large when absent." schema: {type: string, enum: [small, large], default: large} - name: If-None-Match in: header required: false schema: {type: string} - name: Range in: header required: false schema: {type: string} responses: '200': description: The picture. headers: ETag: {$ref: '#/components/headers/ETag'} Cache-Control: {$ref: '#/components/headers/CacheControl'} Content-Length: {$ref: '#/components/headers/ContentLength'} Last-Modified: {$ref: '#/components/headers/LastModified'} content: image/jpeg: schema: {type: string, format: binary} '206': description: The requested byte range of the picture. headers: Content-Range: schema: {type: string} content: image/jpeg: schema: {type: string, format: binary} '304': {description: Not modified since the `ETag` sent.} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: | No such artist (`artist_not_found`), no free picture of it (`image_not_found`), the provider is off (`provider_disabled`), or the artist has no MusicBrainz id (`no_musicbrainz_id`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '502': description: The picture provider could not be reached (`provider_unavailable`). Try again later. content: application/json: schema: {$ref: '#/components/schemas/Error'} head: tags: [Discovery] operationId: headArtistImage summary: Headers of a picture description: Same as `GET`, without the body. security: - bearerAuth: [] - streamQueryToken: [] parameters: - name: size in: query schema: {type: string, enum: [small, large], default: large} - name: If-None-Match in: header required: false schema: {type: string} responses: '200': description: Headers of the picture. headers: ETag: {$ref: '#/components/headers/ETag'} Cache-Control: {$ref: '#/components/headers/CacheControl'} Content-Length: {$ref: '#/components/headers/ContentLength'} Last-Modified: {$ref: '#/components/headers/LastModified'} '304': {description: Not modified since the `ETag` sent.} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {description: "No such artist, no free picture, the provider is off or the artist has no MusicBrainz id."} '502': {description: "The picture provider could not be reached."} /artists/{id}/image/credit: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Discovery] operationId: getArtistImageCredit summary: The credit of a picture of an artist description: | Whose the picture is and under which licence, to be shown next to it (the licences ask for it). The author is plain text and may be empty; `license_url` may be empty when the licence has no address; `page_url` is the page of the file on Commons, where everything is. It answers like `GET /artists/{id}/image` (same errors), because the credit exists only with a picture: the first request for an artist can take as long as the picture does (several seconds). security: [{bearerAuth: []}] responses: '200': description: The credit. content: application/json: schema: {$ref: '#/components/schemas/PictureCredit'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such artist (`artist_not_found`), no free picture (`image_not_found`), the provider is off (`provider_disabled`) or the artist has no MusicBrainz id (`no_musicbrainz_id`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '502': description: The picture provider could not be reached (`provider_unavailable`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /albums: get: tags: [Catalog] operationId: listAlbums summary: List albums description: | Albums with a playable track, sorted by title. `artist_id` matches the albums an artist owns plus those where it is credited on a playable track, the same set as its `album_count`. security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/Q'} - {$ref: '#/components/parameters/Limit'} - {$ref: '#/components/parameters/Offset'} - {$ref: '#/components/parameters/LibraryId'} - {$ref: '#/components/parameters/ArtistId'} responses: '200': description: A page of albums. content: application/json: schema: {$ref: '#/components/schemas/AlbumPage'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} /albums/{id}: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Catalog] operationId: getAlbum summary: One album security: [{bearerAuth: []}] responses: '200': description: The album. content: application/json: schema: {$ref: '#/components/schemas/Album'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such album, or nothing of it can be played (`album_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /albums/{id}/cover: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Catalog] operationId: getAlbumCover summary: The cover of an album description: | A JPEG made from the picture in the album's own files: the picture embedded in one of its first files, or else a `cover`, `folder`, `front`, `album` or `albumart` image (`.jpg`, `.jpeg` or `.png`, any case) in the album's folder, in that order of names. It is built the first time it is asked for (that request can take a moment), scaled to fit and saved in the server's data folder, and served from there afterwards. It never contacts anybody (unless the `coverartarchive` provider is on, see below). Pictures that are too big (over 20 MB or 16 million pixels) or are not pictures are ignored, and only files inside the library are read. For an album split in folders named like `CD1` or `Disc 2`, the picture in the folder above them is used too. When the files have no picture at all, and an admin switched on the `coverartarchive` provider, the cover is asked from the Cover Art Archive by the MusicBrainz release group id that the tags of the album's files carry (a full rescan reads that tag again for music indexed before); only that id leaves the server. An album whose files have no id is looked up in MusicBrainz by its artist and title when the `musicbrainz` provider is on too: the id is taken only when MusicBrainz is sure (an exact match of both names; a title that ends with a note like `(disc 2)` or `(Deluxe Edition)` is tried again without it), is used for that request and is not stored. The files of the user always come first. That request can take several seconds and may answer `provider_unavailable`. At most a couple of covers are built at the same time, so a client that asks for many at once may wait. An album with no picture answers `cover_not_found`, and the server does not look again for a day; a new or changed file of the album, or a full rescan, makes it look again. A cover that was found is checked again after a week, so a picture replaced in the folder is noticed. The picture is `private` for an hour in caches and has an `ETag`: send it back as `If-None-Match`. An `` element cannot send headers, so, like the stream, this also accepts the access token as the `access_token` query parameter. A header, when present, always wins. security: - bearerAuth: [] - streamQueryToken: [] parameters: - name: size in: query description: "`small` (300 pixels at most on the longest side) or `large` (1000). Large when absent. Never enlarged: a small picture stays as it is." schema: {type: string, enum: [small, large], default: large} - name: If-None-Match in: header required: false schema: {type: string} - name: Range in: header required: false schema: {type: string} responses: '200': description: The cover. headers: ETag: {$ref: '#/components/headers/ETag'} Cache-Control: {$ref: '#/components/headers/CacheControl'} Content-Length: {$ref: '#/components/headers/ContentLength'} Last-Modified: {$ref: '#/components/headers/LastModified'} content: image/jpeg: schema: {type: string, format: binary} '206': description: The requested byte range of the cover. headers: Content-Range: schema: {type: string} content: image/jpeg: schema: {type: string, format: binary} '304': {description: Not modified since the `ETag` sent.} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such album (`album_not_found`), or it has no cover (`cover_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} '502': description: The cover provider could not be reached (`provider_unavailable`). Try again later. content: application/json: schema: {$ref: '#/components/schemas/Error'} '503': description: | None of the album's files or folders could be read, for example because the disk is not mounted (`files_unreadable`). That says nothing about whether there is a picture, so it is not remembered as "no cover" and nothing already built is touched. Try again later. content: application/json: schema: {$ref: '#/components/schemas/Error'} head: tags: [Catalog] operationId: headAlbumCover summary: Headers of a cover description: Same as `GET`, without the body. security: - bearerAuth: [] - streamQueryToken: [] parameters: - name: size in: query schema: {type: string, enum: [small, large], default: large} - name: If-None-Match in: header required: false schema: {type: string} responses: '200': description: Headers of the cover. headers: ETag: {$ref: '#/components/headers/ETag'} Cache-Control: {$ref: '#/components/headers/CacheControl'} Content-Length: {$ref: '#/components/headers/ContentLength'} Last-Modified: {$ref: '#/components/headers/LastModified'} '304': {description: Not modified since the `ETag` sent.} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': {description: "No such album, or it has no cover."} '502': {description: "The cover provider could not be reached."} '503': {description: "None of the album's files could be read."} /tracks: get: tags: [Catalog] operationId: listTracks summary: List tracks description: | Tracks with at least one file that is not flagged missing; a track with several files appears once. Grouped by album, then disc and track number. security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/Q'} - {$ref: '#/components/parameters/Limit'} - {$ref: '#/components/parameters/Offset'} - {$ref: '#/components/parameters/LibraryId'} - {$ref: '#/components/parameters/ArtistId'} - {$ref: '#/components/parameters/AlbumId'} responses: '200': description: A page of tracks. content: application/json: schema: {$ref: '#/components/schemas/TrackPage'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} /tracks/{id}: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Catalog] operationId: getTrack summary: One track security: [{bearerAuth: []}] responses: '200': description: The track. content: application/json: schema: {$ref: '#/components/schemas/Track'} '400': {$ref: '#/components/responses/InvalidInput'} '401': {$ref: '#/components/responses/Unauthorized'} '404': description: No such track, or it has no playable file (`track_not_found`). content: application/json: schema: {$ref: '#/components/schemas/Error'} /tracks/{id}/stream: parameters: - {$ref: '#/components/parameters/Id'} get: tags: [Playback] operationId: streamTrack summary: Stream a track description: | Serves the original audio file. Supports `Range` requests, so players can seek, and conditional requests. Streaming never records a listen; report one with `POST /listens`. An `