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 ¶
- Variables
- func IgnoredCodecsFromConfig(cfg interface{ ... }) map[string]bool
- type Cfg
- type Engine
- func (e *Engine) HashFile(ctx context.Context, path string) (hash string, size int64, err error)
- func (e *Engine) InventoryCoverage(ctx context.Context, req *subflux.SearchRequest, videoPath string) bool
- func (e *Engine) ProviderTimeouts() (map[subflux.ProviderID]subflux.ProviderStatus, bool)
- func (e *Engine) ResetTimeouts()
- func (e *Engine) ScoreSubtitles(req *subflux.SearchRequest, results []subflux.Subtitle) []subflux.ScoredResult
- func (e *Engine) SearchTargets(ctx context.Context, req *subflux.SearchRequest, videoPath string, ...) (subflux.SearchResult, error)
- func (e *Engine) SimulateScore(mediaType subflux.MediaType, videoRelease, subRelease string, ...) subflux.ScoreResult
- func (e *Engine) SyncAndPostProcess(ctx context.Context, data []byte, videoPath, lang string, ...) (synced []byte, offsetMs int64)
- type FileWriter
- type Metrics
- type NoopDetector
- type Option
- type Scorer
- type Store
- type SubtitleSyncer
- type TrackDetector
Constants ¶
This section is empty.
Variables ¶
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 whole of what this resolver reads: 1 of the 37 values the configuration offers. Every caller's own config surface already carries EmbeddedPolicy, so each satisfies this structurally without naming anything.
Types ¶
type Cfg ¶ added in v0.4.0
type Cfg interface {
// Scores returns the scoring weights. 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.
// Empty slice means no providers will be searched for this target.
ProvidersForTarget(t *subflux.SubtitleTarget, allProviders []subflux.ProviderID) []subflux.ProviderID
// MinScoreForTarget returns the minimum acceptable score for a target.
// Returns 0 to accept any score.
MinScoreForTarget(t *subflux.SubtitleTarget, mediaType subflux.MediaType) int
// ProviderPriority returns the priority of a provider by name.
// 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 — the widest consumer surface in the app, and still short of the whole by the auth, logging, server-runtime, media-path and UI halves a search never reads.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine coordinates subtitle searches.
func New ¶
New creates a search engine. The providers slice is required; all other dependencies are supplied via functional options.
func (*Engine) HashFile ¶
HashFile computes the OpenSubtitles hash and file size for a video file. Concurrent calls for the same path are deduplicated 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 a snapshot of all provider timeout states. Returns (status, true) if timeouts are enabled, (nil, false) otherwise.
func (*Engine) ResetTimeouts ¶
func (e *Engine) ResetTimeouts()
ResetTimeouts clears all provider timeout state and re-enables all providers.
func (*Engine) ScoreSubtitles ¶
func (e *Engine) ScoreSubtitles(req *subflux.SearchRequest, results []subflux.Subtitle) []subflux.ScoredResult
ScoreSubtitles scores and ranks subtitles for a search request.
func (*Engine) SearchTargets ¶
func (e *Engine) SearchTargets(ctx context.Context, req *subflux.SearchRequest, videoPath string, targets []subflux.SubtitleTarget, ) (subflux.SearchResult, error)
SearchTargets searches for subtitles using resolved SubtitleTargets. Always searches for regular (non-HI, non-forced) subs, with HI as fallback. Respects per-target provider filtering and min scores.
func (*Engine) SimulateScore ¶
func (e *Engine) SimulateScore(mediaType subflux.MediaType, videoRelease, subRelease string, matchedBy subflux.MatchMethod) subflux.ScoreResult
SimulateScore simulates scoring a subtitle against a video using release names.
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:
- If sync_subtitles is enabled, try reference-based sync (embedded SRT track extracted from the video container).
- If that produces no offset and audio_sync_fallback is enabled, try audio-based sync (PCM extraction + VAD correlation).
- 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 ¶
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 reports no embedded tracks.
type Option ¶
type Option func(*Engine)
Option configures the search Engine.
func WithSyncExec ¶ added in v0.1.148
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 (P13).
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).
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.
Source Files
¶
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. |