Hello everyone!

I've had issues with downloaded subtitles being out of sync. I am sure I am not the only one. For years I used a script that ran ffsubsync on the out-of-sync subtitle files, one by one. I don't know why, but that issue has been happening more often. This approach now takes too much time.

I know that there are out-of-the-box solutions such as Bazarr, which I was using some time ago. At the time the sync mechanism of Bazaar wasn't reliable, it may have changed since, but I would rather limit the number of services on my machine to a minimum. Also, I only need the sync feature, as Subbuz does the job of downloading very well for me. I haven't found a lightweight solution that does that.

So I wrote (using AI for specific parts) a plugin that allows the usage of ffsubsync, which I is fast and efficient, over everything, on a schedule: Marnalas/jellyfin-subsync

What it does

• Adds a "Sync unsynced subtitles" scheduled task.
• The sweep walks your configured library paths, finds subtitle files, matches each to its video, and hands it to ffsubsync.
• Already-synced files are tracked by content hash, so repeat sweeps skip them and are nearly cost-free. First run can take hours on a big library; every run after that only touches what's new.
• No GPU needed as ffsubsync's default webrtc VAD is CPU-only.

How it's put together (the one caveat worth reading before you install)

It's two pieces: the plugin itself, and a small always-on HTTP service that wraps ffsubsync and ffmpeg, running as its own docker container next to Jellyfin.

That's deliberate. ffsubsync is a python package and I wasn't sure how to install it and its dependencies, then run it cleanly inside the jellyfin container. Handing the plugin a Docker socket is out of the question.

Practically: you copy three files into your existing stack, add one service block to your jellyfin docker compose file, and mount your libraries into it. I have documented the full walkthrough in the README.

it works well for me. It has already resynced my whole library in two hours. but I understand that people not running docker may find it hard or impossible to use this plugin.

Credit where it's due

The plugin is glue. All the actual work is done by ffsubsync by Stephen Macke, and FFmpeg.

This is a first release and it's been running against my own library, not a hundred different setups. I think it's worth this announce as I haven't found an equivalent, lightweight, solution to this issue that I assume is impacting other Jellyfin users.

Bug reports, edge cases, and "this made no sense to me in the README" feedback are all very welcome on the issue tracker.

See the README.md file for updated installation instructions