How matching works

A scan tells Credenza that a file exists and what its name says. Matching is the next step: finding that film or show on a metadata provider and bringing back its proper title, artwork, description and the rest.

Providers

Library type	Provider
Movies	TMDB
TV Shows	TMDB
Anime	TMDB
Games	ScreenScraper and IGDB, in the order you choose. See Games.

Everything on this page is about TMDB unless it says otherwise.

Connect TMDB

Credenza needs your own TMDB token. The setup wizard asks for it on first run, and you can add or change it later:

1. Sign in to your account at themoviedb.org and open Settings → API. Create an API key if you haven’t already, then copy the API Read Access Token, the long one.
2. In Credenza, go to Settings → Server → Metadata.
3. Under Films and shows, paste it into TMDB read access token and press Save.

The token is never shown again; the field just says a token is set. To remove it, save a single space.

Without a token, films and shows still appear and play, but they keep the titles from their file names and a generated cover, and nothing is looked up. Adding a token doesn’t go back over what’s already there by itself. Scan the library again, or choose Refresh metadata from its menu under Settings → Server → Libraries.

How an item is matched

Matching runs in the background after a scan files something new. While it works, the library’s panel shows Fetching metadata… N to go. It carries on after the scan has finished, and TMDB being slow or unreachable never holds a scan up.

Credenza only accepts a match it’s sure of. It never picks the most likely-looking result.

• A film is searched for by its title and year. A result counts only if its title, or its original-language title, is exactly the name from the file, ignoring capitals and punctuation. If exactly one such film came out that year, it’s the match. If two did, Credenza refuses to choose. If none did, it searches again without the year and accepts the result only if there’s exactly one film with that exact title.
• A show is searched for by its name, with the same exact-title rule. If there’s exactly one, it’s the match. If there are several, the year in the show’s folder name, if any, picks between them.
• Episodes aren’t searched for. Once a show is matched, Credenza fetches each season you have and fills in every episode by its number. That’s why an episode can’t be corrected on its own: fix the show, and its episodes follow.
• New episodes of a matched show are filled in as soon as a scan finds them.
• Anime numbered from 1 straight through is placed in TMDB’s seasons automatically. See Naming shows and anime.

When there’s no sure answer, the item is left with the title from its file name and a generated cover, and goes on the Needs matching list. Credenza doesn’t try again by itself. You fix it there with a couple of clicks; see Fixing matches.

If TMDB can’t be reached or is rate-limiting, that isn’t a “no”. The item is tried again later.

What gets fetched

For	Credenza fetches
Films	Title, original title, synopsis, release date, runtime, tagline, rating, genres, poster, backdrop, the first 20 cast members with their photos, and key crew: director, writers, story, producers, executive producers, cinematographer and composer
Shows	Title, original title, synopsis, first air date, genres, poster and backdrop
Seasons	Poster. Seasons stay named by number, like “Season 2”.
Episodes	Title, synopsis, air date and runtime. TMDB episode stills aren’t used; episodes show their season’s poster.

Once an item is matched, TMDB’s title and date win over the file name, and later scans don’t write the file name’s version back over them. To change what a matched item is called, use Edit details. An item that never matched keeps taking its title from the file name.

Artwork

Posters, backdrops and cast photos are downloaded once and stored on the server, so browsing never waits on TMDB. Until an image has arrived, a generated cover stands in.

They’re kept in the Artwork folder, under Settings → Server → Metadata → Artwork. Leave it blank to use the default. If you change it, artwork already downloaded isn’t moved; each item fetches its images again the next time its metadata is refreshed.

Refresh metadata

To ask TMDB again, for example after TMDB has corrected something:

• One item: choose Refresh metadata from its ⋮ menu, on its tile or its page.
• A whole library: choose Refresh metadata from the library’s ⋮ under Settings → Server → Libraries.

A refresh keeps every item matched to the same TMDB entry and replaces its details with whatever TMDB says now. Items that never matched are searched for again. Neither works while that library is scanning.

What Credenza remembers

Credenza keeps a copy of every answer TMDB gives, separately from your libraries. If you delete a library and add the same folders back, the new one fills in its details from that copy straight away, without asking TMDB again. Refresh metadata always asks TMDB and replaces what was remembered.

Match files

Matches you correct by hand and details you edit are also written into a small file beside your media, so they survive even if the library is deleted, the database is lost, or you move to a new server.

The file is named after what it describes:

Films/
└── Nausicaa (1984)/
    ├── Nausicaa (1984).mkv
    └── Nausicaa (1984).credenza.json
Shows/
└── Cowboy Bebop/
    ├── Cowboy Bebop.credenza.json
    └── Season 1/
        └── Cowboy Bebop - S01E05.mkv

• A film gets <file name>.credenza.json beside each of its files. So does a game, beside its ROM.
• A show gets <show folder name>.credenza.json inside the show folder. Edited episode details are kept in the show’s file, since episodes have no folder of their own.

It’s plain JSON, such as:

{
  "schemaVersion": 1,
  "kind": "Movie",
  "title": "Nausicaä of the Valley of the Wind",
  "year": 1984,
  "ids": { "imdb": "tt0087544", "tmdb": "81" },
  "overrides": { "title": "Nausicaä of the Valley of the Wind" }
}

When they’re written: automatically, whenever you correct a match or edit an item’s details. For everything else, choose Write match files from a library’s ⋮ under Settings → Server → Libraries. That writes a file for every matched item in the library and reports how it went, such as “Match files: 120 written, 4 already correct, 2 skipped”. An item is skipped when nothing has matched it and nobody has edited it, when every copy of it is missing, or for a show whose episodes sit loose in the library folder with no show folder to write into.

When they’re read: during a scan, for an item Credenza doesn’t already know the match or edits for, such as in a library you’ve just added again. Once a server knows an item’s match, the file never overrides it.

A few more things to know:

• Your media folders need to be writable for these files to be written. On a read-only mount the write fails with the file’s path listed, and everything else carries on as normal.
• A damaged or hand-mangled file is ignored, and the item is matched from its name as usual.
• You don’t need to edit these files, but it’s safe to keep them in backups and to copy them along with your media.

Outbound proxy

If your server reaches the internet through a proxy, set it under Settings → Server → Metadata → Outbound proxy, in Proxy address:

http://proxy.example.com:3128
http://user:password@proxy.example.com:3128

It’s used for every request to TMDB, ScreenScraper and IGDB, including artwork downloads, and for the check for new Credenza releases. It takes effect on the next request, with no restart.

• Left blank, provider traffic follows the machine’s own HTTP_PROXY setting, if it has one.
• To clear it, save a single space.
• If you retype the address, include the username and password again.
• An address that can’t be understood stops all provider requests rather than quietly going direct. The page then says No provider can be reached until you fix it.