subflux

command module
v0.1.51 Latest Latest
Warning

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

 Go to latest Published: Jun 16, 2026 License: GPL-2.0, GPL-3.0 Imports: 50 Imported by: 0

README

subflux

Image Size Platforms Go Report Card Test coverage Mutation OpenSSF Best Practices OpenSSF Scorecard SBOM

A fast, low-memory subtitle search and download engine for Sonarr/Radarr libraries — a Go-based Bazarr replacement.

What it does

Subflux finds, scores, downloads, and time-syncs subtitles for your Plex/Sonarr/Radarr library. It watches the *arr import history in real time and runs scheduled full-library scans, querying multiple providers concurrently, ranking results by release quality, and syncing subtitle timing to the video before saving.

It was born from diagnosing Bazarr's 15–20 GB memory consumption on a 52k-episode library (CPython arena fragmentation during long Sonarr sync loops). Subflux processes items in a batch-fetch-then-iterate model with bounded goroutine pools and no Python runtime — a single static binary in a distroless image.

Features

  • Providers — OpenSubtitles, Gestdown, embedded (ffprobe), SubSource, SubDL, BetaSeries, AnimeTosho, YIFY Subtitles, HDBits — behind one interface, each registered declaratively.
  • Two-phase scoring — an identity gate (IMDB/TVDB/TMDB + season/episode + title validation) followed by a 0–100 release-quality score for ranking and upgrades.
  • Audio-language-based language rules — map detected audio to subtitle targets, with standard/forced/hi variants and per-target provider/min-score overrides.
  • Subtitle sync — a Go port of the alass algorithm plus cross-language anchor alignment, framerate correction, split-aware DP, and GMM audio VAD, with confidence-scored voting.
  • Adaptive backoff — per-provider exponential backoff for no-result media, season-level early termination, and per-provider timeout to avoid hammering failing APIs.
  • Manual override — numbered manual downloads lock an item from automation; locks clear automatically when files are deleted or the video is replaced.
  • Web UI — a zero-dependency, zero-build vanilla-ESM SPA: library coverage table, manual search, sync dialog with video preview, history, schema-driven settings, and live SSE updates.
  • Multi-user auth — local password + WebAuthn/passkeys + OIDC + TOTP, API keys, and rate limiting.
  • Prometheus metrics at /metrics, structured slog logging, and a distroless file-marker healthcheck.

Run it

# compose.yaml
services:
  subflux:
    image: ghcr.io/cplieger/subflux:latest
    ports:
      - "8374:8374"
    volumes:
      - ./config:/config        # config.yaml + SQLite state
      - /media:/media           # must NOT be read-only — subflux writes .srt files
    restart: unless-stopped

Open http://localhost:8374; the settings dialog auto-opens on first run (unconfigured mode) until a valid config is saved. Point it at your Sonarr/Radarr instances and configure providers + language rules.

The media volume must not be mounted :ro — subflux writes subtitle files alongside the media.

Configuration

All settings are editable in the web UI (schema-driven form) and persist to config.yaml. The CLI also supports manual search and remote commands against a running instance (subflux search, subflux scan, subflux status, subflux locks, …) via the SUBFLUX_URL env var.

Security

Distroless gcr.io/distroless/static:nonroot (UID 65534, no shell). Provider URLs are validated against SSRF before every fetch; secrets are redacted from config API responses; archive extraction is zip-bomb-guarded; all external input is size-capped and validated. Images are published with cosign signatures and SBOM attestations.

License

GPL-3.0. See LICENSE.

Documentation

Overview

providers.go is the single registration point for all subtitle providers. Each provider's factory function and settings schema are registered here; adding a new provider requires one Register + one RegisterSchema call. No init(), no blank imports, no global state.

Source Files

View all Source files

Directories

Path Synopsis
cmd
wire-codegen command
Command wire-codegen generates TypeScript interfaces and validating decoders from Go wire types using the wiregen library (AST-based; github.com/cplieger/wiregen).
 Command wire-codegen generates TypeScript interfaces and validating decoders from Go wire types using the wiregen library (AST-based; github.com/cplieger/wiregen).
internal
api
Package api defines the internal contracts between subflux components.
 Package api defines the internal contracts between subflux components.
arrapi
Package arrapi provides Sonarr and Radarr API clients.
 Package arrapi provides Sonarr and Radarr API clients.
authstore
Package authstore re-exports the composite store interface from the standalone github.com/cplieger/auth library so subflux call sites can continue to refer to authstore.AuthStore without depending on the library's import path directly.
 Package authstore re-exports the composite store interface from the standalone github.com/cplieger/auth library so subflux call sites can continue to refer to authstore.AuthStore without depending on the library's import path directly.
cache
Package cache provides a generic TTL cache with singleflight coalescing.
 Package cache provides a generic TTL cache with singleflight coalescing.
cliparse
Package cliparse adds help generation, unknown-flag detection (with typo suggestions), and required/type validation on top of subflux's existing flag-parsing helpers.
 Package cliparse adds help generation, unknown-flag detection (with typo suggestions), and required/type validation on top of subflux's existing flag-parsing helpers.
clisearch
Package clisearch implements CLI subtitle search, resolution, and download.
 Package clisearch implements CLI subtitle search, resolution, and download.
config
config/defaults
Package defaults provides shared configuration constants and helpers used by both config/ and config/schema/.
 Package defaults provides shared configuration constants and helpers used by both config/ and config/schema/.
config/schema
Package schema generates the UI configuration schema for the web frontend.
 Package schema generates the UI configuration schema for the web frontend.
fsutil
Package fsutil provides filesystem utility functions.
 Package fsutil provides filesystem utility functions.
httputil
Package httputil provides shared HTTP utilities for subtitle providers.
 Package httputil provides shared HTTP utilities for subtitle providers.
metrics
Package metrics provides Prometheus-compatible metrics for Subflux.
 Package metrics provides Prometheus-compatible metrics for Subflux.
provider
Package provider contains the provider registry and retry wrappers.
 Package provider contains the provider registry and retry wrappers.
provider/anidb
Package anidb provides TVDB → AniDB mapping using the community-maintained anime-list.xml from https://github.com/Anime-Lists/anime-lists.
 Package anidb provides TVDB → AniDB mapping using the community-maintained anime-list.xml from https://github.com/Anime-Lists/anime-lists.
provider/animetosho
Package animetosho implements the AnimeTosho subtitle provider.
 Package animetosho implements the AnimeTosho subtitle provider.
provider/archive
Package archive provides subtitle extraction from ZIP and RAR archives.
 Package archive provides subtitle extraction from ZIP and RAR archives.
provider/betaseries
Package betaseries implements the BetaSeries subtitle provider.
 Package betaseries implements the BetaSeries subtitle provider.
provider/classify
Package classify provides subtitle classification (forced/HI) and language resolution utilities consumed by provider sub-packages.
 Package classify provides subtitle classification (forced/HI) and language resolution utilities consumed by provider sub-packages.
provider/dlcache
Package dlcache provides a generic LRU download-data cache with heap-based eviction.
 Package dlcache provides a generic LRU download-data cache with heap-based eviction.
provider/embedded
Package embedded detects embedded subtitles in video files.
 Package embedded detects embedded subtitles in video files.
provider/gestdown
Package gestdown implements the Gestdown subtitle provider.
 Package gestdown implements the Gestdown subtitle provider.
provider/hdbits
Package hdbits implements the HDBits.org subtitle provider.
 Package hdbits implements the HDBits.org subtitle provider.
provider/mock
Package mock provides a configurable mock subtitle provider for functional testing.
 Package mock provides a configurable mock subtitle provider for functional testing.
provider/opensubtitles
Package opensubtitles implements the OpenSubtitles.com REST API provider.
 Package opensubtitles implements the OpenSubtitles.com REST API provider.
provider/subdl
Package subdl implements the SubDL subtitle provider.
 Package subdl implements the SubDL subtitle provider.
provider/subsource
Package subsource implements the SubSource subtitle provider.
 Package subsource implements the SubSource subtitle provider.
provider/yifysubtitles
Package yifysubtitles implements the YIFY Subtitles provider.
 Package yifysubtitles implements the YIFY Subtitles provider.
scorer
Package scorer implements subtitle scoring based on release matching.
 Package scorer implements subtitle scoring based on release matching.
search
Package search implements the subtitle search engine.
 Package search implements the subtitle search engine.
search/release
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.
search/scoring
Package scoring provides pure subtitle scoring and identity filtering.
 Package scoring provides pure subtitle scoring and identity filtering.
search/syncing
Package syncing provides subtitle timing synchronization for the search engine.
 Package syncing provides subtitle timing synchronization for the search engine.
search/timeout
Package timeout provides provider health tracking with sliding-window failure detection and cooldown-based timeout.
 Package timeout provides provider health tracking with sliding-window failure detection and cooldown-based timeout.
server
Package server provides the HTTP server and history poller for subtitle management.
 Package server provides the HTTP server and history poller for subtitle management.
server/activity
Package activity provides concurrent-safe activity and alert tracking for the subflux UI status indicator.
 Package activity provides concurrent-safe activity and alert tracking for the subflux UI status indicator.
server/authhandlers
Package authhandlers provides shared types and utilities for the server's authentication handler cluster: login, TOTP, WebAuthn, OIDC, admin user management, and security management (password change, API keys, passkeys).
 Package authhandlers provides shared types and utilities for the server's authentication handler cluster: login, TOTP, WebAuthn, OIDC, admin user management, and security management (password change, API keys, passkeys).
server/confighandlers
Package confighandlers provides HTTP handlers for configuration CRUD operations: get, save, reset, schema, and path validation.
 Package confighandlers provides HTTP handlers for configuration CRUD operations: get, save, reset, schema, and path validation.
server/coverage
Package coverage provides pure computation functions for subtitle coverage analysis.
 Package coverage provides pure computation functions for subtitle coverage analysis.
server/coveragehandlers
Package coveragehandlers provides HTTP handlers for the /api/coverage/* endpoints.
 Package coveragehandlers provides HTTP handlers for the /api/coverage/* endpoints.
server/events
Package events provides an in-memory pub/sub event bus for server-sent events.
 Package events provides an in-memory pub/sub event bus for server-sent events.
server/filehandlers
Package filehandlers provides HTTP handlers for the /api/files/* endpoints.
 Package filehandlers provides HTTP handlers for the /api/files/* endpoints.
server/httphelpers
Package httphelpers provides shared HTTP handler prelude helpers used across server sub-packages.
 Package httphelpers provides shared HTTP handler prelude helpers used across server sub-packages.
server/manualops
Package manualops implements the business logic for manual subtitle search and download operations.
 Package manualops implements the business logic for manual subtitle search and download operations.
server/mediahandlers
Package mediahandlers provides HTTP handlers for the /api/media/* endpoints.
 Package mediahandlers provides HTTP handlers for the /api/media/* endpoints.
server/polling
Package polling provides the history-polling subsystem for Sonarr/Radarr import events and the write-through poll timestamp cache.
 Package polling provides the history-polling subsystem for Sonarr/Radarr import events and the write-through poll timestamp cache.
server/previewhandlers
Package previewhandlers provides HTTP handlers for the video/subtitle preview and poster proxy endpoints.
 Package previewhandlers provides HTTP handlers for the video/subtitle preview and poster proxy endpoints.
server/queryhandlers
server/scanning
Package scanning implements the full-scan orchestration engine.
 Package scanning implements the full-scan orchestration engine.
server/scheduler
Package scheduler provides the periodic full-scan pipeline, DB maintenance, and auth cleanup scheduling for the subflux server.
 Package scheduler provides the periodic full-scan pipeline, DB maintenance, and auth cleanup scheduling for the subflux server.
server/serveradapter
Package serveradapter provides adapter types that bridge the server's activity, alert, and event subsystems to the interfaces consumed by the scanning and manualops packages.
 Package serveradapter provides adapter types that bridge the server's activity, alert, and event subsystems to the interfaces consumed by the scanning and manualops packages.
server/sessionbatch
Package sessionbatch implements batched session activity updates to reduce SQLite write-lock acquisitions.
 Package sessionbatch implements batched session activity updates to reduce SQLite write-lock acquisitions.
server/showskip
Package showskip provides a TTL-based cache for show-level subtitle pre-check results.
 Package showskip provides a TTL-based cache for show-level subtitle pre-check results.
server/synchandlers
Package synchandlers provides HTTP handlers for subtitle sync operations (audio-based sync and manual offset adjustment).
 Package synchandlers provides HTTP handlers for subtitle sync operations (audio-based sync and manual offset adjustment).
store
Package store provides SQLite-backed state for adaptive search and subtitle state.
 Package store provides SQLite-backed state for adaptive search and subtitle state.
store/authdb
Package authdb provides SQLite-backed persistence for authentication data (users, sessions, passkeys, API keys, TOTP, OIDC state).
 Package authdb provides SQLite-backed persistence for authentication data (users, sessions, passkeys, API keys, TOTP, OIDC state).
store/coveragedb
Package coveragedb provides SQLite-backed persistence for subtitle file coverage tracking and scan state.
 Package coveragedb provides SQLite-backed persistence for subtitle file coverage tracking and scan state.
store/migrations
Package migrations defines the schema DDL and migration steps for the subflux SQLite database.
 Package migrations defines the schema DDL and migration steps for the subflux SQLite database.
store/reconcile
Package reconcile extracts the subtitle_state reconciliation subsystem.
 Package reconcile extracts the subtitle_state reconciliation subsystem.
store/storetest
Package storetest provides shared contract test suites for api.Store implementations.
 Package storetest provides shared contract test suites for api.Store implementations.
store/txutil
Package txutil provides shared transaction helpers for store sub-packages.
 Package txutil provides shared transaction helpers for store sub-packages.
subsync
Package subsync provides subtitle timing synchronization.
 Package subsync provides subtitle timing synchronization.
subsync/crosslang
Package crosslang implements cross-language subtitle alignment using anchor-based matching and dynamic programming.
 Package crosslang implements cross-language subtitle alignment using anchor-based matching and dynamic programming.
subsync/ffmpeg
Package ffmpeg provides low-level ffmpeg/ffprobe subprocess wrappers for stream probing, subtitle extraction, and PCM audio extraction.
 Package ffmpeg provides low-level ffmpeg/ffprobe subprocess wrappers for stream probing, subtitle extraction, and PCM audio extraction.
subsync/fft
Package fft provides a radix-2 Cooley-Tukey FFT implementation for cross-correlation in the subsync package.
 Package fft provides a radix-2 Cooley-Tukey FFT implementation for cross-correlation in the subsync package.
subsync/framerate
Package framerate provides framerate drift detection for subtitle alignment.
 Package framerate provides framerate drift detection for subtitle alignment.
subsync/vad
testsupport
Package testsupport provides shared test helpers used across multiple packages.
 Package testsupport provides shared test helpers used across multiple packages.
wiring
Package wiring holds composition-root types that connect concrete implementations across the api, metrics, search, and provider packages.
 Package wiring holds composition-root types that connect concrete implementations across the api, metrics, search, and provider packages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.