api

type AdaptiveConfig struct {
	InitialDelay      time.Duration
	MaxDelay          time.Duration
	BackoffMultiplier float64
	MaxAttempts       int
	Enabled           bool
}

type AdminUserCreatedResponse struct {
	Username string    `json:"username"`
	Email    string    `json:"email"`
	Role     auth.Role `json:"role"`
	ID       int64     `json:"id"`
}

type ArrConfig struct {
	URL       string
	APIKey    string
	PublicURL string
}

type ArrConfigProvider interface {
	SonarrConfig() ArrConfig
	RadarrConfig() ArrConfig
}

type AudioRuleJSON struct {
	Audio     string             `json:"audio"`
	Subtitles []SubtitleTargJSON `json:"subtitles"`
}

type AudioSyncResult struct {
	Method     string
	Cues       []SubtitleCue
	Offset     int64   // milliseconds
	Confidence float64 // 0.0 to 1.0
	Applied    bool    // true if sync was applied and should be saved
}

type AuthConfigProvider interface {
	AuthEnabled() bool
	BasicAuthEnabled() bool
	OIDCEnabled() bool
	OIDCConfig() auth.OIDCConfig
	SessionIdleTimeout() time.Duration
	SessionAbsoluteTimeout() time.Duration
	CheckBreachedPasswords() bool
	WebAuthnRPID() string
}

type AuthError struct{ Msg string }

type BackoffEntry struct {
	LastTried time.Time  `json:"last_tried"`
	NextRetry time.Time  `json:"next_retry"`
	MediaType MediaType  `json:"media_type"`
	MediaID   string     `json:"media_id"`
	Language  string     `json:"language"`
	Provider  ProviderID `json:"provider"`
	Failures  int        `json:"failures"`
}

type BackoffParams struct {
	InitialDelay time.Duration
	MaxDelay     time.Duration
	Multiplier   float64
}

type BackoffStore interface {
	RecordNoResult(ctx context.Context, mediaType MediaType, mediaID, language string, providerName ProviderID, bp BackoffParams) error
	BackedOffProviders(ctx context.Context, mediaType MediaType, mediaID, language string, maxAttempts int) ([]ProviderID, error)
}

type CacheClearer interface {
	ClearCache()
}

type CleanupResult struct {
	// Paths are subtitle file paths whose DB entries were removed.
	// The caller is responsible for validating and deleting files from disk.
	Paths []string
}

type ConfigDrift struct {
	// RemovedLanguages are language codes that were in the old config
	// but not in the new one. Their search_attempts should be cleared.
	RemovedLanguages []string

	// RemovedProviders are provider names that were enabled in the old
	// config but disabled or removed in the new one. Their
	// search_attempts should be cleared.
	RemovedProviders []ProviderID

	// AdaptiveDisabled is true when adaptive search was enabled in the
	// old config but disabled in the new one. All search_attempts
	// should be cleared.
	AdaptiveDisabled bool
}

type ConfigLoader func(data []byte) (ConfigProvider, error)

type ConfigProvider interface {
	ScoringConfig
	LanguageResolver
	ArrConfigProvider
	ProviderConfigProvider
	ServerConfig
	PathValidator
	SearchConfigProvider
	AuthConfigProvider
	UIConfigProvider
}

type CoverageStore interface {
	RecordSubtitleFiles(ctx context.Context, mediaType MediaType, mediaID string, files []SubtitleFile) (bool, error)
	UpsertSubtitleFile(ctx context.Context, mediaType MediaType, mediaID string, f *SubtitleFile) error
	GetSubtitleFiles(ctx context.Context, mediaType MediaType, mediaIDPrefix string) ([]SubtitleEntry, error)
	DeleteSubtitleFile(ctx context.Context, mediaType MediaType, mediaID, language string, variant Variant, source SubtitleSource, path string) error
	RecordScanState(ctx context.Context, rec *ScanRecord) error
	GetScanStates(ctx context.Context, mediaType MediaType, mediaIDPrefix string) ([]ScanStateRow, error)
	RecentlyScanned(ctx context.Context, cutoff time.Time) (map[string]bool, error)
	TotalSubtitleFiles(ctx context.Context) (int, error)
	LastScanTime(ctx context.Context) (string, error)
}

type DownloadMeta struct {
	Title      string
	ImdbID     string
	ReleaseTag string
	VideoPath  string // Path to the video file (for reconciliation and upgrades).
	Season     int
	Episode    int
	Manual     bool // True if user manually selected this subtitle.
}

type DownloadRecord struct {
	Meta         *DownloadMeta
	MediaType    MediaType
	MediaID      string
	Language     string
	Variant      Variant // subtitle variant (standard/hi/forced); empty is normalized to standard
	ProviderName ProviderID
	ReleaseName  string
	Path         string
	Score        int
}

type DownloadStore interface {
	SaveDownload(ctx context.Context, rec *DownloadRecord) error
	DownloadedRefs(ctx context.Context, mediaType MediaType, mediaID, language string) ([]DownloadedRef, error)
	CurrentScore(ctx context.Context, mediaType MediaType, mediaID, language string, variant Variant) (score int, mediaImported time.Time, found bool, err error)
}

type DownloadedRef struct {
	ReleaseName string
	Provider    ProviderID
}

type EmbeddedTrack struct {
	Codec           string
	Lang            string
	Name            string
	Index           int
	Forced          bool
	HearingImpaired bool
}

type HistoryStore interface {
	HistoryMediaIDs(ctx context.Context, mediaType MediaType, mediaIDPrefix string) ([]string, error)
}

type KeyGenerated struct {
	CreatedAt time.Time `json:"created_at"`
	Key       string    `json:"key"`
	KeyPrefix string    `json:"key_prefix"`
	KeySuffix string    `json:"key_suffix"`
	Label     string    `json:"label"`
	ID        int64     `json:"id"`
}

type LanguageResolver interface {
	ResolveTargetsWithFallback(originalLang string, audioLangs []string) []SubtitleTarget
	LanguageCodes() []string
	ProvidersForTarget(t *SubtitleTarget, allProviders []ProviderID) []ProviderID
	MinScoreForTarget(t *SubtitleTarget, mediaType MediaType) int
}

type LanguageRulesJSON struct {
	Rules   []AudioRuleJSON    `json:"rules,omitempty"`
	Default []SubtitleTargJSON `json:"default,omitempty"`
}

type LogFormat string

type LogLevel string

type LoginSuccess struct {
	Redirect string     `json:"redirect"`
	User     MeResponse `json:"user"`
}

type MaintStore interface {
	DeleteStateByPaths(ctx context.Context, paths []string) (CleanupResult, error)
	CleanupDrift(ctx context.Context, drift ConfigDrift) error
	ReconcileState(ctx context.Context) (ReconcileResult, error)
}

type ManualLockEntry struct {
	MediaType MediaType `json:"media_type"`
	MediaID   string    `json:"media_id"`
	Language  string    `json:"language"`
	Variant   Variant   `json:"variant"`
	Count     int       `json:"count"`
}

type ManualLockStore interface {
	// IsManuallyLocked reports whether the quad has a manual row. An empty
	// variant asks whether ANY variant of the language is locked.
	IsManuallyLocked(ctx context.Context, mediaType MediaType, mediaID, language string, variant Variant) (bool, error)
	// ClearManualLock clears the quad's lock. An empty variant clears the
	// locks of ALL variants of the language.
	ClearManualLock(ctx context.Context, mediaType MediaType, mediaID, language string, variant Variant) error
	// ManualDownloadCount counts the quad's manual rows (exact variant).
	ManualDownloadCount(ctx context.Context, mediaType MediaType, mediaID, language string, variant Variant) (int, error)
	// ManualSubtitlePaths returns the manual rows' file paths. An empty
	// variant returns the paths of ALL variants of the language.
	ManualSubtitlePaths(ctx context.Context, mediaType MediaType, mediaID, language string, variant Variant) ([]string, error)
	// NextManualNumber returns the next manual ordinal for the quad (exact
	// variant): movie.fr.1.srt and movie.fr.forced.1.srt count independently.
	NextManualNumber(ctx context.Context, mediaType MediaType, mediaID, language string, variant Variant) int
}

type MatchMethod string

type MatchSet struct {
	Hash             bool
	Source           bool
	ReleaseGroup     bool
	StreamingService bool
	VideoCodec       bool
	HDR              bool
	Edition          bool
	SeasonPack       bool
	SeriesIMDB       bool
	IMDB             bool
}

type MeResponse struct {
	Username    string    `json:"username"`
	Role        auth.Role `json:"role"`
	ID          int64     `json:"id"`
	HasPasskeys bool      `json:"has_passkeys"`
	OIDCLinked  bool      `json:"oidc_linked"`
	HasPassword bool      `json:"has_password"`
	CanLinkOIDC bool      `json:"can_link_oidc"`
}

type MediaType string

type PasskeyRegistered struct {
	CreatedAt time.Time `json:"created_at"`
	Name      string    `json:"name"`
	Transport string    `json:"transport"`
	ID        int64     `json:"id"`
}

type PathValidator interface {
	MediaRoots() []string
	ValidatePath(ctx context.Context, path string) error
	RemoveUnderRoot(ctx context.Context, path string) error
}

type PollKey string

type PollStore interface {
	GetPollTimestamp(ctx context.Context, key PollKey) (time.Time, error)
	SetPollTimestamp(ctx context.Context, key PollKey, t time.Time) error
}

type PostProcessConfig struct {
	StripHI          bool `json:"strip_hi"`
	StripTags        bool `json:"strip_tags"`
	NormalizeUTF8    bool `json:"normalize_utf8"`
	CleanWhitespace  bool `json:"clean_whitespace"`
	NormalizeEndings bool `json:"normalize_endings"`
	RemoveEmpty      bool `json:"remove_empty"`
}

type Provider interface {
	// Name returns the provider identifier (e.g. "opensubtitles", "yifysubtitles").
	Name() ProviderID

	// Search finds subtitles matching the request.
	Search(ctx context.Context, req *SearchRequest) ([]Subtitle, error)

	// Download fetches the subtitle content for the given search result.
	Download(ctx context.Context, sub *Subtitle) ([]byte, error)
}

type ProviderCfg struct {
	Settings map[string]any
	Priority int // Lower = higher trust. 0 means unset (defaults to 99).
	Enabled  bool
}

type ProviderConfigProvider interface {
	ProviderConfigs() map[ProviderID]ProviderCfg
	ProviderPriority(name ProviderID) int
}

type ProviderID string

type ProviderRegistry interface {
	// LoadAll instantiates providers from the given config map, skipping
	// unconfigured entries. Returns an error if a configured provider fails.
	LoadAll(ctx context.Context, configs map[ProviderID]ProviderCfg) ([]Provider, error)
	// ProviderNames returns all registered provider names in priority order.
	ProviderNames() []ProviderID
	// Schema returns the UI label and settings fields for a named provider.
	Schema(name ProviderID) (label string, fields []ProviderSchemaField)
}

type ProviderSchema struct {
	Name          string        `json:"name"`
	Label         string        `json:"label"`
	Settings      []SchemaField `json:"settings,omitempty"`
	AlwaysEnabled bool          `json:"always_enabled,omitempty"`
}

type ProviderSchemaField struct {
	Key     string `json:"key"`
	Label   string `json:"label"`
	Type    string `json:"type"` // text, secret, bool
	Default string `json:"default,omitempty"`
	Help    string `json:"help,omitempty"`
	Secret  bool   `json:"secret,omitempty"`
}

type ProviderStatus struct {
	LastError         string        `json:"last_error,omitempty"`
	CooldownRemaining time.Duration `json:"cooldown_remaining,omitempty"`
	RecentFailures    int           `json:"recent_failures"`
	Threshold         int           `json:"threshold"`
	TimedOut          bool          `json:"timed_out"`
}

type ProviderTimeoutManager interface {
	ProviderTimeouts() (status map[ProviderID]ProviderStatus, enabled bool)
	ResetTimeouts()
}

type ProvidersResponse struct {
	Providers map[ProviderID]ProviderStatus `json:"providers"`
	Enabled   bool                          `json:"enabled"`
}

type QueryStore interface {
	GetState(ctx context.Context, q *StateQuery) ([]StateEntry, error)
	GetBackoffItems(ctx context.Context) ([]BackoffEntry, error)
	GetBackoffByPrefix(ctx context.Context, mediaType MediaType, mediaIDPrefix string) ([]BackoffEntry, error)
	GetManualLocks(ctx context.Context) ([]ManualLockEntry, error)
	Stats(ctx context.Context) (downloads, attempts int, err error)
}

type RadarrClient interface {
	Ping(ctx context.Context) error
	GetMovies(ctx context.Context) ([]arrapi.Movie, error)
	GetMovieByID(ctx context.Context, id int) (arrapi.Movie, error)
	GetHistorySince(ctx context.Context, since time.Time, eventTypes ...arrapi.EventType) ([]arrapi.HistoryRecord, error)
	GetWantedMovies(ctx context.Context, excludeTagIDs map[int]struct{}, fn func(arrapi.Movie) error) error
	ResolveExcludeTagIDs(ctx context.Context, tagNames []string, logMissing bool) map[int]struct{}
	RescanMovie(ctx context.Context, movieID int) error
}

type RateLimitError struct {
	Msg        string
	RetryAfter time.Duration
}

type ReconcileResult struct {
	// Deleted contains subtitle paths removed because the video is gone.
	Deleted CleanupResult

	// ResetCount is the number of entries reset for re-search because
	// the subtitle file was missing but the video still exists.
	ResetCount int64
}

type ScanOutcome string

type ScanRecord struct {
	MediaType MediaType
	MediaID   string
	Title     string
	AudioLang string
	Season    int
	Episode   int
}

type ScanStateRow struct {
	ScannedAt string `json:"scanned_at"`
	MediaID   string `json:"media_id"`
	Title     string `json:"title"`
	AudioLang string `json:"audio_lang"`
	Season    int    `json:"season,omitempty"`
	Episode   int    `json:"episode,omitempty"`
}

type ScanStats struct {
	// Pre-scan totals (from API).
	TotalSeries       int
	TotalEpisodeFiles int // Sum of episodeFileCount across all series.
	TotalMovies       int
	TotalMovieFiles   int // Movies with hasFile=true.

	// Post-scan outcomes for episodes. EpisodesSearched counts every episode
	// the scan loop processed (it drives progress reporting); the other
	// fields are its per-outcome buckets.
	EpisodesSearched  int // Episodes processed by the scan loop.
	EpisodesSkipped   int // Episodes with existing subs (no search needed).
	EpisodesFound     int // Episodes where a subtitle was downloaded.
	EpisodesNoResult  int // Episodes searched but no subtitle found.
	EpisodesBackedOff int // Episodes where every needed provider was in adaptive backoff (no query ran).
	SeriesSkipped     int // Series skipped by show-level pre-check.

	// Post-scan outcomes for movies.
	MoviesSearched  int
	MoviesSkipped   int
	MoviesFound     int
	MoviesNoResult  int
	MoviesBackedOff int
}

type SchemaField struct {
	Key         string         `json:"key"`
	Label       string         `json:"label"`
	Type        string         `json:"type"`
	Default     string         `json:"default,omitempty"`
	Help        string         `json:"help,omitempty"`
	Placeholder string         `json:"placeholder,omitempty"`
	Min         string         `json:"min,omitempty"`
	Max         string         `json:"max,omitempty"`
	ShowWhen    string         `json:"show_when,omitempty"`
	Requires    string         `json:"requires,omitempty"`
	Group       string         `json:"group,omitempty"`
	Fields      []SchemaField  `json:"fields,omitempty"`
	Options     []SchemaOption `json:"options,omitempty"`
	Secret      bool           `json:"secret,omitempty"`
	Required    bool           `json:"required,omitempty"`
}

type SchemaFunc func(providers []ProviderSchema) []SchemaSection

type SchemaOption struct {
	Value string `json:"value"`
	Label string `json:"label"`
}

type SchemaSection struct {
	Key              string           `json:"key"`
	Title            string           `json:"title"`
	Type             string           `json:"type"`
	Help             string           `json:"help,omitempty"`
	RequiredGroup    string           `json:"required_group,omitempty"`
	EnableKey        string           `json:"enable_key,omitempty"`
	Fields           []SchemaField    `json:"fields,omitempty"`
	ProviderTemplate []SchemaField    `json:"provider_template,omitempty"`
	Providers        []ProviderSchema `json:"providers,omitempty"`
}

type ScorePreview struct {
	Tier        ScoreTier `json:"tier"`
	Score       int       `json:"score"`
	ScoreNoHash int       `json:"score_no_hash"`
}

type ScoreResult struct {
	Tier        ScoreTier // Quality tier label (excellent/good/acceptable/minimal/none).
	Score       int       // Final score including hash match bonus.
	ScoreNoHash int       // Score from release attributes only, excluding hash match.
}

type ScoreSimulator interface {
	SimulateScore(mediaType MediaType, videoRelease, subRelease string, matchedBy MatchMethod) ScoreResult
	ScoreSubtitles(req *SearchRequest, results []Subtitle) []ScoredResult
}

type ScoreTier string

type ScoredResult struct {
	Matches map[string]int // Per-category score contributions.
	Sub     Subtitle
	Score   int
}

type Scorer interface {
	// Score computes a quality score for a subtitle match. Returns the full
	// score (including hash bonus) and the release-attribute-only score.
	Score(video *VideoInfo, sub SubtitleInfo, matches MatchSet) (score, scoreNoHash int)
	// ScoreToTier maps a numeric score to a human-readable tier label
	// (excellent/good/acceptable/minimal/none) based on media type thresholds.
	ScoreToTier(score int, mediaType MediaType) ScoreTier
}

type Scores struct {
	Hash             int `json:"hash" yaml:"hash"`
	Source           int `json:"source" yaml:"source"`
	ReleaseGroup     int `json:"release_group" yaml:"release_group"`
	StreamingService int `json:"streaming_service" yaml:"streaming_service"`
	VideoCodec       int `json:"video_codec" yaml:"video_codec"`
	HDR              int `json:"hdr" yaml:"hdr"`
	Edition          int `json:"edition" yaml:"edition"`         // movies only
	SeasonPack       int `json:"season_pack" yaml:"season_pack"` // episodes only
}

type ScoringConfig interface {
	Scores() Scores
}

type SearchConfig struct {
	ExcludeArrTags         []string
	ScanInterval           time.Duration
	ProviderTimeout        time.Duration
	ScanDelay              time.Duration
	MinScore               int
	UpgradeWindowDays      int
	DownloadMaxAttempts    int // Max download attempts per search (0 = default DefaultDownloadMaxAttempts)
	MaxProviderConcurrency int // Max parallel provider searches (0 = default DefaultProviderConcurrency)
	MaxSSEClients          int // Max concurrent SSE connections (0 = default 32)
	UpgradeEnabled         bool
}

type SearchConfigProvider interface {
	Search() SearchConfig
	Adaptive() AdaptiveConfig
	PostProcessConfig() PostProcessConfig
	SyncConfig() SyncConfig
}

type SearchEngine interface {
	SubtitleSearcher
	ScoreSimulator
	ProviderTimeoutManager
	SubtitlePostProcessor
}

type SearchRequest struct {
	MediaType         MediaType // "episode" or "movie"
	ImdbID            string    // IMDB ID; fallback for providers without TMDB/TVDB support
	Title             string
	AlternativeTitles []string // from Sonarr/Radarr alternateTitles
	EpisodeTitle      string   // Episode title from Sonarr (for identity validation across numbering schemes)
	ReleaseName       string
	VideoPath         string   // Absolute path to the video file (for embedded provider and sync)
	VideoHash         string   // OpenSubtitles hash
	AudioLang         string   // resolved audio language (for coverage tracking)
	Languages         []string // ISO 639-1 codes to search for
	TmdbID            int      // Movie TMDB ID from Radarr; 0 for episodes
	VideoSize         int64    // file size for hash-based search
	Year              int
	Season            int // 0 for movies
	Episode           int // 0 for movies
	TvdbID            int // Series TVDB ID from Sonarr; 0 for movies
	MaxResults        int // 0 = provider default (typically one page)

	// Alternate episode numbering from Sonarr (0 = not available).
	// Scene numbers come from TheXEM; absolute numbers from TVDB.
	SceneSeason     int
	SceneEpisode    int
	AbsoluteEpisode int

	// ForceUpgrade makes the search engine treat all external subtitles
	// as eligible for upgrade, regardless of the upgrade_enabled config.
	// Set by manual scan triggers (series/season search buttons).
	ForceUpgrade bool
}

type SearchResult struct {
	Paths           []string // Subtitle files downloaded.
	FoundLangs      []string // Language codes that had at least one subtitle downloaded.
	SearchedLangs   []string // Language codes whose group actually ran (not skipped); superset of FoundLangs.
	Searched        int      // Languages where providers were actually queried.
	Skipped         int      // Languages skipped (subs already exist, not eligible for upgrade).
	BackedOff       int      // Languages that needed a search but had every provider in adaptive backoff (no query ran).
	CoverageChanged bool     // True if RecordSubtitleFiles detected changes on disk.
}

type SearchTarget struct {
	MinScore  *int     `json:"min_score,omitempty"`
	Code      string   `json:"code"`
	Variant   string   `json:"variant"`
	Providers []string `json:"providers,omitempty"`
	Exclude   []string `json:"exclude,omitempty"`
}

type SearchTargets struct {
	OrigLang   string         `json:"orig_lang"`
	AudioLangs []string       `json:"audio_langs"`
	Targets    []SearchTarget `json:"targets"`
}

type ServerConfig interface {
	ServerPort() int
	PollInterval() time.Duration
	LoggingLevel() LogLevel
	LoggingFormat() LogFormat
}

type SetupStatus struct {
	SetupRequired bool `json:"setup_required"`
	ConfigValid   bool `json:"config_valid"`
}

type ShowSubtitleCounter interface {
	// CountShowSubtitles returns the total number of subtitles available for
	// a show in the given language. The request should have ImdbID set and
	// Season/Episode set to 0.
	CountShowSubtitles(ctx context.Context, imdbID, lang string) (int, error)
}

type SignalData struct {
	RPID          string   `json:"rp_id"`
	UserID        string   `json:"user_id"`
	Name          string   `json:"name"`
	DisplayName   string   `json:"display_name"`
	CredentialIDs []string `json:"credential_ids"`
}

type SonarrClient interface {
	Ping(ctx context.Context) error
	GetSeries(ctx context.Context) ([]arrapi.Series, error)
	GetEpisodes(ctx context.Context, seriesID int) ([]arrapi.Episode, error)
	GetSeriesByID(ctx context.Context, id int) (arrapi.Series, error)
	GetEpisodeByID(ctx context.Context, id int) (arrapi.Episode, error)
	GetHistorySince(ctx context.Context, since time.Time, eventTypes ...arrapi.EventType) ([]arrapi.HistoryRecord, error)
	GetWantedEpisodes(ctx context.Context, excludeTagIDs map[int]struct{}, fn func(arrapi.Series, arrapi.Episode) error) error
	ResolveExcludeTagIDs(ctx context.Context, tagNames []string, logMissing bool) map[int]struct{}
	RescanSeries(ctx context.Context, seriesID int) error
}

type StateEntry struct {
	MediaImported time.Time  `json:"media_imported"`
	Title         string     `json:"title"`
	MediaID       string     `json:"media_id"`
	Language      string     `json:"language"`
	Variant       Variant    `json:"variant"`
	Provider      ProviderID `json:"provider"`
	Path          string     `json:"path"`
	ReleaseName   string     `json:"release_name"`
	ImdbID        string     `json:"imdb_id,omitempty"`
	MediaType     MediaType  `json:"media_type"`
	ID            int64      `json:"id"`
	Score         int        `json:"score"`
	Season        int        `json:"season,omitempty"`
	Episode       int        `json:"episode,omitempty"`
	Manual        bool       `json:"manual"`
}

type StateQuery struct {
	MediaType MediaType
	Language  string
	Provider  ProviderID
	Search    string
	Limit     int
	Offset    int
}

type Stats struct {
	LastScan            string `json:"last_scan"`
	Downloads           int    `json:"downloads"`
	Attempts            int64  `json:"attempts"`
	ScanIntervalSeconds int    `json:"scan_interval_seconds"`
	TotalSubs           int    `json:"total_subs"`
	TotalSeries         int    `json:"total_series"`
	TotalMovies         int    `json:"total_movies"`
	MissingSubs         int    `json:"missing_subs"`
	Partial             bool   `json:"partial"`
}

type Store interface {
	BackoffStore
	DownloadStore
	ManualLockStore
	QueryStore
	HistoryStore
	CoverageStore
	SyncOffsetStore
	MaintStore
	PollStore
	Close(ctx context.Context) error
}

type Subtitle struct {
	Provider    ProviderID
	ID          string // provider-specific identifier
	Language    string // ISO 639-1 code
	ReleaseName string
	DownloadURL string
	MatchedBy   MatchMethod // how this subtitle was matched (hash, title, imdb, etc.)
	Title       string      // show/movie title from provider (for identity validation)
	Year        int         // year from provider (0 if unknown)
	Season      int         // season from provider (0 if unknown or movie)
	Episode     int         // episode from provider (0 if unknown or movie)
	HearingImp  bool
	Forced      bool
}

type SubtitleCue struct {
	Text  string
	Start time.Duration
	End   time.Duration
}

type SubtitleEntry struct {
	MediaID   string `json:"media_id"`
	Language  string `json:"language"`
	Variant   string `json:"variant"`
	Source    string `json:"source"`
	Codec     string `json:"codec,omitempty"`
	Path      string `json:"path,omitempty"`
	VideoPath string `json:"video_path,omitempty"`
	Score     int    `json:"score,omitempty"`
	OffsetMs  int64  `json:"offset_ms,omitempty"`
}

type SubtitleFile struct {
	Language string         // ISO 639-1
	Variant  Variant        // "standard", "hi", "forced"
	Source   SubtitleSource // SourceEmbedded or SourceExternal
	Codec    string         // e.g. "subrip", "ass"; empty for external
	Path     string         // file path for external; empty for embedded
}

type SubtitleInfo struct {
	HashVerifiable bool
}

type SubtitlePostProcessor interface {
	SyncAndPostProcess(ctx context.Context, data []byte, videoPath, lang string, variant Variant) (synced []byte, offsetMs int64)
	HashFile(ctx context.Context, path string) (hash string, size int64, err error)
}

type SubtitleProcessor interface {
	// NormalizeEncoding converts subtitle data to UTF-8 from detected encoding.
	NormalizeEncoding(data []byte) []byte
	// ParseSRT parses SRT subtitle data into individual cues.
	ParseSRT(data []byte) ([]SubtitleCue, error)
	// WriteSRT serializes cues back to SRT format.
	WriteSRT(cues []SubtitleCue) ([]byte, error)
	// ShiftCues applies a timing offset to all cues.
	ShiftCues(cues []SubtitleCue, offset time.Duration) []SubtitleCue
	// SyncFromAudio runs audio-based sync on subtitle data against the video.
	SyncFromAudio(ctx context.Context, data []byte, videoPath, subtitlePath string) AudioSyncResult
}

type SubtitleSearcher interface {
	SearchTargets(ctx context.Context, req *SearchRequest, videoPath string, targets []SubtitleTarget) (SearchResult, error)
}

type SubtitleSource string

type SubtitleTargJSON struct {
	MinScore  *int     `json:"min_score,omitempty"`
	Code      string   `json:"code"`
	Variant   string   `json:"variant,omitempty"`
	Variants  []string `json:"variants,omitempty"`
	Providers []string `json:"providers,omitempty"`
	Exclude   []string `json:"exclude,omitempty"`
}

type SubtitleTarget struct {
	MinScore  *int
	Code      string
	Variant   Variant
	Variants  []string
	Providers []ProviderID
	Exclude   []ProviderID
}

type SyncConfig struct {
	// SyncSubtitles enables automatic timing sync against embedded
	// reference subtitles when a new subtitle is downloaded.
	SyncSubtitles bool `json:"sync_subtitles"`
	// AudioSyncFallback enables audio-based sync as a fallback when
	// no embedded reference subtitle is available or sync fails.
	AudioSyncFallback bool `json:"audio_sync_fallback"`
	// SyncMinConfidence is the minimum confidence threshold (0.0–1.0) for
	// accepting an automatic sync result. Defaults to DefaultSyncMinConfidence when zero.
	SyncMinConfidence float64 `json:"sync_min_confidence,omitempty"`
}

type SyncOffsetStore interface {
	SetSyncOffset(ctx context.Context, path string, offsetMs int64) error
	GetSyncOffset(ctx context.Context, path string) (int64, error)
}

type Transient interface {
	IsTransient() bool
}

type UIConfigProvider interface {
	LanguageRulesForUI() LanguageRulesJSON
}

type Variant string

type VideoInfo struct {
	ReleaseGroup string    // Full release name for parsing.
	MediaType    MediaType // "episode" or "movie"
}

type WebAuthnUnknownCredentialResponse struct {
	Error  string `json:"error"`
	Signal string `json:"signal"`
}