cplieger/subflux repository overview

⁠subflux

subflux finds, downloads and times subtitles for the shows and movies in your Sonarr and Radarr library, and saves them next to each video. It works only through Sonarr and Radarr and does not scan folders on its own.

⁠⚠️ Alpha software

subflux is under active development and has not reached version 1.0. Any update can change the config format, the saved state, the API or the behavior. Pin a specific image tag instead of latest, and read the release notes before you upgrade.

⁠What it does

subflux gets subtitles in your languages onto your whole library:

• Checks Sonarr and Radarr every 30 seconds and fetches subtitles for each new download.
• Scans the library once a day to fill gaps and upgrade recent subtitles.
• Fixes each download's timing to match a subtitle track in the video, or optionally its audio.
• Shows coverage on a web page, where you can search, pick and re-time subtitles by hand.

⁠Who it is for

subflux is built for people who run Sonarr, Radarr or both on a Docker host and want subtitles without picking them by hand. It picks languages from each file's audio track and can fetch forced and hearing-impaired versions. A 52,000-episode library runs in 1 GB of memory.

You need a Sonarr or Radarr instance with its API key, and your media mounted writable at the paths they use. subflux searches eight sites. Gestdown, AnimeTosho and YIFY Subtitles need no account. OpenSubtitles, SubDL, SubSource, BetaSeries and HDBits need an account or an API key.

Consider Bazarr⁠ if you want a native install on Windows, macOS or a Raspberry Pi, or a site such as Titlovi or Napiprojekt. It supports 184 subtitle languages and Whisper speech-to-text.

subflux is free software under the AGPL-3.0-or-later license.

⁠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
    # Run "sudo install -d -o 1000 -g 1000 /opt/appdata/subflux" before the first start,
    # or the container restarts in a loop. If .env sets PUID and PGID, use those numbers.
    user: "${PUID:-1000}:${PGID:-1000}"

    ports:
      - "8374:8374"

    volumes:
      - "/opt/appdata/subflux:/config"  # settings and saved state
      # Put the path Sonarr and Radarr show for your media on the right, writable by the user above.
      - "/path/to/media:/media"

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Configuration⁠
• Database maintenance⁠
• Security⁠
• How subflux works⁠
• Monitoring and alerts⁠
• 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⁠.