Getting started

1. Install Witchstream on your TV or phone and create your profile.
2. Open Settings › Sources and add a stream source (see below). Without one, the app stays empty: it comes with no content.
3. Optional but recommended: add a free TMDB key for richer home rows, actor pages and search by people.
4. Optional: turn on sync to share profiles, lists and progress between your devices.

Sources

Witchstream plays from Stremio compatible addons. Paste an addon link (it usually ends in /manifest.json) into Settings › Sources › Stream source. You can add more under More stream sources: their streams are added together.

You can also use your own media server through an addon that serves it in the same format. Only add sources you have the right to use.

Only titles my source has

When this is on, the home page, search and suggestions only show titles your sources can play. The first start builds this list, so it takes a little longer; after that the page opens straight away.

Allow low quality copies

Off by default: camera recordings and early leaks are hidden, and titles that only exist that way stay out of your catalog.

Quality

Settings › Playback › Quality sets what Play picks, separately for TVs (1080p by default) and phones (720p by default). If it isn't available, the next one up is used. Every version stays in Other streams.

TMDB key (free)

TMDB is a free film and TV database. With your own key you get personal home rows, “Because you watched”, actor and collection pages, cast in the player, and search by actor or director.

1. Create a free account at themoviedb.org.
2. Go to Settings › API and request a key (choose personal use).
3. Copy the API Key (or the Read Access Token) into Settings › TMDB in Witchstream.

Your key stays on your devices. This product uses the TMDB API but is not endorsed or certified by TMDB.

Debrid (optional)

A debrid service turns many links into instant, fast streams and downloads. It's a paid service from a third party. If you use one, set it up in your source's own settings, then turn on Settings › Sources › I use a debrid service so instant links come first. Witchstream works fine without one.

Sync and devices

Sync uses your own free Firebase project, so your lists never pass through us. Set it up once on a computer:

1. Open console.firebase.google.com and sign in with any Google account. Add project, any name. It's free (Spark plan), no card needed. Analytics can stay off.
2. Build › Authentication › Get started › Sign-in method › Anonymous › Enable › Save.
3. Build › Firestore Database › Create database (not Realtime Database). Any location, Production mode.
4. In Firestore, open the Rules tab, replace everything with the rules below, then Publish.
5. Project settings (gear icon) › General › Your apps › Web (</>) › register with any name. Copy the projectId and apiKey it shows.
6. In Witchstream: Settings › Sync, type them in and press Check and save.

rules_version = '2';
service cloud.firestore {
  match /databases/{db}/documents {
    match /households/{hid} {
      allow get, create, update: if request.auth != null;
    }
    match /households/{hid}/{coll}/{doc} {
      allow read, write: if request.auth != null;
    }
    match /pairs/{code} {
      allow get, create, delete: if request.auth != null;
    }
  }
}

Adding another device

On a device that's already set up: Settings › Sync › Add a device. It shows a code for 10 minutes. On the new device, open Settings › Sync, type the code and press Join.

Profiles

Each person gets their own Continue watching, list, history, likes and suggestions. Settings, sources and Live TV are shared. When you create a new profile and there are at least two people, you can make it a group profile for watching together: it moves each member's own progress along too.

Live TV

Add a playlist link (.m3u) under Settings › Live TV. TV guides load by themselves: the playlist's own guide if it has one, and free guides for the countries of the channels you browse. If a channel still has no guide, you can add a guide link (XMLTV, .xml or .xml.gz) to that service.

Play on TV and the phone keyboard

1. Open Witchstream on the TV. Phone and TV must be on the same Wi‑Fi.
2. On the phone, a TV icon appears at the top. Tap it and choose Pair; type the 4 digit code the TV shows. You only do this once.
3. On a title page or in the player, tap the cast icon or Play on TV. Or choose Keyboard to type on the TV.

Everything stays on your home network. Unpair phones on the TV under Settings › Sync › Phones.

Downloads (phones)

Tap Download on a title page. Downloads run on Wi‑Fi (you can allow mobile data in Settings) and keep going in the background. With Smart downloads on, finishing a downloaded episode fetches the next ones, and watched downloads are deleted after a week.

Something's wrong

A page keeps loading

Open Settings › About › Diagnostics while it loads. If it says PAUSED, your source asked the app to slow down for a minute; it carries on by itself. If it shows errors, check your connection.

“Your source is busy” or “No connection”

Wait a moment and press Try again. Some free sources limit how many questions they answer.

A video won't play

Some devices can't play some formats (for example 10-bit HEVC on older TV boxes). Go back and pick another version in Other streams, or use Open in another player (VLC, MX Player).

Still stuck?

Write to hello@witchstream.com with a screenshot of Diagnostics and what you were doing.