0.2.65 - End Credits wiring / Gateway: 0.1.45 - Credits

server/internal/credits/README.md

@@ -77,6 +77,28 @@ costs a 0.3 penalty, which usually means storing nothing. **Prefer no marker to
 marker** is the governing rule throughout: a missing Skip Credits button is an absence nobody
 notices, a button during the final scene is a fault they remember.
 
+## Where the bytes come from
+
+The gateway has no filesystem access to the media, so a scan reads Emby's own stream route
+over HTTP and `-ss` ahead of `-i` is what makes that a ranged request rather than a download.
+That optimisation is only worth anything if the range survives the trip, which is why the
+address is configurable separately from every other way the gateway reaches Emby.
+
+`MEMBY_EMBY_MEDIA_URL` is the address media bytes are read from; unset it falls back to
+`MEMBY_EMBY_URL` and nothing changes. The distinction is not cosmetic in this deployment: the
+stack runs on the NAS, Emby and the media live on the HTPC, and `MEMBY_EMBY_URL` is a public
+DDNS name. Left to fall back, every ranged read leaves the host for the internet-facing edge,
+pays TLS and returns through a reverse proxy — and a proxy that buffers its upstream turns
+the ranged read into a whole-file read, which is the single thing this package is built not to
+do. Naming the LAN address instead keeps the read on the wire between the two machines.
+
+It is **stated rather than inferred** for the usual reason: there is no way to look at a URL
+and tell whether it happens to resolve locally, and guessing wrong either sends scans the long
+way round or points them at a host that is not there. `media_url` is on the `credits detection
+enabled` start-up line so an operator can read back which path is in force, and the benchmark
+below sets it too — measuring the public route and deploying the internal one would report a
+number belonging to neither.
+
 ## Cost, and what is still unmeasured
 
 **Derived arithmetic** (checkable without hardware):