Module user

What the user writes: favourites, ratings, notes, tags, listening history.

This is the only data in the program that cannot be recovered. Lose the catalog and a scan rebuilds it in a minute; lose this and it is gone. Two consequences run through the whole module.

It lives in its own file, never in the catalog. The catalog is derived from the disk and written whole; a rating that changes on a keystroke has no business rewriting a library.

It is never keyed by a catalog identifier. Those are positions in a vector that every scan renumbers — the lesson the imported analyses already taught, at the cost of a rewrite. A EntityRef names a thing the way the thing names itself, and an annotation whose target is missing is kept waiting, never dropped: a folder renamed between two scans must not cost anybody a note they wrote.

Favourites, ratings, notes and tags look like four features and are one: something a person said about an entity. One record per target, so copying everything said about one album onto another is a record copy rather than a loop over four kinds.

Structs

Annotation

Everything one person said about one entity.

Attachment

Counts personal records attached, waiting, or relocated during reconciliation.

ClientPreference

One application-owned JSON document; no credentials belong in this table.

Collection

A query saved under a name: a smart collection.

EntityRef

A stable way to name an entity, independent of any scan.

Merge

What a merge did, so that an import can say it rather than be trusted.

Play

One listening event.

PlayCount

How often one person played one track, for as long as the library lasts.

PlaybackEntry

One stable queue occurrence; repeating a track uses another occurrence ID.

PlaybackSettings

Processing settings restored explicitly with a native-player profile.

PlaybackSource

File evidence captured when selecting a resumable source.

PlaybackState

One private named checkpoint, resumed only by an explicit client request.

Playlist

One owner’s ordered, private selection, independent of catalog identifiers.

RelationAnnotation

A personal note and free-form labels attached to one relationship.

Relink

A user’s explicit decision to reattach personal data.

RelinkSummary

Counts of personal records moved by one explicit reattachment.

SameArtist

Two spellings the owner of the disk says are one musician.

Scrobble

A client declares that a track was listened to, without playback evidence.

SetAside

A record the user has taken off a report, and why that is allowed.

TrackIdentity

Last observed identity evidence for a file named by personal data.

UserData

Everything the user wrote, as it sits on disk.

Constants

HISTORY_LIMIT

Events kept per owner in each native-play or scrobble journal before that owner’s oldest events are forgotten.

HISTORY_STORE_LIMIT

Global journal capacity, independent of per-owner retention. Publication refuses this bound rather than evicting another owner’s records.

LOCAL_USER

The owner of a library nobody has named yet.

PLAYBACK_ENTRY_LIMIT

Maximum ordered occurrences retained by one player profile.

PLAYBACK_PROFILE_LIMIT

Maximum named player profiles belonging to one immutable owner.

PLAYBACK_STATE_LIMIT

Maximum native-player checkpoints in one personal store.

PLAYLIST_LIMIT

Maximum static playlists in one personal store.

PLAYLIST_OWNER_LIMIT

Maximum static playlists belonging to one owner.

PLAYLIST_TRACK_LIMIT

Maximum ordered entries in one static playlist, including repetitions.

RELEASE_KEY_SEPARATOR

What separates the three parts of a release key.

USER_FILE

Name of the user file inside the data folder.

USER_FORMAT_VERSION

Version of the user file on disk, independent of the catalog’s.

USER_MAX_BYTES

Maximum UTF-8 bytes read from or published to the personal store.

Functions

from_json

Reads the document back.

load

Loads what the user wrote; Ok(None) when nothing has been written yet.

merge

Folds one set of user data into another.

reconcile

Reconciles personal references without guessing from a filename alone.

save

Saves what the user wrote, atomically.

to_json

The document, one array per table.

user_path

Where the user file sits inside a data folder.

valid_playback_profile

Whether a native-player profile uses the bounded case-sensitive spelling.

valid_preference

Validate storage bounds independently of any HTTP/frontend schema.

Type Aliases

UserRef

Whose opinion it is.