Using Plugins
StudioBrain’s plugin system lets you extend the editor with custom panels, integrations, and tools. Plugins run in sandboxed iframes and communicate with the host application through a typed message protocol. This guide covers installing, configuring, and managing plugins as an end user.
Plugin System Overview
Plugins add functionality to the entity editor. Each plugin can provide one or more panels that appear as component blocks within entity edit pages. Plugins can:
- Display custom UI alongside entity fields
- Read entity data (with permission)
- Suggest changes to entity fields
- Integrate with external services (Jira, Discord, Google Sheets, etc.)
- Provide specialized tools (PDF export, version history, voice generation, etc.)
Plugins are isolated in iframes, so a misbehaving plugin cannot break the main application.
Built-in Plugins
StudioBrain ships with 22 built-in plugins covering a range of use cases:
Creative Tools
| Plugin | Description |
|---|---|
| ComfyUI Workflows | Run ComfyUI image generation workflows from within the entity editor |
| Voice Forge | Generate character voice samples using AI voice synthesis |
| Music Gen | Generate background music and audio tracks |
| LoRA Trainer | Train custom LoRA models from entity reference images |
Export & Publishing
| Plugin | Description |
|---|---|
| PDF Exporter | Export entities or collections as formatted PDF documents |
| Showrunner Exporter | Export entities in showrunner-compatible format for TV production pipelines |
| UEFN Exporter | Export entities for Unreal Editor for Fortnite |
| Unity Exporter | Export entities in Unity-compatible data format |
| Unreal Exporter | Export entities for Unreal Engine projects |
Integrations
| Plugin | Description |
|---|---|
| Jira Sync | Sync entity production status with Jira issues |
| Discord Poster | Post entity updates and previews to Discord channels |
| Google Sheets Sync | Sync entity data to and from Google Sheets |
| Notion Sync | Sync entities with Notion databases |
| Obsidian Vault | Export entities to Obsidian-compatible Markdown vault format |
| Webhook Automations | Trigger custom webhooks on entity events |
| YouTube Manager | Manage video content associated with entities |
| Social Publisher | Publish entity content to social media platforms |
Project Management
| Plugin | Description |
|---|---|
| Kanban Board | Visual kanban board for tracking entity production status |
| Time Tracker | Track time spent editing entities |
| Version History | View and restore previous versions of entity files |
Development
| Plugin | Description |
|---|---|
| Blender Bridge | Send entity data to Blender for 3D asset creation |
| Hello World | Example plugin for developers learning the plugin system |
Installing Plugins
Enabling Built-in Plugins
Built-in plugins come pre-installed but may be disabled by default. To enable one:
- Go to Settings > Plugins.
- Find the plugin in the list.
- Click the toggle to Enable it.
- The plugin is now available in entity editors.
Where Plugins Appear
Enabled plugins appear in the entity editor as component blocks. You can control where they show up:
- Layout Designer — Drag plugin blocks into specific sections of the entity layout.
- Plugin settings — Configure which entity types the plugin panel appears on (e.g., Voice Forge only on Characters).
If a plugin is enabled but not placed in the layout, it typically appears at the bottom of the entity editor or in a dedicated plugins tab.
Configuring Plugins
Each plugin may have its own configuration options. Access them from Settings > Plugins, then click the gear icon next to the plugin name.
Common Configuration Options
| Setting | Description |
|---|---|
| Entity type filter | Which entity types the plugin panel appears on. Some plugins only make sense for certain types (e.g., Voice Forge for Characters). |
| API credentials | Some plugins require external API keys or OAuth connections (e.g., Jira Sync needs a Jira API token, Discord Poster needs a webhook URL). |
| Display mode | Panel size (compact, standard, expanded) and whether the panel is collapsed by default. |
| Auto-refresh | Whether the plugin panel refreshes automatically when entity data changes. |
Per-Entity-Type Settings
Some plugins behave differently depending on the entity type:
- ComfyUI Workflows might show different workflow presets for Characters vs. Locations.
- PDF Exporter might use different templates for different entity types.
- Kanban Board might group entities differently based on type-specific production status fields.
Configure these in the plugin’s settings under the Entity Type Configuration section.
The Iframe Sandbox
Plugins run in sandboxed iframes for security and stability. This means:
What Plugins CAN Do
- Display custom HTML, CSS, and JavaScript UI
- Read the current entity’s data (frontmatter fields and Markdown body)
- Suggest changes to entity fields (the user must approve)
- Make HTTP requests to their own backend services
- Store plugin-specific settings in the plugin configuration
- Listen for entity change events
What Plugins CANNOT Do
- Access the host application’s DOM directly
- Read other entities without going through the message protocol
- Modify entity data without user approval
- Access the local filesystem
- Access other plugins’ data
- Execute code outside their iframe
- Access StudioBrain’s database directly
Message Protocol
Plugins communicate with StudioBrain through a typed postMessage protocol. The protocol supports:
- Entity data requests — Plugin asks for current entity data
- Field update suggestions — Plugin suggests a change to a field
- Navigation requests — Plugin asks to navigate to another entity
- Notification messages — Plugin sends toast notifications to the user
- Settings access — Plugin reads its own configuration
For developers building plugins, see the Plugin Iframe Protocol reference.
Managing Plugin Data
Plugin State
Plugins can store state in StudioBrain’s plugin settings database. This state persists across sessions and is specific to each plugin.
- Global settings — Plugin-wide configuration (API keys, display preferences)
- Per-entity state — Data the plugin stores for individual entities (e.g., Time Tracker’s logged hours)
Exporting Plugin Data
Plugin data is included in StudioBrain’s data export (Settings > Data Export). The export includes:
- Plugin configurations
- Plugin-specific state data
- Any plugin-generated files stored in the project directory
Plugin Data and Sync
When cloud sync is enabled, plugin configurations sync across devices. However, plugin runtime state (like Time Tracker hours) may or may not sync, depending on the plugin’s implementation.
Troubleshooting Plugins
Plugin panel is blank or not loading
- Check that the plugin is enabled in Settings > Plugins.
- Check your internet connection if the plugin loads external resources.
- Try disabling and re-enabling the plugin.
- Check the browser console (F12 > Console) for error messages from the plugin iframe.
Plugin is not showing on the entity page
- Verify the plugin is enabled for the current entity type in the plugin’s settings.
- Check the Layout Designer to see if the plugin block has been placed in the layout.
- If the plugin was recently enabled, try refreshing the page.
Plugin is showing outdated data
- Switch to a different entity and back.
- Click the refresh button on the plugin panel (if available).
- Save the entity to trigger a data update event.
Plugin integration is not connecting
For plugins that connect to external services (Jira, Discord, Google Sheets):
- Verify the API credentials in the plugin’s settings.
- Check that the external service is accessible from your network.
- Test the connection using the plugin’s Test Connection button (if available).
- Check the external service’s API status page for outages.
Plugin is causing performance issues
- Disable the plugin in Settings > Plugins.
- If performance improves, the plugin may be making excessive API calls or rendering heavy content.
- Check the plugin’s settings for options to reduce refresh frequency or content loading.
- Report the issue to the plugin author or StudioBrain support.
Uninstalling Plugins
Disabling vs. Removing
- Disable — Turns off the plugin but preserves its configuration and data. You can re-enable it later without reconfiguring.
- Remove — Deletes the plugin’s configuration and any plugin-specific data. Entity fields that the plugin wrote to are preserved in the YAML, but the plugin panel will no longer render.
How to Remove a Plugin
- Go to Settings > Plugins.
- Find the plugin and click the options menu (three dots).
- Select Remove Plugin.
- Confirm the removal.
Built-in plugins can be disabled but not fully removed — they are part of the StudioBrain installation.
Next Steps
- Getting Started — Overview of the application
- Managing Entities — Entity editing and the component block system
- Settings & Configuration — Plugin and theme configuration
- Plugin Iframe Protocol — Developer reference for building plugins