Multiple Libraries

Organize your music into separate named collections, each backed by its own media path.

How It Works

Instead of a single monolithic collection, Black Candy Store lets you create multiple libraries. Each library:

• Has its own name and media directory
• Maintains its own catalog of songs, albums, and artists
• Can be independently scanned and managed
• Can be shared with other servers (see Cross-Server Sharing)

Users browse one active library at a time and can switch between them.

Backwards Compatibility

If you're upgrading from a single-media-path setup, your existing collection automatically becomes the default library. No migration needed — it just works.

Creating a Library

First, mount your music directories into the container:

docker run \
  -v /nas/jazz:/media/jazz \
  -v /nas/electronic:/media/electronic \
  -v /nas/vinyl-rips:/media/vinyl \
  -v ./storage_data:/rails/storage \
  -p 80:80 \
  ghcr.io/ajeskey/blackcandystore:latest

Then create libraries in the admin UI:

1. Click Libraries in the main navigation sidebar on the left
2. Click the New Library button in the top-right corner (visible to admin users only)
3. Fill in the Name field — a descriptive label like "Jazz Collection" or "Vinyl Rips"
4. Fill in the Media path field — the directory path inside the container (e.g. /media/jazz)
5. Click Save

The library is created immediately. You'll need to trigger a media scan to index the files (see Scanning below).

Switching Libraries

On the Libraries page, you'll see all available libraries listed with their names. Each one shows its status:

• Active badge — this is your currently selected library
• Remote badge — this library is shared from another server

To switch to a different library, click the Set Active button next to it. All browsing, search, and playback will immediately switch to that library's catalog.

Managing Libraries

From the Libraries page, admin users can:

• Rename — click the Rename button next to any local library to change its display name
• Share — click the Share button to generate invite codes (see Cross-Server Sharing)
• Delete — click the trash icon next to any non-default library. You'll be asked to confirm. This removes the library and its catalog from the database but does not delete the actual music files on disk.

Scanning

Each library is scanned independently. To trigger a scan:

1. Go to Settings in the sidebar navigation
2. Under the Library section at the top, click the Scan button
3. The scan runs in the background — only files in the active library's media path are indexed

You can also enable the Media Listener checkbox in Settings to automatically detect file changes and rescan.

Browsing a Library

Once a library is active, the main navigation shows your catalog counts — Albums, Artists, and Songs — with links to browse each. From there you can:

• Search and filter by genre, year, or artist
• Add tracks to playlists or your favorites
• Queue tracks for playback

Source Preference

When the same track appears in multiple libraries (or from a shared remote library), you can configure source preference to choose:

• Local first — prefer your own server's copy
• Highest quality — prefer whichever copy has the best bitrate/format

This is configured per-user in their playback settings.

Next Steps

• Share a library with another server →
• Full environment variable reference →