Set Up WhisperSubs Workers with Jellyfin and Localtonet

How WhisperSubs, Jellyfin, workers, and Localtonet fit together

WhisperSubs is a Jellyfin plugin for generating subtitle files with Whisper speech-to-text models. Its default processing path runs transcription on the Jellyfin server. The plugin can also distribute work to a pool of additional machines, GPUs, a NAS, or a deliberately configured hosted endpoint. Local workers are used before the plugin bursts to a paid provider.

The important architectural distinction is that WhisperSubs does not need to become a separate public media application. Its administration interface, progress information, library browser, and user request controls appear inside Jellyfin. When you add remote access with Localtonet, the local target is therefore your existing Jellyfin HTTP listener. An authorized administrator who opens the resulting public HTTPS address reaches Jellyfin and can then navigate to the WhisperSubs controls allowed by Jellyfin.

This separation also helps with troubleshooting. A plugin installation problem belongs to Jellyfin or WhisperSubs. A transcription failure belongs to the engine, model, FFmpeg, media permissions, selected binary, or worker. A page that works locally but not through its public address points instead to the Jellyfin listener, Localtonet client, or tunnel configuration.

Prerequisites and planning decisions

Begin with a working Jellyfin installation. Confirm that you can sign in locally as an administrator and reach the Dashboard and Plugins pages. Do not start by creating a public tunnel. Installing and testing locally first keeps application, transcription, and networking problems separate.

Account for the operating system

The engine setup differs by platform. Linux users can download both the Whisper engine binary and a model from the WhisperSubs settings page. The project offers multiple prebuilt binary variants, so the selected build must match the server's CPU and any intended acceleration backend.

On macOS and Windows, an empty binary variant list is expected behavior rather than a broken plugin page. Prebuilt Whisper engine downloads are Linux-only. Install whisper-cli yourself and enter its real filesystem location in Whisper Binary Path. Model downloads remain available through the settings page on all three platforms.

Do not copy an engine path from another operating system or deployment layout. For example, paths inside a container differ from host paths. Jellyfin must be able to see and execute the path from its own runtime environment.

Decide whether the Jellyfin server is sufficient

A separate worker is optional. Start with the local Jellyfin server unless you already know it lacks suitable processing resources. A successful local transcription gives you a baseline before you introduce worker networking, credentials, extra storage access, or a hosted provider.

GPU acceleration options documented by the project include CUDA for NVIDIA hardware, Vulkan for Intel, AMD, or NVIDIA hardware, and ROCm for AMD hardware. Availability on a particular system still depends on compatible hardware, drivers, container passthrough where relevant, and a matching Whisper binary. Do not select an accelerated build solely because the hardware vendor appears in that list.

Install WhisperSubs from the Jellyfin plugin repository

The recommended installation method uses the project's Jellyfin repository. It avoids manually compiling and copying the plugin assembly, and it keeps plugin discovery inside Jellyfin's normal catalog workflow.

https://geiserx.github.io/whisper-subs/manifest.json

If WhisperSubs does not appear in the catalog, first recheck the manifest URL and confirm that the Jellyfin server can retrieve the repository metadata. If installation appears to complete but the settings page is absent, verify that Jellyfin was actually restarted and that its version meets the plugin requirement.

Why this guide does not use the manual build method

The project also documents a developer-oriented manual path that builds the plugin in Release configuration and copies WhisperSubs.dll into a Jellyfin plugin directory. That path introduces .NET build requirements and deployment-specific plugin locations. It is unnecessary for the normal installation covered here, so the repository installation is the safer and simpler baseline.

Configure the Whisper engine, model, and subtitle behavior

Configure the engine on Linux

Open the WhisperSubs settings page and use its engine setup controls to select a compatible Linux binary variant. The project publishes multiple variants because processors and acceleration environments do not all support the same instructions or backends. Choose according to the actual CPU, GPU, drivers, and runtime available to Jellyfin.

After choosing the variant, use the settings page to download the engine. Confirm that the resulting configuration points to the downloaded whisper-cli executable. If the executable immediately terminates with exit code 132, a common cause is an illegal CPU instruction from an incompatible binary variant. Select a build compatible with the processor rather than repeatedly retrying the same executable.

Configure the engine on macOS or Windows

Install whisper-cli separately because the plugin does not offer prebuilt engine downloads for these platforms. Then set Whisper Binary Path to the actual whisper-cli executable. The exact installation command and path depend on how whisper.cpp is installed on that machine, so no universal command or path is safe to provide.

Check the path from Jellyfin's point of view. A path that works in your interactive shell can still fail when Jellyfin runs under a service account with a different working directory, environment, or filesystem access. Use an absolute path and grant only the execution and read permissions required by the Jellyfin service.

Download and select a model

Model downloads are available from the plugin settings on Linux, macOS, and Windows. Select and download a GGML model, wait for the download to complete, and confirm that the model path is populated. A plugin with a valid engine but no model still cannot transcribe.

Model choice affects resource requirements and transcription behavior, but the supplied evidence does not establish a universal best model for every language, server, or GPU. Begin with a model that fits the memory and processing capacity of the machine, verify one file, and evaluate its output before scheduling the whole library.

Choose a subtitle mode

Automatic language detection first considers each audio stream's language tag. If a tag is absent, Whisper's own detection is used. For media containing multiple audio languages, the plugin can generate a subtitle for each audio language.

Understand output naming

WhisperSubs writes generated subtitles beside the media. Its default filename template is {name}.{lang}.{label}{.type}, and the default label is WhisperSubs. A Spanish movie can therefore produce the following files:

Movie.es.WhisperSubs.srt
Movie.es.WhisperSubs.forced.srt
Movie.en.WhisperSubs.translated.srt

Music output uses an LRC file such as Song.lrc. The subtitle label is both the title shown in Jellyfin's subtitle picker and the marker WhisperSubs uses to recognize files it created. If you change the label, choose something distinctive. Older files containing the .generated. anchor remain recognized.

Review the skip behavior before processing a mature library. The scheduled task skips media that already has a usable subtitle in the required language. Forced tracks do not meet that requirement while Ignore forced subtitles when skipping remains enabled, which is the documented default. Image-based subtitle tracks are not counted unless Count image-based subtitles as present is enabled.

Verify a local transcription before adding workers or remote access

Use one short, representative media item for the first test. It should be stored in a library location where Jellyfin can read the media and write an adjacent subtitle. A small test reduces the time needed to diagnose an engine, model, or permission problem.

A completed job should leave both an observable plugin result and a usable media-side file. Checking only the queue is not enough. Likewise, finding an SRT file without testing playback does not confirm that Jellyfin indexed it or that the content matches the intended language.

WhisperSubs can resume interrupted transcription from its last timestamp instead of starting the entire item again. This is useful after a transient interruption, but it should not be treated as a reason to ignore recurring engine or storage failures.

Plan and validate WhisperSubs transcription workers

Once local transcription works, you can consider additional workers. WhisperSubs supports a worker pool for distributing transcription across extra machines, GPUs, a NAS, or a hosted endpoint. It can also use Groq, OpenAI, or OpenRouter as a backend when deliberately configured. Processing stays on hardware you control by default, but media leaves the Jellyfin server when you intentionally configure a remote worker or hosted provider.

Worker expansion should solve a specific constraint. A worker may provide a suitable GPU, isolate a heavy workload from the media server, or increase parallel processing capacity. It also adds network reachability, authentication, service lifecycle, and resource-management concerns.

A safe worker rollout sequence

1. Complete one successful transcription on the Jellyfin server.
2. Choose a worker host with a compatible processor or GPU and sufficient storage and memory for its engine and model.
3. Install the official worker implementation according to the documentation matching the deployed WhisperSubs version.
4. Configure the worker's engine, model, and required authentication without exposing its API key.
5. Ensure Jellyfin can reach the worker endpoint through the intended private or controlled network path.
6. Add the worker through WhisperSubs using the endpoint and authentication fields documented by the installed release.
7. Inspect the worker status before sending a test job.
8. Submit one test item and verify that it is processed by the intended worker.
9. Add further workers only after the first one behaves predictably.

This limitation matters because an incorrect port or variable can produce a service that appears to start while remaining incompatible with the plugin. It is safer to leave an exact value unspecified than to publish a stale container command. Record the version, worker address, selected backend, and non-secret configuration when you deploy it so future troubleshooting begins with a reproducible inventory.

Protect remote worker traffic

Keep worker endpoints private whenever the architecture permits it. Apply authentication, network restrictions, least privilege, and a narrow path between Jellyfin and each worker. If a worker processes media remotely, understand what audio or media-derived data crosses that connection and whether the destination is hardware you control or a hosted provider.

Exposing Jellyfin through Localtonet does not require exposing worker endpoints. These are separate traffic paths. Public Jellyfin access is for the application interface, while worker connectivity is for transcription processing. Do not point the Jellyfin HTTP tunnel at a worker just because both are associated with WhisperSubs.

Expose the working Jellyfin HTTP endpoint with Localtonet

Add remote access only after Jellyfin, WhisperSubs, and at least one local transcription work on the local network. You need the exact local IP address or hostname and HTTP port on which Jellyfin is listening from the Localtonet client's point of view.

This article intentionally does not provide a supposed Jellyfin default address or port. Jellyfin listeners vary by installation, reverse-proxy arrangement, container mapping, and administrator configuration. Open the address that already works locally and record its host and port. If Localtonet runs in a container or on another device, remember that 127.0.0.1 refers to that client environment, not automatically to the Jellyfin host.

With Localtonet, our client initiates an outbound connection to a relay server. This means the workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The tunnel is available only while the selected Localtonet client is connected and the tunnel is running.

The current dashboard is authoritative for available servers, regions, process options, and account-specific capabilities. If you choose a custom domain, follow the current DNS instructions rather than assuming a record type or target. For the product workflow, consult our Localtonet HTTP tunnel documentation.

Verify both application and tunnel state

Test the public address in a private browser session so an existing local login does not hide an authentication problem. Confirm that the connection presents the expected Jellyfin sign-in page, not an unrelated service on the same host. Then sign in with a least-privileged test account and verify only the capabilities that account should have.

For administrative testing, use an administrator account only when necessary. Open the WhisperSubs page, inspect queue status, and avoid launching a large job merely to prove that the interface loads. If you need to verify a request flow, use the same small media item that passed local testing.

Routine operation, security, and troubleshooting

Operate the queue deliberately

WhisperSubs gives manual user requests priority over the background sweep. Non-administrator users can request subtitles from the item menu only after an administrator enables that option. Consider the processing capacity of your server or workers before enabling requests broadly.

The default scheduled task runs daily at 2:00 AM and on startup. A persistent skip cache prevents repeated probing of unchanged items. Review scheduling in the context of your server's backup window, media scans, power availability, and other compute-intensive jobs.

Real-time progress reports the current item, current phase, file progress, and queue depth. Use those signals to distinguish a long transcription from a stalled process. Preserve relevant, non-secret Jellyfin and plugin logs when diagnosing a failure.

Diagnose installation and engine failures

Check container and service boundaries

Container deployments commonly fail because a path or address is valid on the host but not inside the container. A host path to whisper-cli, a model, or media is useful only if Jellyfin sees the corresponding mounted path. The same rule applies to networking. A Jellyfin container cannot necessarily reach a worker through the worker host's loopback address.

GPU acceleration in a container additionally requires appropriate device passthrough and compatible drivers. WhisperSubs cannot compensate for a GPU that the Jellyfin or worker runtime cannot see. Establish hardware visibility before treating the plugin configuration as the source of the problem.

Maintain privacy expectations

By default, transcription occurs on the Jellyfin server, and self-hosted workers can keep processing on systems you control. That privacy boundary changes if you add a hosted provider or a remote worker outside your controlled network. Document which destinations receive media-derived data and remove unused provider credentials.

Localtonet's role is connectivity to Jellyfin. The Localtonet client establishes an outbound relay connection, and the public endpoint exists only while the selected client is connected and the tunnel is running. You can stop the tunnel without uninstalling Jellyfin or WhisperSubs, and you can delete it when the remote-access configuration is no longer needed.

Frequently asked questions