Real-time bilingual subtitle translation for IINA
English · 简体中文 · 繁體中文 · 한국어 · 日本語 · Русский · العربية · Français
SubTandem translates the local embedded text subtitle or external SRT/ASS subtitle currently selected in IINA and renders the translation itself in an independent overlay. It looks only a short distance ahead of playback, translates in bounded batches, and keeps the original subtitle selection and video playing when a translation is delayed or fails.
SubTandem keeps the original subtitle visible while independently displaying the translation at your chosen position.
- Live bilingual subtitles: Keep the original subtitle selected in IINA while SubTandem renders translations centered horizontally at your chosen vertical position without occupying another subtitle track.
- Embedded and external text subtitles: Works with local Matroska SubRip/ASS/SSA, local MOV/MP4
mov_text, and readable external SRT/ASS tracks selected in IINA. The release includes the required extractor; no externalffmpegorffprobeis needed. - Your choice of translation service: Use OpenAI, Claude, DeepSeek, or Ollama. You can also connect services compatible with OpenAI or Claude.
- Playback-first behavior: Translation work never pauses the video or hides the original subtitle.
- Bounded requests: SubTandem translates only nearby cues, limits concurrent work per player window, and caches successful results only for the current video session.
- Persistent translation styling: Customize the font, size, bold and italic styles, text color, border, and background under Subtitle. Color presets and the macOS color picker support transparency, and your style settings are saved for future use.
- Multiple profiles: Save settings for different services and models, edit and test them in place, and switch the active profile. Your choice applies across player windows and is retained after restarting IINA.
- Network routing: Choose whether each profile connects directly or uses the system proxy settings for model refreshes, connection tests, and translation requests. Direct connections bypass the system proxy; new profiles use system proxy settings by default.
- An interface in IINA’s language: On IINA 1.5.0 or later, SubTandem follows IINA’s interface language, covering all 31 language variants shipped with IINA 1.5.0. Controls, status and error messages, accessibility text, the plugin description, and font and color pickers use that language. System-provided picker text may fall back to a language available in macOS.
- macOS 12 or later
- A Mac with Secure Enclave to save or use a nonempty API key; services that do not require one remain supported.
- IINA 1.4.0 or later; automatic interface language requires IINA 1.5.0 or later
- A supported local embedded text subtitle or readable external SRT/ASS/SSA track
- An OpenAI, Claude, DeepSeek, or Ollama service with a model you can use. See the setup guidance below for each service.
SubTandem does not download or start translation models.
The steps and screenshots below use the English interface in IINA 1.5.0 or later. Open Settings → Plugins and choose Get Plugins… or Install Local Package….
Click Get Plugins…, then choose either way to install:
- Enter a repository: Type
janwee-sha/SubTandemin theowner/repofield at the top, then click Install beside it. - Choose from the community plugin list: Select SubTandem from the list, then click Install in its details pane.
Once installation finishes, click Done to return to the plugin manager.
- Open the Releases page and download the latest
SubTandem-X.Y.Z.iinaplgzpackage. - Return to Settings → Plugins and click Install Local Package….
- Select the downloaded
.iinaplgzfile and confirm the installation.
With either method, approve the requested plugin permissions if prompted. After installation, make sure the switch next to SubTandem is on and restart IINA. Then play a video, open IINA's sidebar, and select the SubTandem tab.
SubTandem follows IINA’s application language; restart IINA after changing it. Older hosts, unsupported languages, or unavailable language information use English. A missing translation also falls back to English. There is no separate plugin language setting. The steps below use English control names; your interface may show their localized equivalents.
- Load a local video and select a supported embedded text subtitle or external SRT/ASS subtitle as the primary subtitle in IINA.
- Under Subtitle, select the exact target language. The selected translation service understands each cue's source language inside the translation request; there is no source-language confirmation step.
- Under Translation service, choose New profile and create an OpenAI, Claude, DeepSeek, or Ollama profile. New drafts use Use system proxy settings by default. If the service requires authentication, enter its API key before manually refreshing the model list. Select a returned model, or enter an exact custom Model ID.
- Use Test at the lower left to test the current draft without saving it, then Save it at the lower right and turn on its independent switch. Test may make a billable fixed request, but it sends no playing subtitle text, does not save the entered key, and does not enable the profile.
- Turn on Translate. The original subtitle remains selected in IINA; translated cues appear in SubTandem's overlay. Under Subtitle, use Position to move the overlay from top (
0) to bottom (100). - In the Font, Border, and Background groups, choose the eight text style values. Select a color preset for a direct save, or choose Show Colors… for the macOS color panel; closing it without a change keeps the previous value.
Expand a profile summary to edit it in place. The action row keeps Test on the left and Cancel, Delete, Save on the right; a new draft omits Delete. Test the current values, save the update, and enable the new revision before translating.
- The default API root is
https://api.openai.com. For OpenAI, enter your API key and choose a model available to your account. - Refresh the model list and choose a model, or enter its exact Model ID.
- For an OpenAI-compatible service, replace API root with its API root. The sidebar shows the translation request URL. Leave API key blank if that service accepts requests without one.
- The default API root is
https://api.anthropic.com. For Claude, enter your Anthropic API key and choose a model available to your account. - Refresh the model list and choose a model, or enter its exact Model ID.
- For a Claude-compatible service, replace API root with its API root. Leave API key blank if that service accepts requests without one. You can refresh models, test, save, and enable the profile without a key.
- The default API root is
https://api.deepseek.com. For the official DeepSeek service, enter your API key and choose a model available to your account. - Refresh the model list and choose a model, or enter its exact Model ID. SubTandem does not select a DeepSeek model for you.
- If your service uses a different compatible API root, change API root.
- The default server root is
http://127.0.0.1:11434for Ollama running on your machine. Start Ollama and install a compatible model first. - Refresh the model list and choose an installed model, or enter its exact Model ID.
- For a remote Ollama server, change API root to its server root. Enter an API key only if that server requires one. Test checks the connection, model, and structured-output support.
New profiles use Use system proxy settings by default. Network route controls model refresh, connection tests, and translation; choose Connect directly to bypass the system proxy. Existing profiles keep their saved route, and a route chosen in the current draft is preserved when you switch services and return.
- SubTandem sends only nearby subtitle cue text, the exact target language, opaque cue identifiers, and limited neighboring context to the one profile you explicitly enable. The service understands the source language inside that translation request. It does not send video or audio content.
- The
video-overlaypermission displays the current translation in a local, non-interactive overlay. The overlay does not accept input or enable dragging on the video, does not use network or WebView storage, and is cleared with the playback session. - API keys are stored as authenticated encrypted data in the plugin’s private
credentials.json, alongside profile settings and hardware-bound recovery material. Secure Enclave protects the encryption keys; saving a nonempty API key or using a saved API key fails when the required hardware protection is unavailable. Empty API keys and explicitly clearing one remain supported. API keys stay out of IINA preferences, logs, diagnostics and the plugin package. On the same Mac and user account with valid system keys, newly saved API keys remain available after restarting IINA, restarting the Mac and signing in, or later plugin upgrades, without extra authorization, a master password, or biometric prompts. - Open a profile to edit its saved API key. It starts masked; Show API key reveals it only in the current drawer. Save replaces it with the current input, and saving an empty field clears it. A failed read leaves an editable empty field without changing the saved data. Cancel discards edits.
- Upgrading from the previous plaintext format preserves profile settings and a valid enabled selection but clears saved API keys. Enter them again when needed. SubTandem cleans copies it manages; APFS/Time Machine snapshots, offline copies and other backups can still contain old API keys. Rotate old API keys with your service.
- Back up the complete
credentials.jsonwith its paired recovery material. Recovery requires the original device, user and a valid system key environment, and is not guaranteed even there. Another device or user cannot recover the saved API keys; re-enter them for each profile. - For embedded text subtitles, the bundled extractor reads only the selected stream from the current local media into a session-only temporary SRT. It does not support remote media or image-based subtitles, and removes temporary extraction data after parsing, cancellation, timeout, or shutdown.
- Translations are cached only for the current video session and are cleared when the video changes, playback ends, or the window closes.
- Short tracks, unknown-source text, and text already matching the exact target language are still sent to the enabled service and may incur charges. Your provider applies its own data and content policies; batching and session caching reduce calls but do not guarantee a maximum cost.
SubTandem does not perform audio transcription, OCR or extraction of image-based subtitles, embedded subtitle extraction from remote media, whole-video pretranslation, translation export, cloud sync, or persistent translation caching.
- Select a supported text subtitle: Select a local embedded SubRip/ASS/SSA/
mov_texttrack or an external SRT/ASS track as IINA's primary subtitle. Remote embedded and image-based tracks are not supported; use the displayed state to reselect a text track or retry a failed preparation. - Translation failed: Follow the specific action shown in Session. Depending on the failure, test the profile and check its API root, exact model ID, API key, network route, account limits, or Ollama process. Playback and the original subtitle continue normally.
- An empty profile list after startup: If saved settings cannot load, New profile remains available. Damaged settings may be reset; create and save a new profile to continue. A temporary access problem preserves valid saved profiles, which can reappear when access returns. If saving fails, your draft remains available for retry. A failed read of one API key does not reset the list.
- Credential could not be saved: Install the release package rather than using an incomplete development copy, make sure the plugin data directory is writable, and fully restart IINA.
- No rendered translation: Confirm that the intended profile switch and Translate are both enabled. Playback must also be within the time range of an available translated cue.
- Network or proxy trouble: New profiles use system proxy settings. Check the system proxy configuration, or choose Connect directly for that profile. Save, test, and enable the new revision.
If SubTandem helps you, you can voluntarily buy its creator a coffee through Afdian or Ko-fi.


