Stremio's player never sees a torrent

What happens when you press play in Stremio? Three things in two places: the app and its server on your Mac, the addon somewhere else. The player never sees a torrent, only an address on your own machine.

  1. 01The question
  2. 02Three things in two places
  3. 03The server is a website on your Mac
  4. 04A magnet link is a fingerprint
  5. 05The film arrives in pieces
  6. 06Every piece crosses as packets
  7. 07Back up

01The question

Stremio is an app for watching films and shows. Press play and, a second or two later, a film starts. Clear out your disk and you may find a folder called stremio-server holding tens of gigabytes. So what is actually happening between the press and the picture, and what is that folder?

The answer runs through most of what makes networks feel like magic: a server on your own machine, torrents, fingerprints, and the packets everything travels in. Each layer hides the one beneath it, which is why it feels like magic, and why it stops feeling that way once the layers are taken apart. This note builds on Your shell finds a tool by searching folders in order, which covers where programs live on your machine.

02Three things in two places

Stremio is three programs, and only two are on your Mac. The app is what you click: the catalogue, the buttons, the player. stremio-server is a second program the app starts behind it, and it does the downloading. The addon, Torrentio for instance, isn't on your Mac at all. It is an : a small website running on someone else's server.

Installing an addon saves its address, and a copy of its description, in the app's settings. That is all. If the addon's server went offline, it would disappear from the app though nothing on your Mac changed. The server is the opposite: a real program on your disk, which works with no internet at all.

Press play, and the app sends the addon the film's IMDb ID. The addon has already searched torrent sites and indexed what it found, so it answers with a list of streams: the quality, the size, and each one's fingerprint. It sends no film. You pick one, and the app hands that fingerprint to the server.

Fig 01
Step 1 of 5
  1. 1Stremio appYour Mac
  2. 2stremio-serverYour Mac
  3. 3TorrentioSomeone else's server
  4. 4Other peersThe swarm

1 / 5You open the film. The app asks Torrentio, out on the internet, what streams there are for it.

Carriestt1254207, Big Buck Bunny's IMDb ID
Pressing play, one message at a time. Ink is whoever is acting.

The addon finds; the server fetches. Finding happens on someone else's machine, fetching on yours.

03The server is a website on your Mac

The app and the server talk the way a browser talks to a website: the app asks for an address over HTTP, and the server sends back bytes. The address is 127.0.0.1:11470. 127.0.0.1, or , is the address every computer gives itself; 11470 is the , the number that says which program on the machine should answer. So localhost isn't a third thing. It's how the app reaches the server when both are on the same Mac.

Why two programs, rather than one? Because the player knows how to play an address, not a torrent. Make the torrent engine a small web server, and the player can play its films like any other video online. It also means the server can live somewhere else: on a home server, with a phone or a TV pointing at it. Localhost is the case where somewhere else is your own Mac. The shape is client and server, the same as your browser and a website, or the claude command and Anthropic's API.

Fig 02
GET http://127.0.0.1:11470/…
The request
Never leaves the Mac. It goes out through the network software and straight back in.
Who downloads
This Mac
The player sees
A web address that sends a video. The same in both.
The same request with the server in two places. Only the address changes.

The player never sees a torrent. It asks a web address on its own machine for a film, and gets one.

04A magnet link is a fingerprint

What the server is handed is a , and to see what that is, start with what a torrent is. A file is cut into numbered pieces, usually 256 KiB each. Every piece is run through a function, which turns any amount of data into a short number that changes completely if a single byte does: a fingerprint. The list of pieces and their fingerprints is the torrent's description. Hash the description, and you get one fingerprint for the whole torrent, its .

A magnet link is that info hash and a name to show, and nothing more: magnet:?xt=urn:btih:dd8255ec… and so on. It's enough, because the fingerprint can be used to find people who have the torrent. The server asks the , a phone book spread across the peers themselves. Each one it asks passes it to others nearer the fingerprint, until it reaches some who know who is sharing it. (The older way is a , a server that does nothing but introduce people.) One of them sends the description, and the server checks that it hashes to the fingerprint it started with.

Fig 03
You

The magnet link is only the fingerprint, and a name to show. Nobody has been asked anything yet.

The descriptionNot yet
From a magnet link to the full description, a hop at a time through the DHT.

A magnet link is only the fingerprint. The swarm fills in the rest, and the fingerprint proves it's the right thing.

05The film arrives in pieces

Everyone sharing a torrent at the moment is its , and each of them is a . A has the whole thing and only uploads. The server connects to some of them, and they say which pieces they have. Each piece that arrives is hashed and checked against its fingerprint; a piece that doesn't match is thrown away and asked for again from someone else, so a stranger can't slip in a broken piece.

An ordinary torrent client takes pieces in whatever order is quickest. A film needs them in order, so a streaming engine asks first for the pieces just ahead of the playhead, writes each to disk, and sends it to the player. Skip back and the pieces are already there; skip ahead and it asks for that part next. That cache is the folder you found. When the film ends the pieces stay, a full copy for every film, until something clears them. (Stremio's server is closed source, so its exact rules can't be read; this is what the open streaming engines do.)

Fig 04
0 pieces on disk

Play. The server asks peers for the first pieces before anything else.

▼ PlayheadInk on disk · outline coming
A film's pieces as a streaming engine fetches them. Ink is on disk; an outline is coming; dots are not asked for yet.

And while it downloads, the server uploads pieces to other peers. That is how the swarm works: the more people want a film, the more there are to get it from. It also means every peer you trade with sees your address.

The film is assembled under the player from pieces sent by strangers, each one checked by its fingerprint.

06Every piece crosses as packets

One piece doesn't travel whole. It crosses the internet as about 180 , small envelopes of data, each stamped with where it's from and where it's going. Every router on the way reads only the "to", passes the packet one hop nearer, and forgets it. Nobody knows the whole route, which is why the internet carries on when a cable is cut: packets go round it.

At your end, the packets are put back in order and the receiver sends small acknowledgements back, saying what has arrived. Anything that didn't is sent again. This is the bottom: the one trick the whole internet runs on.

Fig 05
The peer
From198.51.100.23 (the peer)To203.0.113.7 (you)Carries1,460 bytes of piece 412

Piece 412 leaves the peer as about 180 packets. This is one, stamped from the peer, to you, with its number in the sequence.

One packet of a piece, crossing from a peer to you a hop at a time.

07Back up

Now the right way up. Packets make a piece; checked pieces make the film, near the playhead first; the server serves it at an address on your own Mac; the player plays it. Above that, the app asked the addon what there was, and the addon answered with fingerprints.

Everything below the player is hidden from it. It asked an address on its own machine for a film, and got one.

Connected

Side threads

Questions that came up once the main idea began to hold, kept as they were asked. Each opens beside the paragraph it grew from.

Terms

Checked

What the chat had wrong or only half right, against sources. The note above already says the corrected thing.

  1. The server picks the pieces near the playhead and caches them.Stremio's server is closed source, so how it picks can't be read. The open streaming engines it resembles do ask first for what playback needs, and keep it on disk.torrent-stream
  2. stremio-server is a Node.js server.Stremio's app runs a bundled, closed-source server.js with Node, at 127.0.0.1:11470, or another port if that one is taken.stremio-shell source
  3. Without a VPN, every hop knows you're on Netflix.With HTTPS the hops never see what you send. They see the address, and usually the site's name, unless encrypted DNS and Encrypted Client Hello hide it.RFC 8744; RFC 9849
  4. A VPN hides you.From the café, your provider and the site. The VPN provider now sees what your provider used to, and how much you send, and when, still shows.RFC 8744
  5. A torrent file or magnet link lists the pieces' checksums.A magnet link carries only the info hash. The description, with the piece fingerprints, comes from a peer and is checked against it.BEP 9
  6. Installing an addon saves only its address.Its address and a copy of its manifest. Torrentio answers with each torrent's info hash and which file in it is the film.Stremio addon protocol
  7. Peers fetch the rarest pieces first.That is how clients behave, with exceptions; the original specification says pieces are usually fetched in random order.BEP 3; Cohen, Incentives Build Robustness in BitTorrent, 2003
  8. The DHT has no central server.True, but a new client joins through a few well-known contacts.BEP 5
  9. Cap the upload at about 80% of the line's speed.The usual advice is closer to 90% of a measured speed test.OpenWrt, SQM
  10. Every packet you receive is acknowledged by one going back.TCP usually acknowledges every second packet. The queue builds the same way.RFC 9293
  11. With a debrid service, your Mac never joins a swarm.Your Mac doesn't, but the service's servers do, and the service knows what you fetched.Real-Debrid API