No description
  • C# 59.2%
  • Python 17.2%
  • HTML 15.6%
  • JavaScript 7.1%
  • Shell 0.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Wayfinder release bot 3f680c8892 Release 1.0.0.2 [skip ci]
2026-11-15 01:04:53 +00:00
.forgejo/workflows Make build workflow manual-only 2026-11-11 21:54:35 -07:00
assets Finish Wayfinder display branding and document rename upgrades 2026-11-11 21:51:58 -07:00
docs Document Home Navigation's separate update identity 2026-11-14 17:43:33 -07:00
scripts Start Wayfinder builds and release versioning at 1.0.0.1 2026-11-14 17:25:11 -07:00
src Release 1.0.0.2 [skip ci] 2026-11-15 01:04:53 +00:00
tests Start Wayfinder builds and release versioning at 1.0.0.1 2026-11-14 17:25:11 -07:00
.dockerignore Document deployment and validation and add container and Forgejo builds 2026-11-10 22:49:27 -07:00
.gitignore Add behavioral tests and checksummed Jellyfin update manifest packaging 2026-11-10 22:46:19 -07:00
Directory.Build.props Finish Wayfinder display branding and document rename upgrades 2026-11-11 21:51:58 -07:00
Dockerfile.build Rebrand plugin as Wayfinder with a nautical compass thumbnail 2026-11-11 17:16:47 -07:00
global.json Initialize Jellyfin 12.4 plugin solution and implementation contract 2026-11-10 22:34:25 -07:00
manifest.json Release 1.0.0.2 [skip ci] 2026-11-15 01:04:53 +00:00
PickForMe.slnx Reduce Wayfinder row query and DTO costs 2026-11-14 16:40:02 -07:00
README.md Start Wayfinder builds and release versioning at 1.0.0.1 2026-11-14 17:25:11 -07:00

Jellyfin Wayfinder

A Jellyfin 12.4 / .NET 10 plugin for local, per-user series recommendations. Formerly Pick for Me. The catalog, dashboard, home row, and task category now use Wayfinder. The plugin GUID, HSS section ID, task keys, assemblies, API routes, configuration identity, and snapshot directory remain unchanged to preserve existing settings and history. The renamed installation folder can leave an older copy behind; see the rename upgrade instructions if both sidebar entries appear. The repository URL also remains unchanged; older release URLs/checksums are preserved.

Wayfinder windrose and wordmark

The browser and official Android mobile app display a Wayfinder row through Home Screen Sections.

Development status: the full plugin solution builds successfully with .NET SDK 10.0.113 against Jellyfin 12.4.0, with zero warnings or errors. All 26 C# behavioral tests pass. The existing recommendation row has been confirmed working on the user's server; new UI and branding changes still need live verification after updating. See validation.

How it works

  1. Import watch history snapshots existing Jellyfin episode watch state, favorites, and available last-played dates. Default schedule: daily at 02:00 server local time.
  2. Generate recommendations reads that snapshot, scores eligible series, and publishes a new result set. Default schedule: 03:00 server local time. It waits for an active import, but never imports implicitly.

Run either task manually or change its schedule in Dashboard → Scheduled Tasks → Wayfinder. The tasks run for each existing user. Failures preserve each user's previous successful snapshot and are reported in both task results and plugin settings. Generation continues for other users if one fails. No playback events, library scans, page loads, or settings saves trigger these tasks. The row reads saved results and rechecks item visibility; it makes no similarity-provider calls.

The plugin writes its own configuration and snapshots only. It does not create libraries, symlinks, duplicate media items, or modify Jellyfin watch state or media files.

Configuration

Open Dashboard → Plugins → Wayfinder. Set administrator defaults or independent user overrides. Overrides copy defaults when enabled and then remain independent.

  • History libraries: learn tastes from watched/favorited series in these libraries.
  • Recommendation libraries: recommend accessible series from these libraries.
  • Empty selections mean none. Both lists are intersected with the user's library permissions.
  • Include started series and Include fully watched series default off and are independent. Fully watched means all currently available episodes; adding episodes changes that state.
  • Choose TF-IDF (default) or weighted metadata matching. Both use normalized genres, tags, people, and studios. TF-IDF emphasizes less-common metadata.
  • Tune favorites, recency, diversity, minimum history, result count (default 20), and sorting. Highest-rated/newest-added sort only the recommendation shortlist, not the whole library.
  • Provider-assisted hybrid scoring is opt-in. It calls Jellyfin's similar-item manager using the source library's provider configuration, with cached results and serial, timed lookups. Remote providers can make network requests. Only local, eligible results appear in the row.
  • Sparse history or no usable metadata match produces a Discovery selection, ordered by community rating then date added. Discovery cards are labeled; IDs and playback remain original.

After changing history libraries, run import and then generation. Other scoring changes require generation only. Status shows which step is pending. Watch state filters are evaluated during generation, so newly watched shows may remain until the next generation; access and library filters are always reapplied when serving results.

Build and test

Install the .NET 10 SDK, Python 3, and Node.js, then:

bash scripts/check.sh

The C# test executable has 24 cases covering ranking, task independence/order, persistence, cancellation, permission changes, episode-copy deduplication, per-user failure isolation, filtering, provider opt-in/cache/timeout/fallback, damaged cache recovery, and stale settings. Python tests verify release manifests and ZIP checksums. JavaScript tests cover settings loading, zero-valued options, empty selections, and independent user overrides; the web check also validates embedded script syntax. A Forgejo workflow runs these checks when a compatible runner is configured. The CI job uses the Ubuntu 24.04 .NET 10 SDK container and installs distro Python with apt-get; the Forgejo runner must support job containers. It does not depend on setup-python having a downloadable interpreter for the runner's host OS. Node.js 22 is installed with setup-node. The first shell step installs distro Node before any JavaScript action runs: act-based Forgejo runners need node inside the job container even to execute checkout or setup-node.

For an isolated .NET build with Docker BuildKit:

docker build -f Dockerfile.build --target artifacts \
  --build-arg VERSION=0.1.0.0 --output type=local,dest=artifacts/build .
python3 -m unittest discover -s tests -p 'test_*.py' -v
python3 scripts/check_web.py
node --test tests/config_page.test.cjs

Install in Docker / TrueNAS SCALE

Open Wayfinder directly from the dashboard sidebar under Plugins to configure libraries, recommendation settings, and view task status. The plugin card also opens this page.

Start with the two library lists, result count, and tuning sliders for recent watches, favorites, variety, and the local/provider scoring mix. Sliders affect ranking within the selected libraries, not the share of results from each library. Provider suggestions remain opt-in. Advanced options contains the algorithm, history threshold, recency half-life, and provider limits/timeouts/cache lifetime. Existing settings are preserved when opening or saving the page; turning providers off retains the selected mix for later use.

The page shows loaded dependency versions, each user's selected libraries, imported history and stored recommendation counts, discovery/personalized mode, task completion times, errors, and the next task to run. Failed refreshes retain previous successful snapshots and request a retry. Registration status confirms server integration, not whether HSS is active in the browser.

Use Recommendation preview → Preview for → Load preview to inspect a user's saved results without running either task or depending on the HSS home layout. The administrator-only preview filters current library access and resolves explanation titles from currently accessible history libraries. Older snapshots may show generic explanations until regenerated. Scores are ranking values, not probabilities. Save settings first; stale results are explicitly marked. Further improvements are tracked in the roadmap.

First validate against a separate Jellyfin 12.4 instance as described in the validation guide. Use a persistent mount for Jellyfin's /config; the container must be able to write it.

  1. Build and package the plugin, then extract the ZIP into /config/plugins/Wayfinder_0.1.0.0/ while Jellyfin is stopped. Include both DLLs, meta.json, and wayfinder.png, not Jellyfin's own assemblies.
  2. Restart Jellyfin. Confirm Wayfinder and its two tasks are listed.
  3. Configure libraries and run import followed by generation.
  4. Install compatible Home Screen Sections, File Transformation, and Plugin Pages from the maintainer's repository: https://www.iamparadox.dev/jellyfin/plugins/manifest.json. The initial compatibility matrix is HSS 3.0.4.0, File Transformation 3.0.3.0, Plugin Pages 3.0.3.0, each with a 12.4 build.
  5. Restart, open Modular Home settings, enable its layout, and select Wayfinder along with Continue Watching, Next Up, and the other rows you want. HSS replaces the home layout.
  6. Refresh the browser/app's cached web assets. Android may retain the old layout until its cache expires. If registration failed, settings show a diagnostic; restart after fixing dependencies.

Settings are in Jellyfin's plugin configuration directory. Snapshots are under IApplicationPaths.DataPath/pick-for-me/ (normally inside the persistent /config tree). Snapshots contain viewing preferences; back them up with Jellyfin's configuration. Removing a user stops processing them but does not automatically erase their old plugin snapshot directory.

Repository and updates

Successful Actions runs provide a wayfinder-build artifact containing the installable plugin ZIP, a matching candidate manifest.json, and installation notes. Extract the downloaded artifact wrapper first; the inner wayfinder-<version>.zip is the release asset. For an unpublished version, upload that inner ZIP and commit its accompanying manifest so checksums match. The workflow runs only when started manually; pushes and pull requests do not trigger it. Manual builds with publishing unchecked do not publish releases or change the tracked manifest. Never replace an already published version with a CI rebuild; increment the project version for updates.

To publish automatically, open Actions → Build and test → Run workflow, select main, check Increment the version and publish a release, and run it. Leaving the checkbox off only builds and uploads artifacts. The checked run chooses a version newer than the project, catalog, and existing version tags. It increments the lowest of four components first: 1.0.0.0 → 1.0.0.1, 1.0.0.20 → 1.0.1.0, 1.0.20.20 → 1.1.0.0, and 1.20.20.20 → 2.0.0.0. The lower three components roll over after 20.

After checks pass, the workflow commits the project version and generated catalog manifest, reserves the release tag, uploads the ZIP and matching manifest.json to a draft release, publishes it, and pushes the manifest commit to main. The same files are available in the wayfinder-release build artifact. Jellyfin continues using the raw repository URL below; the manifest beside the release ZIP is also provided for download. Pull main after a release to get the automated commit before making further changes.

Publishing uses the workflow's automatic repository token. Repository branch/tag protection must permit that token to push. A stale run or conflicting tag fails rather than overwriting changes. If an upload fails, inspect the reserved tag/draft before retrying; a new run skips reserved versions. If the final push fails because main advanced, the release is already published: merge/cherry-pick its tagged manifest/version commit onto main to advertise it.

After pushing this repository's main branch, use this raw repository URL in Jellyfin:

https://git.blusnake.net/blusnake/jellyfin-pick-for-me/raw/branch/main/manifest.json

New release ZIPs use wayfinder-<version>.zip. Older Pick for Me releases retain their original filenames and checksums. Publish the next version through the workflow above to ship the rename. The ZIP must match the manifest checksum; do not substitute a separately rebuilt archive. The URL must be readable by your Jellyfin server; a private Forgejo repository may require a separately hosted manifest and release assets. That remote URL has not been tested here.

For subsequent releases, use a new version:

bash scripts/release.sh 0.1.1.0 'Describe the changes'

This builds with the supplied assembly version, runs checks, creates artifacts/wayfinder-0.1.1.0.zip, and updates manifest.json with its actual checksum, target ABI, timestamp, and release URL. It does not push or publish. Packaging checks the generated build-info.json against the requested release version and ABI, and rejects versions older than an existing release. Keep that build marker beside the DLLs; it is not included in the installable ZIP.

Create the matching tag/release (for example v0.1.1.0) on Forgejo and upload that exact ZIP. Once the asset is available, commit and push the updated manifest. Publish increasing four-part versions; do not replace released ZIPs. With the repository configured and plugin auto-updates enabled, Jellyfin can discover those updates. For container-built DLLs, run scripts/package.py with --build-dir artifacts/build --version ... --changelog ... after the other checks.

API and dependency boundary

  • GET /PickForMe/Recommendations: authenticated current user's original Jellyfin item DTOs. No user-ID override. Server API keys without a user identity cannot read personalized results.
  • GET/PUT /PickForMe/Configuration, GET /PickForMe/Setup, GET /PickForMe/Status: administrator authorization required. Settings updates are validated server-side.
  • Home Screen Sections uses a small reflection adapter, not a compile-time dependency. Its callback validates the authenticated identity against the supplied user ID. Background tasks and the API continue working if HSS is unavailable.

HSS itself also controls caching and other rows. Its own cross-user behavior must be tested; our callback is not a patch for vulnerabilities elsewhere in HSS. Do not enable an unverified HSS build for multiple untrusted accounts.

Development-session Git recovery instructions are in docs/GIT-RECOVERY.md.

See home navigation implementation and acceptance for the Wayfinder row optimizations and separate, locally tested HSS patch candidate.

Builds now start at 1.0.0.1. The manual release workflow uses that unpublished candidate for the first 1.x release, then increments to 1.0.0.2 and onward using the existing carry rules. Published 0.x manifest entries remain intact. Build-only runs produce a candidate package; enable publish_release to publish and update the catalog.