Beets Integration

Sync your existing beets library into Vynl. Faster than a fresh import — beets has already done the metadata work.

What it does

beets is the de facto music-management toolkit for serious collectors. If you've spent years curating a beets library, Vynl can read it directly:

• Import beets-managed tracks (metadata + paths) without re-scanning
• Pick up beets' MusicBrainz IDs, ISRCs, release years, album types
• Stay in sync as beets imports new music — Vynl's File Watcher catches the file changes

Quick start

1. Make the beets DB readable to Vynl

If beets and Vynl are on the same host, ensure the beets DB path is inside Vynl's /music mount (read-only is fine):

volumes:
  - /path/to/your/music:/music:ro    # this should include the beets DB

Common beets DB locations:

• /music/.beets/library.db (if you set directory: in beets config to your music root)
• ~/.config/beets/library.db (default beets location — make sure to mount it too)

2. Tell Vynl where the DB is

Settings → Beets Integration → Beets DB path → enter the path as Vynl sees it inside the container. Example: /music/.beets/library.db.

Click Test connection. Should report the track count.

3. Sync

Click Sync from Beets. Vynl reads the beets DB, inserts tracks into its own DB, copies over metadata. For 15,000 tracks expect ~30 seconds.

What gets synced

Beets field	Vynl column
path	tracks.file_path
title	tracks.title
artist	tracks.artist
albumartist	tracks.album_artist
album	tracks.album
genre	tracks.genre
year	tracks.year
mb_trackid, mb_albumid, mb_artistid	(used internally for matching)
isrc	tracks.isrc
albumtype	tracks.album_type
comp	tracks.is_compilation

Embedded cover art is extracted on first read and cached to vynl-covers.

Keeping in sync

Vynl doesn't write to the beets DB — it only reads. To keep them in sync:

• Adding music: import to beets first (beet import), then either:
  • Re-run Sync from Beets in Vynl, or
  • Enable the File Watcher in Vynl pointed at your beets-managed directory
• Removing music: delete from beets (beet remove), then re-sync. Vynl won't auto-delete the rows yet (RULE #1 — deletion is UI-gated via FireStorage)
• Edits to tags: beets writes them back to the audio files. Re-sync to pull the changes into Vynl

Why beets + Vynl together

Beets is great at library management (metadata, fingerprinting, deduplication, organization). Vynl is great at playback, discovery, and sharing.

Use beets to curate, use Vynl to listen. Each focuses on what it's best at.

Troubleshooting

Issue	Fix
"Cannot open database file"	The DB path is wrong inside the container. SSH in, ls /music/.beets/library.db to verify
Sync imports 0 tracks	Beets DB might be empty — try `beet ls
Tracks imported but file paths wrong	Beets DB was created with different mount paths. Either re-mount to match, or use beet move --update-data to rewrite paths
Cover art missing	Beets stores embedded art in the file itself. If the file isn't readable from Vynl's container, art extraction fails — check the /music mount

Related

• Configuration — volume mount paths
• Library Doctor — bulk metadata cleanup
• File Watcher — auto-import on new files