Metadata and artwork

Collectoh fills in titles, descriptions, cast, genres, ratings and artwork for everything it scans. It reads what sits beside your files first, then asks online catalogues. There's nothing to set up: no accounts to make and no keys to find. Which catalogues it asks, and in what order, is up to you for each library.

#Where details come from

Beside the files, always first. NFO files, pictures such as poster.jpg, the tags inside music and audiobook files, the details built into ebooks and comics, course.nfo and folder.json. A carefully prepared library may need nothing more; see Naming and organising your files.

Online catalogues fill in the rest:

Courses, photos and home videos are described by what's beside the files. Memories libraries can also tag photos by what's in them and recognise faces, entirely on your server: switch these on in the library's settings, and see Beyond films.

#Nothing to set up

TMDB, TheTVDB, fanart.tv, TheAudioDB, Google Books, IGDB and OpenSubtitles each want an API key from whoever asks them. As with Plex, you don't need any: once your server is signed in to your Collectoh account (the first step of setup), it asks them through collectoh.com, which holds the keys. It sends what it needs to find a match, such as a title, a year or an ID, and gets the details back. Admin → Metadata agents shows each catalogue as Through Collectoh.

The pictures themselves come straight from each catalogue to your server.

#Keys of your own

If you'd rather your server asked a catalogue directly, give it a key of your own. Its lookups then go straight to that catalogue, and not through collectoh.com. Nobody needs to do this.

The simplest way is Admin → Metadata agents: open Use a key of your own under the catalogue, paste the key and press Save. It's used from the next refresh, with no restart. A saved key is kept encrypted on your server and never shown again, only that it's set. Remove takes it away, and the catalogue goes back through Collectoh. The same page takes an OpenSubtitles key, username and password of your own, for subtitle files.

You can also give keys to the server as environment variables, which it reads when it starts. A key saved in Admin → Metadata agents is used in place of the environment's, and removing it brings the environment's back.

With Docker, add them to the .env file beside docker-compose.yml, then run docker compose up -d:

TMDB_API_KEY=your-tmdb-key
TVDB_API_KEY=your-tvdb-key
FANART_API_KEY=your-fanart-key

Other installs can set the same variables for the Collectoh service, or put the keys in config.yaml in Collectoh's configuration folder:

providers:
  tmdbApiKey: your-tmdb-key
  tvdbApiKey: your-tvdb-key
  fanartApiKey: your-fanart-key

Restart the server after changing environment variables.

Where to get keys of your own:

• TMDB: themoviedb.org/settings/api, with a free account
• TheTVDB: thetvdb.com/api-information
• fanart.tv: fanart.tv/get-an-api-key
• IGDB: a Twitch application's client ID and secret, from dev.twitch.tv (see IGDB's account creation); as environment variables, IGDB_CLIENT_ID and IGDB_CLIENT_SECRET

#Choose sources for each library

Each library asks its sources, called its metadata agents, in order. The defaults:

To change them, open Admin → Libraries, choose Edit, and use Metadata agents (in order): move agents up or down, remove them, or Add an agent…. Use the defaults for this type puts things back.

• The first agent with an answer for a field supplies it; genres, tags, cast and pictures are gathered from all of them.
• An agent that can't answer yet, because the server isn't signed in to Collectoh and has no key of its own for it, says so and is skipped until it can, so it can stay in the list.
• fanart.tv works from the IDs that TMDB or MusicBrainz found, and TheAudioDB prefers MusicBrainz's, so keep them after those.
• Keep Beside the files first. Without it, NFO files and your own pictures are ignored.
• Plugins can add more agents.

#How matching works

For each film, show, album or book, Collectoh compares the catalogue's candidates with what your files say: the title (ignoring case, punctuation and a leading "The", and reading "II" as "2" and "One Hundred and One" as "101"), the year, and the running time. A candidate that scores 85% or more is applied automatically. Anything less keeps the name from its files and goes to the Needs matching queue, because a wrong match is worse than none.

Books are matched on title and author; audiobooks on title, author and narrator.

#The Needs matching queue

Admin → Needs matching lists everything no catalogue could identify with confidence, from all your libraries. For each item, adjust the search text if you need to, choose Find match, then Use beside the right result.

If nothing comes back, try another spelling or the original title. Courses, and any library that only looks beside the files, never appear here.

#Episode order

TV libraries have an Episode order setting, under Admin → Libraries → Edit:

TMDB knows only the broadcast order. In DVD or absolute order, TMDB still describes the show, but its seasons and episodes are described by TheTVDB or by NFO files beside the episodes. Specials stay in season 0 whatever the order.

#Fix a wrong match

1. Open the item and choose Edit (also Edit… in its … menu).
2. Open the Match tab and search for the right title.
3. Choose Use this beside the right entry.

Collectoh fetches everything again from that entry, keeping any fields you've locked, and drops pictures that belonged only to the old match. Pictures you uploaded, or that sit beside the files, stay. Your choice is kept: later refreshes stay with it.

Editing and matching are for the owner and admins.

#Edit details and lock them

Under Edit → Details, change any field and choose Save. Edited fields lock automatically, as the padlock beside each shows, so no refresh will overwrite your change. To go back to the catalogue's version, unlock the field and choose Refresh metadata.

Genres, labels and keywords lock the same way, and a book's series, number, ISBN, publisher and page count lock together.

#Choose artwork

Edit → Artwork shows every picture on offer: those beside your files, those from each catalogue, and a still from the video, each labelled with its kind and where it came from. Select one to use it. You can also Upload poster (JPEG, PNG or WebP), or Design a poster from templates using the item's own details. A picture you choose stays chosen.

Until you choose, Collectoh picks: a picture beside your files beats any catalogue's, and a still from the video is the last resort, so nothing is left as a blank tile.

#Collections

Collections live on each library's Collections tab.

• Automatic: when TMDB puts a film in a series, Collectoh makes a collection for it once you have two or more of its films, across all your libraries. Turn this off with Gather film series into collections in Admin → Settings; existing collections stay.
• Your own: choose New collection, or open any item and choose Collections to add it to one. Admins can make a collection for everyone on the server; anyone else's collections are personal to them.
• Smart: New smart collection gathers items by rules — type, year, genre, rating, date added, watched or in progress, times played, labels and more. The rules are checked each time you open it, so it's always up to date.

#Refresh details

• One item: Refresh metadata in its … menu or its Edit window. It asks every agent again, keeps what you've locked, and tells you which sources answered and what changed.
• A whole library: Refresh all metadata in the library's … menu in the sidebar, or a Refresh metadata scan in Admin → Scans.
• Automatically: each night, Collectoh refreshes a batch of the items whose details are more than 30 days old. If no catalogue could be reached when an item was scanned, it's tried again each night until one answers. A catalogue being down never makes a scan fail.

#Credits

This product uses the TMDB API but is not endorsed or certified by TMDB. Metadata provided by TheTVDB. Music details come from MusicBrainz and TheAudioDB, pictures also from fanart.tv, books from Open Library, and games from IGDB.com.