Settings — Format & Naming

When Sublarr writes a subtitle next to a video, the filename follows a strict pattern. This page is where you tune that pattern so the output integrates cleanly with your media server, archival workflow, or whatever else reads the files.

The naming pattern

Sublarr builds filenames like:

<base>.<separator><language><suffix-block>.<extension>

Example: for Frieren.S01E01.1080p.BluRay.x264.mkv with German + HI subtitle:

Frieren.S01E01.1080p.BluRay.x264.de.hi.srt
       └─ base ─┘  └sep┘└lang┘└─suffix─┘

The fields

Setting	Default	Values	Effect
Language code format	2-letter	2-letter / 3-letter / region	de / deu / de-DE. Use region if your media server requires regional codes.
Suffix separator	.	. / - / _	Character between filename parts. Match your media server’s convention.
HI suffix	.hi	freeform	Appended for hearing-impaired subtitles. Some servers use .cc.
Forced suffix	.forced	freeform	Appended for forced subtitles.
Default extension	.srt	.srt / .ass / .vtt / .sup	Fallback when the source format is uncertain.

Format conversion

By default, Sublarr writes whatever format the provider returned. You can convert at write-time:

Setting	Effect
Convert to	none (write as-is) / srt / ass / vtt.
Strip styling on convert	Drop ASS styling when converting to SRT. Keep on for compatibility, off for archival.
Preserve karaoke	When converting ASS to ASS, preserve \k overrides (no-op for SRT/VTT targets).

Caution

Converting ASS to SRT loses styling — colours, font, positioning. Run a test conversion on a sample file before bulk-applying; the result is irreversible without restoring the original.

Embedded extraction

Setting	Default	Values	Effect
Maximum ASS/SSA subtitle size (MiB)	20	1–50	The largest ASS/SSA file the sanitizer accepts; larger files are rejected. SRT/VTT stay capped at 5 MiB.

Text encoding

Every subtitle Sublarr saves is written as UTF-8, whatever it came in. Providers and manual uploads still deliver plenty of files in older encodings (Windows-1250/1251/1252/1253, Greek, Cyrillic, Turkish, Hebrew, Chinese GBK/Big5, …), so the encoding is worked out before anything reads the text, strongest evidence first:

1. a byte-order mark, or UTF-16 recognised by its byte pattern — UTF-16 subtitles are accepted;
2. valid UTF-8;
3. the encoding the provider detected itself;
4. the encodings the subtitle’s language was written in before UTF-8;
5. a statistical guess, limited to encodings subtitles are really saved in.

The language check, the editor, the subtitle tools, the health check and the re-encode fix all use the same detection, so they also open files that are not UTF-8. Files an older version already saved with ”�” in place of letters are restored by the Subtitle Repair.

Subtitles inside a ZIP or RAR are found whatever their file name is written in, including names without Latin letters (简体.srt).

Examples per media server

Server	Recommended setup
Plex	2-letter, . separator, default suffixes.
Jellyfin	Same as Plex. Some Jellyfin versions also accept 3-letter.
Emby	Same as Plex.
Kodi	3-letter works better with some addons.
VLC manual playback	Any pattern. VLC matches <base>.<lang>.srt by default.

Language code references

2-letter	3-letter	Region	Language
de	deu	de-DE	German
en	eng	en-US	English
ja	jpn	ja-JP	Japanese
es	spa	es-ES	Spanish
pt	por	pt-PT	Portuguese
pt-BR	por-BR	pt-BR	Brazilian Portuguese

These are the most-asked-about ones. The language picker offers all 183 ISO 639-1 languages, with English and German names, and the three-letter tags of these languages (bel, wel, tib, …) are recognised on embedded tracks too.

Edge cases

File without language tag

If your existing library has subtitles named Frieren.S01E01.srt (no language suffix), Sublarr won’t recognise them as managed files. Re-rename via:

Action	Effect
Library → Sidecar pill → Rename	Adds the language code based on detected content.
Bulk → Re-tag	Same, applied to selection.

Multiple subtitles same language

When a video has two subtitle files for the same language (e.g. one HI, one regular), the suffix block disambiguates:

Frieren.S01E01.de.srt        ← regular
Frieren.S01E01.de.hi.srt     ← hearing impaired
Frieren.S01E01.de.forced.srt ← forced (foreign-language scenes)

The matching profile HI / Forced bias decides which one is preferred when both are valid candidates.

Provider-supplied filename

Some providers return subtitles with their own naming convention (e.g. [Erai-raws] Frieren - 01 [1080p].ass). Sublarr always rewrites these to your configured pattern at write-time — the provider name is preserved in the database but never makes it to disk.