Documentation

Matching and metadata

Home Stream works out what each file is from its name, then fetches the poster, the description and the rest. Usually it gets it right. When it gets one wrong, you can correct it in one step, and the correction stays.

Where the details come from

• Films and television come from TMDb: posters, backdrops, descriptions, cast, genres, running times, age ratings, episode titles and pictures, and which film series a film belongs to. TMDb needs a free API key of your own. Enter it in Settings → Region & Metadata → TMDb API Key (see Region & Metadata). Without a key, films and shows get no details.
• Albums come from MusicBrainz, which says which release a folder is and what year it came out. Covers come from the Cover Art Archive. If it has nothing for that exact pressing, Home Stream tries the cover for the record as a whole, and then any artwork stored inside the album's own files. No key is needed.
• Artists: photographs and biographies come from TheAudioDB and Wikipedia. A biography from Wikipedia is credited on the artist's page and links back to its article. No key is needed.

Everything is downloaded once and kept on the server. Your library looks the same when the internet is down.

How automatic matching works

After each scan, Home Stream looks up anything that isn't matched yet.

• A film is looked up by the title and year in its file name, such as The Matrix (1999).mkv. If that spelling finds nothing, it tries a few close spellings, such as Jr and Jr.. If those fail too, it searches again without the year, because a year in a file name is often out by one. When several films come back, it prefers one with the same title and a year within one of yours.
• A show is looked up by its folder name. Each episode is then found by its season and episode numbers, such as S07E09.
• An album is looked up on MusicBrainz by its artist and title.
• Libraries from Plex or Jellyfin: if a file or folder already names its TMDb entry, Home Stream uses that entry and doesn't guess. It reads a {tmdb-603} tag in the name, an .nfo file or a .plexmatch file.

Once something is matched, scans and metadata runs leave the match alone. That keeps them quick. It also means scanning again never fixes a wrong match. For that, use Fix Metadata.

A film's title and its file name

A film's title comes from the TMDb entry it's matched to, not from its file name, so a typo in a folder gets corrected instead of kept. When you correct a film's match, refresh it, or upload it, its file is renamed to match, as Title (Year).ext. The right name then outlasts the database: a fresh scan of the same folder finds the same film.

• Only the film's own file is renamed, together with any other editions of it beside it. Nothing else in the folder moves.
• If the new name is taken, the drive is read-only or permission is refused, the file stays exactly as it was. The details are still updated.
• If something fails part-way through, the files go back to their old names.
• Every rename is recorded in the server's log, along with the file's old name.
• No database number is ever written into a file name.

A show's title also comes from its match, but its folder isn't renamed. Episode files aren't renamed either.

When a match is wrong: Fix Metadata

Fix Metadata is in the ⋯ menu of films, shows, albums and artists. Find that menu on a poster in any grid (it appears in the top-right corner when you hover), or at the top of the title's own page.

1. Open it

   Choose ⋯ → Fix Metadata…. The search box starts with the name the library has now, so to fix a misspelling you change one word instead of retyping the whole title.

2. Search

   A film has a title box and a year box. Clear the year to search every year. A show has the title only. An album has separate boxes for the artist and the album title, because usually only one of them is wrong, and pressings from your own country are listed first. An artist's results come from TheAudioDB, Wikipedia and MusicBrainz, and each result says which. MusicBrainz is best at telling apart musicians who share a name. It has no photographs in the list, but one is fetched when you choose it.

3. Choose

   For films, shows and albums, the entry in use now is marked current. Click the right one. It's applied immediately, with no separate confirm step. For a film, that includes renaming its file. The choice is then pinned.

Chose the wrong one? Open Fix Metadata again and choose the right one. A film's file is renamed again to match.

Films and shows need a TMDb key before Fix Metadata can search for them.

Correcting an episode

There's nothing to search for with an episode, because it's found through its show and its numbers. An episode with the wrong title is really a file with the wrong numbers, often because a special was counted as episode one.

Open the ⋯ menu on the episode's row in its show and choose Fix Metadata…. Enter the season and episode the file really is, then choose Apply. The title, description and picture update to match. You can move an episode to another season only if that season already exists in the show. A later scan won't change the numbers back.

Pinning

A match you choose is pinned. Scans, metadata runs and refreshes re-read the entry you chose and never search again.

To give a film or show back to automatic matching, open Fix Metadata and choose Use automatic matching. The button only appears when there's a choice to undo. Your choice is forgotten and the match is worked out again straight away.

Pictures are pinned separately from matches. A poster you picked or uploaded stays even if you change the match.

Refreshing, fixing and updating

Settings → Library Maintenance → Re-read Music Tags reads each track's title, number and disc from the tags inside the file, which are usually better than the file name. Nothing on your drive changes.

Only one library job runs at a time. If a scan is running, a metadata update waits for it to finish.

Pictures

Choosing a different poster

One TMDb entry can hold a dozen posters. Some differ only by language. Others are different versions, such as a black-and-white poster and a colourised one for the same film. For a film, choose ⋯ → Change Poster… and click the one you want. Posters without text come first, then English ones. Whatever you pick is kept, and nothing automatic replaces it. A film needs a match before there are posters to choose from.

Using your own picture

When no source has a picture, you can use your own. In ⋯ → Fix Metadata…, choose Choose Image… below the results. It sets the poster for a film or show, the cover for an album, or the photograph for an artist. An artist also has a hero image, the wide picture behind their name at the top of their page, with its own Choose Image… button. Your browser shrinks the picture before sending it. It's then kept, and nothing automatic replaces it.

To go back to what matching finds, open Fix Metadata and choose Remove Uploaded Image or Remove Hero Image. Remove Uploaded Image also undoes a poster you picked with Change Poster.

Age ratings

Films and shows get their age rating from TMDb. Ratings are read for your country first, which you set in Settings → Region & Metadata → Region. If your country has no rating for a title, other countries are tried in turn. You see the rating the board issued, such as PG-13. Child accounts see only what's rated for their age, and nothing unrated: unrated isn't the same as suitable.

After you change the region, run Update Metadata and every stored rating is read again. See Region & Metadata.