core

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 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 BrowseQuery struct {
	Filter Filter
	Sort   SortOrder
	Desc   bool
	Offset int
	Limit  int
}

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 Chapter struct {
	ID    int64         `json:"id"`
	Title string        `json:"title,omitempty"`
	Start time.Duration `json:"start"`
	End   time.Duration `json:"end"`
}

type ClientCaps struct {
	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...
	HDR10          bool                `json:"hdr10"`
	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
	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

	// 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 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"`
	// 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 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"`
	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 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 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 CustomFormat struct {
	ID             string                `json:"trash_id"`
	Name           string                `json:"name"`
	Scores         map[string]int        `json:"trash_scores,omitempty"`
	Specifications []FormatSpecification `json:"specifications"`
}

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 DecideOptions struct {
	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
}

type Decision struct {
	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"`
	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"`

	// 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 DecisionKind string

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
}

type DownloadRemuxer interface {
	// RemuxDownload runs ffmpeg -c copy 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 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 FacetValue struct {
	Key   string `json:"key"`
	Title string `json:"title"`
	Count int    `json:"count"`
}

type Filter struct {
	Type             MediaType     `json:"type,omitempty"` // movie or show
	Genres           []string      `json:"genres,omitempty"`
	YearFrom         int           `json:"yearFrom,omitempty"`
	YearTo           int           `json:"yearTo,omitempty"`
	MinRating        float64       `json:"minRating,omitempty"`
	MaxRuntime       time.Duration `json:"maxRuntime,omitempty"`
	MinRuntime       time.Duration `json:"minRuntime,omitempty"`
	Languages        []string      `json:"languages,omitempty"`
	Countries        []string      `json:"countries,omitempty"`
	ContentRatings   []string      `json:"contentRatings,omitempty"`
	MaxContentRating string        `json:"maxContentRating,omitempty"` // per-user limit
	Collection       int64         `json:"collection,omitempty"`
	Person           int64         `json:"person,omitempty"` // cast or crew TMDB id
	Studio           string        `json:"studio,omitempty"`
	Query            string        `json:"query,omitempty"` // title substring
}

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 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 {
	SessionID string
	InputURL  string // ffmpeg input; Ether serves sources on loopback HTTP with range support
	// 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
	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) or ProtocolDASH. A DASH
	// session also implements DASHSession; Transcoder.Session returns it as
	// an HLSSession, so type-assert to reach the DASH 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 HWAccel struct {
	Name     string   `json:"name"` // "videotoolbox", "nvenc", "qsv", "vaapi", "none"
	Encoders []string `json:"encoders"`
	Device   string   `json:"device,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 HomeLayout struct {
	Global    []LayoutPage   `json:"global"`
	Viewers   []ViewerLayout `json:"viewers"`
	UpdatedAt time.Time      `json:"updatedAt,omitempty"`
}

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 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
}

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
	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 IDs struct {
	TMDB int64  `json:"tmdb,omitempty"`
	IMDB string `json:"imdb,omitempty"`
	TVDB int64  `json:"tvdb,omitempty"`
}

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 LookupResult struct {
	ID        int64  `json:"id"`
	Name      string `json:"name"`
	Subtitle  string `json:"subtitle,omitempty"`
	ImagePath string `json:"imagePath,omitempty"` // TMDB image path
}

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 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 Page struct {
	Items []Title
	Total int
}

type Person struct {
	TMDB      int64  `json:"tmdb,omitempty"`
	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"`
	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
	Failovers      int // mid-stream release swaps so far
	// 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 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 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 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 QualityProfile struct {
	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
	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
	MaxSizeMBPerMin      float64        `json:"maxSizeMbPerMin"`
	PreferredLanguages   []string       `json:"preferredLanguages"`
	AllowCam             bool           `json:"allowCam"` // also gated by the owner's global cam setting
}

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 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 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"`

	// 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"`
}

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"`
	Proper      bool     `json:"proper,omitempty"`
	Repack      bool     `json:"repack,omitempty"`
	Container   string   `json:"container,omitempty"`
}

type ReleaseTarget struct {
	Season  int `json:"season,omitempty"`
	Episode int `json:"episode,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 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
	// 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
}

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 SearchRequest struct {
	Type    MediaType // movie or episode
	IDs     IDs       // movie ids, or the show's ids for episodes
	Title   string
	Year    int
	Season  int
	Episode int
}

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 SortOrder string

type Source string

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 StreamInfo struct {
	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"`
	Default       bool    `json:"default,omitempty"`
	Forced        bool    `json:"forced,omitempty"`
	Width         int     `json:"width,omitempty"`
	Height        int     `json:"height,omitempty"`
	FrameRate     float64 `json:"frameRate,omitempty"`
	BitDepth      int     `json:"bitDepth,omitempty"`
	ColorTransfer string  `json:"colorTransfer,omitempty"` // smpte2084 = HDR10, arib-std-b67 = HLG
	DolbyVision   bool    `json:"dolbyVision,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-record facts are optional: codec tags alone do not
	// establish whether the enhancement/base layers or RPU are present.
	DolbyVisionVersion    string `json:"dolbyVisionVersion,omitempty"`
	DolbyVisionBLPresent  *bool  `json:"dolbyVisionBLPresent,omitempty"`
	DolbyVisionELPresent  *bool  `json:"dolbyVisionELPresent,omitempty"`
	DolbyVisionRPUPresent *bool  `json:"dolbyVisionRPUPresent,omitempty"`
}

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"`
	SeasonTitle string    `json:"seasonTitle,omitempty"`
	Season      int       `json:"season,omitempty"`
	Episode     int       `json:"episode,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"`
	Released      time.Time     `json:"released,omitempty"` // first air / release date
	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
	Studios       []string `json:"studios,omitempty"`
	Countries     []string `json:"countries,omitempty"`
	Language      string   `json:"language,omitempty"` // ISO 639-1 original language
	ContentRating string   `json:"contentRating,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"`

	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 Transcoder interface {
	Probe(ctx context.Context, inputURL string) (*MediaInfo, error)
	Decide(info MediaInfo, caps ClientCaps, opts DecideOptions) Decision
	// StartHLS starts an HLS session, or a DASH session (a DASHSession)
	// when req.Protocol is ProtocolDASH.
	StartHLS(ctx context.Context, req HLSRequest) (HLSSession, error)
	Session(id string) (HLSSession, bool)
	Stop(id string)
	HWAccel() HWAccel
}

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 {
	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 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 ViewerActivity struct {
	Title     Title     `json:"title"`
	At        time.Time `json:"at"`
	Completed bool      `json:"completed"`
	Progress  float64   `json:"progress"` // 0..1
}

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 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
	Duration     time.Duration `json:"duration,omitempty"`
	UpdatedAt    time.Time     `json:"updatedAt"`
}