Admin Guide

Admin Guide

The Moonbase settings page, tab by tab, in plain words. You don't have to touch most of it. Sync alone already gives your users the biggest win, and everything else is optional.

Where the page is: Jellyfin: Dashboard > Plugins > My Plugins > Moonbase. Emby: Dashboard > Plugins > Moonbase. Both open the same page with the same tabs: General, Integrations, Games, User defaults, Themes, Messages, Actions, Help and Active Downloads. Click Save at the bottom after changing anything.

If an amber banner is at the top (Jellyfin): it says These settings look like they were reset. Moonbase keeps a spare copy of this page's settings, and the banner shows up when the live settings are back to defaults while that copy still holds your real ones. Click Restore these settings, then restart the server. Your users' own settings are stored separately and aren't affected. Common Problems has the causes and the manual route.

The five-minute setup

If you only do one thing on each tab:

Tab	Do this
General	Tick Enable Moonbase Sync
Integrations	Paste a free MDBList API key and a free TMDB API key so your users get extra ratings without keys of their own. Add Seerr if you have it
Games	Skip unless you have ROMs
User defaults	Skip. Users decide for themselves
Themes	Skip
Messages	Skip

Then Save, and tell your users to tick Settings > Integrations > Moonbase Plugin > Enable Plugin in their apps.

General

• Enable Moonbase Sync. The master switch. It turns on settings sync across devices and is required for the Seerr and ratings integrations. Leave it on.
• Moonfin Web Client. Only matters for the web app at /Moonfin/Web/.
  • Default Server URL pre-fills the Add Server box in the web app. Leave empty and it uses the address the page was opened from, which is right for nearly everyone.
  • Forced Server URL makes the web app connect to that address on load without asking. Use it when you want the web app to behave like a kiosk for one server. Use the base address, such as http://192.168.1.10:8096, without /web.
  • Enable WebRTC Private Subnet Scan lets the web app look for servers on the local network. Turn it off if your browsers block WebRTC.
• Enable client log upload (Emby, under Diagnostics). Lets your users send a diagnostic or crash report from the app with Send report to server. Reports land under Dashboard > Logs beside your server's own, named upload_<client>_<version>_<time>.txt. Emby has no way to receive one without this plugin, so it's on by default. Jellyfin takes these reports on its own, which is why its page doesn't have this switch. The apps strip server addresses, IP addresses and access tokens out before sending, each user is limited to 10 reports an hour at 1 MB each, and turning this off makes the button in the apps go gray.

Integrations

Seerr Integration

• Enable Seerr and Seerr URL: the address of your Seerr, as your server sees it. The full walkthrough is Seerr Setup.
• Display Name: what the apps call it in menus, for example "Requests". Leave empty for "Seerr".
• Public Server URL: how Seerr reaches your server for notifications. Only needed when Seerr and the server can't reach each other by the server's own guess, typically separate Docker containers. See Seerr Notifications.
• Push Relay URL, Push Relay Key, Push Service Account: leave them alone. Phone notifications work through the hosted relay by default. They exist for people who run their own relay or Firebase project.

MDBList Integration

• Server-wide MDBList API Key: a free key from mdblist.com (Preferences > API Key). With it, every user sees Rotten Tomatoes, Metacritic, Letterboxd and other ratings in the apps without making their own account.
• Sync MDBList official lists and Max items per official list: turns MDBList's curated lists into home rows your users can switch on.

IMDb Charts

• Sync IMDb charts: adds IMDb Top 250, Popular and similar charts as optional home rows.

Recommendations

• Use Moonfin Recommends for similar items (Jellyfin 12+): on by default. Moonbase scores the "more like this" titles itself, matching on genres, tags, directors, writers, cast, studios, franchise, release year and rating, and only suggests what that user is allowed to see. Moonfin apps get these on any Jellyfin version. On Jellyfin 12 it also plugs into Jellyfin's own similar items, so every client gets them, the stock web interface included, and Jellyfin's own results only fill the slots Moonbase leaves empty. Turn it off to hand similar items back to Jellyfin everywhere, Moonfin apps included. Jellyfin only.

Studio Logos

• Sync studio logos from TMDB and a refresh age. Downloads the studio logos the apps show on detail pages and caches them on the server.

TMDB Integration

• Server-wide TMDB API Key: a free key from themoviedb.org. Used for episode ratings, TMDB list rows, studio logos, and a series' next air date when there's no Sonarr to ask.

Each of these syncs runs as a scheduled task you can trigger by hand under Dashboard > Scheduled Tasks: Moonfin MDBList Ratings Sync, Moonfin MDBList Official Lists Sync, Moonfin IMDb Lists Sync, Moonfin Custom Lists Sync (Jellyfin) and Moonfin Studio Images Sync. Ratings appear after the first run, so run it once right after pasting a key rather than waiting for the schedule.

Anime Filler & Recap Markers (Jellyfin only)

• Classify anime episodes as canon, mixed or filler: the main switch, off by default. Moonbase matches your anime by title against AnimeFillerList so the apps can badge filler episodes. No account or API key needed.
• Libraries to look in: leave everything unchecked to consider every library. Treat everything in the selected libraries as anime skips the "does this look like anime" check for the Subbed and Dubbed pills. Only turn it on when the libraries you picked hold nothing but anime.
• Also mark recap episodes (uses MyAnimeList): on by default. AnimeFillerList has no recap category, so this asks MyAnimeList as well. If that lookup fails, the filler data is unaffected.
• Also mark episodes and seasons as Subbed or Dubbed and Also mark movies as Subbed or Dubbed: these read the audio tracks in your own files and need no internet. Japanese audio and nothing else is Subbed, any other spoken language makes it Dubbed, and audio with no language tag is left unmarked. A season only gets a pill when every episode agrees. Label dual-audio files as Subbed/Dubbed shows a file that has both as Subbed/Dubbed instead of just Dubbed.
• Where to put the pills: below the runtime, beside it, or on the episode thumbnail. Season and movie cards always put the pill on the artwork.
• Which pills to show: Filler, Mixed canon and filler, Recap, Manga canon and Anime canon. The two canon pills are off by default, because nearly every episode of most shows is canon. A pill switched off here is never sent to any app.
• Marker refresh age (days): shows older than this are fetched again (default 30). It mostly decides how quickly an airing show picks up new episodes.
• Check matching shows how many of your series matched a show on the site and names some that didn't. Clear marker cache throws away everything fetched so far. Type a name into Preview a series to see which of your episodes each marker landed on, and Fetch now pulls that one show straight away instead of waiting for the task.
• Write a marker debug log: records every marker request an app makes, and the answer, to moonfin-anime-markers.log in the server's log folder, so it also shows under Dashboard > Logs. Show log and Clear log sit below it. If a badge is missing and its request never shows up in the log, the app never asked. Leave it off otherwise.

Markers appear after the Moonfin Anime Markers Sync task has run. It runs every night and never at startup, because it waits 10 seconds between pages to go easy on the site. Each run stops after 45 minutes, or after 5 failed fetches in a row, and carries on the next night, so a big library can take a few nights the first time.

Games

• Enable retro games switches the feature on. Everything is off until you do.
• Game libraries: tick the libraries that hold your ROMs.
• Emulator cores: games play out of the box from a public CDN. Install downloads the roughly 290 MB bundle onto your server so games work without reaching out, and Upload cores zip does the same from a file you provide.
• Isolate the web app for PSP games (Jellyfin): off by default. PSP games need cross-origin isolation to start in Moonfin Web, and the game player only gets it when the whole web app is isolated. Turn it on if PSP games stop with an error, Save, then reload Moonfin Web. Once it's on, anything cross-origin you've added to the web client has to allow isolation too.

Folder naming, box art, BIOS files, saves and per-platform support are on the Retro Games page.

User defaults

The Default User Settings here are the starting point every user gets, split into the same sections the apps have: General Style, Details Screen, Navigation, Home Screen, Home Sections, Libraries, Playback, Extras and Integrations. Every control mirrors what the apps actually offer.

• A setting left on Not set (user decides) passes the user's own choice through. That is the right value for almost everything.
• A default only fills the gap. The first time someone signs in, the Moonfin app for Android, Apple, Windows and Linux saves every setting it has to the server, even ones they never touched. So a default you set or change later only reaches people who haven't signed in yet, unless you push.
• Apply Defaults To Users (called Push Defaults To Existing Users on Emby, and found on the Actions tab) writes the defaults you set over everyone's stored values, and connected apps pick it up immediately. Anything still on Not set is left alone. On Jellyfin you can also apply to one user, or tick Overwrite each user's existing settings (full reset) to replace everything they have, device overrides included. Use it deliberately.

Details Screen sets the Detail screen style (Classic, Modern, Spotlight, Nouveau or Minimalist) and the Metadata Row, where you tick which details show on detail pages (release year, parental rating, runtime and seasons, series status, upcoming episodes, genres and Seerr availability) and put them in order. General Style also covers the loading animation and the TV screensaver, down to which libraries and collections the screensaver draws from and which genres it skips.

Typical reasons to set a default: a house theme, the navigation position for a room full of TVs, a screensaver on TV clients, hiding the Seerr or Downloads button for a family server, or a sensible Max days in Next Up.

Themes

Uploaded Themes lists the custom themes on your server and lets you upload new ones. Themes are JSON files made in the built-in editor at https://<your server>/Moonfin/Web/theme/. The server checks each upload against the theme schema, so a broken file is refused rather than handed to clients. Connected apps see a new theme without restarting. Details on the Themes page.

Messages

Server messages are notes from you to your users that show up inside their apps, even if they were offline when you wrote them.

• Title, a Markdown body, a color, an audience (everyone or selected users), optional start and end dates, and an optional link button.
• Saved Messages lists what you've written. Edit or delete from there.
• For a quick one-off with no scheduling, use Broadcast Message on the Actions tab instead.

Messages go out over the live connection and as a push notification to phones that have one registered. In the Moonfin apps they appear in a messages window with an unread badge. On Smart TVs they appear as an on-screen notice.

Actions

• Apply Defaults To Users (Jellyfin) or Push Defaults To Existing Users (Emby): see User defaults above.
• Broadcast Message: a one-off note to everyone right now.

Active Downloads

The Active Downloads dashboard: every transcoded download your users have running, with live transcode metrics. Useful to see who is making the server work before the first byte reaches their device.

Help

On Jellyfin, Web Plugin Status has the setup steps for the Moonfin button in Jellyfin's header (it needs the File Transformation plugin), and says to run the Moonfin Startup scheduled task once if the button doesn't load. On Emby, Opening Moonfin is a reminder that the web app is opened directly at /Moonfin/Web/.

Scheduled tasks

All of these live under Dashboard > Scheduled Tasks and can be run by hand:

Task	What it does
Moonfin Startup	Registers the Jellyfin header button injection. Normally automatic. Run it once if the web app or the header button doesn't load after installing
Moonfin Settings File Repair	Checks every user's settings file and repairs or quarantines damaged ones. Runs at startup on its own
Moonfin MDBList Ratings Sync	Fetches ratings for your library from MDBList
Moonfin MDBList Official Lists Sync	Refreshes the MDBList list rows
Moonfin IMDb Lists Sync	Refreshes the IMDb chart rows
Moonfin Custom Lists Sync	Refreshes every custom home row your users have set up from Letterboxd, TMDB, MDBList and IMDb lists, so the rows are fresh before anyone opens them. Jellyfin only
Moonfin Studio Images Sync	Downloads studio logos from TMDB
Moonfin Anime Markers Sync	Fetches filler, canon and recap data for the anime in your library. Jellyfin only. Runs nightly, never at startup, and stops after 45 minutes

What differs on Emby

Almost everything works the same on both servers. The differences:

Feature	Jellyfin	Emby
Moonfin button in the server's own web header	Yes, with the File Transformation plugin	No, Emby has no way to inject it. Open /Moonfin/Web/ directly
Audiobook bookmarks and notes synced through the server	Yes	No
Moonfin Recommends for similar items	Yes, and on Jellyfin 12 for every client, the stock web interface included	No
Anime filler, recap and Subbed/Dubbed markers	Yes	No
Settings backup and the restore banner	Yes	No
Isolate the web app for PSP games	Yes	No
Moonfin Custom Lists Sync task	Yes	No, custom rows refresh when someone loads them
Settings File Repair	Scheduled task	Runs at startup automatically, plus a manual task
Client log upload from the apps ("Send report to server")	Yes, Jellyfin has its own endpoint, so the plugin isn't needed	Yes, but only through this plugin, since Emby has no endpoint for it. Needs Enable client log upload
Everything else: sync, Seerr, notifications, ratings, list rows, retro games with saves and self-hosted cores, themes, messages, collection ordering, active downloads	Yes	Yes

Where the data lives

User settings, Seerr sessions, themes, saves and caches are in a Moonfin folder under your server's plugin configuration directory. Your own choices from this page are in an XML file next to it, and on Jellyfin a spare copy of that file sits inside the Moonfin folder. Both, with backup and reset advice, are on Data Locations.