Get started
How Wren TV works
The server, Wren TV accounts, the web player and the address service, and what each one sees.
Wren TV has a few parts. Only one of them touches your media: your own server.
The pieces
| Piece | Where it runs | What it does |
|---|---|---|
| Wren TV server | Your computer, NAS or VPS | Scans your folders, fetches metadata, streams video, keeps watch history |
| Wren TV accounts | Hosted (Supabase) | Sign-in, which servers you own, who you've shared them with |
| Web player | watch.wrentv.com | An app in your browser that talks to your server directly |
| Address service | api.wrentv.net | Publishes HTTPS names for servers, like 192-168-1-20.<id>.wrentv.net |
| Apps | Your devices | Like the web player, with more formats (libmpv) and true Dolby Vision output |
What happens when you press play
- You sign in. The web player or app signs in to Wren TV accounts with your email and password.
- It finds your servers. Your account lists the servers you own or that were shared with you, with each server's addresses. Servers report those addresses themselves every five minutes and whenever they change (a "heartbeat").
- It connects. The player tries every address at once and keeps the first that answers and proves it's the right server. Addresses on your home network win, then the owner's own public URL, then the automatic public address.
- It streams. Browsing and playback requests go straight to the server, carrying your sign-in token. The server checks with Wren TV accounts that you're allowed in, and which libraries you can see.
- Video flows directly from the server to your screen. It never passes through wrentv.com, Cloudflare or anyone else.
What each part sees
- wrentv.com and watch.wrentv.com only serve web pages. They never see your media, your library or your watch history.
- Wren TV accounts know your email, display name, the servers you own, their names and addresses, the list of library names, and who you share with. Not what's in the libraries.
- The address service sees the IP addresses your server asks it to publish, and nothing else.
- Your server keeps everything else: the library database, artwork, watch progress and play history, in its data directory.
Local accounts
A server can also run without Wren TV accounts entirely (auth.mode: local). Then accounts are usernames and
passwords stored on the server, and you use the web app the server hosts at http://<server>:32500. watch.wrentv.com,
email sharing and automatic HTTPS addresses need Wren TV accounts. See First run.