rsbts
A safe, plan-first music library manager and reusable Rust library. rsbts scans local audio, searches a metadata provider, explains its match confidence, and organizes approved albums without silently overwriting files.
Safety model
- Imports are previewed and approved per album. A collision rejects the whole album; an existing, managed destination with identical content is a no-op.
- Copy, move, link, cover-art, and file-deleting removal operations use a persistent SQLite journal. Interrupted work is reconciled when the CLI opens for a non-dry-run command; if ownership cannot be proven, recovery stops and reports the paths requiring manual attention.
- Move sources are deleted only after the album and tracks commit to SQLite; recovery also requires the journaled file identity and content hash to match.
- Removal is planned and confirmed as one complete set. With
--delete, files are first moved into a same-directory, no-clobber quarantine, then database rows commit, then quarantined files are unlinked. A file replaced after the plan is shown is preserved, even when its bytes are identical. - Schema upgrades run transactionally and create a timestamped, integrity-checked database backup before migrating an existing library.
- Missing files remain represented in the database and are reported by audit.
- Query values are bound SQLite parameters; malformed fields fail closed.
- Paths must round-trip through UTF-8 before they can enter SQLite or the operation journal; unrepresentable paths are reported and skipped.
- Dry runs use an in-memory database snapshot and skip journal recovery, so they do not create or modify the configured database or library.
Install
rsbts requires Rust 1.89 or newer. Library API documentation is available on docs.rs.
To install the current source checkout instead:
Quick start
The built-in defaults use ~/Music for organized files and
~/.local/share/rsbts/library.db for the catalog. Configuration loading is
side-effect free, so it is safe to inspect a new installation before importing
anything:
Create a configuration only when you want different paths or behavior:
For a first album, start with a preview. A dry run reads tags, searches MusicBrainz, displays match scores and the planned destination, but does not create or modify the database or library:
The interactive import lets you choose a MusicBrainz candidate, keep the
existing file tags, or skip the album. Tied releases can all display excellent
scores while still failing the runner-up-margin gate. This is intentional:
--yes skips ambiguous matches instead of guessing and exits with status 2
when work was skipped.
Relative paths in an explicit config are resolved from that config's directory. An explicit missing config or an unknown TOML key is an error; loading configuration itself creates nothing.
Path templates describe the destination stem. rsbts appends the source audio
extension, preserving periods that are part of a title. Variables are
$albumartist, $artist, $album, $genre, $year, $track, $title, and
$disc. Functions are %upper{value}, %lower{value}, %title{value},
%left{length,value}, %right{length,value}, and
%if{condition,true-value,false-value}. Unknown fields, malformed functions,
absolute paths, parent traversal, and control characters are rejected during
configuration or planning.
Import
Interactive imports show candidate-level artist, album, track, provider, total,
and runner-up scores before asking for a decision. --yes is deliberately
strict: it accepts only the top result when tags are non-placeholder, track
counts match, artist similarity is at least 95%, album similarity is at least
92%, every track has either 90% title similarity or matching number/disc plus a
duration within three seconds, and the configured composite and
runner-up-margin thresholds pass (92% and five points by default). Failed gates
are printed and that album is skipped.
Without a terminal, mutating imports require --yes; --dry-run never mutates.
Failures are isolated per album so later albums can still be processed.
Query and manage
Field filters support literal substring field:value, exact field:=value,
SQLite glob field::pattern (*, ?, and []), ranges such as
year:1960..1969, negation with ^, relative added dates such as added:-7d,
and ascending/descending sort suffixes +/-.
Double-quote values containing spaces, for example
artist:"Black Sabbath" album:="Master of Reality"; malformed quotes are
rejected.
modify validates the entire request before changing anything and commits all
matched rows together. Set an optional field to an empty value (for example,
genre= or year=) to clear it. Album summaries are reconciled when album,
album-artist, artist, or year fields change. Empty modify and rm query
strings are rejected, preventing an unset shell variable from selecting the
entire library. Explicitly empty ls and update queries are rejected too;
omit the query argument when selecting all items is intentional.
Changing canonical title/artist/track fields clears the affected provider track
ID; changing album/album-artist/year clears the affected provider release ID.
Changing artist also clears the release ID when that item has no explicit album
artist. The same selective invalidation applies when update detects changed
file tags.
audit prints every missing file, unknown file size, orphaned item, invalid
timestamp, and full-text search index inconsistency. It exits with status 2
when it finds an issue. These deep checks run only for an explicit audit, so
ordinary commands do not scan every library file at startup.
Exit status is 0 for success, 2 when some work was skipped or failed while
the rest continued, and 1 for validation or fatal runtime errors. Clap uses
status 2 when the command-line arguments themselves are syntactically invalid.
Library API
The public API exposes provider-neutral metadata DTOs and an async
MetadataProvider trait, typed Query values, explicit ImportPlan /
ApprovedAlbumPlan and RemovalPlan types, journaled executors, library audit,
and explicit Library::recover_pending() recovery. Library consumers choose
when recovery runs; the CLI runs it automatically before every command except a
dry run. Library::open_snapshot() provides a non-mutating database view.
Development checks
RUSTDOCFLAGS="-D warnings"
To exercise the installed CLI without touching a real collection, point an
explicit config at a temporary library and database, then import disposable,
tagged audio. Cover at least this user journey: empty stats and audit, an
import dry run, an interactive or explicitly confirmed import, filtered ls,
modify, update, removal dry run, confirmed removal, and a final clean
audit.
Supported audio
MP3, FLAC, Ogg Vorbis, Opus, M4A/AAC, ALAC, WAV, and AIFF.
License
MIT