Subtitle Edit

the subtitle editor :)

Plugins (Subtitle Edit 5)

Subtitle Edit 5 plugins are standalone executables that communicate with Subtitle Edit through JSON files. Subtitle Edit writes a request file, launches the plugin process, waits for it to exit, then reads a response file the plugin wrote. The plugin is free to show its own user interface while it runs.

This model is a clean break from the Subtitle Edit 4 plugin API (in-process WinForms DLLs), which cannot run on the cross-platform Avalonia build. SE4 plugins are not compatible with SE5 and must be ported.

Status: the JSON contract, the host-side runner/catalog, the Plugins menu, the plugin manager (Plugins → Manage plugins… — enable/disable/remove and open the plugins folder), and the online installer (Get plugins online… — download and update plugins from the index) are implemented. Installing, enabling, disabling, and removing plugins update the Plugins menu live (no restart needed). A startup update notification is still to come.

The Plugins menu is shown by default but can be hidden via Options → Settings → Appearance → Show Plugins menu. The menu must be enabled there to run or manage plugins from the main window.

How a plugin runs

  1. The user picks the plugin from a Subtitle Edit menu.
  2. Subtitle Edit writes a request.json to a fresh temp folder.
  3. Subtitle Edit launches the plugin executable with the request file path as the first command-line argument.
  4. The plugin reads the request, does its work (optionally showing its own window), and writes a response.json to the path given in the request (responseFilePath).
  5. The plugin exits with code 0.
  6. Subtitle Edit reads the response. On ok it creates an undo point and replaces the subtitle; on cancelled it does nothing; on error it shows the message.
  7. Subtitle Edit deletes the temp folder.

Cancelling from Subtitle Edit kills the plugin process. A non-zero exit code, a missing response file, or invalid JSON is reported to the user as an error and the subtitle is left unchanged.

Installation layout

Each plugin lives in its own folder under the Plugins directory in the Subtitle Edit data folder (next to Settings.json; in portable installs that is the Subtitle Edit program folder). Every plugin folder must contain a plugin.json manifest:

Plugins/
  MyPlugin/
    plugin.json
    MyPlugin.exe          (Windows)
    MyPlugin              (Linux/macOS)
    icon.png              (optional)

Install a plugin either by copying its folder here manually, or via Plugins → Manage plugins… → Get plugins online…, which downloads it from the plugin index (see below).

The online plugin index

Get plugins online… reads a JSON index and offers each listed plugin for download. The index lives at the URL in PluginConstants.OnlineIndexUrl (https://raw.githubusercontent.com/SubtitleEdit/plugins/main/se5-plugins.json):

{
  "plugins": [
    {
      "name": "Uppercase Selected Lines",
      "description": "Converts the text of the selected lines to UPPERCASE.",
      "version": "1.0.0",
      "author": "Jane Doe",
      "url": "https://github.com/example/se-uppercase-plugin",
      "date": "2026-05-01",
      "minSeVersion": "5.0.0",
      "downloads": {
        "win-x64":     "https://github.com/example/se-uppercase-plugin/releases/download/v1.0.0/Uppercase-win-x64.zip",
        "win-arm64":   "https://github.com/example/se-uppercase-plugin/releases/download/v1.0.0/Uppercase-win-arm64.zip",
        "linux-x64":   "https://github.com/example/se-uppercase-plugin/releases/download/v1.0.0/Uppercase-linux-x64.zip",
        "linux-arm64": "https://github.com/example/se-uppercase-plugin/releases/download/v1.0.0/Uppercase-linux-arm64.zip",
        "osx-x64":     "https://github.com/example/se-uppercase-plugin/releases/download/v1.0.0/Uppercase-osx-x64.zip",
        "osx-arm64":   "https://github.com/example/se-uppercase-plugin/releases/download/v1.0.0/Uppercase-osx-arm64.zip"
      }
    }
  ]
}

plugin.json (manifest)

The manifest lets Subtitle Edit list the plugin in its menus without launching it.

{
  "apiVersion": 1,
  "name": "Uppercase Selected Lines",
  "description": "Converts the text of the selected lines to UPPERCASE.",
  "version": "1.0.0",
  "author": "Jane Doe",
  "url": "https://github.com/example/se-uppercase-plugin",
  "menu": "Tools",
  "shortcut": "Control+Shift+U",
  "minSeVersion": "5.0.0",
  "icon": "icon.png",
  "executables": {
    "windows": "MyPlugin.exe",
    "linux": "MyPlugin",
    "macos": "MyPlugin"
  }
}
Field Required Notes
apiVersion yes JSON contract version. Currently 1.
name yes Menu text.
description no Shown in the plugin manager.
version no The plugin’s own version.
author no  
url no Project/home page.
menu no Intended menu group: Tools (default), File, Sync, Translate, SpellCheck, or Assa. Currently every plugin is listed under a single top-level Plugins menu; menu-based routing is planned.
shortcut no Suggested keyboard shortcut.
minSeVersion no Minimum supported Subtitle Edit version.
icon no Icon file name, relative to the plugin folder.
executables yes* Native executable file names per OS, relative to the plugin folder.
runtime no Set to "dotnet" to launch via the shared .NET runtime instead of a native exe.
entry no Entry .dll (relative to the plugin folder), used with runtime: "dotnet".

* Provide either executables or runtime + entry. A dotnet plugin is launched as dotnet <entry> <requestFilePath>.

request.json (Subtitle Edit → plugin)

{
  "apiVersion": 1,
  "requestType": "run",
  "responseFilePath": "C:\\Users\\...\\Temp\\SubtitleEditPlugins\\<id>\\response.json",
  "tempDirectory": "C:\\Users\\...\\Temp\\SubtitleEditPlugins\\<id>",
  "pluginDataDirectory": "C:\\Users\\...\\Subtitle Edit\\Plugins\\Data\\Uppercase Selected Lines",
  "subtitle": {
    "format": "Advanced Sub Station Alpha",
    "fileName": "C:\\videos\\episode01.ass",
    "native": "[Script Info]\n...full subtitle in its original format...",
    "subRip": "1\n00:00:01,000 --> 00:00:03,000\nHello world\n\n..."
  },
  "subtitleEncoding": "UTF-8 with BOM",
  "selectedIndices": [3, 4, 5],
  "videoFileName": "C:\\videos\\episode01.mkv",
  "frameRate": 23.976,
  "videoDurationSeconds": 1432.5,
  "videoPositionSeconds": 142.0,
  "videoWidth": 1920,
  "videoHeight": 1080,
  "uiLanguage": "English",
  "theme": "Dark",
  "themeColors": {
    "isDark": true,
    "backgroundColor": "#FF212121",
    "foregroundColor": "#FFDCDCDC",
    "accentColor": "#631E90FF",
    "backgroundColorLighter": "#FF262626",
    "backgroundColorHeader": "#FF303030",
    "bookmarkColor": "#FFFFD700"
  },
  "seVersion": "5.0.0",
  "settings": { "lastUsedOption": true },
  "settingsVersion": 2
}

response.json (plugin → Subtitle Edit)

Write this file to responseFilePath before exiting with code 0.

{
  "apiVersion": 1,
  "status": "ok",
  "message": "Converted 3 lines to uppercase.",
  "subtitle": {
    "format": "SubRip",
    "native": "1\n00:00:01,000 --> 00:00:03,000\nHELLO WORLD\n\n..."
  },
  "settings": { "lastUsedOption": true },
  "settingsVersion": 2,
  "undoDescription": "Uppercase Selected Lines 1.0.0"
}
status Effect
ok Subtitle Edit re-parses subtitle.native (as subtitle.format), makes an undo point, and replaces the current subtitle.
cancelled Nothing changes. Use this when the user closed your plugin’s window.
error message is shown to the user; the subtitle is left unchanged.

Notes for plugin authors