Why your Jellyfin subtitles drift, and how release matching plus a sync check fixes it

If you run Jellyfin for a Romanian household — your own here, or family in Germany, Spain, France or Italy watching the same library over the internet — you have probably lived this: the subtitle loads, then slowly slides out of step, and by minute twenty the dialogue is a full scene behind. Nine times out of ten the file is fine and the subtitle is fine; they were simply made for different releases.

This tutorial is about fixing the cause, not the symptom. Rosub is a Jellyfin plugin that searches subs.ro for Romanian subtitles and picks the file made for your release, then verifies the timing against the subtitle already embedded in your video before saving anything.

Why subtitles drift

A subtitle is timed to a specific cut of a film or episode. Change the release group, the source (WEB-DL, BluRay, HDTV), the service it came from or the frame rate, and the cue timings no longer line up. Sometimes the drift is a constant offset — the whole file is two seconds early — and sometimes it grows through the runtime, which means the two versions have different cuts and no simple shift will save them.

A subtitle search that only matches on title and year will happily hand you a file made for a different release. That is the drift you see. The fix is to match on the release name and to verify the timing before the subtitle is saved.

Prerequisites

• Jellyfin Server 12.2 or newer, on Linux, Windows or Docker.
• A free subs.ro API key, from subs.ro under My account → API.
• Optional: a free OpenSubtitles.com API key, used only as a fallback.
• The server's ffprobe, which Rosub uses for the sync check.
• A MediaLab Works account with a license that covers the plugin (subscription, lifetime license within its update window, the Jellyfin bundle, or the free 30-day trial).

Step 1 — Get your own API keys

Nothing is bundled: you use your own keys. Create the subs.ro key first and keep it somewhere safe; you will paste it into Jellyfin in step 3. If you also want the OpenSubtitles fallback, create an API key there too.

Both services have daily request limits. subs.ro allows 300 requests a day per key, and Rosub stays under the budget you configure, keeping a reserve for newly added items. The defaults are 250 requests a day for subs.ro and 5 for OpenSubtitles, which is plenty for a normal household library.

Step 2 — Install the plugin

The recommended route is your private plugin repository, so Jellyfin installs and updates Rosub by itself:

1. In your MediaLab Works account open Licenses → Jellyfin plugin repository and click Create address. Copy the address — it is private, so do not share it.
2. In Jellyfin go to Dashboard → Plugins → Repositories, click +, name it (for example MediaLab Works), paste the address and save.
3. In Dashboard → Plugins → Catalog find Rosub by MediaLab, click Install, then restart Jellyfin.

There is also a public catalog at https://medialab.works/jellyfin/manifest.json, and a manual zip install if you prefer; the guide walks through both, including the plugin folder paths for Linux, Docker and Windows.

Step 3 — Activate the license and enter your keys

1. Open Dashboard → Plugins → Rosub by MediaLab and click Open License page. Paste your license key and click Activate with key. No key yet? The same page starts the 30-day free trial.
2. Open Dashboard → Rosub and enter your subs.ro API key, then save. Without it the plugin does nothing.
3. Choose the libraries to work in (empty means all movie and series libraries) and the match mode: strict (the default), relaxed or any.
4. Optionally add the OpenSubtitles.com fallback with your own API key, plus the daily request budget and the reserve for new items.

Your keys and the OpenSubtitles account password are stored encrypted at rest in secrets.enc.json in the plugin data folder and are never sent to the browser — the page only shows "set ✓".

Step 4 — How release matching picks the right file

This is the heart of it. Rosub splits your file name into title, year, season/episode, resolution, source (WEB-DL, BluRay, HDTV), service, codec and release group, and compares that with each subtitle it finds on subs.ro. In strict mode it accepts only subtitles made for the same release, group or streaming source. That is what stops the drift before it starts: a WEB-DL file gets the WEB-DL subtitle, not the BluRay one.

If you have a mixed library with unusual naming, relaxed or any mode gives you more candidates — but strict is the right default, and it is the one that keeps a diaspora family watching the same library from three countries out of trouble.

Step 5 — The sync check with ffprobe

When your video has an embedded subtitle track, Rosub compares the candidate's timing against it using the server's ffprobe. A constant offset — the whole file a couple of seconds early or late — is corrected automatically. A subtitle that is out of sync in a way a constant shift cannot fix is rejected, and the journal on the plugin page tells you why.

Be realistic about the limit: the sync check fixes constant offsets. It cannot repair a subtitle made for a different cut of the film, where the drift grows through the runtime. In that case you want a different candidate, which is exactly what release matching is for.

Step 6 — New items and the backlog

• On arrival: a few minutes after Jellyfin identifies a new movie or episode, Rosub searches subs.ro by IMDb/TMDb id and saves the subtitle next to the video as Name.ro.srt.
• Daily: the scheduled task Missing Romanian subtitles runs at 04:00 and retries everything without a Romanian subtitle, newest first. Items not found yet are retried after a few days, because subtitles often appear days after a release. You can also run the task by hand from Dashboard → Scheduled Tasks.

Step 7 — Manual search and correct diacritics

Sometimes you want to intervene. In an item's Edit subtitles → Search, Rosub results appear next to the other providers. Subtitles are saved as ordinary external .srt files in UTF-8 with correct Romanian diacritics — ș and ț with the comma below, not the old cedilla forms.

Tips and troubleshooting

• Nothing is downloaded. Check the API key and whether the daily budget is used up. subs.ro answers 429 at the limit; the counter resets every day.
• Quota reached. Lower the daily budget or let the reserve do its job for new items; the backlog task will pick up the rest tomorrow.
• The subtitle is not shown. Jellyfin recognizes ro and rum as Romanian. If the item was open in a client while the subtitle was downloaded, refresh its metadata.
• Subtitles not showing on a TV. Rosub writes plain external .srt files, which show in any client that displays external subtitles. Individual native apps are not tested, so if a TV app misbehaves, try Jellyfin Web on the same network to confirm the file is there.
• Read the journal. The plugin page lists what was downloaded, rejected and why — the fastest way to understand a stubborn item.
• Privacy. For subs.ro, Rosub sends only the IMDb or TMDb id and the language — no titles, file names, release names or hashes. Release matching and sync checking happen locally with ffprobe.

Conclusion

Drift is a matching problem, not a subtitle problem. Install Rosub, enter your own free subs.ro key, keep strict matching, and let the ffprobe sync check reject anything that would slide out of step. New items are handled within minutes, the 04:00 task fills in the backlog, and your library gets Romanian subtitles with proper ș and ț. Start on the product page, follow the guide, and check the changelog when an update lands. Questions? The knowledge base, the FAQ and contact are there.