TransBox Plugin Development Docs
For: MOD authors / engineers integrating private ASR, MT or TTS / AI agents that implement plugins straight from these docs.
These docs are organised as knowledge cards: one topic per page, every fact written exactly once, other pages only link. Editing the docs? Find the single card that owns the topic — never repeat the same fact across pages.
The single source of truth for the contract is the client source code (src/transbox/plugins/, src/transbox/ui/bridge/). If a page disagrees with the source, the source wins; please report mismatches in the Plugin Hub.
This directory mirrors
docs/plugin-dev/in the client repository — same structure, same content. The Plugin Specification page lives at its original URL and keeps only copy-paste assets.
Five-minute quick start
- Copy an official example folder (
extensions/example_glossary_gaming/,extensions/community_select_translate/,extensions/community_cloud_mimo_asr/, …). - Edit
id/nameinmod.json(idmust be globally unique, e.g.myteam.mt.deeplx; never use thebuiltin.*segment). - Drop it into a scan directory → Settings → Extension Workshop → Refresh → flip the enable switch.
- Engine types (
asr/mt/tts) also need to be selected as the active engine on their settings page; data types (theme/glossary/i18n) take effect as soon as they are enabled.
Details: Quick start.
Doc map
Getting started
| Card | In one line |
|---|---|
| Quick start | What the smallest working plugin looks like |
| Layout & mod.json | What a plugin folder must contain; every field lives here |
| Runtime architecture & lifecycle | Scan roots / dual-track / enable-disable / mutual exclusion |
By plugin type
| Card | In one line |
|---|---|
| Type overview & selection | 12 type values — which one do I need? |
| glossary | Zero code, just terms.json |
| theme | theme.json token theming + caption bar parameters |
| UI extensions (QML) | Replace backplate / VU meter / caption view |
| middleware | Intercept at any pipeline stage |
| asr | Wire up a private speech-recognition engine |
| mt | Wire up DeepL / an LLM / local translation |
| tts | Voice list / voice cloning / streaming / speed |
| interpretation | End-to-end SI (bypasses local ASR→MT→TTS) |
| assistant | Interview copilot / answering overlay |
| tool | Select-to-translate / global-hotkey tools |
| i18n | Full UI language pack + self-contained plugin strings |
| caption_extractor | Add caption extraction for another video site |
Host SPI (what plugins call on the host)
| Card | In one line |
|---|---|
| SPI index & cheat sheet | Every method at a glance + base-class powers |
| Captions & translation | Push text into the caption chain / call the active MT engine |
| Config & private data | This plugin's config / KV / data directory |
| Session & host state | History context / pipeline state / installed plugins |
| Global hotkeys | Declarative hotkeys and runtime registration |
| Model artifacts | Declare weight repos; the host downloads and checks readiness |
| Event bus | Plugin ↔ host events and the standard event table |
| Speech & feedback | speak / toast / capture exclusion |
| Plugin windows | Multi-instance, always-on-top, click-through, capture-safe QML windows |
| File pickers & long tasks | System file dialogs / cancellable progress |
Provider contracts (mandatory signatures)
| Card | In one line |
|---|---|
| Capabilities & read-only contract | How the host asks about capabilities without starting your service |
| Provider signatures & data types | MT / ASR / TTS signatures + Transcript and friends |
| Local-service engine contract | Lazy startup / ports / devices / child processes / persistence |
Config & UI
| Card | In one line |
|---|---|
| config_schema | Field types, visibility rules, presets, compute device |
| Custom settings view | When you need "Get a key" / "Test connection" |
| UI slots | Replaceable slot list + background-slot guidelines |
Debug & publish
| Card | In one line |
|---|---|
| Hot debugging | Edit → refresh → read the log |
| Packaging & size limit | Export a zip; the 20 MB hard limit and your options |
| Publish channels | Steam Workshop / web Plugin Hub |
| Prerequisite plugins | requires_plugins + locating directories by id |
| Host runtimes | requires_runtime; don't ship binaries in the package |
Reference
| Card | In one line |
|---|---|
| Example library | Which folder to copy for each type |
| Language codes & translatable languages | target_langs vs supported_langs, normalization, the 33-language table |
| Threading contract | Which API may be called from which thread |
| Runtime environment & red lines | Bundled libs / libs vendor / no pip at runtime |
| Compatibility & version gates | target_app_version (required), naming migration, min_app_version, retired types |
| Host implementation status | What is actually exposed (don't guess non-existent hooks) |
Find a page by goal
| I want to… | Read these |
|---|---|
| Get a minimal plugin running | Quick start → Layout & mod.json |
| Wire up a cloud ASR / MT / TTS | Type overview → the matching type card → config_schema |
| Declare which languages an MT model can translate into | mt → Language codes & translatable languages |
| Wire up a local inference service (llama-server etc.) | Local-service engine contract (required reading) → Model artifacts |
| Work on UI / theming | UI slots → theme |
| Add a glossary / language pack (no code) | glossary / i18n |
| Have an AI write the plugin | The "hand it to an AI" prompt in Quick start + Layout & mod.json + the matching type card |
| Ship it | Packaging & size limit → Publish channels |
The three most common traps
Local-service plugins (those that spawn
llama-server/tts-server/ a custom HTTP service) must read Local-service engine contract first. All three traps below are user-visible bugs.
- Never start a local service in
initialize()— the host performs read-only queries when the settings page is opened or model/voice status is checked. The old pattern makes users wait seconds and burn gigabytes of VRAM just for opening a settings page. Start the service inensure_loaded()or at the request entry point. - Don't default to ports 8080/8081/8082 — in practice they are often taken by Steam's
steamwebhelperand similar. Use a high, uncommon range and fall back to the next free port. - Persist server-side voice registries yourself — if they only live in memory, users must re-register after every restart (measured:
tts-serverbehaves exactly like this).
Two more frequent issues:
- Never hard-code a sibling plugin's directory name — workshop installs name the folder after the plugin id. Use
host.plugin_dir(id)(see Prerequisite plugins). - Don't ship large binaries or models inside the package — the upload channel caps at 20 MB. Binaries go through Host runtimes; weights go through Model artifacts.
Old Plugin Specification sections → new cards
The Plugin Specification page (1700+ lines) has been split into the cards above. To avoid writing the same fact twice, that page now keeps only copy-paste code assets; every other section points at a card:
| Plugin Spec section | Where it lives now |
|---|---|
| §0 Direct Prompt for AI Agents | Stays on the page (§0 Prompt-and-Go) |
| §1 Directory Structure | Layout & mod.json |
§2 mod.json Field Table | Layout & mod.json |
§3 Supported type Values | Type overview & selection |
§3.1 caption_extractor | Caption extraction for video sites |
§4 entrypoint Rules | Layout & mod.json |
| §5.1 Glossary | glossary |
| §5.2 Theme | theme |
| §5.3 i18n (language pack) | i18n |
| §5.4 Plugin i18n contributions | i18n |
| §5.5 tool | tool |
§6 config_schema | config_schema |
| §6.2 QML consumption & hot reload | UI extensions (QML) |
| §6.3 Cloud custom settings view | Custom settings view |
| §7.0 Standalone Development Stub | Stays on the page (for developing without host source) |
| §7.1–7.9 Base classes / data types / Host SPI | Provider signatures & data types + SPI index & cheat sheet |
| §7.10 Local model artifacts & external runtime | Model artifacts |
§7.11 requires_runtime | Host runtimes |
| §8 Minimal Runnable Templates (7) | Stays on the page (complete code you can copy and rename) |
| §9 Local hot debugging | Hot debugging |
| §10 In-app publishing & updates | Packaging & size limit + Publish channels |
| §11 Self-contained plugin locales | i18n |
| §12 Runtime environment & hard rules | Runtime environment & red lines |
| §13 Official example index | Example library |
| §14 Implementation checklist for AI agents | Stays on the page |
| §15 UI Slots (summary) | UI slots + QML slots & HostContext |
Related docs (other Developer Centre pages)
| Page | Contents |
|---|---|
| Plugin Specification | Prompt-and-Go template / standalone SDK stub / 7 complete templates / AI checklist |
| Client internals | Python class loading, config assembly and the security model (plugin contracts live in this card tree) |
| QML slots & HostContext | Slot properties, hostContext subsystems, settings_view injection |
| Local source & dev environment | Client source setup (uv / Python 3.11–3.12) |
| Workshop & self-publish | Export a zip, Steam upload, local extension-directory distribution |
| Web Plugin Hub (author/ops manual) | Author-centre uploads, subscriptions, review and operations |
The core team reserves the right to evolve this specification. Please open a GitHub issue for questions.