Getting started

From a freshly installed server to everyone in the house watching. Everything here happens in a browser, signed in as the administrator, except the apps themselves.

Not installed yet? Start with the installation guide.

  1. Add your library folders

    In Settings → Library Folders → Add a Folder, choose each folder and say what is in it: films, television, music, music videos or home videos. Browse finds a folder on your drive, and New Folder there makes one if it doesn't exist yet. You can add as many as you like, across drives. A layout made for Plex or Jellyfin works unchanged.

    A scan never moves, renames or rewrites a file. Your folders change only when you upload, delete or correct a match yourself.

  2. Get a TMDb key, for posters and details

    Why it's needed. Home Stream doesn't carry its own database of every film and programme ever made. Instead, it looks each one up in TMDb, The Movie Database, from the title and year in its file name: that's how a file called Nosferatu (1922).mp4 becomes a title with a poster, a description, its cast, its running time and its age rating. TMDb asks each person who uses it to have their own key, which is free for use at home. Your server uses yours directly, so nothing passes through us. It takes about five minutes, once.

    Without a key, films and shows still play, but:

    • they're listed by their file names, with no posters, descriptions, cast or details;
    • they have no age rating, so child accounts see no films or shows at all, because anything unrated is hidden from them;
    • film series don't collect themselves, there are no online trailers, and there's no In Theatres page;
    • a wrong title can't be corrected with Fix Metadata.

    Music isn't affected: album and artist details come from MusicBrainz, which needs no key. Age ratings don't apply to music, so child accounts see all of it.

    1. Make a free account at themoviedb.org/signup, and confirm it from the email TMDb sends.
    2. Signed in, open your account's Settings, then API, or go straight to themoviedb.org/settings/api.
    3. Ask for a key. Choose Developer when asked what kind, accept TMDb's terms, and fill in the short form: for the type of use, choose personal; for the application, write something like "Home Stream, my home media server"; for the website, openhomestream.com is fine.
    4. TMDb shows two values. Copy the short one, labelled API Key, not the much longer "API Read Access Token".

    Then, in Home Stream, paste it into Settings → Region & Metadata → TMDb API Key and choose Save. While you're there, set Region to your country, so films and shows take their age rating from it.

    You can add the TMDb key later. Once it's saved, run Settings → Library Maintenance → Update Metadata and everything already in the library is filled in.

  3. Scan

    Run Settings → Library Maintenance → Library Scan. A scan does two things in one go: it finds your files, then fetches their details and artwork from TMDb and MusicBrainz. That's why the TMDb key comes first, and why there's no separate step for the details. The first scan of a large library takes a while; you can watch it fill in, and leave the page while it works.

    Turn on Schedule Scans there too, and anything you copy to the drive later appears on its own, details included.

    Scanned before adding your TMDb key? Run Update Metadata, just below Library Scan, once the TMDb key is saved. It fetches whatever the library is missing without reading your files again.

  4. Invite the household, yourself included

    In Settings → Users & Devices → People, create an invitation code for each person and pass it on however you like. Mark a child's invitation as a child's: their account sees only what is rated for their age, and nothing unrated.

    To look after collections and artwork from your own account, give it Can curate.

  5. Install the apps

    On iPhone and iPad, open the app on your home network. Your server is listed by name; if it isn't, choose Enter address and type the one your browser uses. Allow access to the local network when asked: without it nothing can be found.

    Sign in with Apple. The first time, the app asks for your invitation code.

    No Apple device? An invitation also works in a browser: open the server's address, choose I have an invite code, and pick a username and password.

  6. Sign in on the Apple TV

    Sign in with Apple, or pair it: the television shows a short code, and you enter it on your iPhone or iPad under Settings → Pair a Device. It joins as you, so it is worth pairing each television as the person who watches it.

  7. Take things with you

    On iPhone and iPad, a film, a series, an album or a playlist can be kept on the device to watch or listen to offline. Where you got to catches up with the server once you're home.

Optional

Every setting, and what it does, is in the server settings reference.

Stuck? The support page answers the common questions, and has an address to write to.