search

package
v0.9.0-dev.31 Latest Latest
Warning

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

Go to latest
Published: Oct 18, 2026 License: AGPL-3.0 Imports: 34 Imported by: 0

Documentation

Overview

Package search implements the subtitle search engine.

orchestrate.go: search pipeline orchestration (lang-group search, variant processing) orchestrate_filter.go: eligibility checks, variant/score filtering, provider filtering provider_sweep.go: provider sweep, singleflight dedup, download target_state.go: target state building, decision logic, backoff

Index

Constants

This section is empty.

Variables

View Source
var (

	// ErrProviderGated reports a call the provider gate refused, so no request
	// was made. The wrapping error carries the gate's reason.
	ErrProviderGated = errors.New("provider gated")
)

Functions

func IgnoredCodecsFromConfig

func IgnoredCodecsFromConfig(cfg interface{ EmbeddedPolicy() subflux.EmbeddedPolicy }) map[string]bool

IgnoredCodecsFromConfig builds the set of embedded codecs that should be treated as "present but not usable" from the typed embedded_subtitles policy. This is the ONE resolver every consumer (engine + server handlers) goes through.

The parameter is an anonymous one-method interface because that is the only value this resolver reads; every caller's config surface already carries EmbeddedPolicy, so each satisfies this structurally.

Types

type Cfg added in v0.4.0

type Cfg interface {
	// Scores must return non-zero values; zero scores disable all attribute matching.
	Scores() subflux.Scores
	// Search returns the top-level search configuration (concurrency, etc.).
	Search() subflux.SearchConfig
	// Adaptive returns the adaptive search configuration.
	Adaptive() subflux.AdaptiveConfig
	// Sync returns subtitle sync/timing configuration.
	Sync() subflux.SyncConfig
	// PostProcess returns post-processing settings.
	PostProcess() subflux.PostProcessConfig
	// ProvidersForTarget returns provider names allowed for this target.
	// An empty slice means no providers will be searched for this target.
	ProvidersForTarget(t *subflux.SubtitleTarget, allProviders []subflux.ProviderID) []subflux.ProviderID
	// MinScoreForTarget returns 0 to accept any score.
	MinScoreForTarget(t *subflux.SubtitleTarget, mediaType subflux.MediaType) int
	// ProviderPriority returns 0 for unknown providers (lowest priority = tried last in tiebreakers).
	ProviderPriority(name subflux.ProviderID) int
	// EmbeddedPolicy returns the typed embedded subtitle codec policy
	// (top-level embedded_subtitles config section).
	EmbeddedPolicy() subflux.EmbeddedPolicy
}

Cfg is what the scan engine reads out of the configuration: the scoring weights and floors it ranks candidates by, the provider allow-list and priority order it queries in, the concurrency and retry limits it paces itself with, and the sync/post-process settings it applies to a download. 9 of the 37 values the configuration offers.

type Engine

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

Engine coordinates subtitle searches.

func New

func New(providers []provider.Provider, opts ...Option) *Engine

New creates a search engine. The providers slice is required; all other dependencies are supplied via functional options.

func (*Engine) CountShowSubtitles added in v0.6.6

func (e *Engine) CountShowSubtitles(ctx context.Context, q subflux.ShowSubtitleQuery) (int, error)

CountShowSubtitles asks the engine's show-level counter, through the provider gate as a search. A refusal is ErrProviderGated with the gate's reason and makes no request; with no counter it is errProviderNotFound.

func (*Engine) Download added in v0.6.6

func (e *Engine) Download(ctx context.Context, sub *subflux.Subtitle) ([]byte, error)

Download fetches sub from its provider through the provider gate; a refusal is ErrProviderGated and makes no request.

func (*Engine) HasShowCounter added in v0.6.6

func (e *Engine) HasShowCounter() bool

HasShowCounter reports whether one of the engine's providers offers the show-level subtitle count.

func (*Engine) HashFile

func (e *Engine) HashFile(ctx context.Context, path string) (hash string, size int64, err error)

HashFile deduplicates concurrent calls for the same path via singleflight.

func (*Engine) InventoryCoverage added in v0.1.148

func (e *Engine) InventoryCoverage(ctx context.Context, req *subflux.SearchRequest, videoPath string) bool

InventoryCoverage is the local-only half of the scan: it refreshes the on-disk/embedded subtitle inventory for a media item and stamps its scan state as inventoried-not-searched, with zero provider work. Scan skip paths (season early stop, show-level skip) call this so coverage badges stay truthful for items the scanner deliberately does not search: "skip" means skip PROVIDER work, not local bookkeeping.

func (*Engine) ProviderStatus added in v0.6.6

func (e *Engine) ProviderStatus() (status map[subflux.ProviderID]subflux.ProviderStatus, timeoutsEnabled bool)

ProviderStatus reports every provider the health tracker or the provider gate has something to say about. timeoutsEnabled is false when the configuration disables provider timeouts; the gate's state is reported either way.

func (*Engine) ResetProviderState added in v0.6.6

func (e *Engine) ResetProviderState(ctx context.Context)

ResetProviderState clears every provider timeout, credential disable, rate-limit pause and rejected setting.

func (*Engine) ScoreSubtitles

func (e *Engine) ScoreSubtitles(req *subflux.SearchRequest, results []subflux.Subtitle) []subflux.ScoredResult

ScoreSubtitles filters results by identity and returns them scored against req.

func (*Engine) SearchTargets

func (e *Engine) SearchTargets(ctx context.Context, req *subflux.SearchRequest,
	videoPath string, targets []subflux.SubtitleTarget,
) (subflux.SearchResult, error)

SearchTargets always searches for regular (non-HI, non-forced) subs, with HI as fallback. Its error is the context's, or the first *mediawrite.UnwritableError a save produced (also in WriteFailure), which is the caller's signal to stop.

func (*Engine) SetProviderHealthHook added in v0.5.0

func (e *Engine) SetProviderHealthHook(fn providerhealth.OnChange)

SetProviderHealthHook installs the observer for provider timeout raise and clear transitions (a no-op when timeouts are disabled). The server installs the SSE publisher here after each activation — the tracker is rebuilt with the engine on a config reload, so the hook is re-installed with it.

func (*Engine) SimulateScore

func (e *Engine) SimulateScore(mediaType subflux.MediaType, videoRelease, subRelease string, matchedBy subflux.MatchMethod) subflux.ScoreResult

SimulateScore returns the score a subtitle release would get against a video release.

func (*Engine) SweepProviders added in v0.6.6

func (e *Engine) SweepProviders(ctx context.Context, req *subflux.SearchRequest,
	perProviderTimeout time.Duration,
) ([]subflux.Subtitle, []SweepNotice)

SweepProviders queries every provider for req, each under its own timeout, with the provider gate applied and the health tracker and adaptive backoff bypassed. Results come back in provider order.

func (*Engine) SyncAndPostProcess

func (e *Engine) SyncAndPostProcess(ctx context.Context, data []byte,
	videoPath, lang string, variant subflux.Variant,
) (synced []byte, offsetMs int64)

SyncAndPostProcess syncs subtitle timing and normalizes content using the user's configured sync settings. It is the single entry point used by manual downloads and any caller that wants the full "match the auto path" behavior:

  1. If sync_subtitles is enabled, try reference-based sync (embedded SRT track extracted from the video container).
  2. If that produces no offset and audio_sync_fallback is enabled, try audio-based sync (PCM extraction + VAD correlation).
  3. Apply the configured post-processing (HI strip, tag strip, encoding normalization, line-ending normalization, whitespace cleanup).

The variant argument selects the same StripHI policy as the auto path's postProcessSub: when the caller is saving an HI-variant file the global strip_hi setting is overridden to false, because the user deliberately asked for HI annotations. For any other variant (standard/forced) the configured strip_hi value is honored. Callers that need just the timing step without post-processing should use syncSubtitle directly.

type MediaWriter added in v0.6.6

type MediaWriter interface {
	// WriteFile returns an error matching mediawrite.ErrUnwritable when the
	// subtitle's folder refuses writes; any other error is about the target.
	WriteFile(ctx context.Context, path string, data []byte) error
	// Blocked reports the unwritable folder at or above path's folder.
	Blocked(path string) (folder string, blocked bool)
}

MediaWriter writes subtitles into the media tree and knows which folders refuse writes; *mediawrite.Writer is the implementation.

type Metrics added in v0.4.0

type Metrics interface {
	RecordSearch(provider subflux.ProviderID, dur time.Duration, err error)
	RecordDownload(provider subflux.ProviderID, err error)
	AdaptiveSkip()
	// RecordEmbeddedDetectorError counts a failed embedded track probe
	// (subflux_embedded_detector_errors_total). Context cancellation is
	// excluded by the caller.
	RecordEmbeddedDetectorError()
	// RecordSubtitleSaved counts a subtitle file written next to the media.
	RecordSubtitleSaved(provider subflux.ProviderID)
}

Metrics is the narrow observability interface consumed by the search engine; the concrete *obs.Metrics satisfies it via structural typing.

type Option

type Option func(*Engine)

Option configures the search Engine.

func WithConfig

func WithConfig(c Cfg) Option

WithConfig sets the engine's configuration source.

func WithMediaWriter added in v0.6.6

func WithMediaWriter(w MediaWriter) Option

WithMediaWriter sets the writer every subtitle save goes through. Required.

func WithMetrics

func WithMetrics(m Metrics) Option

WithMetrics sets the engine's metrics sink.

func WithProviderGate added in v0.6.6

func WithProviderGate(b *providergate.Binding) Option

WithProviderGate sets the provider gate binding every provider call goes through. Required.

func WithScorer

func WithScorer(s Scorer) Option

WithScorer sets the engine's release scorer.

func WithStore

func WithStore(s Store) Option

WithStore sets the engine's persistence backend.

func WithSyncExec added in v0.1.148

func WithSyncExec(x syncing.SyncExec) Option

WithSyncExec sets the executor for the engine's own heavy sync calls (the audio fallback). Defaults to in-process; server mode installs the sync-worker client so alignment memory lives in a disposable child.

func WithSyncer

func WithSyncer(s SubtitleSyncer) Option

WithSyncer sets the engine's subtitle syncer.

func WithTimeout

func WithTimeout(h providerHealth) Option

WithTimeout sets the provider health tracker. When not set, the engine constructs one from config (or uses noopHealth if disabled).

func WithTracks

func WithTracks(t TrackDetector) Option

WithTracks sets the engine's embedded-track detector.

type Scorer added in v0.4.0

type Scorer interface {
	// Score computes a quality score for a subtitle match set. Returns the
	// full score (including the hash bonus) and the release-attribute-only
	// score. A verifiable hash match short-circuits to the hash weight alone.
	Score(sub subflux.SubtitleInfo, matches subflux.MatchSet) (score, scoreNoHash int)
	// ScoreToTier maps a numeric score to a human-readable tier label via one
	// global threshold table: excellent >= 80, good >= 50, acceptable >= 20,
	// minimal >= 1, else none. Thresholds do not vary by media type.
	ScoreToTier(score int) subflux.ScoreTier
}

Scorer turns a subtitle's release-attribute match set into a quality score. Both methods, because the engine uses both: it scores every candidate and labels the winner's tier. Declared here because this is the package that does the scoring work; the manual path takes only the labelling half at its own site.

type Store added in v0.4.0

type Store interface {
	// Search flow: backoff tracking, download recording, score queries, and
	// manual locks.
	RecordNoResult(ctx context.Context, mediaType subflux.MediaType, mediaID, language string, providerName subflux.ProviderID, bp subflux.BackoffParams) error
	BackedOffProviders(ctx context.Context, mediaType subflux.MediaType, mediaID, language string, maxAttempts int) ([]subflux.ProviderID, error)
	SaveDownload(ctx context.Context, rec *subflux.DownloadRecord) error
	CurrentScore(ctx context.Context, mediaType subflux.MediaType, mediaID, language string, variant subflux.Variant) (score int, mediaImported time.Time, found bool, err error)
	IsManuallyLocked(ctx context.Context, key subflux.ManualLockKey) (bool, error)

	// Coverage: subtitle-file recording, sync offsets, and scan state.
	RecordSubtitleFiles(ctx context.Context, mediaType subflux.MediaType, mediaID string, files []subflux.SubtitleFile) (bool, error)
	UpsertSubtitleFile(ctx context.Context, mediaType subflux.MediaType, mediaID string, f *subflux.SubtitleFile) error
	SetSyncOffset(ctx context.Context, path string, offsetMs int64) error
	RecordScanState(ctx context.Context, rec *subflux.ScanRecord) error
}

Store is the store surface the search engine consumes, and the whole of it: the engine calls all nine of these and nothing else.

It was three interfaces — FlowStore and CoverageRecorder embedded into this composite — and the two halves were deleted because nothing depended on them. Repo-wide, neither name appeared as a parameter, a field, or a type assertion; both existed only to be embedded here, while their doc comments claimed consumers ("Consumed by orchestrate.go and search_download.go", "Consumed by SearchTargets and downloadAndSave") that took this composite instead. A grouping worth stating is worth stating as a comment; an interface nothing names is mechanism with no consumer, and one whose doc names consumers it does not have is worse than none.

The concrete boltstore.DB satisfies this structurally; that package declares no interface of its own by design.

type SubtitleSyncer

type SubtitleSyncer interface {
	// Sync adjusts subtitle timing against a reference (embedded, external, or audio).
	// Returns the (possibly modified) data and the applied offset in milliseconds
	// (0 if no sync was applied or confidence was too low).
	Sync(ctx context.Context, data []byte, videoPath, lang string) (synced []byte, offsetMs int64)

	// PostProcess applies encoding normalization, HI removal, tag stripping, etc.
	PostProcess(data []byte, pp subflux.PostProcessConfig) []byte
}

SubtitleSyncer synchronizes subtitle timing and applies post-processing.

type SweepNotice added in v0.6.6

type SweepNotice struct {
	Err      error
	Provider subflux.ProviderID
	Reason   string
	Gated    bool
}

SweepNotice reports a provider that contributed no results to a sweep: either the gate refused it (Gated, with the gate's Reason) or its search failed (Err).

type TrackDetector

type TrackDetector interface {
	// DetectTracks returns ALL normalized embedded subtitle tracks in the
	// given video file (including bitmap formats), or an error when the
	// probe fails (ffprobe error, corrupt file, timeout). The engine owns
	// the error policy: log/metric observability, fail-open search, and
	// skipping the coverage replacement so a failed probe never deletes
	// persisted rows. (nil, nil) means "no tracks", distinct from an error.
	DetectTracks(ctx context.Context, videoPath string) ([]subflux.EmbeddedTrack, error)
}

TrackDetector detects embedded subtitle tracks in video containers. Implemented by internal/embedded's ffprobe-backed Detector.

Directories

Path Synopsis
Package providergate decides whether a subtitle provider may be called for one operation right now.
Package providergate decides whether a subtitle provider may be called for one operation right now.
Package providerhealth tracks how a provider is behaving and takes a failing one out of rotation: it counts failures in a sliding window and, past a threshold, times the provider out for a cooldown.
Package providerhealth tracks how a provider is behaving and takes a failing one out of rotation: it counts failures in a sliding window and, past a threshold, times the provider out for a cooldown.
Package release provides release name parsing via PCRE-compatible regex patterns sourced from TRaSH Guides and Sonarr/Radarr QualityParser.
Package release provides release name parsing via PCRE-compatible regex patterns sourced from TRaSH Guides and Sonarr/Radarr QualityParser.
Package scoring holds the pure matching and weighting rules the scan engine applies to a candidate: which subtitles identify as the requested item, which weight categories a release hits, and the title and episode comparisons under both.
Package scoring holds the pure matching and weighting rules the scan engine applies to a candidate: which subtitles identify as the requested item, which weight categories a release hits, and the title and episode comparisons under both.
Package syncing provides subtitle timing synchronization for the search engine.
Package syncing provides subtitle timing synchronization for the search engine.

Jump to

Keyboard shortcuts

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