Metadata & integrations
Watch folders are scanned, files are identified, and nine sources are asked in turn. Every enrichment run snapshots what it replaced — so a provider revising its own record is recoverable rather than merely regrettable.
The nine sources
| Source | Provides | Key needed? |
|---|---|---|
| TMDB | Films & TV — titles, artwork, cast, certifications | Yes (free) |
| MusicBrainz | Music — releases, artists, relationships | No |
| AcoustID | Music — identifies files by acoustic fingerprint (Chromaprint) | Yes (free) |
| Open Library | Books — titles, authors, covers | No |
| iTunes | Music & books — artwork, release data | No |
| Spotify | Music — artist images, popularity, related data | Yes (free) |
| OpenSubtitles | Films & TV — caption tracks | Yes (free) |
| File tags | Whatever your files already know about themselves | — |
| OCR | Scanned books — makes the text selectable and searchable | — |
Adding keys
Admin → Metadata sources. Keys are entered there, not in .env.
A source with no key skips itself and says so in the log rather than silently
returning nothing — so a half-configured install still enriches from the keyless sources.
On Windows, add the certificate bundle first. Without it every source
fails with cURL error 60, which reads as a network problem. See
Install on Windows, step 4.
Enrichment is reversible
Every run snapshots what it replaced. If a provider revises its record — a renamed album, a re-credited cast — the previous state is recoverable. Combined with the rule that originals are never deleted, metadata mistakes are annoying, not destructive.
Enrichment runs in the background
Lookups happen on the queue, not during the scan — so php artisan queue:work
must be running or metadata never fills in. See
Background workers.
Beyond metadata
- Plex / Jellyfin / Emby — SoundChex reads and writes the same folder conventions, so a library can serve several tools at once during a migration.
- Web app manifest — the library installs to a phone's home screen as an app, with your artwork as the icon.
- SCNet — the hosted relay for remote access, coming soon; see Remote access.