---

📑 Table of contents

• Overview
• Features - release highlights, ratings, external sync, TV/webOS, views, social, admin
• Screenshots
• Requirements
• Installation
• How to use - rating controls, My Ratings, external sync, native mirroring
• API Reference - ratings, watchlist, diary, lists, Letterboxd, config
• Data storage
• Building from source
• Contributing
• Changelog - release notes from 1.8.0 back to 1.4
• Support the project
• License

---

Overview

StarTrack started as a simple star-rating plugin and has grown into a full Letterboxd-style social layer for Jellyfin: ratings, reviews, watchlists, liked films, a chronological diary with rewatches, Top 4 favourites, collaborative lists, recommendations, server-wide watchlist sharing, two-way Letterboxd and Serializd sync, and optional Trakt, Simkl and Yamtrack workflows. Ratings can also mirror into Jellyfin's native per-user rating field for use with Jellyfin filters and backups. Everything is stored as plain JSON on your own server; external services are contacted only when you explicitly configure and connect them.

Designed to integrate cleanly with modern Jellyfin setups: desktop, mobile, TV/webOS remote navigation, and reverse proxies that serve Jellyfin from a BaseURL sub-path.

---

Features

🆕 New in 1.8.1

A fix release for 1.8.0, almost all of it reported by users of it.

Jellyfin 12.1

• StarTrack appears in the new top bar. 12.1 moved navigation into a Material-UI app bar and the old nav drawer is not in that layout, so the My Ratings link had nowhere to go. It now sits in the toolbar beside your libraries (#27).

Fixes

• Opening a film from My Ratings no longer freezes page scrolling. Six code paths closed the overlay and only one of them released the scroll lock, so clicking a film could leave the whole Jellyfin web UI unscrollable until you reloaded (#27).
• Back closes My Ratings instead of navigating the page behind it while the overlay stays on screen (#27).
• Half stars are half. The filled half of a half-star was cut past the middle of the glyph (#27).
• "Out of ten" now applies to your own ratings too, not only community averages — the panel, the recent list, My Ratings cards, the diary and the comparison view all honour it (#27).
• Letterboxd "Verify login" works the way a push does. It never used FlareSolverr, so a correctly configured server still failed it; and a stale pasted cookie was used forever and never questioned, which is worse than no cookie at all. It now retries without your cookies and on a freshly solved challenge, and says what actually fixes a Cloudflare block instead of asking you to paste more cookies (#24).
• The self-check stopped calling healthy servers broken. "Injected into the web UI" reported a failure for a read-only index.html — the normal state in Docker — when the server was injecting perfectly well by its other route (#20).
• A duplicate copy of a film in your library no longer gets a second rating when an import runs; the copy you already rated is the one that is updated.

New

• StarTrack tells you when your browser is running an old copy of it. If your browser has Jellyfin's page cached, a plugin update changes nothing for you — silently, for as long as the cache lives. One dismissible line now says so, with a Reload button. It never reloads on its own (#20).
• A ★ My Ratings button in the rating panel, so you can reach your profile without the sidebar (#28).
• Remove from watchlist straight from the watchlist, instead of opening the film to do it (#28).

⭐ Ratings & reviews

• Half-star ratings (0.5 – 5★) per item, per user
• Rate movies, series, seasons and episodes - seasons were added in 1.7.0 and behave like any other item: panel, badge, Top 4 slot and type tab
• Written reviews with an admin-configurable limit from 1 to 10,000 characters
• Canonical community badge displayed once on each detail page; click it to open the rating panel
• Compact badge mode - show only the rating while keeping the full StarTrack label and count in the tooltip
• Per-user breakdown - expandable list of every user's score and review on the detail panel
• Star tier colours - five visual tiers (5★ glowing gold → 1★ muted red) so the rating grid is scannable at a glance
• Optional native mirror - write StarTrack's 0.5–5★ value into Jellyfin's 0–10 per-user rating field, clear it when the StarTrack rating is removed, and backfill older ratings from the admin page
• How ratings are shown - an admin choice of stars only (3.5, the default), both (3.5 (7/10)) or out of ten (7/10). It applies to every rating StarTrack prints, community averages and your own: the panel, the floating pill, poster badges, the recent list, My Ratings cards, the diary and the taste comparison. Display only - you still rate with five stars, nothing is converted, and a rating always lands on a real position of the scale (so /10 shows 7, never 7.0)

📺 Media-page, TV & reverse-proxy compatibility

• Three ways into My Ratings, because Jellyfin's chrome keeps changing: the sidebar entry on the classic layout, a ★ My Ratings link in the top bar on Jellyfin 12.1 (whose Material-UI app bar has no nav drawer), and a ★ My Ratings button in the rating panel itself, which works on every layout
• Duplicate-resistant media badge - reconciles Jellyfin SPA navigation, cached DOM clones and delayed native-rating nodes so only the current page owns a StarTrack badge
• TV/webOS controls - the media badge, Rate pill, post-playback prompt and whole-star targets support D-pad focus plus OK/Enter activation
• Unrated TV target - a dimmed ☆ Rate badge remains available on TV so remote users always have a focusable way to rate
• Flexible sizing - Normal, Large and Large (TV only) admin defaults with a per-device override in My Ratings → ⚙ Preferences
• BaseURL-aware routing - widget assets, StarTrack endpoints and native Jellyfin item/poster/avatar requests work below reverse-proxy paths such as /jelly
• It tells you when your browser is running an old copy of it - if your browser has Jellyfin's page cached, a plugin update changes nothing for you, silently, for as long as that cache lives. StarTrack compares the version it was loaded with against the version the server would serve and shows one dismissible line with a Reload button. It never reloads on its own, and says nothing unless it is certain

🎞 Letterboxd-parity views

📖 Diary

• Automatic logging on playback - finishing something records it, server-side, so every client counts and not just the web UI. Anything under two minutes (pre-rolls, idents, trailers) is not a viewing
• Log a watch - a dated "log this" control on the rating panel, so a diary is something you build in Jellyfin rather than only import
• Rewatch detection - logging something you have already watched is recorded as a rewatch without you saying so
• One viewing, one row - a film logged by playback and later rated (in StarTrack, on Letterboxd, or from a ZIP) keeps one entry with the score on it; a rating from any source fills an unrated row
• Imports with dates - Letterboxd's diary (via Sync everything or the export ZIP) and Serializd's diary come in with their original dates, rewatches and likes
• Grouped by month with visual star bars, and pushed back to Letterboxd as dated entries if you turn on diary logging there

⭐ Top 4 favourites (per type)

• Pin up to 4 movies, 4 series, 4 seasons and 4 episodes to your profile
• Sub-rows shown in the type tab they belong to (Movies tab → Top 4 Movies, etc)
• Empty slots show a clear "+ pin a film" placeholder so the feature is discoverable
• Hover any pinned slot to reveal an × remove button
• Hover any film card to reveal ⭐ pin to Top 4 and + add to a list buttons
• On your own watchlist, hovering also reveals ✕ remove from watchlist, so taking something off the list no longer means opening the film

🔄 Letterboxd integration

Two-way as of 1.7.0. Import has always worked from a username alone. Sending ratings back is new, and comes in two flavours because Letterboxd has no public write API:

The CSV route is offered first and is what most people should use. Automatic push is opt-in, hidden behind a checkbox, and states plainly that it stores your Letterboxd password so it can sign in as you. If your account has two-factor authentication, only the CSV route is possible - StarTrack cannot complete a second factor unattended, and says so rather than failing mysteriously.

• Push ratings, watched status and likes - ratings and watched marks use Letterboxd's idempotent endpoints, so re-running is harmless and changing a rating updates it in place
• Optional diary logging - writes dated diary entries for films you rate from the moment you switch it on. It deliberately does not backfill: your existing diary is left completely alone, because StarTrack has no way to tell an existing entry apart from a new one and would otherwise duplicate years of history
• Verify login button tells you immediately whether the password and any Cloudflare cookies work, instead of failing silently an hour later
• ⟳ Sync everything - imports your entire Letterboxd history live, no file needed: every rating (including films you rated but never logged, placed in the order you rated them), every diary entry with its date, then watchlist, likes and Top 4. Safe to run again - unchanged ratings are left alone, dates included. Admins can run it for any linked user. Needs FlareSolverr
• Drop in your Letterboxd export ZIP to import everything in one pass: ratings.csv, diary.csv, watchlist.csv and likes/films.csv - the offline equivalent
• Sync now button pulls your latest diary entries (RSS, the last ~50), your watchlist (the watchlist page - Letterboxd removed the RSS feed for it) and your likes - one click, three data types
• Hourly auto-sync scheduled task for every user with a Letterboxd username configured
• Import Top 4 button reads your Letterboxd profile's "favourite films" section, year included, so "Heat" is the right Heat
• Imports never overwrite what they do not carry - a review you wrote here, or the date you rated something, survives every import; a like is dated by the viewing it belongs to, not the moment of import; a library with two copies of a film gets the rating on the copy you already rated

Cloudflare, and FlareSolverr

Letterboxd puts a Cloudflare JavaScript challenge in front of most of what StarTrack needs: the likes page, the profile page (Top 4), the ratings and diary pages that Sync everything reads, and the sign-in used for automatic push. No server can pass a JavaScript challenge on its own, and no header makes it go away. The diary RSS feed and the watchlist page are not affected, so Sync now keeps working without help.

Without help, StarTrack notices the challenge, stops asking for six hours instead of hammering Letterboxd every few minutes, and says so in the Letterboxd panel.

With help, both work. FlareSolverr is a small self-hosted container that solves the challenge in a real headless browser - the same tool Prowlarr, Jackett and Sonarr use for the same wall, so if you run those you already have one. Put its URL in Dashboard → Plugins → StarTrack → FlareSolverr URL, and:

• Reading works. Likes sync, Top 4 import and Sync everything go through FlareSolverr wherever it runs, because those pages are fetched by its browser.
• Signing in is different, and worth being plain about. For sign-in there is no page to hand over - StarTrack has to post your credentials itself, using the clearance cookie FlareSolverr earned. Cloudflare ties a clearance to the browser that earned it: its IP, its User-Agent and its TLS handshake. Our HTTP client matches none of those, so a borrowed clearance is often refused however it was obtained. Measured against live Letterboxd: sign-in sometimes goes straight through with no cookie at all, and sometimes fails with a freshly solved one.

Verify login tries all of this for you in order - as configured, then without any cookies you pasted, then on a freshly solved challenge - and only retries a Cloudflare block, never a rejected password. If it still fails, that is Cloudflare refusing the server, not something you did.

So if you want to send ratings back, use "Download CSV for letterboxd.com/import". No password, no cookies, nothing to expire, and it is the only route that works for accounts with two-factor authentication. Automatic push remains available and works when Cloudflare lets it, but it is the fragile half by nature, not by oversight.

Pasting a cf_clearance cookie and User-Agent from your browser still works as a stopgap and still takes priority if set - but a stale paste is worse than none, because Cloudflare reads a bad clearance as a signal in itself. If sign-in has stopped working, clear those two boxes before you try anything else.

• Export CSV - download your StarTrack ratings in Letterboxd-compatible format for backup or migration
• Diagnose button - runs the library matcher and shows you exactly how many movies are indexed, how many duplicates exist, and how titles are normalised
• Clean dead ratings button - removes ratings that point to library items whose underlying file no longer exists (post-HDD-failure cleanup)

📺 Serializd integration

Letterboxd does not do television and Serializd does not do film, so the two together cover a whole library.

Importing needs only a username. Your Serializd diary is public, so StarTrack reads it straight out - no password, no token, nothing stored. Pushing is the half that needs credentials, exactly as with Letterboxd.

• Seasons are the point. A season is Serializd's native unit the way a film is Letterboxd's, and roughly two thirds of a real diary is season entries. StarTrack grew season ratings to match, so nothing is dropped in either direction
• Ratings, and reviews if you want them. Serializd only keeps review text on a log entry, so a rating carrying a review is sent as a log; a bare rating stays a rating and creates no diary noise
• Newest wins on import - a rewatched season appears in the diary more than once, and StarTrack keeps the most recent opinion rather than whichever entry happened to arrive last
• Watch logs with no rating are skipped rather than imported as zero stars, which would invent a rating you never gave
• Specials are left out - Serializd numbers season 0 differently, and filing an episode under the wrong season is worse than not filing it
• Known limitation: the import reads your Serializd diary, which lists entries you logged. A rating you gave on Serializd without logging it is stored as a plain rating and does not appear there, so StarTrack cannot import it. Everything StarTrack pushes is unaffected — that direction writes ratings directly
• Verify login button tells you immediately whether the password works
• Skip-if-unchanged, so an hourly push over a settled library costs one sign-in and no writes at all

Season ratings stay between StarTrack and Serializd. Trakt, Simkl, Yamtrack and Letterboxd have no concept of rating a season, so seasons are deliberately withheld from them rather than filed as a show or, worse, a film.

⇄ External service sync

• Trakt and Simkl authentication - users connect with Trakt's device code or Simkl's PIN after an admin configures the server-wide app credentials
• Per-service direction - Off / Export only / Import only / Two-way, with newer-wins conflict resolution and an automatic ten-minute scheduled sync
• Trakt history and likes - rated movies and episodes can be marked watched; liked items are pushed to a StarTrack Liked list and, for VIP accounts, Trakt Favorites
• Backfill watched history - seed Trakt or Simkl from existing Jellyfin played state; Simkl preserves the original watched/rated dates
• Yamtrack workflow - export an IMDb-compatible CSV for Yamtrack → Import → IMDb while native provider support remains experimental
• IMDb ratings import - drop your imdb.com ratings export into Import file; the format is detected automatically and 1–10 maps exactly onto half-stars
• Portable import/export - authenticated CSV/JSON endpoints plus Letterboxd- and IMDb-compatible export formats; the IMDb/Yamtrack export says how many episodes and id-less items it had to leave out instead of handing back a quietly shorter file
• Daily server backup - optional scheduled CSV or JSON exports for every user with ratings, written at 03:00 UTC

🔍 Search & filter

• Live search input in the topbar - filters the active view by title with a 150 ms debounce
• Discrete star filter dropdown - 5★ only, 4.5★ only, 4★ only … down to 0.5★ only
• Sort dropdown - date rated, film year, your rating, community rating, runtime, each ↑↓
• Type tabs - All / Movies / TV Shows / Seasons / Episodes - drives both the grid and which Top 4 row is visible

👥 Collaborative & social

• Members directory - searchable profile cards with avatars, rating totals, average scores and each member's pinned Top 4
• Detailed profiles - histograms, favourite genres/people/decades, hours watched, monthly activity, calendar heatmap, on-this-day and most-rewatched views
• Follow graph and activity feed - follow members and filter recent ratings, reviews and diary activity between followed users and everyone
• Taste comparison - compare two members with a Pearson-based similarity score, rating histograms, disagreements and shared favourites
• Server-enforced privacy - hide a profile, followers/following, statistics or recent activity; private lists remain owner-only
• Everyone's watchlist view - see what every user on your server wants to watch, sorted by most-wanted first, with a per-user filter dropdown to focus on a specific user
• Collaborative lists - owner can mark a list as collaborative and other users can add their own picks. Each item tracks who added it
• Reviews feed - see what everyone on the server thinks
• Per-user attribution on community averages so you know who rated what

🛠 Admin & infrastructure

• Runs on Jellyfin 10.11, 12.0 and 12.1 from one codebase, as two builds; the plugin repository picks the right one - see Which build do I need?
• "Is StarTrack working?" - a self-check on the plugin page: eight checks, server and browser side, with a paste-ready summary for bug reports. It names which route the script reaches the browser by (written into index.html, or added to each page as it is served - the normal one for Docker, where index.html is read-only), and flags a stale cached widget and a FlareSolverr behind a VPN
• Presentation controls - badge position and size, compact media badge, poster overlays, native/Media Bar replacement and post-playback prompts
• Native Jellyfin integration - opt-in live mirroring plus an elevation-gated, idempotent backfill for existing StarTrack ratings
• Review policy - choose a maximum review length between 1 and 10,000 characters
• External service credentials - configure Trakt and Simkl once while each user owns their connection and sync direction
• Automatic backups - the optional AutoExportDaily task writes CSV or JSON snapshots under <jellyfin-data>/data/InternalRating/exports/
• Per-rating cleanup - purge a single rating without nuking the whole profile
• Multi-rating cleanup - purge every rating that points to a missing library file
• Eight-language UI - English, French, Spanish, German, Italian, Portuguese, Chinese and Japanese across the widget, user preferences and admin settings
• BaseURL and cache-safe injection - supports reverse-proxy sub-paths and refreshes the widget asset token after plugin updates
• Standalone WebView shell - authenticated mobile, TV, kiosk and third-party clients can host the complete My Ratings overlay without rendering Jellyfin's surrounding web UI
• Mobile-responsive UI - full @media query overhaul for phones and tablets
• Client-side metadata cache - switching between views is instant after the first load
• MIT licensed - fork it, modify it, self-host it, bundle it
• Pure JSON storage - no database. Just files in <jellyfin-data>/data/InternalRating/

---

📸 Screenshots

Rating pill (detail pages)

A small floating pill appears at the bottom-right of every Movie / Series / Episode detail page. The canonical StarTrack badge beside Jellyfin's native ratings opens the same panel. Both are keyboard- and TV-remote accessible, and their size can be adjusted for large displays.

Rating panel

Half-star precision, optional written review, community average with per-user breakdown, one-click heart / watchlist / Top 4 pin. "Show all ratings" expands every user's score.

Recent ratings + Letterboxd sync

The pill also shows your recent ratings at a glance. One tap opens the Letterboxd sync panel - enter your username, enable hourly auto-sync, or drop in your export ZIP.

Sidebar entry

Auto-injected into the Jellyfin nav menu - no theme changes required.

Main view + type tabs

Seven top-level views - Media / Watchlist / Liked / Diary / Reviews / For You / Lists - and five type tabs on the Media view: All / Movies / TV Shows / Episodes / Anime. Anime is detected via genre or tag, so a movie or series can count as anime regardless of its underlying Jellyfin type.

Stats, sort, search, Letterboxd + export

Live search with a 150 ms debounce, seven sort options (date rated, film year, your rating, community rating, runtime - each ↑↓), one-click Letterboxd settings pane, and CSV export in Letterboxd-compatible format.

Bringing ratings in. My Ratings → ⇄ External Sync → ⇧ Import file takes a StarTrack CSV or JSON export, a Letterboxd export, or an IMDb ratings export (imdb.com → Your Ratings → Export). The format is detected from the file — there is nothing to choose. IMDb's 1–10 maps exactly onto StarTrack's 0.5–5 stars, the same ten positions, so nothing is rounded.

Sending ratings out. CSV (Letterboxd-compatible), JSON, and an IMDb-format CSV for Yamtrack's Import → IMDb. That last format cannot carry episodes, or anything your library has no IMDb id for — StarTrack now tells you how many rows that was, rather than handing back a quietly shorter file.

Top 4 Movies + full poster grid

Pinned Top 4 sits above the full grid, full-poster cards with a star tier ribbon, year and runtime overlay. Hover any card to reveal Pin / Add to list buttons.

Top 4 Movies (detail)

Per-type Top 4: 4 movies, 4 series, 4 episodes, max 12 total. Each pinned slot shows its rank, star tier, year and runtime, and hovering reveals an × remove button.

Reviews feed

Server-wide vertical feed of every rating that has a written review, with poster, reviewer, star bar, date and review text. (Reviewer name and review text blurred in this screenshot.)

Letterboxd sync

Letterboxd-compatible sync pane: username input, hourly auto-sync toggle, one-click Sync Now (pulls RSS ratings + watchlist + likes scrape), ZIP drop zone for full exports, Import Top 4 from your public profile, Diagnose button for matcher diagnostics, and Clean dead ratings to purge zombie entries after a library rebuild.

---

Where StarTrack works

StarTrack adds itself to Jellyfin's web interface by injecting a script into it. That means it appears anywhere you use Jellyfin in a browser:

The native apps do not load Jellyfin's web interface, so there is nothing for StarTrack to attach to and no plugin can change that. Your ratings are still recorded server-side, so anything you rate in a browser is visible to everyone and counts everywhere — you just cannot rate from those apps.

Requirements

• Jellyfin 10.11.x or 12.x — see Which build do I need? below
• A modern browser (Chromium / Firefox / Safari)
• TV/webOS clients are supported through focusable D-pad controls; exact focus styling can vary by client theme
• Reverse proxies may use Jellyfin's BaseURL setting (for example /jelly); StarTrack applies it to injected assets, plugin APIs and native Jellyfin media requests
• For Letterboxd auto-sync: a Letterboxd account with public profile, watchlist and likes pages
• For Trakt or Simkl sync: an admin-created OAuth application for the selected service

StarTrack uses ASP.NET Core middleware to inject its widget at runtime. No File Transformation plugin required.

---

Installation

Option A - Plugin Repository (recommended)

1. Jellyfin → Dashboard → Plugins → Repositories → +
2. Add:

   https://raw.githubusercontent.com/ZL154/jellyfin-plugin-startrack/main/manifest.json
   

3. Go to Catalogue, find StarTrack, install it, and restart Jellyfin.

Option B - Manual

1. Download the ZIP matching your Jellyfin version from Releases — see the table below
2. Extract the DLL into your Jellyfin plugins folder:

   <jellyfin-data>/plugins/StarTrack/Jellyfin.Plugin.InternalRating.dll
   

3. Restart Jellyfin.

Which build do I need?

Jellyfin 12 moved to .NET 10, so one DLL cannot serve both server generations. StarTrack ships two, built from the same source:

Installing from the repository? Ignore all of this — the catalogue only offers your server the build it can run. This matters only for manual installs.

The two differ only in which Jellyfin they are compiled against. Features, settings and your data are identical, and upgrading your server from 10.11 to 12 needs nothing more than letting the catalogue update the plugin.

⚠️ If you install the wrong one, it fails silently. Jellyfin logs nothing, the plugin simply does not appear and /Plugins/StarTrack/Debug returns 404. If StarTrack has "vanished" after a manual install, check the last digit first.

And installing the right one afterwards is not enough on its own. Jellyfin marks the plugin NotSupported the moment it fails to load the wrong build, and that mark survives the swap — the correct DLL is then skipped as "disabled" at every start. After replacing the DLL, open Dashboard → Plugins, find StarTrack, and Enable it (or set "status": "Active" in its meta.json), then restart. The self-check below calls this out: no answer at all from the plugin, on a manual install, is almost always this.

Verify

Dashboard → Plugins → StarTrack → "Is StarTrack working?" → Run self-check.

It checks eight things — five on the server, three that only your browser can answer — and tells you which one is failing:

• plugin loaded, and whether this build matches your server
• the widget script is reachable, and injected into the web UI
• your reverse-proxy base path, if you have one
• the <script> tag is actually in the page's HTML
• the widget then executed (if the tag is there but it didn't run, something is blocking it)
• your browser is running the current widget, not a cached older one

If nothing at all appears, that answer is itself the diagnosis: the plugin is installed but not running. On a manual install that nearly always means the downloaded build doesn't match your Jellyfin version — see Which build do I need?.

The panel also produces a paste-ready summary for bug reports.

Then open any Movie, TV Show, or Episode detail page: the ☆ Rate pill and one StarTrack badge should appear, and clicking either should open the rating panel.

---

How to use

Rating controls (detail page)

A floating pill appears at the bottom-right of every Movie / Series / Season / Episode detail page. StarTrack also places one clickable badge alongside Jellyfin's native ratings. Click either control - or focus it with a keyboard/TV D-pad and press Enter/OK - to:

• Set your rating (half-star precision)
• Optionally write a review
• See the community average and per-user breakdown
• One-click ❤ like, ☆ watchlist, or ★ pin to Top 4

Admins can use a compact rating-only badge, move poster badges to any corner and choose Normal, Large or Large (TV only) sizing. Users can override the size for their current device from My Ratings → ⚙ Preferences. On TV, unrated media keeps a dimmed ☆ Rate badge so the remote always has a focus target.

My Ratings overlay

Open it from My Ratings in the Jellyfin sidebar, from the ★ My Ratings link in the top bar (Jellyfin 12.1), or from the ★ My Ratings button in any rating panel. Esc or the browser's Back button closes it. The view selector at the top has seven tabs:

• ★ Films - your full rating grid + pinned Top 4 row
• ☆ Watchlist - your watchlist, with a toggle to view everyone's combined watchlist filtered by user
• ♡ Liked - every film you've hearted
• 📖 Diary - chronological journal with rewatches and visual star bars
• ✍ Reviews - server-wide review feed
• ✨ For you - personalised recommendations
• 📃 Lists - your and others' collaborative lists

Each view supports search, sort, star filter (where applicable) and a type filter: All / Movies / TV Shows / Seasons / Episodes / Anime. Hovering a card reveals its actions - pin to Top 4, add to a list, and on your own watchlist, remove from it.

Letterboxd sync

1. In StarTrack, click the ⚙ Letterboxd button in the topbar (or My Ratings → ⚙ Preferences → Connected accounts)
2. Enter your Letterboxd username, optionally enable hourly auto-sync, save
3. Click ⟳ Sync everything to import your whole history - ratings, diary, watchlist, likes and Top 4 - in one go. This needs a FlareSolverr configured by your admin
4. No FlareSolverr? Export your data from letterboxd.com → Settings → Import & Export → Export Your Data and drop the ZIP into the upload box - the same import, offline
5. Click Sync now any time to pull your latest diary entries + watchlist + likes; hourly auto-sync does the same on its own
6. To send ratings back, use Download CSV for letterboxd.com/import (no password) or turn on automatic push

Is StarTrack working?

Dashboard → Plugins → StarTrack → Is StarTrack working? runs eight checks - plugin loaded, script injected, widget executed, token fresh, FlareSolverr reachable and on the same IP as Jellyfin, and so on - and gives you a summary to paste into a bug report. If the page itself returns 404, the plugin is installed but not running, which almost always means the wrong build for your Jellyfin version.

Serializd sync

Serializd covers television; Letterboxd covers film. The two halves have different requirements on purpose.

To import (no password):

1. In My Ratings, click the ⚙ Serializd button in the topbar
2. Type your Serializd username and tick Import my diary hourly
3. Click Save, then Sync now

That is all importing needs - your diary is a public page, so StarTrack just reads it. Nothing is stored beyond the username.

To also push your ratings out: 4. Tick Also push my TV ratings to Serializd, which reveals the credential box 5. Enter your Serializd email and password, click Verify login to check them, then Save 6. Click Push now, or leave it to the hourly task

Choose which kinds to push with the Series / Season / Episode ratings toggles. Include written reviews is off by default: Serializd only keeps review text on a log entry, so a rating carrying a review is sent as a log rather than a bare rating.

Serializd has no public API tokens, so pushing genuinely requires the account password. It is encrypted at rest with the same key ring as the Letterboxd credential and is never returned by any endpoint. If you would rather not store one, use import only - it loses nothing except the outbound direction.

External sync (Trakt / Simkl / Yamtrack)

1. Admin (one-time): Dashboard → Plugins → StarTrack - paste a Trakt client ID + secret and/or a Simkl client ID (create a free app on each service's developer page). This is server-wide; users don't need their own keys.
2. In My Ratings, open the ⇄ External Sync panel.
3. Connect a service:
   • Trakt - click connect, you'll get a code to enter at trakt.tv/activate.
   • Simkl - click connect and approve the PIN.
4. Choose a direction for that service: Off / Export only / Import only / Two-way.
5. Click Sync (or just wait - it auto-syncs every 10 minutes). In two-way mode the newer rating wins on each side.
6. Backfill (optional) seeds the service from your whole library in one pass, and marks rated items watched.
7. Yamtrack: click ⇩ Yamtrack CSV to download an IMDb-format file, then in Yamtrack go to Import → IMDb and upload it. (Yamtrack has no public rating API yet - see notes above.)

Ratings only import for items that exist in your Jellyfin library; titles you rated on a service but don't own can't be matched.

Native ratings, review limits and automatic backups

Open Dashboard → Plugins → StarTrack to configure the server-wide controls:

1. Enable Also save ratings to Jellyfin's native rating field to mirror future StarTrack ratings from 0.5–5★ into Jellyfin's 0–10 per-user field. Removing the StarTrack rating clears its mirrored native value.
2. Use Backfill existing ratings → Backfill now to copy older ratings. The admin-only operation is idempotent, so it is safe to rerun.
3. Set Maximum review length anywhere from 1 to 10,000 characters.
4. For automatic backups, set AutoExportDaily to true and AutoExportFormat to csv or json in the plugin configuration. The v1.6.4 visual admin form does not expose these two advanced fields yet. The task runs at 03:00 UTC and writes to <jellyfin-data>/data/InternalRating/exports/.
5. Configure Trakt/Simkl app credentials once; users connect their own accounts and choose their own sync direction.

If Jellyfin is hosted below a reverse-proxy path, set Jellyfin's normal BaseURL. StarTrack automatically uses that prefix; no separate StarTrack path setting is required.

---

API Reference

All endpoints are under /Plugins/StarTrack/. Every endpoint requires Jellyfin authentication unless otherwise noted.

Ratings

Watchlist / liked / favourites

Diary

Lists

Letterboxd sync

Serializd sync (new in 1.7)

External sync (new in 1.6)

All under /Plugins/StarTrack/ExternalSync/. {provider} is trakt, simkl, or yamtrack.

Members & social (new in 1.5)

Config & translations (new in 1.4)

Misc

---

Data storage

All data is stored as plain JSON in <jellyfin-data>/data/InternalRating/:

Back them up or migrate them like any other data file - no database required. Native-rating mirroring supplements these files; StarTrack's JSON remains the source of truth.

---

Building from source

git clone https://github.com/ZL154/jellyfin-plugin-startrack.git
cd jellyfin-plugin-startrack/InternalRatingSystem
dotnet publish -c Release -o ./publish_out

The compiled DLL is at publish_out/Jellyfin.Plugin.InternalRating.dll.

Version note: The plugin must be compiled against the Jellyfin.Controller NuGet package version that exactly matches your server. The csproj currently targets 10.11.6. Update <PackageReference> if your server version differs.

---

Contributing

Issues and pull requests are welcome.

• Report a bug
• Suggest a feature

---

Changelog

What is new in the current release stays at the top of Features; everything it describes is also folded into the feature sections above, so those read as a description of StarTrack today. Older release notes live here.

New in 1.8.0

Jellyfin 12. StarTrack now runs on Jellyfin 12 and on 10.11, from one codebase, as two builds - see Which build do I need?. Installing from the repository picks the right one for you.

Letterboxd, repaired

• ⟳ Sync everything - one button that imports your entire Letterboxd history: every rating (including films you rated but never logged - "watched, not sure when"), every diary entry with its date, then watchlist, likes and Top 4. The RSS feed only ever carried your last ~50 diary entries, which is why a member with 800 ratings on Letterboxd could have 369 here. This is the export ZIP, live, and it needs no file. Films you rated but never logged are placed in the order you rated them on Letterboxd, so My Ratings still reads newest-first instead of dumping them all on today. Safe to run again: unchanged ratings are left alone, dates included. Admins can run it for any linked user from the plugin page. If a page cannot be read, the result says so instead of passing off part of your profile as all of it. Needs FlareSolverr, because the diary and ratings pages are challenged.
• Watchlist sync works again - Letterboxd removed the watchlist RSS feed, which is why it had silently stopped. StarTrack now reads your watchlist page instead, every page of it.
• Import Top 4 works again, with FlareSolverr - same cause as likes: the profile page is challenged. It also reads the year now, so "Heat" is the right Heat.
• Likes sync works again, with FlareSolverr - Letterboxd puts a Cloudflare challenge in front of the likes page and the sign-in. Point StarTrack at a FlareSolverr and both get through; without one, it backs off politely and tells you in the panel instead of retrying every five minutes forever.
• Simkl pull finally converges (#19) - ratings were matched only when every id and the title all agreed, so a film Jellyfin scraped from TMDb could never match Simkl's copy and was re-imported every run. Any shared id now matches.
• Likes keep their date - a like imported from Letterboxd is dated by the viewing it belongs to (or by the export's own date), not by the moment of import, so the liked page keeps its order.
• Two copies of a film in the library - an import now rates the copy you already rated instead of the other one.
• A failed settings load says so - if the server is busy when you open the Letterboxd panel, it now tells you to reload rather than drawing every box unticked as if your settings were gone.

Diary

• One viewing, one row - a film logged by playback and then rated (in StarTrack, on Letterboxd, or via a ZIP) used to appear twice, once unrated and once with the score. The rating now lands on the existing row. This was a timezone problem at heart - the server's day is UTC and yours is not - so it is fixed with a time window, not a calendar.
• Pre-rolls, idents and trailers are no longer logged as watches - anything under two minutes that plays before a film is not a viewing.

Ratings

• How ratings are shown - an admin setting: stars only (3.5, the default), both (3.5 (7/10)), or out of ten (7/10). Applies everywhere an average is displayed, so a 3.5 sitting next to IMDb's 7 no longer reads as a disagreement. Display only - you still rate with five stars, nothing is converted.
• IMDb import - drop your imdb.com ratings export straight into Import file; the format is detected, ratings map exactly.
• The IMDb/Yamtrack export tells you what it left out - episodes and items without an IMDb id cannot be written to that format; it now says how many, instead of handing back a quietly shorter file.

Diagnostics

• "Is StarTrack working?" - a self-check on the plugin page that answers the single most common support question in one click: eight checks, server and browser side, with a paste-ready summary for bug reports. It also flags a stale cached widget and a FlareSolverr behind a VPN.

Contributed

• Letterboxd ratings for films you don't have yet are kept and applied when the film arrives (#25, thanks @Tailes14).

Fully translated into all eight languages.

New in 1.7.0

The largest release so far: a second external service, a new thing you can rate, and the Letterboxd integration finally going both ways.

External services

• Two-way Letterboxd - send ratings, watched status, likes, your watchlist and dated diary entries back to Letterboxd, either as a CSV you upload yourself (no password) or as an hourly automatic push (password stored encrypted). Letterboxd has no public write API, so the push signs in as you; the CSV route never needs a password and always works.
• Serializd integration, both ways - Serializd is television only and Letterboxd is films only, so between them StarTrack can mirror a whole library. Importing needs your username and nothing else, because your Serializd diary is public. Only pushing needs a password.
• Overwrite toggle - decide whether a push may change a rating that already exists on Letterboxd, or leave the remote one alone. Off by default, so a push never silently overrules a rating you made somewhere else.
• Simkl import fixed (#19) - pulling from Simkl returned nothing at all. StarTrack read the wrong fields and choked on Simkl's string-typed TMDb ids, so every pull silently reported zero while the export kept re-sending the same items. Anime ratings and TV series ids now import too.

Rating seasons

• Seasons are rateable - not just series and episodes. A season gets the same detail-page panel, its own Seasons type tab in My Ratings, and its own Top 4 row.
• Season ratings stay between StarTrack and Serializd. Trakt, Simkl, Yamtrack and Letterboxd have no concept of a season rating, so seasons are deliberately withheld from them rather than filed as a show or, worse, a film.

Diary

• Log a watch - a dated "log this" control on the rating panel, so a diary is something you build in Jellyfin rather than only import from Letterboxd.
• Automatic logging on playback - finishing something records it, server-side, so every client counts and not just the web UI.
• Automatic rewatch detection - logging something you have already watched is recorded as a rewatch without you having to say so.

TV and clients

• TV rating panel is usable again - the panel opened but the stars could not be reached with a remote, so a rating could not actually be set. Focus now lands on the stars and stays inside the panel until you close it.
• Readable on TV - the panel scales properly in Large mode instead of rendering at desktop size on a 1080p screen.
• Where StarTrack works is now documented, because "it doesn't show up on Roku" has a real answer and it is not a bug.

Contributed

• Media Bar Enhanced support - replace the hero rating with the StarTrack average (thanks @mysticalsoap).
• Admin-managed Letterboxd setup - link a Letterboxd username to any user from the plugin config page (thanks @mysticalsoap).

New in 1.6.4

• One canonical media-page badge - removes duplicate, stale and attribute-stripped ghost badges left behind by Jellyfin SPA transitions. The surviving badge is clickable and opens the rating panel.
• Reliable native-rating replacement - Jellyfin's delayed community-rating node remains hidden when replacement is enabled, without creating a second StarTrack renderer.
• TV/webOS whole-star controls - each whole-star target can receive D-pad focus and be selected with OK/Enter, with webOS-compatible focus feedback.
• Native rating backfill - admins can copy every existing StarTrack rating into Jellyfin's native per-user rating field. The elevated operation is safe to run more than once.
• BaseURL follow-up - native Jellyfin item, poster and avatar requests consistently include the configured reverse-proxy sub-path.

New in 1.6.3

• TV/webOS accessibility pass - the media-page badge, floating Rate pill and post-playback prompt are D-pad reachable; unrated items retain a dimmed ☆ Rate target on TV.
• Readable TV presentation - IMDb-style white rating numbers, gold StarTrack accents and corrected Large / Large (TV only) sizing.
• Per-device rating size - users can choose Normal, Large or Large (TV only) from My Ratings → ⚙ Preferences; large mode is automatically constrained on small phone screens.
• Reverse-proxy support throughout the widget - injected assets and StarTrack API calls respect Jellyfin's BaseURL, including installations served from paths such as /jelly.
• Optional native rating mirror - new and changed StarTrack ratings can be written to Jellyfin's built-in 0–10 per-user field; removing a StarTrack rating clears its mirrored value.
• Media-page cleanup - stale, missing and duplicated badges are removed or rebuilt only on the visible detail page.

New in 1.6.2

• Initial BaseURL support - fixed widget and API routing behind reverse proxies that mount Jellyfin below the domain root.
• Native Jellyfin rating integration - added the opt-in live mirror for Jellyfin filters, native UI and backups.
• Per-device sizing - introduced user-level Normal / Large overrides while protecting small phone layouts.
• Media badge reliability - improved duplicate, stale and missing badge cleanup on web and iPad.

New in 1.6.1

• Clickable, deduplicated detail-page badge - clears Jellyfin's cached/cloned copies and opens the rating panel from the remaining badge.
• Widget cache-busting - each plugin update refreshes the injected script token so browsers receive the current widget.
• Configurable review cap - admins can set reviews from 1 to 10,000 characters instead of relying on a fixed limit.
• Display controls - Normal, Large and Large (TV only) rating sizes plus a compact media-page badge that shows only the rating.
• Early TV remote support - the floating pill and media badge can receive D-pad focus and open with OK/Enter.
• Cleaner placement - StarTrack appears before IMDb, Rotten Tomatoes and Jellyfin community ratings; a single rating no longer shows a redundant (1) count.
• Eight-language coverage - all new configuration and user-facing text was translated.

New in 1.6.0

• External rating sync (Trakt · Simkl · Yamtrack) - connect an external service and StarTrack keeps your ratings in sync. Trakt uses device-code login, Simkl uses a PIN; admins drop the client ID/secret into the plugin config page, each user connects from the ⇄ External Sync panel in My Ratings. Pick a direction per service - Off / Export only / Import only / Two-way - and a background task syncs every 10 minutes.
• Newer-wins conflict resolution - in two-way mode, the most recently changed rating wins, so a fresh local edit is never clobbered by a stale remote value (and vice-versa).
• Watched history + likes push (Trakt) - rated movies/episodes are also marked watched on Trakt (so History / Up Next populate), and your ♡ liked items are pushed to a "StarTrack Liked" list (plus Favorites if your Trakt account is VIP).
• One-shot Backfill - a button that seeds the whole service from your existing library in one pass. Simkl gets a dedicated date-accuracy repair so watched/rated dates are preserved instead of all stamped "today".
• Yamtrack CSV export - no released Yamtrack build exposes a public API yet, so StarTrack exports an IMDb-format CSV you import via Yamtrack → Import → IMDb. Marked experimental; the native provider is ready for when their REST API ships.
• Daily auto-export - a scheduled task writes your ratings out to a file every day for automatic backup.
• Configurable poster rating badge position - the gold ★ badge corner is now a setting (top-right default / top-left / bottom-right / bottom-left) so it no longer collides with Jellyfin's watched checkmark (issue #8).
• Full 8-language i18n for all of the new External Sync UI.

New in 1.5.2

• Standalone page endpoint - GET /Plugins/StarTrack/StandalonePage returns a self-contained HTML page that hosts the StarTrack overlay without the surrounding Jellyfin web shell. It is designed for WebViews, mobile apps, smart-TV launchers, third-party clients and kiosk displays. The shell accepts ?token=...&userId=..., seeds Jellyfin's credential storage, loads the existing widget and opens My Ratings without changing normal Jellyfin Web behaviour.

New in 1.5

• Members tab - every visible server user gets a profile card with avatar, rating total, average and pinned Top 4 strip, with grid sorting and search.
• Profile pages and statistics - rating histograms, genres, directors, actors, decades, longest film, hours watched, monthly activity, a 365-day heatmap, on-this-day, most-rewatched and year cards.
• Follow graph and activity feed - follow/unfollow members and browse ratings, reviews and diary activity from followed users or everyone.
• Reviews profile tab - browse an individual member's written reviews.
• Profile comparison - Pearson taste similarity mapped to 0–100%, side-by-side histograms, biggest disagreements and films both users loved.
• Privacy controls - hide a profile from Members or hide follower counts, following, statistics and recent activity; enforcement is server-side.
• Private lists - list owners can keep a list visible only to themselves.
• Diary polish - clearer ↻ Rewatch pills and a denser three-column row layout.
• Performance and security - stale-while-revalidate profile/stat caches, pre-warmed member statistics, shared item/people caches and endpoint hardening.

New in 1.4

• Eight-language i18n - English, French, Spanish, German, Italian, Portuguese, Chinese and Japanese across the widget, panel, overlay and admin page.
• Per-device language and preferences - change language, hide the floating Rate pill and hide the post-playback prompt from My Ratings → ⚙ Preferences.
• Admin presentation controls - default language; global Recent, Letterboxd and Rate-pill visibility; native/Media Bar rating replacement; poster overlays; and post-playback prompts.
• Poster rating badges - gold StarTrack ratings on library cards.
• Media detail and Media Bar replacement - substitute StarTrack averages for Jellyfin's native community rating and compatible Media Bar rating pills.
• Post-playback rating prompt - ask for a rating after a movie or episode completes, skipping items already rated.

---

❤ Support the project

StarTrack is built and maintained in my spare time. If it's useful to you and you'd like to support ongoing development, any of these means a lot:

• ⭐ Star this repo - it's free and helps others find it
• 💖 Sponsor on GitHub - one-off or monthly, every dollar reaches the project
• ☕ Buy me a coffee on Ko-fi - one-off tips

Not expected, just appreciated. Contributions - issues, PRs, translation fixes - are equally valuable.

---

License

MIT - © 2025 ZL154

---