Instant XR Configuration

Setup, monitor, and analyze SpatialFin from one local hub.

The SpatialFin Companion started as a scan-to-config dashboard. It now also handles headset diagnostics, Jellyfin session collection, realtime playback analytics, and enriched watch history from the same local browser UI.

GitHub Repository Back To Main Site

QR Scan-to-Configure Realtime Analytics Diagnostics & Logs PWA Dashboard

SCAN TO CONNECT

No more XR typing Configure servers, users, API keys, and playback defaults from a real keyboard instead of an XR one.

One hub, many views Pair devices, inspect logs, and watch Jellyfin playback trends from one centralized dashboard.

Discovery

Zero-Friction Onboarding

Scan a single QR code to instantly import all your Jellyfin servers, user sessions, and preference overrides.

Diagnostics

Headset Telemetry

Turn on companion logging, inspect uploaded headset logs, and diagnose headset issues without plugging anything in.

Analytics

Jellyfin Insight

Track watch history, top users, top libraries, top items, daily trends, and realtime playback activity from a local dashboard.

Realtime

Polling + WebSockets

The companion combines Jellyfin session polling with websocket subscriptions so analytics stay current while still falling back safely.

Enrichment

Metadata Aware

Item drilldowns include poster art, overview text, runtime, genres, ratings, and series context pulled directly from Jellyfin.

Storage

Local First

Everything is stored in a local SQLite database with rolling backups, including config history, logs, analytics sessions, and metadata.

Installation

Deploy in seconds with Docker.

The SpatialFin Companion runs as a lightweight container on your home server or NAS and exposes a browser dashboard on your local network.

1. Clone The Repo

Start by downloading the companion app repository to the machine that will run Docker:

git clone https://github.com/ignacio82/SpatialFin-Companion.git

2. Open The Project

Move into the cloned folder before starting the service:

cd SpatialFin-Companion

3. Deploy Container

Use Docker Compose to start the companion app in the background:

docker compose up -d

4. Configure Hub

Navigate to http://your-ip:1982 and add your Jellyfin servers, verified users, shared preferences, diagnostics settings, and network shares.

5. Scan & Enjoy

Open SpatialFin on your XR device, go to Settings -> SpatialFin Companion, and scan the QR code displayed on your dashboard.

6. Watch Analytics Populate

Once verified Jellyfin users are saved, the companion can collect active sessions, realtime playback updates, enriched item metadata, and watch-history trends automatically.

Dashboard Surface

Much more than a QR screen.

The current companion dashboard includes onboarding, fleet preference sync, network share management, device log collection, playback session timelines, watch history, top user/library/item/server views, realtime socket health, and enriched media drilldowns.

Instant Pairing

Use a QR code and setup token to import servers, users, preferences, and companion connection state into SpatialFin.

Diagnostics

Enable remote logging from the companion, inspect per-device uploads, and download logs from the browser.

Analytics

See sessions, watch time, completion rate, daily trend charts, top users, top libraries, top items, and top servers.

Realtime Health

Inspect Jellyfin websocket connection health, reconnect status, last message time, and socket-level errors directly from the dashboard.

Technical Details

A secure, local source of truth.

The companion communicates over your local network, uses a rotating setup token for headset sync, can be protected with an admin password, and keeps its state in a local SQLite database with rolling backups.