frontend

type ActivityPage struct {
	Items      []Title
	Total      int
	TotalExact bool
	More       bool
}

type AiredMemo struct {
	Items []core.Title
	Total int
	Err   error
}

type Announcer interface {
	Start(context.Context) error
	Close() error
}

type Artwork interface {
	List(context.Context, ArtworkRequest) (images []Image, complete bool, err error)
	Read(context.Context, ArtworkRequest, Image, ArtworkTransform) (data []byte, contentType string, err error)
}

type ArtworkOwner struct {
	Item          RatingKey
	Images        []Image
	Authoritative bool
}

type ArtworkRequest struct {
	Viewer *core.Viewer
	Device core.Device
	Item   core.RatingKey
	// Channel is a stable LiveTV channel ID. Exactly one of Item and Channel
	// identifies the subject.
	Channel string
}

type ArtworkTransform struct {
	Width, Height int
	Format        string
	Blur          bool
}

type AuthenticatedLazyStreams interface {
	ServeAuthenticated(http.ResponseWriter, *http.Request, string, PlanRequest)
}

type Capabilities interface {
	Build(context.Context, CapabilityRequest) (CapabilityResult, error)
}

type CapabilityRequest struct {
	Viewer       *core.Viewer
	Device       caps.DeviceInfo
	Profile      caps.DeviceProfile
	ProtocolInfo []string
	UserAgent    string
}

type CapabilityResult struct {
	Client  core.ClientCaps
	Quality core.QualityProfile
}

type CertifiedApp struct {
	Name  string        `json:"name"`
	Steps []ConnectStep `json:"steps"`
}

type CinemaIntros interface {
	Trailers(context.Context, *core.Viewer, core.Device, core.RatingKey, int) ([]Extra, error)
}

type ClientCaps = core.ClientCaps

type Collection = core.Collection

type CollectionPage struct {
	Items []core.Collection
	Total int
}

type CollectionQuery struct {
	Types         []core.MediaType
	Offset, Limit int
}

type Command struct {
	Kind                CommandKind
	Position            time.Duration
	StreamIndex         int
	Message             string
	ControllerSessionID string
}

type CommandKind string

type ConnectStep string

type Continuation string

type DecideOptions = core.DecideOptions

type Decision = core.Decision

type Descriptor struct {
	ID             Protocol       `json:"id"`
	Name           string         `json:"name"`
	Logo           string         `json:"logo,omitempty"`
	Version        string         `json:"version,omitempty"`
	DocsURL        string         `json:"docsUrl,omitempty"`
	DefaultPort    int            `json:"defaultPort,omitempty"`
	Clients        []string       `json:"clients,omitempty"`
	CertifiedApps  []CertifiedApp `json:"certifiedApps,omitempty"`
	SettingsSchema any            `json:"settingsSchema,omitempty"`
}

type DetailFacts struct {
	Header       string
	RatingsKnown bool
	Community    *float64
	Critic       *float64
	Sources      []ExternalRating
}

type DetailFactsSource interface {
	DetailFacts(context.Context, *core.Viewer, core.Title) DetailFacts
	PageRatings(context.Context, *core.Viewer, []core.Title) map[core.RatingKey]DetailFacts
}

type DetailPlanner interface {
	DetailPlan(ctx context.Context, request PlanRequest) (PlayPlan, error)
	ResolveDetailSource(ctx context.Context, scope VersionScope, handle string) (DetailSourceTarget, error)
	MatchDetailSession(ctx context.Context, scope VersionScope, handle, sessionID string) error
}

type DetailSourceTarget struct {
	Item RatingKey
	ETag string
}

type Device = core.Device

type DeviceIdentity interface {
	ResolveDevice(context.Context, string, Device) (*Viewer, time.Time, error)
}

type DiscoveryRequest struct {
	Data     []byte
	Peer     netip.AddrPort
	Endpoint string
}

type DiscoveryResponder interface {
	RespondDiscovery(context.Context, DiscoveryRequest) ([]byte, bool)
}

type EditionBatch interface {
	EditionsMany(context.Context, *core.Viewer, core.Device, []core.RatingKey) (map[core.RatingKey][]Version, error)
}

type Editions interface {
	Editions(context.Context, *core.Viewer, core.Device, core.RatingKey) ([]Version, error)
}

type Event struct {
	Type     string
	ViewerID int64
	// ActorViewerID is set from the authenticated actor for SessionCommand;
	// zero denotes a system-originated stop without an authenticated actor.
	ActorViewerID int64
	Item          core.RatingKey
	SessionID     string
	// SubjectKind and SubjectID identify non-title user data such as a
	// favorite person, collection or channel. Item remains the title key.
	SubjectKind     string
	SubjectID       string
	OriginProtocol  Protocol
	OriginSessionID string
	OriginClientID  string
	Command         *Command
	TargetProtocol  Protocol
	TargetDeviceID  string
	Session         *Session
	Timeline        *Timeline
}

type EventScope struct {
	Viewer *core.Viewer
	Owner  bool
	// Protocol suppresses this surface's own user-data invalidations.
	Protocol Protocol
	// SessionID selects the authenticated client session for targeted commands.
	SessionID string
	// Device binds a socket before a playback session exists and remains valid
	// when this authenticated device's current session changes.
	Device core.Device
}

type Experience interface {
	Views(context.Context, *core.Viewer) ([]View, error)
	Collections(context.Context, *core.Viewer, core.Device, CollectionQuery) (CollectionPage, error)
	NotInterested(context.Context, *core.Viewer, core.Device, PageQuery) (NotInterestedPage, error)
	NotInterestedItem(context.Context, *core.Viewer, core.Device, core.RatingKey) (NotInterestedEntry, error)
	// ResolveExternal resolves an IMDb ID without opening a release, and returns
	// a key only after enforcing current viewer and inherited-show policy.
	ResolveExternal(context.Context, *core.Viewer, core.Device, ExternalRequest) (core.RatingKey, error)
	Rows(context.Context, RowRequest) ([]Row, error)
	Item(context.Context, ItemRequest) (ItemDetail, error)
	Children(context.Context, *core.Viewer, core.Device, core.RatingKey, ItemQuery) (core.Page, error)
	LibraryItems(context.Context, *core.Viewer, core.Device, string, ItemQuery) (core.Page, error)
	Similar(context.Context, *core.Viewer, core.Device, core.RatingKey, ItemQuery) (SearchPage, error)
	Ancestors(context.Context, *core.Viewer, core.Device, core.RatingKey) ([]core.Title, error)
	Facets(context.Context, *core.Viewer, core.Device, string, string) ([]core.FacetValue, error)
	ResolveFacet(context.Context, *core.Viewer, core.Device, string, string, string) (core.FacetValue, error)
	// PersonFacetIDs returns IDs only for credited people of an authorized title.
	// Episode-only credits may not appear in library-wide Facets or ResolveFacet.
	// Requests are bounded to 256 positive TMDB IDs; missing credits are omitted.
	PersonFacetIDs(context.Context, *core.Viewer, core.Device, core.RatingKey, []int64) (map[int64]string, error)
	// NamedFacetIDs resolves exact genre or studio names on one visible title.
	// A request contains at most 256 nonempty names; missing names are omitted.
	NamedFacetIDs(context.Context, *core.Viewer, core.Device, core.RatingKey, string, []string) (map[string]string, error)
	Search(context.Context, *core.Viewer, core.Device, string, ItemQuery) (SearchPage, error)
	UserData(context.Context, *core.Viewer, []core.RatingKey) (map[core.RatingKey]core.WatchStatus, error)
	SetPlayed(context.Context, *core.Viewer, core.RatingKey) error
	SetUnplayed(context.Context, *core.Viewer, core.RatingKey) error
	SetFavorite(context.Context, *core.Viewer, core.RatingKey, bool) error
	SetNotInterested(context.Context, *core.Viewer, core.RatingKey, bool) error
	SetWatchlist(context.Context, *core.Viewer, core.RatingKey, bool) error
	SetEntityFavorite(context.Context, *core.Viewer, FavoriteRef, bool) error
	EntityFavorites(context.Context, *core.Viewer, []FavoriteRef) (map[FavoriteRef]bool, error)
	ResolveEventSubject(context.Context, *core.Viewer, core.Device, FavoriteRef) (ResolvedEventSubject, error)
	SetRating(context.Context, *core.Viewer, core.RatingKey, float64) error
	SetLikes(context.Context, *core.Viewer, core.RatingKey, *bool) error
	RemoveFromContinue(context.Context, *core.Viewer, core.RatingKey) error
}

type ExternalRating struct {
	Source, Name, Display string
	Score                 float64
	Votes                 int64
}

type ExternalRequest struct {
	Source          string
	ID              string
	Type            core.MediaType
	Season, Episode *int
}

type Extra struct {
	Key, ParentKey                          core.RatingKey
	Title, Kind, Source, SourceID, Language string
	Official                                bool
	PublishedAt                             time.Time
	Duration                                time.Duration
	Height                                  int
}

type ExtraStreams interface {
	Lookup(core.RatingKey) (Extra, bool)
	Open(context.Context, core.RatingKey) (container, rawURL string, headers map[string]string, err error)
}

type FavoriteKind string

type FavoriteRef struct {
	Kind FavoriteKind
	ID   string
}

type Frontend interface {
	Describe() Descriptor
	Mount(context.Context, Host) (Instance, error)
}

type GrantDeviceIdentity interface {
	ResolveGrantDevice(context.Context, string, string) (*Viewer, Device, time.Time, error)
}

type GrantedImage struct {
	Image  Image
	Secret string
}

type HLSSession = core.HLSSession

type Host struct {
	Experience         Experience
	ViewerCapabilities ViewerCapabilitiesFunc
	ViewerPolicy       ViewerPolicy
	Capabilities       Capabilities
	Preferences        Preferences
	TrackPreferences   TrackPreferenceService
	LiveTV             LiveTV
	VirtualPaths       VirtualPaths
	Sessions           Sessions
	LastPlayedSource   LastPlayedSourceReader
	SourceOffers       SourceOffers
	VersionHandles     VersionHandles
	// Editions lists locally probed copies of one title. It is empty when the
	// process has no local media manifest, and it must not search the network.
	Editions    Editions
	LazyStreams LazyStreams
	LANStreams  LANLazyStreams
	Identity    SurfaceIdentity
	IDs         ids.Codecs
	Events      Subscriber
	Tickets     Tickets
	// WatchParty is the shared Silo and Jellyfin room. Nil leaves both off.
	WatchParty  WatchParty
	Images      Images
	ImageGrants ImageGrants
	// Artwork serves the same composited poster bytes the other frontends
	// grant. DLNA has no credential, so it reads this after LANViewer.
	Artwork Artwork
	// ExtraStreams opens a playable trailer or extra. Nil means extras are not
	// configured; listing routes still authorize the parent and return nothing.
	ExtraStreams ExtraStreams
	// DirectProxy selects the proxy for trailer fetches. Nil follows the
	// process environment. The app wires the direct route so frontends do
	// not import the egress policy.
	DirectProxy func(*http.Request) (*url.URL, error)
	// Cinema lists preroll trailers of other movies. Nil means cinema intros
	// are not wired; the intros route returns an empty page after authorization.
	Cinema CinemaIntros
	// Subtitles searches and downloads a sidecar only after an explicit pick.
	// Nil or Enabled false tells clients the server will not fetch one.
	Subtitles SubtitleCatalog
	Config    func() Settings
	// MetadataLanguage is the catalog language (config catalog.language).
	// Empty skips that step of the no-list audio chain.
	MetadataLanguage func() string
	// AudioOrder is the shared no-choice language chain. Frontends call it
	// instead of importing the track-preference package. Nil keeps the
	// caller's own fallback.
	AudioOrder func(audio []string, server, original string, preferOriginal bool) []string
	// PickAudio returns a stream position in MediaInfo, or -1 when no audio
	// stream exists. Nil keeps the caller's own fallback.
	PickAudio func(MediaInfo, []string) int
	Log       *slog.Logger
	// ViewerPortalURL returns a reachable owner-selected viewer portal URL for this client.
	ViewerPortalURL func(context.Context, *http.Request) (string, error)
	// SecurePortalURL selects a verified reachable HTTPS portal address.
	SecurePortalURL func(context.Context, *http.Request) (string, error)
	// SurfaceURL returns a reachable, verified base for this frontend's routes.
	SurfaceURL func(context.Context, *http.Request) (string, error)
	// LANViewer resolves the owner-selected active DLNA viewer only after
	// trusted-proxy-aware network classification; other surfaces receive nil.
	LANViewer func(context.Context, *http.Request) (*Viewer, error)
	// ClientSeen reports an authenticated client's protocol-specific device ID.
	ClientSeen func(deviceID string)
	// ClientIP resolves the transport peer using the configured trusted proxies.
	ClientIP func(*http.Request) (netip.Addr, bool)
	// PageFreshness invalidates cached browse bodies. Nil disables the cache.
	PageFreshness func() PageFreshness
	// PersonalHomes keeps the last personalized library list so the first
	// UserViews after a restart can include it. Nil keeps that list in memory.
	PersonalHomes PersonalHomeStore
}

type Image struct {
	Kind, Path, Tag string
	// Subject identifies an entity within the authorized item, such as the
	// tmdb:<id> person whose credit owns a portrait. It is part of the grant.
	Subject string
	// Width and Height describe the cached source pixels; zero means unknown.
	Width, Height int
	// BlurHash is a cached preview of the source; empty means unavailable.
	BlurHash string
	// ThumbHash is padded base64 of the cached source's standard ThumbHash;
	// empty means the background computation has not completed.
	ThumbHash string
}

type ImageBatchItem struct {
	Item          core.RatingKey
	Authoritative bool
	Images        []GrantedImage
}

type ImageBatchRequest struct {
	Credential string
	Device     core.Device
	Items      []core.RatingKey
	Kinds      []string
}

type ImageGrantBatch interface {
	IssueBatch(context.Context, ImageBatchRequest) ([]ImageBatchItem, error)
}

type ImageGrantRequest struct {
	Credential string
	Device     core.Device
	Item       core.RatingKey
	Channel    string
	Image      Image
}

type ImageGrants interface {
	Issue(context.Context, ImageGrantRequest) (string, error)
	Revoke(context.Context, string, string) error
	Serve(http.ResponseWriter, *http.Request, string)
}

type ImagePageRequest struct {
	Credential string
	Device     core.Device
	Titles     []core.Title
	Kinds      []string
}

type ImagePageSigner interface {
	SignPage(context.Context, ImagePageRequest) ([]ImageBatchItem, error)
}

type Images interface {
	ServeHTTP(http.ResponseWriter, *http.Request)
}

type Instance interface {
	Handler() http.Handler
	Listeners() []ListenerSpec
	Discovery() []Announcer
	Status(context.Context) Status
	Close(context.Context) error
}

type ItemArtwork interface {
	ItemArtwork(context.Context, *core.Viewer, core.Device, core.RatingKey) ([]Image, bool, error)
}

type ItemArtworkPage interface {
	ItemArtworkPage(context.Context, *core.Viewer, core.Device, []core.RatingKey) (map[core.RatingKey][]Image, error)
}

type ItemDetail struct {
	Collection *core.Collection
	Playlist   *core.Playlist
	Title      core.Title
	UserData   core.WatchStatus
	// CanPlay reflects current playback authorization when known. Nil means the
	// verified peer or policy result is unavailable. It does not guarantee a
	// source, codec, stream slot or transcode capacity will be available.
	CanPlay *bool
	Tracks  []core.StreamInfo
	// TracksEstimated marks a set containing synthesized playback estimates.
	// These streams must not be presented as facts about a resolved source.
	TracksEstimated bool
	Images          []Image
	// ImagesAuthoritative reports whether Images describes the currently selected
	// authorized artwork. Background discovery may add alternatives later.
	ImagesAuthoritative bool
	Versions            []Version
	Markers             []Marker
	Extras              []Extra
}

type ItemProgress interface {
	ReportItemProgress(context.Context, SessionAccess, core.RatingKey, Timeline) error
}

type ItemQuery struct {
	// AdjacentTo selects the anchor and its immediately neighboring visible items.
	AdjacentTo core.RatingKey
	// StartAt selects an inclusive starting item after authorization, filtering
	// and ordering. Offset and Limit apply to the resulting suffix. It cannot
	// be combined with AdjacentTo; an absent or filtered anchor is not found.
	StartAt       core.RatingKey
	Offset, Limit int
	Sort          core.SortOrder
	Desc          bool
	Types         []core.MediaType
	Recursive     bool
	Season        *int // Optional presented season number.
	Filter        core.Filter
	Watched       *bool
	Favorite      *bool
}

type ItemRequest struct {
	Viewer *core.Viewer
	Device core.Device
	Key    core.RatingKey
}

type LANLazyStreams interface {
	IssueLAN(context.Context, *http.Request, PlanRequest) (string, error)
	ServeHTTP(http.ResponseWriter, *http.Request)
}

type LastPlayedSourceReader interface {
	LastPlayedSource(context.Context, *Viewer, Device, RatingKey) (*PlaybackSourceHistory, error)
}

type LatestItem struct {
	Title   Title
	AddedAt *time.Time
}

type LazyHLSStreams interface {
	IssueHLS(context.Context, string, PlanRequest, StreamRequest) (string, error)
}

type LazyStreams interface {
	Issue(context.Context, string, PlanRequest) (string, error)
	ServeHTTP(http.ResponseWriter, *http.Request)
}

type LibraryActivity interface {
	LatestAdded(context.Context, *Viewer, Device, string, int) ([]LatestItem, error)
	// requireExact requests a complete filtered count; an implementation must
	// return an error if it cannot determine one within its resource bounds.
	Resume(context.Context, *Viewer, Device, string, []MediaType, int, int, bool) (ActivityPage, error)
}

type LibraryActivityGrouping interface {
	LatestAddedGrouped(context.Context, *Viewer, Device, string, int, bool) ([]LatestItem, error)
}

type LibraryCollageSource interface {
	LibraryCollage(context.Context, *Viewer, Device, string) (Image, error)
}

type LineupStreams interface {
	IssueLineup(context.Context, string, PlanRequest) (string, error)
}

type ListenerSpec struct {
	Address    string `json:"address"`
	PathPrefix string `json:"pathPrefix,omitempty"`
	TLS        bool   `json:"tls"`
	// Shared means the app supplies this listener; the manager must not bind it.
	Shared bool `json:"shared,omitempty"`
}

type LiveChannel struct {
	ID, Number, Name, Kind, Logo, Rating string
	Favorite                             bool
	Images                               []Image
}

type LiveGuideQuery struct {
	Channels    []string
	From, Until time.Time
	Limit       int
	Device      core.Device
}

type LiveProgramme struct {
	ID, ChannelID                   string
	Start, End                      time.Time
	Item                            core.RatingKey
	Title, Summary, Rating, Artwork string
	ShowTitle, EpisodeTitle         string
	Season, Episode                 int
	Images                          []Image
}

type LiveTV interface {
	Channels(context.Context, *core.Viewer) ([]LiveChannel, error)
	Guide(context.Context, *core.Viewer, LiveGuideQuery) ([]LiveProgramme, error)
	ResolveChannelGUID(context.Context, *core.Viewer, string) (LiveChannel, error)
	ResolveProgrammeGUID(context.Context, *core.Viewer, string, LiveGuideQuery) (LiveProgramme, error)
}

type Marker struct {
	Type       string
	Start, End time.Duration
}

type MediaInfo = core.MediaInfo

type MediaType = core.MediaType

type Membership struct {
	Present bool
	AddedAt *time.Time
}

type MembershipReader interface {
	FavoriteItem(context.Context, *Viewer, Device, RatingKey) (Membership, error)
	WatchlistItem(context.Context, *Viewer, Device, RatingKey) (Membership, error)
}

type NotInterestedEntry struct {
	Key     core.RatingKey
	AddedAt time.Time
}

type NotInterestedPage struct {
	Items []NotInterestedEntry
	Total int
}

type OpenRequest struct {
	Protocol Protocol
	PlanID   string
	Viewer   *core.Viewer
	Device   core.Device
}

type Page = core.Page

type PageArtwork interface {
	ListPage(context.Context, *core.Viewer, core.Device, []core.Title) (map[core.RatingKey][]Image, error)
}

type PageFreshness struct {
	Catalog, Config, Watch, Favorite, Hidden, Listed, Images, Grants, Accounts, Safety uint64
	ArtBucket                                                                          int64
}

type PageQuery struct{ Offset, Limit int }

type PartyActor struct {
	Viewer   *core.Viewer
	Device   core.Device
	Protocol Protocol
}

type PartyCommand struct {
	ID, Action, Jellyfin, PlaylistItemID, SessionID string
	Position                                        time.Duration
	ExecuteAt, IssuedAt                             time.Time
	Playback                                        string
	SelectionRevision                               int64
	Rate                                            float64
}

type PartyCreate struct {
	RoomID, Mode, Name string
}

type PartyEvent struct {
	Type                 string
	View                 PartyView
	Command              PartyCommand
	GroupKind            string
	GroupData            any
	Reason               string
	ClientSent, Received time.Time
	Sent                 time.Time
	ErrorCode            string
	ErrorMessage         string
}

type PartyInput struct {
	Action   string
	Position time.Duration
	Rate     float64
}

type PartyJoin struct {
	Code, Token, GroupID string
}

type PartyMember struct {
	ViewerID                                       int64
	Name                                           string
	Protocol                                       Protocol
	DeviceID                                       string
	Host, Self, Connected, Ready, Buffering, Lobby bool
	IgnoreWait, Blocked                            bool
}

type PartyPick struct {
	Item              core.RatingKey
	FileID, LibraryID string
}

type PartyQueue struct {
	Kind            string
	Items           []core.RatingKey
	Index           int
	PlaylistItemID  string
	Position        time.Duration
	Repeat, Shuffle string
}

type PartyQueueItem struct {
	Item           core.RatingKey
	ContentID      string
	PlaylistItemID string
}

type PartyReport struct {
	Kind                           string
	SessionID, CommandID, Playlist string
	Position                       time.Duration
	Rate                           float64
	Paused, Ready, Lobby, Ignore   *bool
	ClientSent, When               time.Time
	Playing                        bool
}

type PartySocket struct {
	Actor  PartyActor
	Events <-chan PartyEvent
	Close  func()
}

type PartyTicket struct {
	Ticket                string
	ExpiresIn, MaxSeconds int
	Protocol              string
}

type PartyView struct {
	RoomID, Code, JoinToken, RoomToken, InvitePath, Name string
	Phase, Playback, SelectionMode, GuestPolicy, Role    string
	SelectionRevision, Generation                        int64
	Item                                                 core.RatingKey
	ContentID, FileID, LibraryID                         string
	Paused                                               bool
	Position                                             time.Duration
	AnchorAt                                             time.Time
	Rate                                                 float64
	HostConnected                                        bool
	CanTransport, CanManage, IgnoreWait                  bool
	AttachedSessionID                                    string
	Members                                              []PartyMember
	Repeat, Shuffle                                      string
	Queue                                                []PartyQueueItem
	QueueIndex                                           int
	UpdatedAt                                            time.Time
}

type PeopleImageReader interface {
	AuthorizePersonImage(context.Context, *Viewer, Device, RatingKey, Image, func(context.Context) error) error
}

type PeopleQuery struct {
	Query string
	Limit int
	Scope PeopleScope
}

type PeopleReader interface {
	People(context.Context, *Viewer, Device, PeopleQuery) ([]PersonDetail, error)
	Person(context.Context, *Viewer, Device, string, PersonReadOptions) (PersonDetail, error)
	// PersonCredit checks one current cached title-credit membership.
	PersonCredit(context.Context, *Viewer, Device, RatingKey, int64) (PersonDetail, error)
}

type PeopleScope string

type Person = core.Person

type PersonArtwork interface {
	PersonImages(context.Context, ArtworkRequest, Title) ([]Image, error)
}

type PersonDetail struct {
	ID, Name, IMDB string
	TMDB           int64
	ArtworkItem    RatingKey
	Images         []Image
}

type PersonReadOptions struct{ Prefetch bool }

type PersonalHomeStore interface {
	LoadPersonalHome(ctx context.Context, protocol string, viewerID int64, config string) ([]byte, error)
	SavePersonalHome(ctx context.Context, protocol string, viewerID int64, config string, body []byte) error
	PersonalHomeViewers(ctx context.Context) ([]core.User, error)
}

type Placement string

type PlanRequest struct {
	// Version is a resolver-issued variant ID in legacy mode, or a scoped
	// VersionHandles handle when ExactVersion is set. Empty selects automatically.
	Version string
	// ResolvedRelease is the release id just returned by VersionHandles.Resolve
	// for Version, in this process. Plan checks that the handle row still names
	// that release and does not list offers again. Callers that did not resolve
	// leave it empty, and Plan validates the offer itself.
	ResolvedRelease string
	// ExpectedSourceETag binds playback to a previously offered resolved source.
	// It is not an authorization credential. A missing or changed source fails
	// closed instead of resolving a different release.
	ExpectedSourceETag string
	// DetailSource is an opaque, scoped handle returned by DetailPlan.
	DetailSource string
	Viewer       *core.Viewer
	Device       core.Device
	Protocol     Protocol
	Item         core.RatingKey
	// Channel is the stable Host.LiveTV channel ID. Exactly one of Item and
	// Channel must be supplied.
	Channel string
	Caps    core.ClientCaps
	Intent  PlayIntent
}

type PlayIntent struct {
	Estimate bool
	Options  core.DecideOptions
	// ExactVersion treats PlanRequest.Version as a scoped opaque handle and
	// refuses any substitute release, including during later source failover.
	ExactVersion bool
	// Set flags distinguish omitted choices from stream index zero and
	// an explicit subtitle-off choice (SubtitleStream == -1).
	AudioSet    bool
	SubtitleSet bool
	// AudioOrdinal selects a zero-based audio-only position from the opened,
	// probed source. SubtitleStreamIndex is an absolute source stream index;
	// -1 explicitly disables subtitles. Nil preserves normal preferences.
	AudioOrdinal        *int
	SubtitleStreamIndex *int
	Position            time.Duration
	ClientSessionID     string
	PlaybackID          string
	// AllowTranscoding is nil for the existing default; false forbids video
	// or audio transcoding while retaining any allowed direct-stream remux.
	AllowTranscoding *bool
	// PreferRemux asks for a copy-only remux when source changes would
	// otherwise disrupt the client. The broker still decides whether it applies.
	PreferRemux bool
	Plex        *PlexHints
}

type PlayPlan struct {
	ID        string
	Estimated bool
	Media     core.MediaInfo
	Decision  core.Decision
	// Alternatives are evaluated against this same source and client policy.
	// DirectStream denotes copy-only remux, without encoding either stream.
	DirectPlay, DirectStream, Transcoding bool
	// HLS reports whether this resolved source can be delivered as HLS under
	// the declared client profile. Encoder capacity is checked at stream start.
	HLS bool
	// HLSContainer is the authoritative segment container from the resolved HLS
	// output decision (mpegts, fmp4, or mkv). Empty means unknown or ineligible;
	// it is not the source container or an encoder-capacity reservation.
	HLSContainer string
	// ETag identifies the resolved immutable source when available; it is
	// empty when the backend cannot prove a stable source identity.
	ETag string
	// DetailSource is a scoped, expiring handle for the resolved source.
	DetailSource string
}

type PlaybackSourceHistory = core.PlaybackSourceHistory

type Playlist = core.Playlist

type PlaylistLibrary interface {
	Playlists(context.Context, *core.Viewer, PageQuery) (PlaylistPage, error)
	CreatePlaylist(context.Context, *core.Viewer, string, []core.RatingKey) (*core.Playlist, error)
	AddPlaylistItems(context.Context, *core.Viewer, core.RatingKey, []core.RatingKey) error
	RemovePlaylistItem(context.Context, *core.Viewer, core.RatingKey, int) error
	MovePlaylistItem(context.Context, *core.Viewer, core.RatingKey, int, int) error
	DeletePlaylist(context.Context, *core.Viewer, core.RatingKey) error
}

type PlaylistPage struct {
	Items []core.Playlist
	Total int
}

type PlexHints struct {
	Collection        string
	MediaIndex        int
	PartReleaseID     string
	AudioSelection    int
	SubtitleSelection int
	SubtitleSet       bool
	SubtitleStream    *core.StreamInfo
}

type Preferences interface {
	Get(context.Context, *core.Viewer, string, string) (json.RawMessage, error)
	Put(context.Context, *core.Viewer, string, string, json.RawMessage) error
	Delete(context.Context, *core.Viewer, string, string) error
}

type ProgressSample struct {
	InstallationID  string
	Sequence        uint64
	PositionSeconds float64
	Paused          bool
	// Stop finalizes playback under the same ownership gate as sample ordering.
	Stop bool
}

type Protocol = core.Protocol

type PublicViewer struct {
	ID   int64
	Name string
	// HasConfiguredPassword is known only when the identity service can
	// establish it from its active local credential record.
	HasConfiguredPassword *bool
}

type QuickConnectDetails struct {
	Approved     bool
	Code, Secret string
	Device       core.Device
	CreatedAt    time.Time
	ExpiresAt    time.Time
}

type RatingKey = core.RatingKey

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

type RelatedArtwork struct {
	People              []Image
	PeopleAuthoritative bool
	Season, Series      *ArtworkOwner
}

type RelatedArtworkProvider interface {
	RelatedArtwork(context.Context, *Viewer, Device, RatingKey) (RelatedArtwork, error)
}

type ReportOutcome string

type RequestMemo struct {
	Mu      sync.Mutex
	Viewer  *core.User
	Visible map[core.RatingKey]bool
	Aired   map[core.RatingKey]AiredMemo
}

type ResolvedEventSubject struct {
	Ref           FavoriteRef
	PersonFacetID string
	Favorite      bool
	UserData      *core.WatchStatus
}

type RouteSource interface{ Routes() []conform.Route }

type Row struct {
	ID, Title    string
	Purpose      RowPurpose
	Kind         string // Stable semantic producer kind, independent of protocol.
	Layout       RowLayout
	Style        string
	Promoted     bool
	Rank         int
	ImpressionID string
	// Handle is a server-issued row interaction capability.
	Handle string
	// Entries is the ordered heterogeneous row; Items remains for compatibility.
	Entries    []RowEntry
	Items      []core.Title
	More       bool
	Collection core.RatingKey
}

type RowDirectory struct {
	ID, Title, Description, Image string
	Kind                          string
}

type RowEntry struct {
	Kind        RowEntryKind
	Handle      string
	Title       *core.Title
	Collection  *core.Collection
	Playlist    *core.Playlist
	LiveChannel *RowLiveChannel
	Directory   *RowDirectory
}

type RowEntryKind string

type RowInteraction struct {
	Viewer   *core.Viewer
	Device   core.Device
	Protocol Protocol
	Handle   string
	Kind     RowInteractionKind
}

type RowInteractionKind string

type RowInteractionReporter interface {
	ReportRowInteraction(context.Context, RowInteraction) error
}

type RowLayout struct {
	Order int
	Style string
	Paint RowPaint
}

type RowLiveChannel struct {
	ID, Number, Name, Logo string
	GuideReference         string
	Current, Next          *RowProgramme
	Images                 []Image
}

type RowPaint struct {
	Background, Foreground, Accent string
	Artwork                        string
}

type RowProgramme struct {
	ID, Title, EpisodeTitle string
	Start, End              time.Time
	Season, Episode         int
	Item                    core.RatingKey
}

type RowPurpose = core.RowPurpose

type RowRequest struct {
	Viewer    *core.Viewer
	Device    core.Device
	Placement Placement
	ViewID    string
	Item      core.RatingKey
	Limit     int
	// Purpose asks for one row. The zero value still returns the whole placement.
	Purpose RowPurpose
}

type RowView struct {
	ID          string
	Title, Kind string
	Purpose     RowPurpose
	Layout      RowLayout
	Rank        int
}

type RowViewPage struct {
	Entries          []RowEntry
	ImpressionHandle string
	Total            int
	TotalExact       bool
	More             bool
	// Truncated means the snapshot is a bounded prefix of the source row.
	// More only indicates entries available in this snapshot.
	Truncated bool
}

type RowViewPageRequest struct {
	Viewer        *Viewer
	Device        Device
	Protocol      Protocol
	ID            string
	Offset, Limit int
	Kinds         []RowEntryKind
}

type RowViewRequest struct {
	Viewer    *Viewer
	Device    Device
	Protocol  Protocol
	Placement Placement
	ViewID    string
	Item      RatingKey
	// Refresh starts new snapshots and invalidates earlier page generations.
	Refresh bool
}

type RowViews interface {
	ListRowViews(context.Context, RowViewRequest) ([]RowView, error)
	ResolveRowView(context.Context, RowViewPageRequest) (RowViewPage, error)
}

type SampleReporter interface {
	ReportSample(context.Context, SessionAccess, string, ProgressSample) (ReportOutcome, error)
}

type ScopedMedia interface {
	ServeMediaAccess(http.ResponseWriter, *http.Request, SessionAccess)
}

type ScopedTrackPreferenceService interface {
	GetScoped(context.Context, *Viewer, TrackScope) (TrackPreferences, int, int, string, map[string]string, error)
	SetScoped(context.Context, *Viewer, string, string, TrackPreferencePatch) error
	DeleteScoped(context.Context, *Viewer, string, string, string) error
	SetAudio(context.Context, *Viewer, []string) error
	SetSubtitleLanguage(context.Context, *Viewer, []string) error
	SetSubtitleMode(context.Context, *Viewer, string) error
	SetAppearance(context.Context, *Viewer, json.RawMessage) error
	SetBitrate(context.Context, *Viewer, int) error
	SetHeight(context.Context, *Viewer, int, string) error
}

type SearchPage struct {
	Page         core.Page
	TotalExact   bool
	Continuation Continuation
}

type Session struct {
	ID, MediaPath string
	Protocol      Protocol
	ViewerID      int64
	// ClientSessionID is a non-secret protocol installation/session identifier.
	ClientSessionID string
	Device          core.Device
	Item            core.RatingKey
	Channel         string
	Media           *core.MediaInfo
	StartedAt       time.Time
	Capabilities    *SessionCapabilities
}

type SessionAccess struct {
	Viewer   *core.Viewer
	Device   core.Device
	Protocol Protocol
	Owner    bool
}

type SessionBusyError struct{ RetryAfter time.Duration }

type SessionCapabilities struct {
	PlayableMediaTypes           []string
	SupportedCommands            []string
	SupportsMediaControl         *bool
	SupportsPersistentIdentifier *bool
	SupportsRemoteControl        *bool
	DeviceProfile                json.RawMessage
	AppStoreURL                  string
	IconURL                      string
}

type SessionMarkers struct {
	Known      bool
	SourceETag string
	Markers    []Marker
}

type Sessions interface {
	Plan(context.Context, PlanRequest) (PlayPlan, error)
	Open(context.Context, OpenRequest) (Session, error)
	// StartStream revalidates access to the session and returns its scoped URL.
	StartStream(context.Context, SessionAccess, string, StreamRequest) (string, error)
	// SubtitleURL returns a scoped URL for a subtitle stream index and format.
	SubtitleURL(context.Context, SessionAccess, string, int, string) (string, error)
	// Markers returns source-bound ranges for the authorized playback session.
	Markers(context.Context, SessionAccess, string) (SessionMarkers, error)
	// ServeMedia authorizes the scoped grant and serves direct, HLS or DASH data.
	ServeMedia(http.ResponseWriter, *http.Request)
	Report(context.Context, SessionAccess, string, Timeline) error
	Stop(context.Context, SessionAccess, string) error
	Command(context.Context, *core.Viewer, string, Command) error
	UpdateCapabilities(context.Context, SessionAccess, SessionCapabilities) error
	Capabilities(context.Context, SessionAccess) (SessionCapabilities, error)
	Sessions(context.Context, SessionAccess) ([]Session, error)
	Recover(context.Context, string, string, time.Duration) error
	TranscodeFor(context.Context, string) (core.HLSSession, bool)
	// Events includes events from all cluster nodes, filters by viewer unless owner access is authorized, and ends on cancellation.
	Events(context.Context, EventScope) (<-chan Event, error)
}

type Settings map[string]any

type SettingsValidator interface{ ValidateSettings(Settings) error }

type SortOrder = core.SortOrder

type SourceOffer struct {
	ID        string
	ExpiresAt time.Time
	Target    SourceOfferTarget
}

type SourceOfferTarget struct {
	Item          RatingKey
	VersionHandle string
	DetailSource  string
	ETag          string
}

type SourceOffers interface {
	Issue(context.Context, VersionScope, SourceOfferTarget) (SourceOffer, error)
	IssueBatch(context.Context, VersionScope, []SourceOfferTarget) ([]SourceOffer, error)
	Resolve(context.Context, VersionScope, string) (SourceOffer, error)
	Revoke(context.Context, VersionScope, string) error
}

type Status struct {
	Mounted          bool     `json:"mounted"`
	Addresses        []string `json:"addresses"`
	ConnectURLs      []string `json:"connectUrls,omitempty"`
	LAN              string   `json:"lan"`
	WAN              string   `json:"wan"`
	Clients24h       int      `json:"clients24h"`
	Clients24hKnown  bool     `json:"clients24hKnown"`
	LiveStreams      int      `json:"liveStreams"`
	LiveStreamsKnown bool     `json:"liveStreamsKnown"`
	TargetVersion    string   `json:"targetVersion"`
	Conformance      string   `json:"conformance"`
	Error            string   `json:"error,omitempty"`
	Warnings         []string `json:"warnings,omitempty"`
}

type StreamFormat string

type StreamInfo = core.StreamInfo

type StreamRequest struct {
	Format          StreamFormat
	Position        time.Duration
	SegmentDuration time.Duration
}

type Subscriber interface {
	Subscribe(context.Context, EventScope) (<-chan Event, error)
}

type SubtitleCatalog interface {
	Enabled() bool
	Search(context.Context, *core.Viewer, core.Device, core.RatingKey, string) ([]SubtitleOffer, error)
	Download(context.Context, *core.Viewer, core.Device, core.RatingKey, string) (int, error)
}

type SubtitleOffer struct {
	ID, Language, Name, Provider, Format, Author     string
	Downloads                                        int
	Rating                                           float64
	HearingImpaired, Forced, HashMatch, AITranslated bool
}

type SurfaceIdentity interface {
	Resolve(context.Context, string) (*core.Viewer, error)
	// ViewerTimes revalidates the surface credential and allows only the same
	// viewer or an active owner to read another active viewer's timestamps.
	ViewerTimes(context.Context, string, int64) (ViewerTimes, error)
	PublicViewers(context.Context) ([]PublicViewer, error)
	SignIn(context.Context, string, string, core.Device) (string, error)
	IssueRefresh(context.Context, string, core.Device) (string, error)
	Refresh(context.Context, string, core.Device) (string, string, error)
	QuickConnectInitiate(context.Context, core.Device) (code, secret string, err error)
	QuickConnectStatus(context.Context, string) (approved bool, err error)
	QuickConnectDetails(context.Context, string) (QuickConnectDetails, error)
	QuickConnectPoll(context.Context, string) (string, error)
	QuickConnectApprove(context.Context, *core.Viewer, string) error
	Revoke(context.Context, string) error
	SetupComplete() bool
}

type Ticket struct {
	Viewer *Viewer
	Device Device
	// SourceHash identifies the issuing grant for host-side revalidation only.
	SourceHash string
}

type Tickets interface {
	Issue(context.Context, string, Device, string) (string, error)
	Consume(context.Context, string, string) (Ticket, error)
	Active(context.Context, Ticket) (bool, error)
}

type Timeline struct {
	// PlaybackID may be empty for clients that do not send one. The broker
	// preserves its no-ID supersession semantics.
	PlaybackID      string
	ClientSessionID string
	// Sequence is optional; zero preserves the legacy unordered behavior.
	Sequence           uint64
	Position, Duration time.Duration
	State              string
}

type Title = core.Title

type TrackPreferencePatch struct {
	AudioLanguages, SubtitleLanguages *[]string
	SubtitleMode                      *string
	SubtitleAppearance                *json.RawMessage
	MaxBitrateKbps                    *int
	MaxHeight                         *int
	PreferredQuality                  *string
}

type TrackPreferenceService interface {
	Get(context.Context, *Viewer) (TrackPreferences, error)
	SetSubtitle(context.Context, *Viewer, []string, string) error
}

type TrackPreferences struct {
	AudioLanguages, SubtitleLanguages []string
	SubtitleMode                      string
	PreferOriginal                    bool
	SubtitleAppearance                json.RawMessage
}

type TrackScope struct{ Device, Series, Library string }

type TranscodeCapacityError struct {
	RetryAfter time.Duration
	Cause      error
}

type TrickplayOffer struct {
	Width, Height int
	Columns, Rows int
	Count         int
	Interval      time.Duration
	Bandwidth     int
}

type TrickplayTiles interface {
	TrickplayOffer(context.Context, SessionAccess, core.RatingKey) (TrickplayOffer, bool)
	TrickplaySheet(context.Context, SessionAccess, core.RatingKey, int) ([]byte, error)
}

type Version struct {
	ID, Name string
	// Edition is the release's named cut when the catalogue recorded one.
	Edition string
	// AddedAt follows date added. Movies and episodes use their own release
	// or air date. Series and seasons use the latest aired episode, then
	// the premiere. It is not a catalogue insertion, observation, or refresh.
	AddedAt time.Time
	Media   core.MediaInfo
	// Markers are ranges for this version's probed timeline. Nil means the
	// version has no separate timeline yet; a detail-level marker set is not
	// a substitute when several files are present.
	Markers []Marker
	// Source facts are absent unless they are known for this version. FileName
	// is a basename only; DateModified is never a catalogue fallback date.
	FileName     string     `json:"fileName,omitempty"`
	PartCount    *int       `json:"partCount,omitempty"`
	ETag         string     `json:"etag,omitempty"`
	DateModified *time.Time `json:"dateModified,omitempty"`
	PublishedAt  *time.Time `json:"publishedAt,omitempty"`
	// FirstObservedAt is the first committed observation of this candidate offer.
	// Nil means that no trustworthy observation was recorded.
	FirstObservedAt *time.Time `json:"firstObservedAt,omitempty"`
}

type VersionHandleBatch interface {
	IssueBatch(context.Context, VersionScope, core.RatingKey, []string) (map[string]string, error)
}

type VersionHandles interface {
	Issue(context.Context, VersionScope, core.RatingKey, string) (string, error)
	Resolve(context.Context, VersionScope, string) (VersionTarget, error)
	// MatchSession verifies that a scoped handle denotes the source bound to
	// this authenticated local playback session.
	MatchSession(context.Context, VersionScope, string, string) error
}

type VersionScope struct {
	Viewer   *core.Viewer
	Device   core.Device
	Protocol Protocol
	Caps     core.ClientCaps
}

type VersionTarget struct {
	Item core.RatingKey
	// Release is the candidate id stored with the handle. Empty when the
	// handle was resolved by an older caller that only needed the parent.
	Release string
}

type VersionedPreferences interface {
	GetVersioned(context.Context, *core.Viewer, string, string) (json.RawMessage, int64, time.Time, error)
	PutVersioned(context.Context, *core.Viewer, string, string, json.RawMessage) (int64, time.Time, error)
}

type View struct {
	ID   string
	Name string
	Type core.MediaType
	// Virtual is true only when the host asserts this library has no physical
	// locations. False means the host did not assert virtual origin.
	Virtual bool
}

type Viewer = core.Viewer

type ViewerCapabilities struct {
	IsOwner           *bool     `json:"isOwner,omitempty"`
	CanPlayRemote     *bool     `json:"canPlayRemote,omitempty"`
	CanPlay           *bool     `json:"canPlay,omitempty"`
	RemoteBitrateKbps *int      `json:"remoteBitrateKbps,omitempty"`
	CanTranscode      *bool     `json:"canTranscode,omitempty"`
	CanTranscodeAudio *bool     `json:"canTranscodeAudio,omitempty"`
	CanTranscodeVideo *bool     `json:"canTranscodeVideo,omitempty"`
	CanRemux          *bool     `json:"canRemux,omitempty"`
	CanUseLiveTV      *bool     `json:"canUseLiveTV,omitempty"`
	CanManageLiveTV   *bool     `json:"canManageLiveTV,omitempty"`
	HasLocalPassword  *bool     `json:"hasLocalPassword,omitempty"`
	AllowedLibraries  *[]View   `json:"allowedLibraries,omitempty"`
	MaxRating         *string   `json:"maxRating,omitempty"`
	CanDownload       *bool     `json:"canDownload,omitempty"`
	MaxActiveSessions *int      `json:"maxActiveSessions,omitempty"`
	BlockedTags       *[]string `json:"blockedTags,omitempty"`
	PeerRemote        *bool     `json:"peerRemote,omitempty"`
}

type ViewerCapabilitiesFunc func(context.Context, *Viewer, Device, netip.Addr) (ViewerCapabilities, error)

type ViewerPolicy interface {
	SetMaxRating(context.Context, *Viewer, string) error
}

type ViewerTimes struct {
	LastLogin, LastActivity time.Time
}

type VirtualPaths interface {
	Path(context.Context, *Viewer, Device, RatingKey) (string, error)
	// Paths resolves at most 50 distinct keys (256 input entries), omitting
	// hidden or unsupported items and sharing viewer-scoped library scans.
	Paths(context.Context, *Viewer, Device, []RatingKey) (map[RatingKey]string, error)
	// Base returns the verified reachable WebDAV base URL, or an error when
	// WebDAV is disabled or unreachable for the requesting client.
	Base(context.Context, *http.Request) (string, error)
}

type WatchParty interface {
	Create(context.Context, PartyActor, PartyCreate) (PartyView, error)
	Join(context.Context, PartyActor, PartyJoin) (PartyView, error)
	Get(context.Context, PartyActor, string, string) (PartyView, error)
	Select(context.Context, PartyActor, string, string, PartyPick) (PartyView, error)
	Start(context.Context, PartyActor, string, string) (PartyView, error)
	Stop(context.Context, PartyActor, string, string) (PartyView, error)
	Policy(context.Context, PartyActor, string, string, string) (PartyView, error)
	End(context.Context, PartyActor, string, string) error
	Leave(context.Context, PartyActor) error
	List(context.Context, PartyActor) []PartyView
	Transport(context.Context, PartyActor, string, string, PartyInput) error
	Report(context.Context, PartyActor, PartyReport) error
	Queue(context.Context, PartyActor, PartyQueue) error
	IssueTicket(context.Context, PartyActor, string, string) (PartyTicket, error)
	OpenSocket(context.Context, string, string) (PartySocket, error)
	Subscribe(PartyActor) (<-chan PartyEvent, func())
}

type WatchStatus = core.WatchStatus