contentrating

package
v0.3.17 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 21, 2026 License: GPL-3.0 Imports: 4 Imported by: 0

Documentation

Overview

Package contentrating is Ether's one content-rating model. Every certification (US MPAA and TV Parental Guidelines, and the boards of the countries TMDB lists) normalises to a Rating: the issuing country, the label as certified, and an age Level. Rules, viewer limits and pickers compare Levels, so "PG" and "TV-PG" are the same choice everywhere.

Stored form. US labels are stored bare ("PG", "TV-14"), exactly as Plex shows them. Any other country's label is stored region-qualified the way Plex Media Server writes it, lowercase country then a slash: "de/6", "gb/12A", "ca/14A". A foreign label is never stored as if it were US.

Index

Constants

View Source
const NotRatedKey = "NR"

NotRatedKey is the rule and picker value for titles without a usable rating.

View Source
const UncertifiedAdult = "XXX"

UncertifiedAdult marks a title that has no usable certification ("" or "NR") on TMDB or any configured provider, yet carries TMDB adult=true or a strongly adult-leaning stored keyword set. Unlike ordinary unrated titles, UncertifiedAdult is hidden from every viewer with any content-rating limit, even when the owner allows unrated titles.

Variables

Levels lists the rated levels, mildest first. There is no separate "7+" level: the 6–11 age ratings (TV-Y7, DE 6, SE 7, BR 10) sit with PG, so an allowlist of G and PG never hides a title rated milder than PG.

Functions

func Allowed

func Allowed(rating, max string) bool

Allowed is !Exceeds, for readability at call sites.

func Alpha2

func Alpha2(country string) string

Alpha2 normalizes a country or sub-region code (such as "us", "GB", or "CA-QC") to its uppercase ISO 3166-1 alpha-2 code, or "" when invalid.

func ByCountry

func ByCountry(certs []Certification) map[string]string

ByCountry reduces provider certifications to the best bare label per country (keyed by uppercase country code), following Select's release-type ordering and preferring a rated label over an explicit "not rated" mark.

func Canonical

func Canonical(v string) (key string, ok bool)

Canonical maps any accepted rule or limit value to the level's Key: "TV-G" and "gb/U" become "G", "Not rated" becomes "NR". ok is false for a value that names no level and is not an explicit "not rated".

func Display

func Display(stored string, certs map[string]string, preferredRegions ...string) (label, country string)

Display selects a bare certificate and optional ISO 3166-1 alpha-2 country code for a title, preferring the regions in preferredRegions in order (for example the viewer's Accept-Language region, the server's configured region, then "US"), before falling back to other countries in foreignPriority order or the parsed stored rating. Unknown bare ratings return label with "".

func EffectiveEnforcement

func EffectiveEnforcement(enforcementRating, contentRating string, adult bool, keywords []string) string

EffectiveEnforcement resolves the US enforcement rating for a title, using its persisted enforcementRating when present and falling back to its displayed contentRating, adult flag, and stored keywords before lazy backfill has refreshed the row.

func EnforceCertifications

func EnforceCertifications(certs []Certification, region string) string

EnforceCertifications chooses the canonical US enforcement rating ("G", "PG", "PG-13", "R", "NC-17") from TMDB release_dates / content_ratings certifications without modifying the displayed rating returned by Select. Within the winning country and release-type tier, stricter certifications break ties so a dual-cut listing does not under-enforce.

func EnforceExceeds

func EnforceExceeds(rating, max string) bool

EnforceExceeds reports whether an enforcement or content rating exceeds max. An empty max is unrestricted. Unrated ("") and UncertifiedAdult ("XXX") always exceed a non-empty max.

func EnforceRating

func EnforceRating(s string) string

EnforceRating maps a stored or raw certification string to its canonical US enforcement rating ("G", "PG", "PG-13", "R", "NC-17"), preserving UncertifiedAdult ("XXX") and returning "" when unrated.

func Equivalents

func Equivalents(l Level) []string

Equivalents lists the labels each country's board uses for level l, as stored values (bare US, "cc/label" elsewhere), US first then by country.

func Exceeds

func Exceeds(rating, max string) bool

Exceeds reports whether rating is above the limit max. An empty limit is unrestricted. An unrated title, or a limit that names no level, exceeds every limit: restricted viewers never see what Ether cannot place.

func FromPrefixed

func FromPrefixed(label string) string

FromPrefixed reads a Jellyfin or Emby rating label back into stored form: "DE-6" is "de/6" when DE is a board Ether knows; anything else ("PG-13", "TV-14") is already a stored label.

func HasAdultKeywords

func HasAdultKeywords(keywords []string) bool

HasAdultKeywords reports whether a title's stored keyword list strongly indicates adult or soft-core sexual content.

func IsNotRated

func IsNotRated(v string) bool

IsNotRated reports whether an owner value means "titles without a rating".

func LeaningAdultKeywords

func LeaningAdultKeywords() []string

LeaningAdultKeywords returns the sorted multi-hit (>=2) adult-leaning keywords.

func OverrideLabelsForLevel

func OverrideLabelsForLevel(lvl Level) []string

OverrideLabelsForLevel returns the sorted lowercase "cc/label" forms in enforceOverrides for lvl, so SQL rating filters match pre-refresh foreign labels (e.g. "ph/x", "au/rc") before lazy backfill updates their rank.

func Prefixed

func Prefixed(stored string) string

Prefixed is a stored rating in the form Jellyfin and Emby store and show ratings: bare for the US, "DE-6" (country, hyphen, label) elsewhere.

func Qualify

func Qualify(country, label string) string

Qualify is the stored form of a country's label: bare for the US, otherwise "cc/label" like Plex Media Server.

func StrongAdultKeywords

func StrongAdultKeywords() []string

StrongAdultKeywords returns the sorted single-hit adult keywords.

Types

type Certification

type Certification struct {
	Country string // ISO 3166-1, any case
	Label   string
	// ReleaseType is TMDB's movie release type (1 premiere, 2 limited
	// theatrical, 3 theatrical, 4 digital, 5 physical, 6 TV); 0 for TV
	// show content ratings.
	ReleaseType int
}

Certification is one rating a provider lists for a title.

type Level

type Level int

Level is an age band. Higher is more mature; Unrated sorts first and is never inside a limit. The integer values are persisted (catalogue content_rating_rank), so they must not be renumbered.

const (
	Unrated  Level = iota // no usable certification: blank, NR, Unrated, unknown label
	AllAges               // G, TV-G, TV-Y; U (GB), 0 (DE), L (BR)
	Parental              // PG, TV-PG, TV-Y7; PG (GB), 6 (DE), 7 (SE), 10 (BR)
	Teen                  // PG-13, TV-14; 12A (GB), 12 (DE), 14A (CA)
	Mature                // R, TV-MA; 15 (GB), 16 (DE), MA15+ (AU)
	Adult                 // NC-17; 18 (GB, DE), R18+ (AU)
)

func AgeLevel

func AgeLevel(age int) Level

AgeLevel is the band holding a minimum age: 0–5 all ages, 6–11 parental guidance, 12–14 teens, 15–17 mature, 18 and over adults.

func EnforceLevelOf

func EnforceLevelOf(s string) Level

EnforceLevelOf returns the enforcement Level for a stored or raw rating label (e.g. "ph/R-18", "ph/X", "PH X", "de/18", "NC-17", "MA15+"). UncertifiedAdult ("XXX") is not a certified band (LevelOf returns Unrated); use EnforceExceeds for viewer-limit checks.

func EnforceLookup

func EnforceLookup(country, label string) Level

EnforceLookup returns the enforcement Level of a country's certification, mapping 18+/R18/X/banned classifications to Adult (NC-17), 15–17/16/MA15+ to Mature (R), 12–14/13 to Teen (PG-13), 6–11 to Parental (PG), and 0–5/U/G to AllAges (G).

func LevelOf

func LevelOf(s string) Level

LevelOf is Parse(s).Level.

func Lookup

func Lookup(country, label string) Level

Lookup is the level of a country's label. A label the country's table does not list falls back to a plain age ("16", "12+"); otherwise it is Unrated.

func (Level) Age

func (l Level) Age() int

Age is the minimum viewer age the level stands for (-1 when unrated). It is also the parental score other protocols use (Jellyfin and Emby compare these numbers; Jellyfin's US file scores G 0, PG 10, PG-13 13).

func (Level) Key

func (l Level) Key() string

Key is the canonical value a rule or viewer limit stores for the level: the US film label where there is one. "NR" is the explicit "Not rated" choice.

func (Level) USLabels

func (l Level) USLabels() []string

USLabels are the US film and TV labels of a level, in display order.

type Rating

type Rating struct {
	// Country is the ISO 3166-1 code of the issuing board, upper case
	// ("US", "DE", "CA-QC"). Empty when a bare stored label is not a US
	// label and its country cannot be known.
	Country string
	Label   string // as certified: "TV-PG", "6", "12A"
	Level   Level
}

Rating is one parsed certification.

func Parse

func Parse(s string) Rating

Parse reads a stored or owner-entered rating. Bare US labels resolve as US. A bare label from another system (stored by an older release, or typed by the owner) resolves only when every board that uses it agrees on the level, or when it is a plain age ("12", "16+"); anything else is Unrated rather than a guess.

type Selection

type Selection struct {
	Value  string // stored form: "PG", "de/6"; "" when nothing usable
	Source string // "tmdb:US:6", "tmdb:CA"; "" when Value is ""
}

Selection is the chosen rating in stored form, and where it came from.

func Select

func Select(certs []Certification, region string) Selection

Select chooses a title's rating from a provider's certifications: the owner's region first, then the US, then other countries (foreignPriority order). Within a country it takes the first label that has an age level, by release type. A foreign rating is kept region-qualified ("de/6"), never passed off as US. When no country has a rated label, an explicit "not rated" from the region or the US is kept ("NR"), as Plex shows it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL