Documentation

Accounts, people and Kids Mode

Everyone in the house gets their own account, with their own history, favourites and playlists. This page covers inviting people, signing in, what each kind of account can do, and how Kids Mode keeps a child's library suitable.

Who's who

• Administrator. The account made when the server was set up, with a username and password. There is exactly one. It runs the server: it adds library folders, invites people, and changes or removes their access. It isn't meant for watching.
• Curator. Looks after the library: scans, uploads, deleting, fixing matches, collections, home videos and the library settings. Curating can be handed to anyone except a child, without handing over the server.
• Viewer. Watches, and keeps their own history, favourites, watch list and playlists. Can't change the library or the server.
• Child. A viewer in Kids Mode, who sees only what's suitable for their age. A child account can't also curate.

Inviting someone

1. Create an invitation

   As the administrator, go to Settings → Users & Devices → People. Under Invitations, say who it's for, tick Child account or Can curate if either applies, and choose Create Invitation. A child account can't also curate.

2. Pass on the code

   The code looks like ABCD-EFGH. Hand it over however you like. It lasts 7 days and works once. The person joins on the terms you chose, and they can't change them.

3. They redeem it

   In the app, on iPhone or iPad: they sign in with Apple, and the first time the app asks for the code.

   In a browser, with no Apple device needed: they open the server's address, choose I have an invite code, and pick a name, a username and a password of at least 10 characters.

The invitations list shows which codes are still valid, redeemed or expired. Deleting an invitation never removes the account it created.

Signing in

• iPhone and iPad: Sign in with Apple.
• Apple TV: Sign in with Apple, or pair it with a code from your phone.
• A browser: a username and password, or pair it with a code.

Pairing with a code

A television or browser that isn't signed in can show a short code, such as ABC-DEF. In a browser, choose Sign in with a code instead. On iPhone or iPad, enter the code under Settings → Pair a Device. Anyone can also enter it in a browser, under Settings → Users & Devices → Pair a device.

Before you approve, you're shown the device's name, when it asked, which account it will join as, and whether it asked from your home network. Only approve a device you've just started pairing yourself. A code lasts 10 minutes.

A paired device signs in as you, with your access, Kids Mode included. Pair each television as the person who watches it.

What's yours

Each account keeps its own:

• watch history and where you got to, so Continue Watching is yours
• favourites and watch list
• playlists
• picture, set in Settings → Preferences → Your Picture or from iPhone or iPad, and shown on every device
• name, in Settings → Preferences → Your Name
• preferences: whether the next episode plays automatically, whether YouTube trailers are shown, and whether In Theatres is shown. Appearance is kept per browser.

Two of these have a household setting above them, under Settings → Server: how long the next-episode countdown runs, and whether YouTube trailers are offered at all. When trailers are off for the household, your own switch is greyed out.

Pictures are made into a plain square image when saved, with nothing else from the original file kept. A child can choose their own picture only if the administrator allows it, under Settings → Users & Devices → People.

Kids Mode

A child account sees only what's rated for ages 12 and under. On iPhone and iPad, the child's Settings shows Kids Mode: On, ages 12 and under.

How ages are decided

Each film and series has an age certificate. The server reads it for your region first. Set that under Settings → Region & Metadata → Region. If there's none for your region, it looks in the United States, Canada and the United Kingdom, in that order. It turns the certificate into an age and compares it with 12.

Anything unrated is hidden. That includes anything whose certificate the server can't place on its age scale. Unrated means nobody has judged it, not that it's safe. This surprises people, so it's worth knowing.

The age of 12 is fixed. It can't be changed.

What a child doesn't see

• Films and series rated above 12, and anything unrated, everywhere: grids, the home screen, collections, favourites and the watch list. Playback is checked too, not just the listings.
• Home videos. Nobody outside the house has rated them.
• In Theatres, because cinema listings carry no certificates.
• YouTube trailers. A trailer kept in your library as a file is still offered, on the film's own rating.
• Parts of an actor's filmography the child couldn't watch.

Music and music videos carry no ratings and are open to everyone.

Changing it

The child setting is chosen on the invitation. Only the administrator can remove it: Settings → Users & Devices → People → Remove Child Flag. Nobody can lift their own limit. There's no switch to turn an existing account into a child account, so set it on the invitation.

Changing someone's access

The administrator does all of this from Settings → Users & Devices → People.

• Make Curator or Remove Curator.
• Revoke Access stops them signing in and signs out all their devices at once. Their history, favourites and playlists are kept. Restore Access gives everything back.
• Delete erases their favourites, playlists, watch list, history and picture for good. To keep all that, revoke instead.
• Set Password… is for someone who signs in with a password and has forgotten it. You confirm with your own password, and a code if your two-factor is on. If they've never had a username, you give them one. Every device they're signed in on is signed out. Tell them the new password; it isn't shown again. Accounts that sign in with Apple have no password to set.
• Remove Picture takes down a picture that shouldn't be there.

The administrator account can't be deleted or revoked.

Deleting your own account

On iPhone or iPad, go to Settings → Delete Account…. The Apple TV app has the same button on its account screen. Your playlists, favourites and watch history are erased from the server. The library itself isn't touched. This can't be undone. The administrator's account can't be deleted this way.

Signing out devices

• Sign out one device from the device itself. Signing out of a browser doesn't sign out the television.
• See everywhere you're signed in under Settings → Users & Devices → Your Devices. Choose End on any one, or Sign Out Everywhere Else. A device is signed out the moment you do. Everyone has this, children included.
• Change your password in Settings → Security, and every other device is signed out.
• Lost a device? End it from Your Devices on any other device you're signed in on. Or the administrator can revoke your access and restore it, which signs out every device you have.

Two-factor authentication

Any account with a password can add a second step: a six-digit code from an authenticator app, asked for after the password. It works without an internet connection, and nothing is sent anywhere. It's strongly recommended for the administrator and for curators. Accounts that sign in with Apple already have Apple's own.

1. Set it up

   In Settings → Security → Two-Factor Authentication, choose Set Up… and confirm your password. Scan the QR code with your authenticator app, or type in the key shown beside it.

2. Prove it works

   Enter a code from the app and choose Turn On. Until you do, nothing changes.

3. Keep the backup codes

   You're given ten backup codes, shown once. Each works once in place of a code from the app. Copy them or save them as a file, and keep them somewhere safe.

Turning it off, making new backup codes and changing your password all ask for a code as well as your password. After several wrong codes, you'll have to wait a while before trying again.

If the administrator's password is lost

There's no email reset; the server never sends email. Instead, there's a recovery code, kept in a file called recovery-code.txt in the server's data folder, beside its database. Anyone who can reach the machine the server runs on can read it. The person who owns the hardware is the person entitled to get back in.

1. Read the recovery code

   On the machine the server runs on:

   docker exec homestream cat recovery-code.txt

2. Set a new password

   On a computer on the same network as the server, open its address and choose I have lost my password. Enter the username, the recovery code and a new password of at least 10 characters.

• It works only from your own network. It won't work from outside, or through a reverse proxy or tunnel.
• Two-factor is turned off for that account; set it up again once you're back in.
• Every device signed in to that account is signed out.
• The code is replaced as soon as it's used, so a code that's been read out or photographed stops working.

It works for any account with a username, but it's really there for the administrator, who has nobody else to ask. Everyone else can ask the administrator to Set Password….

Without the password and without access to the server's machine, the administrator account can't be recovered.