Cross-Server Sharing
Share a library with someone on another Black Candy server — they browse it like it's their own.
Overview
Cross-server sharing lets you give someone on a completely separate Black Candy Store instance access to one of your libraries. They get a full browsable catalog locally, while audio streams through on demand.
The system has three components:
- Invite codes — generated by the sharing server, redeemed by the receiving server
- Catalog mirroring — the receiving server keeps a local metadata-only copy that syncs automatically
- Live streaming — audio and artwork are proxied from the source at play time
Prerequisites
- Both servers must be reachable over the network (public internet or same LAN)
- The sharing server must have
SERVER_BASE_URL set to its public URL
- HTTPS is strongly recommended for both servers
Generating an Invite Code
On the server that owns the library you want to share:
- Click Libraries in the main navigation sidebar
- Find the library you want to share and click the Share button next to it
- You'll land on the Share Library page, showing the library name at the top
- Under Expires in, choose how long the invite code should remain valid — options are 1 hour, 1 day, 7 days, or 30 days
- Click Generate Invite
- The invite code appears in a text field at the top of the page. Click it to select, then copy it. This code contains your server's URL and an access token.
Send the invite code to the recipient through a secure channel. Anyone with the code can redeem it until it expires or is revoked.
Redeeming an Invite Code
On the receiving server:
- Click Libraries in the main navigation sidebar
- Click the Redeem Invite button in the top-right area (next to New Library)
- Paste the invite code into the Invite code text field
- Click Redeem
The server will connect to the source, verify access, and begin mirroring the catalog. Once complete, the shared library appears in your library list with a Remote badge.
Browsing a Shared Library
Once mirrored, switch to the shared library by clicking Set Active next to it on the Libraries page. From there, everything works the same as a local library:
- Browse albums, artists, and songs
- Search and filter the catalog
- Add tracks to playlists and favorites
- Queue and play tracks
The only difference: audio and artwork are streamed live from the source server rather than served from local files.
Catalog Mirroring
The mirror is metadata-only — no audio or artwork bytes are stored on the receiving server. It stays in sync through:
- Periodic pull — the receiving server polls for changes at a configurable interval (default: every 15 minutes, controlled by
CATALOG_SYNC_POLL_INTERVAL)
- Push nudge — the sharing server sends a best-effort notification when its catalog changes, prompting an immediate sync
Browsing is always served from local queries. Audio and artwork are streamed and proxied live from the source server at play time.
Managing Access Grants
On the sharing server, the Share Library page also shows all existing access grants for that library. Each grant shows its status:
- Pending — invite generated but not yet redeemed
- Redeemed — invite was used and the connection is active
- Expired — invite expired before being redeemed
- Revoked — you manually revoked this grant
Revoking Access
To revoke a shared library connection:
- Go to Libraries → click Share next to the library
- In the Access section at the bottom, find the grant you want to revoke
- Click the trash icon next to it and confirm
Access is revoked immediately — the receiving server's mirror becomes stale and playback from that source will fail.
Security
- Access tokens are encrypted at rest using Active Record encryption (see Configuration for encryption key setup)
- All cross-server communication happens over HTTPS when configured
- Each invite code grants access to a single library only
- Access can be revoked server-side at any time
Next Steps