# metamesh-plugin-still-extractor

MetaMesh container plugin. Grabs a representative frame out of a local video
file and stores it as a content-addressed JPEG, referenced from the video
record as **`still`**.

```
video file ──ffmpeg seek+decode──► frame ──WebDAV PUT──► /files/plugin/still-extractor/
                                                              │
                                                   midhash256 │
                                                              ▼
                                              meta-core:  still = <cid>
```

## Why

Artwork on a local file otherwise comes from TMDB, and only when a title match
succeeds. `still` (METADATA_KEYS.md §6.1) is the episode-level thumbnail slot —
reserved for a future TMDB season-detail fetch, and until now written by
nobody. This plugin gives it a first writer from the one source that never
404s and never depends on a match: the file itself.

**A still is not a poster.** Nothing gates on it, its absence is not an error,
and this plugin never writes `poster` — a frame grab masquerading as real
artwork would propagate to every peer that replicates the record. If a TMDB
episode still ever lands on the record first, this plugin steps aside.

## What it writes

| Key | Value |
|---|---|
| `still` | midhash256 CID of the extracted JPEG |

Nothing else — in particular **no `stillPath`**. `/files/plugin` is a meta-core
watcher root, so the JPEG gets its own record and CID alias and
`LookupPathByCID` resolves it through the reverse index. See the header comment
in `src/plugin.ts`.

## How a frame is chosen

1. Candidate offsets at 20 / 45 / 70 % of `fileinfo/duration`, clamped 2s away
   from both ends (the head is logos and black, the tail is credits).
2. At each offset, one ffmpeg run with **input seeking** (`-ss` before `-i`, so
   it Range-seeks over WebDAV instead of decoding from zero) and
   `thumbnail=60`, which picks the most representative of the next 60 frames.
3. The encoded JPEG is measured (mean + stddev of a 32×32 grayscale reduction).
   Black, blown-out and flat frames are rejected and the next offset is tried.
4. All candidates rejected → `skipped`, no field written.

The primary video stream is the largest one that **looks like moving video** —
not `0:v:0`, and not simply the largest. ffprobe reports attached cover art as
`codec_type=video`, and a 600×900 cover out-measures a 640×480 film.

## Configuration

Runtime config via meta-sort's plugin API (never `plugins.yml`):

```bash
curl -k -X PUT https://metasort-dev.localhost:8180/api/plugins/still-extractor/config \
  -H "Content-Type: application/json" \
  -d '{"seekPercents":"15,40,65","maxWidth":720,"jpegQuality":3}'
```

| Key | Default | What |
|---|---|---|
| `forceRecompute` | `false` | Re-extract even when `still` is already set |
| `seekPercents` | `"20,45,70"` | Candidate offsets, as percentages of duration |
| `maxWidth` | `640` | Frame is scaled down to at most this width |
| `jpegQuality` | `4` | ffmpeg `-q:v`; lower is better quality |
| `frameTimeoutMs` | `120000` | Hard kill for one ffmpeg grab |

## Development

```bash
pnpm install && pnpm build
docker build -t metamesh-plugin-still-extractor:main .
./test.sh            # unit + fixture tests in a container with ffmpeg
./test.sh --shell    # interactive debugging
```

Depends on `file-info` (for `fileType`) and `ffmpeg` (for `fileinfo/duration`
and the `stream/{n}` table). Runs on the **background** queue.