oundrobe

Soundrobe is a Tauri 2 desktop application for preparing and maintaining Navidrome-friendly music libraries. It combines metadata automation, an AI assistant, path-aware metadata auditing, and album/artist artwork downloading in one workflow.

Status: under heavy development. Soundrobe is useful today, but its UI, provider behavior, and supported workflows are still changing. Always work on a backup or copy of your music library and review changes before asking Navidrome to rescan it.

Note: opening Soundrobe on macOS. Soundrobe is currently tested on macOS only; Windows and Linux builds are not verified yet. When opening a downloaded build, macOS Gatekeeper may refuse it and only offer "Move to Trash". First try Control-click (right-click) the app in Finder and choose Open. If that option is not available, clear the quarantine flag and re-sign the app locally:

xattr -dr com.apple.quarantine /Applications/Soundrobe.app
codesign --force --deep -s - /Applications/Soundrobe.app
open /Applications/Soundrobe.app

If open still fails, re-register the app with LaunchServices and try again:

/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f /Applications/Soundrobe.app
open /Applications/Soundrobe.app

Adjust the path if the app is stored elsewhere. This trusts the app only on your own Mac; distributing it to other users requires Developer ID signing and notarization.

Documentation

• Changelog — release history and per-version changes.
• Security — security policy and how to report a vulnerability.
• Contributing — development setup, testing, and contribution guidelines.
• Updater releases — signing-key custody, release automation, and artifact/manifest verification.

What makes Soundrobe different

• Automation: Scan an album or library, derive hints from the folder, existing tags, and filenames, then resolve candidates through the local cache/dataset and enabled MusicBrainz, Discogs, and optional LLM providers. Accepted candidates can update tags, lyrics, and artwork as one workflow.
• AI assistant: Ask for supported operations in natural language, such as inspecting a selection, editing metadata, running auto-tagging, or auditing it. Mutating assistant actions are presented as an approval preview and are verified with readback after they are applied.
• Audit: Check whether tags agree with the album folder, artist folder, filename, track/disc numbering, and other local evidence. Deterministic checks run first; the LLM is used only for targeted review where judgment is useful. Findings are classified as correct, warning, or error, and only eligible high-confidence fixes can be applied automatically.
• Artwork downloading: Prefer artwork already in the album folder or embedded in a track. When it is missing, Soundrobe can use configured remote providers to save normalized album artwork as cover.jpg and artist artwork as artist.jpg in the artist folder.

Start with a good library structure

Organize files before tagging. The recommended starting point is:

/Music/
└── Artist/
    ├── artist.jpg                 # optional artist artwork
    └── Album/
        ├── 01 - Track One.flac
        ├── 02 - Track Two.flac
        └── cover.jpg              # optional album artwork

Soundrobe works best when one album is in one folder and tracks are directly inside that folder. In other words, start with /artist/album/track (where track is the audio filename). It also understands common Artist - Album folder names and multi-disc folders such as CD1 or Disc 2, but a regular Artist/Album/ hierarchy is the least ambiguous input.

This structure is a workflow convention, not a replacement for tags: Navidrome organizes music from embedded metadata rather than from folders. Soundrobe uses the folders as strong evidence when preparing and auditing those tags.

Navidrome-oriented tags

For every track, aim to have consistent values for:

• TITLE
• ARTIST and plural ARTISTS when there are multiple performers
• ALBUM
• ALBUMARTIST and plural ALBUMARTISTS when applicable
• TRACKNUMBER
• DISCNUMBER for multi-disc albums
• DATE/year, GENRE, and compilation metadata when known

Keep the album and album-artist values consistent across all tracks in an album. For compilations, use Various Artists and the compilation flag as appropriate. Soundrobe preserves individual collaborator values in plural artist fields where the format supports them; this avoids hiding multiple artists inside one display string.

Tag format support by file type

Soundrobe reads the native tag format(s) of each supported file type and rewrites metadata in the format shown below.

File type	Tags read	Tags written
MP3	ID3v1 (fallback), ID3v2.2, ID3v2.3, ID3v2.4	ID3v2.4
WAV	ID3v2.2, ID3v2.3, ID3v2.4, RIFF LIST INFO	ID3v2.4 (in the RIFF ID3 chunk)
FLAC	Vorbis comments	Vorbis comments
OGG / Opus	Vorbis comments	Vorbis comments
M4A / MP4	MPEG-4 ilst	MPEG-4 ilst
APE	APEv2	APEv2
AIFF	ID3v2, RIFF LIST INFO	— (read-only)

• Loading or refreshing an album upgrades MP3 ID3v2.2/2.3 tags to ID3v2.4 through an atomic, audio-preserving rewrite. Tags with embedded lyrics stay on ID3v2.3 for broad player compatibility; failed upgrades leave the file untouched and load through the compatibility reader.
• WAV edits rewrite existing ID3v2.2/2.3 tags as ID3v2.4.
• ID3v1 values are read as a fallback when ID3v2 does not define a field. MP3 edits preserve a trailing ID3v1 tag without refreshing it, while APE writes remove it.
• AIFF metadata is read-only in Soundrobe; use another tool to tag AIFF files.

A safe workflow

1. Put new music into the Artist/Album/ structure above and keep a backup.
2. Open the library in Soundrobe and inspect the discovered tracks and folder hints.
3. Run auto-tagging on a selected album first. Review the selected candidate and progress messages before processing a larger library.
4. Run Audit after tagging to find path/tag mismatches and ambiguous fields. Apply only the fixes you understand.
5. Use AI Assistant for bounded, specific operations. Approve its preview before any mutation; use the verification/readback result as the completion signal.
6. Download missing album or artist artwork and optionally fetch missing lyrics. Then rescan the library in Navidrome.

Current limits and expectations

• The library scanner recognizes .mp3, .flac, .m4a, .mp4, .wav, .ogg, .opus, .aiff, and .ape. Individual metadata capabilities vary by format, so test representative files before a large batch.
• Tracks are expected directly inside an album folder. Deeply nested audio files, hidden files, and non-audio files are not part of the normal scan.
• Folder names and filenames are evidence and fallbacks, not guaranteed provider truth. A provider may have no exact release, may return a different edition, or may be unavailable because remote lookup is disabled, offline, rate-limited, or missing credentials. Review candidate matches instead of assuming every result is correct.
• LLM output is assistive and can be uncertain. It is intentionally lower priority than explicit provider evidence for album and track matching; do not use it as a substitute for review on unusual releases.
• Artwork downloading needs usable album metadata and network/provider access when no local or embedded artwork exists. An explicit cover removal is remembered so automatic artwork work does not immediately restore it.
• Lyrics downloading is optional and only fills missing lyrics; local .lrc or .txt files take precedence. Enable it in settings/configuration if you want remote lyrics.
• Writes change files in place. Use a copy for experiments, especially with unfamiliar tag formats, and let Navidrome rescan after metadata or file moves. Keep debug logs and provider credentials private.

Development

Prerequisites:

• Node.js 22 and npm
• A stable Rust toolchain
• The platform dependencies required by Tauri 2
• just for the repository commands

Install dependencies and start the desktop app:

just install
just dev

The Rust backend is in src-tauri, the React renderer is in src, and renderer/Rust tests live in test and beside the Rust modules they cover.

Verification

Run the complete local quality gate:

just check

Useful targeted commands:

just typecheck
just test
cd src-tauri && cargo clippy --all-targets -- -D warnings

Credentialed provider smoke tests are separate from the default offline suite; see just --list for the available gates.

Configuration

Copy config.example.yaml to ~/.soundrobe/config.yaml and set only the providers and behavior you use. Secrets can instead be supplied through the environment variables documented in that example. Environment values take precedence over the config file, and secrets remain in the native process. Existing settings under ~/.auto-tagger are migrated into ~/.soundrobe on startup. The old directory is removed only after the migration succeeds.

The optional local dataset is read from dataset_path. If it is absent or invalid, the app reports it as unavailable and continues with enabled remote providers. Useful settings include remote_lookup_enabled, discogs_enabled, lyrics_download_enabled, lyrics_api_url, chinese_script, and write_concurrency.

For a low-cost OpenRouter setup, start with deepseek/deepseek-v4-flash. OpenRouter currently lists it at $0.09/M input and $0.18/M output; pricing and availability can change, so check the provider page before making large runs.

Distribution

Build the current platform bundle:

just fe-build

Build an explicit local distribution target. These ordinary builds do not create signed updater artifacts or require updater signing credentials:

just fe-dist mac
just fe-dist win
just fe-dist linux

The GitHub release workflow separately creates signed updater artifacts. See Updater releases for the bootstrap limitation, required secret, and post-release verification. macOS release bundles are ad-hoc signed, so the Gatekeeper warning and recovery steps near the beginning of this README still apply.

License

MIT — see LICENSE.