Data model

bae’s catalog is ordinary SQLite, declared to coven table by table: synced tables travel to every device that can read them; undeclared tables never leave the device. The split is the data model’s most load-bearing decision, so this page is organized around it.

The catalog graph

The synced heart of the schema:

• artists, albums, works: the grouping layer. An album aggregates its releases and points at a primary one; works form a parent/child graph for classical structure.
• releases: the central entity, one row per imported copy. Carries the pressing facts (label, catalog number, barcode, country, format, year), optional metadata provenance, a content hash of the imported folder, and measured album loudness. No provenance means the metadata was entered directly; external provenance names the exact source release, while file metadata records a local snapshot source.
• release_identities: exact external identities for what a release is. No rows means no external identity. Each row names a MusicBrainz or Discogs release and release group, and a release can hold identities in both sources at once. This is separate from provenance: identity can change without claiming that the current editable metadata was reset from that source.
• tracks with track_artists, plus release_artist_roles and track_artist_roles: track lists and credits, each credit tagged with its source.
• track_works, work_parts, work_artists: recordings linked to the works they perform.
• audio_formats and audio_format_segments: the playback specs. Per track: codec, sample rate, bit depth, channels, measured loudness and peak, and pregap lengths. Segments map a track onto ordered byte and sample windows of its source files, which is how a CUE rip’s track, pregap included, can span regions of one big file, or several files.
• release_files, covers, artist_images: blob-bearing tables. Rows are catalog entries; the bytes live in coven’s blob layer (see below).
• people, ratings, history, playlists, playlist_entries: each person’s profile and what they record for themselves. These are owner tables: only their author’s devices can change them. history and playlists rows each live either in the household’s shared store or in the person’s private circle.

Synced and local

Every table above syncs, unconditionally: a local release’s rows reach every device like any other release’s, so every device knows what the household owns, and a rating or playlist entry pointing at a local release’s track points at a row every device can read. Only the release’s audio, and the paths it sits at, stay on the importing device. Each table is declared with its row identity, its audience, whether it is an owner table, and the files it carries; a test holds the declarations to exactly that list.

Fully local tables, never declared to coven:

• playback_state: current track, position, queue, volume, shuffle and repeat. Playback is a device fact.
• The scan and import tables: watched folders, scans, import candidates and their drafts.
• source_release and the tables under it: what bae extracted from each MusicBrainz and Discogs release it fetched — album and pressing facts, the full tracklist with credits and works, cover options, and what other catalogs call it — keyed by the provider release rather than by a local release. The raw JSON is not kept; any device can fetch a release again.
• local_release_files: a local release’s file paths and modification times on this device.
• local_history: plays from before this device’s person had a profile, moved into their private circle when it is made.

Two devices’ edits merge cell by cell, the later edit winning a cell both changed. coven keeps the merge bookkeeping in its own tables, so bae’s tables carry no clock columns.

Blobs

Audio and images are coven files, each kind a namespace with its own device cache budget: release_files (20 GiB), covers (512 MiB), artist_images (256 MiB), and avatars (64 MiB). A row references its file by the coven file’s id: file on release_files, covers and artist_images, and avatar_id on people. The file’s size, content hash and location are coven’s, read by joining coven_files.

Release files are the user’s own: a local release’s files are the user’s files at their original paths, recorded in local_release_files, and its rows reference no coven file. Moving the release to the cloud stages every file with coven in one write and points each row at its file; once the last is stored, coven switches them all to the cloud together, and other devices fetch each into cache on first read. Covers, artist images, and avatars are bae’s own: bae produces the bytes (covers are re-rendered as JPEG thumbnails at most 600px wide), and a device fetches one when it is first shown and keeps it until its namespace’s budget evicts it.

Every file uploads encrypted under a random name, at a path fixed when it is staged, so a later rename never moves the object. A file never changes its bytes: a new image is a new file.

Identity of a rip

Every import creates a release with a fresh random ID and its own track and file rows. Each device records in local_release_origin a SHA-256 of the sorted relative paths, sizes, and modification times of the files each of its imports read; the record never syncs. A folder whose hash this device recorded is in Done wherever it has moved, and its row names the one release imported from it. Importing the same files again on that device fails, and Done offers no re-import action.