Subtitles

Written for highsea 0.1.0.

highsea finds subtitles for every film it imports, scores them, and syncs them to the film's speech in the background. The Subtitles page shows how that's going, lists what's still missing, and holds the settings behind it. A film's own subtitles are on its page, under Subtitles.

Owners and Admins can use everything here, except adding a provider's account, which is for the Owner only.

The page at a glanceCopy Anchor Link

Across the top, four figures:

• synced today: subtitles lined up with the speech since midnight UTC.
• waiting to sync: subtitles queued or being synced now.
• average correction: how far today's syncs moved the timing, in milliseconds.
• average confidence: how sure today's syncs were.

Below them are four tabs: Wanted, Providers, Languages and Scoring and sync.

Providers and accountsCopy Anchor Link

highsea searches three providers together and ranks what they find by score:

• OpenSubtitles.com, which signs in with a username and password.
• Subdl, which uses an API key.
• SubSource, which uses an API key.

Each needs an account of your own, made on the provider's site. highsea signs in with it, and it stays on your server.

Add an accountCopy Anchor Link

Owner only.

1. Open Subtitles, then the Providers tab.
2. Choose Edit on the provider's row.
3. Fill in the username and password, or the API key.
4. Choose Test. highsea signs in without saving and says what happened.
5. Choose Save.
6. Turn on the provider's Enabled switch.

A provider without an account can't be switched on; its row says "Add your account first." Once a password or key is saved, its field stays empty in Edit and says "Saved. Leave it empty to keep it."

Requests left todayCopy Anchor Link

Providers limit how much each account can do in a day. The Requests left today column shows what's left, as a bar and a count, or a dash when the provider doesn't say. A free Subdl key allows 2,000 requests a day and a free SubSource key 7,200, according to their documentation.

When a provider has to wait, its bar empties and a line says why and when it's back:

• Too many requests. Resumes …: highsea asked too often. It waits and carries on by itself.
• Out of downloads for today. Resumes …: the account has used its downloads for the day.
• Refused the account. Check it in Edit.: the password or key is wrong, or the account has changed. Fix it in Edit.
• Didn't answer. Tries again …: the provider is down or unreachable for now.

Searches skip a waiting provider until it's back.

Languages and profilesCopy Anchor Link

A language profile says which subtitles a film should have. highsea starts with one called English. Every film has a profile, chosen under Subtitle languages:

• when you add a film;
• in a film's Edit dialog;
• for several films at once, from the Subtitle languages menu in the library's selection bar;
• as a default for every film added to a root folder, in Media management.

Make or change a profileCopy Anchor Link

1. Open Subtitles, then the Languages tab.
2. Choose New profile, or Edit on an existing one. The card turns into a form.
3. Give it a Name.
4. Under Languages, in order of preference, choose Add a language for each one you want. Drag a language by its handle to reorder it, or press Space on the handle, move it with the Up and Down arrows, and press Space again to drop it.
5. For each language, choose which kinds to fetch:
   • Regular only, Regular and forced or Forced only. Forced subtitles cover only the lines in another language, such as a sign or a short scene. Regular and forced fetches both, as two tracks.
   • Without SDH, With or without SDH or SDH only. SDH subtitles also describe sounds and name the speaker, for viewers who are deaf or hard of hearing. With Without SDH, highsea takes an SDH subtitle only when nothing else exists, and removes the descriptions from it.
6. Set the Cutoff: once this language is found, highsea stops looking for better matches. Keep looking never stops.
7. Set a Minimum score from 0 to 100. A match on the file itself scores about 99.
8. Choose Save profile.

Delete removes a profile. highsea refuses while films still use it, and always keeps at least one.

The wanted listCopy Anchor Link

The Wanted tab lists the films that are missing a language their profile asks for, with the missing languages beside each. Subtitles inside the video file count, so a film with built-in English isn't missing English. Films show 50 at a time; Show more loads the next.

• Search on a row searches every provider for that film's missing languages and downloads the best match.
• Search all does the same for every film on the list. What's found downloads and syncs in the background.

When nothing is missing, the tab says "Every movie has its subtitles".

Automatic downloadsCopy Anchor Link

You don't need to search by hand. highsea:

• searches for a film's subtitles as soon as it's imported;
• searches the wanted list again every 6 hours;
• keeps looking for a better match for the number of days in Keep upgrading for, checking every 12 hours, and replaces a subtitle when it finds a better one.

A subtitle that came with the release, beside the video or in a Subs folder, is kept and scores 100, since it was made for that release. Subtitles inside the video file are used as they are.

Before saving a downloaded subtitle, highsea removes advertising lines, such as "Subtitles by …" or a site's address.

Both searches are listed under System › Tasks as Search for wanted subtitles and Upgrade subtitles, with Run now to start one early. See System.

A film's subtitlesCopy Anchor Link

On a film's page, the Subtitles tab lists its tracks, with how many are external (files beside the video) and how many are embedded (inside it). Each track shows:

• Language, and Source: the provider, From the release, Added by hand or Embedded.
• Score: how well it matched.
• Sync: one of Waiting to sync, Syncing, Synced, Not synced, Sync failed or Matches the video, with the sync's confidence beside it.
• Offset: how far the timing has been moved.

Matches the video means the track needs no sync: it's embedded, or it came with the release.

Search and choose a subtitle yourselfCopy Anchor Link

1. On the film's Subtitles tab, under Search for subtitles, pick the Language.
2. Choose Search providers. Results are listed best first, with the release they were made for, the provider and the score.
3. Choose Use on the one you want. It downloads and syncs in the background, and highsea keeps it rather than replacing it with an upgrade.

If no provider is switched on, the search says "Turn on a subtitle provider in Subtitles to search."

Delete a subtitleCopy Anchor Link

Choose Delete on the track. The file beside the video is removed too.

Syncing to the film's speechCopy Anchor Link

A subtitle made for another release of the same film is often early or late by a second or more. highsea listens for speech in the film and lines the subtitle up with it, in the background, after each download.

Each sync reports how sure it is, as a percentage:

• At or above Minimum confidence, the new timing is used and the track reads Synced, with the correction in milliseconds and the confidence.
• Below it, highsea keeps the subtitle's original timing and the track reads Not synced, with its confidence, so you can check it yourself.

Syncing needs FFmpeg. If it's missing, every sync fails at once and System › Health warns: "ffmpeg isn't installed, so subtitles can't be synced to the audio." The official image includes it. Subtitles that are pictures rather than text can't be synced.

Sync againCopy Anchor Link

Choose Sync to the audio again on a track. It goes back to Waiting to sync, any offset you set is cleared, and the result arrives in a moment.

Adjust the offset by handCopy Anchor Link

If a track is still a little early or late, use − and + beside its offset. Each press moves it by 50 ms: − shows the subtitles earlier, + later. The file is rewritten at once, so the change shows the next time the film is played.

Scoring and sync settingsCopy Anchor Link

The Scoring and sync tab holds the settings for every film. Change them, then choose Save, or Discard changes to go back.

Sidecar filesCopy Anchor Link

highsea saves each subtitle as a file beside the video, named after it, so players such as Plex, Jellyfin and Kodi find it. The name carries the language and, when there is one, a flag:

Sintel (2010) Bluray-1080p.mkv
Sintel (2010) Bluray-1080p.en.srt
Sintel (2010) Bluray-1080p.en.forced.srt
Sintel (2010) Bluray-1080p.en.sdh.srt

A second track with the same language and flag adds the provider's name, such as ….en.OpenSubtitles.srt. When highsea renames a film, its subtitles are renamed with it.

When something goes wrongCopy Anchor Link

System › Health lists subtitle problems under the source Subtitles:

• … refused the password. Sign in again in Subtitles. or … refused the key. Check it in Subtitles.: open Edit on the provider and enter the account again.
• … has no downloads left today.: a notice. The provider is skipped until its downloads come back, at the time shown.
• ffmpeg isn't installed: see System.