Each user can make playlists: a name (1 to 200 characters), an optional
description and an ordered list of tracks, where a track may appear more than once
(each place has its own item id). The API makes, lists, renames and deletes
playlists, and adds tracks (at the end or at a position), lists them, moves one and
removes one; positions count from 0 without gaps.
A playlist is its owner's alone: somebody else's answers playlist_not_found (404),
as one that does not exist. A track whose files were deleted or moved stays in the
playlist and is listed with available false. Deleting a user deletes their
playlists. Limits: 1,000 playlists per user, 10,000 tracks per playlist, 500 tracks
per request.
Changes of one playlist are serialised by locking its row, so two requests at once
keep the positions unique on PostgreSQL too. Migration 0019, OpenAPI spec, contract
test, README and the web API types follow. The web app comes separately.
Closes#89
Admin only. GET /library/duplicates lists the groups with what is needed to choose and never a path; POST|GET|DELETE /library/duplicates/check is the job that fingerprints the files; POST /library/duplicates/clean deletes the chosen copies of one song, each refusal with its own status and code (deletion_disabled, scan_running, invalid_input, track_not_found, duplicate_changed, library_read_only). In the spec with the contract test, and wired in main, where an info line says when library.allow_delete is on.
Registration, login and the admin's create-user call take `email` instead of
`username`, and the user object returns `email`. The address is checked for its
shape (a plain address, no display name, at most 254 bytes), trimmed, lowercased
and unique. Sonda sends no mail and does not verify it.
- Migration 0018 renames the users column (and the PostgreSQL index); values are
kept, so an account made before keeps its plain name and still logs in with it
(login does not check the shape).
- Error code username_taken becomes email_taken; the JWT claim is now `email`,
so access tokens issued before the upgrade are refused once and clients refresh.
- OpenAPI spec, README, the web login form (type email), strings (en, it) and
the generated API types follow.
Closes#65
- POST /artists/{id}/lidarr (admin) adds the artist to the admin's own Lidarr by its
MusicBrainz id, never by name, with the profiles, the folder and the monitor
option the admin chose. It works for any artist that has an id, also one that
Sonda only learned of from a list of similar artists. It can be repeated: an artist
that Lidarr already has changes nothing. Two sends at once go one after the other.
- GET /artists/{id}/lidarr (signed in) says whether Lidarr has the artist and
monitors it; what stops the answer is a status (disabled, no_id, not_configured,
error), as for the descriptions.
- It needs the provider switched on and the profiles and folder chosen; a timeout
says the artist may have been added anyway.
- Spec, contract test and README, which also say that Sonda downloads nothing.
Lidarr is a server of the user's own that looks for and downloads music. Sonda
never downloads; this is the first piece of letting an admin send it an artist.
- The `lidarr` provider, off by default: an address, an API key (32 hexadecimal
characters, never returned) and, chosen once, a quality profile, a metadata
profile, a root folder, the monitor option and whether to search for missing
albums. It cannot be enabled without an address and a key.
- The address is checked: http or https, no user and password, no query, no
fragment, no closing slash.
- A small client of its own, apart from the outbound one (which only makes plain
GETs): the key travels in a header, no redirect is ever followed, answers and
time are bounded, and the address and key are read for every request.
Status, options, artist by MusicBrainz id and add (lookup, then the add that
Lidarr's own screen sends).
- `GET /providers/lidarr/options` lists the profiles and root folders; the test of
the provider checks the address and the key (`no_address` when it has none).
- Migration 0017 adds the address and the options to the provider settings.
- OpenAPI, contract test and README say what is sent and where.
Add one engine, internal/jobs, that runs the jobs which go through the whole
library: start, stop, progress, one at a time, give up after five failures in
a row, end at once when a provider is off.
- The covers job now runs on the engine; its API is unchanged.
- POST/GET/DELETE /library/artist-images looks for the picture of every
artist of the library that has a MusicBrainz id.
- POST/GET/DELETE /library/descriptions does the same for the Wikipedia
description.
- ?refresh=true searches everything again and never replaces a stored result
by a failure; artists without an id are never touched, nothing is looked up
by name.
- images.Service.EnsureArtistImage and about.Service.Ensure do the work for one
artist; the lists come from ImageRepo and DiscoveryRepo.
- jobs.Runner binds a job to the application context, replacing the two
hand-written controls.
- OpenAPI, contract test and README describe the new endpoints and say that
they are bulk requests.
- POST /library/covers (admin) starts, in the background and one at a time like a scan,
a job that builds the cover of every album that has something to play and no cover that
is still good; GET /library/covers shows the progress and how the last job ended;
DELETE /library/covers stops it. ?refresh=true searches every album again.
- For each album it does what opening its cover does: the user's own files first, then the
Cover Art Archive if the provider is on. It gives up, and says why, when the provider
fails for five albums in a row; an album that vanished is skipped, not a failure.
- This is the one request that goes through the whole library, and the README and the
provider text say so: with the archive on it sends the release group id of each album with
no picture in its files, one after the other, spaced out.
- NewRouter now refuses to build when a service was not wired, naming it, instead of
panicking at the first request (the wiring of this job in main had been missed, which no
test could see).
- The outbound spacing test measures where the request leaves the client, so a busy
machine cannot make it fail.
- Spec, contract and HTTP tests, README updated.
Closes#45
- The scan reads the MusicBrainz release group id of an album from the tags of its
files (MUSICBRAINZ_RELEASEGROUPID, a vorbis comment or an ID3 frame) and stores it in
albums.mbid: it is taken only when the file has an album and exactly one valid id, an
album keeps the one it has, and an id that another album owns is not given twice. A full
rescan reads it for music that was already indexed.
- New provider "coverartarchive" (off by default, no key, contact in the User-Agent). When
an album has no picture in the user's own files, which always come first, its cover is
asked from the archive by that id and never by a title: only the id leaves the server.
The same GET /albums/{id}/cover; the record keeps the source. An outage is a 502
provider_unavailable and is not remembered, and an older cover is served in its place.
- The archive answers with three redirects (coverartarchive.org, archive.org, a data node
whose name changes). The outbound client can now follow redirects, but only the ones the
caller allows, up to a limit; here that is https on archive.org and its subdomains.
- A purge counter now guards the covers too: a read that started before the provider's data
was taken back is not kept. Removing the provider's data forgets the covers that came from
it and deletes their files, and leaves the ones from the user's files.
- Spec, contract and HTTP tests, README updated; the facts of the real archive are written down.
Closes#43
- GET and HEAD /artists/{id}/image serve a free picture of an artist as a JPEG
(size=small 300 px or large 1000 px, token in the query allowed for an <img>), and
GET /artists/{id}/image/credit gives the author, the licence and the page of the file,
to be shown next to it.
- New provider "commons" (off by default, no key, contact in the User-Agent), which also
needs MusicBrainz on. The way to the picture uses ids only, never a name: the artist's
MusicBrainz id, the Wikidata item MusicBrainz links to it, the file Wikidata names for
it (P18), Commons for its licence, and a 960 px copy from a Wikimedia picture host.
- Only free licences: public domain, CC0, CC BY and CC BY-SA. Non-commercial,
no-derivatives, GFDL alone, fair use and unknown licences are refused, since a copy is
kept. The author is plain text, the licence address is kept only on creativecommons.org,
and the download only from https thumb.wikimedia.org or upload.wikimedia.org.
- Built on the first request, kept in the data folder: 30 days, or a week when there is no
free picture; an older copy is served when Commons cannot be reached; a failure is not
remembered. Credit changes change the ETag.
- Removing the provider's data forgets the records and deletes the files; a read that started
before it is not saved over it.
- images table gets the credit (migration 0015); the purge reports images.
- Spec, contract test, README updated; the facts of the real APIs are written down.
Closes#41
- A page that cannot be used (no text, an address off Wikipedia, a redirect that is
never followed) is now an answer: the chain goes on to the next language and the
outcome is stored. Before, it was a failure asked about again at every view, and
redirects counted against the provider's breaker.
- The chain also needs the MusicBrainz provider to be on, since the id goes to it
with its own contact: nothing is sent to MusicBrainz that the admin did not allow.
The disclosure in the provider settings, the spec and the README say so.
- A Wikidata item that was merged into another is understood through the target: the
entity's own id is returned, compared with the page's item and stored. Verified on
the real API.
- The title shown is the one Wikidata names (with spaces), control characters are
dropped from the text (PostgreSQL refuses NUL), the text is cut to at most 4000
characters with the mark included, and a stored description is reported disabled
when the provider is off.
- A read that started before the provider was switched off does not save its result.
- Tests: the real clients with a redirect and a page without text, merged items,
MusicBrainz off, switching off during a read.
- GET /artists/{id}/description shows what Wikipedia says about an artist: a short
text with its page, a link and the licence (CC BY-SA 4.0).
- New provider "wikipedia" (off by default, no key, contact in the User-Agent, which
Wikimedia requires). The way to the text is a chain of ids, never a name: the
artist's MusicBrainz id, the Wikidata item MusicBrainz links to it, the Wikipedia
page Wikidata names in the first configured language that has one. A page is used
only if it is an article about that same item.
- [wikipedia] languages in the config (one to five codes of two or three lower case
letters, checked before they are sent: an unknown site makes Wikidata answer with
every language).
- Stored 30 days (a day when there was nothing to find), served stale if Wikipedia
fails, removed with the provider's data (the purge now reports descriptions).
- MusicBrainz client: WikidataID. Wikipedia client for Wikidata and the summary,
which also reads Wikidata's errors that come with HTTP 200.
- artist_descriptions table (migration 0014, SQLite and PostgreSQL).
- Spec, contract test, README and example config updated.
Closes#39
- At most two covers are built at the same time: a page of albums asked for at once
could decode dozens of large pictures together.
- A change to an album's files marks its record stale and moves a generation instead
of deleting the row. A build that started before the change is not saved over it
and starts again, so a "no cover" found too early cannot win for a day.
- A cover that was found is checked again after a week, so a picture replaced in a
folder is noticed.
- For CD1/Disc 2 folders the picture in the folder above is used. Folder pictures
are read one at a time, and the pixel count is computed in 64 bits.
- Stored files are synced before they get their name, an empty one counts as
missing, and old temporary files from a crash are removed.
- Files without track or disc numbers sort the same on both databases.
- storage.data_dir defaults next to the SQLite database, so a service started from
another folder does not need a writable working directory.
- Tests: a listener who leaves, a change during a build, the build limit, a named
pipe, an embedded picture of a file outside the library that exists, builds that
really overlap.
- GET and HEAD /albums/{id}/cover serve a JPEG made from the picture embedded in
the album's files, or else a cover, folder, front, album or albumart image
(jpg, jpeg, png) in the album's folder. ?size=small (300 px) or large (1000 px).
The token can be in the query, so an <img> element can use it.
- Built the first time it is asked for, scaled, and kept in storage.data_dir
(SONDA_DATA_DIR, default "data"); an album with no cover is remembered for a day.
A new or changed file of the album, or a full rescan, clears the record.
- Nothing is sent anywhere. Pictures are untrusted: files are opened inside the
library only (links are not followed), over 20 MB or 16 million pixels are
ignored, and what is served is always a JPEG made here. Stored files are 0600.
- images table (migration 0013, SQLite and PostgreSQL).
- Spec, contract test, README and example config updated.
Closes#37
- PUT/DELETE /wishlist/{artist} and GET /wishlist: the artists I want.
- POST/DELETE /discover/{artist}/dismiss and GET /discover/dismissed: the
artists I am not interested in. An artist is wished or dismissed, never both,
and both lists are mine alone.
- Discover never suggests a dismissed artist, does not use one as a seed taken
from my listening, and marks the wished ones it shows (wishlisted).
- New artist_feedback table (migration 0012, SQLite and PostgreSQL), removed
with the account.
- An artist I marked is not cleaned up when the list that named it is replaced,
and goes when its last mark is taken off and nobody names it. Taking a
provider's data back still removes what only it named, marks included.
- Spec, contract test and README updated.
Closes#35
- GET /discover suggests artists, in my library or not, with a score from 0 to 1
and its parts: affinity (similar to the artists I like), genre (tags close to
mine), preference (what my listening says) and discovery (a bonus for what I
have not played). Default weights 0.40, 0.25, 0.25, 0.10, set in [scoring].
- A part with no data (no tags) is left out and the others rescaled; the answer
says which parts were there, and which seeds led to each suggestion.
- Seeds are the artists I name with ?seed=, or, only when I turned on
discover_from_listening, the artists I play most. Without either the request is
refused and nothing is sent to anyone.
- The tags of the best candidates are read from Last.fm only, only for those with
none stored, a few at a time.
- taste.Service.Learn gives the whole picture (every preference, the liked
artists, the tag profile); TagService.ProviderTags asks one provider.
- Spec, contract test, README and example config updated.
Closes#33
- GET and PATCH /me/settings: settings that belong to the signed-in user.
- First setting, discover_from_listening, is off by default. When on, Discover
may start from the artists I listen to most, which sends their names to
Last.fm.
- New user_settings table (migration 0011, SQLite and PostgreSQL), removed with
the account. A user with no row has the private defaults.
- A misspelt setting is rejected instead of being ignored.
- Spec, contract test and README updated.
Refs #29
- taste package: each listening event has a value (complete +1, a play that
counts +0.5, a skip that does not count -1, a short play 0), older events
weigh less (half-life 90 days, taste.half_life_days), and the values of an
artist become a preference in (-1, 1) with tanh.
- Tag profile built from the artists I like: genres of my files plus the tags
already stored from providers, each source scaled to its own best tag.
- GET /me/taste shows the liked artists and the tags. It reads local data only
and never asks a provider.
- TasteRepo reads events, names and tags; tests on SQLite and PostgreSQL.
- OpenAPI spec, contract test, README and example config updated.
Closes#27
- feat: DELETE /api/v1/providers/{name}/data (admin) removes everything a
provider gave: its lists of similar artists, its tags and the records of
when it was asked, then the artists that only that data named and that
nobody has files for. Last.fm's terms ask for this when an agreement ends.
The user's own artists, music, listens and settings stay, the provider is not
switched off, and a second call removes nothing
- feat: a discovered artist that no list names any more is removed when the
list that named it is replaced, together with its tags, so they do not pile
up. Real artists, and any artist that another list still names, are kept
- feat: the scan reads the GENRE tag of each file, offline (several genres
separated by ";", lower case, at most five per file), and
GET /artists/{id}/tags gets a third entry, files: the genres of the artist's
own playable tracks, each weighted by how many tracks have it. It asks nobody
and is always there
- feat: POST /library/scan and POST /libraries/{id}/scan take full=true to read
every file again, not only the new or changed ones, so MusicBrainz ids and
genres reach music that was indexed before. Files keep their identity, so
listening history is kept. Anything but true or false is a 400
- test: the plan of a full scan, the scanner and the manager; the purge on both
databases, checked by removing the rule that spares real artists; the
cleanup of replaced lists; genres per file and per artist
- docs: README, OpenAPI and the todo list updated
- 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
- feat: GET /api/v1/artists/{id}/similar lists the artists Last.fm finds similar
to one in the library, best first, each with the provider's own score and
rank and a flag saying whether it is in the library. It answers 200 when the
provider is off or failing, with provider_status, stale and retrieved_at
- feat: a thin Last.fm client on top of the outbound client. It always sends
autocorrect=0 so a misspelled local name cannot turn into another artist,
prefers the MusicBrainz id when known, always sets a limit, and reads the
error field even when the status is 200. Errors never carry the URL or the
provider's own message, because the key travels in the query string
- feat: results are stored in artist_similar with a freshness ledger in
provider_fetches: 7 days for an answer, 1 day for "unknown artist". Old data
is served when the provider fails, and concurrent requests for the same
artist share one call that does not depend on the first caller staying
- feat: artists named by a provider but without files become artists without
tracks. GET /artists/{id} can show them (track_count 0), the lists of the
library never include them, and a later scan adopts them by name. A provider
id is never written onto an existing artist; names match only when at least
one side has no id, and different ids always mean different artists
- feat: POST /providers/{name}/test (admin) checks a stored key with one cheap
request, whether the provider is on or off, and reports ok, no_api_key,
key_refused, rate_limited, unreachable or error
- test: the whole request is checked from the receiving end, with a user, a
listen, a title and a library path in the database: only the artist and the
key leave, with a User-Agent that names the project
- docs: README and OpenAPI updated; the contract test calls the new operations
- feat(storage): provider_settings table (provider, enabled, api_key, contact);
migration 0007 for both drivers. A provider with no row, or turned off, is
never contacted
- feat(providers): a service that validates and applies settings: a Last.fm key
is 32 hexadecimal characters, enabling a provider that needs a key without
one is refused, clearing the key turns the provider off, a contact cannot
contain parentheses or control characters. Each provider states what it sends
and under which terms, and what it never sends
- feat(api): admin-only GET /providers and PUT /providers/{name}. The API key is
write-only: responses carry only has_api_key, errors never repeat it and the
request log never contains it (tested)
- feat(providers/outbound): the only way Sonda talks to the outside: plain GET
with an identifiable User-Agent, no cookies, no Referer, no Authorization, no
redirects, bounded answers, a timeout per attempt, a minimum interval between
requests, retries with exponential backoff that honour Retry-After without
waiting past the caller's deadline or for an absurd time, and a circuit
breaker that makes a failing provider fail fast
- feat(providers): UserAgent builds "Sonda/version ( contact )" as MusicBrainz
asks, defaulting to the project address so no personal address is sent
- breaking(config): providers.lastfm and SONDA_LASTFM_API_KEY are gone; an old
config, or the variable, fails with a hint instead of being ignored
- docs: OpenAPI operations and schemas, README section on the providers and on
what leaves the server
- test: fake servers and a fake clock only; no network in the suite
- feat: an event counts as a listen when it is `complete`, or when it was
played for at least listening.min_listen_seconds (default 20, 1 to 3600).
The rule is applied when the history is read, not when an event is stored,
so changing the setting re-reads the past; streaming never counts
- feat(api): POST /listens answers with `counted`, also for a duplicate
- feat(api): GET /listens returns the signed-in user's own history, newest
first, with `counted` per event, paging and ?counted=true; nobody sees
anybody else's events
- feat: a reported play time more than twice the track length plus ten seconds
is rejected as implausible; looping and seeking back stay allowed, and a
track of unknown length is not checked
- feat(storage): TrackDurationMs and ListEvents on SQLite and PostgreSQL
- docs: OpenAPI operations and schemas, README rule, setting, API table and a
demo that reports a 25 s and a 3 s play and reads the history; the demo tones
now last 30 s so a 25 s play is plausible
- test: the rule at its boundaries, the plausibility bound, history order,
paging and isolation on both databases, and the contract test for the new
operation
Closes#17
- fix(spec): album.artist and track.album are real nullable objects (OpenAPI
3.0 only honours nullable next to a type); the stream documents 304 on HEAD,
412, If-Unmodified-Since and multipart/byteranges answers
- fix(spec): passwords and idempotency keys are measured in bytes, an overlap
between libraries is a 400, a library PATCH needs a name or a path, limit 0
means the default, login has no format rules of its own, and the wording about
signing out says that issued access tokens live until they expire
- fix(auth): the Bearer scheme is matched ignoring case (RFC 7235)
- fix(listening): a listen with the access token of a deleted account is a 401
instead of a database error
- fix(docs): the docs pages answer HEAD and carry X-Frame-Options, a CSP
frame-ancestors, nosniff and no-referrer, since people paste their token there
- test: error codes are asserted in every error case; every accepted request is
validated against the spec too; HEAD and 3xx answers are checked by hand
because the validator skips them; the stream Content-Type must be one the
spec lists; a scan held mid-way proves the scan_running conflicts; null album
and null album artist, a vanished file, multi-range, 412 and HEAD 304 are
exercised. Verified by breaking the code and the spec on purpose
- feat: internal/api/openapi/openapi.yaml describes every operation (OpenAPI
3.0.3), written by hand and embedded in the binary; GET /api/v1/openapi.yaml
serves it
- feat: GET /api/docs/ serves Swagger UI from assets embedded in the binary
(github.com/swaggest/swgui, v5emb), so opening it never contacts another
server; both are public because they contain no data
- feat: response objects in the spec are closed (additionalProperties: false)
- test: the spec is valid OpenAPI; the router and the spec describe the same
operations in both directions; every operation has an id, a summary, a tag,
a documented 401 when it needs a token and a 403 when it is admin only
- test: a contract test drives every operation through the real services,
including a real scan and real streaming, and validates each response
(status, headers, JSON body) against the spec with kin-openapi; it fails if
an operation was never exercised. Checked by breaking the code and the spec
on purpose
- test: the docs page loads without any external address and every asset it
references is served
- docs: README section on the interactive documentation and on keeping the
spec in step with the code
Closes#15