From cbba97426d75b83d9a6a1674db89ea92acb48cf9 Mon Sep 17 00:00:00 2001 From: Sleeps Date: Thu, 8 Oct 2026 10:55:08 +0100 Subject: [PATCH] Document safe targeted recovery for corrupted caption index --- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/README.md b/README.md index 4d0ceff..8f8db8a 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,46 @@ The current prototype proves this pipeline: The repository now includes the Python Scene Search service, standalone web dashboard and Jellyfin 12 search/control plugin. + +## Repair a damaged caption index (Meilisearch POST/PUT bug) + +Older Scene Search versions submitted caption-only updates via `POST /documents`, +which **replaced** complete frame documents in Meilisearch and dropped +their Jellyfin IDs, media titles and SigLIP vectors. The caption might +still be present but could no longer be attributed to the original video. +The fix uses `PUT /documents` for partial caption updates. + +Canonical SQLite is intact: **do not delete data or rerun captioning**. After +deploying this fix, stop any running caption or library indexing jobs, then +preview the targeted repair: + +```bash +cd /opt/jellyfin-search +docker compose exec -T scene-search python -m scene_search.cli repair-caption-index +``` + +This reports the number of frames with an existing caption or caption-window +membership. It changes nothing. Repair those documents **only** (not the +whole index of millions of visual frames) with: + +```bash +docker compose exec -T scene-search python -m scene_search.cli repair-caption-index --apply +``` + +The command repopulates each affected Meilisearch document with the original +frame ID, Jellyfin video/library IDs, title, timestamp, caption-window +metadata, tags and stored SigLIP embedding from SQLite, waiting for each +Meilisearch task to succeed. It doesn't call Ollama, re-embed frames, clear +Meilisearch or force a whole-library rebuild. If interrupted, simply rerun: +the repair is safe and idempotent. Keep indexing and captioning stopped while +it runs. After completion, test a distinctive saved caption on the standalone +web search and in the Jellyfin plugin diagnostics. + +Note: very old orphaned documents no longer associated with any saved caption +or caption window are outside this targeted selection; a full `sync-meili` +remains available only if a later audit finds widespread unrelated damage. + + ## Persistence model Meilisearch is the fast serving index, but it is not the only copy of expensive AI work.