Subsyncarr

Subsyncarr expects video files and their corresponding subtitle files to have matching names. It follows standard naming conventions compatible with Plex, Jellyfin, Emby, and Bazarr. The tool is non-destructive; it creates new files with engine-specific suffixes (e.g., .ffsubsync.srt) rather than altering originals.

/movies
├── Movie Title (2024).mkv
├── Movie Title (2024).srt          # Will be synchronized
├── Movie Title (2024).ffsubsync.srt # Generated output
└── Another Movie.mp4
    └── Another Movie.srt

/tv
├── Show Name/
│   ├── Season 01/
│   │   ├── Show.S01E01.mkv
│   │   └── Show.S01E01.srt

You can run Subsyncarr as a standalone container using the docker run command. Ensure you map the necessary volumes for media and data persistence, and set the required environment variables.

docker run -d \
  --name subsyncarr \
  -p 3000:3000 \
  -v /path/to/movies:/movies \
  -v /path/to/tv:/tv \
  -v ./data:/app/data \
  -e TZ=Etc/UTC \
  -e PUID=1000 \
  -e PGID=10 \
  -e CRON_SCHEDULE="0 0 * * *" \
  -e SCAN_PATHS=/movies,/tv \
  -e MAX_CONCURRENT_SYNC_TASKS=1 \
  mrorbitman/subsyncarr:latest

You can pull the latest official image from Docker Hub using the following command.

docker pull mrorbitman/subsyncarr:latest

Manage how long processing history and logs are kept using these environment variables:

Subsyncarr provides a WebSocket endpoint at /ws for real-time dashboard updates. Upon connection, the server immediately sends the current state.

Supported Message Types:

• state: Initial payload containing currentRun, files, and isRunning.
• run:started: Broadcast when a new run begins.
• run:completed: Broadcast when a run finishes successfully.
• run:cancelled: Broadcast when a run is stopped.
• file:updated: Broadcast when a specific file's status changes (includes { file, run }).

The client uses a WebSocket connection to listen for specific message types that update the UI and internal state without requiring manual refreshes.

Supported WebSocket message types:

• state: Replaces the entire application state.
• run:started: Sets isRunning to true and updates currentRun.
• run:completed: Sets isRunning to false, updates currentRun, and triggers a history refresh.
• run:cancelled: Sets isRunning to false, updates currentRun, and triggers a history refresh.
• file:updated: Updates a specific file's data in the current file list.
• files:cleared: Resets the current file list and currentRun state.

The SYNC_ENGINE_TIMEOUT_MS environment variable controls how long each sync engine can run before being terminated. This prevents hung processes from blocking the queue. You can also use SYNC_TIMEOUT to set a timeout in seconds.

environment:
  - SYNC_ENGINE_TIMEOUT_MS=3600000 # 60 minutes for large files

Subsyncarr can be deployed using Docker Compose. To ensure functionality, you must mount any directories specified in the SCAN_PATHS environment variable as volumes. If SCAN_PATHS is not provided, the application defaults to scanning /scan_dir. To persist the database across restarts, mount a local directory to /app/data.

services:
  subsyncarr:
    image: mrorbitman/subsyncarr:latest
    container_name: subsyncarr
    ports:
      - '3000:3000'
    volumes:
      - /path/to/movies:/movies
      - ./data:/app/data
    environment:
      - SCAN_PATHS=/movies

If your media files are not being picked up for synchronization, verify the following:

• Naming Convention: Ensure subtitle files match the video filenames (e.g., movie.mkv and movie.srt).
• Path Configuration: Verify that SCAN_PATHS correctly matches your mounted volumes.
• Sync Status: Check if the files have already been processed (look for .ffsubsync.srt files).
• Auto-skip Status: Check the Web UI to see if files are being automatically skipped due to repeated previous failures.