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, the Find online browser, or the File tags browser. Opening or closing a browser does not rewrite the draft. Applying a source 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.

The Default metadata source setting has three values. None creates a blank draft and starts no metadata work. File tags reads and applies the tag snapshot. Find online opens the online workflow. Its Default Find online mode can be Automatic, which queues evidence extraction, provider queries, and matching, or Search manually, which starts no identification. Opening Find online for any candidate uses that configured method; selecting Automatic starts the pipeline unless that candidate already has an active or completed run.

File Tags

File tags reads embedded audio tags and CUE metadata lazily unless it is the configured default for a newly discovered candidate. The preview stores a snapshot stamped with the candidate’s scan generation, file-edit revision, and observed audio files. Applying it replaces the draft from that exact snapshot. Commit consumes the same 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, and the raw JSON of whatever source wins is archived in the database for future re-interpretation.

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 (a config flag can disable this).
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. If the user chose cloud-managed, the upload happens after the commit as a storage transition, and the files’ original bytes remain the source of truth throughout; nothing the user gave bae is ever deleted or altered.

Recognizing rips

Each release records a content hash over its imported folder’s structure (relative paths and sizes, location-independent). Re-scans use it to mark folders already in the library, and re-imports of the same rip find and replace their prior release instead of duplicating it.