core

type ActiveUserSource interface {
	ActiveUser(context.Context, int64) (*User, error)
}

type ActivityDay struct {
	Date          string  `json:"date"` // YYYY-MM-DD, server local time
	Plays         int     `json:"plays"`
	Hours         float64 `json:"hours"`
	UniqueViewers int     `json:"uniqueViewers"`
}

type AlignRequest struct {
	Key          RatingKey     `json:"key"`
	From         Release       `json:"from"`
	To           Release       `json:"to"`
	FromDuration time.Duration `json:"fromDuration,omitempty"`
	ToDuration   time.Duration `json:"toDuration,omitempty"`
}

type ArticleFetcher interface {
	// Body returns the decoded payload of one article (one NZB segment).
	// Returns ErrArticleMissing when no provider has it.
	Body(ctx context.Context, messageID string, groups []string, prio Priority) ([]byte, error)
	// BodyPart is Body plus the article's yEnc =ybegin/=ypart header, which
	// gives the segment's exact byte range inside the posted file.
	BodyPart(ctx context.Context, messageID string, groups []string, prio Priority) ([]byte, ArticlePart, error)
	// Stat reports whether any provider has the article.
	Stat(ctx context.Context, messageID string) (bool, error)
}

type ArticlePart struct {
	Name     string `json:"name"`
	FileSize int64  `json:"fileSize"`
	Part     int    `json:"part"`
	Total    int    `json:"total"`
	Begin    int64  `json:"begin"`
	End      int64  `json:"end"`
}

type ArtworkAccessPolicy interface{ Restricted(*User) bool }

type Auth interface {
	// Authenticate maps an X-Plex-Token to a user with access to this server.
	Authenticate(ctx context.Context, token string) (*User, error)
	Users(ctx context.Context) ([]User, error)
	UpdateUser(ctx context.Context, u User) error
	Owner(ctx context.Context) (*User, error)
}

type AuthoritativeTitleRefresher interface {
	RefreshTitle(ctx context.Context, key RatingKey, persist bool) (*Title, error)
}

type AvailabilitySource interface {
	Available(context.Context, RatingKey) (bool, bool)
}

type BackgroundBudget func(ctx context.Context, resource, source string, amount int64) error

type BatchWatchState interface {
	ScrobbleMany(context.Context, int64, []RatingKey) error
	UnscrobbleMany(context.Context, int64, []RatingKey) error
}

type BitrateAccessPolicy interface{ BitrateLimit(*User) int }

type BrowseQuery struct {
	Filter         Filter
	Sort           SortOrder
	Desc           bool
	SecondarySorts []SortSpec
	Offset         int
	Limit          int
	// NoTotal skips counting the filter's matches, which reads every title
	// the filter admits. Page.Total is then offset plus the items returned.
	NoTotal bool
}

type BufferedInputSwapper interface {
	SwapInputBuffered(context.Context, string, MediaInfo, time.Duration) error
}

type BurstArticleFetcher interface {
	BodyPartBurst(ctx context.Context, messageID string, groups []string, prio Priority, until time.Time) ([]byte, ArticlePart, error)
}

type CachePlayRecorder interface{ RecordPlay(string, string, int64) }

type CachedTitleSource interface {
	CachedTitles(context.Context, []RatingKey) ([]Title, error)
}

type Catalog interface {
	Get(ctx context.Context, key RatingKey) (*Title, error)
	// Children: seasons of a show, episodes of a season.
	Children(ctx context.Context, key RatingKey) ([]Title, error)
	// Grandchildren: all episodes of a show.
	Grandchildren(ctx context.Context, key RatingKey) ([]Title, error)
	Browse(ctx context.Context, q BrowseQuery) (Page, error)
	// Search reaches all of TMDB; matched titles join the browsable set.
	Search(ctx context.Context, query string, types []MediaType, limit int) ([]Title, error)
	// Lists from TMDB: "trending_day", "trending_week", "top_rated", "now_playing", "popular", "airing_today", "upcoming".
	List(ctx context.Context, list string, t MediaType, limit int) ([]Title, error)
	Similar(ctx context.Context, key RatingKey, limit int) ([]Title, error)
	Collection(ctx context.Context, tmdbCollection int64) (name string, items []Title, err error)
	// Facets for filter UIs: "genre", "year", "decade", "contentRating", "studio", "country".
	Facet(ctx context.Context, t MediaType, facet string) ([]FacetValue, error)
	// NextEpisode returns the episode after the given one, or ErrNotFound.
	NextEpisode(ctx context.Context, episode RatingKey) (*Title, error)
	// ByExternalID looks up a title by imdb ("tt123") or tvdb id.
	ByExternalID(ctx context.Context, source, id string) (*Title, error)
}

type CatalogSchedule interface {
	ScheduledEpisodes(context.Context, RatingKey) ([]Title, error)
}

type ChannelPreparer interface {
	PrepareChannel(context.Context, *User, RatingKey, ClientCaps, string) (*PlaySession, error)
}

type Chapter struct {
	ID    int64         `json:"id"`
	Title string        `json:"title,omitempty"`
	Start time.Duration `json:"start"`
	End   time.Duration `json:"end"`
}

type ClientCapabilityOverride struct {
	ID       string `json:"id,omitempty"`
	Product  string `json:"product,omitempty"`
	Platform string `json:"platform,omitempty"`
	Device   string `json:"device,omitempty"`
	// Version is the minimum client version (dotted numbers) this override requires.
	Version             string   `json:"version,omitempty"`
	VideoCodecs         []string `json:"videoCodecs,omitempty"`
	AudioCodecs         []string `json:"audioCodecs,omitempty"`
	Containers          []string `json:"containers,omitempty"`
	SubtitleCodecs      []string `json:"subtitleCodecs,omitempty"`
	DolbyVisionProfiles []int    `json:"dolbyVisionProfiles,omitempty"`
	MaxHeight           int      `json:"maxHeight,omitempty"`
	MaxBitrateKbps      int      `json:"maxBitrateKbps,omitempty"`
	HDR10               *bool    `json:"hdr10,omitempty"`
	DolbyVision         *bool    `json:"dolbyVision,omitempty"`
	Notes               string   `json:"notes,omitempty"`
}

type ClientCapabilityProfiles struct {
	DirectPlay                                                                []ClientDirectPlayProfile
	Transcoding                                                               []ClientTranscodeProfile
	Subtitles                                                                 []ClientSubtitleProfile
	Containers                                                                []ClientContainerProfile
	Codecs                                                                    []ClientCodecProfile
	MaxStaticBitrate, MusicStreamingTranscodingBitrate, MaxStaticMusicBitrate int
}

type ClientCaps struct {
	Profiles        *ClientCapabilityProfiles `json:"profiles,omitempty"`
	Protocol        Protocol                  `json:"protocol,omitempty"`
	Product         string                    `json:"product"`  // X-Plex-Product: "Plex Web", "Plex for iOS", "Plex for Apple TV"
	Platform        string                    `json:"platform"` // X-Plex-Platform
	PlatformVersion string                    `json:"platformVersion"`
	Device          string                    `json:"device"`
	DeviceName      string                    `json:"deviceName"`
	ClientID        string                    `json:"clientId"` // X-Plex-Client-Identifier
	Version         string                    `json:"version"`

	MaxHeight            int                 `json:"maxHeight"`                   // 2160, 1080, 720...
	ExplicitMaxHeight    bool                `json:"explicitMaxHeight,omitempty"` // true when MaxHeight came from a request header/query limitation rather than a product default
	HDR10                bool                `json:"hdr10"`
	ExplicitNoHDR        bool                `json:"explicitNoHdr,omitempty"` // true when HDR was explicitly denied by profile-extra limitations
	DolbyVision          bool                `json:"dolbyVision"`
	VideoCodecs          []string            `json:"videoCodecs"`                    // h264, hevc, av1, vp9
	AudioCodecs          []string            `json:"audioCodecs"`                    // aac, ac3, eac3, truehd, dts, opus, flac
	Containers           []string            `json:"containers"`                     // mp4, mkv, mpegts
	HLSContainers        []string            `json:"hlsContainers,omitempty"`        // explicit segmented output targets; distinct from direct-play containers
	MaxBitrateKbps       int                 `json:"maxBitrateKbps"`                 // 0 = unlimited
	DefaultRemoteBitrate bool                `json:"defaultRemoteBitrate,omitempty"` // true when MaxBitrateKbps came from the server's default remote cap rather than a client limitation
	SubtitleCodecs       []string            `json:"subtitleCodecs,omitempty"`       // native image/text subtitle rendering
	DVProfiles           []int               `json:"dvProfiles,omitempty"`           // explicit Dolby Vision profiles; empty uses product defaults
	VideoProfiles        map[string][]string `json:"videoProfiles,omitempty"`
	VideoLevels          map[string]int      `json:"videoLevels,omitempty"` // codec level in ffprobe units (H.264 51 = 5.1)
	Remote               bool                `json:"remote"`                // not on the server's LAN

	// TranscodeAudioCodecs is the explicit audio target for the current
	// streaming protocol. It constrains remux/transcode output only; source
	// selection and direct play continue to use AudioCodecs.
	TranscodeAudioCodecs []string `json:"transcodeAudioCodecs,omitempty"`

	// Download marks a request for an offline download (Plex Downloads /
	// Sync) rather than live playback: the resolver prefers compact,
	// mobile-native releases and the whole file is remuxed (additive).
	Download bool `json:"download,omitempty"`
}

type ClientCodecProfile struct {
	MediaType                         string
	Codecs, Containers, SubContainers []string
	Conditions, ApplyConditions       []ClientProfileCondition
}

type ClientContainerProfile struct {
	MediaType                 string
	Containers, SubContainers []string
	Conditions                []ClientProfileCondition
}

type ClientDirectPlayProfile struct {
	MediaType   string   `json:"mediaType"`
	Containers  []string `json:"containers"`
	VideoCodecs []string `json:"videoCodecs"`
	AudioCodecs []string `json:"audioCodecs"`
}

type ClientProfileCondition struct {
	Operator string `json:"operator"`
	Property string `json:"property"`
	Value    string `json:"value"`
	Required bool   `json:"required"`
}

type ClientSubtitleProfile struct{ Format, Method, DIDLMode, Language, Container string }

type ClientTranscodeProfile struct {
	MediaType, Delivery, Context                                           string
	Containers, VideoCodecs, AudioCodecs                                   []string
	EstimateContentLength, MPEGTSM2TS, CopyTimestamps, SubtitlesInManifest bool
	SeekInfo, MaxAudioChannels                                             string
	MinSegments, SegmentLength                                             int
	BreakOnNonKeyFrames, AudioVBR                                          *bool
	Conditions                                                             []ClientProfileCondition
}

type Collection struct {
	Key          RatingKey `json:"key"`
	Title        string    `json:"title"`
	Summary      string    `json:"summary,omitempty"`
	Kind         string    `json:"kind"` // "franchise", "trending", "smart", "user"
	Type         MediaType `json:"type"`
	Filter       *Filter   `json:"filter,omitempty"` // smart
	Sort         SortOrder `json:"sort,omitempty"`
	OwnerUserID  int64     `json:"ownerUserId,omitempty"` // 0 = server-wide
	PosterPath   string    `json:"posterPath,omitempty"`
	BackdropPath string    `json:"backdropPath,omitempty"`
	ChildCount   int       `json:"childCount"`
	Upcoming     bool      `json:"upcoming,omitempty"` // admits scoped future placeholders
	// UpdatedAt changes when the collection's members or artwork change, so
	// Plex clients refetch artwork (additive).
	UpdatedAt time.Time `json:"updatedAt,omitempty"`
}

type CollectionArtwork struct {
	Mode   string `json:"mode"` // auto | collage | backdrop | tmdb | custom
	URL    string `json:"url,omitempty"`
	Accent string `json:"accent,omitempty"` // "#rrggbb"
}

type CollectionArtworkSource interface {
	CollectionArtwork(context.Context, *User, RatingKey, string, int) ([]byte, string, bool, error)
}

type CollectionLayoutSource interface {
	LayoutRow(context.Context, *User, HubContext, string) (*CollectionRow, error)
}

type CollectionPlaceholder interface {
	AllowsPlaceholders(context.Context, *User, RatingKey, string) bool
	Placeholder(context.Context, *User, RatingKey, RatingKey, string) (*Title, error)
	FindPlaceholder(context.Context, *User, RatingKey, string) (*Title, RatingKey, error)
}

type CollectionPreview struct {
	Total    int      `json:"total"`
	Items    []Title  `json:"items"`
	Warnings []string `json:"warnings"`
	TookMs   int64    `json:"tookMs"`
}

type CollectionRotate struct {
	Size  int    `json:"size"`
	Every string `json:"every"` // "daily" | "weekly"
}

type CollectionRow struct {
	Hub          Hub    `json:"hub"`
	CollectionID string `json:"collectionId"`
	HomeRow      bool   `json:"homeRow"`
	SectionRow   bool   `json:"sectionRow"`
}

type CollectionRows interface {
	HomeRowsFor(ctx context.Context, user *User, hc HubContext) ([]CollectionRow, error)
}

type CollectionRule struct {
	Field string          `json:"field"`
	Op    string          `json:"op"`
	Value json.RawMessage `json:"value"`
	Label string          `json:"label,omitempty"`
}

type CollectionSchedule struct {
	Days     []int    `json:"days,omitempty"`
	FromHour *int     `json:"fromHour,omitempty"`
	ToHour   *int     `json:"toHour,omitempty"`
	Devices  []string `json:"devices,omitempty"`
}

type CollectionSource struct {
	Kind      string            `json:"kind"`
	List      string            `json:"list,omitempty"`
	MediaType string            `json:"mediaType,omitempty"`
	ID        int64             `json:"id,omitempty"`
	Label     string            `json:"label,omitempty"`
	Params    map[string]string `json:"params,omitempty"`
	Region    string            `json:"region,omitempty"`
	URL       string            `json:"url,omitempty"`
	Keys      []string          `json:"keys,omitempty"`
	// Role narrows tmdbPerson credits: "cast", "director", "writer",
	// "crew" or "" (every credit). Additive to the contract.
	Role string `json:"role,omitempty"`
}

type CollectionSpec struct {
	ID          string             `json:"id,omitempty"` // server-assigned
	Name        string             `json:"name"`
	Description string             `json:"description,omitempty"`
	MediaType   string             `json:"mediaType"` // "movie" | "show" | "mixed"
	Sources     []CollectionSource `json:"sources"`
	Match       string             `json:"match"` // "all" | "any"
	Rules       []CollectionRule   `json:"rules"`
	Exclude     []CollectionRule   `json:"exclude"`
	// Sort: popularity | rating | released | title | added | random | personal | source.
	Sort          string            `json:"sort"`
	SortDesc      bool              `json:"sortDesc"`
	Limit         int               `json:"limit"`   // 0 = no limit
	Refresh       string            `json:"refresh"` // live | hourly | daily | weekly
	Rotate        *CollectionRotate `json:"rotate,omitempty"`
	Artwork       CollectionArtwork `json:"artwork"`
	Targets       CollectionTargets `json:"targets"`
	Enabled       bool              `json:"enabled"`
	LocalOnly     bool              `json:"localOnly,omitempty"`     // evaluate rules against the local catalogue only; no remote discovery
	ReleaseMode   string            `json:"releaseMode,omitempty"`   // released (default), upcoming, or mixed
	LookaheadDays int               `json:"lookaheadDays,omitempty"` // 1..366 when upcoming is enabled
	TemplateID    string            `json:"templateId,omitempty"`
	// Server-maintained.
	UpdatedAt   *time.Time `json:"updatedAt,omitempty"`
	LastBuiltAt *time.Time `json:"lastBuiltAt,omitempty"`
	ItemCount   int        `json:"itemCount"`

	// Additive fields beyond the contract (read-only for clients).
	BuiltIn   bool     `json:"builtIn,omitempty"`   // shipped with Ether; only targets/artwork/rotate/enabled are editable
	RatingKey string   `json:"ratingKey,omitempty"` // the Plex ratingKey of the published collection
	Warnings  []string `json:"warnings,omitempty"`  // from the last build
	// OwnerUserID is set for private collections created by a Plex user
	// (core.Collections.CreateSmart); 0 = server-wide.
	OwnerUserID int64 `json:"ownerUserId,omitempty"`
}

type CollectionSpecSource interface {
	ListSpecs(context.Context) ([]CollectionSpec, error)
}

type CollectionTargets struct {
	CollectionsTab bool                `json:"collectionsTab"`
	HomeRow        bool                `json:"homeRow"`
	SectionRow     bool                `json:"sectionRow"`
	Users          UserTargets         `json:"users"`
	Schedule       *CollectionSchedule `json:"schedule,omitempty"`
}

type CollectionTemplate struct {
	ID          string         `json:"id"`
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Category    string         `json:"category"`
	Spec        CollectionSpec `json:"spec"`
}

type Collections interface {
	List(ctx context.Context, user *User, t MediaType) ([]Collection, error)
	Get(ctx context.Context, user *User, key RatingKey) (*Collection, error)
	Items(ctx context.Context, user *User, key RatingKey, offset, limit int) (Page, error)
	CreateSmart(ctx context.Context, c Collection) (*Collection, error)
	DeleteSmart(ctx context.Context, key RatingKey) error
}

type ContextReaderAt interface {
	ReadAtContext(context.Context, []byte, int64) (int, error)
}

type ContextualRecommender interface {
	HomeHubsFor(ctx context.Context, user *User, hc HubContext, limit int) ([]Hub, error)
	SectionHubsFor(ctx context.Context, user *User, t MediaType, hc HubContext, limit int) ([]Hub, error)
}

type CreditFilter struct {
	People  []int64 `json:"people,omitempty"`
	Kind    string  `json:"kind,omitempty"`
	Exclude bool    `json:"exclude,omitempty"`
}

type CustomFormat struct {
	ID             string                `json:"trash_id"`
	Name           string                `json:"name"`
	Scores         map[string]int        `json:"trash_scores,omitempty"`
	Specifications []FormatSpecification `json:"specifications"`
	// App names the Starr app whose enum values the specifications use:
	// Sonarr numbers sources differently from Radarr. Empty means Radarr.
	App string `json:"app,omitempty"`
}

type DASHSession interface {
	HLSSession
	// ServeManifest writes the MPD.
	ServeManifest(w http.ResponseWriter, r *http.Request)
	// ServeInit writes the initialization segment of a representation.
	ServeInit(w http.ResponseWriter, r *http.Request, rep int)
	// ServeMedia writes media segment n of a representation, waiting for
	// ffmpeg and restarting it at the right offset when a seek jumps ahead.
	ServeMedia(w http.ResponseWriter, r *http.Request, rep, n int)
}

type DamageReporter interface{ SetDamageHandler(func(int64, int64) bool) }

type DateFilter struct {
	Op      string `json:"op,omitempty"`
	Unix    int64  `json:"unix,omitempty"`
	SpanDay bool   `json:"spanDay,omitempty"`
}

type DecideOptions struct {
	// DisableVideoTranscode prevents optional enhancement from promoting direct playback.
	DisableVideoTranscode bool

	DirectPlay     bool     // client allows direct play
	DirectStream   bool     // client allows remux
	MaxBitrateKbps int      // client-requested cap (maxVideoBitrate)
	MaxHeight      int      // from videoResolution
	AudioStream    int      // selected stream index, -1 default
	SubtitleStream int      // -1 none
	AudioFilters   []string // trusted owner/viewer audio processing; forces audio encoding
	BurnSubtitles  bool
	// Protocol is the conversion protocol the client asked for (hls, dash,
	// http). Empty keeps the HLS target. Additive.
	Protocol string
}

type Decision struct {
	Enhancement VideoEnhancement `json:"enhancement,omitempty"`

	Kind       DecisionKind `json:"kind"`
	VideoCopy  bool         `json:"videoCopy"`
	AudioCopy  bool         `json:"audioCopy"`
	VideoCodec string       `json:"videoCodec"` // target codec when transcoding
	AudioCodec string       `json:"audioCodec"`
	Container  string       `json:"container"` // "mpegts" (HLS) or original
	MaxHeight  int          `json:"maxHeight"`
	// H264Level is a verified output level_idc for a constrained H.264 encode.
	// Zero retains the encoder's existing automatic selection.
	H264Level int `json:"h264Level,omitempty"`
	// H264FrameRate bounds the selected encoder output rate for that level.
	H264FrameRate  float64  `json:"h264FrameRate,omitempty"`
	BitrateKbps    int      `json:"bitrateKbps"`
	AudioStream    int      `json:"audioStream"`
	SubtitleStream int      `json:"subtitleStream"` // -1 none
	BurnSubtitles  bool     `json:"burnSubtitles"`
	Reason         string   `json:"reason"`
	AudioFilters   []string `json:"audioFilters,omitempty"`
	// AudioChannels and AudioSampleRate keep the already negotiated audio
	// decoder configuration across a source change. Zero uses the normal
	// encoder defaults.
	AudioChannels   int `json:"audioChannels,omitempty"`
	AudioSampleRate int `json:"audioSampleRate,omitempty"`

	// ToneMap converts HDR (HDR10, HLG, Dolby Vision) video to SDR while
	// transcoding, for clients without HDR support.
	ToneMap bool `json:"toneMap,omitempty"`

	// StripDolbyVision copies the compatible HDR10 base layer while
	// removing Dolby Vision RPU/configuration data; it never re-encodes.
	StripDolbyVision bool `json:"stripDolbyVision,omitempty"`
}

type DecisionCandidate struct {
	ReleaseID     string
	Name          string
	Height        int
	Size          int64
	Score         float64
	Rejected      bool
	Reason        string
	Healthy       bool
	HealthChecked bool
}

type DecisionKind string

type DecisionTrace struct {
	Profile            string
	ProfileMaxHeight   int
	ClientMaxHeight    int
	EffectiveMaxHeight int
	AllowHDR           bool
	AllowDolbyVision   bool
	Chooser            string
	ChosenVersion      string
	Candidates         []DecisionCandidate
}

type DecisionTraceSource interface {
	LatestDecision(key RatingKey) (DecisionTrace, bool)
}

type DelegationAuth interface {
	IssueDelegation(context.Context, int64) (string, error)
}

type Device struct {
	ID         string
	Client     string
	Product    string
	Version    string
	Platform   string
	DeviceName string
	Language   string
}

type DirectPlayRetrier interface{ RetryDirectPlay() bool }

type DownloadAccessPolicy interface{ AllowDownloads(*User) bool }

type DownloadRemuxRequest struct {
	// InputURL is the loopback URL of the playback session feeding ffmpeg.
	InputURL string
	// Info is the probed media info of the resolved source.
	Info MediaInfo
	// AudioStream is the source stream index to keep; -1 picks the
	// default (first) audio stream.
	AudioStream int
	// ViewerID bounds converting downloads to one encode per viewer.
	// Zero skips the per-viewer encode lock (copy remuxes do not take it).
	ViewerID int64
	// Caps is the requesting client's download profile. Empty uses
	// H.264/HEVC + AAC/AC3 in MP4, the mobile download target.
	Caps ClientCaps
	// Options are the per-request transcode choices (bitrate, height, burn).
	Options DecideOptions
}

type DownloadRemuxer interface {
	// RemuxDownload copies or converts a resolved source to a temp MP4,
	// reporting progress as a fraction in [0,1] when progress is non-nil.
	// Cancelling ctx kills ffmpeg and removes the partial file.
	RemuxDownload(ctx context.Context, req DownloadRemuxRequest, progress func(fraction float64)) (path string, size int64, err error)
	// ReleaseDownload deletes a remuxed file and frees its budget.
	// Releasing an unknown path is a no-op.
	ReleaseDownload(path string)
}

type DurablePrefetcher interface {
	DurablePrefetch(context.Context, string, []byte, int64, int64) error
}

type EncoderInputLease interface {
	// ClaimInput succeeds once, before seal. Failed claims never call onDrained.
	// Successful claims call it exactly once, possibly before this returns,
	// after sealed producers and registry ownership are released. The trusted
	// callback must only do bounded accounting/requeue; no I/O, waits or source
	// operations. It runs outside every manager/session/scope lock.
	ClaimInput(onDrained func(error)) error
	HeadersForInput(inputURL string) (map[string]string, error)
	SealInput()
	InputDone() <-chan struct{}
	InputErr() error
}

type EncoderRetirement interface {
	EncoderDone() <-chan struct{}
	EncoderErr() error
}

type Engine interface {
	// Open builds the byte-offset index for the main video file of an NZB.
	Open(ctx context.Context, releaseID string, nzb []byte) (MediaSource, error)
	// Prefetch warms [offset, offset+length) at background priority.
	Prefetch(ctx context.Context, releaseID string, nzb []byte, offset, length int64) error
}

type ExactVariantPlayback interface {
	PrepareExactVariant(ctx context.Context, user *User, key RatingKey, caps ClientCaps, releaseID string) (*PlaySession, error)
}

type FacetValue struct {
	ID    string `json:"id,omitempty"` // Stable namespace-aware neutral identifier.
	Key   string `json:"key"`
	Title string `json:"title"`
	Count int    `json:"count"`
	// Labels are the equivalent values Key stands for, where a facet groups
	// them (content-rating levels list every board's label).
	Labels []string `json:"labels,omitempty"`
}

type Filter struct {
	KnownAddedDate bool `json:"-"` // only released/aired titles, before pagination
	// ExcludeKeys applies local visibility policy before counting and pagination.
	ExcludeKeys []RatingKey `json:"-"`
	// IncludeKeys, when set, restricts the page to these keys before
	// counting and pagination. An empty list matches nothing.
	IncludeKeys []RatingKey `json:"-"`
	// ExcludeGenres and ExcludeKeywords remove viewer-blocked facts before
	// counting and pagination. Matching is case-insensitive.
	ExcludeGenres         []string        `json:"-"`
	ExcludeKeywords       []string        `json:"-"`
	AddedAfter            int64           `json:"-"`              // inclusive Unix timestamp bound on added/release time
	AddedBefore           int64           `json:"-"`              // inclusive Unix timestamp bound on added/release time
	UpdatedAfter          int64           `json:"-"`              // inclusive Unix timestamp bound on metadata update time
	UpdatedBefore         int64           `json:"-"`              // inclusive Unix timestamp bound on metadata update time
	Type                  MediaType       `json:"type,omitempty"` // movie or show
	Genres                []string        `json:"genres,omitempty"`
	Keywords              []string        `json:"keywords,omitempty"` // every keyword must match (case-insensitive)
	YearFrom              int             `json:"yearFrom,omitempty"`
	YearTo                int             `json:"yearTo,omitempty"`
	Years                 []int           `json:"years,omitempty"`
	ExcludeYears          []int           `json:"excludeYears,omitempty"`
	MinRating             float64         `json:"minRating,omitempty"`
	MaxRating             float64         `json:"maxRating,omitempty"`
	ExcludeRatings        []float64       `json:"excludeRatings,omitempty"`
	MaxRuntime            time.Duration   `json:"maxRuntime,omitempty"`
	MinRuntime            time.Duration   `json:"minRuntime,omitempty"`
	ExcludeRuntimes       []time.Duration `json:"excludeRuntimes,omitempty"`
	Languages             []string        `json:"languages,omitempty"`
	Countries             []string        `json:"countries,omitempty"`
	ExcludeCountries      []string        `json:"excludeCountries,omitempty"`
	ContentRatings        []string        `json:"contentRatings,omitempty"`
	ExcludeContentRatings []string        `json:"excludeContentRatings,omitempty"`
	MaxContentRating      string          `json:"maxContentRating,omitempty"` // per-user limit
	// SaferPlexRating applies cached Plex content-rating levels in SQL
	// together with MaxContentRating so paging and counts stay correct.
	SaferPlexRating bool `json:"-"`

	Collection         int64          `json:"collection,omitempty"`
	Collections        []int64        `json:"collections,omitempty"`
	ExcludeCollections []int64        `json:"excludeCollections,omitempty"`
	Person             int64          `json:"person,omitempty"` // cast or crew TMDB id
	Credits            []CreditFilter `json:"credits,omitempty"`
	Studio             string         `json:"studio,omitempty"`
	StudioFilters      []StringFilter `json:"studioFilters,omitempty"`
	FirstCharacter     string         `json:"firstCharacter,omitempty"`
	Query              string         `json:"query,omitempty"` // title substring
	TitleFilters       []StringFilter `json:"titleFilters,omitempty"`
	ReleasedFilters    []DateFilter   `json:"releasedFilters,omitempty"`
	// MinContentRating is an additive share-policy predicate (plex.tv share
	// filters). It does not replace MaxContentRating or ContentRatings.
	MinContentRating string `json:"-"`
	// IncludeCollectionNames / ExcludeCollectionNames match
	// Title.CollectionName (plex.tv share label filters). An empty
	// collection name is unmappable and is not excluded.
	IncludeCollectionNames []string `json:"-"`
	ExcludeCollectionNames []string `json:"-"`
}

type FormatSpecification struct {
	Name           string                     `json:"name"`
	Implementation string                     `json:"implementation"`
	Negate         bool                       `json:"negate"`
	Required       bool                       `json:"required"`
	Fields         map[string]json.RawMessage `json:"fields"`
}

type GoodputSession interface {
	// GoodputKbps is the rolling segment-delivery estimate; 0 unknown.
	GoodputKbps() int
}

type HLSIndependentSegments interface {
	IndependentSegments() bool
}

type HLSLadderSession interface {
	HLSSession
	// Rungs lists the ladder, highest first; Rungs()[0] is "base".
	Rungs() []HLSRung
	// ServeRungPlaylist writes rung's media playlist.
	ServeRungPlaylist(w http.ResponseWriter, r *http.Request, rung string)
	// ServeRungSegment writes segment n of rung (InitSegment numbering as
	// in ServeSegment: the caller passes the parsed segment number).
	ServeRungSegment(w http.ResponseWriter, r *http.Request, rung string, n int)
}

type HLSRequest struct {
	// RequireIndependentProof emits HLS independence tags only when the
	// session can guarantee every advertised segment is independently decodable.
	// Zero preserves the legacy playlist contract for existing callers.
	RequireIndependentProof bool
	SessionID               string
	InputURL                string // ffmpeg input; Ether serves sources on loopback HTTP with range support
	// LiveInput permits playlist demuxers for owner-configured live sources.
	// Ordinary resolved media must leave this false, even if duration is unknown.
	LiveInput bool
	// InputHeaders are optional HTTP headers ffmpeg must send when reading
	// InputURL (e.g. for resolved trailer URLs). Transcoders that cannot
	// send headers ignore them; most resolved URLs need none (additive).
	InputHeaders map[string]string
	// InputLease is trusted host composition only, never decoded from wire
	// requests. A caller retains an unclaimed lease if admission fails early.
	InputLease  EncoderInputLease `json:"-"`
	Info        MediaInfo
	Decision    Decision
	StartOffset time.Duration
	// SegmentDuration defaults to 4s when zero (5s for DASH).
	SegmentDuration time.Duration
	// Protocol is ProtocolHLS (default when empty), ProtocolDASH, or
	// ProtocolHTTP (Plex for Mac / Desktop's chunked Matroska stream;
	// the constant lives with the other "http" protocol name in debrid.go).
	// A DASH session also implements DASHSession; an HTTP session also
	// implements HTTPSession. Transcoder.Session returns either as an
	// HLSSession, so type-assert to reach the protocol methods.
	Protocol string
}

type HLSRung struct {
	// ID is the rung's URL component: session/{id}/{ID}/index.m3u8. The
	// primary rung is always "base" (served by the HLSSession methods).
	ID string
	// Bandwidth is the peak bitrate in bits per second (#EXT-X-STREAM-INF
	// BANDWIDTH / DASH Representation bandwidth).
	Bandwidth int
	// AverageBandwidth is the average bitrate in bits per second.
	AverageBandwidth int
	Width            int
	Height           int
	// Codecs is an RFC 6381 codecs string ("avc1...,mp4a...").
	Codecs    string
	FrameRate float64
}

type HLSSession interface {
	ID() string
	// ServePlaylist writes the media playlist (index.m3u8).
	ServePlaylist(w http.ResponseWriter, r *http.Request)
	// ServeSegment writes segment n, waiting for ffmpeg to produce it and
	// restarting ffmpeg at the right offset when a seek jumps ahead.
	ServeSegment(w http.ResponseWriter, r *http.Request, n int)
	// SwapInput restarts the session on a new input at the given position
	// (mid-stream failover). Segment numbering continues.
	SwapInput(ctx context.Context, inputURL string, info MediaInfo, at time.Duration) error
	LastAccess() time.Time
	Close() error
}

type HTTPSession interface {
	HLSSession
	ServeHTTP(w http.ResponseWriter, r *http.Request)
}

type HWAccel struct {
	Name     string   `json:"name"` // "videotoolbox", "nvenc", "qsv", "vaapi", "none"
	Encoders []string `json:"encoders"`
	Device   string   `json:"device,omitempty"`
	// NoGPUScale: the encoder works but the device's video processing
	// (VAAPI scale_vaapi) does not, so frames are decoded and scaled in
	// software and uploaded to the encoder.
	NoGPUScale bool `json:"noGpuScale,omitempty"`
	// NoGPUTonemap: the device's VAAPI VPP cannot run tonemap_vaapi, so HDR
	// tone-mapping falls back to the software zscale/tonemap path.
	NoGPUTonemap bool `json:"noGpuTonemap,omitempty"`
	// VAAPIQualityRC / VAAPIBitrateRC record the probed VAAPI rate-control
	// modes ("QVBR", "VBR", "CBR", "CQP") per encoder ("h264_vaapi",
	// "hevc_vaapi"); nil/empty falls back to the default QVBR/VBR modes.
	VAAPIQualityRC map[string]string `json:"vaapiQualityRc,omitempty"`
	VAAPIBitrateRC map[string]string `json:"vaapiBitrateRc,omitempty"`
}

type HealthChecker interface {
	Check(ctx context.Context, nzb []byte) (healthy bool, err error)
}

type HistoryEntry struct {
	UserID    int64     `json:"userId"`
	Key       RatingKey `json:"key"`
	ViewedAt  time.Time `json:"viewedAt"`
	Completed bool      `json:"completed"`
}

type HomeCandidateSource interface {
	HomeCandidatesFor(context.Context, *User, HubContext, int) ([]Hub, error)
}

type HomeLayout struct {
	Global    []LayoutPage   `json:"global"`
	Viewers   []ViewerLayout `json:"viewers"`
	UpdatedAt time.Time      `json:"updatedAt,omitempty"`
}

type HomeLayoutSource interface {
	FinalizeHome(context.Context, *User, HubContext, string, []Hub) ([]Hub, error)
}

type HomePreview struct {
	Rows        []HomeRow  `json:"rows"`
	GeneratedAt time.Time  `json:"generatedAt"`
	Context     HubContext `json:"context"`
	// HomeDeduped counts the titles kept off a Movies or TV Shows page
	// because the viewer's Home leads with them (DedupeHome).
	HomeDeduped int `json:"homeDeduped,omitempty"`
}

type HomeRow struct {
	HubID        string               `json:"hubId"`
	Layer        string               `json:"layer,omitempty"`
	Slot         int                  `json:"slot,omitempty"`
	AnchorSlot   int                  `json:"anchorSlot,omitempty"`
	Placement    string               `json:"placement,omitempty"`
	HiddenReason string               `json:"hiddenReason,omitempty"`
	Policy       *RowPolicy           `json:"policy,omitempty"`
	PolicyLayer  string               `json:"policyLayer,omitempty"`
	Title        string               `json:"title"`
	Kind         string               `json:"kind"` // e.g. "because-you-watched", "collection:<id>"
	Reason       string               `json:"reason"`
	Score        float64              `json:"score"` // predicted engagement used for ordering
	Pinned       bool                 `json:"pinned,omitempty"`
	Hidden       bool                 `json:"hidden,omitempty"` // hidden by a layout rule: not sent to Plex
	Source       string               `json:"source"`
	Items        []Title              `json:"items"`
	ItemReasons  map[RatingKey]string `json:"itemReasons,omitempty"`
	// Hub is the row as handed to the Plex front end.
	Hub Hub `json:"-"`
}

type HomeSituation struct {
	Device, Daypart                        string
	Weekend                                bool
	Now                                    time.Time
	LibraryID                              int
	Product, Platform, SessionID, ClientID string
}

type Hub struct {
	ID       string    `json:"id"` // stable identifier, e.g. "trending.week.movie"
	Title    string    `json:"title"`
	Type     MediaType `json:"type"`            // item type in the row ("mixed" allowed via "")
	Context  string    `json:"context"`         // Plex hub context, e.g. "hub.movie.recentlyreleased"
	Style    string    `json:"style,omitempty"` // "shelf", "hero", "clip"
	Promoted bool      `json:"promoted"`        // show on Home
	Items    []Title   `json:"items"`
	More     bool      `json:"more"`
	Key      RatingKey `json:"key,omitempty"` // backing collection, if any
	// ItemCount carries rendered availability when a front end retains the
	// actual metadata and asks only for row placement.
	ItemCount int `json:"itemCount,omitempty"`
}

type HubContext struct {
	Device    string    `json:"device"`
	Daypart   string    `json:"daypart"`
	Weekend   bool      `json:"weekend"`
	Now       time.Time `json:"now"`
	SectionID int       `json:"sectionId,omitempty"`
	Product   string    `json:"product,omitempty"`  // X-Plex-Product
	Platform  string    `json:"platform,omitempty"` // X-Plex-Platform
	SessionID string    `json:"sessionId,omitempty"`
	ClientID  string    `json:"clientId,omitempty"`
}

type HubImpression struct {
	UserID   int64       `json:"userId"`
	HubID    string      `json:"hubId"`
	Position int         `json:"position"`
	Keys     []RatingKey `json:"keys"`
	Context  HubContext  `json:"context"`
	At       time.Time   `json:"at"`
}

type HubItemSource interface {
	HubItemsFor(context.Context, *User, HubContext, string, int) (Hub, bool)
}

type IDs struct {
	TMDB int64  `json:"tmdb,omitempty"`
	IMDB string `json:"imdb,omitempty"`
	TVDB int64  `json:"tvdb,omitempty"`
}

type Identity interface {
	Resolve(ctx context.Context, surface, credential string) (*Viewer, error)
}

type ImageURLFunc func(path, size string) string

type ImpressionSink interface {
	RecordImpressions(user *User, hc HubContext, hubs []Hub)
}

type Indexer interface {
	Name() string
	Search(ctx context.Context, req SearchRequest) ([]Release, error)
	FetchNZB(ctx context.Context, r Release) ([]byte, error)
}

type IntentTracker interface {
	// RecordDetailOpen notes that a viewer opened a title's detail page.
	RecordDetailOpen(ctx context.Context, user *User, t *Title)
	// NotePlayback notes that playback of key started; an open for the
	// same title moments earlier was a conversion, not browsing intent.
	NotePlayback(user *User, key RatingKey)
}

type KeyKind int

type KeyframePoint struct {
	Offset int64         `json:"offset"`
	Time   time.Duration `json:"time"`
}

type LayoutPage struct {
	Section       string         `json:"section"`
	MaxRows       int            `json:"maxRows,omitempty"`
	DeviceMaxRows map[string]int `json:"deviceMaxRows,omitempty"`
	Rows          []RowPolicy    `json:"rows"`
	// DedupeHome keeps titles the viewer's Home leads with off this page
	// (Movies/TV Shows only). Nil means the default: on.
	DedupeHome *bool `json:"dedupeHome,omitempty"`
	// Tuning shapes how the page's rows and titles are chosen. Nil fields
	// inherit (viewer page → global page → engine default).
	Tuning *LayoutTuning `json:"tuning,omitempty"`
}

type LayoutTuning struct {
	// Discovery: 0 sticks to proven favourites, 1 explores new territory.
	Discovery *float64 `json:"discovery,omitempty"`
	// Freshness: 0 favours timeless picks, 1 favours new and trending.
	Freshness *float64 `json:"freshness,omitempty"`
	// Variety: 0 keeps rows focused on the strongest tastes, 1 spreads
	// across genres, eras and moods.
	Variety *float64 `json:"variety,omitempty"`
}

type LayoutWhen struct {
	Days      []int    `json:"days,omitempty"`
	Dayparts  []string `json:"dayparts,omitempty"`
	Months    []int    `json:"months,omitempty"`
	StartDate string   `json:"startDate,omitempty"`
	EndDate   string   `json:"endDate,omitempty"`
	FromHour  *int     `json:"fromHour,omitempty"`
	ToHour    *int     `json:"toHour,omitempty"`
	Devices   []string `json:"devices,omitempty"`
}

type LibraryExclusion struct {
	// Name is optional. Clients label a rule from its conditions.
	Name      string           `json:"name"`
	Action    string           `json:"action,omitempty"` // show, hide; empty means hide
	MediaType string           `json:"mediaType"`        // movie, show, mixed
	Match     string           `json:"match"`            // all, any
	Rules     []CollectionRule `json:"rules"`
}

type LikesState interface {
	SetLikes(context.Context, int64, RatingKey, *bool) error
}

type LocalFileSource interface{ LocalFile() *os.File }

type LookupResult struct {
	ID        int64  `json:"id"`
	Name      string `json:"name"`
	Subtitle  string `json:"subtitle,omitempty"`
	ImagePath string `json:"imagePath,omitempty"` // TMDB image path
}

type MarkedPlaylists interface {
	MarkedPlaylist(context.Context, int64, string) (*Playlist, error)
	EnsureMarkedPlaylist(context.Context, int64, string, string) (*Playlist, error)
}

type MediaInfo struct {
	Chapters    []Chapter     `json:"chapters,omitempty"`
	Container   string        `json:"container"` // mkv, mp4, avi, mpegts
	Duration    time.Duration `json:"duration"`
	Size        int64         `json:"size"`
	BitrateKbps int           `json:"bitrateKbps"`
	Streams     []StreamInfo  `json:"streams"`
	Estimated   bool          `json:"estimated"` // derived from release name, not probed

	// Keyframes is the container's keyframe/cue index, sorted, when it was
	// read on open or probe; empty when unknown. Not serialized: it can hold
	// thousands of points (additive).
	Keyframes []KeyframePoint `json:"-"`
}

type MediaSource interface {
	io.ReaderAt
	Size() int64
	Name() string // file name inside the release, e.g. "Movie.2024.1080p.mkv"
	ReleaseID() string
	Close() error
}

type MediaType string

type MetadataReaderAt interface {
	ReadMetadataAtContext(context.Context, []byte, int64) (int, error)
}

type MicroReason struct {
	Header       string    `json:"header,omitempty"`
	MatchPercent int       `json:"matchPercent,omitempty"`
	HasMatch     bool      `json:"hasMatch,omitempty"`
	Reason       string    `json:"reason,omitempty"`
	EndsAt       time.Time `json:"endsAt,omitempty"`
	HasEnd       bool      `json:"hasEnd,omitempty"`
}

type MicroReasoner interface {
	MicroReason(ctx context.Context, user *User, t *Title, now time.Time) MicroReason
}

type NeutralEntryRef struct{ Kind, ID string }

type NeutralHomeLayoutSource interface {
	FinalizeNeutralHome(context.Context, *User, HomeSituation, string, []NeutralHomeRow) ([]NeutralHomeRow, error)
}

type NeutralHomeRow struct {
	ID, Title, Kind string
	Purpose         RowPurpose
	Type            MediaType
	Items           []Title
	ItemCount       int
}

type NeutralImpression struct {
	Situation          HomeSituation
	RowID, Kind, Title string
	Purpose            RowPurpose
	Rank               int
	Items              []RatingKey
	Collection         RatingKey
	Item               RatingKey // Parent item for detail rows.
	Placement, ViewID  string
	Entries            []NeutralEntryRef
}

type NeutralImpressionSink interface {
	RecordNeutralImpression(*User, NeutralImpression)
}

type OriginSource interface {
	Origin() string
}

type OwnedEncoderSession interface {
	HLSSession
	EncoderRetirement() EncoderRetirement
	RetireEncoder() error
}

type OwnedSourcePlayback interface {
	PrepareSurfaceSource(context.Context, *User, RatingKey, ClientCaps, string, bool) (*PlaySession, SourceRetirement, error)
	SourceRetirement(string) (SourceRetirement, bool)
	// RetireSource detaches the exact captured source lifetime and schedules
	// cleanup. Admission failure leaves the session attached. It is idempotent
	// for the same lifetime and cannot detach a replacement.
	RetireSource(string, SourceRetirement) error
}

type OwnedTranscoder interface {
	StartHLSOwned(context.Context, HLSRequest) (HLSSession, EncoderRetirement, error)
}

type Page struct {
	Items []Title
	Total int
}

type Person struct {
	TMDB      int64  `json:"tmdb,omitempty"`
	IMDB      string `json:"imdb,omitempty"`
	ID        string `json:"id,omitempty"` // catalogue person id when there is no TMDB id
	Name      string `json:"name"`
	Role      string `json:"role,omitempty"` // character for cast, job for crew
	ThumbPath string `json:"thumbPath,omitempty"`
}

type PersonalScorer interface {
	ScoreTitles(ctx context.Context, user *User, titles []Title) (map[RatingKey]float64, error)
}

type PlaySession struct {
	PlaybackGroup string `json:"playbackGroup,omitempty"`
	// PreparedOnly marks a source reserved for planning but not opened by a
	// frontend. Cluster snapshots carry it for owner Activity.
	PreparedOnly bool `json:"preparedOnly,omitempty"`
	ID           string
	UserID       int64
	ClientID     string
	Key          RatingKey
	Resolution   *Resolution
	Source       MediaSource // swaps on failover; read through Playback.Source
	Info         MediaInfo
	StartedAt    time.Time

	// Status for the admin dashboard and /status/sessions, filled on the
	// snapshots Playback returns.
	TitleName      string       // "Movie (2024)" or "Show - S01E02 - Episode"
	Username       string       // user display name
	Client         ClientCaps   // the client's product, device and limits
	DecisionReason string       `json:"decisionReason,omitempty"`
	Decision       DecisionKind // directplay once bytes go straight to the client; "" until known
	BytesServed    int64        // source bytes delivered (direct play and ffmpeg input)
	SpeedBps       int64        // recent delivery rate, bytes per second
	LastActive     time.Time
	// ViewOffset is the client's last reported playhead in milliseconds.
	// Nil means no timeline has arrived; source bytes do not imply progress.
	ViewOffset *int64 `json:"viewOffset,omitempty"`
	Failovers  int    // mid-stream release swaps so far
	// Origin names where the current release streams from: "Usenet" or the
	// debrid service, such as "Real-Debrid" (additive).
	Origin string `json:"origin,omitempty"`
	// DownFailovers counts speed-driven swaps to a lower-bitrate release
	// (a subset of Failovers) (additive).
	DownFailovers int `json:"downFailovers,omitempty"`
	// RequiresRemux is set when a direct-play failover could not splice or
	// find an exact-size replacement: the next decision/start for this
	// session must be a zero-encode remux (additive).
	RequiresRemux bool `json:"requiresRemux,omitempty"`
	// Node is the cluster node serving a session reported by another node
	// (empty for this node's own sessions and on a standalone server).
	Node string `json:"node,omitempty"`
}

type Playback interface {
	// Estimate is the virtual media info shown before a title is resolved.
	Estimate(ctx context.Context, t *Title, caps ClientCaps) MediaInfo
	// Prepare resolves and opens a source for the user and client, enforcing
	// stream limits. Reuses an existing session for the same user/client/key.
	Prepare(ctx context.Context, user *User, key RatingKey, caps ClientCaps) (*PlaySession, error)
	Session(id string) (*PlaySession, bool)
	// SessionFor finds the live session of a client for a title.
	SessionFor(userID int64, clientID string, key RatingKey) (*PlaySession, bool)
	// ServeRange serves the session's current source with HTTP range
	// support, failing over to the next release when articles are missing.
	ServeRange(w http.ResponseWriter, r *http.Request, sessionID string)
	// InputURL is a loopback URL ffmpeg can read the session's source from.
	InputURL(sessionID string) string
	// Failover swaps the session to the next candidate release, keeping the
	// timestamp. Returns the new media info.
	Failover(ctx context.Context, sessionID string, at time.Duration) (*PlaySession, error)
	Stop(sessionID string)
	Sessions() []*PlaySession
}

type PlaybackAccessPolicy interface {
	CanPlay(*User, bool, time.Time) bool
}

type PlaybackEncoderInputs interface {
	ReserveEncoderInput(context.Context, string, SourceRetirement) (EncoderInputLease, error)
}

type PlaybackPosition interface{ RequestedPosition() time.Duration }

type PlaybackPreparer interface {
	PreResolve(context.Context, *User, RatingKey, ClientCaps) bool
}

type PlaybackRevisionPin interface {
	PinSourceRevision(ctx context.Context, id, revision string) error
	UnpinSourceRevision(id string)
}

type PlaybackSourceHistory struct {
	Revision, ReleaseDigest, VideoCodec string
	Height                              int
	HDR                                 *bool
}

type PlaybackSourceObservation struct {
	Revision, ReleaseID string
	VideoCodec          string
	Height              int
	HDR                 *bool
}

type PlaybackSourceSnapshot interface {
	CurrentSource(context.Context, string) (PlaybackSourceObservation, error)
}

type PlaybackTimeline interface {
	PlaybackProgress(userID int64, clientID string, key RatingKey, position time.Duration, state string)
}

type Playlist struct {
	Key       RatingKey   `json:"key"`
	UserID    int64       `json:"userId"`
	Title     string      `json:"title"`
	Smart     bool        `json:"smart"`
	Items     []RatingKey `json:"items"`
	UpdatedAt time.Time   `json:"updatedAt"`
}

type Playlists interface {
	List(ctx context.Context, userID int64) ([]Playlist, error)
	Get(ctx context.Context, userID int64, key RatingKey) (*Playlist, error)
	Create(ctx context.Context, userID int64, title string, items []RatingKey) (*Playlist, error)
	Add(ctx context.Context, userID int64, key RatingKey, items []RatingKey) error
	Remove(ctx context.Context, userID int64, key RatingKey, itemIndex int) error
	Move(ctx context.Context, userID int64, key RatingKey, from, to int) error
	Delete(ctx context.Context, userID int64, key RatingKey) error
}

type PolicyHomeCandidateSource interface {
	HomeCandidatesWithPolicy(context.Context, *User, HubContext, int, func(context.Context, *User, *Title) bool) ([]Hub, error)
	SectionCandidatesWithPolicy(context.Context, *User, MediaType, HubContext, int, func(context.Context, *User, *Title) bool) ([]Hub, error)
}

type PostPlayPick struct {
	Title      Title   `json:"title"`
	Score      float64 `json:"score"`
	TasteFit   float64 `json:"tasteFit"`
	Similarity float64 `json:"similarity"`
	RuntimeFit float64 `json:"runtimeFit"`
	Reason     string  `json:"reason,omitempty"`
}

type PostPlayer interface {
	PostPlay(ctx context.Context, user *User, justWatched RatingKey, hc HubContext, limit int) ([]PostPlayPick, error)
}

type PrefetchReaderAt interface {
	ReadAtPrefetchContext(context.Context, []byte, int64) (int, error)
}

type PrewarmOptions struct {
	// Reason labels the trigger for logs and budgets (Prewarm* constants).
	Reason string `json:"reason"`
	// PrefetchBytes is how much of the opening of the file to pre-buffer at
	// background priority once the release is resolved, opened and probed.
	// Zero uses the implementation's default for the reason.
	PrefetchBytes int64 `json:"prefetchBytes,omitempty"`
	// DuringPlayback allows the warm-up while the viewer already has an
	// active session (a trailer, or the end of a film, is playing).
	DuringPlayback bool `json:"duringPlayback,omitempty"`
}

type Prewarmer interface {
	Prewarm(ctx context.Context, user *User, key RatingKey, caps ClientCaps, opts PrewarmOptions) bool
}

type Priority int

type ProcessCPUTime interface {
	CPUTime() (time.Duration, time.Duration)
}

type ProcessIdentity interface{ PID() int }

type ProcessPeakMemory interface{ PeakRSSBytes() (uint64, bool) }

type Protocol string

type QualityProfile struct {
	ReleaseRules         []ReleaseRule  `json:"releaseRules,omitempty"`
	Ranking              []string       `json:"ranking,omitempty"`
	AllowedQualities     []string       `json:"allowedQualities,omitempty"` // imported source-resolution gates
	CustomFormatScores   map[string]int `json:"customFormatScores,omitempty"`
	MinCustomFormatScore *int           `json:"minCustomFormatScore,omitempty"`
	Name                 string         `json:"name"`
	MaxHeight            int            `json:"maxHeight"` // cap, e.g. 1080
	// ConfiguredMaxHeight is MaxHeight as the owner configured it,
	// before download reshaping or a client's caps clamped the
	// effective MaxHeight. -1 means the owner set no ceiling ("Any");
	// 0 means unset (a profile built outside SelectProfile), in which
	// case MaxHeight itself is the configured value. Runtime-only,
	// never persisted with the profile.
	ConfiguredMaxHeight    int      `json:"-"`
	MinHeight              int      `json:"minHeight"` // floor, e.g. 720
	AllowHDR               bool     `json:"allowHdr"`  // only applied when the client also supports it
	AllowDolbyVision       bool     `json:"allowDolbyVision"`
	PreferredSources       []Source `json:"preferredSources"` // best first
	PreferredCodecs        []string `json:"preferredCodecs"`  // best first; codecs the client can't play are dropped anyway
	PreferredAudio         []string `json:"preferredAudio"`
	MinSizeMBPerMin        float64  `json:"minSizeMbPerMin"` // size sanity, per minute of runtime (movies, and fallback for TV)
	MaxSizeMBPerMin        float64  `json:"maxSizeMbPerMin"`
	EpisodeMinSizeMBPerMin float64  `json:"episodeMinSizeMbPerMin,omitempty"` // optional TV episode size bounds (0 uses MinSizeMBPerMin/MaxSizeMBPerMin)
	EpisodeMaxSizeMBPerMin float64  `json:"episodeMaxSizeMbPerMin,omitempty"`
	PreferLargest          bool     `json:"preferLargest,omitempty"` // prefer larger files among candidates matching the profile
	PreferredLanguages     []string `json:"preferredLanguages"`
	AllowCam               bool     `json:"allowCam"` // the only CAM switch; cinema recordings play only for profiles that allow them
	// SelectionKey is the canonical hash of this profile's configured
	// definition, computed by resolver.SelectProfile from the pristine
	// configured profile before download reshaping or client-cap
	// clamping. Release rules are part of that definition. The catalogue
	// original language is not: it is per-title evaluation context, not a
	// profile fact. Runtime-only, never persisted with the profile.
	SelectionKey string `json:"-"`
}

type RankerFeature struct {
	Name   string  `json:"name"`
	Label  string  `json:"label"`
	Weight float64 `json:"weight"`
}

type RankerInsight struct {
	TrainedAt *time.Time `json:"trainedAt,omitempty"`
	// Examples/Positives are the impressions and plays the model last
	// trained on.
	Examples  int `json:"examples"`
	Positives int `json:"positives"`
	// AUC of the learned model and of the hand-tuned baseline on held-out
	// impressions (0.5 = chance). Zero when there is not enough data.
	AUC         float64 `json:"auc"`
	BaselineAUC float64 `json:"baselineAuc"`
	// Active is true when the learned model is being used for ranking.
	Active   bool            `json:"active"`
	Features []RankerFeature `json:"features"`
}

type RatingKey int64

type ReadRetirement struct {
	// contains filtered or unexported fields
}

type Recommender interface {
	// HomeHubs are the rows on the Home screen across both sections.
	HomeHubs(ctx context.Context, user *User, limit int) ([]Hub, error)
	// SectionHubs are the rows at the top of a library section.
	SectionHubs(ctx context.Context, user *User, t MediaType, limit int) ([]Hub, error)
	// Related are rows on a detail page ("More like this", franchise).
	Related(ctx context.Context, user *User, key RatingKey, limit int) ([]Hub, error)
}

type RecoveryBuffer struct {
	Position, ReadyUntil time.Duration
	SeekAt               time.Time // a discontinuous output request invalidates older telemetry
	// DeliveredUntil is contiguous complete HTTP delivery, not a promise that
	// the client retained or decoded it. Zero means unavailable.
	DeliveredUntil time.Duration
}

type RecoveryBufferSource interface{ RecoveryBuffer() RecoveryBuffer }

type Release struct {
	ID       string      `json:"id"`      // stable: sha1(indexer + guid)
	GUID     string      `json:"guid"`    // indexer guid
	Indexer  string      `json:"indexer"` // indexer name
	Name     string      `json:"name"`    // release name
	NZBURL   string      `json:"nzbUrl"`
	Size     int64       `json:"size"`
	PubDate  time.Time   `json:"pubDate"`
	Grabs    int         `json:"grabs,omitempty"`
	Password bool        `json:"password,omitempty"` // indexer flagged passworded
	Category int         `json:"category,omitempty"`
	Info     ReleaseInfo `json:"info"`
	Score    float64     `json:"score"`
	// TitleIDs are movie/series identifiers reported by the indexer. They
	// must never be inferred from the search request's identifiers.
	TitleIDs IDs `json:"titleIds,omitempty"`

	// Torrent releases (additive). Protocol is "" for Usenet and
	// ProtocolTorrent for Torznab results; torrents are streamed through
	// an owner-configured debrid service (internal/debrid).
	Protocol  string `json:"protocol,omitempty"`
	InfoHash  string `json:"infoHash,omitempty"` // lower-case hex BitTorrent v1 info hash
	MagnetURL string `json:"magnetUrl,omitempty"`
	Seeders   int    `json:"seeders,omitempty"`
	Peers     int    `json:"peers,omitempty"`
	// Target narrows a multi-file release (a season pack) to the wanted
	// episode; set by the resolver on candidates before fetching.
	Target *ReleaseTarget `json:"target,omitempty"`
	// DebridCached and DebridUncached name the debrid services (config
	// Debrid* kinds) the source reported as holding, or not holding, the
	// torrent, such as a Stremio addon's cached marker (additive). Hints
	// only: a provider's own answer always wins.
	DebridCached   []string `json:"debridCached,omitempty"`
	DebridUncached []string `json:"debridUncached,omitempty"`
	// HTTP stream releases (ProtocolHTTP, additive). StreamURL is the URL
	// the addon answered with; it and StreamHeaders (request headers the
	// addon requires) can carry the addon's credentials, so they never
	// leave the server. StreamOrigin is the owner-configured addon origin
	// (scheme://host:port), the only private address the URL may reach.
	StreamURL     string            `json:"streamUrl,omitempty"`
	StreamHeaders map[string]string `json:"streamHeaders,omitempty"`
	StreamOrigin  string            `json:"streamOrigin,omitempty"`
}

type ReleaseBlockChecker interface {
	ReleaseBlocked(context.Context, string) (bool, error)
}

type ReleaseCondition struct {
	Field    string  `json:"field"`
	Operator string  `json:"operator"` // equals, contains, regex, range
	Value    string  `json:"value,omitempty"`
	Min      float64 `json:"min,omitempty"`
	Max      float64 `json:"max,omitempty"`
}

type ReleaseFeed struct {
	Categories []int  `json:"categories,omitempty"` // local filter when a feed ignores category queries
	ID         string `json:"id"`
	Name       string `json:"name"`
	Generation string `json:"-"`
	Protocol   string `json:"protocol"`
	Supported  bool   `json:"supported"`
	Reason     string `json:"reason,omitempty"`
	// DailyLimit is the indexer's own cap. Zero means unlimited.
	DailyLimit int `json:"dailyLimit,omitempty"`
	// PageMax is the page size reported by caps. Zero means unknown.
	PageMax int `json:"pageMax,omitempty"`
}

type ReleaseHealthChecker interface {
	HealthChecker
	CheckRelease(ctx context.Context, releaseID string, nzb []byte) (healthy bool, err error)
}

type ReleaseInfo struct {
	Title       string   `json:"title"`
	Edition     string   `json:"edition,omitempty"`
	Year        int      `json:"year,omitempty"`
	Seasons     []int    `json:"seasons,omitempty"`
	Episodes    []int    `json:"episodes,omitempty"`
	FullSeason  bool     `json:"fullSeason,omitempty"`
	Height      int      `json:"height,omitempty"` // 480, 720, 1080, 2160
	Source      Source   `json:"source,omitempty"`
	VideoCodec  string   `json:"videoCodec,omitempty"` // h264, hevc, av1
	HDR10       bool     `json:"hdr10,omitempty"`
	DolbyVision bool     `json:"dolbyVision,omitempty"`
	AudioCodec  string   `json:"audioCodec,omitempty"` // aac, ac3, eac3, truehd, dts, dtshd
	Atmos       bool     `json:"atmos,omitempty"`
	Channels    string   `json:"channels,omitempty"` // "5.1"
	Group       string   `json:"group,omitempty"`
	Languages   []string `json:"languages,omitempty"`
	// SubtitleLanguages are subtitle languages a release declares without
	// claiming the audio (VOSTFR, VOSE, SUBFRENCH) (additive).
	SubtitleLanguages []string `json:"subtitleLanguages,omitempty"`
	// AbsoluteEpisodes are episode numbers counted from the series start,
	// as anime releases number them ("Show - 1071") (additive).
	AbsoluteEpisodes []int  `json:"absoluteEpisodes,omitempty"`
	Proper           bool   `json:"proper,omitempty"`
	Repack           bool   `json:"repack,omitempty"`
	Container        string `json:"container,omitempty"`
}

type ReleaseRule struct {
	ID         string             `json:"id"`
	Name       string             `json:"name"`
	Action     string             `json:"action"`          // require, prefer, avoid (exclude)
	Match      string             `json:"match,omitempty"` // all (default) or any
	Conditions []ReleaseCondition `json:"conditions"`
	Unless     []ReleaseCondition `json:"unless,omitempty"`   // any matching exception skips the rule
	Fallback   []ReleaseCondition `json:"fallback,omitempty"` // require only, any matching condition
	Disabled   bool               `json:"disabled,omitempty"`
}

type ReleaseSizeSource interface{ ReleaseSizes() map[string]int64 }

type ReleaseTarget struct {
	Season       int    `json:"season,omitempty"`
	Episode      int    `json:"episode,omitempty"`
	ShowYear     int    `json:"showYear,omitempty"`
	EpisodeTitle string `json:"episodeTitle,omitempty"`
	// ExpectedIDs identify the requested series; ReportedIDs are the
	// release's indexer-reported series IDs, retained for file validation.
	ExpectedIDs IDs `json:"expectedIds,omitempty"`
	ReportedIDs IDs `json:"reportedIds,omitempty"`
}

type ReleaseVariant struct {
	// ID is stable for the title and release; front ends encode it (or its
	// position) in Media/Part ids.
	ID string `json:"id"`
	// Label is the viewer-facing name, e.g. "4K Dolby Vision Remux" or
	// "1080p WEB-DL (High Compatibility)".
	Label string `json:"label"`
	// Edition is the cut, e.g. "Director's Cut", "Extended", "IMAX"; empty
	// for the theatrical/unspecified cut.
	Edition string `json:"edition,omitempty"`
	// Auto marks the resolver's own pick for this client ("Best for Device").
	Auto    bool    `json:"auto,omitempty"`
	Release Release `json:"release"`
	// Info is the expected media info, estimated from the release name until
	// the release has been probed.
	Info MediaInfo `json:"info"`
}

type RemuxRequirer interface {
	RequiresRemux(sessionID string) bool
}

type RepairEvent struct {
	Key            int
	Attempt        uint64 // distinguishes concurrent readers repairing one article
	Offset         int64
	Approximate    bool
	Phase          string // missing, planning, repairing, repaired, failed, obsolete
	Estimate       time.Duration
	RemainingBytes int64
}

type RepairReporter interface {
	SetRepairHandler(func(RepairEvent) RepairWindow)
}

type RepairWindow struct {
	Deadline       time.Time
	Stop           bool
	ReadAheadBytes int64
}

type RescueIndexer interface {
	SearchRescue(context.Context, SearchRequest) ([]Release, error)
}

type Resolution struct {
	Title      RatingKey `json:"title"`
	Release    Release   `json:"release"`
	NZB        []byte    `json:"-"`
	Alternates []Release `json:"alternates"` // next candidates, best first
	ResolvedAt time.Time `json:"resolvedAt"`
}

type ResolveRequest struct {
	Title  *Title
	Client ClientCaps
	User   *User
	// PlayedRelease is the release this viewer last played of the title
	// (the one a resume opens); Variants names Auto after it (additive).
	PlayedRelease string
	// Exclude releases already tried (failover).
	Exclude []string
	// Prefer is a release ID to try first (the viewer picked a version in
	// Plex's "Play Version" picker). It is health-checked like any other
	// candidate; when it is unavailable, normal ranking applies (additive).
	Prefer string
	// ExactHEVCTranscode permits the explicitly preferred HEVC source to reach
	// playback admission for an H.264 encode. The broker must still validate
	// the probed source and the client's complete output profile.
	ExactHEVCTranscode bool
}

type Resolver interface {
	// Resolve finds a healthy release. Returns ErrNotAvailable when nothing
	// acceptable exists.
	Resolve(ctx context.Context, req ResolveRequest) (*Resolution, error)
	// MarkBad records a release as broken so nobody gets it again.
	MarkBad(ctx context.Context, releaseID string, reason string) error
	// Available reports a cached availability answer without searching:
	// (known, available).
	Available(ctx context.Context, key RatingKey) (known bool, available bool)
}

type RowDescriptor struct {
	HubID       string `json:"hubId"`
	Title       string `json:"title"`
	Kind        string `json:"kind"`
	Description string `json:"description"`
	// Sections lists the pages this row can appear on ("home", "movies",
	// "shows"); empty means every page.
	Sections []string `json:"sections,omitempty"`
	// Group is the designer's category: "picks", "explore", "shows",
	// "household", "collections" or "plex".
	Group string `json:"group,omitempty"`
}

type RowInsight struct {
	HubID         string  `json:"hubId"`
	Title         string  `json:"title"`
	Impressions7d int     `json:"impressions7d"`
	Plays7d       int     `json:"plays7d"`
	PlayRate      float64 `json:"playRate"`
}

type RowPolicy struct {
	Row            string      `json:"row"`
	Status         string      `json:"status"`
	Slot           int         `json:"slot,omitempty"`
	MinSlot        int         `json:"minSlot,omitempty"`
	MaxSlot        int         `json:"maxSlot,omitempty"`
	Priority       float64     `json:"priority,omitempty"`
	MaxPerPage     int         `json:"maxPerPage,omitempty"`
	MaxDaysPerWeek int         `json:"maxDaysPerWeek,omitempty"`
	When           *LayoutWhen `json:"when,omitempty"`
}

type RowPurpose string

type SearchCacheRefiller interface {
	RefillSearchCache(*Title) <-chan struct{}
}

type SearchRequest struct {
	Type          MediaType // movie or episode
	IDs           IDs       // movie ids, or the show's ids for episodes
	Title         string
	OriginalTitle string // optional original-language or canonical title (additive)
	Year          int
	Season        int
	Episode       int
	EpisodeTitle  string // optional title used to distinguish same-numbered episodes
	// AbsoluteEpisode is the episode's number counted from the series
	// start (0 = unknown), and Anime marks a series whose releases are
	// commonly numbered that way (additive).
	AbsoluteEpisode int
	Anime           bool
	// AlternativeTitles are other names of the movie or series (TMDB
	// alternative titles) a release name may use; matching only, never
	// part of a query or cache key (additive).
	AlternativeTitles []string `json:"-"`
}

type SectionCandidateSource interface {
	SectionCandidatesFor(context.Context, *User, MediaType, HubContext, int) ([]Hub, error)
}

type SegmentCache interface {
	Get(releaseID string, segment int) ([]byte, bool)
	Put(releaseID string, segment int, data []byte) error
	// Pin protects every segment of a release from eviction.
	Pin(releaseID string, reason string) error
	Unpin(releaseID string, reason string) error
	Usage() (used, budget int64)
}

type SegmentPresence interface{ Has(string, int) bool }

type SessionActivity interface{ PlaybackState(state string) }

type ShowTrajectory struct {
	ShowKey       RatingKey `json:"showKey"`
	EarlyRating   float64   `json:"earlyRating,omitempty"`
	FinaleRating  float64   `json:"finaleRating,omitempty"`
	PeakRating    float64   `json:"peakRating,omitempty"`
	RatedSeasons  int       `json:"ratedSeasons,omitempty"`
	SticksLanding bool      `json:"sticksLanding,omitempty"`
}

type SortOrder string

type SortSpec struct {
	Sort SortOrder `json:"sort,omitempty"`
	Desc bool      `json:"desc,omitempty"`
}

type Source string

type SourceDeliveryObserver interface {
	ObserveSourceDelivery(Release, float64)
}

type SourceRetirement interface {
	Done() <-chan struct{}
	Err() error
}

type State interface {
	Get(ctx context.Context, userID int64, key RatingKey) (WatchStatus, error)
	GetMany(ctx context.Context, userID int64, keys []RatingKey) (map[RatingKey]WatchStatus, error)
	// Progress records a timeline update. Crossing 90% marks it watched.
	Progress(ctx context.Context, userID int64, key RatingKey, offset, duration time.Duration, state string) error
	Scrobble(ctx context.Context, userID int64, key RatingKey) error   // mark watched
	Unscrobble(ctx context.Context, userID int64, key RatingKey) error // mark unwatched
	Rate(ctx context.Context, userID int64, key RatingKey, rating float64) error
	// OnDeck: in-progress items and next episodes, most recent first.
	InProgress(ctx context.Context, userID int64, limit int) ([]WatchStatus, error)
	History(ctx context.Context, userID int64, since time.Time, limit int) ([]HistoryEntry, error)
	// InProgressAny lists keys in progress for any user (cache protection, prefetch).
	InProgressAny(ctx context.Context) ([]RatingKey, error)
}

type StoredTitleLookup interface {
	StoredTitle(context.Context, RatingKey) (*Title, error)
}

type StreamInfo struct {
	// Probe hints for enhancement backends that require progressive, steady-rate input.
	Interlaced        bool `json:"interlaced,omitempty"`
	VariableFrameRate bool `json:"variableFrameRate,omitempty"`

	Index         int    `json:"index"`
	Type          string `json:"type"` // video, audio, subtitle
	Codec         string `json:"codec"`
	Profile       string `json:"profile,omitempty"`
	Level         int    `json:"level,omitempty"`
	Language      string `json:"language,omitempty"`
	Title         string `json:"title,omitempty"`
	CodecLongName string `json:"codecLongName,omitempty"`
	Default       bool   `json:"default,omitempty"`
	Forced        bool   `json:"forced,omitempty"`
	// Nil means the source did not report this ffprobe disposition.
	DefaultDisposition *bool   `json:"defaultDisposition,omitempty"`
	ForcedDisposition  *bool   `json:"forcedDisposition,omitempty"`
	HearingImpaired    *bool   `json:"hearingImpaired,omitempty"`
	Original           *bool   `json:"original,omitempty"`
	VisualImpaired     *bool   `json:"visualImpaired,omitempty"`
	Commentary         *bool   `json:"commentary,omitempty"`
	Dub                *bool   `json:"dub,omitempty"`
	Width              int     `json:"width,omitempty"`
	Height             int     `json:"height,omitempty"`
	FrameRate          float64 `json:"frameRate,omitempty"`
	// Optional probe facts are nil/empty when the source did not report them.
	AverageFrameRate   *float64 `json:"averageFrameRate,omitempty"`
	ReferenceFrameRate *float64 `json:"referenceFrameRate,omitempty"`
	DisplayAspectRatio string   `json:"displayAspectRatio,omitempty"`
	PixelFormat        string   `json:"pixelFormat,omitempty"`
	CodecTag           string   `json:"codecTag,omitempty"`
	TimeBase           string   `json:"timeBase,omitempty"`
	NALLengthSize      *int     `json:"nalLengthSize,omitempty"`
	ReferenceFrames    *int     `json:"referenceFrames,omitempty"`
	BitsPerRawSample   *int     `json:"bitsPerRawSample,omitempty"`
	ProbedLevel        *int     `json:"probedLevel,omitempty"`
	FieldOrder         string   `json:"fieldOrder,omitempty"`
	ProbedInterlaced   *bool    `json:"probedInterlaced,omitempty"`
	BitDepth           int      `json:"bitDepth,omitempty"`
	ColorTransfer      string   `json:"colorTransfer,omitempty"` // smpte2084 = HDR10, arib-std-b67 = HLG
	// Signalled picture format, in ffprobe's names; empty when the stream
	// and container leave it unspecified (decoders then assume square
	// pixels and limited range).
	SampleAspectRatio string `json:"sampleAspectRatio,omitempty"` // "N:D"
	ColorRange        string `json:"colorRange,omitempty"`        // tv, pc
	ColorPrimaries    string `json:"colorPrimaries,omitempty"`    // bt709, bt2020, smpte170m...
	ColorSpace        string `json:"colorSpace,omitempty"`        // matrix: bt709, bt2020nc, smpte170m...
	DolbyVision       bool   `json:"dolbyVision,omitempty"`
	// HDR10Plus is nil unless the probe provides affirmative or explicit negative evidence.
	HDR10Plus     *bool  `json:"hdr10Plus,omitempty"`
	Channels      int    `json:"channels,omitempty"`
	ChannelLayout string `json:"channelLayout,omitempty"`
	SampleRate    int    `json:"sampleRate,omitempty"`
	BitrateKbps   int    `json:"bitrateKbps,omitempty"`
	External      bool   `json:"external,omitempty"` // sidecar subtitle (OpenSubtitles)
	ExternalURL   string `json:"externalUrl,omitempty"`

	// DolbyVisionProfile is the DV profile (5, 7, 8...) from the DOVI
	// configuration record; 0 when unknown or not Dolby Vision.
	DolbyVisionProfile         int    `json:"dolbyVisionProfile,omitempty"`
	DolbyVisionLevel           int    `json:"dolbyVisionLevel,omitempty"`
	DolbyVisionCompatibilityID int    `json:"dolbyVisionCompatibilityId,omitempty"`
	CodecString                string `json:"codecString,omitempty"` // RFC 6381, derived from the codec configuration

	// Configuration presence is known from a completed MP4/Matroska container
	// probe; nil means unprobed, unsupported or ambiguous. Codec tags alone do
	// not establish whether enhancement/base layers or RPU are present.
	DolbyVisionConfigurationPresent     *bool  `json:"dolbyVisionConfigurationPresent,omitempty"`
	DolbyVisionBLCompatibilityIDPresent *bool  `json:"dolbyVisionBLCompatibilityIdPresent,omitempty"`
	ProbedDolbyVisionProfile            *int   `json:"probedDolbyVisionProfile,omitempty"`
	ProbedDolbyVisionLevel              *int   `json:"probedDolbyVisionLevel,omitempty"`
	DolbyVisionVersion                  string `json:"dolbyVisionVersion,omitempty"`
	DolbyVisionBLPresent                *bool  `json:"dolbyVisionBLPresent,omitempty"`
	DolbyVisionELPresent                *bool  `json:"dolbyVisionELPresent,omitempty"`
	DolbyVisionRPUPresent               *bool  `json:"dolbyVisionRPUPresent,omitempty"`
}

type StreamingIndexer interface {
	SearchWith(context.Context, SearchRequest, func([]Release)) ([]Release, error)
}

type StreamingRescueIndexer interface {
	SearchRescueWith(context.Context, SearchRequest, func([]Release)) ([]Release, error)
}

type StringFilter struct {
	Op    string `json:"op,omitempty"`
	Value string `json:"value,omitempty"`
}

type SubtitleExtractor interface {
	ExtractSubtitle(ctx context.Context, inputURL string, streamIndex int, codec string, w io.Writer) error
}

type SurfaceScopedPlayback interface {
	PrepareSurface(ctx context.Context, user *User, key RatingKey, caps ClientCaps, releaseID string, exact bool) (*PlaySession, error)
	SessionForSurface(surface string, userID int64, clientID string, key RatingKey, releaseID string, exact bool) (*PlaySession, bool)
	MarkSurfaceOpened(id string) bool
	MarkSurfacePrepared(id string) bool
}

type TasteDecade struct {
	Decade int     `json:"decade"`
	Weight float64 `json:"weight"`
}

type TasteHabits struct {
	WeeknightMinutes float64 `json:"weeknightMinutes"` // typical minutes watched on an active weeknight
	WeekendMinutes   float64 `json:"weekendMinutes"`   // typical minutes watched on an active weekend day
	PreferredDevice  string  `json:"preferredDevice"`  // DeviceTV, DeviceMobile, ... or ""
	BingeScore       float64 `json:"bingeScore"`       // 0..1: share of episodes watched in same-day runs of 3+
	RewatchScore     float64 `json:"rewatchScore"`     // 0..1: share of finished titles watched again
	PeakHours        []int   `json:"peakHours"`        // most common start hours (local), busiest first
}

type TasteLanguage struct {
	Code   string  `json:"code"`
	Weight float64 `json:"weight"`
}

type TasteOverride struct {
	Kind   string  `json:"kind"`
	Value  string  `json:"value"`
	Weight float64 `json:"weight"`
}

type TastePerson struct {
	ID     int64   `json:"id"`
	Name   string  `json:"name"`
	Role   string  `json:"role"` // "director", "writer", "actor"
	Weight float64 `json:"weight"`
	Image  string  `json:"image,omitempty"` // browser-loadable URL
}

type TasteProfile struct {
	UserID     int64           `json:"userId"`
	UpdatedAt  time.Time       `json:"updatedAt"`
	Confidence float64         `json:"confidence"` // 0..1, grows with history
	Genres     []TasteWeight   `json:"genres"`
	People     []TastePerson   `json:"people"`
	Keywords   []TasteWeight   `json:"keywords"`
	Decades    []TasteDecade   `json:"decades"`
	Languages  []TasteLanguage `json:"languages"`
	Habits     TasteHabits     `json:"habits"`
	Overrides  []TasteOverride `json:"overrides"`
}

type TasteWeight struct {
	Name   string  `json:"name"`
	Weight float64 `json:"weight"`
}

type TimelineAligner interface {
	AlignTime(ctx context.Context, req AlignRequest, at time.Duration) (mapped time.Duration, ok bool)
}

type Title struct {
	Key  RatingKey `json:"key"`
	Type MediaType `json:"type"`
	IDs  IDs       `json:"ids"`

	// Seasons and episodes.
	ShowKey           RatingKey `json:"showKey,omitempty"`
	ShowIDs           IDs       `json:"showIds,omitempty"`
	ShowTitle         string    `json:"showTitle,omitempty"`
	ShowOriginalTitle string    `json:"showOriginalTitle,omitempty"` // canonical original series name, distinct from episode title
	ShowYear          int       `json:"showYear,omitempty"`          // series premiere year, distinct from episode air year
	SeasonTitle       string    `json:"seasonTitle,omitempty"`
	Season            int       `json:"season,omitempty"`
	Episode           int       `json:"episode,omitempty"`
	// AbsoluteEpisode counts an episode from the series start across its
	// regular seasons; 0 when an earlier season's size is unknown (additive).
	AbsoluteEpisode int `json:"absoluteEpisode,omitempty"`

	Title         string `json:"title"`
	OriginalTitle string `json:"originalTitle,omitempty"`
	SortTitle     string `json:"sortTitle,omitempty"`
	Tagline       string `json:"tagline,omitempty"`
	Summary       string `json:"summary,omitempty"`
	Year          int    `json:"year,omitempty"`
	// PrimaryReleased is TMDB's primary release_date for a movie. The title
	// year comes from it. Released stays the date added (theatrical, when
	// one exists). Empty when the year came from a premiere or the release
	// itself. Not serialized.
	PrimaryReleased time.Time `json:"-"`
	// YearSource records which date produced Year: primary, premiere,
	// released, none, or missing. Empty means a row stored before that
	// date was kept. Not serialized.
	YearSource                  string        `json:"-"`
	Released                    time.Time     `json:"released,omitempty"`   // first air / release date
	AddedAt                     time.Time     `json:"addedAt,omitzero"`     // series/season latest aired episode, or a derived air date; not a catalogue insertion time
	LastAirDate                 time.Time     `json:"lastAirDate,omitzero"` // last aired episode date when known
	HomeReleaseChecked          bool          `json:"homeReleaseChecked,omitempty"`
	HomeReleased                time.Time     `json:"homeReleased,omitempty"`
	HomeReleaseFallbackAdmitted bool          `json:"homeReleaseFallbackAdmitted,omitempty"`
	Runtime                     time.Duration `json:"runtime,omitempty"`
	Status                      string        `json:"status,omitempty"` // TMDB status: Released, In Production, Ended...

	Genres   []string `json:"genres,omitempty"`
	Keywords []string `json:"keywords,omitempty"` // TMDB keywords (lower-case), for content-based recommendations
	// AlternativeTitles are other names the title goes by (TMDB alternative
	// titles: romanized originals, regional and working titles). Release
	// matching only; never serialized (additive). Episodes and seasons carry
	// their series' in ShowAlternativeTitles.
	AlternativeTitles     []string `json:"-"`
	ShowAlternativeTitles []string `json:"-"`
	RemoteTrailerName     string   `json:"remoteTrailerName,omitempty"`
	RemoteTrailerURL      string   `json:"remoteTrailerURL,omitempty"`
	Studios               []string `json:"studios,omitempty"`
	Countries             []string `json:"countries,omitempty"`
	Language              string   `json:"language,omitempty"` // ISO 639-1 original language
	// ContentRating is the certification in contentrating's stored form:
	// bare US labels ("PG", "TV-14"), region-qualified otherwise ("de/6").
	ContentRating string `json:"contentRating,omitempty"`
	// ContentRatingSource records where ContentRating came from: "tmdb:US:6"
	// (TMDB, country, movie release type), "tmdb:CA" (TV), "omdb", "mdblist".
	ContentRatingSource string `json:"contentRatingSource,omitempty"`
	Adult               bool   `json:"adult,omitempty"`

	Rating     float64 `json:"rating,omitempty"` // TMDB vote average 0-10
	VoteCount  int     `json:"voteCount,omitempty"`
	Popularity float64 `json:"popularity,omitempty"`

	PosterPath   string `json:"posterPath,omitempty"`
	BackdropPath string `json:"backdropPath,omitempty"`
	StillPath    string `json:"stillPath,omitempty"` // episodes
	LogoPath     string `json:"logoPath,omitempty"`

	Cast      []Person `json:"cast,omitempty"`
	Directors []Person `json:"directors,omitempty"`
	Writers   []Person `json:"writers,omitempty"`
	Crew      []Person `json:"crew,omitempty"` // creators, cinematographers, composers (additive)

	CollectionID   int64  `json:"collectionId,omitempty"` // TMDB franchise
	CollectionName string `json:"collectionName,omitempty"`

	ChildCount int `json:"childCount,omitempty"` // seasons of a show, episodes of a season
	LeafCount  int `json:"leafCount,omitempty"`  // episodes of a show

	UpdatedAt time.Time `json:"updatedAt,omitempty"`
}

type TransactionalMarkedPlaylists interface {
	EnsureMarkedPlaylistTx(context.Context, *sql.Tx, int64, string, string) (RatingKey, error)
	DeleteMarkedPlaylistTx(context.Context, *sql.Tx, int64, string) error
	MarkedPlaylistKeyTx(context.Context, *sql.Tx, int64, string) (RatingKey, error)
}

type Transcoder interface {
	Probe(ctx context.Context, inputURL string) (*MediaInfo, error)
	Decide(info MediaInfo, caps ClientCaps, opts DecideOptions) Decision
	// StartHLS starts an HLS session, a DASH session (a DASHSession)
	// when req.Protocol is ProtocolDASH, or an HTTP Matroska session
	// (an HTTPSession) when req.Protocol is ProtocolHTTP.
	StartHLS(ctx context.Context, req HLSRequest) (HLSSession, error)
	Session(id string) (HLSSession, bool)
	Stop(id string)
	HWAccel() HWAccel
}

type TrickplayCanceler interface{ CancelTrickplay(string) }

type TrickplayLease interface {
	Ensure(context.Context, TrickplaySource)
	Release(cancelIfIdle bool)
}

type TrickplayLeaser interface {
	AcquireTrickplay(context.Context, TrickplaySource) (TrickplayLease, error)
}

type TrickplayProvider interface {
	// EnsureTrickplay starts (or continues) progressive thumbnail
	// generation for the source in the background. It returns
	// immediately; duplicate calls for a release already generating are
	// no-ops.
	EnsureTrickplay(ctx context.Context, src TrickplaySource)
	// TrickplayAvailable reports whether thumbnails for the release
	// exist or are being generated, so a front end can advertise them
	// (Plex's indexes="sd").
	TrickplayAvailable(releaseID string) bool
	// TrickplayBIF returns a snapshot of the release's sparse BIF index
	// built from the frames generated so far.
	TrickplayBIF(releaseID string) ([]byte, bool)
	// TrickplayFrame returns the JPEG of the latest generated frame at
	// or before at (a fallback still when no real frame precedes it).
	TrickplayFrame(releaseID string, at time.Duration) ([]byte, bool)
	// SetTrickplayFallback records a low-fidelity still (TMDB episode
	// still or backdrop, already JPEG at roughly BIF width) used to fill
	// not-yet-generated intervals. Real frames replace it as they arrive.
	SetTrickplayFallback(releaseID string, jpeg []byte)
}

type TrickplaySource struct {
	ReleaseID string
	InputURL  string
	Info      MediaInfo
	// AvailableUntil is the playback position already read by the client.
	// Generators must only fill intervals at or before this point and may
	// advance it on later calls as playback progresses.
	AvailableUntil time.Duration
}

type User struct {
	// Timestamps are internal identity metadata and do not change existing wire JSON.
	CreatedAt time.Time `json:"-"`
	UpdatedAt time.Time `json:"-"`
	// Delegated marks short-lived server credentials; these never grant owner access.
	Delegated bool   `json:"-"`
	ID        int64  `json:"id"` // local id
	PlexID    int64  `json:"plexId"`
	UUID      string `json:"uuid,omitempty"`
	Username  string `json:"username"`
	Title     string `json:"title"` // display name
	Email     string `json:"email,omitempty"`
	Thumb     string `json:"thumb,omitempty"`
	IsOwner   bool   `json:"isOwner"`

	StreamLimit       int      `json:"streamLimit"`       // 0 = server default
	MaxContentRating  string   `json:"maxContentRating"`  // "" = unrestricted, e.g. "PG-13", "TV-14"
	SubtitleLanguages []string `json:"subtitleLanguages"` // ISO 639-1, preference order
	AudioLanguages    []string `json:"audioLanguages"`
	AllowedSections   []int    `json:"allowedSections"` // empty = all
}

type UserPolicySource interface{ UserPolicy(*User) *User }

type UserTargets struct {
	All bool
	IDs []int64
}

type VariantPlayback interface {
	PrepareVariant(ctx context.Context, user *User, key RatingKey, caps ClientCaps, releaseID string) (*PlaySession, error)
}

type VariantResolver interface {
	Variants(ctx context.Context, req ResolveRequest, max int) ([]ReleaseVariant, error)
}

type VibeQuery struct {
	// Query is the viewer's original text.
	Query string `json:"query,omitempty"`
	// Title is the human collection title, e.g.
	// "90s Thrillers Under 100 Minutes".
	Title string `json:"title,omitempty"`
	// Filter is the catalogue filter the members are browsed with.
	Filter Filter    `json:"filter"`
	Sort   SortOrder `json:"sort,omitempty"`
	Desc   bool      `json:"desc,omitempty"`
	// SimilarSeed is the unresolved seed title text of a
	// "shows like the office" query; SimilarKey is it resolved.
	SimilarSeed string    `json:"similarSeed,omitempty"`
	SimilarKey  RatingKey `json:"similarKey,omitempty"`
	// PersonName is an unresolved person name ("christopher nolan
	// films"); once resolved it lands in Filter.Person.
	PersonName string `json:"personName,omitempty"`
}

type VibeRefiner interface {
	RefineVibe(ctx context.Context, user *User, query string) (VibeQuery, bool, error)
}

type VibeSearcher interface {
	VibeCollection(ctx context.Context, user *User, query string) (c *Collection, items []Title, ok bool, err error)
	// PromoteEphemeral saves an ephemeral collection as a persisted
	// personal smart collection for its owner. ok is false when key is
	// not a live ephemeral collection owned by user.
	PromoteEphemeral(ctx context.Context, user *User, key RatingKey) (c *Collection, ok bool, err error)
}

type VideoEnhancement struct {
	Backend string `json:"backend,omitempty"`
	State   string `json:"state,omitempty"` // off, unavailable, ineligible, selected, starting, running, fallback, stopped
	Reason  string `json:"reason,omitempty"`
	Width   int    `json:"width,omitempty"`
	Height  int    `json:"height,omitempty"`
	Quality int    `json:"quality,omitempty"`
}

type VideoEnhancementSupport struct {
	// SetupState is off, checking, installing, ready, or unavailable.
	SetupState string   `json:"setupState,omitempty"`
	Backend    string   `json:"backend"`
	Available  bool     `json:"available"`
	Reason     string   `json:"reason,omitempty"`
	Version    string   `json:"version,omitempty"`
	Protocols  []string `json:"protocols,omitempty"`
	Active     int      `json:"active"`
}

type Viewer = User

type ViewerActivity struct {
	Title     Title     `json:"title"`
	At        time.Time `json:"at"`
	Completed bool      `json:"completed"`
	Progress  float64   `json:"progress"` // 0..1
}

type ViewerInvalidator interface{ Invalidate(userID int64) }

type ViewerLayout struct {
	UserID int64        `json:"userId"`
	Pages  []LayoutPage `json:"pages"`
}

type ViewerStats struct {
	UserID          int64     `json:"userId"`
	LastActive      time.Time `json:"lastActive,omitempty"`
	Plays30d        int       `json:"plays30d"`
	HoursWatched30d float64   `json:"hoursWatched30d"`
}

type WarmProbeWaiter interface {
	WaitWarmProbe(ctx context.Context, user *User, caps ClientCaps, key RatingKey, budget time.Duration) (MediaInfo, bool)
}

type WarmProber interface {
	WarmProbeInfo(user *User, caps ClientCaps, key RatingKey) (MediaInfo, bool)
}

type WatchStatus struct {
	Key             RatingKey     `json:"key"`
	ViewOffset      time.Duration `json:"viewOffset"`
	ViewCount       int           `json:"viewCount"`
	LastViewedAt    time.Time     `json:"lastViewedAt,omitempty"`
	UserRating      float64       `json:"userRating,omitempty"` // 0-10
	InWatchlist     bool          `json:"inWatchlist,omitempty"`
	IsFavorite      bool          `json:"isFavorite,omitempty"`      // Derived from the viewer’s favorites set.
	IsNotInterested bool          `json:"isNotInterested,omitempty"` // Derived from the viewer’s recommendation exclusions.
	Duration        time.Duration `json:"duration,omitempty"`
	UpdatedAt       time.Time     `json:"updatedAt"`
}