search

package
v0.6.2 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2026 License: AGPL-3.0 Imports: 31 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 (
	// ErrProviderNotFound indicates the provider name doesn't match any registered provider.
	ErrProviderNotFound = errors.New("provider not found")
	// ErrInvalidContent indicates the provider returned bytes that are not a
	// subtitle. It wraps subtitlefile.Validate's reason, so a caller that needs
	// to tell an empty download from a corrupt one tests for
	// subtitlefile.ErrEmpty rather than a second sentinel here.
	ErrInvalidContent = errors.New("provider returned invalid data")
)

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) 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) ProviderTimeouts

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

ProviderTimeouts returns (nil, false) when timeouts are disabled.

func (*Engine) ResetTimeouts

func (e *Engine) ResetTimeouts()

ResetTimeouts clears all provider timeout state.

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.

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) 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 FileWriter

type FileWriter interface {
	WriteFile(ctx context.Context, path string, data []byte) error
}

FileWriter abstracts atomic file writes, decoupling the search engine from the concrete atomicfile implementation. The default wraps atomicfile.WriteFile; tests can inject a stub that records writes without touching disk.

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

Metrics is the narrow observability interface consumed by the search engine. Only the 4 methods actually called are required; the concrete *obs.Metrics satisfies this via structural typing.

type NoopDetector added in v0.1.148

type NoopDetector struct{}

NoopDetector is an explicit no-detection TrackDetector for callers that have no use for embedded track inspection (search.New requires a detector, so "none" must be said out loud rather than left nil).

func (NoopDetector) DetectTracks added in v0.1.148

func (NoopDetector) DetectTracks(_ context.Context, _ string) ([]subflux.EmbeddedTrack, error)

DetectTracks always returns no tracks and no error.

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 WithMetrics

func WithMetrics(m Metrics) Option

WithMetrics sets the engine's metrics sink.

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