- feat: GET /api/v1/artists/{id}/tags lists, for each provider that is on, the
tags it gives to an artist with its own weights, kept as they came: Last.fm's
are relative to the artist, MusicBrainz's are counts of votes, and they are
never mixed. MusicBrainz also marks the tags it lists as genres. The same
rules as similar artists apply: asked only on demand, kept 7 days (1 for an
unknown artist), old data served when a provider fails, and one call for
simultaneous requests. A provider that is off, failing or lacking an id does
not hide the other
- feat: a thin MusicBrainz client that reads an artist's tags and genres by its
id. It never searches by name, because a search returns look-alikes and
picking one would be a guess. The id is checked before it reaches the path,
and errors never repeat the provider's text
- feat: the User-Agent can change while the server runs, so the contact an
admin sets for MusicBrainz applies to the next request; if the settings
cannot be read it falls back to the project address
- feat: Last.fm top tags, by id when known and by name otherwise, never
autocorrected
- feat: the scan reads MusicBrainz artist ids from the file tags, offline, and
keeps them on the artists. An id is only used when it can be paired with its
artist for certain: the same number of ids as artists, all valid. The same id
is the same artist whatever the spelling, an artist without an id takes the
one its file gives, and another id under the same name is another artist. A
file that confirms the id a provider gave to a discovered artist keeps it
- feat: POST /providers/musicbrainz/test checks that the service answers
- test: what leaves the server for MusicBrainz is checked from the other end:
the id of the artist and the admin's contact, nothing from the library;
removing the safeguards on ids and pairing makes tests fail
- docs: README, OpenAPI and the provider text updated
1510 lines
55 KiB
YAML
1510 lines
55 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: Discovery
|
|
description: Music outside the library, from external providers an admin switched on.
|
|
- 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`.
|
|
security: [{bearerAuth: []}]
|
|
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.
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'202': {$ref: '#/components/responses/ScanStarted'}
|
|
'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. 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 (0 to 100, the top tag is usually 100), MusicBrainz's is a count of
|
|
votes. `genre` is true for a MusicBrainz tag that it also lists among its curated genres.
|
|
|
|
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, and only the MusicBrainz id to MusicBrainz: Sonda never looks an id up by name,
|
|
so for an artist whose id is not known (it comes from the tags in the music files) 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'}
|
|
|
|
/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'}
|
|
|
|
/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}
|
|
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 (`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.
|
|
|
|
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]}
|
|
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.}
|
|
|
|
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}
|