diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..313a066 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,9 @@ +.git +.github +.venv +.env +data +jellyfin-plugin +tests +__pycache__ +*.pyc diff --git a/.env.example b/.env.example index 198a062..2be91d3 100644 --- a/.env.example +++ b/.env.example @@ -25,6 +25,9 @@ CAPTION_ROUTER_CONTEXT_SECONDS=6 # Jellyfin ingestion JELLYFIN_URL=http://127.0.0.1:8096 +# Docker Compose uses this only from inside the scene-search container. +# Leave blank to use http://host.docker.internal:8096. +JELLYFIN_DOCKER_URL= JELLYFIN_API_KEY= # Preferred: comma-separated list of libraries to index by default. JELLYFIN_LIBRARIES= @@ -47,9 +50,11 @@ JELLYFIN_FORCE_SPECIALIST_TAG=scene-search:specialist JELLYFIN_FORCE_GENERAL_TAG=scene-search:general JELLYFIN_SKIP_TAG=scene-search:skip -# HTTP search API used by the Jellyfin plugin +# HTTP API / standalone web dashboard. +# Docker Compose overrides SCENE_API_HOST to 0.0.0.0 and publishes this port. SCENE_API_HOST=127.0.0.1 SCENE_API_PORT=8097 -# Optional but recommended. When set, /api/search and thumbnails require -# Authorization: Bearer or X-Scene-Search-Key: . +# Strongly recommended when Docker exposes the dashboard/API on the LAN. +# Protected API calls accept Authorization: Bearer or X-Scene-Search-Key. +# The web dashboard stores the key only in the browser's local storage. SCENE_API_KEY= diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..d71b346 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,23 @@ +FROM python:3.12-slim + +ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 \ + PIP_NO_CACHE_DIR=1 + +WORKDIR /app + +RUN apt-get update \ + && apt-get install -y --no-install-recommends ffmpeg curl ca-certificates \ + && rm -rf /var/lib/apt/lists/* + +COPY requirements.txt /app/requirements.txt + +# Install a CUDA-enabled PyTorch wheel explicitly; the NVIDIA container runtime +# supplies access to the host driver/GPU. +RUN python -m pip install --upgrade pip \ + && python -m pip install "torch>=2.4" --index-url https://download.pytorch.org/whl/cu124 \ + && python -m pip install -r /app/requirements.txt + +COPY scene_search /app/scene_search + +CMD ["python", "-m", "scene_search.cli", "serve"] diff --git a/README.md b/README.md index b2724da..1872115 100644 --- a/README.md +++ b/README.md @@ -37,14 +37,52 @@ Long term: - Docker / Docker Compose - Ollama for optional stage-2 captions -## 1. Start Meilisearch +## 1. Run Scene Search with Docker + +The normal deployment runs both Meilisearch and the Scene Search API/web app with Docker Compose. The Python CLI remains available for maintenance and debugging, but you do not need to keep `python -m scene_search.cli serve` running manually. + +Create your environment file and set the Jellyfin/API credentials: ```bash cp .env.example .env -# Change MEILI_MASTER_KEY in .env -docker compose up -d +nano .env ``` +At minimum set `MEILI_MASTER_KEY`, `JELLYFIN_API_KEY`, `SCENE_API_KEY`, and your Ollama URL/model settings. + +GPU access requires the NVIDIA Container Toolkit on the Docker host. Once Docker can expose the NVIDIA GPU to containers, build and start everything: + +```bash +docker compose up -d --build +``` + +The existing `./data` directory is bind-mounted into the application container, so SQLite, thumbnails, editable prompts and the Hugging Face model cache persist across container rebuilds. + +The Compose service reaches Jellyfin on the same host through `host.docker.internal:8096` by default. If your Jellyfin server uses another address, set: + +```env +JELLYFIN_DOCKER_URL=http://your-jellyfin-host:8096 +``` + +Meilisearch is addressed internally as `http://meilisearch:7700`; the existing host port `7869` remains available for its dashboard/API. + +Check the containers: + +```bash +docker compose ps +docker compose logs -f scene-search +``` + +The standalone Scene Search dashboard is then available at: + +```text +http://:8097/ +``` + +If `SCENE_API_KEY` is configured, enter it once in the dashboard. It is stored only in that browser's local storage. + +> If an item has no Jellyfin Trickplay data and the indexer must use ffmpeg fallback, its Jellyfin media path must also be mounted into the container at the same path. Trickplay-backed items do not require the original media filesystem to be mounted. + ## 2. Python environment Create and activate a venv, install a CUDA-compatible PyTorch build if required, then: @@ -322,7 +360,7 @@ SCENE_API_KEY=replace-with-a-random-secret If Jellyfin and this project run on the same host, keeping the API bound to `127.0.0.1` is recommended. -Start the service: +With the recommended Docker deployment the service starts automatically with `docker compose up -d`. For development outside Docker you can still run: ```bash python -m scene_search.cli serve @@ -364,7 +402,22 @@ The API also exposes authenticated Jellyfin-management endpoints used by the plu - `POST /api/jellyfin/index` — start one background indexing job for selected library ids. - `GET /api/jellyfin/index/status` — report live library/item/frame/sync progress. -Only one plugin-triggered indexing job can run at a time. Search requests return a temporary 503 while that job owns the shared embedding model. +Only one indexing job can run at a time. Search requests return a temporary 503 while that job owns the shared embedding model. + +The indexing status now includes an overall item-weighted percentage across all selected libraries. The final 1% is reserved for rebuilding Meilisearch, so the UI reaches 99% after media ingestion and 100% only when the serving index is ready. + +### Standalone web dashboard + +The API serves a lightweight management/search UI at `/`. It provides: + +- service/Meilisearch health at a glance; +- Jellyfin library selection and indexed item/frame counts; +- normal or forced indexing; +- overall progress plus current library/item/frame progress; +- final indexed/unchanged/failed/removed totals; +- semantic scene search with cached frame thumbnails. + +The page talks to the same authenticated API used by the Jellyfin plugin. The API key is never embedded into the HTML; when supplied in the page it is kept in that browser's local storage. ## Jellyfin 12 search plugin @@ -398,7 +451,7 @@ Open **Dashboard → Plugins → Scene Search** and configure: The plugin asks the Python service for the libraries visible to the configured Jellyfin API key and shows their current indexed item/frame counts. The selected library ids are saved in Jellyfin's plugin configuration, so normal operation does not require editing `.env`. -Use **Index selected libraries** to start a backend indexing job. The plugin shows the current library, item and frame progress and polls until the job completes. When ingestion finishes, the backend automatically rebuilds Meilisearch, so newly indexed vectors are searchable without a separate `sync-meili` command. +Use **Index selected libraries** to start a backend indexing job. The plugin shows an overall percentage/progress bar across all selected libraries as well as the current library, item and frame progress, and polls until the job completes. When ingestion finishes, the backend automatically rebuilds Meilisearch, so newly indexed vectors are searchable without a separate `sync-meili` command. Plugin-triggered indexing reuses the API process's existing SigLIP instance and blocks semantic searches while the indexing job owns the model, avoiding a second GPU copy on the same machine. diff --git a/docker-compose.yml b/docker-compose.yml index bab88aa..d56827a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -9,3 +9,39 @@ services: MEILI_MASTER_KEY: ${MEILI_MASTER_KEY:-change-me-now} volumes: - ./data/meili:/meili_data + + scene-search: + build: + context: . + restart: unless-stopped + env_file: + - .env + environment: + SCENE_API_HOST: 0.0.0.0 + DATA_DIR: /app/data + MEILI_URL: http://meilisearch:7700 + JELLYFIN_URL: ${JELLYFIN_DOCKER_URL:-http://host.docker.internal:8096} + HF_HOME: /app/data/huggingface + ports: + - "${SCENE_API_PORT:-8097}:${SCENE_API_PORT:-8097}" + volumes: + - ./data:/app/data + extra_hosts: + - "host.docker.internal:host-gateway" + depends_on: + - meilisearch + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: 1 + capabilities: [gpu] + healthcheck: + test: + - CMD-SHELL + - "curl -fsS http://127.0.0.1:${SCENE_API_PORT:-8097}/api/health >/dev/null || exit 1" + interval: 30s + timeout: 10s + retries: 3 + start_period: 60s diff --git a/jellyfin-plugin/Jellyfin.Plugin.SceneSearch/Configuration/configPage.html b/jellyfin-plugin/Jellyfin.Plugin.SceneSearch/Configuration/configPage.html index ddc04a3..80b7883 100644 --- a/jellyfin-plugin/Jellyfin.Plugin.SceneSearch/Configuration/configPage.html +++ b/jellyfin-plugin/Jellyfin.Plugin.SceneSearch/Configuration/configPage.html @@ -60,6 +60,13 @@ +
+
+ 0% + 0 / 0 items +
+ +
+ + +
Stored only in this browser's local storage.
+ + + + +
+
+
+

Libraries

+
+ + +
+
+
Loading…
+
+ + +
+
+ +
+

Index progress

+
+
0%
+
0 / 0 items
+
+ +
Idle
+
+
+
+ +
+

Search

+
+
+ +
+
+
+
+ + + + diff --git a/tests/test_api.py b/tests/test_api.py index 6cbca4b..db90c41 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -6,7 +6,12 @@ from unittest.mock import patch from fastapi import HTTPException -from scene_search.api import require_api_key +from scene_search.api import WEB_INDEX_PATH, require_api_key + + +class WebDashboardTests(unittest.TestCase): + def test_dashboard_asset_is_bundled(self) -> None: + self.assertTrue(WEB_INDEX_PATH.is_file()) class ApiAuthTests(unittest.TestCase): diff --git a/tests/test_index_jobs.py b/tests/test_index_jobs.py new file mode 100644 index 0000000..f22d406 --- /dev/null +++ b/tests/test_index_jobs.py @@ -0,0 +1,72 @@ +from __future__ import annotations + +import unittest +from types import SimpleNamespace + +from scene_search.index_jobs import IndexJobManager + + +class OverallIndexProgressTests(unittest.TestCase): + def make_manager(self) -> IndexJobManager: + return IndexJobManager(SimpleNamespace()) # type: ignore[arg-type] + + def test_progress_accounts_for_different_library_sizes(self) -> None: + manager = self.make_manager() + manager._state = { + "running": True, + "stage": "starting", + "library_item_totals": [2, 4], + "overall_items_total": 6, + "overall_items_completed": 0, + "overall_percent": 0.0, + } + + manager._progress( + { + "stage": "embedding", + "library_number": 2, + "library_total": 2, + "item_number": 3, + "item_total": 4, + "frames_processed": 5, + "frames_total": 10, + } + ) + + status = manager.status() + self.assertEqual(status["overall_items_completed"], 4) + self.assertAlmostEqual(status["overall_percent"], 74.2, places=1) + + def test_sync_reserves_final_percent(self) -> None: + manager = self.make_manager() + manager._state = { + "running": True, + "stage": "indexed", + "library_item_totals": [10], + "overall_items_total": 10, + } + + manager._progress({"stage": "syncing"}) + + status = manager.status() + self.assertEqual(status["overall_items_completed"], 10) + self.assertEqual(status["overall_percent"], 99.0) + + def test_complete_is_one_hundred_percent(self) -> None: + manager = self.make_manager() + manager._state = { + "running": True, + "stage": "sync", + "library_item_totals": [3, 2], + "overall_items_total": 5, + } + + manager._progress({"stage": "complete", "running": False}) + + status = manager.status() + self.assertEqual(status["overall_items_completed"], 5) + self.assertEqual(status["overall_percent"], 100.0) + + +if __name__ == "__main__": + unittest.main()