Settings reference¶

Everything below lives at Dashboard → Plugins → WhisperSubs, except the handful marked config file only. The sections follow the order of the settings page, so you can read down this page and down the screen at the same time.

Defaults are the values a fresh install starts with.

Connect an akou server¶

The first section of the page. It sets up an akou server worker, the default way to transcribe, and stores nothing of its own: Save writes the URL and key into the first akou row under Workers, or adds that row, and saves the page.

Setting	Default	What it does
akou URL	empty	The akou server's base URL, for example `http://akou:8476`. No `/v1`.
Key	empty	An `ak_` key with the `jobs` scope, from `akou keys create --name whisper-subs --scope jobs`. Sent only from this server.
Test		Checks the server and the key and says what is wrong: not akou, a refused host name, no file jobs, `best` not pulled, a refused key or a key without `jobs`.

Without the local Whisper engine, an akou install makes English translations only when the akou server offers its translate task (Test then says "translates into English"), and otherwise skips them. It runs Full and Forced as Full, and makes nothing in Forced Only or Translation Only. A title tagged with a language Qwen3-ASR does not cover goes to a worker in the pool that is not an akou or Qwen3-ASR row, and is skipped when there is none. Each of these is a warning in the log, not a failure. An untagged title is always named as one of the 30 languages, since akou can only answer with those, so a title spoken in another language gets a subtitle in the nearest of them, usually a translation: tag its audio track.

The Whisper Engine section sits under Transcribe on this server instead (optional), folded while an akou row exists. It opens by itself when this server already has Whisper installed or Qwen3-ASR selected and no akou row is set. Vocal Separation, Canary engine, VAD tuning and Advanced / Manual Install stay outside it, where they were.

Transcription engine (experimental)¶

The Whisper Engine section ends with a Transcription engine panel. It decides which model transcribes whole titles on this server. Workers in the pool keep their own engine.

Setting	Default	What it does
Engine	Whisper	`whisper` runs whisper-cli with the model picked above, as every version so far. `qwen3` runs Qwen3-ASR-1.7B through CrispASR, the same binary the Canary targets use. Stored as `TranscriptionEngine`.
crispasr Binary	not installed	The one CrispASR binary, shared with More target languages. Either panel installs it. CPU is the default: in testing the CPU build was faster than the Vulkan build on an integrated GPU.
Qwen3-ASR Model	not installed	Downloads the GGUF weights. Q8_0 is 2.5 GB and recommended. Q4_K is 1.5 GB, with the audio encoder kept at Q8_0.
Word timing (CTC aligner)	not installed, on	Downloads the NVIDIA Canary CTC aligner (392 MB, CC-BY-4.0) that gives Qwen3-ASR word-accurate cue timing, see below. The checkbox keeps an installed aligner idle when off. Stored as `Qwen3AlignerModelPath` and `Qwen3UseAligner`.
Qwen3-ASR model path	empty	Filled by the model Download button. Set it only for your own file.

What stays on Whisper when Qwen3-ASR is selected:

Language detection, including the per-chunk detection of the forced-subtitle pass. Qwen3-ASR always receives a language code; with Default Language on auto-detect the Whisper detection model names it first.
Any language outside Qwen3-ASR's 30 (Chinese, English, Cantonese, Arabic, German, French, Spanish, Portuguese, Indonesian, Italian, Korean, Russian, Thai, Vietnamese, Japanese, Turkish, Hindi, Malay, Dutch, Swedish, Danish, Finnish, Polish, Czech, Filipino, Persian, Greek, Hungarian, Macedonian, Romanian). Such a title is transcribed by Whisper and the log says so.
Translation into English, which Qwen3-ASR cannot do. A turbo Whisper model still cannot translate, see Limitations.
Everything, until both the binary and the model are installed. A missing file means Whisper transcribes and the panel says so. No job fails because of the switch.

Thread count comes from the Canary thread count field under Translation, which is the crispasr -t for both engines. 0 keeps crispasr's default of 8.

A Qwen3-ASR title is transcribed in ten-minute windows, and each finished window is written to the subtitle file at once. crispasr only writes its output when a run ends, so without windows an interruption (Pause generation during playback, a restart) threw the whole run away and a long film restarted from zero every time. With them an interruption costs at most one window and the next attempt resumes where the file ends, like Whisper. Each window starts at a cue boundary of the previous one, so nothing is cut or repeated at the seams.

Qwen3-ASR returns text without timestamps. Without the aligner, cue timing comes from the Silero VAD model: each speech segment is one cue, split at Maximum subtitle line length in proportion to text, so a segment with music under it becomes a cue that starts early. With the aligner installed and on, crispasr places every word and cue starts land on the spoken word, for English and the 24 Canary languages; other languages keep segment timing. The line length defaults to 42 characters for this engine, scaled for Cyrillic, Greek and CJK scripts because crispasr counts bytes. The subtitle timing corrections apply afterwards like for Whisper, once Align subtitles to speech is on.

Generation defaults¶

Setting	Default	What it does
Default Language	Auto-detect from audio (`auto`)	Reads the language tag from each audio stream and transcribes in that language. With no tags, whisper detects the spoken language and the file is written with language `auto`. Picking a specific language forces every transcription to use it.
Audio languages (auto-detect)	All audio languages	Only applies when the language above is Auto-detect and the file carries more than one audio language. All audio languages transcribes every one of them, producing one subtitle per language. Primary audio track only transcribes just the first track. A specific language, or a file with no language tags, is one language already and is unaffected.
Subtitle Mode	Full	Which passes run. See below.

Subtitle modes¶

Mode	What it produces
Full	A complete transcription of all speech.
Forced Only	Only the segments where the spoken language differs from the track's primary language, for example French dialogue inside an English film.
Full + Forced	Both files, per track.
Translation Only (English)	Skips native-language transcription entirely and produces only an English translation, in a single whisper pass.

Translation Only needs a model that can translate. The recommended turbo models cannot, so pick a medium or large non-turbo model for it. Limitations explains why.

Subtitle file naming¶

Setting	Default	What it does
Subtitle label	`WhisperSubs`	The brand written into the plugin's own subtitle filenames through the `{label}` token. With the default template it lands right after the language code, which makes it the Title shown in Jellyfin's subtitle picker. It is also the ownership marker the plugin matches to recognise its own sidecar files, so pick something distinctive. It is matched as a substring.
Filename template	`{name}.{lang}.{label}{.type}`	The filename pattern, without the extension.

Template tokens¶

Token	Expands to
`{name}`	The media filename without its extension. Treated as opaque, so dots inside a release name are never read as separators.
`{lang}`	The language code, for example `en`.
`{label}`	The subtitle label above.
`{.type}`	`.translated`, `.forced`, or nothing for a full transcription.
`{type}`	The same value without the leading dot.

A template must contain {name}, {lang} and {label}. The page shows a warning under the field when one is missing, and an invalid template that got saved anyway falls back to the default at the moment it is used, so it can never produce a broken filename.

Empty segments are cleaned up after expansion: any .. collapses to ., and a leading or trailing dot is trimmed. Movie..srt and Movie.srt. cannot happen.

The three preset buttons fill the field with:

Brand first (recommended)   {name}.{lang}.{label}{.type}
Label at end                {name}.{lang}{.type}.{label}
Keep .generated             {name}.{lang}.{label}.generated

A template with no type token collides

The Keep .generated preset has no {.type}, so the type is simply dropped. Full, forced and translated output for the same language all expand to the same filename and overwrite each other. If you use a custom template, keep {.type} in it unless you run in Full mode only.

Files written by older versions are still recognised. Anything containing .generated. or .translated. counts as the plugin's own output regardless of the current label, alongside the label-based .WhisperSubs. form.

Automation¶

Setting	Default	What it does
Enable Auto-Generation	Off	Lets the scheduled task sweep your libraries. With this off, subtitles are only ever produced by a manual Generate.
Libraries	none selected	The checkbox list under Auto-Generation scopes the sweep. With none selected, every library is scanned. Selecting one or more restricts the sweep to those. It applies to the scheduled task only; a manual Generate on a single item ignores it.
Enable Lyrics Generation (Experimental)	Off	Includes music libraries in the sweep and writes `.lrc` lyrics next to audio tracks. Whisper is trained on speech, not singing, so accuracy varies. See Limitations.
Pause generation during playback	Off	Pauses transcription on this server while any user is playing something, and continues when playback stops. A session paused on a title does not count. On Linux the running engine is suspended and continued, so a pause loses no work; on other systems the job is cancelled and retried from its partial output. A job on a remote worker starts at once and its requests keep running, but what it runs on this server (the audio extraction, and this server's Whisper detecting languages for a Qwen3-ASR or akou row) is suspended through playback on Linux like a local job. Useful when the same box transcodes and transcribes.
Skip media that already has subtitles	On	The sweep skips media that already has a usable subtitle in the language it needs, embedded or external. For the translation pass, an existing English subtitle counts as already translated.
Ignore forced subtitles when skipping	On	A forced subtitle track does not count as satisfying the need. Forced tracks only cover foreign-dialogue inserts, not the whole dialogue.

Language detection and forced subtitles¶

The forced-subtitle pass asks which language each stretch of speech is in and keeps the stretches that are not in the title's language.

Setting	Default	What it does
Detection model	Small detection model	Small detection model is `ggml-base.bin`, downloaded for you, about 1.3 s a stretch. The Whisper transcription model is more accurate: on 358 labelled stretches from a real library it named 86.6% right against 79.6%, and called 3 of 37 Spanish stretches foreign against 9. It takes about 13 s a stretch on 16 CPU threads, or about 15 s on an Intel UHD 770 GPU, so a film's forced pass can spend half an hour on detection. A model file you choose takes the path of any multilingual Whisper ggml model; a missing file falls back to the small model with a warning in the log. Qwen3-ASR's own language ID through akou scored 78.2% on the same set: it cannot name Catalan or Galician, and it never called a Spanish stretch foreign.
Detection device	Auto	Auto runs a short English clip (whisper.cpp's public-domain JFK sample) through the GPU before the first detection with each whisper-cli and model, and detects on the CPU (`--no-gpu`) when the answer is not English at 0.5 or more. The page shows the last result. GPU skips the check, CPU always passes `--no-gpu`. See Limitations. The page also warns when the container sees several GPUs or an SR-IOV virtual function.
Translate foreign lines into English on English titles	On	On an English title the forced subtitle shows its foreign lines in English. Off, they are written in their own language. Other titles always keep the original language, since Whisper only translates into English.
Lines Qwen3-ASR cannot transcribe	Transcribe them with Whisper	On a title Qwen3-ASR transcribes, a foreign line in a language outside Qwen3-ASR's 30 goes to this server's Whisper model, which loads a full model for it. Leave them out skips such lines. A title whose only foreign lines were skipped is tried again once you switch back to Whisper; a forced subtitle already written with some lines left out stays as it is until you delete it.

Detection and engines (advanced)¶

Setting	Default	What it does
Detection threads	`0`	CPU threads for a detection run. `0` is 4 for the small model and the Whisper thread count for the transcription model.
Foreign-language confidence	`0.3`	How sure detection must be, 0 to 1, before a stretch counts as foreign. Higher leaves out more uncertain stretches; lower catches more and lets more wrong ones in. The translation pass's own English check keeps 0.3.
Stretches per detection run	`32`	Stretches one whisper-cli run detects, 1 to 64. Each run loads the model once.
Detection timeout per stretch	`300`	Seconds one stretch may take before the run is stopped, 30 to 3600.
Vulkan device for whisper.cpp and crispasr	empty	A Vulkan device index, or several separated by commas, passed as `GGML_VK_VISIBLE_DEVICES` to whisper-cli and crispasr. Empty lets the engine pick its first GPU. It does not make an SR-IOV virtual function safe: give the container the physical function only (for an Intel iGPU, `/dev/dri/renderD128` and its `card` node rather than all of `/dev/dri`), because Vulkan compute on a virtual function can hang it.
Full-model engines at once	`1`	Processes with a full model allowed on this server together, 1 to 8: Whisper transcription or translation, Qwen3-ASR, Canary, and detection on the transcription model. Measured on an Intel UHD 770 with Vulkan: large-v3 about 6.2 GB, crispasr with Qwen3-ASR and its aligner about 5.6 GB. Size it against the container's memory limit. Applies from the next engine started.
Let small-model detection run beside a full model	On	A small-model detection run takes about 0.6 GB, so one runs beside the full-model engines. Off, it waits its turn with them.
Qwen3-ASR window on this server	`600`	Seconds of audio per pass when this server's Qwen3-ASR transcribes, 60 to 7200. Playback or a restart costs at most one window.
Remove leftover temp files when the task starts	On	Deletes this plugin's temp files older than the Jellyfin process, which only a job killed by a restart leaves behind.
Pause a remote worker's jobs on this server during playback	On	With Pause generation during playback on, the audio extraction and detection this server runs for a remote worker's job are suspended while someone watches (Linux). Off, they run through.

Engine limits and the Vulkan device apply to the next engine process as soon as you save; the detection settings apply from the next run of the task.

Subtitle generation¶

Whisper transcribes the speech it hears, so it can only write a subtitle in the title's own audio language. Turning that audio into English is a separate pass, covered under Translation below.

Setting	Default	What it does
Generate original-language subtitles	On	The main generate switch. Transcribes each title in its own spoken language: a Korean film gets Korean subtitles, an English film gets English. Turning it off leaves the sweep producing only whatever forced or translated output the mode calls for. A manual single-item Generate always transcribes regardless of this setting.
Count image-based subtitles as present	Off	When on, image-based tracks (PGS, VOBSUB) count as an existing subtitle. Off by default because image subtitles cannot be searched or edited, so the plugin still writes a text one.

The two filters are independent

"Ignore forced subtitles" and "Count image-based subtitles as present" are separate tests, applied one after the other to the same stream. A stream has to pass both to count as an existing subtitle. Neither one governs the other: a forced image track is rejected by the forced test whatever the image setting says, and turning the image setting on does not make forced tracks count.

The plugin's own output is always excluded from these checks, so a subtitle it generated last week never satisfies the check this week and stops it regenerating a file it just wrote.

Skip cache¶

Re-checking the filesystem for every candidate item on every scheduled run is the slow part of a large library. The cache stores the per-item verdict so a repeat run can skip the probe.

Setting	Default	What it does
Remember already-subtitled items between runs	On	Caches the "already has subtitles" verdict per item. An entry is reused only while the item's Jellyfin change token is unchanged and the skip settings above are unchanged. Any metadata or subtitle change, any edit to a skip setting, or a change to the translation target languages re-checks the item. Scheduled task only.
Skip-cache re-verify (days)	`30`	Backstop. Re-check a cached item after this many days even if nothing changed, so a subtitle you deleted outside Jellyfin is eventually regenerated. Deleting a file outside Jellyfin does not bump the change token until the next library scan, which is what this covers. `0` disables the time backstop and relies on the change token alone.

The Clear skip cache now button next to the field empties the cache immediately, so the next scheduled run re-checks every item from scratch.

Translation to English¶

English is the only language whisper can translate into.

Setting	Default	What it does
Also create an English subtitle when a title has none	Off	For a title whose audio is not English and that has no English subtitle, additionally translate it. Titles with English audio, or an existing English subtitle, are skipped automatically, so this only fills a gap. Uses whisper's own `--translate`, no external service.

This applies only when Subtitle Mode includes Full subtitles. It does nothing in Forced Only, and it is implicit in Translation Only.

More target languages (experimental)¶

Whisper translates only into English. For a title whose audio is English, the plugin can also write a subtitle in any of 24 European languages with NVIDIA Canary, which CrispASR runs. A title counts as English when any of its audio tracks is tagged English, so a foreign film with an English dub qualifies and Canary translates from the dub. The design doc has the reasoning and the test results.

The section sits under Translation on the settings page. The checkboxes drive the automatic run and need Also create an English subtitle when a title has none turned on; nothing changes until you tick a language. Translating a single title needs neither. See Translate one title.

Setting	Default	What it does
Target language checkboxes	none	Each checked language gets its own `.translated` subtitle, for example `Movie.nl.WhisperSubs.translated.srt`. Stored as `TranslationTargetLanguages`.
crispasr Binary	not installed	Downloads the pinned CrispASR release for your platform. On Linux x64 the variants are CPU, which is the default, CPU compatibility for CPUs without AVX2, Vulkan, CUDA 12, CUDA 13 and ROCm. CPU is the default because Canary ran no faster on an integrated GPU. The Vulkan and ROCm builds do not fall back to the CPU when the driver is missing. The same binary serves the optional Qwen3-ASR transcription engine.
Canary Model	not installed	Downloads the Canary GGUF weights. Q8_0 is 1.05 GB and recommended. Q5_0 is 720 MB.
crispasr binary path	empty	Filled by the Download button. Set it only for your own build.
Canary model path	empty	Filled by the model Download button.
Canary thread count	`0`	crispasr `-t`, for Canary and for Qwen3-ASR. `0` keeps the engine's own default.

Per title and per language, the pass skips instead of translating when:

The audio is not English, or its language cannot be determined. This is the normal case for most of a library, so it is logged at Information level and is not an error.
The audio is already in that language.
The plugin already wrote a translated subtitle in that language.
A usable subtitle in that language exists and Skip media that already has subtitles is on.

If the audio is English and no engine can make the language, a title you generate by hand fails that language with an error that says why: nothing is installed, Also use this server as a worker is off, or a single Remote API URL keeps this server out of the pool. An engine is the local crispasr binary and Canary model together, or a worker that lists the language, as described in Remote workers. No file is written for a language that fails or skips.

The scheduled task treats an English title as finished only when every checked language has its subtitle, so adding a language gets picked up by the next automatic run. Changing the list also clears the skip cache. A checked language that no engine can make is left out of each automatic run, with one warning in the log naming it, so it never fails your English titles. Installing the engine clears the skip cache and the next run picks those titles up.

Translate one title¶

On a movie, episode, season or series page, Translate into… sits next to the Subtitles button. Pick a language and the plugin queues a translation into that language for that title, or for every episode of the season or series. It works with no checkbox ticked and with Also create an English subtitle when a title has none off.

English comes from Whisper and works from any audio language. It needs a model that can translate. With a turbo model active on this server, English comes only from a worker that lists en, and without one the pick is refused.
The other 24 languages come from Canary and need English audio.
If no engine can make the language, the plugin refuses the pick at once and queues nothing. Admins see why; other users see that the language cannot be made right now, and the reason goes to the log. An engine is the crispasr binary and Canary model on this server, or a worker that lists the language.
If the worker that makes the language is busy, the translation waits for it. If that worker cannot start at all, the translation stays queued and runs once it can.
If a title's audio is not English and you picked a Canary language, that title fails with the reason. It is not retried and gets no file. The queue panel shows the reason as the last error.
A title that already has the translation, or whose audio is already in that language, is skipped.
A single movie or episode is translated even when it has a subtitle in that language from another source. A season or series respects Skip media that already has subtitles.

For admins, the translation goes straight to the queue at the admin priority. When Allow users to request subtitles is on, other users see the same list. Their pick becomes a request with the usual approval, quota and caps, and a translation request counts toward them like any other. Collections and folders cannot be translated in one go, for the same reason they cannot be generated in one go.

Canary output is experimental. Limitations explains what it cannot do.

Subtitle timing¶

Why these settings exist¶

whisper.cpp emits cues back to back. The start of one cue is the end of the previous one, with no gap, even across a silence where nobody is speaking. On screen that reads as a subtitle appearing during the pause before its line is actually spoken.

There are two independent corrections for it:

Native VAD runs Silero voice activity detection inside whisper.cpp at transcription time, so a cue starts at real speech onset. This is the default and the better fix.
The forward snap is the older energy-based fallback. It runs an extra FFmpeg silencedetect pass over the audio already extracted on this server and moves each cue start forward to the nearest detected speech onset. It only ever moves a cue later, never earlier.

Both apply to full and translated subtitles. Neither applies to forced subtitles or lyrics.

Setting	Default	What it does
Use speech detection (VAD)	On	Passes `--vad` to whisper-cli with the Silero model. The model is about 885 KB and downloads automatically on first use. Local whisper-cli only: it does not apply to a remote worker, which owns its own timing, nor to forced subtitles.
Align subtitles to speech (fallback)	On	Enables the FFmpeg forward snap. On its own it runs only when VAD is off. Leave it on so the fallback exists.
Also align VAD / worker timestamps to speech	Off	Layers the forward snap on top of VAD output and on top of remote worker output. Turn this on if lines still appear early. Requires "Align subtitles to speech" to be on. Off by default because the energy-based detector proved unreliable on some real material and can push a few starts slightly late.
Compensate audio start offset	On	Shifts every timestamp by the audio stream's start time, for containers whose audio does not begin at exactly 0:00. Applies to local and to timestamped remote output, for full and translated subtitles, not forced.

When the forward snap actually runs¶

Timestamps came from	Align subtitles to speech	Also align VAD / worker timestamps	Forward snap runs
Local whisper-cli, VAD off	On	either	Yes
Local whisper-cli, VAD on	On	Off	No
Local whisper-cli, VAD on	On	On	Yes
Remote worker or hosted provider	On	Off	No
Remote worker or hosted provider	On	On	Yes
anything	Off	either	No

VAD tuning (advanced)¶

Each of these maps to one --vad-* flag on whisper-cli, and each applies only when Use speech detection (VAD) is on.

An empty field means "use whisper's own default"

Leave a tuning field empty and the plugin stores -1, which it treats as unset. No flag is emitted for it and whisper.cpp uses its built-in value. That is why the rows below quote a whisper default rather than a plugin one: on a fresh install the plugin sets none of them, and the command line it builds is identical to one with no tuning feature at all.

Max Speech Duration additionally treats 0 as unset, because a zero second cap has no meaning.

Setting	Default	What it does
Silero VAD model	`v5.1.2`	Which Silero model whisper-cli loads. `v5.1.2` is the default and `v6.2.0` is a newer opt-in. Both are about 885 KB. An unset or unrecognised value falls back to `v5.1.2`, so upgrading never silently changes the model or shifts your timing. Selecting the other version downloads it on the next run.
VAD Threshold	unset (whisper uses `0.5`)	Speech probability cutoff, `0` to `1`. Lower catches quieter speech and adds false positives.
Min Speech Duration (ms)	unset (whisper uses `250`)	Segments shorter than this are dropped.
Min Silence Duration (ms)	unset (whisper uses `100`)	How much silence has to sit between two speech segments before they are split. Raising it groups sentences together.
Max Speech Duration (s)	unset (whisper leaves it unlimited)	Segments longer than this are split automatically. Around `30` limits timestamp drift on long unbroken takes.
Speech Padding (ms)	unset (whisper uses `30`)	Padding added to each side of a speech segment so word edges are not clipped.
Samples Overlap (s)	unset (whisper uses `0.1`)	Audio carried over between consecutive segments so a word on the boundary is not cut.

A matching flag placed in Custom Whisper Arguments supersedes the value set here. Custom arguments are appended last and whisper-cli takes the last value it sees.

The next two sections on the page, Remote Whisper API and Worker Pool, are covered in Remote workers.

Performance and advanced¶

These sit under Advanced / Manual Install on the settings page.

Setting	Default	What it does
Whisper Thread Count	`0`	CPU threads for whisper inference. `0` emits no `-t` flag, so whisper.cpp uses its own default of 4. Set it to your core count. On a 16-thread i5-14500 a 2h15m film drops from an estimated 7 hours to 1h48m. Language detection with the small model uses 4 threads unless Detection threads says otherwise.
Maximum subtitle line length	`0`	Maximum characters per cue, emitted as `--max-len N` together with `--split-on-word` so a cap never breaks mid-word. `0` is unset, which leaves whisper.cpp's own default of unlimited; Canary translations run by the local `crispasr` binary use `42` when it is `0` (`84` for Bulgarian, Greek, Russian and Ukrainian), but a CrispASR server worker does not. For Canary the number counts bytes, so in those four languages each letter counts twice. Raise it if subtitles arrive as one enormous run-on line: broadcast subtitling caps a line near 42 characters and `47` is a good starting point. Applies to the local whisper-cli and the local `crispasr` only, since a remote worker, a CrispASR server included, owns its own segmentation. Set `WHISPER_MAX_LEN` on a whisper worker instead.
Custom Whisper Arguments	empty	Extra space-separated arguments appended to every whisper-cli invocation, for example `--beam-size 8`. Local whisper-cli only.

Arguments the plugin manages itself are blocked from that field: the model, input file, language, thread count, max context, non-speech suppression, every output format and the output path, --translate, --detect-language, the no-timestamps flags, --prompt, the offset and duration flags, and --vad with --vad-model. The VAD tuning flags and --max-len are deliberately not blocked, so you can override those settings from here.

Config file only¶

These have no control on the settings page. They live in Jellyfin's plugin configuration file, at <Jellyfin program data>/plugins/configurations/WhisperSubs.xml:

Deployment	Path
`jellyfin/jellyfin` container, and the NAS app images built on it	`/config/plugins/configurations/WhisperSubs.xml`
Debian or Ubuntu package on bare metal or in an LXC	`/var/lib/jellyfin/plugins/configurations/WhisperSubs.xml`

Stop Jellyfin before editing it

Jellyfin holds the plugin configuration in memory and writes the whole file back whenever you press Save on the settings page. Editing the file while Jellyfin is running either has no effect or gets overwritten. Stop Jellyfin, edit, start it again.

Remote call deadlines¶

Every call to a remote worker is bounded by a deadline derived from the length of the audio, rather than by a fixed HTTP timeout. The deadline is the audio length multiplied by the real-time factor, then clamped between the floor and the cap. A slow but working worker is never cut off; a dead endpoint fails instead of piling up.

Setting	Default	What it does
`JobTimeoutRealtimeFactor`	`6.0`	How much slower than real time a worker may run before a single call is presumed hung.
`JobMinTimeoutSeconds`	`60`	Floor for the per-call deadline, so a tiny language-detection chunk still gets a sane minimum.
`JobMaxTimeoutHours`	`12`	Absolute cap for the per-call deadline.

Retries and sweep length¶

Setting	Default	What it does
`JobMaxRetries`	`3`	How many times a killed or failed job is automatically re-queued before the plugin gives up. It goes back at its original priority tier and the counter survives a Jellyfin restart. `0` disables auto-retry, dropping a killed job outright.
`TaskMaxRuntimeHours`	`6`	Wall-clock cap on one sweep of the Generate Subtitles task. At the cap the sweep stops cleanly between items: finished work is kept, the skip cache is written, and the next scheduled run picks up where this one stopped. `0` means unlimited.

Other config file values¶

Setting	Default	What it does
`LanguageDetectionSampleSeconds`	`30`	Seconds of audio, from the start of each chunk, sent for language detection only. Detection needs only a short window, so bounding it stops a long or noisy chunk turning into a runaway decode. It does not affect subtitle quality: a chunk confirmed as foreign is still transcribed in full. `0` sends the whole chunk. `30` matches whisper's own language-detection window.
`VadModelPath`	empty	An explicit path to a Silero VAD ggml file. The plugin also writes this automatically when it downloads a model, and a path it wrote inside its own managed `vad/` directory is ignored in favour of the Silero VAD model selection. A path pointing anywhere else is treated as a deliberate external override and wins over that selection.

Subtitle requests and priority¶

Off by default. When Allow users to request subtitles is on, non-admin users get a Request Subtitles entry on the item page. Requests land as Pending and consume no CPU until an admin approves them, unless auto-approve is also on.

Work is drained strongest tier first, and FIFO within a tier. Lower tiers never starve a higher one.

Setting	Default	What it does
Allow users to request subtitles	off	Master switch. While off, only admins can queue work.
Auto-approve user requests (skip my approval)	off	Enqueue a request immediately instead of holding it for an admin.
Admin request priority	High	Tier for work an admin queues by hand.
User request priority	Medium	Tier for an approved user request. Below admin work, above the sweep.
Background sweep priority	Background	Tier for the scheduled library sweep. The weakest tier.
Requests per user per window	5	Requests one user may make per rolling window. `0` means unlimited.
Rolling window (hours)	24	The rolling window the daily quota is measured over.
Max active requests per user	3	Requests one user may have in flight at once. `0` means unlimited.
Max items per request	200	Ceiling on the fan-out when a user requests a season or a series. The settings page enforces a minimum of 1 and rewrites anything lower back to 200.
Global active request cap	500	Ceiling on pending and queued requests across all users. `0` means unlimited.

The last five sit behind the collapsed User request limits (anti-abuse) disclosure on the settings page; expand it to find them.

Priorities are always assigned server-side from who made the request. A client cannot ask for one.

Settings documented elsewhere¶

The remaining settings belong to features with their own pages.

Settings	Where
Whisper Binary Path, Whisper Model Path, and the recorded binary variant	Setup guide
Vocal separation: the master switch, binary and model paths, the recorded variant and quantization, overlap and chunk size	Vocal separation
Remote Whisper API URL, model and key, the worker pool list with each worker's dialect and translation targets, and whether the local host participates as a worker	Remote workers