- Check the discover_from_listening setting before reading the listening history, so a refused request does no work and a database failure cannot turn it into a 500. - Cosine adds up in tag order: the sum in map order changed in the last digit between runs, and equal artists could swap places between requests. - A seed that could not be read is no longer listed as a seed. - README and spec: Discover exists now; "disabled" means something had to be asked and Last.fm is off; the stored lookups are shared, so another local user can see from retrieved_at that an artist was looked up, but not who. - Tests: the history is not read for a refused request, a stable cosine, tags fetched only for the pool and four at a time, a cancelled request stops, MusicBrainz is never asked, the setting is per user.
1836 lines
71 KiB
YAML
1836 lines
71 KiB
YAML
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 <token>`. 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: 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 username is taken (`username_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 username 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 username is taken (`username_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/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.
|
||
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'}
|
||
|
||
/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'}
|
||
|
||
/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'}
|
||
|
||
/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 `<audio>` element cannot send headers, so this is the only operation that also accepts
|
||
the access token as the `access_token` query parameter. A header, when present, always wins.
|
||
security:
|
||
- bearerAuth: []
|
||
- streamQueryToken: []
|
||
parameters:
|
||
- name: Range
|
||
in: header
|
||
required: false
|
||
description: A byte range, for example `bytes=0-99`.
|
||
schema: {type: string}
|
||
- name: If-Modified-Since
|
||
in: header
|
||
required: false
|
||
schema: {type: string}
|
||
- name: If-Unmodified-Since
|
||
in: header
|
||
required: false
|
||
schema: {type: string}
|
||
responses:
|
||
'200':
|
||
description: The whole file.
|
||
headers:
|
||
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
|
||
Content-Length: {$ref: '#/components/headers/ContentLength'}
|
||
Last-Modified: {$ref: '#/components/headers/LastModified'}
|
||
content:
|
||
audio/mpeg:
|
||
schema: {type: string, format: binary}
|
||
audio/flac:
|
||
schema: {type: string, format: binary}
|
||
'206':
|
||
description: |
|
||
The requested byte range. Several ranges in one request are answered as
|
||
`multipart/byteranges`.
|
||
headers:
|
||
Content-Range:
|
||
description: The range sent and the size of the file, for example `bytes 0-99/40635`. Absent for a multipart answer.
|
||
schema: {type: string}
|
||
content:
|
||
audio/mpeg:
|
||
schema: {type: string, format: binary}
|
||
audio/flac:
|
||
schema: {type: string, format: binary}
|
||
multipart/byteranges:
|
||
schema: {type: string, format: binary}
|
||
'304': {description: Not modified since `If-Modified-Since`.}
|
||
'412': {description: '`If-Unmodified-Since` names a date before the last change of the file.'}
|
||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'404':
|
||
description: No such track (`track_not_found`), or its file is not available (`file_missing`).
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Error'}
|
||
'416':
|
||
description: The range cannot be satisfied.
|
||
headers:
|
||
Content-Range:
|
||
description: '`bytes */<size of the file>`.'
|
||
schema: {type: string}
|
||
head:
|
||
tags: [Playback]
|
||
operationId: headTrackStream
|
||
summary: Headers of a stream
|
||
description: Same as `GET`, without the body.
|
||
security:
|
||
- bearerAuth: []
|
||
- streamQueryToken: []
|
||
parameters:
|
||
- name: Range
|
||
in: header
|
||
required: false
|
||
schema: {type: string}
|
||
- name: If-Modified-Since
|
||
in: header
|
||
required: false
|
||
schema: {type: string}
|
||
- name: If-Unmodified-Since
|
||
in: header
|
||
required: false
|
||
schema: {type: string}
|
||
responses:
|
||
'200':
|
||
description: Headers of the whole file.
|
||
headers:
|
||
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
|
||
Content-Length: {$ref: '#/components/headers/ContentLength'}
|
||
Last-Modified: {$ref: '#/components/headers/LastModified'}
|
||
'206':
|
||
description: Headers of the requested range.
|
||
headers:
|
||
Content-Range:
|
||
schema: {type: string}
|
||
'304': {description: Not modified since `If-Modified-Since`.}
|
||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'404': {description: No such track or file.}
|
||
'412': {description: '`If-Unmodified-Since` names a date before the last change of the file.'}
|
||
'416': {description: The range cannot be satisfied.}
|
||
|
||
/providers:
|
||
get:
|
||
tags: [Providers]
|
||
operationId: listProviders
|
||
summary: List the external providers
|
||
description: |
|
||
Admin only. Every provider Sonda knows (Last.fm, MusicBrainz), with whether it is on and
|
||
what it would send. Providers are off by default: nothing leaves the server until an admin
|
||
enables one. The API key is never returned; `has_api_key` says whether one is stored.
|
||
security: [{bearerAuth: []}]
|
||
responses:
|
||
'200':
|
||
description: The providers, in a fixed order.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [providers]
|
||
properties:
|
||
providers:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/Provider'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'403': {$ref: '#/components/responses/AdminRequired'}
|
||
|
||
/providers/{name}:
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
required: true
|
||
schema: {type: string, enum: [lastfm, musicbrainz]}
|
||
put:
|
||
tags: [Providers]
|
||
operationId: updateProvider
|
||
summary: Set up a provider
|
||
description: |
|
||
Admin only. Send any of `enabled`, `api_key` and `contact`; fields you leave out are kept.
|
||
|
||
The key is write-only: it is never returned and never logged. Sending an empty `api_key`
|
||
clears it, and turns a provider that needs a key (Last.fm) off; a provider that needs none
|
||
(MusicBrainz) is not affected. A provider that needs a key cannot be enabled without one. `contact` goes into the User-Agent sent to the provider (MusicBrainz
|
||
asks for a URL or an e-mail address); empty means the project address.
|
||
security: [{bearerAuth: []}]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ProviderUpdate'}
|
||
responses:
|
||
'200':
|
||
description: The provider as it is now.
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Provider'}
|
||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'403': {$ref: '#/components/responses/AdminRequired'}
|
||
'404':
|
||
description: No such provider (`provider_not_found`).
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Error'}
|
||
|
||
/providers/{name}/test:
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
required: true
|
||
schema: {type: string, enum: [lastfm, musicbrainz]}
|
||
post:
|
||
tags: [Providers]
|
||
operationId: testProvider
|
||
summary: Check a provider's API key
|
||
description: |
|
||
Admin only. Asks the provider one cheap question with the stored key, to find out whether
|
||
it works. It works whether the provider is on or off, so you can check before switching it on.
|
||
It is the only request Sonda makes at an admin's command rather than for a listener, and it
|
||
sends nothing but the key. A provider that cannot be reached or refuses the key is not an
|
||
error here: the answer is `200` with `ok` false and the reason in `status`.
|
||
|
||
MusicBrainz has no key: its test only asks whether the service answers. A provider that
|
||
has no test is a `400`.
|
||
security: [{bearerAuth: []}]
|
||
responses:
|
||
'200':
|
||
description: The outcome of the check.
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ProviderTest'}
|
||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'403': {$ref: '#/components/responses/AdminRequired'}
|
||
'404':
|
||
description: No such provider (`provider_not_found`).
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Error'}
|
||
|
||
/providers/{name}/data:
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
required: true
|
||
schema: {type: string, enum: [lastfm, musicbrainz]}
|
||
delete:
|
||
tags: [Providers]
|
||
operationId: purgeProviderData
|
||
summary: Remove what a provider gave
|
||
description: |
|
||
Admin only. Removes everything the provider told Sonda: its lists of similar artists, its
|
||
tags and the records of when it was asked, and then the artists that only that data named
|
||
and that nobody has files for. Last.fm's terms ask for exactly this when an agreement ends.
|
||
|
||
Your own artists, music, listens and settings are not touched, and the provider is not
|
||
switched off: if it is still on, it is asked again when someone asks. The answer counts what
|
||
was removed; doing it again removes nothing.
|
||
security: [{bearerAuth: []}]
|
||
responses:
|
||
'200':
|
||
description: What was removed.
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ProviderPurge'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'403': {$ref: '#/components/responses/AdminRequired'}
|
||
'404':
|
||
description: No such provider (`provider_not_found`).
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Error'}
|
||
|
||
/listens:
|
||
get:
|
||
tags: [Playback]
|
||
operationId: listListens
|
||
summary: Your listening history
|
||
description: |
|
||
The events you reported, newest first, each with `counted`: whether it counts as a listen
|
||
under the current rule (see `POST /listens`). Nobody else's history is visible.
|
||
security: [{bearerAuth: []}]
|
||
parameters:
|
||
- {$ref: '#/components/parameters/Limit'}
|
||
- {$ref: '#/components/parameters/Offset'}
|
||
- name: counted
|
||
in: query
|
||
description: Send `true` to list only the events that count as a listen.
|
||
schema: {type: boolean, enum: [true]}
|
||
responses:
|
||
'200':
|
||
description: A page of events.
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ListenPage'}
|
||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
post:
|
||
tags: [Playback]
|
||
operationId: recordListen
|
||
summary: Record a listen
|
||
description: |
|
||
Clients report what the listener did: **one event per play**, when the play ends or is
|
||
abandoned, with the time actually played (`complete` if it finished, `skip` if the listener
|
||
moved on, `play` if it simply stopped).
|
||
|
||
Use **one `idempotency_key` per play**. A retry with the same key from the same user is
|
||
recorded once and answered with `duplicate`. An event cannot be upgraded afterwards: a later
|
||
event with a key that was already used is ignored, even if its type or duration differ, and
|
||
sending it with a new key would count the same play twice.
|
||
|
||
**What counts as a listen.** An event counts when its type is `complete`, or when
|
||
`duration_played_ms` is at least `listening.min_listen_seconds` (20 seconds by default).
|
||
A `play` or `skip` shorter than that is stored but does not count. The rule is applied when
|
||
the history is read, so changing the setting re-reads the past. The answer says whether this
|
||
event counts; for a `duplicate` it describes the event you sent.
|
||
|
||
**Plausibility.** When the length of the track is known, `duration_played_ms` may not exceed
|
||
twice that length plus 10 seconds (a listener can seek back and loop). Streaming a file never
|
||
records anything on its own.
|
||
security: [{bearerAuth: []}]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Listen'}
|
||
responses:
|
||
'201':
|
||
description: Recorded.
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ListenResult'}
|
||
'200':
|
||
description: Already recorded (same `idempotency_key`).
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ListenResult'}
|
||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'404':
|
||
description: No such track (`track_not_found`).
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Error'}
|
||
|
||
components:
|
||
securitySchemes:
|
||
bearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: The `access_token` from `POST /auth/login` or `POST /auth/refresh`.
|
||
streamQueryToken:
|
||
type: apiKey
|
||
in: query
|
||
name: access_token
|
||
description: The same access token, for stream URLs used by an `<audio>` element. Accepted only on `/tracks/{id}/stream`.
|
||
|
||
parameters:
|
||
Id:
|
||
name: id
|
||
in: path
|
||
required: true
|
||
schema: {type: integer, format: int64, minimum: 1}
|
||
Q:
|
||
name: q
|
||
in: query
|
||
description: |
|
||
Case-insensitive substring of the name or title. Accented letters are matched ignoring
|
||
case (`BJÖRK` finds `Björk`), but accents are kept (`bjork` does not). At most 200 characters.
|
||
schema: {type: string, maxLength: 200}
|
||
Full:
|
||
name: full
|
||
in: query
|
||
description: "`true` reads every file again, not only the new or changed ones. Only `true` and `false` are accepted."
|
||
schema: {type: boolean, default: false}
|
||
Limit:
|
||
name: limit
|
||
in: query
|
||
description: Page size. 50 when absent or 0; values above 200 are lowered to 200.
|
||
schema: {type: integer, minimum: 0, default: 50}
|
||
Offset:
|
||
name: offset
|
||
in: query
|
||
schema: {type: integer, minimum: 0, default: 0}
|
||
LibraryId:
|
||
name: library_id
|
||
in: query
|
||
description: Only items with a playable file in this library.
|
||
schema: {type: integer, format: int64, minimum: 1}
|
||
ArtistId:
|
||
name: artist_id
|
||
in: query
|
||
schema: {type: integer, format: int64, minimum: 1}
|
||
AlbumId:
|
||
name: album_id
|
||
in: query
|
||
schema: {type: integer, format: int64, minimum: 1}
|
||
|
||
headers:
|
||
AcceptRanges:
|
||
description: Always `bytes`.
|
||
schema: {type: string}
|
||
ContentLength:
|
||
schema: {type: integer}
|
||
LastModified:
|
||
schema: {type: string}
|
||
|
||
responses:
|
||
InvalidInput:
|
||
description: The request is malformed or a value is out of range (`invalid_input`).
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Error'}
|
||
Unauthorized:
|
||
description: The access token is missing, invalid or expired, or the account it belongs to no longer exists (`unauthorized`).
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Error'}
|
||
AdminRequired:
|
||
description: The account is not an admin (`admin_required`).
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Error'}
|
||
LibraryNotFound:
|
||
description: No such library (`library_not_found`).
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Error'}
|
||
ScanStarted:
|
||
description: The scan was started in the background.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [status]
|
||
properties:
|
||
status: {type: string, enum: [started]}
|
||
|
||
schemas:
|
||
Error:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [error]
|
||
properties:
|
||
error:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [code, message]
|
||
properties:
|
||
code:
|
||
type: string
|
||
description: |
|
||
A stable identifier, for example `invalid_input`, `unauthorized`, `admin_required`,
|
||
`user_not_found`, `last_admin`, `library_exists`, `scan_running`, `track_not_found`.
|
||
message: {type: string}
|
||
|
||
Credentials:
|
||
type: object
|
||
required: [username, password]
|
||
properties:
|
||
username:
|
||
type: string
|
||
minLength: 3
|
||
maxLength: 64
|
||
pattern: '^[A-Za-z0-9._-]+$'
|
||
password:
|
||
type: string
|
||
format: password
|
||
description: 8 to 256 bytes (UTF-8).
|
||
|
||
LoginRequest:
|
||
type: object
|
||
required: [username, password]
|
||
properties:
|
||
username: {type: string}
|
||
password: {type: string, format: password}
|
||
|
||
CreateUser:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Credentials'
|
||
- type: object
|
||
properties:
|
||
is_admin: {type: boolean, default: false}
|
||
|
||
User:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, username, is_admin]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
username: {type: string}
|
||
is_admin: {type: boolean}
|
||
|
||
Session:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [access_token, access_expires_at, refresh_token, refresh_expires_at, user]
|
||
properties:
|
||
access_token: {type: string}
|
||
access_expires_at: {type: string, format: date-time}
|
||
refresh_token: {type: string, description: Works once.}
|
||
refresh_expires_at: {type: string, format: date-time}
|
||
user: {$ref: '#/components/schemas/User'}
|
||
|
||
RefreshRequest:
|
||
type: object
|
||
required: [refresh_token]
|
||
properties:
|
||
refresh_token: {type: string}
|
||
|
||
PasswordChange:
|
||
type: object
|
||
required: [current_password, new_password]
|
||
properties:
|
||
current_password: {type: string, format: password}
|
||
new_password:
|
||
type: string
|
||
format: password
|
||
description: 8 to 256 bytes (UTF-8).
|
||
|
||
Library:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, name, path, created_at]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
name: {type: string}
|
||
path: {type: string, description: Absolute directory on the server.}
|
||
created_at: {type: string, format: date-time}
|
||
|
||
NewLibrary:
|
||
type: object
|
||
required: [name, path]
|
||
properties:
|
||
name: {type: string, minLength: 1, maxLength: 100}
|
||
path: {type: string, description: "Absolute, existing directory."}
|
||
|
||
LibraryUpdate:
|
||
type: object
|
||
anyOf:
|
||
- required: [name]
|
||
- required: [path]
|
||
properties:
|
||
name: {type: string, minLength: 1, maxLength: 100}
|
||
path: {type: string}
|
||
|
||
ScanSummary:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [libraries, found, added, updated, unchanged, renamed, restored, missing, failed, skipped, unsupported]
|
||
properties:
|
||
libraries: {type: integer, description: Libraries covered by the scan.}
|
||
found: {type: integer, description: Audio files seen on disk (MP3 and FLAC).}
|
||
added: {type: integer}
|
||
updated: {type: integer}
|
||
unchanged: {type: integer}
|
||
renamed: {type: integer, description: Files that moved; they keep their track.}
|
||
restored: {type: integer, description: Files that were missing and are back.}
|
||
missing: {type: integer, description: Files newly flagged as missing. They are never deleted.}
|
||
failed: {type: integer, description: Files that could not be read.}
|
||
skipped: {type: integer, description: Symlinks and special files.}
|
||
unsupported: {type: integer, description: "Audio files in formats Sonda cannot read yet, such as m4a, ogg or wav."}
|
||
|
||
ScanStatus:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [running]
|
||
properties:
|
||
running: {type: boolean}
|
||
started_at: {type: string, format: date-time}
|
||
last_finished_at: {type: string, format: date-time}
|
||
last: {$ref: '#/components/schemas/ScanSummary'}
|
||
last_error: {type: string}
|
||
|
||
ArtistRef:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, name]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
name: {type: string}
|
||
|
||
AlbumRef:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, title]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
title: {type: string}
|
||
|
||
Artist:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, name, album_count, track_count]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
name: {type: string}
|
||
album_count: {type: integer}
|
||
track_count: {type: integer, description: Playable tracks the artist is credited on.}
|
||
|
||
Album:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, title, artist, track_count, duration_ms]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
title: {type: string}
|
||
artist:
|
||
type: object
|
||
nullable: true
|
||
description: The album artist; null when the album has none.
|
||
additionalProperties: false
|
||
required: [id, name]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
name: {type: string}
|
||
track_count: {type: integer}
|
||
duration_ms: {type: integer, format: int64}
|
||
|
||
Track:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, title, duration_ms, track_no, disc_no, album, artists, format]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
title: {type: string}
|
||
duration_ms: {type: integer, format: int64}
|
||
track_no: {type: integer, description: 0 when unknown.}
|
||
disc_no: {type: integer, description: 0 when unknown.}
|
||
album:
|
||
type: object
|
||
nullable: true
|
||
description: The album; null for a track that belongs to none.
|
||
additionalProperties: false
|
||
required: [id, title]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
title: {type: string}
|
||
artists:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ArtistRef'}
|
||
format: {type: string, description: 'Format of the first playable file, for example `mp3` or `flac`.'}
|
||
|
||
ArtistPage:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [items, total, limit, offset]
|
||
properties:
|
||
items:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/Artist'}
|
||
total: {type: integer, description: "Size of the whole result, not of this page."}
|
||
limit: {type: integer}
|
||
offset: {type: integer}
|
||
|
||
AlbumPage:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [items, total, limit, offset]
|
||
properties:
|
||
items:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/Album'}
|
||
total: {type: integer}
|
||
limit: {type: integer}
|
||
offset: {type: integer}
|
||
|
||
TrackPage:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [items, total, limit, offset]
|
||
properties:
|
||
items:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/Track'}
|
||
total: {type: integer}
|
||
limit: {type: integer}
|
||
offset: {type: integer}
|
||
|
||
Listen:
|
||
type: object
|
||
required: [track_id, event_type, idempotency_key]
|
||
properties:
|
||
track_id: {type: integer, format: int64, minimum: 1}
|
||
event_type: {type: string, enum: [play, complete, skip]}
|
||
occurred_at: {type: string, format: date-time, description: Defaults to now.}
|
||
duration_played_ms:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
description: Milliseconds actually played. Up to twice the track length plus 10 seconds when that length is known.
|
||
idempotency_key: {type: string, description: "One per play, 1 to 128 bytes (UTF-8). A key that was already used is ignored."}
|
||
|
||
Provider:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [name, enabled, needs_api_key, has_api_key, contact, sends, notes, updated_at]
|
||
properties:
|
||
name: {type: string, enum: [lastfm, musicbrainz]}
|
||
enabled: {type: boolean, description: Whether Sonda may contact this provider.}
|
||
needs_api_key: {type: boolean}
|
||
has_api_key: {type: boolean, description: Whether a key is stored. The key itself is never returned.}
|
||
contact: {type: string, description: Contact in the User-Agent; empty means the project address.}
|
||
sends: {type: string, description: "Plain statement of what is sent to the provider, and what never is."}
|
||
notes: {type: string, description: Terms of use and attribution that apply to the provider's data.}
|
||
updated_at:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
description: When the settings last changed; null if they never did.
|
||
|
||
ProviderUpdate:
|
||
type: object
|
||
anyOf:
|
||
- required: [enabled]
|
||
- required: [api_key]
|
||
- required: [contact]
|
||
properties:
|
||
enabled: {type: boolean}
|
||
api_key:
|
||
type: string
|
||
format: password
|
||
description: A Last.fm key is 32 hexadecimal characters. Empty clears it.
|
||
contact:
|
||
type: string
|
||
maxLength: 200
|
||
description: A URL or e-mail address, without parentheses. Empty restores the default.
|
||
|
||
ProviderPurge:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [similar_artists, tags, artists]
|
||
properties:
|
||
similar_artists: {type: integer, description: Similar-artist links removed.}
|
||
tags: {type: integer, description: Tags removed.}
|
||
artists: {type: integer, description: "Artists removed because only the removed data named them and nobody has files for them."}
|
||
|
||
ProviderTest:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [ok, status]
|
||
properties:
|
||
ok: {type: boolean}
|
||
status:
|
||
type: string
|
||
enum: [ok, no_api_key, key_refused, rate_limited, unreachable, error]
|
||
description: |
|
||
`no_api_key`: none is stored, so nobody was asked. `key_refused`: the provider does not accept
|
||
it. `rate_limited`: try again later. `unreachable`: the provider did not answer. `error`: anything else.
|
||
|
||
ArtistTags:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [sources]
|
||
properties:
|
||
sources:
|
||
type: array
|
||
items:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [provider, provider_status, stale, retrieved_at, attribution, tags]
|
||
properties:
|
||
provider: {type: string, enum: [lastfm, musicbrainz, files]}
|
||
provider_status:
|
||
type: string
|
||
enum: [ok, disabled, error, no_id]
|
||
description: |
|
||
`ok`: the data is as fresh as it needs to be. `disabled`: the provider is off or has no
|
||
key, so it was not asked. `error`: it was asked and failed. `no_id`: it needs the
|
||
MusicBrainz id of the artist, which is not known, so it was not asked.
|
||
stale: {type: boolean, description: "True when `tags` are older than they should be because the provider could not be asked."}
|
||
retrieved_at:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
description: When the provider was last read for this artist; null if never.
|
||
attribution: {type: string, description: Credit to show where the tags are shown.}
|
||
tags:
|
||
type: array
|
||
description: The heaviest tags first, at most 50.
|
||
items:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [name, weight, genre]
|
||
properties:
|
||
name: {type: string, description: Lower case.}
|
||
weight: {type: number, description: "The provider's own number; see the operation."}
|
||
genre: {type: boolean}
|
||
|
||
SimilarArtists:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [provider, provider_status, stale, retrieved_at, attribution, items]
|
||
properties:
|
||
provider: {type: string, enum: [lastfm]}
|
||
provider_status:
|
||
type: string
|
||
enum: [ok, disabled, error]
|
||
description: |
|
||
`ok`: the data is as fresh as it needs to be. `disabled`: the provider is off or has no key,
|
||
so it was not asked. `error`: it was asked and failed.
|
||
stale: {type: boolean, description: "True when `items` are older than they should be because the provider could not be asked."}
|
||
retrieved_at:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
description: When the provider was last read for this artist; null if never.
|
||
attribution: {type: string, description: Credit to show where the data is shown.}
|
||
items:
|
||
type: array
|
||
items:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [artist, in_library, score, rank]
|
||
properties:
|
||
artist: {$ref: '#/components/schemas/ArtistRef'}
|
||
in_library: {type: boolean, description: Whether the artist has something playable in the library.}
|
||
score: {type: number, minimum: 0, maximum: 1, description: "The provider's own number, relative to this list."}
|
||
rank: {type: integer, minimum: 1, description: "Position in the provider's list, 1 first."}
|
||
|
||
ListenResult:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [status, counted]
|
||
properties:
|
||
status: {type: string, enum: [recorded, duplicate]}
|
||
counted: {type: boolean, description: Whether the event counts as a listen.}
|
||
|
||
ListenItem:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, track, event_type, occurred_at, duration_played_ms, counted]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
track:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, title]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
title: {type: string}
|
||
event_type: {type: string, enum: [play, complete, skip]}
|
||
occurred_at: {type: string, format: date-time}
|
||
duration_played_ms: {type: integer, format: int64}
|
||
counted: {type: boolean, description: Whether the event counts as a listen under the current rule.}
|
||
|
||
Taste:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [artists, tags]
|
||
properties:
|
||
artists:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/TasteArtist'}
|
||
tags:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/TasteTag'}
|
||
|
||
Discover:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [provider_status, attribution, from_listening, seeds, items]
|
||
properties:
|
||
provider_status: {type: string, enum: [ok, disabled, error]}
|
||
attribution: {type: string, description: What to show where the data is shown.}
|
||
from_listening: {type: boolean, description: "True when the seeds were taken from your listening, false when you named them."}
|
||
seeds:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/DiscoverSeed'}
|
||
items:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/Suggestion'}
|
||
|
||
DiscoverSeed:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, name, weight]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
name: {type: string}
|
||
weight: {type: number, minimum: 0, maximum: 1, description: "1 for a seed you named, your preference for one taken from your listening."}
|
||
|
||
Suggestion:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [artist, in_library, score, components, because]
|
||
properties:
|
||
artist: {$ref: '#/components/schemas/ArtistRef'}
|
||
in_library: {type: boolean}
|
||
score: {type: number, minimum: 0, maximum: 1}
|
||
components: {$ref: '#/components/schemas/ScoreParts'}
|
||
because:
|
||
type: array
|
||
description: Up to three seeds that count most for this suggestion, strongest first.
|
||
items: {$ref: '#/components/schemas/SuggestionReason'}
|
||
|
||
ScoreParts:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [a, g, p, d]
|
||
properties:
|
||
a: {type: number, minimum: 0, maximum: 1, description: Affinity.}
|
||
g: {type: number, minimum: 0, maximum: 1, nullable: true, description: "Genre. Null when the artist has no tags or you have no taste to compare with; the score is then worked out without it."}
|
||
p: {type: number, minimum: 0, maximum: 1, description: Preference. 0.5 for an artist you never played.}
|
||
d: {type: number, minimum: 0, maximum: 1, description: Discovery bonus.}
|
||
|
||
SuggestionReason:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [artist, match]
|
||
properties:
|
||
artist: {$ref: '#/components/schemas/ArtistRef'}
|
||
match: {type: number, minimum: 0, maximum: 1, description: "Last.fm's similarity of the suggestion to this seed, relative to the seed's own list."}
|
||
|
||
UserSettings:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [discover_from_listening]
|
||
properties:
|
||
discover_from_listening:
|
||
type: boolean
|
||
description: |
|
||
When true, Discover may start from the artists you listen to most. That sends their
|
||
names to Last.fm, which is asked for artists similar to each one (only when an admin
|
||
switched Last.fm on). When false, Discover starts only from artists you name yourself.
|
||
False until you turn it on. What Last.fm answers is stored like any other lookup and is
|
||
shared: another user can see from `retrieved_at` in `GET /artists/{id}/similar` that
|
||
somebody looked an artist up, but not who.
|
||
|
||
UpdateUserSettings:
|
||
type: object
|
||
additionalProperties: false
|
||
properties:
|
||
discover_from_listening: {type: boolean, nullable: true}
|
||
|
||
TasteArtist:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, name, preference, listens, last_listened_at]
|
||
properties:
|
||
id: {type: integer, format: int64}
|
||
name: {type: string}
|
||
preference: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 1, description: How much you like the artist. Only artists above 0 are listed.}
|
||
listens: {type: integer, description: "Events that count as a listen, with no decay, within the period that is read (ten half-lives)."}
|
||
last_listened_at: {type: string, format: date-time, description: The most recent listen that counted.}
|
||
|
||
TasteTag:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [tag, weight]
|
||
properties:
|
||
tag: {type: string, description: Lower case.}
|
||
weight: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 1, description: "How much the tag matters to you; the best one is 1."}
|
||
|
||
ListenPage:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [items, total, limit, offset]
|
||
properties:
|
||
items:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ListenItem'}
|
||
total: {type: integer, description: "Size of the whole result, not of this page."}
|
||
limit: {type: integer}
|
||
offset: {type: integer}
|