# Quality Gate

![Quality Gate](<https://geiserx.github.io/quality-gate/images/banner.svg>)

[![Release](<https://img.shields.io/github/v/release/GeiserX/quality-gate?style=flat-square&amp;logo=github>)](<https://github.com/GeiserX/quality-gate/releases>) [![CI](<https://img.shields.io/github/actions/workflow/status/GeiserX/quality-gate/ci.yml?style=flat-square&amp;logo=github-actions&amp;logoColor=white&amp;label=CI>)](<https://github.com/GeiserX/quality-gate/actions/workflows/ci.yml>) [![License: GPL-3.0-or-later](<https://img.shields.io/github/license/GeiserX/quality-gate?style=flat-square>)](<https://github.com/GeiserX/quality-gate/blob/main/LICENSE>) [![GitHub Stars](<https://img.shields.io/github/stars/GeiserX/quality-gate?style=flat-square&amp;logo=github>)](<https://github.com/GeiserX/quality-gate/stargazers>) [![Coverage](<https://img.shields.io/codecov/c/github/GeiserX/quality-gate?style=flat-square>)](<https://codecov.io/gh/GeiserX/quality-gate>)

---

**Quality Gate** is a Jellyfin plugin that caps the video height each user can be served: 480p, 720p, 1080p, 1440p or 4K, per user or as a default for everyone. The cap is measured on the file's real video stream, so a rename, a re-encode or a symlink does not get around it. Media above the cap arrives as a capped transcode, or as a smaller version of the same item when one exists, and the original file is refused. Jellyfin's own limit is a bitrate for remote clients, not a height: a low-bitrate 4K file passes it and a viewer on the local network is not limited at all. Start with [Getting started](<https://geiserx.github.io/quality-gate/getting-started/index.md>), then read the settings page section by section in [Usage](<https://geiserx.github.io/quality-gate/usage/index.md>).

- **[Getting started](<https://geiserx.github.io/quality-gate/getting-started/index.md>)**

  ---

  Add the plugin repository to Jellyfin 12, install, cap one user at 720p and prove the cap holds with one `curl`.
- **[Usage](<https://geiserx.github.io/quality-gate/usage/index.md>)**

  ---

  The settings page section by section: policies, user access, version grouping and encode priority, each with a screenshot.
- **[One library, two qualities](<https://geiserx.github.io/quality-gate/one-library/index.md>)**

  ---

  Keep a smaller copy beside each original and have Jellyfin show them as one film with two versions.
- **[Configuration](<https://geiserx.github.io/quality-gate/configuration/index.md>)**

  ---

  Every setting, its default, how a user's policy is chosen, and the fields that restrict nothing.

## The settings page

![The top of the settings page: the note that each policy's Maximum Resolution is what restricts playback, and the first policy card, named 720p Only](<https://geiserx.github.io/quality-gate/images/screenshots/settings-policies.png>)

![The User Access table: alex on Full Access, guest on 480p Guest, kids-room on 720p Only, and admin, robin and sam on Use Default, whose effective access is the default 1080p Family](<https://geiserx.github.io/quality-gate/images/screenshots/settings-user-access.png>)

User Access: one row per user, an explicit policy or the default

![The Media Info dialog of Sintel: two media sources, Sintel (2010).mkv at 3840x2160 and Sintel (2010) - 720p.mkv at 1280x720, in one film](<https://geiserx.github.io/quality-gate/images/screenshots/film-versions.png>)

Version grouping: the original and its 720p copy as one film

![The Encode Priority section: one encoder named Movies over /media/movies producing 720p and serving two groups of viewers, and a preview list with Tears of Steel at rank 1 because a capped viewer has it in Continue Watching](<https://geiserx.github.io/quality-gate/images/screenshots/settings-encode-priority.png>)

Encode priority: what the encoder should make next

![The dashboard while kids-room, capped at 720p, plays Tears of Steel: the device card shows the client, the film and kids-room](<https://geiserx.github.io/quality-gate/images/screenshots/capped-playback.png>)

The cap holding: a capped viewer's playback as a transcode

The screenshots come from a demo server running Jellyfin 12.1 with plugin 3.9.1.0, two of the Blender open films and invented users. A policy is a name and a **Maximum Resolution**; [User Access](<https://geiserx.github.io/quality-gate/usage/#user-access>) assigns one per user or exempts a user with `Full access`; [Version Grouping](<https://geiserx.github.io/quality-gate/usage/#version-grouping>) shows an encoded copy and its original as one film; [Encode Priority](<https://geiserx.github.io/quality-gate/encode-priority/index.md>) tells [quality-gate-encoder](<https://github.com/GeiserX/quality-gate-encoder>) which files capped viewers need next.

## What it does

- Caps at 480p, 720p, 1080p, 1440p or 4K, checked against the item's video stream, never its filename.
- One policy per user, a default for everyone else, and `Full access` to exempt someone. [API keys and anonymous requests](<https://geiserx.github.io/quality-gate/how-it-works/#api-keys-are-not-capped>) can be held to a policy of their own.
- A capped user cannot direct-play, stream, download or fetch the original file; a within-cap copy plays as it is, and anything else arrives as a capped transcode.
- Optional [version grouping](<https://geiserx.github.io/quality-gate/one-library/index.md>) for movies libraries, rebuilt on every scan, and [encode priority](<https://geiserx.github.io/quality-gate/encode-priority/index.md>) for the encoder that makes the copies.
- A different intro video per policy, and a log line for every decision naming the user, the cap and the policy ([Configuration](<https://geiserx.github.io/quality-gate/configuration/#per-policy>)).

## How it runs

```
flowchart LR
    C[Client]
    F[ResolutionCapFilter<br/>inside Jellyfin]
    S[Jellyfin StreamBuilder]
    C -->|POST /Items/id/PlaybackInfo| F
    F -->|adds Height at most the cap<br/>to the device profile| S
    S -->|within-cap version,<br/>or a capped transcode| C
    C -->|/Download, /stream, HLS| F
    F -->|403 above the cap| C
```

- The plugin registers one global MVC filter and one intro provider; nothing runs outside Jellyfin's own process. [How it works](<https://geiserx.github.io/quality-gate/how-it-works/index.md>) lists every route it inspects.
- Negotiation gets a required `Height` condition, so Jellyfin itself offers the within-cap version or a capped transcode; the direct delivery routes answer `403` for an item above the cap.
- Policies live in `config/plugins/configurations/Jellyfin.Plugin.QualityGate.xml`, outside the plugin folder, so an upgrade or a reinstall never touches them.

## What it does not do

- It is not DRM. A user who can read the filesystem, or who already holds a copy, is out of scope.
- One legacy HLS segment route cannot be mapped back to an item and is [not covered](<https://geiserx.github.io/quality-gate/how-it-works/#the-one-route-that-is-not-covered>).
- If the plugin fails to load, every user is unrestricted and Jellyfin reports nothing. Watch that it stays **Active**; [Troubleshooting](<https://geiserx.github.io/quality-gate/troubleshooting/#the-plugin-vanished-after-an-update>) says how it can vanish.
- Media Jellyfin has never probed has no height: it is allowed and logged, and negotiation still transcodes it at the cap.
- Version grouping applies to movies libraries; Jellyfin already groups television on its own.

## Getting help

- Something broken: work down [Troubleshooting](<https://geiserx.github.io/quality-gate/troubleshooting/index.md>), then open an [issue](<https://github.com/GeiserX/quality-gate/issues>) with the plugin version, the Jellyfin version and the log line for the decision.
- A security problem: follow the [security policy](<https://github.com/GeiserX/quality-gate/blob/main/SECURITY.md>), never a public issue.
- What changed between versions: the [releases on GitHub](<https://github.com/GeiserX/quality-gate/releases>). Building from source and cutting a release: [Development](<https://geiserx.github.io/quality-gate/development/index.md>).
- The encoder and the rest of the family: [Related projects](<https://geiserx.github.io/quality-gate/related/index.md>).

## License

Quality Gate is released under the [GPL-3.0-or-later](<https://github.com/GeiserX/quality-gate/blob/main/LICENSE>) license. Thanks to [Jellyfin](<https://jellyfin.org>) and its plugin community.
