Host SPI index & cheat sheet
Plugins call the host through
self.host(that is,self._host_context). This page is navigation + cheat sheet; the detailed contract of each group lives in its own card.
Overview
| Group | Methods | Details |
|---|---|---|
| Captions & translation | feed_direct_caption · feed_caption · translate · translate_batch | Captions & translation |
| Config & data | get_plugin_config · set_plugin_config_value · save_plugin_config · get_plugin_data_dir · get_plugin_kv · set_plugin_kv · delete_plugin_kv | Config & private data |
| Session & state | get_recent_conversation · get_history_as_text · get_pipeline_state · get_active_provider · list_installed_plugins · plugin_dir · has_plugin · runtime_dir · has_runtime · get_app_version · get_locale · log | Session & host state |
| Hotkeys | register_plugin_hotkey · unregister_plugin_hotkeys · get_plugin_hotkeys | Global hotkeys |
| Models | list_model_artifacts · inspect_model_artifact · download_model_artifact | Model artifacts |
| Events | subscribe_event · unsubscribe_event · unsubscribe_all_events | Event bus |
| Speech & feedback | speak · stop_speak · is_speaking · show_toast · show_error · set_window_excluded_from_capture · set_copilot_visible · toggle_copilot_window | Speech & feedback |
| Floating windows | create_plugin_window · show_plugin_window · close_plugin_window · close_plugin_windows · move_plugin_window · resize_plugin_window · set_plugin_window_flags · list_plugin_windows · get_plugin_window | Plugin windows |
| Files & progress | pick_file · pick_files · pick_folder · pick_save_file · begin_progress · update_progress · end_progress · cancel_progress · is_progress_cancelled · get_progress | File pickers & long tasks |
Instance powers provided by BasePlugin
Subclasses can use these directly:
| Member | Description |
|---|---|
self.host | Host SPI entry point |
self.manifest / self.id / self.name / self.plugin_type | Manifest metadata |
self._config | Current config dict (maintained by initialize / update_config) |
initialize(config) / shutdown() / update_config(new_config) | Lifecycle hooks |
handle_action(action, params) | Dispatches to action_<action>(**params) |
emit_event(name, payload) | Plugin → front-end events |
handle_host_event(name, payload) | Host → plugin events (overridable) |
subscribe_host_event(name, cb) / unsubscribe_host_event(name) | Instance-level event subscriptions |
get_data_dir() | Private data directory (equivalent to host.get_plugin_data_dir(id)) |
show_toast(msg, level, timeout_ms) | Convenience method |
run_in_background(target, *args, **kwargs) | Run slow work on a daemon thread |
model_artifacts() / check_ready() / requires_hf_runtime | See Model artifacts |
ensure_loaded() / wait_async_init() | Lazy startup and async initialize convergence, see Local-service contract |
TTS-only: supports_voice_clone / supports_speed / list_voices() / register_voice() / remove_voice() | See tts |
Naming conventions
- Use snake_case only (new code). Camel-case aliases (
feedDirectCaption,registerPluginHotkey,getPluginConfig…) coexist with the canonical names for at least one minor version, kept only for compatibility with old plugins. - Any method on the bridge that is not listed in these docs is unstable — don't use it.
- For the full method signatures,
HostProtocolinsrc/transbox/plugins/base.pyis authoritative.
Related
- Provider signatures & data types
- Threading contract — which API may be called from which thread
- Host implementation status