Import pipeline

Import turns a folder of files into a release-accurate catalog entry without modifying a byte of the files. This page is the pipeline behind the flow described in the use guide.

Scanning

Watched folders are monitored by the platform’s file-system events, debounced, and re-scanned on change; scans reconcile against the existing candidate list rather than starting over. The scanner classifies a folder as one release (audio directly inside, or disc-shaped subfolders like CD1/CD2), or recurses into it as a collection. Files classify by extension into audio, artwork, and documents, then audio is probed: the codec that matters is the one FFmpeg finds in the bytes, not the file extension. Folders containing partial-download markers are excluded until the download finishes.

A CUE sheet turns one audio image into a track list. The parser handles pregaps and postgaps, per-track performers and ISRCs, and both single-file images and one-file-per-track CUE layouts. Track boundaries convert from CUE frames (1/75th of a second) to exact sample positions, which later become the byte and sample windows playback uses.

Metadata drafts

Each candidate stores one editable metadata draft and optional provenance. The draft may be blank, populated directly, populated from an external release, or populated from a stored file-tag snapshot. Provenance records where the current draft began; later edits do not erase it. Direct entry and a cleared draft have no provenance.

The top metadata slot displays either the draft or the Find online page. Opening or closing that page does not rewrite the draft. Applying a source — a release picked there, or the candidate’s own file metadata through “Reset to file metadata” — replaces the draft, its provenance, and its selected source cover in one database transaction while retaining the candidate’s file roles, CUE bindings, disc assignments, and other mapping decisions.

Find online

Find online is the only path that runs identification. It reads three kinds of evidence out of the folder in one pass:

• a disc ID, the MusicBrainz fingerprint of a CD’s exact track layout, computed from a rip log or from the CUE sheet;
• barcodes, decoded from artwork scans by the platform’s vision framework and read from CUE catalog fields;
• text: catalog numbers and free text from artwork OCR, folder and file names, and text files in the rip.

Embedded audio tags are deliberately not Lookup evidence: they describe what a tagger believed, not what the pressing is.

Disc ID and barcode are looked up concurrently, the disc ID against MusicBrainz, the barcode against MusicBrainz and Discogs at once, and the results are triangulated: results that agree on a release group converge, catalog-number matches narrow the pressing list, and disagreement between signals surfaces as an explicit conflict for the user rather than a silent best guess. Every result carries its provenance (found by disc ID, by barcode, catalog match) so the UI can say why a row is being offered.

When a candidate is added, its draft is created from the folder’s own metadata, inside the same write that stores the candidate. The library setting Identify automatically makes the queue-wide sweep run every candidate that has no stored result for the files it has right now — a pre-filled draft, a release a person chose, and fields they typed exempt none of them. A run starts when a candidate is added, when its files change and retire the result read from them, or when a person asks for one; nothing else starts one.

A person asks for one through Identify automatically on the candidate’s card, which is the only entry that starts a run. It cancels whatever run that candidate has going before starting the new one, so a superseded run can never land its result, and it asks unconditionally — a stored result is what a person pressing it is unhappy with. The card’s other entry, Search for release, opens the same page on its typed search and asks for nothing.

File Tags

File metadata is read at two moments and nowhere else: the pre-fill reads it as a candidate is added, and “Reset to file metadata” reads it again on demand. Each read stores a snapshot stamped with the candidate’s scan generation, file-edit revision, and observed audio files, and replaces the draft from that exact snapshot in the same transaction. Commit consumes the stored snapshot and fails before library writes if its stamp or observations changed; it does not read a different answer.

Direct entry performs no metadata I/O. The blank draft’s release and track fields are editable immediately, and it becomes importable when the required fields and mappings validate. The candidate list does not treat missing provenance as an error or a request for attention.

Sources

MusicBrainz is queried anonymously with a strict one-request-per-second pace. Discogs authenticates with the user’s personal token from the keyring, paced and retried within its rate limits, and a rejected token is reported as such so the UI can flag it rather than fail searches quietly. Responses are cached per session. When a release is picked, what bae uses from its documents — its album and pressing facts, its full tracklist with credits and works, its cover options, and what other catalogs call it — is extracted into the database once; the raw JSON is not kept.

Commit

Confirming an import runs, in order:

1. Decode verification: every track is decoded end to end; a rip that cannot fully decode fails the import before anything is written.
2. Loudness analysis: integrated loudness and true peak are measured per track and per album during that same decode pass, stored for replay-gain use.
3. Cover selection: the chosen art (remote, folder image, or embedded) is re-rendered to a display thumbnail; the original is kept among the release’s files if it came from the folder.
4. Atomic write: the release, tracks, credits, identities, formats, segments, files, and cover commit in one transaction. There is no half-imported state.

The release lands referencing the user’s files in place. For a cloud import, coven reads and hashes each file before the write, and the same write stages every file with coven, points each row at its file, and queues its upload. A local import records each file’s path, size, and modification time on this device instead; its bytes are read only if the release is later moved to the cloud. Either way the files’ original bytes remain the source of truth throughout; nothing the user gave bae is ever deleted or altered.

Recognizing rips

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.