From f11e5508ad40061bdcf300189ef078537c2a248f Mon Sep 17 00:00:00 2001
From: Duncan Tourolle <duncan@tourolle.paris>
Date: Sun, 28 Jun 2026 12:16:07 +0200
Subject: [PATCH] update readme and spec for current release

---
 README.md | 656 ++++++++++++++++++++++++------------------------------
 SPEC.md   |  10 +-
 2 files changed, 301 insertions(+), 365 deletions(-)

diff --git a/README.md b/README.md
index e9d84b6..7e608b5 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,19 @@
 # JRay
 
-JRay reads "truth" files produced offline by the scene-actor-extraction pipeline (face detection + recognition) and exposes an API to query which actors are visible on screen at a given timestamp in a movie, for building an actor-overlay (Jellyfin "X-Ray") style feature.
+A Jellyfin plugin that brings an actor-overlay (think Amazon "X-Ray") feature to your media: pause a movie and JRay shows you which actors are on screen at that exact moment.
+
+JRay reads "truth" files produced offline by the
+[scene-actor-extraction](https://github.com/dtourolle/scene-actor-extraction)
+pipeline (face detection + recognition) and exposes an API to query which actors
+are visible at a given timestamp. A small overlay, injected into the Jellyfin web
+client, displays the result when you pause playback.
+
+## Status
+
+**Alpha** — JRay works end to end (sidecar truth files, remote truth push, and the
+pause overlay) but is early software and the truth-file schema may still change.
+The overlay relies on patching the web client's `index.html`, which is inherently
+a little fragile across Jellyfin versions (see [Important Notes](#important-notes)).
 
 ## Quick Install
 
@@ -10,422 +23,339 @@ Add this repository URL in Jellyfin (Dashboard → Plugins → Repositories):
 https://gitea.tourolle.paris/dtourolle/jRay/raw/branch/master/manifest.json
 ```
 
-Then install "JRay" from the plugin catalog.
+Then install "JRay" from the plugin catalog and restart Jellyfin.
 
----
+## Features
 
-# So you want to make a Jellyfin plugin
+- **Pause overlay** — pause a movie or episode in the web client and see the
+  actors currently on screen, without leaving the player.
+- **Sidecar truth files** — drop a `Movie.jray.json` next to `Movie.mkv` and JRay
+  picks it up automatically (suffix configurable).
+- **Remote truth push** — for servers that can't run the extraction pipeline
+  locally, a remote worker can `PUT` truth data over HTTP. Managed (pushed) data
+  takes precedence over sidecar files.
+- **Work discovery API** — a remote worker can poll for a random batch of library
+  items that still need processing, so the backlog spreads naturally across
+  workers without server-side task tracking.
+- **Extensible "context at time t" envelope** — the per-timestamp response is
+  designed to grow (locations, trivia, …) without breaking existing clients.
+- **In-memory caching** — loaded truth files are cached with a configurable TTL.
+- **Toggleable overlay** — disabling the overlay also cleanly removes the injected
+  script from the web client.
 
-Awesome! This guide is for you. Jellyfin plugins are written using the dotnet standard framework. What that means is you can write them in any language that implements the CLI or the DLI and can compile to net8.0. The examples on this page are in C# because that is what most of Jellyfin is written in, but F#, Visual Basic, and IronPython should all be compatible once compiled.
-
-## 0. Things you need to get started
-
-- [Dotnet SDK 9.0](https://dotnet.microsoft.com/en-us/download/dotnet)
-
-- An editor of your choice. Some free choices are:
-
-   [Visual Studio Code](https://code.visualstudio.com)
-
-   [Visual Studio Community Edition](https://visualstudio.microsoft.com/downloads)
-
-   [Mono Develop](https://www.monodevelop.com)
-
-## 0.5. Quickstarts
-
-We have a number of quickstart options available to speed you along the way.
-
-- [Download the Example Plugin Project](https://github.com/jellyfin/jellyfin-plugin-template/tree/master/Jellyfin.Plugin.Template) from this repository, open it in your IDE and go to [step 3](https://github.com/jellyfin/jellyfin-plugin-template#3-customize-plugin-information)
-
-- Install our dotnet template by [downloading the dotnet-template/content folder from this repo](https://github.com/jellyfin/jellyfin-plugin-template/tree/master/dotnet-template/content) or off of Nuget (Coming soon)
-
-   ```
-   dotnet new -i /path/to/templatefolder
-   ```
-
-- Run this command then skip to step 4
-
-   ```
-      dotnet new Jellyfin-plugin -name MyPlugin
-   ```
-
-If you'd rather start from scratch keep going on to step one. This assumes no specific editor or IDE and requires only the command line with dotnet in the path.
-
-## 1. Initialize Your Project
-
-Make a new dotnet standard project with the following command, it will make a directory for itself.
+## How It Works
 
 ```
-dotnet new classlib -f net9.0 -n MyJellyfinPlugin
+  scene-actor-extraction            Jellyfin server                 web client
+  (offline pipeline)                                                (browser)
+ ┌────────────────────┐           ┌──────────────────┐           ┌────────────┐
+ │ face detection +   │  truth    │   JRay plugin    │  jray?t=  │  pause      │
+ │ recognition        │ ───────►  │ - sidecar reader │ ◄───────  │  overlay    │
+ │ result_sink_node   │  file     │ - managed store  │  actors   │  script     │
+ └────────────────────┘           │ - REST API       │ ───────►  └────────────┘
+        │ PUT /Truth (remote)     │ - web patcher    │
+        └────────────────────────►└──────────────────┘
 ```
 
-Now add the Jellyfin shared libraries.
+1. The extraction pipeline analyses a film offline and emits a **truth file**
+   listing each detected actor and the time windows they're on screen.
+2. JRay loads that truth file either from a **sidecar** next to the media
+   (`Movie.jray.json`) or from a **managed store** populated via the push API.
+3. On startup JRay injects a small `<script>` into the web client's `index.html`.
+   When you pause, the script calls JRay for the current item and timestamp and
+   renders the on-screen actors as an overlay.
 
-```
-dotnet add package Jellyfin.Model
-dotnet add package Jellyfin.Controller
-```
+## Truth File Format
 
-You have an autogenerated Class1.cs file. You won't be needing this, so go ahead and delete it.
+For a media file `Movie.mkv`, JRay looks for a sibling `Movie.jray.json` (suffix
+configurable). Schema (`schema_version: 1`, minimal verbosity):
 
-Navigate to the csproj that was generated, and ensure that you modify the package references to exclude assets, so that unnecessary files aren't copied over.
-Skipping this step will prevent your plugin from registering correctly.
-```
-<ItemGroup>
-    <PackageReference Include="Jellyfin.Controller" Version="10.11.3">
-        <ExcludeAssets>runtime</ExcludeAssets>
-    </PackageReference>
-    <PackageReference Include="Jellyfin.Model" Version="10.11.3">
-        <ExcludeAssets>runtime</ExcludeAssets>
-    </PackageReference>
-</ItemGroup>
-```
-Note: Ensure the package reference version matches the install version of jellyfin server, otherwise the plugin will show as NotSupported.
-
-## 2. Set Up the Basics
-
-There are a few mandatory classes you'll need for a plugin so we need to make them.
-
-### PluginConfiguration
-
-Create a folder named "Configuration", and a PluginConfiguration.cs file inside.
-
-You can call it whatever you'd like really. This class is used to hold settings your plugin might need. We can leave it empty for now. This class should inherit from `MediaBrowser.Model.Plugins.BasePluginConfiguration`
-
-It should look something like the following:
-```c#
-    using MediaBrowser.Model.Plugins;
-    
-    namespace MyJellyfinPlugin.Configuration;
-    class PluginConfiguration : BasePluginConfiguration
+```json
+{
+  "schema_version": 1,
+  "movie": "/path/to/Movie.mkv",
+  "sample_fps": 1,
+  "anneal_sec": 2,
+  "actors": [
     {
-        
+      "name": "Tom Hanks",
+      "imdb_id": "nm0000158",
+      "tmdb_id": "31",
+      "jellyfin_id": "abc123-guid",
+      "scenes": [[12.0, 45.0], [102.5, 150.0]]
     }
+  ]
+}
 ```
 
-### Plugin
+An actor is considered visible at timestamp `t` (seconds) if any of their
+`scenes` windows satisfies `start <= t <= end`. JRay prefers `jellyfin_id` (a
+Jellyfin Person GUID) when present, otherwise resolves `imdb_id`/`tmdb_id`
+against the item's People `ProviderIds`.
 
-This is the main class for your plugin and will reside in the root of your project. It will define your name, version and Id. It should inherit from `MediaBrowser.Common.Plugins.BasePlugin<PluginConfiguration>`
+See [SPEC.md](SPEC.md) for the full schema and field-by-field reference.
 
-It should look something like the following:
-```c#
-    using MediaBrowser.Common.Plugins;
-    using MyJellyfinPlugin.Configuration;
-    
-    namespace MyJellyfinPlugin;
-    
-    class Plugin : BasePlugin<PluginConfiguration>
-    {
-        
-    }
+## API
+
+All routes are served under `/Plugins/JRay`. Authentication uses Jellyfin's
+standard scheme — pass a token (a user access token or an API key) as either
+the `X-Emby-Token: <token>` header or `Authorization: MediaBrowser Token="<token>"`.
+
+| Method & Route | Auth | Description |
+| --- | --- | --- |
+| `GET /Items/{itemId}/jray?t={seconds}` | user | "Context at time t" envelope (on-screen actors), or `404`. |
+| `GET /Items/{itemId}/Timeline` | user | Full truth file for an item, or `404` if none. |
+| `PUT /Items/{itemId}/Truth` | admin | Push managed truth data (schema v1). `204` on success, `400` on bad schema. |
+| `DELETE /Items/{itemId}/Truth` | admin | Remove managed truth data (idempotent, `204`). Falls back to sidecar. |
+| `GET /Tasks/Pending?limit=10` | admin | Random sample of items still needing truth data (default 10, max 100). |
+| `GET /ClientScript` | anon | The pause-overlay script injected into the web client. |
+
+- **user** — any authenticated Jellyfin user token.
+- **admin** — a token belonging to a user with the **Administrator** role
+  (create an API key under Dashboard → API Keys).
+- **anon** — no authentication required.
+
+## Client-Side Integration
+
+JRay is designed so that *any* Jellyfin client (not just the bundled web overlay)
+can build an actor-overlay feature. The integration is two calls: figure out
+**what is playing and where**, then ask JRay **who is on screen**.
+
+### 1. Query on-screen actors: `GET /Items/{itemId}/jray?t={seconds}`
+
+Given a Jellyfin item id and a playback position in **seconds**, returns the
+actors visible at that timestamp. This is the only call most clients need.
+
+**Request**
+
+```
+GET /Plugins/JRay/Items/abc123-guid/jray?t=87.5
+X-Emby-Token: <user-or-api-token>
 ```
 
-Note: If you called your PluginConfiguration class something different, you need to put that between the <>
+**Response — `200 OK`**
 
-### Implement Required Properties
-
-The Plugin class needs a few properties implemented before it can work correctly.
-
-It needs an override on ID, an override on Name, and a constructor that follows a specific model. To get started you can use the following section.
-
-```c#
-public Plugin(IApplicationPaths applicationPaths, IXmlSerializer xmlSerializer) : base(applicationPaths, xmlSerializer){}
-public override string Name => throw new System.NotImplementedException();
-public override Guid Id => Guid.Parse("");
+```json
+{
+  "actors": [
+    {
+      "name": "Tom Hanks",
+      "imdb_id": "nm0000158",
+      "tmdb_id": "31",
+      "jellyfin_id": "abc123-guid"
+    }
+  ]
+}
 ```
 
-## 3. Customize Plugin Information
+- `actors` may be an **empty array** when no one is on screen at `t` — that's a
+  `200`, not a `404`.
+- `404 Not Found` means the item has **no truth data at all** (no managed upload
+  and no sidecar file). Treat this as "JRay isn't available for this item" and
+  silently skip — don't surface an error to the viewer.
+- The id fields are `""` when unresolved. Prefer `jellyfin_id` (a Jellyfin Person
+  GUID) to deep-link into the library or fetch a headshot; fall back to
+  `imdb_id` / `tmdb_id` for external links.
+- The top-level object is an **extensible envelope**: future releases may add
+  sibling keys (e.g. `locations`, `trivia`) alongside `actors`. **Ignore unknown
+  keys** so your client keeps working across versions.
 
-You need to populate some of your plugin's information. Go ahead a put in a string of the Name you've overridden name, and generate a GUID
+### 2. (Optional) Pre-fetch the whole timeline: `GET /Items/{itemId}/Timeline`
 
-- **Windows Users**: you can use the Powershell command `New-Guid`, `[guid]::NewGuid()` or the Visual Studio GUID generator
+Returns the complete truth file (the [schema above](#truth-file-format)) — every
+actor with all their scene windows. Use this if you'd rather fetch once and
+compute "who's on screen" client-side (e.g. to drive a scrubber-bar heatmap)
+instead of polling `jray?t=` on each pause. `404` if no truth data exists.
 
-- **Linux and OS X Users**: you can use the Powershell Core command `New-Guid` or this command from your shell of choice:
+### Reference implementation (web client)
 
-   ```bash
-   od -x /dev/urandom | head -n1 | awk '{OFS="-"; srand($6); sub(/./,"4",$5); sub(/./,substr("89ab",1+rand()*4,1),$6); print $2$3,$4,$5,$6,$7$8$9}'
-   ```
+The bundled overlay ([`Web/jray-overlay.js`](Jellyfin.Plugin.JRay/Web/jray-overlay.js))
+shows the full pattern using Jellyfin's `ApiClient`, and is a good template for a
+custom client:
 
-or
+```js
+// 1. Find what's playing and the current position (in seconds).
+var sessions = await ApiClient.ajax({
+    url: ApiClient.getUrl('Sessions', { DeviceId: ApiClient.deviceId() }),
+    type: 'GET', dataType: 'json'
+});
+var s = sessions[0];
+var itemId = s.NowPlayingItem.Id;
+var t = (s.PlayState.PositionTicks || 0) / 10000000; // ticks → seconds
 
-   ```bash
-   uuidgen
-   ```
+// 2. Ask JRay who is on screen. ApiClient adds the auth token for you.
+var ctx = await ApiClient.ajax({
+    url: ApiClient.getUrl('Plugins/JRay/Items/' + itemId + '/jray', { t: t }),
+    type: 'GET', dataType: 'json'
+});
 
-- Place that guid inside the `Guid.Parse("")` quotes to define your plugin's ID.
-
-## 4. Adding Functionality
-
-Congratulations, you now have everything you need for a perfectly functional functionless Jellyfin plugin! You can try it out right now if you'd like by compiling it, then placing the dll you generate in a subfolder (named after your plugin for example) within the plugins folder under your Jellyfin directory (Normally C:\Users\{YourUserName}\AppData\Local\jellyfin\plugins). If you want to try and hook it up to a debugger make sure you copy the generated PDB file alongside it.
-
-Most people aren't satisfied with just having an entry in a menu for their plugin, most people want to have some functionality, so lets look at how to add it.
-
-### 4a. Implement Interfaces
-
-If the functionality you are trying to add is functionality related to something that Jellyfin has an interface for you're in luck. Jellyfin uses some automatic discovery and injection to allow any interfaces you implement in your plugin to be available in Jellyfin.
-
-Here's some interfaces you could implement for common use cases:
-
-- **IAuthenticationProvider** - Allows you to add an authentication provider that can authenticate a user based on a name and a password, but that doesn't expect to deal with local users.
-- **IBaseItemComparer** - Allows you to add sorting rules for dealing with media that will show up in sort menus
-- **IIntroProvider** - Allows you to play a piece of media before another piece of media (i.e. a trailer before a movie, or a network bumper before an episode of a show)
-- **IItemResolver** - Allows you to define custom media types
-- **ILibraryPostScanTask** - Allows you to define a task that fires after scanning a library
-- **IMetadataSaver** - Allows you to define a metadata standard that Jellyfin can use to write metadata
-- **IResolverIgnoreRule** - Allows you to define subpaths that are ignored by media resolvers for use with another function (i.e. you wanted to have a theme song for each tv series stored in a subfolder that could be accessed by your plugin for playback in a menu).
-- **IScheduledTask** - Allows you to create a scheduled task that will appear in the scheduled task lists on the dashboard.
-
-There are loads of other interfaces that can be used, but you'll need to poke around the API to get some info. If you're an expert on a particular interface, you should help [contribute some documentation](https://docs.jellyfin.org/general/contributing/index.html)!
-
-### 4b. Use plugin aimed interfaces to add custom functionality
-
-If your plugin doesn't fit perfectly neatly into a predefined interface, never fear, there are a set of interfaces and classes that allow your plugin to extend Jellyfin any which way you please. Here's a quick overview on how to use them
-
-- **IPluginConfigurationPage** - Allows you to have a plugin config page on the dashboard. If you used one of the quickstart example projects, a premade page with some useful components to work with has been created for you! If not you can check out this guide here for how to whip one up.
-
- **IPluginServiceRegistrator** - Will be located by Jellyfin at server startup and allows you to add services to the DI container to allow for injection in your plugin's classes later.
-
-- **IHostedService** - Allows you to run code as a background task that will be started at program startup and will remain in memory. See [Microsoft's documentation](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/host/hosted-services?view=aspnetcore-8.0&tabs=visual-studio#ihostedservice-interface) for more information. You can make as many of these as you need; make Jellyfin aware of them with an `IPluginServiceRegistrator`. It is wildly useful for loading configs or persisting state. **Be aware that your main plugin class (IBasePlugin) cannot also be a IHostedService.**
-
-- **ControllerBase** - Allows you to define custom REST-API endpoints. This is the default ASP.NET Web-API controller. You can use it exactly as you would in a normal Web-API project. Learn more about it [here](https://docs.microsoft.com/aspnet/core/web-api/?view=aspnetcore-5.0).
-
-Likewise you might need to get data and services from the Jellyfin core, Jellyfin provides a number of interfaces you can add as parameters to your plugin constructor which are then made available in your project (you can see the 2 mandatory ones that are needed by the plugin system in the constructor as is).
-
-- **IBlurayExaminer** - Allows you to examine blu-ray folders
-- **IDtoService** - Allows you to create data transport objects, presumably to send to other plugins or to the core
-- **ILibraryManager** - Allows you to directly access the media libraries without hopping through the API
-- **ILocalizationManager** - Allows you tap into the main localization engine which governs translations, rating systems, units etc...
-- **INetworkManager** - Allows you to get information about the server's networking status
-- **IServerApplicationPaths** - Allows you to get the running server's paths
-- **IServerConfigurationManager** - Allows you to write or read server configuration data into the application paths
-- **ITaskManager** - Allows you to execute and manipulate scheduled tasks
-- **IUserManager** - Allows you to retrieve user info and user library related info
-- **IXmlSerializer** - Allows you to use the main xml serializer
-- **IZipClient** - Allows you to use the core zip client for compressing and decompressing data
-
-## 5. Create a Repository
-
-- [See blog post](https://jellyfin.org/posts/plugin-updates/)
-
-## 6. Set Up Debugging
-
-Debugging can be set up by creating tasks which will be executed when running the plugin project. The specifics on setting up these tasks are not included as they may differ from IDE to IDE. The following list describes the general process:
-
-- Compile the plugin in debug mode.
-- Create the plugin directory if it doesn't exist.
-- Copy the plugin into your server's plugin directory. The server will then execute it.
-- Make sure to set the working directory of the program being debugged to the working directory of the Jellyfin Server.
-- Start the server.
-
-Some IDEs like Visual Studio Code may need the following compile flags to compile the plugin:
-
-```shell
-dotnet build Your-Plugin.sln /property:GenerateFullPaths=true /consoleloggerparameters:NoSummary
+// 3. Render ctx.actors. A 404 (no truth data) rejects the promise — swallow it.
 ```
 
-These flags generate the full paths for file names and **do not** generate a summary during the build process as this may lead to duplicate errors in the problem panel of your IDE.
+Notes for client authors, learned from the reference overlay:
 
-### 6.a Set Up Debugging on Visual Studio
+- **Position is in seconds.** Jellyfin reports `PositionTicks` (100 ns units);
+  divide by `10_000_000` before passing as `t`.
+- **Fail silently.** A `404` or any network error must never interrupt playback —
+  just render nothing.
+- **Enrich via the core API.** JRay returns ids, not images/bios. Use
+  `jellyfin_id` with the standard Jellyfin item/image endpoints (e.g.
+  `ApiClient.getItem(...)` / `getImageUrl(...)`) to show headshots and overviews,
+  and deep-link to `#/details?id=<jellyfin_id>`.
+- **Refresh on player events.** The overlay recomputes on `pause` and clears on
+  `play` / `playing` / `seeking`. Poll `jray?t=` again after a seek rather than
+  reusing a stale result.
 
-Visual Studio allows developers to connect to other processes and debug them, setting breakpoints and inspecting the variables of the program. We can set this up following this steps:
-On this section we will explain how to set up our solution to enable debugging before the server starts.
+### Pushing truth data (remote extraction workers)
 
-1. Right-click on the solution, And click on Add -> Existing Project...
-2. Locate Jellyfin executable in your installation folder and click on 'Open'. It is called `Jellyfin.exe`. Now The solution will have a new "Project" called Jellyfin. This is the executable, not the source code of Jellyfin.
-3. Right-click on this new project and click on 'Set up as Startup Project'
-4. Right-click on this new project and click on 'Properties'
-5. Make sure that the 'Attach' parameter is set to 'No'
+For the full remote-worker workflow — authenticate, resolve the item id by
+`Path`, and `PUT` the truth file — see
+[SPEC.md](SPEC.md#client-pushing-results-from-a-remote-extraction-worker).
+These endpoints require an **Administrator** token.
 
-From now on, everytime you click on start from Visual Studio, it will start Jellyfin attached to the debugger!
+## Configuration
 
-The only thing left to do is to compile the project as it is specified a few lines above and you are done.
+Configure JRay in Jellyfin Dashboard → Plugins → JRay:
 
-### 6.b Automate the Setup on Visual Studio Code
+- **Truth File Suffix** — filename suffix used to locate sidecar truth files next
+  to media (default `.jray.json`, e.g. `Movie.mkv` → `Movie.jray.json`).
+- **Cache Duration (minutes)** — how long a loaded truth file is cached in memory
+  before being re-read from disk (default `60`).
+- **Enable pause overlay** — whether JRay injects its overlay script into the web
+  client's `index.html`. Disabling it removes any previously injected script
+  (default `on`).
 
-Visual Studio Code allows developers to automate the process of starting all necessary dependencies to start debugging the plugin. This guide assumes the reader is familiar with the [documentation on debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) and has read the documentation in this file. It is assumed that the Jellyfin Server has already been compiled once. However, should one desire to automatically compile the server before the start of the debugging session, this can be easily implemented, but is not further discussed here.
+## Building the Plugin
 
-A full example, which aims to be portable may be found in this repo's `.vscode` folder.
+### Prerequisites
 
-This example expects you to clone `jellyfin`, `jellyfin-web` and `jellyfin-plugin-template` under the same parent directory, though you can customize this in `settings.json`
+- [.NET SDK 9.0](https://dotnet.microsoft.com/en-us/download/dotnet)
+- Jellyfin 10.9.0 or later (built against `Jellyfin.Controller` 10.11.5)
 
-1. Create a `settings.json` file inside your `.vscode` folder, to specify common options specific to your local setup.
-   ```jsonc
-    {
-        // jellyfinDir : The directory of the cloned jellyfin server project
-        // This needs to be built once before it can be used
-        "jellyfinDir"     : "${workspaceFolder}/../jellyfin/Jellyfin.Server",
-        // jellyfinWebDir : The directory of the cloned jellyfin-web project
-        // This needs to be built once before it can be used
-        "jellyfinWebDir"  : "${workspaceFolder}/../jellyfin-web",
-        // jellyfinDataDir : the root data directory for a running jellyfin instance
-        // This is where jellyfin stores its configs, plugins, metadata etc
-        // This is platform specific by default, but on Windows defaults to
-        // ${env:LOCALAPPDATA}/jellyfin
-        "jellyfinDataDir" : "${env:LOCALAPPDATA}/jellyfin",
-        // The name of the plugin
-        "pluginName" : "Jellyfin.Plugin.Template",
-    }
-   ```
+### Build Steps
 
-1. To automate the launch process, create a new `launch.json` file for C# projects inside the `.vscode` folder. The example below shows only the relevant parts of the file. Adjustments to your specific setup and operating system may be required.
+```bash
+dotnet publish Jellyfin.Plugin.JRay/Jellyfin.Plugin.JRay.csproj -c Release
+```
 
-   ```jsonc
-    {
-        // Paths and plugin names are configured in settings.json
-        "version": "0.2.0",
-        "configurations": [
-            {
-                "type": "coreclr",
-                "name": "Launch",
-                "request": "launch",
-                "preLaunchTask": "build-and-copy",
-                "program": "${config:jellyfinDir}/bin/Debug/net8.0/jellyfin.dll",
-                "args": [
-                //"--nowebclient"
-                "--webdir",
-                "${config:jellyfinWebDir}/dist/"
-                ],
-                "cwd": "${config:jellyfinDir}",
-            }
-        ]
-    }
+The compiled `Jellyfin.Plugin.JRay.dll` will be under
+`Jellyfin.Plugin.JRay/bin/Release/net9.0/publish/`.
 
-   ```
+A reproducible build via the bundled Docker image is also available:
 
-   The `request` type is specified as `launch`, as this `launch.json` file will start the Jellyfin Server process. The `preLaunchTask` defines a task that will run before the Jellyfin Server starts. More on this later. It is important to set the `program` path to the Jellyin Server program and set the current working directory (`cwd`) to the working directory of the Jellyfin Server.
-   The `args` option allows to specify arguments to be passed to the server, e.g. whether Jellyfin should start with the web-client or without it.
+```bash
+docker build -f Dockerfile.builder -t jray-builder .
+```
 
-2. Create a `tasks.json` file inside your `.vscode` folder and specify a `build-and-copy` task that will run in `sequence` order. This tasks depends on multiple other tasks and all of those other tasks can be defined as simple `shell` tasks that run commands like the `cp` command to copy a file. The sequence to run those tasks in is given below. Please note that it might be necessary to adjust the examples for your specific setup and operating system.
+## Manual Installation
 
-   The full file is shown here - Specific sections will be discussed in depth
-    ```jsonc
-    {
-        // Paths and plugin name are configured in settings.json
-        "version": "2.0.0",
-        "tasks": [
-            {
-            // A chain task - build the plugin, then copy it to your
-            // jellyfin server's plugin directory
-            "label": "build-and-copy",
-            "dependsOrder": "sequence",
-            "dependsOn": ["build", "make-plugin-dir", "copy-dll"]
-            },
-            {
-            // Build the plugin
-            "label": "build",
-            "command": "dotnet",
-            "type": "shell",
-            "args": [
-                "publish",
-                "${workspaceFolder}/${config:pluginName}.sln",
-                "/property:GenerateFullPaths=true",
-                "/consoleloggerparameters:NoSummary"
-            ],
-            "group": "build",
-            "presentation": {
-                "reveal": "silent"
-            },
-            "problemMatcher": "$msCompile"
-            },
-            {
-                // Ensure the plugin directory exists before trying to use it
-                "label": "make-plugin-dir",
-                "type": "shell",
-                "command": "mkdir",
-                "args": [
-                "-Force",
-                "-Path",
-                "${config:jellyfinDataDir}/plugins/${config:pluginName}/"
-                ]
-            },
-            {
-                // Copy the plugin dll to the jellyfin plugin install path
-                // This command copies every .dll from the build directory to the plugin dir
-                // Usually, you probablly only need ${config:pluginName}.dll
-                // But some plugins may bundle extra requirements
-                "label": "copy-dll",
-                "type": "shell",
-                "command": "cp",
-                "args": [
-                "./${config:pluginName}/bin/Debug/net8.0/publish/*",
-                "${config:jellyfinDataDir}/plugins/${config:pluginName}/"
-                ]
+1. Build the plugin (see above).
+2. Copy the published output into a `JRay` subfolder of your Jellyfin plugins
+   directory (e.g. `~/.local/share/jellyfin/plugins/JRay/` on Linux, or
+   `%LOCALAPPDATA%\jellyfin\plugins\JRay\` on Windows).
+3. Restart Jellyfin.
+4. Configure JRay in Dashboard → Plugins → JRay.
 
-            },
-        ]
-    }
+## Technical Architecture
 
-    ```
-    1.  The "build-and-copy" task which triggers all of the other tasks
-    ```jsonc
-        {
-        // A chain task - build the plugin, then copy it to your
-        // jellyfin server's plugin directory
-        "label": "build-and-copy",
-        "dependsOrder": "sequence",
-        "dependsOn": ["build", "make-plugin-dir", "copy-dll"]
-        },
-    ```
-    2.  A build task. This task builds the plugin without generating summary, but with full paths for file names enabled.
+### Directory Structure
 
-        ```jsonc
-            {
-            // Build the plugin
-            "label": "build",
-            "command": "dotnet",
-            "type": "shell",
-            "args": [
-                "publish",
-                "${workspaceFolder}/${config:pluginName}.sln",
-                "/property:GenerateFullPaths=true",
-                "/consoleloggerparameters:NoSummary"
-            ],
-            "group": "build",
-            "presentation": {
-                "reveal": "silent"
-            },
-            "problemMatcher": "$msCompile"
-            },
-        ```
+```
+Jellyfin.Plugin.JRay/
+├── Configuration/
+│   ├── PluginConfiguration.cs     # Suffix, cache TTL, overlay toggle
+│   └── configPage.html            # Dashboard config page (embedded resource)
+├── Controllers/
+│   ├── ActorsController.cs        # /Timeline and /jray?t= read endpoints
+│   ├── TruthController.cs         # PUT/DELETE managed truth data
+│   ├── TasksController.cs         # /Tasks/Pending work discovery
+│   └── WebController.cs           # /ClientScript overlay script
+├── Models/
+│   ├── TruthFile.cs               # Root truth-file schema (schema_version 1)
+│   ├── TruthActor.cs              # Per-actor entry with scene windows
+│   ├── ActorAtTime.cs            # Actor entry in the "context at t" envelope
+│   ├── JRayContext.cs             # Extensible "context at time t" envelope
+│   └── PendingExtractionItem.cs   # Item descriptor for the work-discovery API
+├── Services/
+│   ├── Interfaces/
+│   │   ├── ITruthDataService.cs
+│   │   └── IManagedTruthStore.cs
+│   ├── TruthDataService.cs        # Resolves + caches truth (managed > sidecar)
+│   ├── ManagedTruthStore.cs       # Storage for pushed/managed truth data
+│   └── WebClientPatchService.cs   # Injects/removes overlay script in index.html
+├── Web/
+│   └── jray-overlay.js            # Pause-overlay client script (embedded resource)
+├── ServiceRegistrator.cs          # DI registration
+└── Plugin.cs                      # Plugin entry point; applies web patch on load
+```
 
-    3.  A tasks which creates the necessary plugin directory and a sub-folder for the specific plugin. The plugin directory is located below the [data directory](https://jellyfin.org/docs/general/administration/configuration.html) of the Jellyfin Server. As an example, the following path can be used for the bookshelf plugin: `$HOME/.local/share/jellyfin/plugins/Bookshelf/`
-        ```jsonc
-            {
-                // Ensure the plugin directory exists before trying to use it
-                "label": "make-plugin-dir",
-                "type": "shell",
-                "command": "mkdir",
-                "args": [
-                "-Force",
-                "-Path",
-                "${config:jellyfinDataDir}/plugins/${config:pluginName}/"
-                ]
-            },
-        ```
+### Key Components
 
-    4.  A tasks which copies the plugin dll which has been built in step 2.1. The file is copied into it's specific plugin directory within the server's plugin directory.
+1. **Truth Data Service** (`TruthDataService`): resolves truth data for an item —
+   managed (pushed) data takes precedence over a sidecar file — and caches the
+   result in memory with the configured TTL.
+2. **Managed Truth Store** (`ManagedTruthStore`): stores truth data pushed via the
+   API, independently of the media library filesystem.
+3. **Controllers**: REST endpoints for reading (`ActorsController`), pushing
+   (`TruthController`), work discovery (`TasksController`), and serving the
+   overlay script (`WebController`).
+4. **Web Client Patch Service** (`WebClientPatchService`): injects (or removes) the
+   `<script>` tag in the web client's `index.html`, marked with `<!-- jray-overlay -->`
+   so it's idempotent. Re-applied whenever configuration changes.
+5. **Overlay Script** (`jray-overlay.js`): listens for the player's pause event,
+   calls `jray?t=`, and renders the on-screen actors.
 
-        ```jsonc
-            {
-                // Copy the plugin dll to the jellyfin plugin install path
-                // This command copies every .dll from the build directory to the plugin dir
-                // Usually, you probablly only need ${config:pluginName}.dll
-                // But some plugins may bundle extra requirements
-                "label": "copy-dll",
-                "type": "shell",
-                "command": "cp",
-                "args": [
-                "./${config:pluginName}/bin/Debug/net8.0/publish/*",
-                "${config:jellyfinDataDir}/plugins/${config:pluginName}/"
-                ]
-            },
-        ```
+## Important Notes
 
-## Licensing
+- **Web client overlay is a patch, not a hook.** Jellyfin has no plugin hook for
+  player UI, so JRay edits the web client's `index.html` directly. This generally
+  survives across restarts but may need re-applying after a Jellyfin web update;
+  toggling the overlay setting off and on re-runs the patch.
+- **Truth data is produced offline.** JRay does not run face detection itself — it
+  consumes truth files from the
+  [scene-actor-extraction](https://github.com/dtourolle/scene-actor-extraction)
+  pipeline. No extraction = no overlay.
+- **Schema version 1 only.** JRay accepts `schema_version: 1`. The schema may
+  change in future releases; bump-aware clients should send the version they
+  produced.
+- **Remote path mapping.** Workers pushing truth match items by `Path`, so they
+  must see media at the same path Jellyfin does (translate paths first if mounts
+  differ).
 
-Licensing is a complex topic. This repository features a GPLv3 license template that can be used to provide a good default license for your plugin. You may alter this if you like, but if you do a permissive license must be chosen.
+## Contributing
 
-Due to how plugins in Jellyfin work, when your plugin is compiled into a binary, it will link against the various Jellyfin binary NuGet packages. These packages are licensed under the GPLv3. Thus, due to the nature and restrictions of the GPL, the binary plugin you get will also be licensed under the GPLv3.
+Contributions welcome! This project is hosted on a self-hosted
+[Gitea](https://gitea.tourolle.paris/dtourolle/jRay) instance.
 
-If you accept the default GPLv3 license from this template, all will be good. However if you choose a different license, please keep this fact in mind, as it might not always be obvious that an, e.g. MIT-licensed plugin would become GPLv3 when compiled.
+**You don't need a separate account** — you can sign in with your existing GitHub
+account. On the [sign-in page](https://gitea.tourolle.paris/user/login), choose
+**"Sign in with GitHub"** to register and log in via GitHub OAuth. Once signed in,
+you can:
 
-Please note that this also means making "proprietary", source-unavailable, or otherwise "hidden" plugins for public consumption is not permitted. To build a Jellyfin plugin for distribution to others, it must be under the GPLv3 or a permissive open-source license that can be linked against the GPLv3.
+- **Raise issues** — report bugs or request features on the
+  [issue tracker](https://gitea.tourolle.paris/dtourolle/jRay/issues).
+- **Contribute code** — fork the repository, push a branch, and open a pull request.
+
+## License
+
+JRay is licensed under the **GNU General Public License v3.0**. See the
+[LICENSE](LICENSE) file for details.
+
+Because Jellyfin plugins link against the GPLv3-licensed Jellyfin NuGet packages,
+the compiled plugin is necessarily GPLv3 as well.
+
+## Acknowledgments
+
+This plugin was developed partly using
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) by Anthropic.
+
+Built on the [Jellyfin plugin template](https://github.com/jellyfin/jellyfin-plugin-template)
+and powered by the
+[scene-actor-extraction](https://github.com/dtourolle/scene-actor-extraction)
+pipeline.
+
+## References
+
+- [Jellyfin Plugin Documentation](https://jellyfin.org/docs/general/server/plugins/)
+- [scene-actor-extraction pipeline](https://github.com/dtourolle/scene-actor-extraction)
+- [JRay truth file specification](SPEC.md)
diff --git a/SPEC.md b/SPEC.md
index d3b00f4..3019303 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -53,15 +53,21 @@ For a given timestamp `t` (seconds), an actor is visible if any of their
 
 ## API
 
+All read endpoints below require an authenticated Jellyfin user token (passed as
+`X-Emby-Token` or `Authorization: MediaBrowser Token="..."`); the admin endpoints
+additionally require the **Administrator** role. Only `GET /Plugins/JRay/ClientScript`
+is anonymous.
+
 ### `GET /Plugins/JRay/Items/{itemId}/Timeline`
 
 Returns the full truth file (schema above) for an item, or `404` if no truth
-data exists (neither a managed upload nor a sidecar file).
+data exists (neither a managed upload nor a sidecar file). Requires an
+authenticated user token.
 
 ### `GET /Plugins/JRay/Items/{itemId}/jray?t={seconds}`
 
 Returns an extensible "context at time t" envelope, or `404` if no truth
-data exists for the item:
+data exists for the item. Requires an authenticated user token:
 
 ```json
 {