cplieger/subflux repository overview

⁠subflux

A fast, small subtitle search, download, and sync engine for Sonarr and Radarr. A Go-based Bazarr alternative that ships as a ~14 MB container.

⁠⚠️ Alpha software

Subflux is pre-1.0 and under active development. It is functional and runs a 52,000-episode library in production today, but rough edges remain. Any update can introduce a breaking change. The config format, the on-disk state, the API, and behavior can all change between releases. Pin a specific image tag instead of latest, and check the release notes before upgrading.

⁠What it does

Subflux finds, scores, downloads, and time-syncs subtitles for your Sonarr/Radarr library. It watches the *arr import history (default 30 s poll) so new downloads get subtitles within moments of importing, and runs scheduled full-library scans (default 24 h) to fill gaps and upgrade what's already there. Every result passes an identity check and a release-quality score; the best one is downloaded, synced against the video's own timing, cleaned up, and saved next to the media file. A web UI shows per-show coverage at a glance and lets you search, pick, and visually sync subtitles by hand when you want control.

⁠Pull

docker pull cplieger/subflux:latest

Also published to ghcr.io/cplieger/subflux with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for subflux. See the README for all configuration options and hardening.
services:
  subflux:
    image: ghcr.io/cplieger/subflux:latest
    container_name: subflux
    restart: unless-stopped
    # Override with PUID/PGID in .env; defaults to 1000:1000.
    user: "${PUID:-1000}:${PGID:-1000}"  # match your host user

    ports:
      - "8374:8374"

    volumes:
      - "/opt/appdata/subflux:/config"
      - "/path/to/media:/media"

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Operability Runbooks⁠
• Contributing⁠
• Releases and changelog⁠

⁠License

AGPL-3.0-or-later. See LICENSE⁠. The image carries the license text of every bundled component under /usr/share/licenses/.

The image bundles two upstream programs built from source, both GPL-2.0-or-later: FFmpeg⁠ (the FFMPEG_VERSION pin in the Dockerfile, fetched as the n<version> tag archive of https://github.com/FFmpeg/FFmpeg⁠) and x264⁠ (the X264_COMMIT pin, cloned from https://code.videolan.org/videolan/x264.git⁠). The build applies no patches; this repository's Dockerfile, together with those two pinned sources, is the complete build recipe, which is how the GPL source offer for the shipped binaries is met.

Two upstream projects are ported into internal/subsync rather than bundled: the alignment algorithms of alass⁠ (GPL-3.0-or-later, which section 13 of the GPLv3 lets an AGPL-3.0 program contain) and the voice activity detector of WebRTC⁠ (BSD-3-Clause). Both license texts, with the files that carry the ported code, are in THIRD_PARTY_NOTICES.md⁠.