Overview
Install & usage
Changelog
Pricing

Plan Guard for Jellyfin — guide

Installation

For now you need medialab Server (the MediaLab variant of Jellyfin 12.2; the current build does not load in the official Jellyfin 12.2 Docker image) and a MediaLab Works account with a license that covers the plugin (an active subscription, a lifetime license within its update window, the Jellyfin bundle or the free 30-day trial).

From your plugin repository (recommended). Jellyfin then installs and updates the plugin by itself.

  1. In your MediaLab Works account open Licenses → Jellyfin plugin repository and click Create address. Copy it: it is private (it contains a token), so do not share it; you can regenerate or revoke it at any time.
  2. In Jellyfin open Dashboard → Plugins → Repositories, click +, give it a name (for example MediaLab Works), paste the address and save.
  3. In Dashboard → Plugins → Catalog find Plan Guard by MediaLab, click Install, then restart Jellyfin.

The repository lists only the plugins your licenses cover, and only the versions they allow. Its download links are signed and expire after a few hours, so Jellyfin always reads a fresh list.

From the public catalog. https://medialab.works/jellyfin/manifest.json lists every released MediaLab Works plugin with its public build; medialab Server adds it by itself. You can add it the same way to install a plugin before you have a key: the plugin then asks for the license, or starts the trial, on its License page. With a lifetime license whose update window has ended, keep to your private repository, which offers only the versions your license allows.

Manually, from a zip file.

  1. In Account → Licenses download jf-planguard_x.y.z.zip (the SHA-256 of the file is shown next to the button).
  2. Extract it into a new folder Plan Guard by MediaLab_x.y.z.0 inside the Jellyfin plugins folder:
    • Linux (package): /var/lib/jellyfin/plugins/
    • Docker (official image): /config/plugins/ in the config volume
    • Windows: %ProgramData%\Jellyfin\Server\plugins\
  3. Restart Jellyfin.

License activation

  1. Open the plugin page in Dashboard → Plugins → Plan Guard by MediaLab and click License.
  2. Paste your license key and click Activate with key. The plugin contacts the license server, binds the key to this Jellyfin server and shows the license as Active.
  3. No key yet? On the same page enter your e-mail and start the 30-day free trial (card needed, nothing to pay today) or buy a license; the plugin activates itself when the payment is done.

The license is checked once a day and at every Jellyfin start. Without internet the plugin keeps working for 7 days after the last successful check. Without a valid license the plugin stops its work and only its License page keeps working (trial, key, renewal); nothing is deleted, and everything resumes as soon as the license is valid again. Move license (release this server) on the same page frees the key for another server.

Updates and rollback

  • From the repository: Jellyfin shows new versions in Dashboard → Plugins and can update the plugin automatically; restart Jellyfin to load the new version.
  • From the plugin's License page: with a valid license, Install update installs the newest version your license allows and Roll back to x.y.z goes back to the previous version (for example if something stopped working after an update). Restart Jellyfin after either. Both packages are checked against the checksum published by the license server.
  • A lifetime license receives the versions released during its update window; after it, the plugin keeps working on the last version it may use.
  • After a rollback, if your plugin repository is added in Jellyfin, Jellyfin's scheduled task Update Plugins (at start-up and daily) installs the newest version again. To stay on the previous version for a while, remove the triggers of that task in Dashboard → Scheduled Tasks and add them back later.

Source code

The GPL-3.0 source code of each version is in Account → Licenses (Source code), next to the download, as a .tar.gz archive made from the exact commit of that version.

Configuration

Open Plan Guard in the Jellyfin dashboard menu. The page has six tabs: Active streams, Profiles, Users, Sharing, Log and Settings.

  1. Profiles: click Add profile and set, for each profile (0 means no limit):
    • the number of simultaneous streams;
    • the quality at home and away from home, in Mbit/s;
    • the maximum resolution;
    • whether video conversion (transcoding) is allowed, and whether 4K conversion is allowed (the most expensive for the server);
    • how many devices in 30 days an account may use before it counts as a sharing signal;
    • with Cashier, the linked Cashier plan.
  2. Users: choose the profile of each user, and the profile for everyone else (or no limits). Administrators are never limited.
  3. Cashier plans (optional): with Cashier installed and With Cashier installed: the profile follows the paid plan turned on, subscribers get the profile linked to their plan (or the plan's device limit), and Plan Guard takes over stopping playback.
  4. Settings → enforcement:
    • Automatically stop playback that breaks the profile (off: log only);
    • Seconds between message and stop (10 by default);
    • Sign out devices that ignore stop (on by default): the user has to sign in again on that device;
    • Block the device after signing it out (off by default).
  5. Settings → shared accounts: turn on Detect shared accounts, then choose what happens below the threshold: notify only (activity log, the default), notify and message the user, notify and force a new sign-in, or notify and block the newest device. You can also set the score threshold (50 by default), the "impossible travel" speed (500 km/h by default) and how many different networks in one day count as a signal (5 by default).

Daily use

  • When a user starts a playback above the stream limit, Jellyfin refuses it before it starts. The quality is capped at the start, at the profile's bitrate for home or away from home.
  • During playback, Plan Guard checks every stream about every 10 seconds. A playback that breaks the profile gets a message, then a stop command; if it keeps playing, its transcode is ended on the server and the device is signed out.
  • Active streams shows who is playing what, the quality, where from and the profile, with a Stop button and an optional message for the user.
  • Sharing shows a trust score per account (100 = clean) over the last 30 days, with the signals and places behind it. Alerts also go to the Jellyfin activity log, at most once a day per account.
  • Log shows every action Plan Guard took and why.

How players react

  • Players without remote control, such as Infuse, Kodi and DLNA, ignore stop commands, so Plan Guard signs the device out instead (if Sign out devices that ignore stop is on).
  • Players that keep playing after the stop command have their transcode ended on the server, then they are signed out.
  • The full list of clients and how each one reacts will be added after testing.

What it sends where

Locations are looked up on your server, from the free DB-IP Lite City and ASN databases, downloaded from download.db-ip.com while shared-account detection is on, and downloaded again at start-up once they are older than 35 days. If Access Log or Security Notifications already keep a location database, Plan Guard reuses it; the Sharing tab shows which one is in use. Nothing about your users is sent anywhere; only the license check reaches medialab.works.

IP Geolocation by DB-IP (CC BY 4.0).

Troubleshooting

  • "Geolocation is not available yet": the DB-IP Lite databases are still downloading; the server needs to reach download.db-ip.com over HTTPS.
  • A user on mobile data or a VPN looks like a shared account: that can happen; keep the action on Notify only, or raise the networks-per-day setting.
  • Cashier is installed but the profiles do not follow the plans: check that Cashier's license is active and that it is up to date; the Users tab shows the state of the link.
Tell me when it is availableProducts