memby/server/internal/credits/README.md

# Credits detection

Where an episode's closing credits begin, discovered for the small number of episodes a
household is actually about to watch.

This is not a library scanner and the distinction is the whole design. A scanner asks "what
is in the library" and answers by reading all of it. This asks "what will somebody press Play
on over the next few evenings", which Tracearr already knows, and reads almost nothing:

```
Tracearr demand → priority queue → marker/cooldown check → tiny tail scan → history + marker
```

## Why it exists

Emby's `CreditsStart` marker is in its `MarkerType` enumeration and Emby 4.10 does not write
it. A survey of this household's 20,000-item library found `Chapter`, `IntroStart` and
`IntroEnd` and **no `CreditsStart` at all**. The existing feature's coverage comes entirely
from chapters *named* like credits — about 5% of items. This fills in the rest.

Emby still wins wherever it has an answer. `api/intro.go` reads its chapters first and only
falls through to a discovered marker when there is nothing to defer to.

## What was reused rather than built

The investigation that preceded this found more already in place than expected, and none of
it was duplicated:

| Needed | Already there |
|---|---|
| Tracearr ingestion | `internal/tracearr` + the `tracearr_sessions` table, imported by the For You pipeline |
| Emby item ids for sessions | `emby_item_id` / `emby_series_id`, backfilled by `UpdateTracearrSessionMapping` |
| Stop positions and next-episode transitions | `progress_ms`, `total_duration_ms`, `started_at`/`stopped_at` on the same table |
| Episode numbering | `library_items`, via `ParentIndexNumber`/`IndexNumber` in the payload |
| Delivery to Android TV | `introResponse.creditsAvailable` / `creditsStartMs` — **no client changes at all** |
| Background scheduling | `internal/scheduler`, so the interval is the operator's and the last run is in the console |
| Live playback signal | the playback reports televisions already send |

Two database reads produce the entire candidate queue for the whole household, whatever it
is watching. Nothing here is per-candidate and nothing polls Tracearr directly.

## The files

```
service.go     the worker, the cache check, and when scanning is allowed
queue.go       bounded in-RAM priority queue; nothing about it is persisted
candidates.go  velocity, look-ahead, decay, multi-user merging — all pure
tracearr.go    demand → candidates, and the in-memory episode index
behaviour.go   stop clustering; can write a marker with no media access at all
confidence.go  signal combination and the rule that stops repeated rewrites
window.go      where to scan, and how season history narrows it
detector.go    the two-stage sparse visual scan and its changepoint
sampler.go     ffmpeg, used surgically
fingerprint.go media version identity, so a replaced file invalidates itself
resolver.go    one Emby request per candidate, cached
postgres.go    the store adapter
load.go        whether the server is too busy for speculative work
```

## Operator controls and history

Admin Console → Credits detection controls three different bounds: the number of candidates
allowed to wait, the ordinary and maximum episode look-ahead, and the retry delay after an
inconclusive or failed speculative scan. The environment values are first-run defaults; a
saved console choice is restored on restart.

The retry delay is important. A successful marker excludes an episode naturally, but an old
worker forgot a no-match result and selected the episode again at the next ten-minute
refresh. Completed attempts now have a small durable history and no-match/failed episodes
cool down before prediction may select them again. Live playback may still raise an episode
immediately because a viewer is waiting.

## Two detectors, and the cheap one is often better

**Behavioural** clustering costs nothing: no file is opened, no decoder runs, no new row is
written anywhere. Where three viewers independently stopped an episode within seconds of each
other, near the end but not at it, that agreement is evidence no decoder can produce. Two
viewers is enough only when both rolled into the next episode, which is unambiguous about why
they left.

**Visual** scanning finds a sustained structural transition — dark, flat, textured with thin
text, and staying that way for about half a minute. Darkness is *multiplied* rather than added
into the frame score, which is the one modelling decision worth defending: under a weighted
sum a night exterior reaches the credit-like floor on darkness and flatness alone, which is
exactly how a final scene comes to be reported as a credits roll. The candidate frame itself
must also be genuinely dark, and at least 65% of the remaining frames must stay credit-like;
those two guards stop a dim final scene or a temporary title card becoming an early marker.
Unit tests pin both cases.

The two fail in unrelated ways, so agreement between them is worth far more than either
alone — hence a probabilistic union rather than an average. Disagreement beyond 20 seconds
costs a 0.3 penalty, which usually means storing nothing. **Prefer no marker to a wrong
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):

| | |
|---|---|
| Generic tail window | `clamp(runtime × 0.20, 5min, 12min)` — 8m50s on a 44-minute episode, **20% of the file** |
| Season-narrowed window | ±90s around the expected position — **3 minutes, 6.8% of the file** |
| Coarse pass | one 160×90 grey frame every 4s — ~45 frames over a narrowed window |
| Fine pass | 750ms over ±30s — ~80 frames |
| Frame buffer | 14,400 bytes, allocated once and reused for the whole pass |
| Writes, cached marker | **0** |
| Writes, completed scan | **1 history row**, plus **1 marker** only when accepted |

Against scanning the full library: 20,000 items read end to end versus a queue capped at 20
candidates, most of which are rejected by the marker check before any media is touched. Once
a household settles, the steady state is one indexed read per candidate and nothing else.

**Not yet measured, and it needs the NAS.** Bytes actually read, wall-clock analysis time,
CPU and peak RSS all depend on the container, the network path to Emby and the media itself,
and no figure taken anywhere else would mean anything. The tool is built and ships in the
image:

```
docker compose exec server /app/memby-credits benchmark <emby-item-id>
```

It prints the runtime, the scan region **and its provenance**, an estimated byte count,
frames sampled, allocation, elapsed time, the detection and what would be stored. The
provenance line is the one to read: a run reporting `generic-tail-window` every time is a run
in which demand-driven narrowing is doing nothing, and the design would need revisiting.

## Things to preserve

- **The queue is deliberately not durable.** Candidate priorities are rebuilt from one
  Tracearr query on restart, which is cheaper and simpler than a second persistent job
  scheduler. Completed scan history is durable because it is an operator record and the
  source of retry cooldowns; it does not preserve or resume queue state.
- **A single worker, and it is not a placeholder for a pool.** Concurrent scans multiply the
  two costs this exists to minimise on a machine whose real job is streaming video.
- **Live playback does not scan immediately.** `livePlaybackDelay` (45s) is what stops a
  curious button press becoming disk activity; `AbandonPlayback` withdraws it.
- **The marker is keyed on a media fingerprint**, so a file Sonarr replaces stops matching
  with nothing having to notice the swap. A fingerprint too weak to detect a replacement
  (runtime only) causes the marker to be *withheld* rather than stored un-invalidatable.
- **Season history needs two markers, not one.** One is an anecdote and may itself be the
  mis-detection; narrowing a scan onto it is how one wrong marker propagates through a season.
- **`ShouldRewrite` is the only thing between "one write per episode, ever" and a row updated
  on every playback.** Readings wobble by seconds; a ±12s difference is not news.
- **The detector never learns why an episode was chosen.** That boundary is what stops it
  being tuned to agree with the predictor rather than with the media.
- **An `ffmpeg` decoder crash gets one conservative retry.** The retry is single-threaded and
  discards corrupt packets; ordinary network, authentication and timeout failures are not
  retried by the sampler.